Skip to content

Recruitment Integrations for External ATS Vendor SmartRecruiters

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

The following main functionalities are incorporated 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 clicks on the Send Job button, on 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 SmartRecruiters, the following mandatory values should be defined in IFS before the integration:

  • Industry Areas
  • Job Functional Areas
  • Employment Type
  • Job Grade

For the integration, the following data should be 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 need to be filled to send a job vacancy to SmartRecruiters other than the above mentioned required Basic Data:

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

When sending details to SmartRecruiters, we build a JSON template including the details relevant to the job posting. The following is a 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 and job grade details should be added 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 number in Recruitment Requisition.
    target_hiring_date VARCHAR2(4000) Defines the 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

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

Function Parameter Data Type
CompanyId Text
PersonnelReqNo Text
Action Text

The 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. When the action is SYNC, the request header is PUT.

Given below is 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 the external recruitment vendor integration.

Error Handling

This is handled both internally and externally. When it comes to error handling, the required fields for the job posting are checked internally. When it comes to errors when publishing or the mapping of incorrect fields, they are handled via retrieving the external error through the 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.

The process of retrieving candidates and creating 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 for which they have been hired.

Note: If the 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.

  1. primaryAssignment - This object contains data about the latest job the candidate has been updated in.
  2. 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 of the candidate that 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                 {...}
}

The values below 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

Given below is the procedure to add a communication method to an applicant.

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

Below is the procedure to add the default address of the applicant.

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)
}

The values below 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

The procedure below is used to add the 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
}

The values below 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

The procedure below is used to add the 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
}

The values below 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

The procedure below is used to connect an applicant to a requisition.

PROCEDURE Connect_To_Requisition__(
   applicant_id_ IN VARCHAR2,
   ats_job_uid_  IN VARCHAR2)

Using ats_job_uid, the application tries to connect the applicant to a requisition. The procedure searches 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.