Questo articolo spiega come sono strutturati i dati di anagrafiche e organigramma in Altamira e come si relazionano fra loro. È la lettura preliminare consigliata prima di progettare un'integrazione tramite API REST: senza questo modello in mente, è difficile interpretare correttamente i payload e gli effetti delle operazioni descritti negli articoli per-entità.

Le tre entità principali

Dipendenti

L'anagrafica delle persone presenti in azienda. Contiene i dati identificativi del dipendente (nome, cognome, codice fiscale, email, date di assunzione e dimissione) ed eventuali campi aggiuntivi configurati dal cliente.

Il codice fiscale è un dato informativo importante ma non è la chiave tecnica usata dall'API: la stessa persona può essere registrata in azienda più di una volta, con record di Dipendente distinti, in caso di uscita e rientro dopo un periodo. Ogni record è un dipendente a sé, con il proprio storico, la propria posizione e i propri dati. Lo stesso codice fiscale può quindi comparire su più record di Dipendente nel tempo. Il riferimento univoco usato dalle API è sempre l'id del dipendente.

Posizioni

Le caselle dell'organigramma. Una posizione rappresenta un ruolo organizzativo all'interno di una sede, indipendentemente dalla persona che la occupa. I campi caratterizzanti sono:

• Nome — manuale oppure costruito automaticamente come Cognome Nome - Ruolo.
• Ruolo e Sede — codifiche di lookup.
• ParentID — riferimento alla posizione gerarchicamente superiore.
• Organigramma di appartenenza — una stessa azienda può avere più organigrammi (es. funzionale, geografico).

Una posizione esiste anche quando non ha alcun dipendente assegnato: in quel caso si dice vacante (vedi più avanti).

Assegnazioni (Dipendenti-Posizioni)

Il legame fra un dipendente e una posizione, con data di inizio e (opzionalmente) data di fine. La stessa entità contiene sia le assegnazioni attive (data di fine non valorizzata) sia quelle chiuse (storico). Ogni riga rappresenta un periodo in cui un dipendente ha occupato una posizione.

Identificatori e riferimenti fra entità

Ognuna delle tre entità sopra ha una propria chiave primaria tecnica, esposta nelle API attraverso il campo id. La chiave primaria è l'unico identificatore che le API usano per leggere, aggiornare o legare un record a un altro: tutti i campi di tipo "ID" presenti nei payload (ParentID, PosizioneID, Employee, OrganigrammaID, FunzioneID, LocationID, KeyID) devono essere valorizzati con il valore id dell'entità referenziata.

Riepilogo dei riferimenti

• Posizione → Posizione padre: il campo Positions_ParentID contiene l'id della posizione superiore. Per le posizioni di root il valore è null.
• Posizione → Codifiche: Positions_KeyID contiene l'id dell'organigramma; Positions_FunzioneID contiene l'id del ruolo; Positions_LocationID contiene l'id della sede.
• Assegnazione → Dipendente: EmployeesPositionsHistory_Employee contiene l'id del dipendente.
• Assegnazione → Posizione: EmployeesPositionsHistory_PosizioneID contiene l'id della posizione.
• Assegnazione → Organigramma: EmployeesPositionsHistory_OrganigrammaID contiene l'id dell'organigramma a cui la posizione appartiene.

Gli id sono numerici, generati da Altamira, e non vanno costruiti dal cliente: si recuperano dalle chiamate di lettura sulle viste delle entità o sulle codifiche, oppure (per le creazioni) sono restituiti nella risposta della chiamata di scrittura.

Identificatori del cliente (CustomerID)

Per facilitare la riconciliazione fra i dati Altamira e quelli del sistema esterno, le entità Dipendente, Posizione e Assegnazione espongono ciascuna un campo CustomerID in cui il cliente può scrivere il proprio identificativo (es. il codice del dipendente, della posizione o dell'assegnazione nel sistema HR del cliente):

• Employees_CustomerID sul Dipendente
• Positions_CustomerID sulla Posizione
• EmployeesPositionsHistory_CustomerID sull'Assegnazione

Il CustomerID è un campo libero, lato Altamira ha solo valore informativo: non sostituisce l'id nei riferimenti fra entità. Va aggiunto alla vista come campo qualsiasi se si vuole popolarlo o leggerlo via API.

Struttura gerarchica dell'organigramma

L'organigramma è un albero di posizioni costruito dal campo Positions_ParentID: ogni posizione punta, tramite l'id, alla posizione superiore. Le posizioni in cima (root) hanno Positions_ParentID = null.

Quando si cambia il ParentID di una posizione, l'intero sotto-albero (la posizione e tutte le posizioni che da essa discendono) viene riposizionato sotto il nuovo padre. Questa è la differenza chiave fra "spostare una posizione" e "spostare solo la persona": la prima trascina con sé i riporti, la seconda no (vedi articolo Casistiche operative).

Capo, riporti e dipendente in posizione

Direct boss, boss e riporti non sono campi delle entità: sono concetti derivati dalla navigazione gerarchica delle posizioni.

• Il direct boss di un dipendente è chi occupa la posizione padre della posizione del dipendente (la posizione il cui id compare nel Positions_ParentID della posizione del dipendente).
• I riporti di un dipendente sono i dipendenti che occupano le posizioni figlie della sua.
• Il boss indiretto è chi occupa una posizione antenata (qualunque posizione raggiungibile risalendo i ParentID).

Di conseguenza, per cambiare il direct boss di un dipendente non si modifica il dipendente, ma si modifica la posizione: o cambiando il suo Positions_ParentID (sposta tutto il sotto-albero), o creando una nuova posizione sotto il nuovo capo e ri-assegnando lì il dipendente (vedi articolo Casistiche operative).

Più dipendenti sulla stessa posizione

Una posizione può avere più assegnazioni attive contemporaneamente: la stessa casella dell'organigramma può cioè essere occupata da più dipendenti nello stesso periodo. Lo storico delle assegnazioni mantiene una riga distinta per ciascun dipendente. Questa flessibilità copre, a titolo di esempio, situazioni come job-sharing, sostituzioni temporanee con periodi di affiancamento, o brevi sovrapposizioni durante un cambio di titolare; il modello dati è generale e non vincola a uno specifico scenario.

Posizione vacante

Quando tutte le assegnazioni attive di una posizione vengono chiuse, la posizione resta nell'organigramma ma perde il titolare e viene rinominata in automatico come vacante. La posizione vacante:

• continua ad esistere, mantiene il proprio id, il proprio ParentID e il proprio Ruolo;
• conserva i riporti già collegati: i dipendenti che riportavano alla posizione mantengono come direct boss la stessa posizione, ora vacante;
• torna a un nome regolare non appena un nuovo dipendente le viene assegnato.

Questo meccanismo permette di sostituire la persona in un nodo dell'organigramma senza dover ricostruire il ramo dei suoi riporti.

Codifiche di lookup

Le posizioni si appoggiano a tre codifiche, mantenute come tabelle dedicate e accessibili in lettura tramite endpoint:

• Organigrammi — raggruppano le posizioni in alberi distinti (utile quando la stessa azienda mantiene più viste organizzative).
• Ruoli — i ruoli aziendali (job title) associabili alle posizioni.
• Sedi — le sedi fisiche o logiche.

Anche queste codifiche hanno il proprio id: gli ID restituiti dalle relative chiamate di lettura sono i valori da inserire nei campi Positions_KeyID, Positions_FunzioneID e Positions_LocationID dei payload di scrittura delle posizioni.

Storico delle assegnazioni

Lo storico delle assegnazioni dipendente-posizione è gestito dalla stessa entità delle assegnazioni attive: una riga per ogni periodo in cui il dipendente ha occupato la posizione, identificato da una data di inizio e una data di fine. Le righe chiuse (data di fine valorizzata) sono lo storico; quelle aperte (data di fine a null) sono l'attività corrente.

Non esiste una "tabella storico" separata: lavorando sull'entità Dipendenti-Posizioni storico si accede a entrambi i sotto-insiemi.

Schema riassuntivo delle relazioni

• Dipendente ←→ Assegnazione ←→ Posizione: relazione molti-a-molti nel tempo, mediata dall'id di Dipendente e dall'id di Posizione.
• Posizione → Posizione padre: relazione gerarchica, l'id della posizione padre è memorizzato in Positions_ParentID.
• Posizione → Organigramma / Ruolo / Sede: tramite gli id delle codifiche.

Articoli correlati

• REST - Gestione anagrafiche e organigramma via API
• REST - Anagrafica dipendenti via API
• REST - Organigramma e posizioni via API
• REST - Assegnazione dipendenti alle posizioni via API
• REST - Casistiche operative su organigramma via API