> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/integrations/workday.md). # 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 %} ## Why use the integration for Workday Workday is the system of record for your people, teams, and reporting relationships. However, that organizational structure often lives separately from the tools your engineers use day to day. The integration for Workday bridges that gap by syncing your Workday ownership data directly into Cortex, automatically importing employees, teams, and hierarchies so that ownership in your software catalog stays aligned with how your organization is actually structured. Instead of manually maintaining team rosters and reporting lines in two places, you can rely on Workday as the source of truth and let Cortex handle the rest: connecting people to the services, resources, and entities they own, enforcing accountability through Scorecards, and ensuring that as teams reorganize or employees change roles, your ownership model evolves with them. This is especially valuable for organizations that want to drive operational excellence at scale, where knowing who owns what—and being able to trust that information—is foundational to incident response, compliance, and engineering productivity. ## Configuring Workday ### Prerequisites 1. Users with the `Configure Integrations` permissions can configure Workday. ### Step 1: Generating an ownership report in Workday 1. In Workday, generate an ownership report. 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 Note that the required fields in the report differ depending on which option you choose. See the table below.

Field	Description	Required for supervisory orgs?	Required for Workday teams?
`email`	Email address for employee. Use the same address that employees will use to access Cortex.
`employeeId`	Unique employee ID.
`firstName`	Employee first name (displayed in Cortex).
`lastName`	Employee last name (displayed in Cortex).
`employeeRole`	Employee role (displayed in Cortex).	optional	optional
`employeeSupervisoryOrgId`	Supervisory org ID for employee. Cortex uses this field to group employees. Any changes to this field results in the creation of a new team as this is how Cortex identifies teams.
`teamName`	Team name for employee. This field is used to group employees into teams in Cortex. Any changes to this field results in the creation of a new team as this is how Cortex identifies teams.
`teamDisplayName`	Display name for team. This is used for the title and tag for any teams imported from Workday. If not included, `teamName` is used instead. This should be the same for all employees on the same team.		optional
`teamEmployeeManages`	The team this employee manages. Include this field if your report identifies a team's manager on the team record. If you omit it, Cortex treats the person in `managerEmail` as the manager.	optional	optional
`managerEmail`	Email address for 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 is 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.
`teamSupervisoryOrgId`	Supervisory org ID for the employee's team. This org becomes the parent of `employeeSupervisoryOrgId` in the team hierarchy.
`teamListKey`	Key for the list of teams associated with a given user. This field is for a single employee on multiple teams.

### Step 2: Configuring the Workday integration 1. From the main sidebar in Cortex, select **Integrations**. 2. Locate Workday, then click **Install**. The Workday side panel opens. 3. In the Workday side panel, do the following: 1. From the **Category** dropdown, select at least one category that applies to the integration (required). **Team** is the default category. 2. Under **Username**, enter the username associated with the Workday account used to generate the ownership report (required). 3. Under **Password**, enter the password associated with the Workday username (required). 4. Under **Ownership report URL**, enter the URL for the ownership report you generated (required). 1. Provide the base report URL. Do not include query parameters in the URL. If necessary, Cortex appends `?format=json` when making requests. 4. Click **Test connection**. A successful connection means your integration is configured correctly. 5. Click **Save**. {% hint style="info" %} To modify an existing configuration, see [Modifying an integration configuration](/ingesting-data-into-cortex/integrations.md#modifying-an-integration-configuration). {% endhint %} ### Step 3: Configuring the report mappings in Cortex After saving the configuration, you can configure how you want the fields to map to different elements in Cortex. The options available in each drop-down menu 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 dropdowns on the configuration page are populated from this cache. If you open the configuration page immediately after adding or rotating credentials, the dropdowns 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. The dropdowns include fields that appear on only some rows of your report, as well as fields nested inside a team list, so every employee record doesn't need to carry every field. {% hint style="info" %} Cortex 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. {% endhint %} **To configure report mappings**: 1. From the main sidebar, select **Integrations**. 2. Locate Workday, then click **Settings**.

The 'Settings' button next to the Workday integration on the Integrations page.

3. From the **Integrations settings** tab, do the following: 1. In the **Employee attributes** section, map report fields that pertain to employees: 1. From the **Employee ID** dropdown, select a report field for the unique employee identifier (required). 2. From the **Email** dropdown, select a report field for the employee's email address (required). This is what Cortex matches against a user's login. 3. From the **First Name** dropdown, select a report field for the given name shown in Cortex. 4. From the **Last Name** dropdown, select a report field for the surname shown in Cortex. 5. From the **Role** dropdown, select a report field for the employee's role, displayed as a badge next to their name on the team's **Members** tab. 6. From the **Manager Email** dropdown, select a report field for the manager's email. This is used to identify a team's manager. 7. Click **Save**. 2. In the **Team attributes** section, map report fields that pertain to employees' teams. 1. From the **Team type** dropdown, select the shape of the report: 1. **One Employee-Multiple Teams** - Select this option if your report includes employees who belong to multiple teams. 1. From the **Team List Key** dropdown, select a report field that contains the teams you want imported into Cortex for a given employee entry (required). 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: 2. From the **Team ID** dropdown, select a report field for the team ID. New teams are imported based on this ID (required). If the identifier changes, Cortex creates a new team. 3. From the **Team ID-Fallback** dropdown, enter a fallback team for a user who does not have an associated `teamListKey`. 4. From the **Team Name** dropdown, select a report field for the team name. Cortex updates this name if changes are detected in Workday. 5. From the **Team Name-Fallback** dropdown, enter a fallback team name for the fallback team ID defined above. 6. From the **Team Employee Manages** dropdown, select a report field that names the team an employee manages. If you set this, Cortex assigns managers based on this field. If you leave it empty, Cortex uses the person in **Manager Email** as the team's manager.

Set Team Employee Manages if your teams are nested and each one has its own manager. Without it, Cortex assigns the parent team's manager to every child team below it.

For example, if a Customer Experience team has Customer Success, Customer Support, and Customer Education as child teams, leaving Team Employee Manages empty makes the Customer Experience manager the manager of all three.

7. Click **Save**. 2. **One Employee - Multiple Teams (Multiple Fields)** - 1. Click **Add team**. 2. Configure the team: 1. From the **Team ID** dropdown, select a report field for the team ID. New teams are imported based on this ID (required). If the identifier changes, Cortex creates a new team. 2. From the **Team Name** dropdown, select a report field for the team name. Cortex updates this name if changes are detected in Workday. 3. From the **Parent Team ID** Field, select a report field that identifies the parent team. 4. Click **Save**. 3. **One Employee - One Team** -Select this option if your report includes employees who belong to a single team. This is best if you are configuring the integration based on [supervisory orgs](#supervisory-organizations) and/or if users manage teams they belong to. 1. From the **Team ID** dropdown, select a report field for the team ID. New teams are imported based on this ID (required). If the identifier changes, Cortex creates a new team. 2. From the **Team Name** dropdown, select a report field for the team name. Cortex updates this name if changes are detected in Workday. 3. Click **Save**. 3. In the **Hierarchy fields** section, configure the hierarchy fields mappings. This is only required if you want to automatically import Workday teams. Note that you must [enable the option to auto-import Workday teams](/ingesting-data-into-cortex/integrations/workday/using-the-integration-for-workday.md#automatically-import-teams) in order for new teams to be created automatically. Hierarchy relationships are written for existing teams on manual import and whenever hierarchy field mappings are updated, regardless of whether auto-import is enabled. 1. From the **Field on parent team** dropdown, select a report field whose value identifies a team as a parent (required). 2. Optionally, toggle on **Is List** when the parent field holds a list rather than a single value, so one entry can be the parent of several teams. 3. From the **Field on parent team-Fallback** dropdown, select an alternate field for the parent identifier. 4. Optionally, toggle on **Is List-Fallback** so Cortex reads the fallback field when the primary field is missing from a record, which is useful when your report doesn't populate every field on every row. 5. From the **Field on child team** dropdown, select a report field on a team's record whose value points at that team's parent (required). 6. From the **Field on child team-Fallback** dropdown, select an alternate field for the parent pointer. 7. From the **Root Team IDs** dropdown, select the ID for the team you expect to be at the top of the hierarchy. If set, Cortex uses this to [break cycles](/ingesting-data-into-cortex/integrations/workday/using-the-integration-for-workday.md#known-limitations) that may be in the hierarchy. 8. Click **Save**.