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. It also uses the Workday REST API to enable embedded apply applications.

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 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 REST API Credentials

Authentication Strategy

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

1. Basic Auth - Username and Password
2. 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?

• Workday Web Services will use the API to retrieve the candidate data. It is recommended to use this with API Version 43.2 or higher.
• Workday Web Service and Reports is for older API versions. This requires an additional custom report to be created in Workday, and then included in the integration settings in Recruitment Marketing. For details on how to do this, see Workday Web Service and Reports (Legacy Configuration).

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., v46.2

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 needs 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 endpoint 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.

Importing the hiring team

The Workday integration can import each job's hiring team - its recruiters and hiring manager - associate them with the jobs, and keep up to date on every job sync.

The following must be in place:  

• Job Hiring Team enabled for your account. Contact your account manager or support to have this feature switched on. 
• Workday API version 44.0 or higher on the integration. Earlier versions do not include the person behind each role assignment, so no hiring team data is imported for integrations below v44.0.       
• "Enrich jobs with roles" enabled on the integration - required to import recruiters assigned directly on a job requisition.
• "Enrich jobs with organisation data" enabled on the integration - required to import recruiters inherited from the supervisory organisation, and required for hiring managers.                                         

When any of these is missing, the sync leaves job hiring teams untouched - it never removes existing members because of a configuration gap.

Filter location usage

This filter should be used if the customer has a large number of locations defined in Workday that 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 postings 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).

Regular expressions can be used to mark a job as hybrid or remote when a phrase does not occur in the description. If the requirement is "Mark all jobs that contain #LI-ONSITE in the job description as onsite, #LI-REMOTE as remote, and everything else as hybrid", then the ATS configuration settings would be:

In this case, the regular expression: (?i)^((?!(#LI-REMOTE|#LI-ONSITE)).)*\z translates to "mark any jobs that do not contain #LI-REMOTE, or #LI-ONSITE as hybrid, and ignore case sensitivity".

Regex to match remote job locations

The regular expression used to identify fully remote jobs. This is usually something simple like ".*(?i)Remote.*"

Regex to match hybrid job locations

The regular expression used to identify hybrid jobs (partially remote / partially on-site). This is usually something simple like ".*(?i)Hybrid.*".

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"]
• Job_Requisition//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 or Job Requisition 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. For example, 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.

Location

Department

Category

Job Category

Level

If Level setting is configured to "Job Level":

If Level setting is configured to "Management Level":

Employment Type

Hiring Team

Only recruiter and hiring manager roles are associated with imported jobs at this time.

Recruiters: Assigned directly to the requisition within Workday (manually assigned)

From Get_Job_Requisitions / Get_Evergreen_Requisitions with Include_Roles: true. The Worker_Reference exists from Workday API v44.0.           

Recruiters: Inherited from the supervisory organisation

From Get_Organizations with Include_Roles_Data: true. Used only when the requisition has no directly assigned recruiters - direct assignments replace inherited ones. If there is no manually assigned recruiter, the recruiter from the organisation is used. 

Hiring Managers

From Get_Organizations - the manager of the job posting's supervisory organisation in Workday.

Name and Email: Common to all hiring team members

From a batched Get_Workers (Staffing) call with Include_Personal_Information: true, requested by Employee_ID for every collected member.

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.

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 that is able to provide the information required for the first step. Therefore, customers are required to create a custom Workday report that 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

Job Application

Experiences

Educations

Tags

Skills

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, for example: 

https://wd2-impl-services1.workday.com/ccx/service/your-company/Recruiting/v32.2