The employee model
The employee is a complex resource that is represented through several objects.Resources: Employees, Employments, Job-Positions…
1
Employee
The employee resource represents the public face of the employee, i.e. all of their attributes
that would be commonly known to anyone in the company.
2
Employee-Personal-Record
The employee-personal-record
is a record that extends an employee and contains personal information about
the employee: personal contact information, emergency contact, social security number, etc…
3
Employment
The employment represents the relationship
between an employee and a legal-entity.
It can be a work-contract, a training agreement, the contract of a contractor, etc…
An employment has a start date and optional end date. No two employments may overlap
for a given employee.
Employments also dictate access rights, as only employees
having an “active” employment may access their Lucca account.
4
Job-Position
The job-position represents a temporary
position occupied by an employee during one of their employment. It indicates the employee’s
business-establishment,
manager,
job-qualification,
department,
job title,
occupation-category,
etc…
The list of job-positions occupied by an employee represents their whole career
in the company.
How can I retrieve the current state of an employee's employment and/or job-position?
How can I retrieve the current state of an employee's employment and/or job-position?
In the Lucca API model, an employee may have more than one employment, and occupy several job-positions over this single employment (without overlaps, though).
This makes it possible to keep track of the whole employee’s career. But in some cases, clients may just need to figure out
the employee’s single current employment and job-position. For example to retrieve their current department and manager.In order to facilitate this, the employee resource has two extra attributes:
applicableJobPosition
: which references the current job-position, i.e. the one whose start and end dates contain “now”;applicableEmployment
: which references the current employment, i.e. the one who has the applicable job-position.
The Extension System
Introduction
The base employee model, as well as some of its related resources, can be extended with additional properties in order to conform to your company specificities. These extensions are first defined throughextension-definitions
; then values
are stored as extensions
.
For example, you may first create an employee-extension-definition
in order to declare
a new “blood type” employee extension, then save the blood-type of each employee as
employee-extensions
.
Extension Schema
An extension-definition defines the expected schema of its extension values, i.e. its type and how it is serialized in JSON in the API. For example, the schema of a “has an access badge” employee extension definition could be a simple booleantrue | false
.
This schema is defined through the JSON schema standard, by referencing (through $ref
) a base schema of the Lucca API.
Schema Name | ref) | Description | Example Value |
---|---|---|---|
short-text | /lucca-api/schemas/short-text | Short string (max 255 chars). | "Abc" |
long-text | /lucca-api/schemas/long-text | Long string (max 4000 chars). | "Lorem.\n Ipsum." |
boolean | /lucca-api/schemas/boolean | Boolean (in UI: checkbox). | true |
int32 | /lucca-api/schemas/int32 | Integer. | 123 |
decimal | /lucca-api/schemas/decimal | Decimal number. | 123.45 |
legacy-date | /lucca-api/schemas/legacy-date | Stringified date. Format: YYYY-mm-DDTHH:MM:ss . | "2025-01-01T09:45:23" |
phone-number | /lucca-api/schemas/phone-number | Phone number as a string. | "+336123456" |
email | /lucca-api/schemas/email | Email address as a string. | "jdoe@example.org" |
url | /lucca-api/schemas/url | URL address as a string. | "https://www.example.org" |
file-reference | /lucca-api/schemas/file-reference | Reference to a file. | {"id": 1, "type": "file", "url": "..."} |
employee-reference | /lucca-api/schemas/employee-reference | Reference to an employee. | {"id": 1, "type": "employee", "url": "..."} |
taxonomy-label-reference | /lucca-api/schemas/taxonomy-label-reference | Reference to a value among a list. | {"id": 1, "type": "taxonomy-label", "url": "..."} |
All definition schemas are “nullable”, i.e.
null
extension values are accepted.Examples
Employee Children (object)
Employee Children (object)
Tee-Shirt Size (taxonomy)
Tee-Shirt Size (taxonomy)
Has Access Badge (boolean)
Has Access Badge (boolean)