Docs

Integrations / HR systems / Workday

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:

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.

  1. Open the Workday dialog

    Go to Settings > Integrations and click Workday. On the API client card, click Connect.

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

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

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

  5. 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
  6. 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.

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

DomainPermissionPurpose
Worker Data: Public Worker ReportsGetWQL queries to resolve workers by email
Worker Data: WorkersGetRetrieve worker details (job title, manager, org)
Worker Data: Current Staffing InformationGetResolve person ID from worker ID via Staffing service
Worker Data: All PositionsGetCurrent and historical position details
StaffingGetGeneral staffing service access
System: Workday Query LanguageGetExecute WQL queries
System: Worker Event HistoryGetRead worker event history

Personal data

DomainPermissionPurpose
Person Data: Personal DataGetGet personal data
Person Data: Personal InformationGetGet personal information fields

Home address

DomainPermissionPurpose
Person Data: Home Contact InformationGet and PutRead home addresses and update them within a change event
Person Data: Home AddressGet and PutSecures Change Home Contact Information (REST Service)
Self-Service: Home AddressGet and PutSecures Change Home Contact Information (REST Service) initiated on behalf of the worker
Person Data: Work Contact InformationGetRead work contact information

Time off and absence

DomainPermissionPurpose
Worker Data: Time OffGet and PutPTO balances, time off entries, eligible types, and submitting time off requests
Absence ManagementGet and PutAbsence management operations
Worker Data: Absence BalancesGetRetrieve PTO balances
Self-Service: Time Off and Leave BalancesGetRetrieve 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.

TemplateWhat the agent doesTools it needs
Workday Time Off RequestLooks 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 BalanceLooks 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 UpdateLooks 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 LookupLooks 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.

  1. Find the Workday templates

    Go to Runbooks and click Browse templates. Type Workday in Search templates. The HR group lists the time off and home address templates.

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

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

  4. 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:

ToolWhat it does
Get Workday Employee InfoReads the employee's worker record from Workday
Get Workday Time Off BalanceReads the employee's balances and the time off types they can request
Request Workday Time OffSubmits a time off request in Workday
Get Workday Home AddressReads the employee's home address
Update Workday Home AddressChanges the employee's home address in Workday
Get Workday Job RequisitionReads 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