OData API Support for Position Generic Object on Job Requisition and Job Offer

Hello SAP Community,

With the advent of the 2H 2020 in SAP SuccessFactors, the Entities Job Requisition and Job Offer in OData now support the Position Generic Object, so it is now possible to use both OData API and the UI to create a Job Requisition or Offer with the Position Generic Object. We would like to share a working example using OData API.

The environment used was a SalesDemo hosted on DC4 which is using the b2011 release version.

All the images and data used here were taken from SAP SuccessFactors SalesDemo instance, which means that it is all dummy data.

Objective:

Provide and working example that could help our customers and partners on the decision of implementing this approach in their local environments and/or projects.

Supporting documents for this set up:

• SAP SuccessFactors What’s New Viewer – OData Support for Position Generic Object on Job Requisition and Job Offer – (2H 2020)
• SAP SuccessFactors HXM Suite OData Reference Guide – (2H 2020)
• Set Up and Maintaining SAP SuccessFactors Recruiting – (2H 2020)
• All documents include the “/latest” in the URL, so in the future, the document might have some different procedures that are not covered in this blog post.

Constraints:

Let’s start with the constraints, so we can clear our path before implementing and executing the next required steps. The imminent blockers that must be checked are API Visibility and  Security on Object Definition.

When running OData API operation on objects, we must ensure that the object that we would be manipulating is API accessible. The way to check that is by accessing Configure Object Definitions and searching for the Position Object:

Selecting this will lead you to the Definition of the Object, which contains API Visibility and Security. Just by opening the Position Object, we can see in the first few lines our API Visibility setting. This setting is what will grant the option to use this object when running API queries, so it is strictly recommended to be checked and confirmed that it is Editable, or Read Only:

Scrolling down towards the bottom of the page, the Security section is found. This is where access to the Object is defined granted. The Secured option could be either Yes or No. No means that no permissions are considered while accessing data for this Generic Object, which is what we are going to use in this example:

Another constraint that must be taken into consideration is that when a Position is being associated with a Job Requisition, the system runs a Duplicate Position Check, and in case the Position that is trying to be associated with the Job Requisition is already on another Open Job Requisition, it will fail.

Configuration:

There are a couple of pre-requisites in terms of configuration that should be met to take full advantage of this feature:

1. Ensure that you have the std_position_obj configured with multi-select set to True:
   
2. Also, make sure that your std_position_obj field is mapped to the Job Offer from the Job Requisition :
   

Job Requisition:

With the templates all set up, a Job Requisition has been created and a Position was selected inside the Position Object field.

Query

This Job Requisition was created directly through the UI and no Positions associated with it. Executing a query on it will look as the following:

Request: https://apisalesdemo4.successfactors.com:443/odata/v2/JobRequisition(2780)?$expand=std_position_objlist&$format=json

Response:

[…]

Upserting the Job Requisition with Positions

Executing now an upsert on the same Job Requisition adding a new Position association to this Job Requisition.

Request: 

<content type=”application/xml”>

    <m:properties>

    <d:key m:null=”true”></d:key>

    <d:status>OK</d:status>

    <d:editStatus>UPDATED</d:editStatus>

    <d:message>Job Requisition has been updated successfully</d:message>

    <d:index m:type=”Edm.Int32″>0</d:index>

    <d:httpCode m:type=”Edm.Int32″>204</d:httpCode>

    <d:inlineResults m:type=”Bag(SFOData.UpsertResult)”></d:inlineResults>

    </m:properties>

</content>

“std_position_objlist”: {

    “results”: [

    {

        “__metadata”: {

            “uri”: “https://apisalesdemo4.successfactors.com:443/odata/v2/JobReqGOPosition(2887L)”,

            “type”: “SFOData.JobReqGOPosition”

        },

“jobReqMultiSelectId”: “2887”,

        “jobReqId”: “2780”,

        “fieldName”: “std_position_obj”,

 “isPrimary”: true,

        “value”: {

            “__deferred”: {

                “uri”: “https://apisalesdemo4.successfactors.com:443/odata/v2/JobReqGOPosition(2887L)/value”

            }

        }

    },

    {

        “__metadata”: {

                “uri”: “https://apisalesdemo4.successfactors.com:443/odata/v2/JobReqGOPosition(2888L)”,

            “type”: “SFOData.JobReqGOPosition”

        },

“jobReqMultiSelectId”: “2888”,

        “jobReqId”: “2780”,

“fieldName”: “std_position_obj”,

 “isPrimary”: false,

        “value”: {

            “__deferred”: {

                “uri”: “https://apisalesdemo4.successfactors.com:443/odata/v2/JobReqGOPosition(2888L)/value”

            }

        }

    }

    ]

}

Accessing back the Instance, and opening the same Job Requisition that has been updated, we can see the following information on the Position field:

Conclusion:

As demonstrated by this blog post, you are now able to Query, Create, and Update the Positions that are associated with your Job Requisition via OData API. With the instructions provided in this post, you will be able to set up your Integrations to use the Position object.

We hope this post can help you and your team doing the implementation better and faster.

If you found this post to be useful, please press the like button!

Kind regards,

Eduardo