Italiano English (United States) Español

Articoli in questa sezione

Vedi altro

REST - Organigramma e posizioni via API

Segui

Questo articolo descrive come leggere, creare, aggiornare ed eliminare le posizioni dell'organigramma tramite l'API REST di Altamira, oltre alle codifiche di lookup necessarie a popolare i payload (Organigrammi, Ruoli, Sedi). Per il contesto generale fai riferimento all'articolo REST - Gestione anagrafiche e organigramma via API.

Modello dell'organigramma

La struttura dell'organigramma è gestita tramite l'entità Posizioni, i cui elementi sono collegati gerarchicamente attraverso il campo ParentID: ogni posizione punta alla posizione superiore. Le posizioni in cima all'albero (root) hanno ParentID = null. L'organigramma viene gestito per consentire la relazione Report — Direct boss — Boss lineare senza Unità organizzative.

Endpoint da predisporre

Posizioni

  • Creare un Endpoint/View per estrarre i dati delle posizioni.
  • Creare un Endpoint/View per creare/aggiornare le posizioni.

Codifiche di lookup

  • Creare un Endpoint/View per estrarre i dati della codifica Organigrammi.
  • Creare un Endpoint/View per estrarre i dati della codifica Ruoli.
  • Creare un Endpoint/View per estrarre i dati della codifica Sedi.

Le tre viste di codifica restituiscono gli ID che vanno poi valorizzati nei campi Positions_KeyID, Positions_FunzioneID e Positions_LocationID dei payload di scrittura delle posizioni.

Scrittura — creazione di una posizione

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

Esempio — posizione di root

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "Cognome Nome - Ruolo",
      "Positions_ParentID": null,
      "Positions_KeyID": 12345,
      "Positions_FunzioneID": 56897,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "false",
      "Positions_CustomerID": "DirectBoss_0001"
    }
  ]
}

Esempio — posizione figlia

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "Cognome Nome - Ruolo",
      "Positions_ParentID": 88888,
      "Positions_KeyID": 12345,
      "Positions_FunzioneID": 87945,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "false",
      "Positions_CustomerID": "Report_0001"
    }
  ]
}

Significato dei campi

  • id — 0 per la creazione di una nuova posizione, l'identificativo della posizione per l'aggiornamento.
  • Positions_Name — nome della posizione (vedi Comportamento del nome posizione più avanti).
  • Positions_ParentID — identificativo della posizione superiore. null per le posizioni nella root, quelle iniziali nella struttura dell'organigramma.
  • Positions_KeyID — ID della codifica Organigramma a cui la posizione appartiene.
  • Positions_FunzioneID — ID del Ruolo associato alla posizione.
  • Positions_LocationID — ID della Sede associata alla posizione.
  • Positions_Inherits — flag di ereditarietà.
  • Positions_AutoName — modalità di costruzione del nome posizione (vedi sotto).
  • Positions_CustomerID — identificativo univoco della posizione nel sistema del cliente. È utile per riconciliare le posizioni Altamira con la propria base dati esterna.

Comportamento del nome posizione (Positions_AutoName)

  • "true" → il nome della posizione deve essere costruito manualmente nel campo Positions_Name.
  • "false" → il nome della posizione viene costruito automaticamente con la sintassi Cognome Nome - Ruolo.

Aggiornamento di una posizione

Per aggiornare una posizione esistente è sufficiente eseguire una chiamata POST sullo stesso endpoint passando il id della posizione e i campi che si vogliono modificare.

Eliminazione di una posizione

Utilizzare l'endpoint per la scrittura con il metodo DELETE.

Vincoli

  • Non è possibile cancellare posizioni che contengono dipendenti attivi.
  • Non è possibile cancellare posizioni che hanno elementi sottostanti nell'organigramma.

Prima dell'eliminazione, l'integrazione deve quindi disattivare/spostare i dipendenti associati e rimuovere o re-imparentare le posizioni figlie.

Lettura

  • Lettura posizioni — restituisce le posizioni contenute nella vista. Aggiungere alla vista i campi necessari per il caso d'uso.
  • Lettura organigramma completo — restituisce la struttura ad albero delle posizioni di un organigramma, utile per ricostruire la gerarchia nel sistema esterno.

Note operative

  • Le date devono essere nel formato "2026-04-02T00:00:00Z".
  • I campi negli esempi sono il set minimo per la corretta scrittura delle posizioni: nomi e struttura devono essere rispettati. È possibile aggiungere ulteriori campi nelle viste secondo le esigenze del cliente.
  • Per costruire correttamente la gerarchia, creare prima le posizioni di livello superiore e poi quelle figlie, valorizzando Positions_ParentID con l'identificativo restituito dalla chiamata di creazione del padre.

Permessi necessari

  • Lettura sull'entità Posizioni per le chiamate GET.
  • Scrittura sull'entità Posizioni per creazioni e aggiornamenti.
  • Cancellazione sull'entità Posizioni per le chiamate DELETE.
  • Lettura sulle codifiche Organigrammi, Ruoli e Sedi, per ricavare gli ID da inserire nei payload.

Articoli correlati

 

Articoli correlati

Commenti

0 commenti

Accedi per aggiungere un commento.