> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workday RaaS

*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

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | No | Workers synced from your custom report (extended attributes via `Get_Workers`). Provisioning is limited to account updates: username, password, work email, disabled status, expiration date, and the predefined custom IDs `samAccountname` and `immutableID` |
| Security Groups | Permission | Yes | Yes | User-based security group assignments, which Lumos can assign and unassign |

**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

| Setting | Description |
| - | - |
| Exclude SOAP API Calls | By default Lumos calls `Get_Workers` once per worker in your report to add the `samAccountName` and `immutableID` custom IDs to each account. On large reports these per-worker calls can make the sync time out. Turn this on to list accounts from the report alone; the two custom ID attributes are then not synced. |

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## 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.