# Workday

{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}

[Workday](https://www.workday.com/) is cloud-based enterprise software that unifies finance and workforce management in a single platform. Integrate Workday with Cortex to manage teams and hierarchies, enforce ownership, and drive operational excellence.

## How to configure Workday with Cortex

### Step 1: Generate an ownership report in Workday

Depending on how you want to manage teams and the corresponding hierarchy, you can choose one of the following options:

* Manage teams based on Workday supervisory organizations
* Manage teams based on Workday teams

The required fields in the report differ depending on which option you choose. See the tabs below for instructions.

{% tabs %}
{% tab title="Supervisory orgs" %}
Your report will need the following fields:

* `email`: Email address for employee. Use the same address that employees will use to access Cortex.
* `employeeId`: Unique ID for each employee.
* `firstName`: Employee first name. This will be displayed in Cortex.
* `lastName`: Employee last name. This will be displayed in Cortex.
* `employeeRole` **(optional)**: Employee role. This will be displayed in Cortex.
* `employeeSupervisoryOrgId`: The ID for the supervisory organization that the employee is in. Cortex uses this field to group employees.
* `teamDisplayName`: A display name for individual teams based on the `employeeSupervisoryOrgId`; this should be the same across all employees who belong to the same supervisory org. This will become the Cortex team name and tag.
* `managerEmail`: Email address for the employee's manager. If Cortex detects an employee with the same email as the `managerEmail`, that employee will be added to the team with a "Manager" role.
* `teamSupervisoryOrgId`: The supervisory org ID for the team that the employee is part of. The organization registered in this field will become a "parent" in the team hierarchy, while the org registered in `employeeSupervisoryOrgId` will become a "child" in the hierarchy.
* `teamListKey` (for One Employee - Multiple Teams): Key for the list of teams associated with a given user.

{% hint style="warning" %}
Any changes to the `employeeSupervisoryOrgId` will result in the creation of a new team because this field is how Cortex identifies teams.
{% endhint %}
{% endtab %}

{% tab title="Workday teams" %}
Your report will need the following fields:

* `email`: Email address for employee. Use the same address that employees will use to access Cortex.
* `employeeId`: Unique ID for each employee.
* `firstName`: Employee first name. This will be displayed in Cortex.
* `lastName`: Employee last name. This will be displayed in Cortex.
* `employeeRole` **(optional)**: Employee role. This will be displayed in Cortex.
* `teamName`: Team name for employee. This field is what we use to group employees into teams in Cortex.
* `teamDisplayName` **(optional)**: Display name for the team. This will be used for the title and the tag for any teams imported from Workday at time of import. If not included, `teamName` will be used instead. This should be the same for all employees on the same team.
* `managerEmail`: Email address for the employee's manager. Cortex uses this field to create team hierarchies. If Cortex detects an employee with the same email as the `managerEmail`, that employee will be added to the team with a "Manager" role.
  * **Omit this field** if you **do not** want to auto-import teams and the corresponding hierarchy from Workday.

{% hint style="warning" %}
Any changes to the `teamName` will result in the creation of a new team because this field is how Cortex identifies teams.
{% endhint %}
{% endtab %}
{% endtabs %}

### Step 2: Configure the integration in Cortex

1. In Cortex, navigate to the [Workday settings page](https://app.getcortexapp.com/admin/integrations/workday):
   * Click **Integrations** from the main nav. Search for and select **Workday**.
2. Click **Add configuration**.
3. Configure the Workday integration form:
   * **Username**: Enter the username associated with the Workday account used to generate the ownership report.
   * **Password**: Enter the password for the Workday username.
   * **Ownership report URL**: Enter the URL for the ownership report you generated.
     * Provide the base report URL. Do not include query parameters in the URL. If necessary, Cortex will append `?format=json` when making requests.
4. Click **Save**.

### Step 3: Configure the report mappings

After saving the configuration, you can configure how you want the fields to map to different elements in Cortex. The options available in each dropdown menu will mirror the fields included when generating the ownership report.

**Note on field mapping availability**

When you first add or update a Workday report URL, Cortex runs a background sync job to fetch and cache the report's column structure. The field mapping drop-downs on the configuration page are populated from this cache.

If you open the configuration page immediately after adding or rotating credentials, the drop-downs may appear empty or validation errors like "Employee Id is required" may surface before the sync completes. If this occurs, wait a few minutes and refresh the page—the column options populate once the background sync has finished.

Cortex also runs a daily sync to keep the field cache up-to-date. If your Workday report structure changes, the latest mapping drop-downs are reflected within 24 hours.

1. Configure the mappings:
   * **Employee Attributes**: Map report fields that pertain to employees, including the following:
     * **Employee ID**
     * **Email**
     * **First Name**
     * **Last Name**
     * **Role (optional)**
       * Imports employees' roles and populates a badge that appears next to an employee's name.
     * **Manager Email**
       * When added, lists the corresponding manager for a given employee. The report should also include an entry for the manager to populate the field.
   * **Team Attributes**: Map report fields that pertain to employees' teams.
     * **Team type**: Select whether to map the fields using `One Employee - One Team` or `One Employee - Multiple Teams`.
       * The `One Employee - One Team` configuration is best if your report includes employees who belong to a single team. The `One Employee - Multiple Teams` configuration is recommended if employees have a list of teams they belong to. This is best if you are configuring the integration based on [supervisory orgs](#supervisory-organizations) and/or if users manage teams they belong to.
     * If using `One Employee - One Team`:
       * **Team ID**: Enter the team ID. New teams are imported based on this ID. If the identifier (i.e. `teamName`) changes, Cortex will create a new team.
       * **Team Name**: Enter a display name for the team in Cortex. Cortex will update this name if changes are detected in Workday.
     * If using `One Employee - Multiple Teams`:
       * **Team List Key**: Enter the list key for the list that contains teams you want imported into Cortex for a given employee entry. This requires the `teamListKey` field in the Workday report. The `teamListKey` should be a list of objects, where each object has at least `teamName` and `teamId` properties:
         * **Team ID**: Enter the team ID. New teams are imported based on this ID. If the identifier (i.e. `teamName`) changes, Cortex will create a new team.
         * **Team ID - Fallback**: Enter a fallback team for a user who does not have an associated `teamListKey`.
         * **Team Name**: Enter a display name for the team in Cortex. Cortex will update this name if changes are detected in Workday.
         * **Team Name - Fallback**: Enter a fallback team name for the fallback team ID defined above.
2. At the bottom of the screen, click **Save**.

#### **Configure the hierarchy fields for auto-importing Workday teams**

If you choose to [automatically import Workday teams](#automatic-import-of-teams), you must also configure the hierarchy fields mappings:

* **Field on parent team**: The value selected becomes a parent team for value selected in **Field on child team**.
* **Is List**: Toggle **on** when an entry for the parent field is a parent to multiple teams.
* **Field on child team**: The value selected is defined as child team.
* **Root Team IDs**: The ID for the team you expect to be at the top of the hierarchy.
  * If set, Cortex will use this to [break cycles](#limitations) that may be in the hierarchy.

Note that you must [enable the option to auto-import Workday teams](#automatic-import-of-teams) in order to import hierarchies.

## How to connect Cortex entities to Workday

### Discovery

By default, Cortex will use the [Cortex tag](https://docs.cortex.io/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" for Workday team. For example, if your Cortex tag is `my-entity`, then the corresponding name in Workday should also be `my-entity`.

If your Workday teams don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

Note: The team name is case-sensitive and should be exactly the same as in the report's `teamDisplayName` or `teamName` field.

### Automatic import of teams

You can choose to automatically import discovered teams and team relationships from Workday into Cortex. Before enabling auto import, make sure your Workday report includes the `managerEmail` field to ensure that team relationships are imported.

1. Navigate to [**Settings > Entities > Teams**](https://app.getcortexapp.com/admin/settings/entities/teams) in Cortex.
2. Under **Enabled identity providers**, make sure the box is checked next to **Workday**.
3. Under **Enable auto import of teams**, click the toggle next to **Auto import teams** to turn this setting on.

The next automatic import will occur when the background [entities sync runs](#background-sync) at 9 a.m. UTC.

{% hint style="info" %}
If an entity already exists with a tag that matches the tag of a Workday team that you are importing, Cortex automatically adds a `-team` suffix to the Workday team's [Cortex tag](https://docs.cortex.io/entities#cortex-tag).

For example, if `payments` exists as a Cortex tag in Cortex, then you import a Payments team from Workday, Cortex will import the team's tag as `payments-team`.
{% endhint %}

#### Manually trigger team import

You can also manually trigger this sync:

1. Navigate to [**Catalogs > Teams**](https://app.getcortexapp.com/admin/catalogs/teams) in Cortex.
2. Click **Create team**.
3. In the upper left corner, click **Sync teams**.

### Entity descriptor

```yaml
x-cortex-owners:
  - type: group
    name: workday-team-tag
    provider: CORTEX
    description: This is a description for this owner.
```

| Field         | Description                                                                                                                                  | Required |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | :------: |
| `type`        | Ownership type (in this case, `group`)                                                                                                       |   **✓**  |
| `name`        | The [tag of the Cortex team entity](https://docs.cortex.io/entities#unique-identifiers-for-entities) linked to the auto-created Workday team |   **✓**  |
| `provider`    | The source of the team (in this case, it was a Cortex-created team)                                                                          |   **✓**  |
| `description` | Description for the owner                                                                                                                    |          |

## Using the Workday integration

#### Entity pages

Once the integration is set up, Cortex will automatically import and structure your team hierarchy. Any teams imported from Workday will appear with a description: **"Automatically created by Cortex"**.

On each team's details page, any team members Cortex detects will populate under the **Members** tab. If you included the "Role" field in your Workday report, members' roles will appear in a badge next to their names.

### Scorecards and CQL

<details>

<summary>All ownership details</summary>

A special built-in type that supports a null check or a count check, used to enforce ownership of entities.

**Definition:** `ownership: Ownership | Null`

**Example**

An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:

```
ownership.teams().length > 0
```

</details>

<details>

<summary>All owner details</summary>

List of owners, including team members and individual users, for each entity

**Definition:** `ownership.allOwners()`

**Example**

The Scorecard might include a rule to ensure that entity owners all have an email set:

```
ownership.allOwners().all((member) => member.email != null)
```

</details>

<details>

<summary>Team details</summary>

List of teams for each entity

**Definition:** `ownership.teams(): List<Team>`

**Example**

The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:

```
ownership.teams().all(team => team.description != null and team.isArchived == false)
```

</details>

### View integration logs <a href="#still-need-help" id="still-need-help"></a>

## Background sync

Cortex syncs teams from the report every day at 9 a.m. UTC.

You can sync teams manually at any time by clicking the **Sync teams for Workday** button from [Workday settings page](https://app.getcortexapp.com/admin/integrations/workday) in Cortex. Doing so will **not** auto-import teams.

## Limitations

Cortex does not support hierarchies with cycles. For example, let's say `Employee A` is on the platform team, `Employee B` is on the frontend team, and both report to `Manager C` on the engineering team. If `Manager C` reported to someone on the platform team, that would create a cycle between the platform and engineering teams.

## Still need help?[​](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help) <a href="#still-need-help" id="still-need-help"></a>

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: <help@cortex.io>, or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/ingesting-data-into-cortex/integrations/workday.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.