Workday API integration

Recruitment Marketing Public

This guide will take you through the process of integrating your Workday account with Recruitment Marketing. This integration uses the Workday Web Services SOAP API as opposed to the legacy integration which exclusively utilised Workday Reports.

Whilst this method primarily uses web services to obtain job requisition/posting and candidate data, it is necessary to also create a customer report in Workday which provides the recruitment marketing module with visibility to the candidate's status updates.

Configuring Workday API

Creating API Credentials

  • Your Workday administrator should configure a user account that has a username and password and can be used to make SOAP API calls.
  • The account needs to be in the Integration Developers group.
  • Recruitment Marketing will be making calls to the API endpoints: get_Candidates and get_Job_Postings which are part of the Recruiting web service.
  • The account will need permission to access:
    Recruiting: get_candidates

    Recruiting: put_candidates (used for Direct Apply)
    Recruiting: get_job_postings
    Recruiting: get_evergreen_requisitions
    Recruiting: get_job_requisitions

    Human Resources: get_locations
    Human Resources: get_job_families
    Human Resources: get_job_family_groups
    Human Resources: get_work_shifts
    Human Resources: get_job_profiles
    Human Resources: get_organizations (optional)
    Human Resources: get_workers (optional)

  • The account will also need permissions to:
    • Candidate Data: Attachments
      • Candidate Resume Attachments
  • The tenant name should be known as it is used in the Endpoint URL and the username. For example: [user-name]@[tenant-name]

Creating the Candidate RaaS Report

Additionally, you will also need to create a custom report in Workday. The report should be published using the Workday "Reports as a Service" (RaaS) capability. The report provides Recruitment Marketing with a list of candidates who have been updated within Workday since the last time the integration was executed. Unfortunately, the Workday API does not currently provide a way of directly obtaining this same information, making the report an integral part of being able to deliver a scalable integration.

A sample definition for this report is available at Workday Candidate Report. The report must contain a column labelled "email" as this data point is used for subsequent processing of the candidate updates.

Once created, you will need the URL of the report, along with the credentials required to access the report.

Authentication Strategy

There are two authentication methods available when connecting with the Workday API. OAuth is an optional layer of security using OAuth tokens.

  • Basic Auth - Username and Password
  • OAuth1.0 - Refresh Token (if using OAuth)

Configuring Recruitment Marketing

Creating a new Workday ATS Integration:

  1. From the side menu, under Integrations click ATS.
  2. Click the New button.
  3. Click the Workday Web Services logo.

Workday API integration form

Name

A Recruitment Marketing company account can have multiple ATS integrations. This field is used to distinguish those integrations.

How is candidate data retrieved?

Ideally, a customer is able to provide Workday API credentials and a custom made report which will tell Recruitment Marketing which candidates have been recently updated. Without this custom report, Recruitment Marketing has to import all candidates from Workday, every time a synchronisation is run.

If the customer is able to provide both Workday API settings and a Workday Report, then set this field to "Workday Web Services and Reports." If a report is unavailable, then set it to "Workday Web Services only."

For more information refer to the Workday Candidate Report.

Workday Web Services

Tenant Name: Provided by customer e.g. acmecorp

Tenant Hostname: Provided by customer e.g. services1.myworkday.com

  • Note: the hostname should be entered without the HTTP protocol, and will be similar in format the example above

Username: e.g. ISU_RM_Job_Report

Password: Provided by customer

Authentication Strategy: By default, the integration uses Basic Auth. However, optionally, OAuth 2.0 can be utilised. If using OAuth, a refresh token also needs to be provided in the relevant field.

API Version: e.g v35.1

Workday Reports

Refer to Creating the Candidate RaaS Report above for the definition of the RaaS report.

Candidates URL: the URL of the candidate status report created as per the definition above. This report is an XML file containing a list of email addresses of recently updated candidates. When entering the URL for the report, the prompt for the data and time parameter should be replaced with a variable:

%{last_sync_datetime}

Therefore, when entered, the URL will look something like this:

https://services1.myworkday.com/ccx/service/customreport2/customername/username/reportname?Prompt_-_Date_and_Time_1=%{last_sync_datetime}

Candidates Report Username: Provided by customer

Candidates Report Password: Provided by customer

XPath to emails: The XPath used to access the email node in the report  (e.g. wd:Report_Data/wd:Report_Entry/wd:email)

Job Data

Apply URLs
An apply URL is the URL that a candidate is redirected to when they complete a Recruitment Marketing job application Call-to-Action. There is an apply URL for each job that has been read from Workday. This setting determines which Workday field to use for the apply URL. Possible values are "External Apply URL" (default) and "External Job Path."

Level mapping
This is the field used to populate the level field for a job. Options are "Job Level" and "Management Level."

Which job postings should be used?
Sometimes only a subset of jobs need to be imported from Workday. If chosen, the "Only job postings with specified Job Posting site id" setting restricts the jobs imported by a supplied Workday site identifier. When this option is selected, an additional field will be displayed to allow entry of the relevant job posting site ID. The additional field supports a comma delimited list of Job Posting Site IDs in the event that multiple site IDs are being utilised.

How are jobs identified in the ATS?
Each imported job has an associated identifier in Workday. It's possible to use Workday's Job Posting Identifier or Requisition Identifier.

Requisition Field Overrides

It is possible, subject to the appropriate configuration of your Workday system, to request additional job requisition related data fields via Workday's Integration_Field_Override_Data functionality. Once the requisition field overrides have been configured within the Workday system, the WID of the field or group of fields should be entered into this field. A comma separated list of field overrides can be entered. These WIDs are then appended to the requests made to the Get_Job_Requisitions end point via the Request_Criteria > Field_And_Parameter_Criteria_Data > Provider Reference nodes within the SOAP request.

The returned data can then be referenced in the response via the Integration_Field_Override_Data nodes and can be mapped to Job Template Fields using the ATS Field Mapping functionality.

For detailed information refer to 'Workday Requisition Field Overrides' on how to configure Integration Override fields.

Use additional job profiles?
It is possible to read Workday Additional Job Profile feature which will create additional jobs in Recruitment Marketing.

Use additional locations?
When this field is checked, and the "Create on job per location" option has been chosen, additional jobs will be created using Workday's Job Posting Additional Location data.

Use salary information?
Salary information will be read from Workday and associated with each job.

Enrich jobs with job family groups
The Workday job import process will make additional calls to Workday to read Job Family Groups and associate them with the job.

Enrich jobs with organisation data
The Workday job import process will make additional calls to Workday to read Organization data and associate it with the job.

Filter location usage
This filter should be used if the customer has a large number of locations defined in Workday which are not relevant to recruitment. By applying this filter, only relevant locations are queried, thus improving the efficiency of the integration. If this field is selected, a relevant filter value should be entered (e.g. JOB POSTING).

Filter requisition status
This filter should be used if the customer has a large volume of job requisitions within Workday. By default, the integration pulls all requisitions and then filters down to just the open requisitions. By applying this filter, only relevant requisitions are queried, thus improving the efficiency of the integration. If this field is selected, a relevant filter value should be entered (e.g. OPEN).

Exclude jobs without a requisition
When selected, only job posting attached to a requisition are queried.

What should happen when reading a job that has multiple locations?
It is possible to create one job per location or multiple locations per job.

How are remote jobs identified?

This field is used to specify how remote jobs (both fully remote and hybrid remote jobs) should be identified.

Available options are:

  • Not required
  • An ATS specific field
  • Job title field matches a regular expression
  • Job description matches a regular expression

A remote job can be identified via a word in a title or description e.g. Sales Manager - Remote. In these cases, a regular expression is supplied (in the following fields) to identify the exact phrase e.g. \A.*Remote\Z.

Regex to match remote job locations

The regular expression used to identify fully remote jobs.

Regex to match hybrid job locations

The regular expression used to identify hybrid jobs (partially remote / partially on-site).

ATS field for remote

This field will be displayed when the option to identify remote jobs using An ATS specific field is selected.

The available options are:

  • Job_Posting//Job_Posting_Location_Data/Primary_Location_Reference/ID[@type="Location_ID"]
  • Job_Posting//Job_Posting_Remote_Type_Data/External_Name
  • Job_Posting//Hiring_Requirement_Data/Remote_Type_Reference/ID[@type="Job_Requisition_Remote_Type_ID"]

The first option scans the Workday ID of the job location for a regular expression.

For customers able to use v39.2 or above of the workday API, the system can be configured to utilise the Job Posting Remote Type Data.

Finally, it is also possible to utilise the ID of the Remote_Type_Reference within the Hiring_Requirements_Data.

How are hidden job identified?

Hidden jobs are only accessible via a direct link to the job description page. Enter a query to define how hidden jobs should be identified (e.g. title ~ "test").

Candidate Data

Import unknown candidates?
This will import candidates from Workday who have recently been updated, but have not interacted with the Recruitment Marketing careers site and don't exist in the CRM.

Ignore historical candidate events before this date
When importing a recently changed candidate, ignore any status updates before this date.

Candidate read timeout (advanced)

This timeout prevents the integration from failing if the API takes an extended period to return the details for a particular candidate. This can occur if the candidate has a large amount of application data in Workday.

Source Attribution

Append candidate source to the apply URL
This will append any utm_source from a candidate's browsing activity to the apply URL, sending it straight to Workday to populate candidate attribution.

Candidate source fallback
In the event that a candidate source cannot be determined by Recruitment Marketing, it is possible to append a default value e.g. careers_site to the apply URL, allowing Workday to set some level of candidate attribution.

Synchronisation Settings

How often do you want to read jobs from the ATS?
15 minutes is the recommended amount of time to synchronise jobs. For slow integrations, the value should be adjusted.

How often do you want to read candidate data from the ATS?
If the candidate synchronisation process can be completed quickly, then 15 minutes is ideal for this setting. For slow integrations, the value should be adjusted.

Sync translation content
If a site has been localised into multiple languages, then this setting should be checked.

Direct apply settings

What is the default stage of the candidate when uploaded?
Select the application status which a candidate uploaded directly to Workday should be added to.

Getting started

To activate the integration, click the Play icon.
Alternatively, to deactivate it click the Pause icon.

Advanced Information - Job Data

API endpoints

The following Workday API endpoints are referenced by the integration:

  • Human_Resources - Get_Job_Postings
  • Human_Resources - Get_Job_Profiles
  • Human_Resources - Get_Locations
  • Recruiting - Get_Evergreen_Requisitions
  • Recruiting - Get_Job_Requisitions
  • Human_Resources - Get_Job_Families
  • Human_Resources - Get_Job_Family_Groups (optional)
  • Human_Resources - Get_Work_Shifts
  • Recruiting - Get_Organizations (optional)

Job

A paginated call is made to Human_Resources - Get_Job_Postings. A Workday Job Posting is mapped to a Recruitment Marketing job. Several filters are passed to Workday so that archived or draft postings aren’t used e.g. the following parameters are set:

  • Show_Only_Active_Job_Postings: true
  • Exclude_Future_Job_Postings: true
  • Job_Posting_Site_ID. This filter is optional and is useful for companies that support external and internal job postings.

The data returned is processed as follows, with calls made to relevant endpoints to obtain the related look-up data.

Recruitment Marketing Workday
ATS id Job_Posting/Job_Posting_ID
Title Job_Posting/Job_Posting_Title
Description Job_Posting/Job_Posting_Description
Requisition ATS id Job_Posting/Job_Requisition_ID
Start Date Job_Posting/Job_Posting_Start_Date
Note the time zone used to convert this date to UTC is stored in Job_Posting/Job_Posting_Location_Data/Primary_Location_Reference/ID[@type="Location_ID"]
Apply URL Job_Posting/External_Job_Path or Job_Posting/External_Apply_URL
Location

Job_Posting_Location_Data/Primary_Location_Reference/ID[@type="Location_ID"].

This value is used to look up the full Location details from the Location lookup table. Once found, the Address_Data/Formatted_Address value is sent to Google’s Location API which returns data such as latitude, longitude, Google Place ID etc.

Note: Once a Recruitment Marketing location has been created from a Workday LocationID, it is not automatically updated. This means if there is an update to a Workday location (as opposed to assigning a new location to a job) it will not be reflected in Recruitment Marketing. The workaround is to delete the Recruitment Marketing location and run the Job sync process

Additional Locations

Job_Posting_Location_Data/Job_Posting_Additional_Location_Data/Additional_Location_Reference/ID[@type="Location_ID"]

If the “Use additional locations” checkbox in the ATS configuration has been checked, then the above Workday values are used to add additional locations to the job.

Remote

When “Remote” is set based on an ATS field, All location and additional location ids are concatenated and the resulting string is checked against a regular expression. For example, if any of the location IDs for the job contain the word “Remote”, this field is checked

Workday v39.0 has built in support for remote jobs/locations. We can now read the remote value from Job_Posting_Remote_Type_Data/External_Name.

Payment Amount Requisition/Amount
Payment Frequency Requisition/Frequency_Reference/ID[@type="Frequency_ID"]
Payment Plan Requisition/Pay_Plan_Reference/ID[@type="Compensation_Plan_ID"]
Payment Currency Code Requisition/Currency_Reference/ID[@type="Currency_ID"]

Note: By default, the Workday job posting identifier is mapped to the Recruitment Marketing job's identifier. However this can be modified using the How are jobs identified in the ATS option, so that the Workday requisition identifier is mapped to both the Recruitment Marketing job id and the Recruitment Marketing requisition id.

Location

Recruitment Marketing Workday
ATS id Location/ID[@type="Location_ID"]
Street Location/Address_Line_Data
City Location/Municipality
State Location/Country_Region_Descriptor
Postcode Location/Postal_Code
Country code Location/Country_Reference/ID[@type="ISO_3166-1_Alpha-2_Code"]
Time Zone Location/Time_Zone_Reference/ID[@type="Time_Zone_ID"]
Full Address Location/Address_Data/Formatted_Address
Usage Location/Location_Usage_ID

Department

Recruitment Marketing Workday
ATS id Job_Family/Job_Family_Data/Name
ATS Name Job_Family/Job_Family_Data/Name

Category

Recruitment Marketing Workday
ATS id Job_Family_Group/Job_Family_Group_Data/Name
ATS Name Job_Family_Group/Job_Family_Group_Data/Name

Job Category

Recruitment Marketing Workday
ATS id
Job_Category_Reference/[@type="WID"]
ATS Name
Job_Category_Reference/[@type="Job_Category_ID"]

Level

If Level setting is configured to "Job Level":

Recruitment Marketing Workday
ATS id Job_Posting/Job_Level_Reference/[@type="WID"]
ATS Name Job_Posting/Job_Level_Reference/[@type="Job_Level_ID"]

If Level setting is configured to "Management Level":

Recruitment Marketing Workday
ATS id Job_Posting/Management_Level_Reference/[@type="WID"]
ATS Name Job_Posting/Management_Level_Reference/[@type="Management_Level_ID"]

Employment Type

Recruitment Marketing Workday
ATS id Job_Posting/Time_Type_Reference//ID[@type="WID"]
ATS Name Job_Posting/Time_Type_Reference//ID[@type="Position_Time_Type_ID"]

Job Template Fields (Custom Mappings)

A number of Workday fields that don’t map to Recruitment Marketing built-in fields have been made available for mapping to Recruitment Marketing job template fields. To use these, make a new ATS field mapping, choose Liquid as the language, and fill in the value on the right hand side as the path to the ATS field.

Description Workday Liquid Mapping Code
company_assignment.id Organization_Data/Organization_Assignments_Data/Company_Assignment_Reference/ID[@type="WID"] {{company_assignment.id}}

company_assignment.code

Organization_Data/Organization_Assignments_Data/Company_Assignment_Reference/ID[@type="Company_Reference_ID"] {{company_assignment.code}}
company_assignment.descriptor Organization_Data/Organization_Assignments_Data/Company_Assignment_Reference wd:Descriptor attribute {{company_assignment.descriptor}}
cost_centre_organisation.id Organization/Organization_Data//Reference_ID (Note: Check Enrich jobs with organization data to get these values) {{cost_centre_organisation.id}}
cost_centre_organisation.name Organization/Organization/Organization_Data//Name {{cost_centre_organisation.name}}
cost_centre_organisation.type.id Organization_Data/Organization_Type_Reference/[@type="WID"] {{cost_centre_organisation.type.id}}
cost_centre_organisation.type.code Organization_Data/Organization_Type_Reference/[@type="Organization_Type_ID"] {{cost_centre_organisation.type.code}}
job_type.id Job_Posting/Job_Type_Reference//ID[@type="WID"] {{job_type.id}}
job_type.code

Job_Posting/Job_Type_Reference//ID[@type="Employee_Type_ID"]

{{job_type.code}}
job_category.id Job_Category_Reference/[@type="WID"] {{job_category.id}}
job_category.code
Job_Category_Reference/[@type="Job_Category_ID"]
{{job_category.code}}
supervisory_organisation.id Supervisory_Organization_Reference//ID[@type="WID"] (Note: Check Enrich jobs with organization data to get these values) {{supervisory_organisation.id}}
supervisory_organisation.code Supervisory_Organization_Reference//ID[@type="Organization_Reference_ID"] {{supervisory_organisation.code}}
supervisory_organisation.name Organization_Data//Name {{supervisory_organisation.name}}
supervisory_organisation.descriptor Supervisory_Organization_Reference wd:Descriptor attribute {{supervisory_organisation.descriptor}}
supervisory_organisation.type.id Organization_Data/Organization_Type_Reference/[@type="WID"] {{supervisory_organisation.type.id}}
supervisory_organisation.type.code Organization_Data/Organization_Type_Reference/[@type="Organization_Type_ID"] {{supervisory_organisation.type.code}}
work_shift.id Work_Shifts/Work_Shift_Data/Work_Shift_ID {{work_shift.id}}
work_shift.name Work_Shifts/Work_Shift_Data/Work_Shift_Name {{work_shift.name}}
worker_sub_type.id Job_Posting/Position_Worker_Type_Reference//ID[@type="WID"] {{worker_sub_type.id}}
worker_sub_type.code Job_Posting/Position_Worker_Type_Reference//ID[@type="Employee_Type_ID"] {{worker_sub_type.code}}

Additional Job Profiles

If the Use additional job profiles checkbox is enabled, and the current Workday job posting has supplied a Additional_Job_Profiles_Reference//ID[@type="Job_Profile_ID"] field, then this will result in an extra job being created under the same requisition.

Additional Job Locations

If the Use additional locations checkbox is enabled, the Job_Posting_Location_Data/Job_Posting_Additional_Location_Data/Additional_Location_Reference/ID[@type="Location_ID"] values will be used to create additional locations assigned to the job.

Advanced Information - Candidate Data

API endpoints

The following Workday API endpoints are referenced by the integration:

  • Recruiting - Get_Candidates

Methodology

This part of the integration does the following:

  1. Find out what candidates have recently changed
  2. Get the candidate from Workday and import them

Workday does not currently have an endpoint which is able to provide the information required for the first step. Therefore, customers are required to create a custom Workday report which provides a list of email addresses for candidates who have changed since the date of the last successful candidate synchronisation.

Once the email addresses of the recently changed candidates have been acquired, a request to Recruiting - Get_Candidates is made

Candidate

Recruitment Marketing Workday
ATS id Candidate_ID
First name First_Name
Last name Last_Name
Email address Email_Address
Phone number Phone_Number and
Country_Phone_Code_Reference//ID[@type="Country_Phone_Code_ID"]
Location Country_code: Location_Data//Country_Reference//ID[@type="ISO_3166-1_Alpha-2_Code"]
Address Line 1: Location_Data//Address_Line_1
City: Location_Data//City
State: Location_Data//Country_Region_Reference//ID[@type="ISO_3166-2_Code"]
Zip: Location_Data//Postal_Code
Employee ID Worker_Reference//ID[@type="Employee_ID"]
Job Applications Each Job_Application_Data entry is examined

Job Application

Recruitment Marketing Workday
Status The ATS status uid, text, and time of creation fields are mapped to:
Stage_Reference//ID[@type="WID"]
Stage_Reference//ID[@type="Recruiting_Stage_ID"]
Status_Timestamp
Requisition ID Job_Requisition_Reference//ID[@type="Job_Requisition_ID"]
Resume

Resume_Attachment_Data/File_Content

Resume_Attachment_Data/Filename

Experiences

Recruitment Marketing Workday
Company name Experience_Data/Company_Name
Job title Experience_Data/Title
Start date Experience_Data/Start_Month, Experience_Data/Start_Year
End date Experience_Data/End_Month, Experience_Data/End_Year
Is current Experience_Data/Currently_Work_Here

Educations

Recruitment Marketing Workday
School ID Education_Data/School_Reference//ID[@type="School_ID"]
School Name Education_Data/School_Name
Degree ID Education_Data/Degree_Reference//ID[@type="Degree_ID"]
Field of study ID Education_Data/Field_of_Study_Reference//ID[@type="Field_Of_Study_ID"]

Educations

Recruitment Marketing Workday
Name (maximum length is 50) Skill_Data/Skill_Name

Note: max length for skills is 50 characters

Useful information

Example URLs

WSDL URL: This is the URL of the Workday Recruiting WSDL file. Most likely it will look like this (note the version number)
https://community.workday.com/sites/default/files/file-hosting/productionapi/Recruiting/v32.2/Recruiting.wsdl

Endpoint URL: This is the URL of your workday installation
e.g. https://wd2-impl-services1.workday.com/ccx/service/your-company/Recruiting/v32.2

Comments

0 comments

Article is closed for comments.