REST - Personnel and organization data model – Altamira HRM Help Center

This article explains how personnel and organization-chart data are structured in Altamira and how they relate to each other. It is the recommended preliminary reading before designing a REST API integration: without this model in mind, it is hard to interpret correctly the payloads and the effects of the operations described in the per-entity articles.

The three main entities

Employees

The registry of the people working in the company. It contains the employee's identifying data (first name, last name, fiscal code, email, hire date, resignation date) and any additional fields configured by the customer.

The fiscal code is an important informational field but it is not the technical key used by the API: the same person can be registered in the company more than once, as separate Employee records, when they leave and rejoin after a period. Each record is an employee in its own right, with its own history, its own position and its own data. The same fiscal code can therefore appear on more than one Employee record over time. The unique reference used by the APIs is always the Employee id.

Positions

The boxes of the organization chart. A position represents an organizational role within a location, regardless of who occupies it. The defining fields are:

Name — either manual or built automatically as Last name First name - Role.
Role and Location — lookup tables.
ParentID — reference to the position immediately above in the hierarchy.
Organization chart the position belongs to — the same company can have multiple organization charts (e.g. functional, geographic).

A position exists even when no employee is assigned to it: in that case it is said to be vacant (see below).

Assignments (Employee-Positions)

The link between an employee and a position, with a start date and (optionally) an end date. The same entity holds both the active assignments (end date not set) and the closed ones (history). Each row represents a period during which an employee held a position.

Identifiers and references between entities

Each of the three entities above has its own technical primary key, exposed in the APIs through the id field. The primary key is the only identifier the APIs use to read, update or link a record to another: every "ID" field present in the payloads (ParentID, PosizioneID, Employee, OrganigrammaID, FunzioneID, LocationID, KeyID) must be valued with the id of the referenced entity.

Reference summary

Position → Parent position: the Positions_ParentID field contains the id of the position above. Root positions have a null value.
Position → Lookups: Positions_KeyID contains the organization-chart id; Positions_FunzioneID contains the role id; Positions_LocationID contains the location id.
Assignment → Employee: EmployeesPositionsHistory_Employee contains the employee id.
Assignment → Position: EmployeesPositionsHistory_PosizioneID contains the position id.
Assignment → Organization chart: EmployeesPositionsHistory_OrganigrammaID contains the id of the organization chart the position belongs to.

The ids are numeric, generated by Altamira, and must not be built by the customer: they are retrieved from the read calls on the entity views or on the lookup views, or (for creations) they are returned in the response of the write call.

Customer identifiers (CustomerID)

To make it easier to reconcile Altamira data with the external system, the Employee, Position and Assignment entities each expose a CustomerID field where the customer can write its own identifier (e.g. the employee, position or assignment code in the customer's HR system):

Employees_CustomerID on Employee
Positions_CustomerID on Position
EmployeesPositionsHistory_CustomerID on Assignment

The CustomerID is a free-text field; on the Altamira side it has informational value only: it does not replace the id in cross-entity references. It must be added to the view like any other field if you want to populate or read it via API.

Hierarchical structure of the organization chart

The organization chart is a tree of positions built through the Positions_ParentID field: each position points, through the id, to the position above it. The positions at the top (root) have Positions_ParentID = null.

When you change the ParentID of a position, the entire sub-tree (the position itself and all the positions descending from it) is repositioned under the new parent. This is the key difference between "moving a position" and "moving only the person": the former drags the reports with it, the latter does not (see the Common operational scenarios article).

Direct boss, reports and employee in a position

Direct boss, boss and reports are not entity fields: they are concepts derived from the hierarchical navigation of positions.

The direct boss of an employee is whoever occupies the parent position of the employee's position (the position whose id appears in the Positions_ParentID of the employee's position).
An employee's reports are the employees who occupy the child positions of theirs.
An indirect boss is anyone who occupies an ancestor position (any position reachable by climbing up ParentIDs).

As a consequence, to change an employee's direct boss you do not modify the employee — you modify the position: either by changing its Positions_ParentID (which moves the whole sub-tree), or by creating a new position under the new boss and re-assigning the employee there (see the Common operational scenarios article).

Multiple employees on the same position

A position can hold more than one active assignment at the same time: the same box in the organization chart can be occupied by several employees in the same period. The assignment history keeps a separate row for each employee. This flexibility covers, by way of example, situations such as job-sharing, temporary substitutions with overlap periods, or short overlaps during a change of incumbent; the data model is general and is not tied to a specific scenario.

Vacant position

When all the active assignments of a position are closed, the position stays in the organization chart but loses its incumbent and is automatically renamed as vacant. A vacant position:

continues to exist, keeps its own id, ParentID and Role;
keeps the linked reports: the employees who reported to the position keep the same (now vacant) position as their direct boss;
returns to a regular name as soon as a new employee is assigned to it.

This mechanism makes it possible to replace the person at a node of the organization chart without having to rebuild the branch of their reports.

Lookup tables

Positions rely on three lookup tables, kept as dedicated tables and accessible in read mode through an endpoint:

Organization charts — group positions into separate trees (useful when the same company maintains multiple organizational views).
Roles — the job titles that can be associated with positions.
Locations — physical or logical locations.

These lookup tables have their own id too: the IDs returned by their read calls are the values to put into the Positions_KeyID, Positions_FunzioneID and Positions_LocationID fields of the position write payloads.

Assignment history

The history of employee-position assignments is managed by the same entity that holds the active ones: one row for each period an employee held a position, identified by a start date and an end date. Closed rows (end date set) are the history; open rows (end date null) are the current activity.

There is no separate "history table": by working on the Employee-Positions history entity you access both subsets.

Summary of relationships

Employee ←→ Assignment ←→ Position: many-to-many over time, mediated by the Employee id and the Position id.
Position → Parent position: hierarchical relationship, the parent position id is stored in Positions_ParentID.
Position → Organization chart / Role / Location: through the ids of the lookups.

Altamira HRM Help Center

Articles in this section

REST - Personnel and organization data model