Workday RaaS Connector

The Workday connector reads workers, optional groups, and optional group membership from JSON custom reports exposed with Workday Report-as-a-Service (RaaS). It does not use the Workday REST, SOAP, or Graph APIs.

Workday custom report columns are tenant-defined. Roster therefore defines a small report contract that you can satisfy with your tenant’s existing fields and Roster field mappings.

Recommended Minimum

Start with one users report. This is enough to search for and select individual workers in Roster.

Roster connector field	Recommended value
Name	Workday
Directory role	Primary, unless this connector enriches an existing primary directory
Users report URL	Workday-generated JSON URL for the users custom report
Groups report URL	Leave blank
Group members report URL	Leave blank
Username	Dedicated Workday report user
Password reference	env:WORKDAY_REPORT_PASSWORD
Refresh schedule	Keep the default 0 * * * * unless you need another schedule

Add the two optional group reports only when users need to select Workday groups or resolve their direct members.

1. Create the Users Report in Workday

Create an advanced custom report for the workers who can be selected in Roster. Workday’s web service best practices recommend using a custom report instead of integrating directly with a standard report, and enabling that custom report as a web service.

Use a name such as:

Roster Users

Recommended report design:

1. Choose a worker data source that your dedicated report user can access.
2. Include only workers eligible for selection in Roster, typically active workers.
3. Add the four columns below.
4. Enable the report as a web service.
5. Grant the dedicated report user only the report and underlying domain access it needs.

JSON key expected by the default Roster mapping	Requirement	Recommended Workday value
external_id	Required	Stable worker identifier, such as Worker ID or Employee ID when stable in your tenant
display_name	Recommended	Worker display or preferred name
primary_email	Recommended	Primary work email
user_name	Optional	Workday user name or another stable login; Roster falls back to primary_email

If Workday emits different JSON keys, keep the Workday report as-is and configure the corresponding Roster field mappings. You do not need to rename tenant fields merely to match this example.

Mock Users Response

The documented users-only configuration is tested with this response:

{
  "Report_Entry": [
    {
      "external_id": "W-1001",
      "display_name": "Ada Lovelace",
      "primary_email": "ada.lovelace@example.com",
      "user_name": "ada.lovelace"
    }
  ]
}

Roster also accepts a JSON array directly and these row collection names:

Report_Entry
report_entry
entries
items
value

The collection can be nested under Report_Data, report, or data.

2. Copy and Verify the JSON URL

Copy the JSON URL generated by Workday for the custom report. The exact tenant hostname and path are tenant-specific. Ensure the selected URL returns JSON; classic report URLs commonly use format=json.

Example shape only:

https://wd.example.com/ccx/service/customreport2/acme/roster/Roster_Users?format=json

Before configuring Roster, make one authenticated GET request with the dedicated report user. Verify that:

• the response is successful JSON
• the row collection is one of the supported shapes
• every row has a non-empty, unique, stable external ID
• the report contains only the workers Roster should expose
• the report does not require an interactive SSO or MFA prompt

Roster sends the configured username and password with HTTP Basic authentication. Store the password in the deployment’s secret manager or protected environment file:

WORKDAY_REPORT_PASSWORD=replace-with-the-report-user-password

Do not put the password in the report URL or in the Roster connector form.

3. Configure Roster

In Connectors, select New connector, choose Workday, and enter the recommended minimum values:

Users report URL:
https://wd.example.com/ccx/service/customreport2/acme/roster/Roster_Users?format=json

Groups report URL:
(blank)

Group members report URL:
(blank)

Username:
roster_report_user

Password reference:
env:WORKDAY_REPORT_PASSWORD

Keep the default users field mapping when the report uses the mock response keys:

{
  "display_name": "display_name",
  "external_id": "external_id",
  "primary_email": "primary_email",
  "user_name": "user_name"
}

If the report returns tenant-specific keys, select Edit field mapping and map each Roster field to the actual JSON key. For example:

{
  "display_name": "Worker_Display_Name",
  "external_id": "Worker_ID",
  "primary_email": "Primary_Work_Email",
  "user_name": "Workday_User_Name"
}

Mappings are case-sensitive. A mapping value can also be a dot-separated path for nested JSON, such as worker.id.

Save the connector, then search for the mock or test worker from a participant picker. Selecting the worker materializes that directory record in Roster.

Optional Group Support

Groups are not required for an individual-worker directory. To support Workday groups:

1. Add a groups report to enable group search and selection.
2. Add a group members report to expand selected groups into their direct members.
3. Keep all Workday report URLs on the same origin as the users report URL.

The groups report uses this default contract:

{
  "Report_Entry": [
    {
      "external_id": "ORG-100",
      "display_name": "Engineering",
      "mail": "engineering@example.com"
    }
  ]
}

Groups key	Requirement
external_id	Required and unique
display_name	Recommended
mail	Optional

The group members report links the external IDs from the users and groups reports:

{
  "Report_Entry": [
    {
      "group_external_id": "ORG-100",
      "user_external_id": "W-1001"
    }
  ]
}

Roster also accepts group_id, organization_external_id, or organization_id for the group reference, and worker_external_id, member_external_id, user_id, worker_id, or member_id for the direct member reference.

Membership rows whose group or member is absent from the corresponding report are ignored. Duplicate membership rows are collapsed. A group members report without a groups report cannot resolve membership and should remain blank.

Security and Production Requirements

• Use a dedicated, least-privileged Workday report user.
• Limit the custom reports to the records and fields Roster needs.
• Keep the password in a secret manager or protected environment configuration.
• Keep every configured report URL on the users report URL’s origin. Roster rejects cross-origin credentialed report requests.
• Prefer stable identifiers over names, email addresses, or descriptors.
• Validate reports and security changes in a non-production tenant before production use.
• Review Workday’s current integration and web service limits when sizing the reports.

How Roster Uses the Reports

Roster uses Workday live when an administrator searches Workday users or groups from a participant picker. When the administrator selects a user or group, Roster caches that record. Selecting a group also caches its direct members and membership edges for participant resolution.

MCP and REST directory-record search uses only Roster’s cached records and does not call Workday live.

Reports are loaded lazily and cached for the lifetime of the connector client:

• user searches and lookups load only the users report
• direct group lookups load only the groups report
• participant-picker group searches also calculate direct member counts, so they load the configured users and membership reports when group membership support is enabled
• direct membership lookups load the configured users, groups, and membership reports

Filtering and cursor paging happen in Roster after the relevant report is downloaded. Roster does not send a search query or cursor to RaaS, so keep reports appropriately scoped and sized.

Roster retries Workday HTTP 429 and 500 responses up to three total attempts. When Workday returns Retry-After, Roster uses the requested delay up to a five-second maximum per retry so interactive requests stay within their time budget. Otherwise, it uses bounded exponential backoff. Authentication, authorization, malformed JSON, and other non-transient failures are returned without retrying.

Client Acceptance Checklist

The users-only mock configuration and the complete users/groups/memberships configuration are covered by automated integration tests. Complete these tenant-specific checks before enabling a customer connector:

1. Search for a known worker and select that worker.
2. Confirm the selected worker appears under directory records.
3. If groups are configured, search for a known group and verify its direct members.
4. Change a test worker or membership in Workday and run the scheduled refresh.
5. Confirm participant resolution uses the refreshed cached record.
6. Confirm expected behavior for terminated, inactive, or otherwise excluded workers.

These checks validate the customer’s report definitions, security policy, credentials, row volume, and actual Workday response shape without requiring a different Roster implementation for every tenant.