In questo esempio ipotizziamo di voler inserire o aggiornare un curriculum.

Comincia creando la vista per la modifica:

1. Crea una vista di tipo maschera che abbia Curricula come tabella di riferimento
2. Modifica la vista e assegna per esempio il tag name Edit.API
3. Aggiungere alla vista i campi che si intende modificare
4. Esponi la vista come API

Adesso crea un utente con cui poter usare le API:

1. Crea un utente. Questo è l'utente con cui l'API accederà alla piattaforma
2. Assegna i permessi all'utente. Assegnare solo le autorizzazioni per la scrittura dei curricula

Puoi anche usare un utente esistente: ovviamente le autorizzazioni saranno quelle dell'utente che hai scelto. Quindi, se scegli un utente Administrator la chiamate API avranno accesso a tutti i dati della piattaforma.

 

 

REST V3 - Scrittura

In questa versione dell'API il metodo da utilizzare è il POST.

Adesso puoi recuperare la URL per accedere all'API:

1. Dalla gestione delle view copia la URL del API REST

Prima di chiamare questa url è necessario ottenere un token JWT come spiegato nell’articolo precedente al punto 1.

Parametro	Nome	Descrizione	Tipo
header	Token (required)	Token generato precedentemente da AltamiraHRM	string
header	environment	Restituisce i dati nel formato corrispondente a quello ricevuto.    Valori disponibili : Frontend, Mobile, Api   Valore predefinito : Api	string

 

Il parametro Token deve essere inviato come header.

Adesso è necessario costruire il Body della richiesta da mandare con il metodo POST.

L’oggetto JSON che bisogna dovrà contenere le seguenti proprietà:

Proprietà	Descrizione	Tipo
data	Array contenente gli oggetti da inserire o modificare	Array di oggetti

Gli oggetti da includere nella proprietà data dovranno avere come proprietà i tagname dei campi utilizzati nella vista creata per la scrittura: nel nostro esempio Curriculum.Edit.API, fatta eccezione per il primo campo che rappresenta la chiave primaria della  tabella a cui si riferisce la view. Il suo nome è sempre "id" ed è sempre obbligatorio. Nel caso del nuovo deve essere sempre passato con il valore 0.

Un esempio per inserire un nuovo cv potrebbe essere il seguente:

{  
  "data": [    
    {
      "id": 0,
      "CV_CustomerID": 1,
      "CV_Name": "Mario",
      "CV_Surname": "Rossi",
      "CV_DateOfBirth": "1990-01-01T00:00:00.000Z",
      "CV_RegionProvince": "167402847"    
    }  
  ]
}

AltamiraHRM risponderà con un output strutturato come di seguito:

{
  "Curriculum.Edit.API": [
    {
      "id": id_value,
      "CV_CustomerID": 1,
      "CV_Name": "Mario",
      "CV_Surname": "Rossi",
      "CV_DateOfBirth": "1990-01-01T00:00:00.000Z",
      "CV_RegionProvince": "167402847"
    }
  ],
  "Result": [
    {
      "status": "Inserted",
      "statusMessage": "Item added successfully",
      "details": []
    }
  ]
}

Esempio di modifica curriculum esistente

In questo esempio andremo a modificare la data di nascita del curriculum utilizzando come chiave primaria l'id (In questo esempio col valore "id_value", che dovrà essere un numero intero), in questo caso il suo valore è obbligatorio e dovrà essere diverso da 0.

La URL del nostro endpoint (la stessa del precedente esempio) dovrà essere chiamato utilizzando il metodo da utilizzare è il PUT.

Un esempio per modificare un cv potrebbe essere il seguente:

{  
  "data": [    
    {
      "id": id_value,
      "CV_CustomerID": 1,
      "CV_Name": "Mario",
      "CV_Surname": "Rossi",
      "CV_DateOfBirth": "1990-01-01T00:00:00.000Z",
      "CV_RegionProvince": "167402847"    
     }  
  ]
}

E' possibile utilizzare lo stesso URL per poter modificare inserire ed eliminare (da chiamare rispettivamente con i metodi POST, PUT e DELETE) i Curricula, la chiamata verifica all'occorrenza l'esistenza di un record con la chiave primaria ("id") specificata, da errore quando il suo valore non corrisponde a nessun record esistente o meno in relazione al metodo utilizzato.

 

 

REST V2 - Scrittura

In questa versione dell'API il metodo da utilizzare è il POST.

Adesso puoi costruire la URL per accedere all'API:

1. Dalla gestione dell'utente copia la URL del API REST
2. Sostituisci il marcatore VIEW_TAGNAME con il tag name Edit.API

Per esempio, se la URL del API REST è

• https://platform.altamirahrm.com/api/v1/altamira/REST/VIEW_TAGNAME

allora la URL per invocare il metodo Curriculum.Edit.API è:

• https://platform.altamirahrm.com/api/v2/REST/Curriculum.Edit.API

Prima di chiamare questa url è necessario ottenere un token JWT come spiegato nell’articolo precedente al punto 1.

Parametro	Nome	Descrizione	Tipo
header	Token (required)	Token generato precedentemente da AltamiraHRM	string

 

Il parametro Token deve essere inviato come header.

Adesso è necessario costruire il Body della richiesta da mandare con il metodo POST.

L’oggetto JSON che bisogna dovrà contenere le seguenti proprietà:

Proprietà	Descrizione	Tipo
data	Array contenente gli oggetti da inserire o modificare	Array di oggetti
Keys	Campi da utilizzare come chiavi primarie	Array di stringhe
KeySecondary	Campi da utilizzare come chiavi secondarie	Array di stringhe

Gli oggetti da includere nella proprietà Data dovranno avere come proprietà i tagname dei campi utilizzati nella vista creata per la scrittura: nel nostro esempio Curriculum.Edit.API 

Un esempio per inserire un nuovo cv potrebbe essere il seguente:

{  
  "data": [    
    {
      "CV.CustomerID": 1,
      "CV.Name": "Mario",
      "CV.Surname": "Rossi",
      "CV.DateOfBirth": "1990-01-01T00:00:00.000Z",
      "CV.RegionProvince": "167402847"    
    }  
  ],    
  "Keys": [],    
  "KeysSecondary": []
}

AltamiraHRM risponderà con un output strutturato come di seguito:

{
  "Curriculum.Edit.API": [
  {
    "CV.CVID": 172620789,
    "CV.CustomerID": 1,
    "CV.Name": "Mario",
    "CV.Surname": "Rossi",
    "CV.DateOfBirth": "1990-01-01T00:00:00.000Z",
    "CV.RegionProvince": "167402847"
  }
],
"Result": [
  {
    "Status": "Inserted",
    "StatusDescription": "Info. No primary keys have been set: the data will be inserted and no updates will be performed.\r\n"
  }
 ]
}

Esempio di modifica curriculum esistente

In questo esempio andremo a modificare la data di nascita del curriculum utilizzando come chiave primaria il CustomerID (In questo caso con il valore "1").
Per far questo andremo a mettere nel parametro Keys il CV.CustomerID

Un esempio per inserire un nuovo cv potrebbe essere il seguente:

{  
  "data": [    
    {
      "CV.CustomerID": 1,
      "CV.Name": "Mario",
      "CV.Surname": "Rossi",
      "CV.DateOfBirth": "1990-01-01T00:00:00.000Z",
      "CV.RegionProvince": "167402847"    
     }  
  ],    
  "Keys": ["CV.CustomerID"],    
  "KeysSecondary": []
}

E' possibile utilizzare lo stesso URL per poter modificare ed inserire nuovi Curricula, la chiamata verifica l'esistenza di un record con la chiave primaria specificata, se presente lo aggiorna altrimenti lo crea.

 

 

REST v1 - Scrittura

Per questa versione dell'API il metodo da utilizzare è il GET.

Adesso puoi costruire la URL per accedere all'API:

1. Dalla gestione dell'utente copia la URL del API REST
2. Sostituisci i marcatori YOUR_APIKEY con la chiave API che hai generato e VIEW_TAGNAME con il tag name Curriculum.Edit.API

Per esempio, se la URL del API REST è

• https://platform.altamirahrm.com/api/v1/altamira/REST/VIEW_TAGNAME?ApiKey=YOUR_APIKEY

allora la URL per invocare il metodo Curriculum.Edit.API è:

• https://platform.altamirahrm.com/api/v1/altamira/REST/Curriculum.Edit.API?ApiKey=0123456789012345

Ovviamente la chiave API è solo un esempio. Per maggiore sicurezza puoi mettere la chiave API nella header HTTP al posto della URL. Il nome della header è ApiKey.

A questa URL andranno aggiunti altri parametri:

• Operation: Impostare al valore si Upsert per poter modificare o inserire un nuovo record
• Keys (opzionale): Sono le chiavi primarie su cui filtrare per estrarre il record da modificare.
  Inserire il tag name del campo. E' possibile impostare più chiavi primarie utilizzando la virgola come separatore.
  Se non specificato verrà sempre creato sempre un nuovo record 
• CreateListItems (opzionale): di default impostato a false. Serve per aggiungere elementi alle liste di codifica
• Specificare come parametri tutti i campi del record (Curriculum) che si vuole modificare con il relativo valore (utilizzare i tag name come nome del parametro).
  Per l'elenco corretto dei tag name potete far riferimento all'URL del WSDL
  https://platform.altamirahrm.com/api/v2/altamira/SOAP/WSDL/YOUR_APIKEY

 

Esempio di inserimento nuovo curriculum

https://platform.altamirahrm.com/api/v1/altamira/REST/Curriculum.Edit.API?ApiKey=0123456789012345&Operation=Upsert&CV.Name=Mario&CV.Surname=Rossi&CV.DateOfBirth=1990-01-01T00:00:00&CV.CustomerID=1&Regions.RegionProvince=Milano

L'output che sarà strutturato così:

{
"Curriculum.Edit.API": [
{
"CV.CVID": 172620789,
"CV.CustomerID": 1,
"CV.Name": "Mario",
"CV.Surname": "Rossi",
"CV.DateOfBirth": "1990-01-01T00:00:00.000Z",
"CV.RegionProvince": "167402847"
}
],
"Result": [
{
"Status": "Inserted",
"StatusDescription": "Info. No primary keys have been set: the data will be inserted and no updates will be performed.\r\n"
}
]
}

 

Esempio di modifica curriculum esistente

In questo esempio andremo a modificare la data di nascita del curriculum utilizzando come chiave primaria il CustomerID (In questo caso con il valore "1").
Per far questo andremo a mettere nel parametro Keys il CV.CustomerID

https://platform.altamirahrm.com/api/v1/altamira/REST/Curriculum.Edit.API?ApiKey=0123456789012345&Operation=Upsert&Keys=CV.CustomerID&CV.DateOfBirth=1995-10-25T00:00:00&CV.CustomerID=1

{
"Curriculum.Edit.API": [
{
"CV.CVID": 172620789,
"CV.CustomerID": 1,
"CV.Name": "Mario",
"CV.Surname": "Rossi",
"CV.DateOfBirth": "1995-10-25T00:00:00.000Z",
"CV.RegionProvince": "167402848"
}
],
"Result": [
{
"Status": "Updated",
"StatusDescription": "Filter to determine if the row exists: (CV.CustomerID = 1)\r\n - Found row with primary key CV.CVID: 172620789.\r\n"
}
]
}

Esempio di inserimento/modifica tramite unico URL

E' possibile utilizzare lo stesso URL per poter modificare ed inserire nuovi Curricula, la chiamata verifica l'esistenza di un record con la chiave primaria specificata, se presente lo aggiorna altrimenti lo crea.

https://platform.altamirahrm.com/api/v1/altamira/REST/Curriculum.Edit.API?ApiKey=0123456789012345&Operation=Upsert&CV.Name=Andrea&CV.Surname=Bianchi&Keys=CV.CustomerID&CV.DateOfBirth=2000-03-04T00:00:00&CV.CustomerID=2&Regions.RegionProvince=Roma

 

{
"Curriculum.Edit.API": [
{
"CV.CVID": 172620799,
"CV.CustomerID": 2,
"CV.Name": "Andrea",
"CV.Surname": "Bianchi",
"CV.DateOfBirth": "2000-03-04T00:00:00.000Z",
"CV.RegionProvince": "43335434"
}
],
"Result": [
{
"Status": "Inserted",
"StatusDescription": "Filter to determine if the row exists: (CV.CustomerID = 2)\r\n - No row found: a new row will be inserted\r\nRegions.RegionProvince: Unable to find list item Roma and autocreate new list items is not enabled\r\n"
}
]
}