SAP Knowledge Base Article - Public

3508419 - How to Mass Create Job Requisitions using Integration Center - Recruiting Management

Symptom

How to mass create Job Requisitions using Integration Center?

Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental.

Environment

SAP SuccessFactors Recruiting Management

Resolution

** Before you proceed with any changes, we highly recommend that you run this test on your test environment first. Integration Center is a tool that have the potential to change configuration and information, which might cause malfunction on the environment and/or audit non conformities due to data change **

Recruiting OData API Permissions

  • Recruiting Permissions > OData API Job Requisition Export
  • Recruiting Permissions > OData API Job Requisition Create
  • Recruiting Permissions > OData API Job Requisition Update

Steps

1. Create a CSV (UTF-8) file. Include columns with job requisition information (You can use any labels for the columns).

Refer to the "Samples" section below for how to prepare the Job Requisition data and map the fields of different field types.

2. Upload the file to an FTP server (The file name should not contain any spaces).

3. Create an input integration to import the data.

  1. Go to Integration Center > My Integrations.
  2. Click Create and select Scheduled CSV Input Integration.
  3. Search for "JobRequisition" and select the entity.
  4. Click Select button.
  5. Go to Configure Fields tab. Click Upload Sample CSV to upload a sample file for mapping the data to fields.
    (You can upload the same import file but only the first 10 records will be picked in the sample data view.)
  6. Click the link icon to switch to Field Mapping View.
  7. Map the CSV columns to the destination fields by 'Drag and Drop'. Mapped fields will appear in Preview on the right side.
  8. Click the triangle icon to switch to File Import Test View.
  9. Click Run Preview Records to create job requisitions based on the sample data. Check if job requisitions can be created successfully.
    Note: This step will create job requisitions and not just a 'Preview'.
  10. Go to Source Settings tab. Setup File Server Settings, File Name and Folder Settings of the import file.
  11. Go to Scheduling tab to configure the occurrence if this will be a scheduled job.
  12. Save and run the integration.

Samples - How to prepare the Job Requisition data and map the fields

Please also see the sample payloads in SAP SuccessFactors API Reference Guide (OData V2).


1. Mandatory system fields:
templateId, isDraft, internalStatus


(1) templateId

Map the Job Requisition Template ID.

 - How to obtain the value:

  • Story report field: Recruiting > Job Requisition > Templates - Job Requisition > Template ID
  • Adhoc report field: Recruiting V2 > Job Req Templates > Template ID

Provisioning administrators can go to 'Provisioning > Import/Update/Export Job Requisition Template' to obtain the Template ID.

(2) isDraft

Map the value "true".

This is used for creating Pre-approved job requisitions. When isDraft=true, it is possible to create a draft job requisition without filling all required fields.

IMPORTANT: If you save your file using Excel, the 'true' value will automatically be saved as 'TRUE'. This will not work as expected once you upload the file. As a workaround, you can either change the cell format to Text and make sure the 'true' value is in small letters; or edit the file using Notepad++ and change all the 'TRUE' values to 'true'. Save it again and use that file for the upload.

 



(3) internalStatus

  • To create job requisitions with Approved status, set internalStatus=1. 
  • To create job requisitions with Preapproved status, set internalStatus=0.
  • If internalStatus is blank, it creates job requisitions with Preapproved status (internalStatus=0) by default.

Note: When internalStatus=1 (Approved), it is not allowed to set isDraft=true. All the required fields must be populated.

IMPORTANT: Do not update the internalStatus value after creation as it will lead to data inconsistency issue. For example, if a job requisition is originally created with the internalStatus=0 (Pre-approved), and later it is changed to internalStatus=1 (Approved) using API, the job requisition will not be approved properly.



2. Job Requisition template fields: 

Map the necessary job requisition template fields. Refer to the sample fields of different types provided below.


(1) Standard "country" field (type="derived")

 - Column(s) in the CSV file: 2-char ISO country/region code, e.g. "US".

 - How to obtain the value:

Retrieve 'Country/Region' using 'Manage Data' or 'Import and Export Data'.


(2) Standard "currency" field (type="enum")

 - Column(s) in the CSV file: ISO currency code, e.g. "USD".

 - How to obtain the value:

The same as the "country" field. The currency data is available in the Country/Region object.


(3) Standard "jobRole" & "jobCode" fields (Job Profile)

Use the Role and the Job Code to associate a job profile to a job requisition.

Note:

  • In OData API, there are two properties available to update the "jobRole" field: "jobRoleEntity" (*) and "jobRole". An error will occur if both the jobRole and joleRoleEntity properties are used in the OData API payload. 

    • The "jobRole" property accepts the internalId of the Role.
    • The "jobRoleEntity" is a navigation to the Role entity that accepts the externalCode of the Role.
                    
  • When the "jobCode" is provided, the system will automatically pull the associated Role. However, when the "jobRoleEntity" or "jobRole" is provided, the system will not automatically pull the associated Job Code.
  • If one Job Code is mapped to Multiple Roles in the Job Profile Builder (*), it is necessary to provide both the "jobRoleEntity" and "jobCode" to associate the job profile. If only the "jobCode" is provided, the system will pick up a random Role associated with the Job Code.

(*) The "jobRoleEntity" navigation property in OData API and the Job Code association with multiple Roles are new features in the 2H 2024 release.

 - Column(s) in the CSV file: 

  • jobCode - externalCode 
  • jobRoleEntity - externalCode (or jobRole - internalId)

 - How to obtain the value:

Retrieve 'Job Classification' and 'Role' using 'Manage Data' or 'Import and Export Data'.

 - How to map the field:

Job Code - the externalCode can be directly mapped to the "jobCode" property.

Job Role - If using the internalId, please map it to the "jobRole" property; if using the externalCode, please locate "jobRoleEntity" and map it to the GUID (externalCode).


(4) Picklist fields

 - Column(s) in the CSV file: Picklist Option ID

 - How to obtain the value:

Retrieve 'Picklist-Values' using 'Picklist Center' or 'Import and Export Data'.

 - How to map the field:

Picklist fields are appearing as "xxx to PicklistOption". Expand it and map the CSV column to "id".


(5) Date fields

Please also see the SAP SuccessFactors API Reference Guide (OData V2):

TypePatternExample
DateTime<yyyy-mm-dd>T<hh:mm:ss>

2014-04-22T18:10:10

                        
DateTimeOffset

UTC time (zero offset): <yyyy-mm-dd>T<hh:mm:ss>Z

Time offsets: <yyyy-mm-dd>T<hh:mm:ss>±<hhmm>

                        

UTC time (zero offset): 2014-04-22T18:10:10Z

Time offsets: 2014-04-22T18:10:10+0800

                        

In the CSV file, enter the value based on the corresponding pattern. In the example below, the standard field "jobStartDate" is of DateTimeOffset type, so the value in the CSV file should be "2024-08-20T09:00:00Z" (UTC time).

 - How to map the field:

After mapping a date field, the Preview will display the value in JSON format, e.g. "/Date(1724144400000+0000)/".


(6) Object fields

There are two types of object fields in Recruiting: Object and Object List.

 - Column(s) in the CSV file:

  • externalCode
  • startDate -  This should be the same as the Job Start Date.
  • isPrimary - Only required for object list fields. Map the value "1" (1=Yes).

 - How to obtain the value:

Retrieve the object data using 'Manage Data' or 'Import and Export Data'.

 - How to map the field:

The following steps are applicable to the following standard object fields and other custom object fields:

  • legalEntity_obj
  • costCenter_obj
  • businessUnit_obj
  • division_obj
  • department_obj
  • location_obj (multiselect="false")

Note: The job requisition template ids "std_position_obj" and "sfstd_jobLocation_obj" are not available in API. Instead, please use "std_position_objlist" and "sfstd_jobLocation_objlist".

Object fields are appearing as "xxx to <Object Name>". Expand it and map the CSV columns to "externalCode" and "startDate".

(In some objects, the "externalCode" may be named as "code"; the "startDate" may be named as "effectiveStartDate".)

The following steps are applicable to the standard object list fields:

  • location_objlist
  • std_position_objlist
  • sfstd_jobLocation_objlist

Note: 

  • Due to the field mapping limitation in Integration Center, it is not possible to map multiple values. It is only possible to set one primary value.
  • std_position_obj and sfstd_jobLocation_obj are always appearing as object list in OData API, regardless of whether they are single-select or multi-select.

Object list fields are appearing as "xxx Object list to <Object Name>". Expand it and map the CSV columns to "externalCode" and "isPrimary".


(7) Job Title, Job Description Header and Footer (jobReqLocale entity fields)

 - Column(s) in the CSV file:

  • locale - Enter the locale code, e.g. "en_US". Only one locale can be accepted. If the locale is not provided, it will automatically set the default language.
  • externalTitle - External Job Title
  • jobTitle - Internal Job Title
  • templateHeaderFooter - Use this field to apply a template from 'Manage Job Posting Header and Footer'. Enter the exact template name.

If there is no template, use the following fields to create the job posting header and the footer:

  • extJobDescHeader - External Job Description Header (HTML format)
  • extJobDescFooter - External Job Description Footer (HTML format)
  • intJobDescHeader - Internal Job Description Header (HTML format)
  • intJobDescFooter - Internal Job Description Footer (HTML format)

If there is no Job Profile integration, use the following fields to create the job description:

  • externalJobDescription - External Job Description (HTML format)
  • jobDescription - Internal Job Description (HTML format)

Note: For richText type fields, such as the External Job Description Header, please provide the text string in HTML format.

 - How to map the field:

Locate the navigation property "Job Requisition Locale (jobReqLocale) to JobRequisition". Expand it and map the CSV columns to the fields accordingly.

Note: Due to the field mapping limitation in Integration Center, it is not possible to map these jobReqLocale entity fields to multiple locales.


(8) Operator and operatorTeam fields (Recruiter, Hiring Manager, etc.)

 - Column(s) in the CSV file: the "username" of the user.

 - How to map the field:

Operator fields are appearing as "xxx to JobRequisitionOperator". Expand it and map the CSV column to "Operator Username (userName)".

Note

  • For operatorTeam fields, it is recommended to use Manage Recruiting Teams Settings to manage and apply the default groups and users. 
  • It is not supported to add groups or multiple users using Integration Center. However, it is possible to add one single user.


(9) Job postings

There are two ways to post job requisitions when working with API.

a. Using a business rule

By using a business rule, it is possible to post job requisitions either immediately or at a predetermined time in the future.

For details, refer to the User Assistance Documentation - Posting Job Requisitions Using Rules.

b. Using the "JobReqPostings" property

Refer to the samples in the User Assistance Documentation JobRequisitionPosting.

 - Column(s) in the CSV file:

  • Job Board Id (boardId) - Supported values are: "_external", "_internal", "_private_external", "_private_internal", "_agency"
  • Posting Start Date (postStartDate)
  • Posting End Date (postEndDate)
  • Channel ID (channelId) - A numeric ID of agency.

 - How to obtain the value:

To obtain the channelId of an Agency, use API to query the channelId from a job requisition that has been posted to the agency.

 - How to map the field:

Locate the jobReqPostings property and map the CSV columns to boardId, postStartDate and postEndDate. The channelId is required for agency posting.

Note: Due to the field mapping limitation in Integration Center, it is not possible to map the boardId to multiple values for posting job requisitions to multiple job boards.

See Also

KBA 2771951 - How to update Job Requisition fields using Integration Center - Recruiting Management

User Assistance Documentation Links:

Keywords

RCM, API, Job Requisition, Integration Center, mass, bulk, create, pre-approved, approved, Posting, Job Profile, Object, Date, Picklist , KBA , LOD-SF-RCM-INT , Integration Center & Intelligent Services , LOD-SF-RCM-JOB , Job Postings & Requisitions , LOD-SF-RCM-API , Webservices & APIs , How To

Product

SAP SuccessFactors Recruiting all versions