Workday

1.0 Introduction

Workday human capital management (HCM) software allows companies to design and implement different compensation plans across a single organization, administer payroll across both the U.S. and Canada, and use big data and analytics to help improve HR.

Aisera can leverage the following APIs to integrate with Workday:

  • Workday Web Services (WWS)

  • Workday Reporting-as-a-service API (RaaS)

  • Workday Rest API

Depending on the use case, data is either pulled from Workday (e.g. worker profile information) or pushed into Workday (e.g. register employee time-off request).

2.0 Prerequisites

All API operations used by Aisera can be authorized using OAuth2.0. Basic authentication is supported for Workday Web Services (WWS) and RaaS APIs. Depending on the resource, Rest APIs may require OAuth2.0 authentication.

2.1 Basic Authentication

Following are the Authentication inputs that are required for basic auth. Refer to section 4 which addresses this in detail.

  • Endpoint URL

  • Username

  • Password

  • Tenant Name.

The Workday administrator needs to provision an Integration System User and assign the required permission groups in the integration system security group (ISSG) that the user is assigned to. The user provisioning process is a prerequisite both for Basic Authentication and OAuth2.0. MFA and SSO policies should be deactivated for the integration user.

To locate the Workday Tenant and Endpoint refer to sections 2.3 and 2.4.

2.2 OAuth2.0

Requests are authenticated using access tokens obtained from an authorization code grant. A Workday instance administrator should register an API client before using OAuth. Integration information required:

  • Client ID/Secret

  • Authorization Endpoint

  • Token Endpoint

To register an OAuth2.0 client, first, make sure that the Workday tenant has OAuth2.0 clients enabled:

  1. Open Edit Tenant Setup - Security task.

  2. Navigate to OAuth2.0 Settings.

  3. Enable OAuth2.0 Clients Enabled option if disabled.

The client configuration within the Workday requires the following steps:

  1. In the Search bar, search for Register API Client and select as shown in the below screenshot.

  2. Upon selection, the following security options are available as presented in the screenshot below:

  3. Choose Authorization Code Grant.

  4. Choose Bearer Access Token Type.

  5. Add the Redirection URI. It will be in the following form: https://<tenantId>.login.aisera.cloud/?id=aisera.oauth.oauthCommand, where tenantId corresponds to the Aisera tenant Id.

  6. Enable Non-Expiring Refresh Tokens.

  7. Enable Include Workday Owned Scope.

  8. Add the appropriate Scopes (functional areas) based on the resources you want Aisera to have access to.

  9. After completing the configuration, the administrator will be presented with the clientId, clientSecret, authorization endpoint and token endpoint, which need to be provided to Aisera and added to Aisera’s integration configuration

  10. Additionally, an ISU (Integration System User) needs to be created and the credentials (username/password) provided to Aisera, for authenticating to Workday during the OAuth2.0 operation to retrieve the authorization code.

Security needs to be configured both on the API Client (scope) and the ISUser side by configuring an integration system security group (ISSG) for that user. Aisera uses a combination of refresh and access token to access Workday’s API.

2.3 Tenant Name

You can find your tenant name by searching the Tenant Setup report in your Workday instance. As shown in the screenshot below, the ID is located at the top left corner of your screen:

2.4 Workday Web Services Endpoint

  1. Open Public Web Services report.

  2. Select one of the Web Services and open options menu → Web Service→ View WSDL (see screenshot below).

  3. The XML file will open in a new tab in your browser. You can find the web service endpoint by searching: <soapbind:address location=. Following is the format for the address:

  4. https://{Workday_Service}/ccx/service/{tenant_name}/{Web_Service}/{version}

3.0 Workday APIs

3.1 Workday Web Services (SOAP based API)

The official API documentation from Workday is accessible using this link. XML data is exchanged using the SOAP protocol. Operations are grouped into web services and correspond to an API call.

Security permissions required for a Web Service can be found inside the Workday tenant by running the View Security for Securable Item task. An example is presented in the screenshot below for the Get Workers (Web Service) (Web Service Task).

3.2 Workday Reporting-as-a-Service

Workday has a Reporting-as-a-Service (RaaS) interface that allows users to export data by creating a custom report and exposing it as a REST web service. The Workday administrator needs to create and configure the custom report using the Create Custom Report task. The RaaS API is only used for retrieving data from Workday and does not support updating Workday resources. To create a report, a data source must be specified. Each data source contains instances of a business object, which serves as the primary business object of the data source.

A common Reporting API use case for integrating with Aisera, is creating a report based on the Worker from Email Address data source. This data source uses the Worker object as primary business object and allows for retrieving worker data using the worker email address. The following steps indicate the configuration process within Workday. Note that the same process applies to any report definition. To retrieve data related to other business objects just specify the corresponding data source on step 7. Also, remove/replace the Prompts on step 10, if applicable.

  1. Login to your workday tenant.

  2. Search for Create Custom Report task.

  3. Set the report name.

  4. Specify Report Type → Advanced.

  5. “Click” on Enable As Web Service.

  6. Disable Optimized for Performance to enable access to all Data Sources.

  7. Choose Data Source → Worker from Email Address.

  8. “Click” Ok.

  9. Now, choose the Columns tab and specify all the report fields based on the use case (employee ids, contact information, addresses etc.).

  10. In Prompts search for Email Address field and add it with labels (XML Alias) Email_Address. Label it as “Required” by checking the box.

  11. The report configuration is completed. “Click” Ok to save changes.

  12. Now navigate to the report Actions → Custom Report->Transfer Ownership option and specify the ISU configured for Aisera as the report owner. (see screenshot)

  13. Open the Actions menu again and go to Web Service → View URLs. Copy the JSON URL.

  14. Finally, export the report in excel format and provide the file along with the JSON URL to Aisera.

The security privileges to access the data source fields included in the custom report need to be assigned in the ISU’s ISSG. If an API client is used for integrating (OAuth2.0), the Tenant-Non Configurable scope needs to be included in the functional areas.

3.3 Workday REST API

The official API documentation from Workday is accessible here. Employee self-service operations can be conducted using this API, with access to the Workday resources such as:

  • Absence Management

  • Person

  • Worker

This integration pulls or pushes data for each targeted employee to Workday based on the REST endpoint. Aisera can integrate with all public Rest API endpoints.

Security is provided in the official documentation for each API call in the Secured By and Scope sections.

4.0 Integration with Aisera

4.1 Setting up an Integration

Below mentioned are the steps for setting up Integration with Aisera

  1. Login into Aisera with the Admin user credentials.

  2. “Click” on setting on the bottom left-hand side of the screen.

  3. “Click” on Integration.

  4. “Click” on New Integration

  5. Search for Workday, select the icon, and click Next:

  6. Enter the configuration details in the prompt

Name - Ente the name to be given to the Integration

Endpoint - The endpoint is retrieved as described in section 2.4

Public - Determines whether the integration can be used outside the firewall

Description: Enter the description (Optional)

  1. Click Next

  2. Enter the Authentication details:

There are two types of Authentication as mentioned above:

  1. Basic

  2. OAuth

a. For Basic Authentication, the username field is to be populated as follows: <isu_username>@<workday_tenantid>

As you can see in the below screenshot, ISU_1 is the username followed by the @ and then workday tenantid. workday_dpt1 is the tenant id.

b. For OAuth2.0, the Authentication and Token URL gathered by the registered API client along with the Client ID and Secret need to be populated.

Authorization URL - ENter the URL mentioned in section 2.2

Client ID - Enter the Client ID opted in section 2.

Client secret - Enter Client Secret opted in section 2.

Access Token URL - Ente the Access Token URL opted section 2.

11. “Click” ok to complete the integration setup. If you are using Basic Authentication the setup is completed. In case you are using OAuth2.0, you will be redirected to a Workday sign in page where you need to login with the ISU’s credentials. Upon successful login, you will be redirected back to the Aisera’s integration page.

5.0 Setting Up Datasource

Follow the below steps to setup the Datasource with Aisera:

  1. Login into Aisera with the Admin user credentials.

  2. “Click” on Setting on the bottom left-hand side of the screen.

  3. “Click” on Datasource.

4. Click” on New Data Source.

5. “Search” and “Click” on Workday

6. “Click” on Next.

7. “Type” in the name of the New Datasource.

8. “Select” the integration that you have created from the drop down.

9. “Select” the Schedule from the drop-down.

10. “Click” on next.

11. Type in all the required information.

12. “Click” Ok.

The new Datasource should be ready to ingest Workday Users. Ingested users can be seen under “Users” Tab in the left panel.

PreviousHR SystemsNextIdentity and Access Management (IAM/SSO)

Last updated