Skip to main content
Lumos supports 2 Workday connectors: the native Workday connector (documented separately) and Workday RaaS, which syncs workers from custom Workday reports you design. Use RaaS when you want full control over which worker attributes Lumos receives.

​
After this article

You will be able to connect Workday RaaS to Lumos to sync workers from your custom Workday reports and their user-based security groups. In read + write mode, you can also manage security group assignments and update account attributes.

​
Capabilities

Provisioning notes:
  • Admin role required: provisioning and deprovisioning actions require an Administrator, Owner, or equivalent admin role in Workday. Standard users cannot perform these operations even with the right OAuth scopes or API keys.
  • Assign / Unassign Entitlement: security group memberships are added and removed via the Update_User-Based_Security_Group_Assignments SOAP operation.
  • Custom ID updates require the custom ID types to be configured in Workday beforehand and an existing shared reference. Some updates may require business process completion.

​
Required plan and roles

  • Workday role: setup requires a Workday administrator with Report Designer access plus the ability to create Integration System Users, create Security Groups, register API Clients, and activate pending security policy changes.
  • Integration System User (ISU): a dedicated ISU with API access enabled is required. Do not connect with a personal account.
  • ISU security permissions:
    • Run permission on each custom report shared with the integration
    • View domain permissions for every data source used by your reports
  • OAuth client: a registered OAuth 2.0 API client (Client ID + Client Secret). Authentication is OAuth 2.0 with the ISU credentials.
  • Permission scoping: two modes are supported. Read Only syncs account and entitlement data without provisioning. Read + Write additionally enables provisioning/deprovisioning (security group assignment and account attribute updates) via the Workday Human Resources SOAP API. The ISU needs the corresponding write permissions for those operations.
  • Admin role: provisioning and deprovisioning actions require an Administrator, Owner, or equivalent admin role in Workday. Standard users cannot perform these operations even with the right OAuth scopes or API keys.

​
Instructions

Phase 1: Create the custom report in Workday
  1. Open the Create Custom Report task. Configure the report name (e.g. Lumos_User_Access_Report), data source, fields, filters, and optional prompts.
  2. Check Enable As Web Service (required, the integration cannot read the report without it) and Optimized for Performance if available. Matrix reports are not supported.
  3. Column requirements:
    • Required: Employee_ID (accepted variants: employee_id, EmployeeID, employeeID, employeeId). The integration cannot function without it.
    • Recommended: Username (variants: username, User_Name, userName). If omitted, Lumos derives it from the portion of the email address before the @. Also recommended is Email. Lumos resolves email in this order: calculated email field, then Standard Emails, then Standard Public Emails.
    • Set each column’s Column Heading Override XML Alias in snake_case (e.g. EmployeeID → employee_id). For names, Lumos prefers preferred_first_name/preferred_last_name over first_name/last_name.
  4. Test the report, then copy its REST URL: open the report → … → Web Service → View URLs → copy the REST link (format https://{domain}/ccx/service/customreport2/{tenant}/{report_owner}/{report_name}?format=json).
Phase 2: Create the ISU and grant permissions
  1. Open the Create Integration System User task. Set a user name (e.g. ISU_Lumos_RaaS), set a session timeout, check Do Not Allow UI Sessions, and click OK.
  2. Open the Create Security Group task and create an Integration System Security Group (e.g. Lumos RaaS Integration Security Group), then assign the ISU to it.
  3. For each custom report, use Share Report and add the security group with Run permission.
  4. Grant the security group View domain permissions for each report data source (via View Domain).
  5. Run Activate Pending Security Policy Changes. Permissions do not take effect until activated.
Phase 3: Register the OAuth 2.0 client
  1. Open the Register API Client for Integrations task.
  2. Set Client Name (e.g. Lumos Integration - RaaS), Client Type Confidential, Grant Types Authorization Code and Refresh Token, the Redirect URI provided by Lumos, and Scope System.
  3. Click OK, then copy the Client ID and Client Secret immediately and store them securely.
Phase 4: Connect in Lumos
  1. Find the Workday RaaS card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Enter the Tenant Name, Tenant Environment (Production / Implementation / Sandbox), Client ID, Client Secret, ISU Username, and ISU Password.
  3. Add each custom report: Report Name, Report Owner, Report Path, and the data mapping. Configure the format (JSON recommended, CSV supported), pagination, and any report prompts.
  4. Click Authorize and complete the Workday OAuth flow in the popup.
  5. Click Test Reports to validate, then finish connecting.

​
Settings

​
API Endpoints Used

​
Troubleshooting

OAuth authentication failed. Verify the Client ID and Client Secret were copied correctly, the OAuth client is active (not expired) in Workday, the redirect URI matches exactly, and the ISU credentials are correct. Re-run Activate Pending Security Policy Changes if permissions were changed recently. Insufficient permissions. Review the ISU’s security group assignments: Run permission on each specific report, View permission on each report data source, and access to every field included in the report. Pending security policy changes must be activated. Report execution times out. Optimize the report (reduce columns, add filters, enable Optimized for Performance), add date-range filters, or break large reports into smaller ones. If the report runs quickly in Workday but the Lumos sync still times out on a large report, enable Exclude SOAP API Calls (see Settings) so Lumos stops calling Get_Workers per worker. Data not appearing after sync. Verify the report returns data when run manually as the ISU, check the data mapping configuration, confirm column names match the mapping (snake_case XML aliases), and review sync logs for parsing errors. Missing or null field values. Confirm the fields are in the report definition, check for security-based field-level restrictions on the ISU, and verify conditional field visibility. Inconsistent data between syncs. Check report filters for relative-date dependencies and effective dating. Ensure the report returns current data rather than a historical snapshot. Worker types missing. External suppliers/buyers are not synced as users.