Integrate Workday

Integrate with Workday to make it easy to submit requests, receive notifications about request status, and act on notifications.

Integrate with Workday to make it easy to submit requests, receive notifications about request status, and act on notifications. After you complete this process, your existing level of audit logging persists, including any actions carried out by the use of Citrix Microapps. Use the following process to enable the Workday Integration.

For a comprehensive list of out-of-the-box Workday microapps, see Use Workday microapps.

Before setting up the integration in Microapps, ensure you meet the prerequisites and then complete the following procedures:

  • Enable API access by registering an API Client and generating and collecting the Client ID and Client Secret.
  • Create custom reports.
  • Generate custom report URLs.
  • Generate custom report path.
  • Filter PTO Types to restrict PTO microapps to specific time-off types.
  • Set up deep linking in Workspace.
  • Edit business process for time-off requests.
  • Manage security group permissions.
  • Identify your URL, Instance URL, and Tenant.

Review prerequisites

This set up process requires you to have an admin account and the following service account privileges for the Workday connector.

  • Access to the creation of non-temporary custom reports.
  • Access to HumanResources, Integrations, PerformanceManagement, ResourcesManagement, and custom reports APIs.
  • For downloading milestone data, part of the deep link set-up process, you need the following security groups assigned to the admin:
    • HR Administrator
    • Information Administrator
  • Configure Citrix Gateway to support single sign-on for Workday so that once users log in they are automatically logged in again without having to enter their credentials a second time. Follow the instructions in Workday Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

After you set up this integration in Workday, you need these artifacts to enter these account credentials when you set up the integration in Microapps:

  • URL
  • User Name
  • Tenant
  • Password
  • Client ID
  • Client Secret
  • Workday REST API Endpoint
  • Token Endpoint
  • Authorization Endpoint
  • Custom report URLs collected

Register Workday API Client

Register an API client to generate a Client ID and Client Secret for each environment. If you have multiple environments, you must register an API Client for each individual environment.

  1. Log in to Workday as an admin, and search for Register API Client. Complete the required fields:

    • Enter your Client Name.
    • Select Authorization Code Grant for Client Grant Type.
    • Select Bearer for Access Token Type.
    • Enter the Redirection URI: https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback. The callback depends on the target application, and can be found in your URL address bar when creating the integration. The section {yourmicroappserverurl} is composed of a tenant part, a region part, and an environment part: https://{tenantID}.{region(us/eu/ap-s)}.iws.cloud.com.
    • Enter the value 300 for Refresh Token Timeout (in days).
    • Select the following Scope (Functional Areas):
      • Organizations and Roles
      • Staffing
      • Tenant Non-Configurable
  2. Select OK. The Client ID and Client Secret are generated. Collect and save for later use during the set-up process.

  3. Select Done to complete and exit.

Create custom reports

You create custom reports in Workday for each of the following reports. Download the attached spreadsheets and complete the details precisely as described in the spreadsheet. If any detail you enter differs from the provided report, the process does not work. For example, if you use an incorrect name, the report is generated, but no data is downloaded.

The following reports are the current reports. When we add new end-points to this integration, they are added here in the product documentation.

  1. Open one of the following custom report spreadsheets:

  2. In Workday, search for Create Custom Report.
  3. Enter a Report Name. This name must be identical to the spreadsheet of the report that you want to create a URL for.
  4. Select Advanced as Report Type.
  5. Enter the Data Source. This value must be identical to the spreadsheet of the report that you want to create a URL for.
  6. Do not select the Optimized for Performance check box.
  7. Do not select the Temporary Report check box.
  8. Select the Enable As Web Service check box.
  9. Select OK.

    The custom report opens unpopulated except for the three fields you entered.

  10. Complete the details exactly as described in the spreadsheet. Pay attention to the headings. The headings match the tabs in the Workday UI.
  11. The field Column Heading Override XML Alias is auto-generated as you are populating the columns. Verify that the value in Column Heading Override XML Alias matches the spreadsheet instructions. This value often varies.
  12. Select OK. The custom report is created.

Generate custom report URLs

To download data and generate notifications for the custom reports, you must generate the custom report URLs and download the WSDL. You need these URLs to complete the Microapps set-up procedure.

  1. In Workday, open a custom report that you created.
  2. Select Actions and select the name of the report to open settings.
  3. Select Actions > Web Service > View URLs > WSDLs.
  4. Enter any date in Entered On field.
  5. Right-click on the WSDL link under Workday XML section and select Copy URL. (Example URL: https://wd2-impl-services1.workday.com/ccx/service/customreport2/company_tenant/user_name/report_name?wsdl)

Save the URL for use when you set up the microapp in the Add the integration to Citrix Workspace Microapps procedure.

Generate custom report path

You collect the custom report path by using the generated WSDL from the previous procedure. Use this when you enter the custom report URL for Time off types per plan report path amd Event records for milestone path in the set-up procedure.

  1. Open the generated WSDL link in your browser.
  2. Scroll to the bottom and locate two URLs. The second one has the name ReportREST. This is the one we want to use.
  3. Copy the the path from this URL and use it when setting up the Workday integration. (Example path: </ccx/service/customreport2/company_tenant/user_name/report_name>.

Filter PTO Types

Restrict PTO microapps to specific time-off types, such as vacation, or sick leave. If you created the following custom reports in Workday, you need to create calculated fields in Workday and filter custom reports using the following procedures.

  • Event Records for time off requests
  • Time off request details
  • Time off types per plan

Create calculated fields for PTO Requests microapp

You need to create two calculated fields. The first calculated field is intended to retrieve the Absence Type from the Time Off Event so it is available in second calculated field. The second calculated field is used as the filter in the custom report.

  1. Log in to your Workday instance and search for create calculated field.
  2. Complete all fields:
    • Field Name Enter a name for the calculated field. For example, SANDOVAL CF LRV Absence Type from this format: {(report creator)(CF=calculated field)(LRV=lookup related value)(values this field returns)}.
    • Business Object Find and select Time Off Event. We want our calculated field to be part of this business object.
    • Function Find and select Lookup Related Value.
  3. Select OK at bottom left.
  4. Under the Calculation tab, complete these fields:
    • Lookup field Find and select Time Off Event.
    • Return Value Find and select Time Off Types for Time Off Event
  5. Select OK and then Done.

You created a calculated field. Now, let’s create the second field that retrieves the Time Off Event and will be used as the filter.

  1. Again, from your Workday instance search for create calculated field.
  2. Complete all fields:
    • Field Name Enter a name for the calculated field. For example, SANDOVAL CF LRV Time Off Event for Business Process from this format: {(report creator)(CF=calculated field)(LRV=lookup related value)(values this field returns)}.
    • Business Object Find and select Action Event. We want our calculated field to be part of this business object.
    • Function Find and select Lookup Related Value.
  3. Select OK at bottom left.
  4. Under the Calculation tab, complete these fields:
    • Lookup field Find and select Time Off Event.
    • Return Value Find and select the first calculated field you created. In our example, SANDOVAL CF LRV Absence Type.
  5. Select OK and then Done.

Filter a custom report using calculated field for PTO Requests microapp

Add a filter to the custom report related to PTO approval using the new calculated field that you just created to whitelist PTO Types, which will allow you to get all PTO types you select.

  1. From your Workday instance search for Edit Custom Report and select a custom report related to PTO approvals, in our case Event Records for Time Off Requests.
  2. Select Filter tab and + to add new filters.
  3. Complete these fields:
    • And/Or And
    • *Field Find and select the second calculated field you created, in our example SANDOVAL CF LRV Time Off Event for Business Process.
    • *Operator Find and select any in the selection list.
    • Comparison Type Find and select Value specified in this filter.
    • Comparison Value Find and select the PTO types that you want to whitelist, for example:
      • Annual Leave (Days)
      • Annual Leave (Statutory)
      • Personal Leave (Days)
      • Sick (Days)
      • Time Off
  4. Select OK to save.

Note:

To block PTO Types, change field: *Operator to none of the selection list. This blocks the integration from getting any selected PTO types.

Filter a custom report using an existing field for Create PTO Requests and My PTO Requests microapps

Filter Time off types per plan custom report.

Note:

We recommend using the same PTO types in all custom reports. This way if you decide to whitelist or block the outcome, the values in Comparison Value is the same for all custom reports).

  1. From your Workday instance search for Edit Custom Report and select a custom report related to PTO approvals, in our case Time off types per plan.
  2. Select Filter tab and + to add new filters.
  3. Complete these fields:
    • And/Or And
    • *Field Find and select the custom report Time Off Type.
    • *Operator Find and select in the selection list.
    • Comparison Type Find and select Value specified in this filter.
    • Comparison Value Find and select the PTO types that you want to whitelist, for example:
      • Annual Leave (Days)
      • Annual Leave (Statutory)
      • Personal Leave (Days)
      • Sick (Days)
      • Time Off
  4. Select OK to save.

Filter Time off request details custom report.

  1. From your Workday instance search for Edit Custom Report and select a custom report related to PTO approvals, in our case Time off request details.
  2. Select Subfilter tab and select + to add new subfilters, similar to how you added filters.
  3. Complete these fields:
    • And/Or And
    • *Field Find and select the custom report Time Off Type for Time Off Entry.
    • *Operator Find and select in the selection list.
    • Comparison Type Find and select Value specified in this filter.
    • Comparison Value Find and select the PTO types that you want to whitelist, for example:
      • Paid Time Off (Days)
      • Sick (Days)
      • Sick (Hours)
  4. Select OK to save.

If you are referred to this article, contact your administrator and request that they set up deep linking for Citrix Workspace Microapps in Workday.

The following use-cases require the corresponding deep links. For example, if your domain is impl.workday.com and your tenant is citrix_gms2v, then the URL for Create expense report is: https://impl.workday.com/citrix_gms2/d/task/2997$995.htmld:

  • Create Expense Report https://your_domain/your_tenant/d/task/2997$995.htmld

  • Create Milestone https://your_domain/your_tenant/d/task/2998$8704.htmld

  • Create Change Job https://your_domain/your_tenant/d/task/2997$4819.htmld

  • Approve/Deny Change Job (Change Job Requests) https://your_domain/your_tenant/d/unifiedinbox/initialinbox/2998$17139.htmld

Note:

If you do not have this data stored, log in to your Workday account and copy them from the URL. These deep links must be set up with every newly added integration.

Edit business process for time-off requests

Depending on the Workday tenant that you are using, you have a business process established for creating time-off requests. Modify that business process as shown in the following steps.

  1. In Workday, search for bp: request time off, and then select Request Time Off for Global Modern Services.
  2. Go to Actions > Business Process > Edit Definition.
  3. Do not change Effective Date unless required, and select OK.
  4. Under Business Process Steps, select the + icon to add a new row.
  5. Enter b for Order.
  6. Enter Approval for Type.
  7. Select Manager for Group from the menu.
  8. Select OK, and then Done.

Manage security group permissions

To enable proper security permissions for your security group, you complete two procedures. First add permissions to the group and activate the settings. Then add the security group to view all list and activate the settings.

Add and activate integration permissions

  1. In Workday, search for view security group.
  2. Search for the security group that you need, select it, and select OK.
  3. Go to Actions > Security Group > Maintain Security Permissions.
  4. Under the section Integration Permissions, search for the following list of permissions in the Domain Security Policies permitting Get access field, and add them all. Do not use colons (:) in your search:

    Workday integration permissions

    • Manage: Organization Integration
    • Worker Data: Public Worker Reports
    • Set Up: Spend Categories
    • Worker Data: Headcount Reports
    • Business Process Administration
    • Business Process Reporting
    • Set Up: Expense Item
    • Process: Purchase Order – View
    • Process: Expense Report – View
    • Worker Data: Active Employees
    • Worker Data: Current Staffing Information
    • Worker Data: Time Off (Time Off Balances)
    • Worker Data: Time Off (Time Off)
    • Worker Data: Time Off
  5. Select OK, review, and then select Done.
  6. Search for Activate Pending Security Policy Changes.
  7. In the Comment field, type Activate, and select OK.
  8. Select the Confirm check box, and then select OK. Permissions have been updated and activated.

Add and activate security group to view all list

  1. Search for bp:change job and select Change Job for Global Modern Services.
  2. Go to Actions > Business Process > Edit.

    Workday business process screen

  3. Scroll to the section View All. Add your security group to the list of security groups that can view all.
  4. Select OK, and then Done.
  5. Search for Activate Pending Security Policy Changes.
  6. In the Comment field, type Activate, and select OK.
  7. Select the Confirm check box, and then select OK. Permissions have been updated and activated.

You can view your security group by searching for View security group and selecting your security group. There are now two tabs, Domain Security Policy Permissions and Business Process Security Policy Permissions.

Find your base URL

You need to enter the base URL (domain) for your Workday environment to enable API calls. The format is https://{domain}.workday.com. For example, if the Workday REST API Endpoint is https://wd2-impl-services1.workday.com/ccx/api/v1/citrix_gms, your base URL is wd2-impl-services1. Follow the following procedure to identify your base URL.

  1. Log in to Workday as an admin and search for View API Clients.
  2. Look at the first field called Workday REST API Endpoint. The format is https://{domain}.workday.com/ccx/api/v1/{tenant}.

Add the integration to Citrix Workspace Microapps

Add the Workday integration to Citrix Workspace Microapps to connect to your application. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace.

Follow these steps:

  1. From the overview page, select Get Started.

    The Manage Integrations page opens.

  2. Select Add New Integration, and Add a new integration from Citrix-provided templates.
  3. Choose the Workday tile.
  4. Enter an Integration name.
  5. Enter the Connector parameters that you collected as prerequisites.
    • Enter your URL to enable API calls. This is the domain for your Workday environment, for example wd2-impl-services1. For more information about identifying your base URL, see Find your base URL.
    • Enter your Workday instance for Instance URL. Find your instance domain by logging into your Workday environment, and copying the instance url. For example, https://impl.workday.com.
    • Enter your Workday Tenant location. Find an example of identifying the Workday tenant in Find your base URL.
    • Enter your Client ID and Client Secret collected in Prerequisites procedure.
    • Enter your Username and Password.
    • Enter the Days to load to set the day limit when loading data.
  6. Toggle Enable Time off module? to Yes if you create time-off requests that Workday calculates and you want the data downloaded and notifications generated based on the data. You collected these URLs and paths in the procedure Generate custom report URLs and Generate custom report path.

    • Enter the custom report URL for Time off request details report URL.
    • Enter the custom report path for Time off types per plan report path.
    • Enter the custom report URL for Event records for time off requests report URL.
  7. Toggle Enable change job module? to Yes if you create change jobs requests that Workday calculates and you want the data downloaded and notifications generated based on the data. You collected these URLs in the procedure Generate custom report URLs.

    • Enter the custom report URL for Event records for change job report URL.
    • Enter the custom report URL for Staffing activities report URL.
  8. Toggle Enable expense module? to Yes if you create expense reports that Workday calculates and you want the data downloaded and notifications generated based on the data. You collected these URLs in the procedure Generate custom report URLs.

    • Enter the custom report URL for Event records for expenses report URL.
  9. Toggle Enable purchase orders module? to Yes if you create purchase orders and you want the data downloaded and notifications generated based on the data. This uses a publi API and does require a custom report.

  10. Toggle Download milestone items? to Yes if you create milestone items and you want the data downloaded and notifications generated based on the data. You collected these paths in the procedure Generate custom report path.

    • Enter the custom report path for Event records for milestone path.
  11. Select Add.

The Microapp Integrations page opens with your added integration and its microapps. From here you can add another integration, continue setting up your out-of-the-box microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization.

For more information, see Verify needed entities and Set data synchronization in the Configure the integration article.

For more details of API endpoints and table entities, see Workday connector specifications.

Use Workday microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs. Our Workday integration comes with the following preconfigured out-of-the-box microapps:

Change Job Request: View and approve change job requests.

Notification or Page Use-case workflows
New Change Job Request for Approval notification When a new change job approval request is submitted, approver receives a notification.
Change Job Approval page Provides an actionable form with a detailed view of a change job request.
Change Job for Approval page Provides a read only view of an approver’s change job requests awaiting approval.

Create Change Job: Create a change job request.

Notification or Page Use-case workflows
Create Change Job page Provides a page for creating a change job. You must set up deep linking for Citrix Workspace Microapps in Workday.

Create Expense Report: Create an expense report.

Notification or Page Use-case workflows
Create Expense Report page Provides a form for creating an expense report. You must set up deep linking for Citrix Workspace Microapps in Workday.

Create Milestone: Create a milestone.

Notification or Page Use-case workflows
Create Milestone page Provides a form for creating a milestone. You must set up deep linking for Citrix Workspace Microapps in Workday.

Create PTO Request: Submit a paid time-off (PTO) request.

Notification or Page Use-case workflows
Request PTO page Provides a form for creating a paid time-off (PTO) request including choosing type, start and end dates, and optionally adding comments.

Expense Reports: View and approve expense reports.

Notification or Page Use-case workflows
New Expense Report for Approval notification When a new expense approval request is submitted, the approver receives a notification.
Expense Report Approval page Provides an actionable form with a detailed view of an expense report.
Expense Reports for Approval page Provides a read only view of an approver’s expense report requests awaiting approval.

Milestones: View milestone details and receive milestone updates.

Notification or Page Use-case workflows
Milestone Status Update notification When a milestone is updated, a worker who the milestone is assigned to receives a notification.
Milestone Detail Provides a detailed view of all of a user’s milestones.
Milestones Provides an searchable list of a user’s milestones.

My Expenses: View a personalized list of expense reports with report details and details of individual expense items.

Notification or Page Use-case workflows
Expense Status Update notification When the status of an expense changes, the owner of the expense receives a notification.
Expense Report Detail page Provides a detailed view of all of a user’s expenses.
Expense Report Line Detail page Provides dig-down view into one of the user’s expenses.
My Expenses page Provides a read only view of a user’s expense.

My PTO Request: View a personalized list of time-off requests.

Notification or Page Use-case workflows
PTO Request Status Updated notification When the status of a PTO request changes, the owner of the PTO request receives a notification.
My PTO Requests page Provides a read only view of a user’s active time-off requests including when submitted and its status.
PTO Request Detail page Provides a detailed view of all of a user’s time-off requests.

Purchase Orders: View purchase orders with purchase order details.

Notification or Page Use-case workflows
My Purchase Orders page Provides a read only view of a user’s active purchase orders.
Purchase Order Detail page Provides a detailed view of all of a user’s purchase orders.

PTO Balance: View a personalized list of remaining time-off days.

Notification or Page Use-case workflows
PTO Balance page Provides a read only view of a user’s remaining time-off days.

PTO Requests: View and approve paid time-off (PTO) requests.

Notification or Page Use-case workflows
New Time Off for Approval notification When a new time-off approval request is submitted, the approver receives a notification.
Time Off Requests Approval page Provides an actionable form with a detailed view of a time-off request.
Time Off Requests for Approval page Provides a read only view of an approver’s time-off requests awaiting approval.