Workday
Connect Workday to Risotto with an API client and an Integration System User, then use the Workday runbook templates for time off and home address requests
Connect Workday as your HRIS to power employee self-service. Once Workday is connected:
- The support agent can look up the requester's employee record. Turn this on with Agent access on the People tab of Support agent > Context.
- The Workday runbook templates handle time off and home address requests. See Set up time off and home address requests.
Connect from the dashboard
Workday is in the HRIS category of Settings > Integrations. The Workday dialog has two parts: the form, and an Instructions pane with the Workday setup steps. On a narrow screen, the instructions are collapsed under Instructions.
Open the Workday dialog
Go to Settings > Integrations and click Workday. On the API client card, click Connect.
Generate the certificate and private key
Click Generate certificate & private key. Risotto creates a self-signed certificate and PKCS#8 private key (RSA 2048, roughly 10-year validity), saves the private key, and shows the certificate PEM. Click Copy to copy the certificate for your Workday tenant.
Each click creates a new key pair and replaces the previous one. If you click the button again, put the new certificate in Workday too. Workday refuses the connection if its public key does not match the key that Risotto saved.
Register the public key in Workday
Run the Create x509 Public Key task in Workday. Paste the certificate PEM from the previous step and set Name to
risotto_workday_integration_key.Create the Integration System User
Create an Integration System User (ISU) and assign the domain security and/or user security groups described under ISU security configuration so the user can read and update the worker data Risotto uses.
Register an API client in Workday
Register an API client with these settings:
- Client Grant Type: JWT Bearer Grant
- x509 Certificate: the certificate that you registered in Workday
- Access Token Type: Bearer
- Scopes (Functional Areas): the areas under API client scopes
Fill in the form and save
Enter the values under Required information and click Save. A toast confirms "Workday settings saved". If you have not generated a certificate yet, Risotto shows "Generate a certificate and private key first" and saves nothing.
Test the connection
Click Test connection. The button is available after you save, while the form has no unsaved changes. When Workday accepts the credentials, the dialog shows Connected. Otherwise it shows the error from Workday. Click Close to close the dialog.
After you save, the API client card shows the Tenant URL, Tenant Name, Client ID, Integration system user and a masked Private key. To change the values, click Connected on the card, then click Configure....
Required information
To connect Workday, provide:
- Integration System Username (required): The Integration System User account Risotto will authenticate as, for example
integration_user - Client ID (required): The API client ID, a UUID in the form
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - Tenant URL (required): The host of your Workday API, without a path. Copy it from the Token Endpoint of the Risotto API client in Workday (run View API Clients).
- Tenant Name (required): The name of your Workday tenant. It is the part of the Token Endpoint after
/ccx/oauth2/. Only letters, numbers, underscores, and hyphens are allowed.
The private key is not a field. Risotto saves it when you click Generate certificate & private key.
Risotto builds the token URL as <Tenant URL>/ccx/oauth2/<Tenant Name>/token. This URL must be the same as the Token Endpoint in Workday. For example, if the Token Endpoint is https://wd5-services1.myworkday.com/ccx/oauth2/acme/token, enter:
- Tenant URL:
https://wd5-services1.myworkday.com - Tenant Name:
acme
ISU security configuration
The ISU must have domain security in Workday, and the API client must have matching functional area scopes. Without these, Risotto cannot read or write the corresponding worker data, even if the tool that needs it is on.
When a domain is missing, Workday refuses the request with a permission error. The tools Get Workday Employee Info, Get Workday Home Address, Get Workday Time Off Balance, and Update Workday Home Address then tell the agent that Workday is not configured correctly, and your admins get one alert for each tool: "Workday denied access to this data. Make sure the integration system user's security group has the required domain permissions in Workday." Add the missing domain to the ISU's security group in Workday.
Domain security policies
Assign these to the ISU's integration security group. Domain names can vary slightly by tenant, search Domain Security Policies in Workday for the closest match.
Worker lookup
| Domain | Permission | Purpose |
|---|---|---|
| Worker Data: Public Worker Reports | Get | WQL queries to resolve workers by email |
| Worker Data: Workers | Get | Retrieve worker details (job title, manager, org) |
| Worker Data: Current Staffing Information | Get | Resolve person ID from worker ID via Staffing service |
| Worker Data: All Positions | Get | Current and historical position details |
| Staffing | Get | General staffing service access |
| System: Workday Query Language | Get | Execute WQL queries |
| System: Worker Event History | Get | Read worker event history |
Personal data
| Domain | Permission | Purpose |
|---|---|---|
| Person Data: Personal Data | Get | Get personal data |
| Person Data: Personal Information | Get | Get personal information fields |
Home address
| Domain | Permission | Purpose |
|---|---|---|
| Person Data: Home Contact Information | Get and Put | Read home addresses and update them within a change event |
| Person Data: Home Address | Get and Put | Secures Change Home Contact Information (REST Service) |
| Self-Service: Home Address | Get and Put | Secures Change Home Contact Information (REST Service) initiated on behalf of the worker |
| Person Data: Work Contact Information | Get | Read work contact information |
Time off and absence
| Domain | Permission | Purpose |
|---|---|---|
| Worker Data: Time Off | Get and Put | PTO balances, time off entries, eligible types, and submitting time off requests |
| Absence Management | Get and Put | Absence management operations |
| Worker Data: Absence Balances | Get | Retrieve PTO balances |
| Self-Service: Time Off and Leave Balances | Get | Retrieve time off and leave balances |
API client scopes
When you register the API client in Workday, grant these functional areas:
- Staffing: worker lookup, initiate home contact information changes
- Personal Data: read personal information
- Contact Information: read and update home addresses
- Time Off and Leave: PTO balances, time off entries, eligible types, and time off requests
- Absence Management: PTO balances and time off requests
- System: WQL support and REST API routing
- Tenant Non-configurable: global scope required for WQL and People resources
Set up time off and home address requests
Time off and home address requests use the Workday runbook templates in Runbooks > Templates. Each template needs Workday tools, which you create from the template's page.
| Template | What the agent does | Tools it needs |
|---|---|---|
| Workday Time Off Request | Looks up the requester's balances and submits time off requests in Workday. Changes to booked time off go to HR. | Get Workday Time Off Balance, Request Workday Time Off |
| Workday Time Off Balance | Looks up the requester's balances. Escalates every request to take, change, or cancel time off to HR. | Get Workday Time Off Balance |
| Workday Home Address Update | Looks up the requester's home address, confirms the new address with them, and saves it in Workday. | Get Workday Home Address, Update Workday Home Address |
| Workday Home Address Lookup | Looks up the requester's home address. Collects a new address and escalates the change to HR. | Get Workday Home Address |
Each pair matches the same requests, so turn on only one template of each pair. The other Workday templates are Workday Support, which gives guidance from your knowledge base and Workday's documentation, and Workday Job Requisition Lookup. If Workday Support is on, it also matches some time off and address requests. Remove those terms from its conditions, or turn it off.
Find the Workday templates
Go to Runbooks and click Browse templates. Type
Workdayin Search templates. The HR group lists the time off and home address templates.Open a template
Click the template, for example Workday Time Off Request. The page shows the template's match condition, its agent instructions, the Required tools, and Tips in the side panel.
Create the required tools
Under Required tools, click Create beside each tool that shows Not set up. The tool editor opens for that tool. Keep Restrict to Requestor Only on, so the tool works only on the requester's own record. To have a person review each time off request or address change before it reaches Workday, turn on Requires Approval on the request or update tool. Save the tool, and the dashboard returns to the template. If a tool shows Disabled, click Enable.
Use the template
Click Use this template. The button is available once every required tool is ready. If your organization has more than one tool for a required tool, the Choose tool instances dialog asks which one to use: pick one for each and click Continue. The runbook editor opens with the template filled in. Save the runbook and turn it on, as in Create a runbook.
The templates act only for the requester. Before the agent submits time off or changes an address, it confirms the details with the requester and waits for their reply.
Runbook tools
You can also add Workday tools to your own runbooks. Create them on the Tools page:
| Tool | What it does |
|---|---|
| Get Workday Employee Info | Reads the employee's worker record from Workday |
| Get Workday Time Off Balance | Reads the employee's balances and the time off types they can request |
| Request Workday Time Off | Submits a time off request in Workday |
| Get Workday Home Address | Reads the employee's home address |
| Update Workday Home Address | Changes the employee's home address in Workday |
| Get Workday Job Requisition | Reads the details of a job requisition |
- Each employee tool has a Restrict to Requestor Only option, which is on by default. When it is on, the tool works only for the requester of the ticket.
- Request Workday Time Off needs the employee's confirmation, given after the agent asks for it. It does not submit a request for a time off type the employee cannot use, for dates that already have time off, or for more time than the balance allows.
Disconnecting
To disconnect Risotto from Workday, click Connected on the API client card, then click Disconnect.... In the Disconnect from Workday? dialog, click Disconnect. Risotto clears the saved Workday settings, and the Workday tools stop working.
Something wrong or missing? Report an issue · View as Markdown