> ## Documentation Index
> Fetch the complete documentation index at: https://developers.lucca.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](./user-properties) documentation). Here is an example
with various format values.

<CodeGroup>
  ```json Simple Example theme={null}
  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é"
          }
      }
  }
  ```

  ```json Various Types Example theme={null}
  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 }
      }
  }
  ```
</CodeGroup>

## 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).

<Warning>
  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.
</Warning>

<CodeGroup>
  ```http Write Request theme={null}
  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" }
      }
  }
  ```
</CodeGroup>

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

### Simple Single-Value ExtendedData

<Tip>A "simple" ExtendedData is an extension property that only has one property itself.</Tip>

<Tip>A "single-value" ExtendedData is an extension property that does not accept more than one
value for each employee.</Tip>

<Steps>
  <Step title="Creating a value for a simple single-value ExtendedData" stepNumber="1">
    To update an ExtendedData value that does not exist, you must not specify its Id
    (or set it to 0).

    <CodeGroup>
      ```json JSON Example 5 theme={null}
      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..."
          }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Updating the value of a simple single-value ExtendedData" stepNumber="2">
    To update an ExtendedData value that already exists, you must specify the ID of the
    ExtendedData value.

    <CodeGroup>
      ```json HTTP Request theme={null}
      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..."
          }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Deleting the value of a simple single-value ExtendedData" stepNumber="3">
    To delete the value from an ExtendedData, simply set its `value` property to `null`.
    The ExtendedData value ID must be specified.

    <CodeGroup>
      ```json HTTP Request theme={null}
      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
          }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

### Simple Multiple-Value ExtendedData

<Tip>A "simple" ExtendedData is an extension property that only has one property itself.</Tip>

<Tip>A "multiple-value" ExtendedData is an extension property that accepts more than one
value for each employee.</Tip>

<Steps>
  <Step title="Creating a value for a simple multiple-value ExtendedData" stepNumber="1">
    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).

    <CodeGroup>
      ```json HTTP Request theme={null}
      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" }
          ]
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Appending values to a simple multiple-value ExtendedData" stepNumber="2">
    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).

    <CodeGroup>
      ```json HTTP Request theme={null}
      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" },
          ]
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Deleting values from a simple multiple-value ExtendedData" stepNumber="3">
    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).

    <CodeGroup>
      ```json HTTP Request theme={null}
      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
          ]
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

### Composite Single-Value extendedData

<Tip>A "composite" ExtendedData is an extension property that has more than one property itself.</Tip>

<Tip>A "single-value" ExtendedData is an extension property that does not accept more than one
value for each employee.</Tip>

<Steps>
  <Step title="Creating a value for a composite single-value ExtendedData" stepNumber="1">
    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`.

    <CodeGroup>
      ```json HTTP Request theme={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": 0,
              "value": {
                  "e_so_firstname": {
                      "id": 0,
                      "value": "Miss"
                  },
                  "e_so_lastname": {
                      "id": 0,
                      "value": "Piggy"
                  }
              }
          }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Updating the value of a composite single-value ExtendedData" stepNumber="2">
    In order to update a composite ExtendedData value, send ALL of its properties values
    along their own IDs.

    <CodeGroup>
      ```json HTTP Request theme={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": "Lola"
                  },
                  "e_so_lastname": {
                      "id": 2637,
                      "value": "Bunny"
                  }
              }
          }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Deleting the value of a composite single-value ExtendedData" stepNumber="3">
    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.

    <CodeGroup>
      ```json HTTP Request theme={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
                  }
              }
          }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

### Composite Multiple-Value ExtendedData

<Tip>A "composite" ExtendedData is an extension property that has more than one property itself.</Tip>

<Tip>A "multiple-value" ExtendedData is an extension property that accepts more than one
value for each employee.</Tip>

<Steps>
  <Step title="Appending a value to a composite multiple-value ExtendedData" stepNumber="1">
    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).

    <CodeGroup>
      ```json HTTP Request theme={null}
      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 }
                  }
              }
          ]
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Deleting some values of a composite multiple-value ExtendedData" stepNumber="2">
    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.

    <CodeGroup>
      ```json HTTP Request theme={null}
      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!" }
                  }
              }
          ]
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## FAQ

### Retrieve entries from a list type ExtendedData

[The UserProperties API](./user-properties) 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

<CodeGroup>
  ```json JSON Example 17 theme={null}
  // 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": [],
      },
      ...
  ]
  ```
</CodeGroup>