Configuring the HR Service Delivery Integration with Workday

[ppenkov]

Pre-requisites

1.          You have installed the HR Service Delivery Integration with Workday store app – this will automatically install the Workday HR Spoke.
2.          You have set up the Workday HR Spoke successfully and established a connection between the ServiceNow instance and the Workday tenant. The steps of configuring the Workday HR Spoke are detailed in the docs: https://docs.servicenow.com/bundle/vancouver-integrate-applications/page/administer/integrationhub-s...

For setting up SOAP web services (required for pulling the Organisational and Employee data discussed in this guide) you will need to get the following from Workday:

•           Workday tenant base URL: For example, https://[WD URL].workday.com/ccx/service/[tenant]
•           Version: Version of the API. For example, enter v39.0.
•           Username and Password

You only need to configure REST if you are pulling any other data, such as To dos and RaaS reports.

Structure of the HR spoke flows

It is important to understand the basic structure of the Workday HR Spoke, as it has many Subflows that are triggered depending on the data that you are pulling. The configuration in the HR Spoke should not need to be modified unless you are adding custom fields. The process of adding custom fields will be discussed in the next section. The overall structure of the Workday HR Spoke flows is as follows:

Flow: Run Workday Integration Flow

This is the main flow that triggers all other subflows and actions. Here you configure how often the Integration is run and which objects to pull from Workday.

• Trigger: How often the integration runs – recommendation is usually Daily, out of hours, depending on your customer’s requirement.
• Actions:
  • Check Job Status – a check is performed whether a Job is currently running. Keep this in mind as sometimes Jobs can get stuck during development if an error is thrown. You can monitor Jobs via the Job Tracker. Navigate to Workday Worker Profile Sync > Job Tracker > Workday Integration Job Tracker to see all Jobs initiated by the flow.
  • Call Run Workday Service Subflow – here you can control what objects are pulled from Workday depending on your customer’s requirement. You can either enable or disable the pulling of:
    • Department
      • Calls the Get_Organizations service in Workday
    • Location
      • Calls the Get_Locations service in Workday
    • Job Profile
      • Calls the Get_Job_Profiles service in Workday
    • Worker Profile – gets all workers regardless of their effective start/end dates
    • Effective Worker profile – gets all workers that are effective at the time the job is started
    • Future Worker Profile – gets all workers with a future effective date
      • All of the above worker subflows call the Get_Workers service in Workday, with respective filters applied in the request message for effective dates.
    • Retrieve All Data – enable this option to do a full pull of all data from the Workday tenant. If it is disabled, it will only do a delta pull of the updated records since the last Job was ran.
    • Pull To-Dos – enable this option to pull To-Dos from Workday (this will not be covered in this guide).

Depending on which options you have enabled, there are several subflows and actions that are called for each enabled option. They follow roughly the same structure as follows:

Subflow: Run Workday Service

This subflow checks which objects have been selected in the main Flow above and triggers another subflow for each selected option:

•           Get Departments subflow, if Departments is selected.
•           Get Locations subflow, if Locations is selected.
•           Get Job Profiles, if Job Profiles is selected.
•           Get Workers, if Worker Profile is selected.
•           Get Effective Workers, if Effective Worker Profile is selected.
•           Get Future Workers, if Future Worker Profile is selected.

Subflow: Get Departments, Get Locations, Get Job Profiles, Get Workers, Get Effective Workers, Get Future Workers

These subflows initiate the Job tracker job records and trigger a corresponding Get Department Service, Get Locations Service subflows for organisational data; as well as the Get Workers Service and Get Job Profiles Service for pulling Workers and Employment data.

Note: Get Workers, Get Effective Workers, and Get Future Workers subflows are all calling a single Get Workers Service subflow. This is controlled via the sn_hr_workday.worker_service_flow_name system property, which you can modify so that your Get worker flows call your custom Get Workers Service flow without having the recreate the whole setup when a change is required in the Action to pull custom fields or make any modification from the OOB data parsing. This is covered in more detail in the next section.

Subflow: Get Departments Service, Get Locations Service, Get Workers Service, Get Job Profiles Service

These subflows trigger a set of Look up Actions responsible for creating the request to Workday and the parsing of the received data.

The subflows also create the Staging records and put the Flow variables into their respective Staging table fields.

In case adding custom fields is required, these subflows will need to be copied and changed to trigger the custom Look up Action you create.

Note: Changing the action to a custom Look up action will reset the staging field mappings as well, so you will need to recreate them. Also note that the subflow creates Staging records into 2 tables – HR Profile and HR Job. This is important, as 1 HR Profile can be linked to multiple HR Jobs. This structure is built inside the Lookup actions parsing step and should be retained to minimise customisations and avoid any synchronisation issues between the HR Job, HR Profile and User records.

Action: Look up Organizations, Look up Location Details, Look up Workers and Employment Info

The actions are responsible for initiating the SOAP request sent to Workday and the processing of the received response. These should not need to be modified unless you are adding custom fields. The important sections you need to be aware of are:

•           Pre-Processing – this section is responsible for setting variables in the SOAP request dynamically using a script. These variables are then called in the SOAP request section.
•           Pagination Setup step – this section is responsible for controlling pagination. Generally, it should not need to be modified unless you are testing with a smaller subset of records.
•           Look up step – this section is responsible for building the SOAP Request and what API is called.
•           Script Parser step – this section is responsible for parsing the XML response and stores each parsed value into a variable that is then passed into the Outputs.
•           Outputs – this is the object that is passed back into the subflow calling the action, which then parses the variables into the Staging table fields.

Adding custom logic to the Workday HR Spoke

The Workday HR Spoke is designed to be used as it comes by default, so you should be able to start pulling data from Workday immediately after you have done the Workday HR Spoke setup and selected which objects you want to pull in the main Run Workday Integration flow. Customers, however, are likely to have additional fields that need to be pulled from Workday into ServiceNow.

In those situations, it is important to challenge the business case of why those fields are required to be populated in ServiceNow. If the fields do not drive any logic in ServiceNow, such as driving personalisation or security needs via HR/User criteria, they should not be pulled. In cases where there is a compelling reason to add custom fields, the following process can be followed. The steps below are focused on the most common use case where custom fields are added on the Worker objects, but the same can be applied for Organisational objects, if required.

Copy the OOB Action: Look up Workers and Employment Info

1.          Ensure you do this in the same scope of the OOB action. From the Action, navigate to the More Actions button (…) > Properties and check the Application field.
2.          Navigate to Step 5. Script Parser step. For each of the custom fields you need to add, create a variable, following the structure of the Worker XML. It is important to know whether the fields you are adding are attributes of the Worker or the Worker Job, so that the correct structure is maintained. Note the variable workerJobData is an Array that contains all worker jobs if the worker has multiple jobs. If you are adding a custom field related to the worker job, you need to add it inside the while loop after the workerJobData variable so that it is collected for all worker jobs. There are also several Array variables that are used to group the variables logically together, such as WorkerStatusData, PersonalData, EmploymentData etc. Before adding any custom fields, spend some time to familiarise yourself with the structure of the script so that you add the fields to the correct logical place, depending on the data type you are trying to reach.
3.          You then need to assign the variable to the attribute of the XML that you are trying to reach. Someone that is familiar with Workday should be able to provide you the XPath to the custom field required, but you can use the examples of the existing OOB XPaths to navigate to the attribute if you are familiar with the XML structure. You can log the xmlDoc variable to see the full Worker XML.
4.          After you have created a custom variable, assigned it the correct XPath and added it to the correct Array variable, you need to add it into the Outputs section. Select Edit Outputs to make the form editable and then create a new output for any custom fields you have added in the Script Parser step. Keep in mind the structure of the Outputs, OOB it follows the same structure from the Script Parser so you should preserve that to make the solution more maintainable. For example, if you have added a custom National ID field in the PersonalData array variable in the Script Perser step, you should add the output in the worker > Worker Data > Personal Data section.
5.          Save and publish your custom action.

Create the custom fields

1.          For worker fields, depending on their type, you need to create them on the HR Profile and HR Job tables, as well as the staging tables - HR Profile Staging [sn_hr_workday_hr_profile_staging] and HR Job Staging [sn_hr_workday_hr_job_staging].
2.          Once you have the staging tables fields created, you can use them in the custom subflow below.
3.          You will also need to modify the Transform maps that map the staging fields to the target fields. Keep in mind that these are in the HR Service Delivery Integration with Workday scope, and not the Human Resources: Integrations scope (legacy solution).

Copy the OOB Subflow: Get Workers Service

1.          To call your custom Look up Workers and Employment Info action, you will also need to create a copy of the Get Workers Service. Before you begin, ensure you are again in the right scope by navigating to the More Actions button (…) > Properties and checking the Application field.
2.          In Step 2 of the new subflow, change the action to the custom Look up Workers and Employment Info action you created.
3.          Once you change the action, you will need to reconfigure all the steps below it, including the OOB field mappings for both HR Profile and HR Job staging tables.
4.          Once done, save and publish the subflow.

Calling the custom Get Workers Service subflow.

1.          Navigate to System properties and look for the property sn_hr_workday.worker_service_flow_name
2.          Set the value to “sn_hr_workday.” + the name of your custom subflow. This allows you to call the subflow without having to recreate the rest of the Workday flow, as the property drives which subflow is getting called.

You can now test the Run Workday Integration Flow with your custom subflow and action to pull the additional fields.

Testing tips

1.          Ensure there are no active jobs by navigating to Workday Worker Profile Sync > Job Tracker > Workday Integration Job Tracker to see all Jobs initiated by the flow. If there are any the flow will not start again until there are no active jobs.
2.          If you want to test only for a small subset of users, you can limit the number of records pulled by navigating to your custom action and changing the Pagination Setup step configuration. You can change the totalPages variable to 1 to pull the first 100 worker records.
3.          If you want to pull specific users via their employee number, you can do that by editing the Pre-Processing step script and setting the workerReferenceStr variable to a static string by directly inputting the Employee ID as the {value} instead of calling it from the inputs. Keep in mind that you need to know whether the user is an employee or contingent worker as the string needs to be modified accordingly.
4.          You can further manipulate the script in the Pre-Processing to change the request that is being send to Workday – such as set excludes of inactive workers and contingent workers directly.
5.          If you are adding custom fields, there are tags that might be excluded from the SOAP Envelope in Step 3 of the action. Confirm with Workday whether additional tags need to be set to true in the request for custom fields.
6.          If Workday are adding Field overrides those are usually included at the end of the XML structure and you need to add code in the request to get the field overrides in the response. Confirm with Workday how to adjust the request accordingly if these are required.
7.          If you are getting no execution errors when running the flow but you do not see any records being received, check for a 500 error in the logs of the Action. This usually indicates that the request returned no workers, or that the credentials have expired. Always check with Workday whether new credentials need to be set.

NOTE: Please ensure that your customers are licensed appropriately for these changes under their HR licenses. At the time of writing, a separate IntegrationHub license was not required for adding custom fields if there are no new API calls to other objects in Workday. For example, if a customer wants to pull a custom field that is not available in the Get_Workers Workday API, Workday will have to create an Integration override field and expose that via the Get_Workers API. A custom API Call to another object is not allowed without a separate IntegrationHub license.