REST - Casistiche operative su organigramma via API – Altamira HRM Help Center

Questo articolo raccoglie le casistiche operative ricorrenti nella gestione dell'organigramma via API REST: come inserire un dipendente, spostarlo, sostituirne uno in una posizione, cambiare ruolo, storicizzare un cambio. Per il modello dati e i concetti di base (posizione, assegnazione, direct boss, posizione vacante, id e riferimenti fra entità) leggi prima l'articolo REST - Modello dati di anagrafiche e organigramma. Per la struttura completa di ciascun endpoint e il significato dei campi fai riferimento agli articoli per-entità linkati.

Negli esempi: i payload con id = 0 sono creazioni e richiedono il set completo dei campi della vista; i payload con id valorizzato sono aggiornamenti e includono solo i campi che si vogliono modificare — gli altri campi della vista mantengono il valore precedente.

Inserire un nuovo dipendente nell'organigramma

Sequenza tipica di onboarding di un dipendente già presente in anagrafica.

1. Creazione della posizione che il dipendente dovrà occupare

Chiama l'endpoint di scrittura delle Posizioni con id = 0. Imposta Positions_ParentID con l'id della posizione del direct boss (oppure null se la posizione è di root):

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "",
      "Positions_ParentID": 47896,
      "Positions_KeyID": 25876528,
      "Positions_FunzioneID": 87945,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "true",
      "Positions_CustomerID": "NomeReport-NomeRuolo-NomeDirectBoss"
    }
  ]
}

2. Assegnazione del dipendente alla posizione appena creata

Chiama l'endpoint di scrittura delle Dipendenti-Posizioni con id = 0, l'id del dipendente in EmployeesPositionsHistory_Employee, l'id della posizione appena creata in EmployeesPositionsHistory_PosizioneID, una StartDate nel passato e EndDate = null:

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

Disassegnare un dipendente da una posizione

Per rimuovere un dipendente da una posizione chiama l'endpoint di scrittura delle Dipendenti-Posizioni passando l'id della riga storico e impostando una data di fine antecedente a oggi:

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

Se l'assegnazione chiusa era l'unica attiva sulla posizione, la posizione diventa vacante (vedi Modello dati): mantiene l'id, il ParentID e i riporti.

Spostare un dipendente con tutto il ramo dei suoi riporti

Quando un dipendente cambia direct boss e i suoi riporti devono seguirlo nel nuovo ramo, è sufficiente spostare la sua posizione sotto il nuovo padre: l'intero sotto-albero si riposiziona automaticamente.

Chiama l'endpoint di scrittura delle Posizioni passando l'id della posizione del dipendente e il nuovo Positions_ParentID (l'id della posizione del nuovo direct boss):

{
  "data": [
    {
      "id": 1234,
      "Positions_ParentID": 47896
    }
  ]
}

Tutte le posizioni che riportavano alla posizione spostata continuano a riportare a essa, ora collocata sotto il nuovo direct boss.

Spostare solo il dipendente, lasciando i riporti dov'erano

Quando vuoi spostare solo il dipendente sotto un nuovo direct boss e lasciare i suoi riporti al loro posto, devi:

chiudere l'assegnazione corrente — la posizione vecchia diventa vacante e mantiene i riporti;
creare una nuova posizione sotto il nuovo direct boss;
assegnare il dipendente alla nuova posizione.

1. Chiudere l'assegnazione corrente

Vedi Disassegnare un dipendente.

2. Creazione della nuova posizione sotto il nuovo direct boss

Imposta Positions_ParentID con l'id della posizione del nuovo capo:

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "",
      "Positions_ParentID": 58793,
      "Positions_KeyID": 25876528,
      "Positions_FunzioneID": 87945,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "true",
      "Positions_CustomerID": "NomeReport-NomeRuolo-NomeDirectBoss"
    }
  ]
}

3. Assegnazione del dipendente alla nuova posizione

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

Cambio di ruolo di una posizione

Per cambiare il ruolo associato a una posizione, chiama l'endpoint di scrittura delle Posizioni passando l'id della posizione e il nuovo Positions_FunzioneID (l'id del nuovo ruolo, recuperato dalla codifica Ruoli):

{
  "data": [
    {
      "id": 1234,
      "Positions_FunzioneID": 58964
    }
  ]
}

Se la posizione è in modalità nome automatico, il nome viene aggiornato di conseguenza dopo la scrittura.

Storicizzare un cambio (boss o ruolo)

Le casistiche di cambio descritte sopra modificano la posizione "in linea": il dipendente continua a occupare la stessa posizione e non si genera una nuova riga nello storico delle assegnazioni. Se vuoi invece storicizzare il cambiamento — cioè avere nello storico una riga chiusa con il vecchio scenario e una nuova riga con quello nuovo — applica il seguente pattern in tre passi:

chiudi l'assegnazione corrente;
modifica la posizione: cambia Positions_ParentID per il cambio direct boss, oppure Positions_FunzioneID per il cambio ruolo;
riassegna lo stesso dipendente alla stessa posizione con una nuova riga (id = 0, nuova StartDate).

Lo schema vale identico per i due casi: cambia solo quale campo della posizione viene modificato al passo 2. Di seguito gli esempi dei passi 2 e 3 (per il passo 1 fai riferimento alla sezione Disassegnare un dipendente più sopra).

Passo 1 — chiudi l'assegnazione corrente

Vedi Disassegnare un dipendente.

Passo 2.a — modifica della posizione (variante cambio direct boss)

{
  "data": [
    {
      "id": 1234,
      "Positions_ParentID": 47896
    }
  ]
}

Passo 2.b — modifica della posizione (variante cambio ruolo)

{
  "data": [
    {
      "id": 1234,
      "Positions_FunzioneID": 58964
    }
  ]
}

Passo 3 — riassegnazione del dipendente alla stessa posizione

Chiama l'endpoint di scrittura delle Dipendenti-Posizioni con id = 0 e una nuova StartDate; EmployeesPositionsHistory_Employee e EmployeesPositionsHistory_PosizioneID restano gli stessi del periodo precedente:

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

Permessi necessari

Le casistiche descritte combinano scritture sulle entità Posizioni e Dipendenti-Posizioni storico, e letture sulle codifiche per recuperare gli id da inserire nei payload. L'utente con cui l'integrazione si autentica deve avere assegnati al proprio account i permessi necessari su tutte le entità coinvolte. I permessi vengono assegnati al singolo utente, non al profilo.

Per il dettaglio dei permessi richiesti da ciascun endpoint fai riferimento alle sezioni Permessi necessari degli articoli per-entità.

Altamira HRM Help Center

Articoli in questa sezione

REST - Casistiche operative su organigramma via API