Workday

Configuring the integration for Workday

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.

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, expand Integrations, then select Configurations.

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.

To modify an existing configuration, see Modifying an integration configuration.

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.

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.

To configure report mappings:

1. From the main sidebar, expand Integrations, then select Configurations.

2. Locate Workday, then click Settings.

   
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 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 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 that may be in the hierarchy.

      8. Click Save.