Questo articolo descrive come gestire le assegnazioni dipendente-posizione (creazione, aggiornamento, chiusura) tramite l'API REST di Altamira. Per il contesto generale e il modello dell'organigramma fai riferimento all'articolo REST - Gestione anagrafiche e organigramma via API.

Entità di riferimento

Le assegnazioni dipendente-posizione vengono gestite tramite l'entità Dipendenti-Posizioni storico: la stessa entità rappresenta sia le assegnazioni attive (con data di fine non valorizzata) sia quelle storiche (chiuse). Lavorare sull'entità storico è la modalità corretta sia per le letture sia per tutte le operazioni di scrittura, inclusa la chiusura.

Endpoint da predisporre

• Creare un Endpoint/View per estrarre i dati delle assegnazioni dipendenti-posizioni esistenti (utilizzare l'entità Dipendenti-Posizioni storico).
• Creare un Endpoint/View per creare/aggiornare/disattivare le assegnazioni dipendenti-posizioni (includere il campo Dipendente di tipo lista e utilizzare l'entità Dipendenti-Posizioni storico).

Lo stesso endpoint di scrittura viene utilizzato sia per la creazione di una nuova assegnazione, sia per la sua chiusura/disattivazione.

Creazione di un'assegnazione attiva

L'endpoint di scrittura accetta una chiamata POST con un payload nella forma seguente:

{
  "data": [
    {
      "id": 0,
      "EmployeesPositionsHistory_CustomerID": "DirectBossMain1",
      "EmployeesPositionsHistory_StartDate": "2026-03-01T00:00:00Z",
      "EmployeesPositionsHistory_EndDate": null,
      "EmployeesPositionsHistory_OrganigrammaID": "25876528",
      "EmployeesPositionsHistory_PosizioneID": "27160176",
      "EmployeesPositionsHistory_Employee": "27160150"
    }
  ]
}

Significato dei campi

• id — 0 per la creazione di una nuova assegnazione, l'identificativo della riga storico per l'aggiornamento o la chiusura.
• EmployeesPositionsHistory_CustomerID — identificativo univoco dell'assegnazione nel sistema del cliente. Utile per riconciliare le righe Altamira con la propria base dati esterna.
• EmployeesPositionsHistory_StartDate — data di inizio dell'assegnazione. Inserire una data antecedente a oggi per un'assegnazione attiva.
• EmployeesPositionsHistory_EndDate — data di fine dell'assegnazione. Inserire null per un'assegnazione attiva.
• EmployeesPositionsHistory_OrganigrammaID — ID dell'organigramma a cui appartiene la posizione collegata.
• EmployeesPositionsHistory_PosizioneID — ID della posizione a cui il dipendente viene assegnato.
• EmployeesPositionsHistory_Employee — ID del dipendente da assegnare. Il campo Dipendente deve essere presente nella vista come campo di tipo lista.

Regole su date e stato

• StartDate nel passato + EndDate a null → assegnazione attiva.
• EndDate valorizzata → assegnazione chiusa: il dipendente non risulta più assegnato a quella posizione a partire dalla data indicata.

Chiusura/disattivazione di un'assegnazione

Per disattivare (chiudere) una dipendenti-posizione utilizzare lo stesso endpoint di scrittura, valorizzando il campo id con l'identificativo della riga storico e impostando la data di termine antecedente a oggi:

{
  "data": [
    {
      "id": 27160260,
      "EmployeesPositionsHistory_EndDate": "2026-04-01T00:00:00Z"
    }
  ]
}

Non è necessario inviare gli altri campi: vengono mantenuti i valori già presenti.

Lettura

L'endpoint di lettura risponde a una chiamata GET e restituisce le righe storico (attive e chiuse) contenute nella vista. Aggiungere alla vista i campi necessari per il caso d'uso e applicare eventuali filtri lato client (per dipendente, per posizione, per intervallo di date) come descritto nell'articolo REST - Esempio chiamata di lettura con filtro.

Note operative

• Le date devono essere nel formato "2026-04-02T00:00:00Z".
• I campi negli esempi sono il set minimo per la corretta gestione delle assegnazioni: nomi e struttura devono essere rispettati. È possibile aggiungere ulteriori campi nelle viste secondo le esigenze del cliente.
• Il campo Dipendente deve essere incluso nella vista come campo di tipo lista: è il riferimento usato dall'API per collegare l'assegnazione al dipendente.
• Prima di creare un'assegnazione, assicurarsi che esistano sia il dipendente sia la posizione di destinazione (vedi REST - Anagrafica dipendenti via API e REST - Organigramma e posizioni via API).

Permessi necessari

• Lettura sull'entità Dipendenti-Posizioni storico per le chiamate GET.
• Scrittura sull'entità Dipendenti-Posizioni storico per creazioni, aggiornamenti e chiusure.
• Lettura sulle entità Dipendenti e Posizioni, per ricavare gli ID da inserire nei payload.

Articoli correlati

• REST - Gestione anagrafiche e organigramma via API
• REST - Modello dati di anagrafiche e organigramma
• REST - Anagrafica dipendenti via API
• REST - Organigramma e posizioni via API
• REST - Casistiche operative su organigramma via API
• REST - Esempio chiamata di lettura con filtro
• REST - Esempio chiamata di scrittura