Skip to main content

​
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.
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.
If you have access to these referenced resources, then they can also be embedded in the employee response, in which case you do not even have to follow their URLs.As a result, an employee’s manager can be retrieved thusly:
const options = {
    method: 'GET',
    headers: {'Api-Version': '<api-version>', Authorization: 'Bearer <access_token>'}
};

let req = fetch('https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com/lucca-api/employees/{id}', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

const json = JSON.parse(response);
const managerRef = json.embedded["job-position"][json.applicableJobPosition.id]?.manager;
const manager = json.embedded["employee"][managerRef.id];

​
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 through extension-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 boolean true | false. This schema is defined through the JSON schema standard, by referencing (through $ref) a base schema of the Lucca API. 
{
    "schema": {
        "$ref": "/lucca-api/schemas/boolean"
    }
}
You can also define a new “object” typed extension, i.e. a value which has multiple properties. In which case, each one of its properties will have to reference a base Lucca API schema. 
{
    "schema": {
        "type": "object",
        "properties": {
            "e_foo": {
                "$ref": "/lucca-api/schemas/boolean"
            },
            "e_bar": {
                "$ref": "/lucca-api/schemas/short-text"
            }
        }
    }
}
Schema Nameid(usedforid (used for ref)DescriptionExample Value
short-text/lucca-api/schemas/short-textShort string (max 255 chars)."Abc"
long-text/lucca-api/schemas/long-textLong string (max 4000 chars)."Lorem.\n Ipsum."
boolean/lucca-api/schemas/booleanBoolean (in UI: checkbox).true
int32/lucca-api/schemas/int32Integer.123
decimal/lucca-api/schemas/decimalDecimal number.123.45
legacy-date/lucca-api/schemas/legacy-dateStringified date. Format: YYYY-mm-DDTHH:MM:ss."2025-01-01T09:45:23"
phone-number/lucca-api/schemas/phone-numberPhone number as a string."+336123456"
email/lucca-api/schemas/emailEmail address as a string."jdoe@example.org"
url/lucca-api/schemas/urlURL address as a string."https://www.example.org"
file-reference/lucca-api/schemas/file-referenceReference to a file.{"id": 1, "type": "file", "url": "..."}
employee-reference/lucca-api/schemas/employee-referenceReference to an employee.{"id": 1, "type": "employee", "url": "..."}
taxonomy-label-reference/lucca-api/schemas/taxonomy-label-referenceReference 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

{
    "id": "e_children",
    "type": "employee-extension-definition",
    "url": "https://example.ilucca.net/lucca-api/employee-extension-definitions/e_children",
    "name": "Children",
    "multipleValueHandling": {
        "sorting": "ascending",
        "sortingProperty": "e_childBirthDate"
    },
    "schema": {
        "type": "object",
        "properties": {
            "e_childGivenName": {
                "$ref": "/lucca-api/schemas/short-text"
            },
            "e_childFamilyName": {
                "$ref": "/lucca-api/schemas/short-text"
            },
            "e_childBirthDate": {
                "$ref": "/lucca-api/schemas/legacy-date"
            }
        }
    },
    "propertyDescriptions": {
        "e_childGivenName": {
            "name": "Given Name",
            "taxonomy": null,
            "sortOrder": 0,
            "t9n": {
                "name": {
                    "en-US": "First Name",
                    "fr-FR": "Prénom"
                }
            }
        },
        "e_childFamilyName": {
            "name": "Family Name",
            "taxonomy": null,
            "sortOrder": 1,
            "t9n": {
                "name": {
                    "en-US": "Last Name",
                    "fr-FR": "Nom de famille"
                }
            }
        },
        "e_childBirthDate": {
            "name": "Birth Date",
            "taxonomy": null,
            "sortOrder": 2,
            "t9n": {
                "name": {
                    "fr-FR": "Date de naissance"
                }
            }
        }
    },
    "taxonomy": null,
    "isArchived": false,
    "lastArchivedAt": null,
    "t9n": {
        "name": {
            "fr-FR": "Enfants à charge"
        }
    }
}

{
    "id": "e_tShirtSize",
    "type": "employee-extension-definition",
    "url": "https://example.ilucca.net/lucca-api/employee-extension-definitions/e_tShirtSize",
    "name": "T-shirt size",
    "multipleValueHandling": null,
    "schema": {
        "$ref": "/lucca-api/schemas/taxonomy-label-reference"
    },
    "propertyDescriptions": null,
    "taxonomy": {
        "id": "123",
        "type": "taxonomy",
        "url": "https://example.ilucca.net/lucca-api/taxonomies/123"
    },
    "isArchived": false,
    "lastArchivedAt": null,
    "t9n": {
        "name": {
            "fr-FR": "Taille de tee-shirt"
        }
    }
}

{
    "id": "e_hasAccessBadge",
    "type": "employee-extension-definition",
    "url": "https://example.ilucca.net/lucca-api/employee-extension-definitions/e_hasAccessBadge",
    "name": "Has Access Badge",
    "multipleValueHandling": {
        "allowsMultiple": false
    },
    "schema": {
        "$ref": "/lucca-api/schemas/boolean",
    },
    "propertyDescriptions": null,
    "taxonomy": null,
    "isArchived": false,
    "lastArchivedAt": null,
    "t9n": {
        "name": {
            "fr-FR": "Détenteur d'un badge d'accès"
        }
    }
}
⌘I