Extended Data

ExtendedData are custom employee extension properties created through the HR File configuration interface. It makes it possible to add custom data to your employees. First, by defining them through extensionUserDefinitions objects, then by setting their value through extendedData objects.

Introduction

ExtendedData values can be retrieved through the users API endpoint. They are listed as properties of a JSON object named extendedData. Such extended data can be of different types and formats (refer to the UserProperties documentation). Here is an example with various format values.

GET /api/v3/users?fields=firstName,extendedData HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}

{
	"firstName": "Paul",
    "extendedData": {
    	"e_secondName": {
        	"id": 4547,
            "value": "André"
        }
    }
}

GET /api/v3/users?fields=firstName,extendedData HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}

{
    "id": 476,
    "extendedData": {
        // Single-value (per employee) of type "text"
        "e_github_login": { "id": 15847, "value": "shipit" },
        // Single-value (per employee) of type "list"
        "e_eyes_color": { "id": 8976, "value": 84 },
        // Single-value (per employee) of type "date"
        "e_diploma_date": { "id": 16952, "value": "2016-09-01T00:00:00"  },
        // Multiple-value of type "text"
        "e_favorite_food": [
        	{ "id": 4589, "value": "beer" },
        	{ "id": 4590, "value": "free beer" }
        ],
        // Single-value (per employee) of type "composite"
        "e_significant_other": {
        	"id": 2635,
        	"value": {
            	"e_so_firstname": { "id": 2636, "value": "Lola" },
                "e_so_lastname": { "id": 2637, "value": "Bunny" }
            }
        },
        // Multiple-value of type "composite"
        "e_objectives": [
            {
                "id": 1726,
                "value": {
                    // Child value - number
                    "e_objective_year": { "id": 15855, "value": 2017 },
                    // Child value - text
                    "e_objective_description": { "id": 15856, "value": "Write more doc" }
                }
            },
            {
                "id": 1727,
                "value": {
                    "e_objective_year": { "id": 15865, "value": 2018 },
                    "e_objective_description": { "id": 15867, "value": "More doc!" }
                }
            }
        ],
        // ExtendedData with no value set
        "e_number_of_children": null,
        // ExtendedData with a value which has been deleted
        "e_quote": { "id": 4896, "value": null }
    }
}

Writing on ExtendedData Values

All example payloads described in this section are sent to the /api/v3/users/{id} API endpoint ({id} being the ID of the user that should be updated).

Extended data values are READ through the optional extendedData field on the User. But they are WRITTEN through passing their values at the root level of the User object.

PUT /api/v3/users/416?fields=lastName,extendedData HTTPS/2
Host: example.ilucca.net
Authorization: lucca application=XXX

> Request
Accept: application/json
Accept-Encoding: br, gzip
Content-Type: application/json
{
    "lastName": "Doe",
	"e_quote": { "id": 4896, "value": "test" }
}

< Response
200 OK
Content-Type: application/json

{
    "lastName": "Doe",
    "extendedData": {
        "e_quote": { "id": 4896, "value": "test" }
    }
}

Attempting to write on extended-data values through the extendedData User property will NOT work.

Simple Single-Value ExtendedData

A “simple” ExtendedData is an extension property that only has one property itself.

A “single-value” ExtendedData is an extension property that does not accept more than one value for each employee.

Creating a value for a simple single-value ExtendedData

To update an ExtendedData value that does not exist, you must not specify its Id (or set it to 0).

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_quote": {
        "value": "99 little bugs in the code..."
    }
}

Updating the value of a simple single-value ExtendedData

To update an ExtendedData value that already exists, you must specify the ID of the ExtendedData value.

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_quote": {
        "id": 4896,
        "value": "Take one down, patch it around. 127 little bugs in the code..."
    }
}

Deleting the value of a simple single-value ExtendedData

To delete the value from an ExtendedData, simply set its value property to null. The ExtendedData value ID must be specified.

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_quote": {
        "id": 4896,
        "value": null
    }
}

Simple Multiple-Value ExtendedData

A “simple” ExtendedData is an extension property that only has one property itself.

A “multiple-value” ExtendedData is an extension property that accepts more than one value for each employee.

Creating a value for a simple multiple-value ExtendedData

To create a multiple-value ExtendedData value, you must send all the occurrences at the same time and not specify the ID of these occurrences (or set them to 0).

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_favorite_food": [
        { "id": 0, "value": "beer" },
        { "id": 0, "value": "free beer" }
    ]
}

Appending values to a simple multiple-value ExtendedData

To add occurrences to a multi-valued ExtendedData value that already exists, all occurrences must be sent at the same time without specifying the IDs of the new occurrences (or setting them to 0).

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_favorite_food": [
        { "id": 4589, "value": "beer" },
        { "id": 4590, "value": "free beer" },
        // New occurrences
        { "id": 0, "value": "cold beer" },
        { "id": 0, "value": "more beer" },
    ]
}

Deleting values from a simple multiple-value ExtendedData

In order to delete some values of an existing multiple-values ExtendedData, you just have to send only the values you want to keep.Note: sending an empty array results in the deletion of all existing values for this ExtendedData (and employee).

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_favorite_food": [
        { "id": 4589, "value": "beer" }
        // Other existing values will be deleted
    ]
}

Composite Single-Value extendedData

A “composite” ExtendedData is an extension property that has more than one property itself.

A “single-value” ExtendedData is an extension property that does not accept more than one value for each employee.

Creating a value for a composite single-value ExtendedData

In order to create a value for an existing composite single-value ExtendedData, send a JSON object whose key is the name of the ExtendedData, and whose value is a JSON object with a value property which in itself is a JSON object setting the value of each of the ExtendedData properties.When creating a value, the ExtendedData id may be either omitted or set to zero 0.

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_significant_other": {
        "id": 0,
        "value": {
            "e_so_firstname": {
                "id": 0,
                "value": "Miss"
            },
            "e_so_lastname": {
                "id": 0,
                "value": "Piggy"
            }
        }
    }
}

Updating the value of a composite single-value ExtendedData

In order to update a composite ExtendedData value, send ALL of its properties values along their own IDs.

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_significant_other": {
        "id": 2635,
        "value": {
            "e_so_firstname": {
                "id": 2636,
                "value": "Lola"
            },
            "e_so_lastname": {
                "id": 2637,
                "value": "Bunny"
            }
        }
    }
}

Deleting the value of a composite single-value ExtendedData

In order to delete a composite ExtendedData value, send all the properties of the composite ExtendedData along their IDs with their values set to null.

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_significant_other": {
        "id": 2635,
        "value": {
            "e_so_firstname": {
                "id": 2636,
                "value": null
            },
            "e_so_lastname": {
                "id": 2637,
                "value": null
            }
        }
    }
}

Composite Multiple-Value ExtendedData

A “composite” ExtendedData is an extension property that has more than one property itself.

A “multiple-value” ExtendedData is an extension property that accepts more than one value for each employee.

Appending a value to a composite multiple-value ExtendedData

In order to create a multiple-value composite ExtendedData, send all the values at the same time while not givin IDs to the new ones (or set them to 0).

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_objectives": [
        // First occurrence
        {
            "id": 0,
            "value": {
                "e_e_objective_description": { "id": 0, "value": "Write more doc" },
                "e_objective_year": { "id": 0, "value": 2017 }
            }
        }
    ]
}

Deleting some values of a composite multiple-value ExtendedData

In order to delete some or all values of a multiple-value composite extendedData, only send the values to keep. To remove all values, send an empty array.

PUT /api/v3/users/416 HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
    "e_objectives": [
        {
            "id": 1726,
            "value": {
                "e_e_objective_description": { "id": 15855, "value": "Write more doc" },
                "e_objective_year": { "id": 15856, "value": 2017 }
            }
        },
        {
            "id": 0,
            "value": {
                "e_objective_year": { "id": 0, "value": 2018 },
                "e_e_objective_description": { "id": 0, "value": "More doc!" }
            }
        }
    ]
}

FAQ

Retrieve entries from a list type ExtendedData

The UserProperties API can be used to retrieve possible entries from a list of values. However, the ExtensionUserDefinitions API /api/v3/extensionuserdefinitions allows to retrieve more information about the possible entries for list type ExtendedData. The objects returned by this API contain an extensionUserPropertyListEntries property, which is an array containing useful information about the entries in the list:

id: numeric value identifying the list entry, which can be inserted into ExtendedData values via the users API;
name: lthe text associated with the list entry, translated into the language of the current user;
translation: the text associated with the list entry, translated into all available languages:
- culturedLabels
  - culture.code: the language of the translation (“en-US”, “fr-FR”, “es-ES”, etc)
  - value: the translated text in the specified language

// GET xxx.ilucca.net/api/v3/extensionuserdefinitions?fields=id,formatKey,extensionUserPropertyListEntries[id,name,translation[culturedLabels[culture.code,value]]]
items: [
    {
        "id": "e_eyes_color",
        "formatKey": "select",
        "extensionUserPropertyListEntries": [
            {
                "id": 84,
                "name": "Brown",
                "translation": {
                	"culturedLabels": [
                    	{ "culture": { "code": "en-US" }, "value": "Brown" },
                    	{ "culture": { "code": "fr-FR" }, "value": "Marron" },
                    ]
                }
            },
            {
                "id": 85,
                "name": "Blue",
                "translation": {
                	"culturedLabels": [
                    	{ "culture": { "code": "en-US" }, "value": "Blue" },
                    	{ "culture": { "code": "fr-FR" }, "value": "Bleu" },
                    ]
                }
            },
             {
                "id": 86,
                "name": "Green",
                "translation": {
                	"culturedLabels": [
                    	{ "culture": { "code": "en-US" }, "value": "Green" },
                    	{ "culture": { "code": "fr-FR" }, "value": "Vert" },
                    ]
                }
            }
        ]
    },
    {	
        "id": "e_quote",
        // e_quote is not a list, so extensionUserPropertyListEntries is empty
        "formatKey": "short",
        "extensionUserPropertyListEntries": [],
    },
    ...
]

Documentation

Files

Organization Structure API

Core HR API

Recruitment API

Expenses API

Invoices API

Absences API

Office API

Project API

Schedule API

Timesheet API

Mealvouchers API

Compensation API

Training API

Introduction

Writing on ExtendedData Values

Simple Single-Value ExtendedData

Simple Multiple-Value ExtendedData

Composite Single-Value extendedData

Composite Multiple-Value ExtendedData

FAQ

Retrieve entries from a list type ExtendedData

​Introduction

​Writing on ExtendedData Values

​Simple Single-Value ExtendedData

​Simple Multiple-Value ExtendedData

​Composite Single-Value extendedData

​Composite Multiple-Value ExtendedData

​FAQ

​Retrieve entries from a list type ExtendedData

Introduction

Writing on ExtendedData Values

Simple Single-Value ExtendedData

Simple Multiple-Value ExtendedData

Composite Single-Value extendedData

Composite Multiple-Value ExtendedData

FAQ

Retrieve entries from a list type ExtendedData