Setup

Connect Workday to Ravenna using an Integration System User (ISU) to sync employees and enable time-off workflows.

Connect Workday to Ravenna using an Integration System User (ISU) for secure API access. This setup enables employee sync and time-off workflow actions.

​

Prerequisites

Before you start, make sure you have:

• Workday Security Administrator access (or someone who has it available)
• Permission to create security groups and register API clients
• Access to activate security policy changes

​

Workday configuration

Complete these steps in your Workday tenant to create the integration credentials.

1. Create Integration System User (ISU)

   Search for Create Integration System User and fill in:

   • User Name: ISU_Ravenna
   • New Password: Set a strong password
   • Require New Password at Next Sign In: No
   • Session Timeout Minutes: 0
   • Do Not Allow UI Sessions: Yes

   The ISU is a service account for API access only. Disabling UI sessions prevents interactive logins.

2. Create Integration System Security Group (ISSG)

   Search for Create Security Group and fill in:

   • Type: Integration System Security Group (Unconstrained)
   • Name: ISSG_Ravenna

   After creating it, search Edit Integration System Security Group (Unconstrained), select ISSG_Ravenna, and add ISU_Ravenna to the Integration System Users field.

3. Create User-Based Security Group (USG)

   Search for Create Security Group and fill in:

   • Type: User-Based Security Group
   • Name: USG_Ravenna_Absence_API

   After creating it, search Assign Users to User-Based Security Group, select USG_Ravenna_Absence_API, and add ISU_Ravenna as a member.

   You may see a warning about ISUs in User-Based Security Groups. This is expected and can be ignored. The time-off REST API requires this specific security group type.

4. Configure domain security policies

   Search for Maintain Permissions for Security Group and select ISSG_Ravenna.

   Add these domain security policies:

   Staffing domains:

   Domain Security Policy	View	Modify
   Worker Data: Public Worker Reports	Yes
   Worker Data: Workers	Yes	Yes
   Worker Data: Organization Information	Yes
   Worker Data: Organizations	Yes
   Worker Data: Staffing	Yes

   Contact Information domains:

   Domain Security Policy	View	Modify
   Person Data: Work Email	Yes

   Time Off and Leave domains:

   Domain Security Policy	View	Modify
   Worker Data: Leave of Absence	Yes	Yes
   Worker Data: Time Off	Yes
   Worker Data: Time Off (Time Off Balances)	Yes
   Self-Service: Time Off	Yes
   Access Time Off (Segmented)	Yes

   Organizations and Roles domains:

   Domain Security Policy	View	Modify
   Organization: Supervisory Organization	Yes
   View: Supervisory Organization	Yes
   Manage: Supervisory Organization	Yes	Yes

   Policy names vary by tenant. If a policy is not found, search for similar names. Some policies inherit permissions from parent policies, which is expected.

5. Configure business process security

   Search for Business Process Security Policies and find Request Time Off.

   Edit it and locate the Request Time Off (REST Service) initiating action. Add USG_Ravenna_Absence_API to the Security Groups.

   This grants the ISU permission to submit time-off requests via the REST API.

6. Activate security changes

   Search for Activate Pending Security Policy Changes and run it.

   Review the pending changes and confirm activation. Security changes may take a few minutes to propagate.

7. Register API client

   Search for Register API Client for Integrations and fill in:

   • Client Name: Ravenna Integration
   • Non-Expiring Refresh Tokens: Yes
   • Scope (Functional Areas):
     • Staffing
     • System
     • Time Off and Leave (may be named “Absence Management” in some tenants)

   Save and copy the Client ID and Client Secret. Store them securely.

8. Generate refresh token

   Search for View API Clients, find your client, and select Manage Refresh Tokens for Integrations from the actions menu.

   • Select Workday Account: ISU_Ravenna
   • Check Generate New Refresh Token
   • Click OK

   Copy the refresh token immediately. You will not be able to view it again.

9. Get API endpoints

   Search for View API Clients and select your client.

   Copy these values:

   • Token Endpoint (e.g., https://wd5-services1.myworkday.com/ccx/oauth2/<tenant>/token)
   • REST API Endpoint (e.g., https://wd5-services1.myworkday.com/ccx/)
   • Tenant Name (the segment in the URLs, e.g., mycompany_impl1)

​

Connect to Ravenna

After completing the Workday configuration, you have six values to enter in Ravenna:

Field	Description
Tenant Name	The tenant segment from your Workday URLs
Token Endpoint	OAuth token endpoint URL
REST API Endpoint	Base URL for REST API calls
Client ID	From the API client registration
Client Secret	From the API client registration
Refresh Token	Generated for the ISU

Go to Settings > Integrations > Workday in Ravenna and enter these values to complete the connection.

​

Troubleshooting

403 Permission Denied (S22)

Cause: The ISU does not have the required security permissions, or security changes have not been activated.

Fix:

• Run Activate Pending Security Policy Changes again
• Wait 3-5 minutes for changes to propagate
• Verify the ISU is listed in the ISSG: search View Security Group, select your ISSG, and confirm the ISU appears under Integration System Users
• Verify domain security policies are assigned: search View Security Group, select your ISSG, and check the Domain Security Policy Permissions section

Invalid refresh token

Cause: The refresh token has been revoked or regenerated.

Fix:

• Search View API Clients, find your client, and select Manage Refresh Tokens for Integrations
• Generate a new refresh token
• Update the refresh token in Ravenna’s integration settings

Domain security policy not found

Cause: Policy names vary between Workday tenants.

Fix:

• Search for keywords from the policy name (e.g., “Workers”, “Email”, “Contact”)
• Look for similar policies with different prefixes like “Person Data:” instead of “Worker Data:”
• Select the policy that covers the same data type

Employees are missing after sync

Cause: The sync has not completed, or the worker does not have a work email.

Fix:

• Check the last sync time in integration settings
• Confirm missing employees have valid work email addresses in Workday
• Verify the ISU has View permission on Worker Data: Workers and Person Data: Work Email

Learn more about Workday workflow actions