Recruitment Integrations for External ATS Vendor SmartRecruiters¶

The purpose of this page is to provide the development guidelines about the implementations to third party recruitment integration with SmartRecruiters on IFS Cloud Human Capital Management solutions.

Main functionalities are in co-operated with the external recruitment vendor SmartRecruiters;

Publishing a Job Vacancy
Retrieving the candidates applied

Publishing a Job Vacancy¶

General Information¶

As seen in the above image, once the recruitment requisition is approved. The user will be able to see the "Send Job" button in the "Job Posting" data submenu. Once the user click on the "Send Job" button, after filling the mandatory values given below the job vacancy will be created in the SmartRecruiters side with the state "CREATED".

Mapping Information¶

In order to successfully send the job vacancy details to the SmartRecruiters following mandatory values should be defined in IFS before the integration,

Industry Areas
Job Functional Areas
Employment Type
Job Grade

For the integration, following data should available in each page mentioned above.

Basic Data for Industry Areas;

Industry Area	Industry Area Description
accounting	Accounting
airlines_aviation	Airlines/Aviation
alternative_dispute_resolution	Alternative Dispute Resolution
alternative_medicine	Alternative Medicine
animation	Animation
apparel_and_fashion	Apparel And Fashion
architecture_and_planning	Architecture And Planning
arts_and_crafts	Arts And Crafts
automotive	Automotive
aviation_and_aerospace	Aviation And Aerospace
banking	Banking
biotechnology	Biotechnology
broadcast_media	Broadcast Media
building_materials	Building Materials
business_supplies_and_equipment	Business Supplies And Equipment
capital_markets	Capital Markets
chemicals	Chemicals
civic_and_social_organization	Civic And Social Organization
civil_engineering	Civil Engineering
commercial_real_estate	Commercial Real Estate
computer_and_network_security	Computer And Network Security
computer_games	Computer Games
computer_hardware	Computer Hardware
computer_networking	Computer Networking
computer_software	Computer Software
construction	Construction
consumer_electronics	Consumer Electronics
consumer_goods	Consumer Goods
consumer_services	Consumer Services
cosmetics	Cosmetics
dairy	Dairy
defense_and_space	Defense And Space
design	Design
elearning	E-Learning
education_management	Education Management
electrical_manufacturing	Electrical And Electronic Manufacturing
entertainment	Entertainment
environmental_services	Environmental Services
events_services	Events Services
executive_office	Executive Office
facilities_services	Facilities Services
farming	Farming
financial_services	Financial Services
fine_art	Fine Art
fishery	Fishery
food_and_beverages	Food And Beverages
food_production	Food Production
fundraising	Fundraising
furniture	Furniture
gambling_and_casinos	Gambling And Casinos
glass_ceramics_concrete	Glass, Ceramics And Concrete
government_administration	Government Administration
government_relations	Government Relations
graphic_design	Graphic Design
health_wellness_fitness	Health, Wellness And Fitness
higher_education	Higher Education
hospital_and_health_care	Hospital And Health Care
hospitality	Hospitality
human_resources	Human Resources
import_and_export	Import And Export
individual_and_family_services	Individual And Family Services
industrial_automation	Industrial Automation
information_services	Information Services
it_and_services	Information Technology And Services
insurance	Insurance
international_affairs	International Affairs
international_trade_and_dev	International Trade And Development
internet	Internet
investment_banking_venture	Investment Banking/Venture
investment_management	Investment Management
judiciary	Judiciary
law_enforcement	Law Enforcement
law_practice	Law Practice
legal_services	Legal Services
legislative_office	Legislative Office
leisure_and_travel	Leisure And Travel
libraries	Libraries
logistics_and_supply_chain	Logistics And Supply Chain
luxury_goods_and_jewelry	Luxury Goods And Jewelry
machinery	Machinery
management_consulting	Management Consulting
maritime	Maritime
market_research	Market Research
marketing_and_advertising	Marketing And Advertising
mechanical_engineering	Mechanical Or Industrial Engineering
media_production	Media Production
medical_device	Medical Device
medical_practice	Medical Practice
mental_health_care	Mental Health Care
military	Military
mining_and_metals	Mining And Metals
motion_pictures_and_film	Motion Pictures And Film
museums_and_institutions	Museums And Institutions
music	Music
nanotechnology	Nanotechnology
newspapers	Newspapers
nonprofit_organization_mgmt	Non-Profit Organization Management
oil_and_energy	Oil And Energy
online_publishing	Online Publishing
outsourcing_offshoring	Outsourcing/Offshoring
package_freight_delivery	Package/Freight Delivery
packaging_and_containers	Packaging And Containers
paper_and_forest_products	Paper And Forest Products
performing_arts	Performing Arts
pharmaceuticals	Pharmaceuticals
philanthropy	Philanthropy
photography	Photography
plastics	Plastics
political_organization	Political Organization
primary_secondary_education	Primary/Secondary Education
printing	Printing
professional_training	Professional Training
program_development	Program Development
public_policy	Public Policy
public_relations	Public Relations
public_safety	Public Safety
publishing	Publishing
railroad_manufacture	Railroad Manufacture
ranching	Ranching
real_estate	Real Estate
recreational_services	Recreational Facilities And Services
religious_institutions	Religious Institutions
renewables_and_environment	Renewables And Environment
research	Research
restaurants	Restaurants
retail	Retail
security_and_investigations	Security And Investigations
semiconductors	Semiconductors
shipbuilding	Shipbuilding
sporting_goods	Sporting Goods
sports	Sports
staffing_and_recruiting	Staffing And Recruiting
supermarkets	Supermarkets
telecommunications	Telecommunications
textiles	Textiles
think_tanks	Think Tanks
tobacco	Tobacco
translation_and_localization	Translation And Localization
transportation_trucking_railroad	Transportation/Trucking/Railroad
utilities	Utilities
venture_capital	Venture Capital
veterinary	Veterinary
warehousing	Warehousing
wholesale	Wholesale
wine_and_spirits	Wine And Spirits
wireless	Wireless
writing_and_editing	Writing And Editing

Basic Data for Job Functional Areas;

Functional Area	Functional Area Description
accounting_auditing	Accounting/Auditing
administrative	Administrative
advertising	Advertising
analyst	Analyst
art_creative	Art/Creative
business_development	Business Development
consulting	Consulting
customer_service	Customer Service
design	Design
distribution	Distribution
education	Education
engineering	Engineering
finance	Finance
general_business	General Business
health_care_provider	Health Care Provider
human_resources	Human Resources
information_technology	Information Technology
legal	Legal
management	Management
manufacturing	Manufacturing
marketing	Marketing
other	Other
product_management	Product Management
production	Production
project_management	Project Management
public_relations	Public Relations
purchasing	Purchasing
quality_assurance	Quality Assurance
research	Research
sales	Sales
science	Science
strategy_planning	Strategy/Planning
supply_chain	Supply Chain
training	Training
writing_editing	Writing/Editing

Basic Data for Employment Types;

Employment Type	Employment Type Description
part-time	Part-time
contract	Contract
permanent	Full-time
intern	Intern

Basic Data for Job Grades;

Job Grade	Job Grade Description
associate	Associate
director	Director
entry_level	Entry Level
executive	Executive
internship	Internship
mid_senior_level	Mid-Senior Level
not_applicable	Not Applicable

Following are the other fields that needs to be filled to send a job vacancy to SmartRecruiters other than the above mentioned required Basic Data;

City - Retrieving via the Company work location city details.
Country - Need to fill when recruitment requisition is created.
Default Language - Retrieving the default language for the company.
Job Title - Retrieving when creating the recruitment requisition connected to a Job.

When sending details to SmartRecruiters we are building a JSON template including the details relevant to the job posting; The following is the sample JSON template;

{
  "title": "string",
  "refNumber": "string",
  "targetHiringDate": "2021-07-19T10:03:48.856Z",
  "location": {
    "countryCode": "string",
     "city": "string"
  },
  "industry": {
    "id": "string"
  },
  "function": {
    "id": "string"
  },
  "typeOfEmployment": {
    "id": "string"
  },
  "experienceLevel": {
    "id": "string"
  }
  "template": true,
  "compensation": {
    "min": 0,
    "max": 0,
    "currency": "string"
  },
  "jobAd": {
    "sections": {
      "companyDescription": {
        "title": "string",
        "text": "string"
      },
      "jobDescription": {
        "title": "string",
        "text": "string"
      },
      "qualifications": {
        "title": "string",
        "text": "string"
      },
      "additionalInformation": {
        "title": "string",
        "text": "string"
      },
    },
    "language": {
      "code": "string",
      "label": "string",
      "labelNative": "string"
    }
  }
}

The relevant industry, function, typeOfEmployment, experienceLevel data fields are mapped directly with the above entered basic data under industry areas, Job functional areas, employment types and job grades pages.

Job Functional Area, Job Grade details should add under the general details and set as default when it comes to the Job. Employment Type and Industry Area can be selected via the Recruitment Requisition page when creating a request.

Implementation Details¶

Send Job Vacancy logic is mainly written in the RcruitIntegration utility file under the RCRUIT component.

Structures¶

JobAdvertisementStructure- Main structure to load the job advertisement / vacancy information.

Parameter	Data Type	Description
job_title	VARCHAR2(4000)	-- defines job title in Recruitment Requisition
company_id	VARCHAR2(4000)	-- defines company id in Recruitment Requisition
personnel_req_no	VARCHAR2(4000)	-- defines personnel requisition no in Recruitment Requisition
target_hiring_date	VARCHAR2(4000)	-- defines earliest date in Recruitment Requisition
country_db	VARCHAR2(4000)	-- defines country in Recruitment Requisition
city	VARCHAR2(4000)	-- defines city in Recruitment Requisition
industry	VARCHAR2(4000)	-- defines industry area in Recruitment Requisition
function	VARCHAR2(4000)	-- Retrieves default functional area per the job in job window
type_of_employment	VARCHAR2(4000)	-- defines employment type in Recruitment Requisition
experience_level	BOOLEAN	-- Retrieves default job grade per the job in job window
template	VARCHAR2(4000)	-- set to true if using a template in SmartRecruiters
company_description	VARCHAR2(4000)	-- defines company description in Recruitment Requisition
job_opp_summary	VARCHAR2(4000)	-- defines job description in Recruitment Requisition
key_qualification_needed	VARCHAR2(4000)	-- defines qualifications in Recruitment Requisition
additional_information	VARCHAR2(4000)	-- defines additional information in Recruitment Requisition
language_db	VARCHAR2(4000)	-- defines language in Company Defaults
language	VARCHAR2(4000)	-- defines language in Company Defaults
min_estimated_salary	NUMBER	-- defines minimum estimated salary in Recruitment Requisition
max_estimated_salary	NUMBER	-- defines maximum estimated salary in Recruitment Requisition
currency_code	VARCHAR2(4000)	-- defines currency code in Recruitment Requisition

Publish Advertisement Function¶

PublishAdvertisement function in RcruitIntegration integration projection is used to send OR update the job vacancy details.

Function Parameter	Data Type
CompanyId	Text
PersonnelReqNo	Text
Action	Text

Action Parameter can be "POST" to Publish the vacancy and "SYNC" to update an existing job vacancy.

Once the Job is posted successfully, you will see the "Sync Job" button visible to post updates related to the job vacancy.

Detailing the above function

When the above function is called with a specific action the relevant request header is mapped towards the REST API. When the action is "POST" the request header is "POST", and when the action is "SYNC" the request header is "PUT".

How the data transferring happens;

Plsql_Rest_Sender_API.Call_Rest_Endpoint_Json_Sync(   rest_service_        => 'ATS_SENDER',
                                                      json_                => json_detail_,
                                                      url_params_          =>  url_params_,
                                                      http_method_         => 'POST',
                                                      sender_              => 'ATS_SENDER',
                                                      message_type_        => 'EVENT',
                                                      accepted_res_codes_  => '201,400,401,403,409,422');

'ATS_SENDER' is the message function we have defined in the Routing Rules to identify the Routing Address related to external recruitment vendor integration.

Error Handling¶

This is handled in both internally and externally. When it comes to error handling the required fields for the job posting is checked in internally, so the error handling is done internally. When it comes to errors when publishing or the incorrect fields mapped it is handled via retrieving the external error through IFS Application.

Retrieving Applicants - General Information¶

Once candidates have been hired to jobs and their onboarding status is set to 'Ready to onboard', these candidates are ready to be retrieved into IFS Cloud as Applicants.

Retrieving of candidates and creation of applicants is handled through the background scheduled task 'Get Ready to Onboard Applicants from SmartRecruiters'.

Retrieving Applicants - Implementation Details¶

The logic for retrieving applicants is mainly written inside the RcruitIntegration utility file under the RCRUIT component.

Get Candidates¶

The logic to call the SmartRecruiters candidate endpoint to get applicant data is written inside the procedure SR_Get_Hired_Applicants__.

PROCEDURE SR_Get_Hired_Applicants__(
   page_id_ IN VARCHAR2 DEFAULT NULL)

Calling the endpoint is done as below;

Plsql_Rest_Sender_API.Call_Rest_Endpoint_Json_Sync(rest_service_       => 'ATS_SENDER',
                                                   json_               => json_payload_,
                                                   url_params_         => url_params_,
                                                   http_method_        => 'GET',
                                                   query_parameters_   =>  query_params_,
                                                   sender_             => 'REST_SENDER1',
                                                   accepted_res_codes_ => '200,201,400,401');

URL Details¶

The above REST call is directed to https://api.smartrecruiters.com/candidates with the following query parameters.

onboardingStatus=READY_TO_ONBOARD
status=HIRED
limit=25
If not null, pageId=page_id_

This will return an array of contents containing candidates who have been hired for a job and their onboarding status set as 'Ready to onboard'.

Note: The candidate data returned is not tied to any job. Therefore, the jobs that the candidate has applied will have to be iterated through separately in order to get the jobs in which they have been hired.

Note: If a nextPageId value is found from the above GET call, a recurring call will be done at the end of the procedure, passing the value of nextPageId.

Getting applied jobs¶

The candidate json object has two parts with information about the applied jobs.

primaryAssignment - This object contains data about the latest job the candidate has been updated in.
secondaryAssignments - This array contains objects of all the other jobs the candidate has applied to.

Using the candidate's id and the above job ids, a GET call is sent to https://api.smartrecruiters.com/candidates/{candidate_id}/jobs/{job_id}/onboardingStatus to get each onboarding status. If the onboarding status is 'READY_TO_ONBOARD', an applicant is created in IFS Cloud with the candidate details.

Creating Applicants¶

The function to create applicants is as below;

FUNCTION SR_Add_Applicant__(
   ats_applicant_uid_ IN VARCHAR2,
   ats_job_uid_       IN VARCHAR2) RETURN VARCHAR2

The parameter ats_applicant_uid_ is the smart recruiters candidate id and ats_job_uid_ is the smart recruiters job id which the candidate was hired and onboarding status was 'Ready to onboard'.

To get a detailed object of the candidate, a GET call is sent to https://api.smartrecruiters.com/candidates/{ats_applicant_uid_}.

Candidate json object

{
    id                      string
    internal                boolean
    firstName               string
    lastName                string
    email                   string
    phoneNumber             string
    location                CandidateLocation{...}
    web                     WebProfile{...}
    createdOn               string($date-time)
    updatedOn               string($date-time)
    tags                    [...]
    averageRating           number
    education               [...]
    experience              [...]
    primaryAssignment       {...}
    secondaryAssignments    [...]
    actions                 {...}
}

Below values are used to create the applicant.

Table Column	Value
APPLICANT_ID	Recruitment_Identity_API.Get_Applicant_Id
FIRST_NAME	candidate_obj_.firstName
LAST_NAME	candidate_obj_.lastName
APPLICANT_TYPE	'External'
SOURCE_SEQ_NO	SourceSeqNo of 'ATS' from ApplicantDefinedSource
DATE_APPLIED	SYSDATE
DATE_AVAILABLE	SYSDATE
KEEP_ON_FILE_DURATION	6
ATS_APPLICANT_UID	ats_applicant_uid_
ATS_JOB_UID	ats_job_uid_
TARGET_START_DATE	'startsOn' from candidate's job
ATS_JOB_REF	'{refNumber} - {title}' from Job

startsOn
- By sending a GET call to
  
  https://api.smartrecruiters.com/candidates/{ats_applicant_uid}/jobs/{ats_job_uid}
'{refNumber} - {title}'
- By sending a GET call to
  
  https://api.smartrecruiters.com/jobs/{ats_job_uid}

Add Communication Method¶

The procedure to add a communication method to an applicant is as below;

PROCEDURE SR_Add_Applicant_Comm_Method__(
   applicant_id_ IN VARCHAR2,
   comm_data_    IN VARCHAR2,
   comm_method_  IN VARCHAR2)

Parameter Details

Parameter	Description
applicant_id_	Applicant ID of the IFS Cloud applicant
comm_data_	CommData of ApplicantInfoCommMethod
comm_method_	MethodId of ApplicantInfoCommMethod

Using the above data, a record will be created in ApplicantInfoCommMethod.

Add Address¶

The procedure to add the default address of the applicant is as below;

PROCEDURE SR_Add_Applicant_Address__(
   applicant_id_ IN VARCHAR2,
   address_obj_  IN JSON_OBJECT_T)

Parameter Details

Parameter	Description
applicant_id_	Applicant ID of the IFS Cloud applicant
address_obj_	Json object containing location details

Location json object

{
    country         string
    countryCode     string
    regionCode      string
    region          string
    city            string
    lat             number($float)
    lng             number($float)
}

Below values are used to create address records.

Table Column	Value
VALID_FROM	sysdate
VALID_TO	to_date('9999/12/31', 'YYYY/MM/DD')
APPLICANT_ID	applicant_id_
ADDRESS_DEFAULT_FLAG	'1'
CITY	address_obj_.city
COUNTRY	address_obj_.country
COUNTRY_STATE	address_obj_.region

Add Education¶

Below procedure is used to add education entries of the applicants.

PROCEDURE SR_Add_Applicant_Education__(
   applicant_id_  IN VARCHAR2,
   education_arr_ IN JSON_ARRAY_T)

Parameter Details

Parameter	Description
applicant_id_	Applicant ID of the IFS Cloud applicant
education_arr_	Json array containing education objects

Education json object

{
    institution     string
    degree          string
    major           string
    current         boolean
    location        string
    startDate       Whenstring($when)
                    date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    endDate         Whenstring($when)
                    date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    description     string
}

Below values are used to create the education record.

Table Column	Value
APPLICANT_ID	applicant_id_
APPLICANT_EDU_NUM	APPLICANT_INFO_EDUCATION_SEQ.NEXTVAL
EDUCATION_FIELD_NAME	education_obj_.major
EDU_INSTITUTION_NAME	education_obj_.institution
START_YEAR	education_obj_.startDate OR SYSDATE
END_YEAR	education_obj_.endDate OR Database_SYS.Get_Last_Calendar_Date
EDUCATION_LEVEL_NAME	education_obj_.degree
REMARK	education_obj_.description

Add Work Experience¶

Below procedure is used to add work experience of the applicants.

PROCEDURE SR_Add_Applicant_Experience__(
   applicant_id_   IN VARCHAR2,
   experience_arr_ IN JSON_ARRAY_T)

Parameter Details

Parameter	Description
applicant_id_	Applicant ID of the IFS Cloud applicant
experience_arr_	Json array containing experience objects

Location json object

{
    title           string
    company         string
    current         boolean
    startDate       Whenstring($when)
                    date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    endDate         Whenstring($when)
                    date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    location        string
    description     string
}

Below values are used to create the experience record.

Table Column	Value
APPLICANT_ID	applicant_id_
APP_WORK_EXPERIENCE_NO	APPLICANT_INFO_WORK_EXP_SEQ.NEXTVAL
JOB_TITLE	experience_obj_.title
COMPANY	experience_obj_.company
LOCATION	experience_obj_.location
JOB_DESCRIPTION	experience_obj_.description
START_DATE	experience_obj_.startDate OR SYSDATE
END_DATE	experience_obj_.endDate OR Database_SYS.Get_Last_Calendar_Date
CURRENT_EMPLOYER	experience_obj_.current

Connecting to a Requisition¶

Below procedure is used to connect an applicant to a requisition.

PROCEDURE Connect_To_Requisition__(
   applicant_id_ IN VARCHAR2,
   ats_job_uid_  IN VARCHAR2)

Using the ats_job_uid, the application will try to connect the applicant to a requisition. The procedure will search for the CONNECTION_ID of a recruitment requisition in PersonnelRequisition.

If found, a record will be created in JobApplicant, which connects the applicant to the requisition. This will transfer the applicant to the 'In Recruitement' state.

If a requisition is not found, the applicant will be put to the 'Reserved' state.

Update SmartRecruiters Onboarding Status¶

After an applicant created through the integration is employed, a PUT call is sent to https://api.smartrecruiters.com/candidates/{ats_applicant_uid}/jobs/ats_job_uid}/onboardingStatus with the following body;

{
    "onboardingStatus": "ONBOARDING_SUCCESSFUL"
}

Plsql call:

Plsql_Rest_Sender_API.Call_Rest_Endpoint_Json_Sync(rest_service_        => 'ATS_SENDER',
                                                   json_                => json_payload_,
                                                   url_params_          => url_params_,
                                                   http_method_         => 'PUT',
                                                   sender_              => 'REST_SENDER1',
                                                   accepted_res_codes_  => '200,201,400,401,404,422');

This will update the candidate's onboarding status for the job as 'Onboarding successful' when they are employed, which will prevent them from being fetched again when retrieving.

Database Task Schedule¶

In order for candidates to be retrieved from SmartRecruiters and new applicants to be created, a database task has been added in the RCRUIT component.

Task Name	Method	Description
Get Ready To Onboard applicants from SmartRecruiters	Rcruit_Integration_API.SR_Get_Hired_Applicants__	This will only pull candidates which have been hired and the onboarding status set to 'Ready to Onboard' in SmartRecruiters. Applicants will be created using the candidate's details.