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

# Custom SCIM Attribute Mappings

> Carry a value from your identity provider into one of the eleven spare SCIM attributes SkillsDB stores, and point a career automation at it so each career's initiation date is set automatically. Includes the Entra hire date example and how to populate users who are already provisioned.

> [!NOTE]
>
> **Quick Summary:** SkillsDB stores eleven SCIM attributes it does not otherwise use. Map a value from your identity provider into one of them, then turn on **Use custom mapping for career initiation date** on a career automation and choose that attribute. The mapped value becomes the career's initiation date when the automation assigns the career. The most common case is Entra's **Employee hire date** mapped to `locale`; this page uses it as the worked example.

## Overview

A custom SCIM attribute mapping lets a career automation read a value that your identity provider knows but SkillsDB has no field for. Today a career automation uses such a value for one purpose: the career's **initiation date**, the date a person started in that career. The initiation date anchors training timelines and the "Started" date shown on the career. Without a mapping, a [career automation](https://help.skillsdb.com/identity-and-provisioning/scim-career-automations.md) assigns its career with an empty initiation date.

SkillsDB receives SCIM events through Stytch, which passes through the standard SCIM user attributes but not identity-provider-specific properties such as Entra's `employeeHireDate`. To bridge that gap, SkillsDB stores eleven standard SCIM attributes that have no field of their own in SkillsDB: `locale`, `nickName`, `userType`, `timezone`, `preferredLanguage`, `profileUrl`, `name.middleName`, `name.honorificPrefix`, `name.honorificSuffix`, `costCenter`, and `organization`. These are the **spare attributes**. They are never shown on the person's profile. They exist only so that a career automation can read one of them.

A custom mapping therefore has two halves:

* **In your identity provider**, a mapping that writes the source value into one of the eleven spare attributes. The source can be any date your directory holds: a hire date, a role start date, a contract start date, or a custom extension attribute your HR system fills in.
* **In SkillsDB**, the **Use custom mapping for career initiation date** setting on a career automation, pointing at the same spare attribute.

The setting is per automation. Two automations can read two different spare attributes, for example a company-wide hire date for one career and a department start date for another. An automation without the setting keeps assigning its career without an initiation date.

This page covers the whole flow: choosing a spare attribute, adding the mapping in Microsoft Entra ID, turning the setting on in SkillsDB, what happens for newly provisioned users, how to populate users who were provisioned before the mapping existed, and how to verify the result. The SkillsDB side works the same for any SCIM identity provider; the provider steps on this page are for Entra. Only the enterprise application for SkillsDB is changed, and the mapping does not affect any other application in your tenant.

## Prerequisites

Before you begin, make sure you have:

* **Permission level**: Microsoft Entra administrator access to the SkillsDB enterprise application, and SkillsDB administrator access
* **Setup requirement**: An active SCIM connection between Entra and SkillsDB (see [SCIM Setup](https://help.skillsdb.com/identity-and-provisioning/scim-setup.md))
* **Setup requirement**: At least one custom SCIM group with a career automation (see [SCIM Career Automations](https://help.skillsdb.com/identity-and-provisioning/scim-career-automations.md))
* **Setup requirement**: The source value filled in on the Entra users you want to cover, for example the **Employee hire date** property

## How to choose the spare attribute

Pick one of the eleven spare attributes for each value you want to carry. Two rules decide the choice:

1. **Nothing else in your Entra provisioning configuration maps to it.** If the default Entra configuration already maps a directory property to the attribute, your value would fight with it. `locale` is the recommended first choice because the default Entra provisioning configuration leaves it unmapped. `nickName`, `userType`, `timezone`, `preferredLanguage` and `profileUrl` are usually unmapped as well.
2. **One value per attribute.** If you need two values, for example two different start dates for two automations, use two different spare attributes.

| SCIM attribute (as listed in SkillsDB) | Entra target attribute |
| - | - |
| `locale` | `urn:ietf:params:scim:schemas:core:2.0:User:locale` |
| `nickName` | `urn:ietf:params:scim:schemas:core:2.0:User:nickName` |
| `userType` | `urn:ietf:params:scim:schemas:core:2.0:User:userType` |
| `timezone` | `urn:ietf:params:scim:schemas:core:2.0:User:timezone` |
| `preferredLanguage` | `urn:ietf:params:scim:schemas:core:2.0:User:preferredLanguage` |
| `profileUrl` | `urn:ietf:params:scim:schemas:core:2.0:User:profileUrl` |
| `name.middleName` | `urn:ietf:params:scim:schemas:core:2.0:User:name.middleName` |
| `name.honorificPrefix` | `urn:ietf:params:scim:schemas:core:2.0:User:name.honorificPrefix` |
| `name.honorificSuffix` | `urn:ietf:params:scim:schemas:core:2.0:User:name.honorificSuffix` |
| `costCenter` | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter` |
| `organization` | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization` |

SkillsDB trims each value and drops empty values before storing it. Only these eleven attributes are stored; custom schema extensions are not supported, so the value must travel in one of them. See [Stored attributes for career automations](https://help.skillsdb.com/identity-and-provisioning/scim-setup.md#stored-attributes-for-career-automations) for the storage rules.

## How to add the mapping in Entra

Add one attribute mapping to the provisioning configuration of the SkillsDB enterprise application. The example maps the **Employee hire date** property to `locale`; substitute your own source and target.

**1. Open the attribute mappings**

In the **Microsoft Entra admin center**, navigate to **Enterprise applications**, select the SkillsDB application, and select **Provisioning** under **Manage**.

Select **Edit attribute mappings**, expand **Mappings**, and select **Provision Microsoft Entra ID Users**.

**2. Add the mapping**

Below the **customappsso Attributes** table, select **Add New Mapping**.

Set the fields as follows:

| Field | Value for the hire date example |
| - | - |
| **Mapping type** | Direct |
| **Source attribute** | `employeeHireDate` |
| **Target attribute** | `urn:ietf:params:scim:schemas:core:2.0:User:locale` |
| **Apply this mapping** | Always |

Select **Ok**.

**3. Save**

Select **Save** at the top of the attribute mapping page and confirm.

From the next provisioning cycle, every user that Entra sends to SkillsDB carries the source value in the chosen spare attribute.

**Other sources.** Any Entra user property or extension attribute can be the source: `employeeHireDate`, one of the fifteen `extensionAttribute` properties synchronized from on-premises Active Directory, or a directory extension your HR integration writes. The value must reach SkillsDB as an ISO 8601 date (see [What date formats SkillsDB accepts](#what-date-formats-skillsdb-accepts)). A **Direct** mapping of `employeeHireDate` already produces that form. For a source stored in another format, use the **Expression** mapping type and Entra's date formatting functions to output `yyyy-MM-dd`, then confirm the result on one user with **Provision on demand** before rolling it out.

> [!NOTE]
>
> **Note:** Saving a new mapping does not resend users who have not changed. Entra only sends users whose attributes changed since the last cycle. See [How to populate users who are already provisioned](#how-to-populate-users-who-are-already-provisioned) below.

## How to turn on the mapping in SkillsDB

The mapping is a setting on each career automation. Turn it on for every automation whose career should receive the date.

**1. Open the SSO & SCIM settings**

Navigate to **Company > Settings**, find the **SSO & SCIM** row, and select **Configure**.

**2. Edit the group**

In the **Custom SCIM Groups** table, select the **Edit Group** (pencil) icon on the group whose automation should set the date.

**3. Turn on the custom mapping**

In the **Career Automations** section, on the automation row, select **Use custom mapping for career initiation date**. In the **Select SCIM attribute** dropdown that appears, choose the spare attribute you mapped in Entra, for example `locale`.

**4. Save**

Select **Save Changes**. Turning on the mapping does not present the initial activation choice again and does not assign careers to anyone.

Repeat for each group and automation. If you select the checkbox but do not choose an attribute, SkillsDB shows "Choose the SCIM attribute that carries the date" and does not save.

> [!TIP]
>
> **Tip:** Turn on the SkillsDB setting before you add the Entra mapping. Then every user provisioned after the Entra mapping goes live gets the date at the moment their career is assigned. If you do it the other way round, the date is filled in on each user's next SCIM event instead.

## What happens for newly provisioned users

When both halves of the mapping are in place, no further action is needed for new users.

When Entra provisions a user into a group with a career automation, SkillsDB assigns the career and sets its initiation date from the mapped attribute in the same step. The SCIM event log records a **Career Assigned** event whose description ends with the date and the attribute it came from, for example "initiation date 2024-03-15 from SCIM attribute "Locale"".

If the mapped value arrives in a later SCIM event than the one that assigned the career, SkillsDB fills the initiation date in when that later event arrives and records an **Initiation Date Set** event.

If the mapped value is empty or is not a valid date, SkillsDB assigns the career without an initiation date. The **Career Assigned** event description then ends with "no valid initiation date in SCIM attribute "Locale"" (with the attribute you chose). The assignment itself is never blocked by a missing or invalid date.

## How to populate users who are already provisioned

Users provisioned before the Entra mapping existed have no mapped value stored in SkillsDB. Entra has to send their attributes again. There are two ways to trigger that.

### Test with one user first

**1. Provision one user on demand**

In the Entra enterprise application, select **Provisioning > Provision on demand**, pick a user who holds a career assigned by the automation, and select **Provision**.

**2. Check the event log**

In SkillsDB, open the [SCIM Event Log](https://help.skillsdb.com/identity-and-provisioning/scim-event-log.md) and filter by the user's group. An **Initiation Date Set** event for that user must appear, with the mapped date in its description.

**3. Check the career**

Navigate to **Library > Careers**, open the career, and select **Assigned People**. The user's **Initiation Date** column must show the mapped date.

### Resend every user

**1. Restart provisioning**

In the Entra enterprise application, select **Provisioning > Overview**, then select **Restart provisioning** and confirm.

**2. Wait for the cycle to complete**

The restart runs a full initial cycle over every user assigned to the application and sends each user's current attributes, including the mapped value. The cycle takes from a few minutes to several hours depending on the number of users.

**3. Verify in the event log**

Open the [SCIM Event Log](https://help.skillsdb.com/identity-and-provisioning/scim-event-log.md) and filter by event type **Initiation Date Set**. One event per populated career appears.

### Which careers are populated

As each resent user reaches SkillsDB, the stored value is applied to that user's careers under these rules:

| Career | Populated? |
| - | - |
| Assigned by the automation, initiation date empty | Yes. SkillsDB sets the initiation date and records an **Initiation Date Set** event. |
| Assigned by the automation, initiation date already set | No. An existing initiation date is never overwritten, whether it was set by a person or by an earlier sync. |
| Assigned manually, by import, or by an automation on a different group | No. Only careers that this automation itself assigned are touched. |
| Not held by the user | No. Populating dates never assigns a career. |

Running the restart again does not overwrite initiation dates: careers already holding a date are left as they are. The restart does change other data, though.

> [!WARNING]
>
> **Restart provisioning resends every user, and each resent user is a full update of their SkillsDB record.** Before you restart, know that for every user it resends:
>
> * Fields that SCIM never carries are cleared: Employment Type, Home Number, Gender, Notes, Company, the free-text City field, Website / Resume Link, Attachments, the profile picture, Login Username, Next Available Date, and the employment type expiry date. See [SCIM Setup](https://help.skillsdb.com/identity-and-provisioning/scim-setup.md#stored-attributes-for-career-automations) for the full rule.
> * A user an administrator deactivated by hand in SkillsDB is reactivated if they are still active in Entra. See [Azure Sync Considerations](https://help.skillsdb.com/identity-and-provisioning/azure-sync-considerations.md#user-deactivation).
>
> To fill in dates for only a few users, use **Provision on demand** for those users instead of a full restart.

## What date formats SkillsDB accepts

The mapped value is read as a career initiation date only when it is an ISO 8601 date:

| Form | Example | How SkillsDB reads it |
| - | - | - |
| Plain date | `2024-03-15` | Midnight UTC on that day |
| Date and time with an offset | `2024-03-15T00:00:00Z` or `2024-03-15T09:00:00+02:00` | The exact instant, converted to UTC |

The year must fall between 1900 and 2100, and the date must exist on the calendar (`2024-02-30` is rejected). Any other value, including day-first or month-first formats such as `15/03/2024`, a real locale code such as `en-US`, or free text, is ignored: the career is assigned without an initiation date and the event log says so. A **Direct** Entra mapping of `employeeHireDate` produces an accepted form.

## Common Questions

> [accordion] Which spare attribute should I use?
>
> Use `locale` unless something else in your Entra provisioning configuration already maps to it. The default Entra configuration leaves `locale` unmapped, and SkillsDB does not read it for anything except this mapping. If `locale` is taken, any of the other ten attributes listed under [How to choose the spare attribute](#how-to-choose-the-spare-attribute) works the same way. Use the same attribute in the Entra mapping and in the **Select SCIM attribute** dropdown.

> [accordion] Can different automations read different attributes?
>
> Yes. **Use custom mapping for career initiation date** and the chosen attribute are saved per automation. Map each source value to its own spare attribute in Entra, then point each automation at the attribute that carries the date for its career.

> [accordion] Does the mapping change the user's language, locale, name or cost center in SkillsDB?
>
> No. The eleven spare attributes are stored only so a career automation can read them. They are not shown on the person's profile and do not feed any other SkillsDB field. Mapping a date into `name.middleName`, for example, does not change the person's displayed name.

> [accordion] Can I use a source other than the Entra hire date?
>
> Yes. The source can be any Entra user property or extension attribute that holds a date, such as a role start date or a value your HR system writes into an `extensionAttribute`. SkillsDB only sees the spare attribute and the value in it, never where the value came from. The value must arrive as an ISO 8601 date; use an **Expression** mapping in Entra to reformat sources stored another way.

> [accordion] Why did a user get the career but no initiation date?
>
> Either the source property is empty for that user in Entra, or the value that arrived was not a valid date. Open the [SCIM Event Log](https://help.skillsdb.com/identity-and-provisioning/scim-event-log.md) and read the user's **Career Assigned** event: its description says "no valid initiation date in SCIM attribute "Locale"" (with your attribute) in both cases. Fill in the source value in Entra and use **Provision on demand** for that user; SkillsDB then fills the date in and records an **Initiation Date Set** event.

> [accordion] Why did Restart provisioning not change a user's initiation date?
>
> SkillsDB never overwrites an initiation date that is already set, and it only fills dates on careers that the automation itself assigned. If the user's career already shows a date, or the career was assigned manually or by import, the mapped value is not applied. An administrator can change the date on the career's **Assigned People** page instead.

> [accordion] Does this work with identity providers other than Entra?
>
> The SkillsDB side does: a career automation reads the spare attribute regardless of which provider sent it. Your provider must be able to write the source value into one of the eleven attributes in the table above. The step-by-step provider instructions on this page are for Microsoft Entra ID, which is the provider covered by [SCIM Setup](https://help.skillsdb.com/identity-and-provisioning/scim-setup.md).

## Related Articles

> [card] [SCIM Career Automations](https://help.skillsdb.com/identity-and-provisioning/scim-career-automations.md)
>
> Configure the automations that assign careers and carry the initiation date setting.

> [card] [SCIM Setup](https://help.skillsdb.com/identity-and-provisioning/scim-setup.md)
>
> The Entra provisioning configuration and the attributes SkillsDB stores.

> [card] [SCIM Event Log](https://help.skillsdb.com/identity-and-provisioning/scim-event-log.md)
>
> Verify Career Assigned and Initiation Date Set events.

> [card] [Azure Sync Considerations](https://help.skillsdb.com/identity-and-provisioning/azure-sync-considerations.md)
>
> Other Entra limitations and when to restart provisioning.

## Need More Help?

If a mapped value is not reaching SkillsDB after a restart, reach out to your organization's SkillsDB administrator or contact [SkillsDB Support](https://www.skillsdb.com/support).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.