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_CandidatesRecruiting: Put_Candidates (used for Direct Apply)
Recruiting: Get_Job_Postings
Recruiting: Get_Evergreen_Requisitions
Recruiting: Get_Job_RequisitionsHuman 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 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:
- From the side menu, under Integrations click ATS.
- Click the New button.
- 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 can 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 can 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
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 lookup 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 |
| Close At | Job_Posting/Job_Posting_Data/Hiring_Requirement_Data/Target_End_Date |
| 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 lookup 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. |
| 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"] |
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}} |
| role_assignment_data[].role_assignment_reference.id | Role_Assignment_Data/Role_Assignment_Reference/ID[@type="WID"]. (Note: Check Enrich jobs with requisition roles to get these values. An array of role assignment data items is returned) | {{role_assignment_data[0].role_assignment_reference.id}} |
| role_assignment_data[].role_assignment_reference.descriptor | Role_Assignment_Data/Role_Assignment_Reference wd:Descriptor attribute | {{role_assignment_data[0].role_assignment_reference.descriptor}} |
| role_assignment_data[].role_reference.id | Role_Assignment_Data/Role_Reference/ID[@type="WID"] | {{role_assignment_data[0].role_reference.id}} |
| role_assignment_data[].role_reference.organisation_role_id | Role_Assignment_Data/Role_Reference/ID[@type="Organization_Role_ID"] | {{role_assignment_data[0].role_reference.organisation_role_id}} |
| role_assignment_data[].role_reference.descriptor | Role_Assignment_Data/Role_Reference wd:Descriptor attribute | {{role_assignment_data[0].role_reference.descriptor}} |
| role_assignment_data[].role_assignee_reference.id | Role_Assignment_Data/Role_Assignee_Reference/ID[@type="WID"] | {{role_assignment_data[0].role_assignee_reference.id}} |
| role_assignment_data[].role_assignee_reference.position_id | Role_Assignment_Data/Role_Assignee_Reference/ID[@type="Position_ID"] | {{role_assignment_data[0].role_assignee_reference.position_id}} |
| role_assignment_data[].role_assignee_reference.descriptor | Role_Assignment_Data/Role_Assignee_Reference wd:Descriptor attribute | {{role_assignment_data[0].role_assignee_reference.descriptor}} |
| 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:
- Find out what candidates have recently changed
- 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"] |
Tags
| Recruitment Marketing | Workday |
| Name | Candidate_Tag_Reference wd:Descriptor attribute |
Skills
| Recruitment Marketing | Workday |
| Name (maximum length is 50) | Skill_Data/Skill_Name |
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
Article is closed for comments.