2981609 - Create and Update Job Requisition with multiple positions via ODATA API - Recruiting Management

This article describes how you can Create and Update Job Requisitions with multiple positions via ODATA API as part of the new feature added in b2011 (RCM-74462 - OData Support for Position Generic Object on Job Requisition and Job Offer). This also covers some of the common errors received when performing the creation and updates.

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

SAP SuccessFactors Recruiting Management

API WARNING: API upsert is a powerful tool to help you automate manual tasks and edit data that is not possible or difficult to do in the UI. However, this can also lead to unintentional data changes if mishandled. Make sure you understand how to use the ODATA API Data Dictionary and the integration tools in general. If possible, test first with your preview environment and with only a subset of your data to see whether you are getting the intended results. 

Moreover, creating scripts and making recommendations on how to make them are outside support scope and are typically requests handled by partners. If you have issues that are possible defects, please feel free to reach out to Support.

1. The payload follows this format. This payload is the bare minimum without any other required fields in the requisition template.

{
    "__metadata": {
        "uri": "JobRequisition",
        "type": "SFOData.JobRequisition"
    },

    "templateId": "5427",
    "jobReqLocale": {

        "jobTitle": "Senior Engineer II",
        "externalTitle": "Senior Engineer II"
    },

    "std_position_objlist": [
        {
            "isPrimary": true,
            "__metadata": {

                "type": "SFOData.JobReqGOPosition",
                "uri": "JobReqGOPosition"
            },

            "value": {
                "code": "Engineering001"
            }
        },
        {
            "__metadata": {

                "type": "SFOData.JobReqGOPosition",
                "uri": "JobReqGOPosition"
            },

            "value": {
                "code": "Engineering002"

            }
        }
    ]}

2. The requisition created would look like as follows:

1. 3. Here's the successful response payload. 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
    <entry>
        <content type="application/xml">
            <m:properties>
                <d:key>JobRequisition/jobReqId=23291</d:key>
                <d:status>OK</d:status>
                <d:editStatus>INSERTED</d:editStatus>
                <d:message>Job Requisition has been inserted successfully</d:message>
                <d:index m:type="Edm.Int32">0</d:index>
                <d:httpCode m:type="Edm.Int32">201</d:httpCode>
                <d:inlineResults m:type="Bag(SFOData.UpsertResult)"></d:inlineResults>
            </m:properties>
        </content>
    </entry>
</feed>

Notes:

a. The templateId in the payload must be replaced with the actual values that you have in your instance. 

b. The isPrimary property is a boolean property (true or false) that tells the system whether the position is the primary position code or not.

c. The steps on how to create the requisition with multiple positions is no different from the typical way of creating requisitions mentioned in KBA 2848692 with the addition of std_position_objlist which is a new feature added in b2011 that exposes std_position_obj via ODATA API. You have to have this field defined in the job requisition template to use std_position_objlist for API requests.

<field-definition id="std_position_obj" type="object" required="false" custom="false" object-type="Position" multiselect="true">
<field-label><![CDATA[Position Object STD]]></field-label>
<field-label lang="de_DE_SF"><![CDATA[Position Object]]></field-label>
<field-description><![CDATA[Position Object]]></field-description>
</field-definition>

d. The code in the payload are position codes from Manage Positions.

e. Unlike when creating the Requisition from Position (or Position Org Chat), the information linked to the positions (like Department, Division, Location, etc.) will not be automatically sent over to the created requisition. 

f. As a rule of thumb, a position code can be linked to only one requisition while one requisition can be linked to multiple position codes.

g. Here is a sample GET request of the std_position_objlist:

REQUEST: https://apisalesdemo8.successfactors.com/odata/v2/JobRequisition(23291L)?$expand=std_position_objlist&$select=std_position_objlist  

RESPONSE

{
        "__metadata": {
            "uri": "https://apisalesdemo8.successfactors.com/odata/v2/JobRequisition(23267L)",
            "type": "SFOData.JobRequisition"
        },

        "std_position_objlist": {

            "results": [

                {
                    "__metadata": {

                        "uri": "https://apisalesdemo8.successfactors.com/odata/v2/JobReqGOPosition(11884L)",
                        "type": "SFOData.JobReqGOPosition"
                    },

                    "jobReqMultiSelectId": "11884",
                    "jobReqId": "23267",
                    "fieldName": "std_position_obj",
                    "isPrimary": true,
                    "value": {

                        "__deferred": {

                            "uri": "https://apisalesdemo8.successfactors.com/odata/v2/JobReqGOPosition(11884L)/value"
                        }
                    }
                },

                {
                    "__metadata": {

                        "uri": "https://apisalesdemo8.successfactors.com/odata/v2/JobReqGOPosition(11885L)",
                        "type": "SFOData.JobReqGOPosition"
                    },

                    "jobReqMultiSelectId": "11885",
                    "jobReqId": "23267",
                    "fieldName": "std_position_obj",
                    "isPrimary": false,
                    "value": {
                        "__deferred": {
                            "uri": "https://apisalesdemo8.successfactors.com/odata/v2/JobReqGOPosition(11885L)/value"

                        }
                    }
                }
            ]
        }
    }

4. Here are some of the Common Errors:

a. Error "Remove duplicate values for std_position_objlist, with the index 0." This happens when two or more codes for a specific requisition is the same. In this case, both position codes are set to Engineering001. A position code can only be linked to the requisition once and therefore, be declared only once in the payload.

{
    "__metadata": {

        "uri": "JobRequisition",
        "type": "SFOData.JobRequisition"
    },

    "templateId": "5427",
    "jobReqLocale": {
        "jobTitle": "Senior Engineer II",
        "externalTitle": "Senior Engineer II"
    },

    "std_position_objlist": [

        {
            "isPrimary": true,
            "__metadata": {

                "type": "SFOData.JobReqGOPosition",
                "uri": "JobReqGOPosition"
            },

            "value": {
                "code": "Engineering001"

            }
        },
        {

            "__metadata": {
                "type": "SFOData.JobReqGOPosition",
                "uri": "JobReqGOPosition"
            },
            "value": {
                "code": "Engineering001"
            }
        }
    ]}

b. Error "The std_position_obj Engineering001(Engineering001) you are trying to save to the job requisition is assigned to another job requisition 23284. Saving the same position across different job requisitions may lead to data inconsistencies. Select a different position value. The std_position_obj Engineering002(Engineering002) you are trying to save to the job requisition is assigned to another job requisition 23284. Saving the same position across different job requisitions may lead to data inconsistencies. Select a different position value. with the index 0." This happens when the position code is already linked to an existing requisition. A position code can be linked to only one requisition. If the position code is already linked to an existing requisition you cannot link it to a new requisition unless you unlink it to the old one. 

c. Error "Engineering003, Engineering004 is/are invalid values of std_position_objlist. Enter valid external code, with the index 0." Just like creating requisitions from position, the position code has to come from a valid position i.e., Status - Active, To be Hired - Yes, with valid Division, Department, Business Unit, and Location, etc. See KBA 2878365 for more information.

5. Here is a sample UPDATE on the std_position_objlist of an existing job requisition.

{  "__metadata": {


               "uri": "JobRequisition(23267L)",
               "type": "SFOData.JobRequisition"
           },

          "std_position_objlist" : [
              {

                "isPrimary": true,
                "__metadata": {
                  "type": "SFOData.JobReqGOPosition",
                  "uri": "JobReqGOPosition"
                },

                "value" : { "code": "POS20201001A" }
              }, 

               {
                "isPrimary": false,
                "__metadata": {
                  "type": "SFOData.JobReqGOPosition",
                  "uri": "JobReqGOPosition"
                },
                "value" : { "code": "POS20201001B" }
              }
            ]
        }

6. Here is the successful response payload for the update.

[
        {
            "key": null,
            "status": "OK",
            "editStatus": "UPDATED",
            "message": "Job Requisition has been updated successfully",
            "index": 0,
            "httpCode": 204,
            "inlineResults": null
        }
    ]

2885326 - How to use Postman on performing ODATA API Requests - Recruiting Management
2817669 - ODATA API Data Dictionary - Recruiting Management
2215682 - Successfactors API URLs for different Data Centers

ODATA API Reference Guide

errors, std_position_obj, std_position_objlist, invalid, values, enter, valid, external, code,  index 0, integration, JobRequisition, upsert, Insert , KBA , LOD-SF-RCM-API , Webservices & APIs , How To