3047601 - How to upsert a custom URL via ODATA API - Recruiting Management

This article describes how to properly upsert a custom URL (usually in Job Application) via ODATA API. If you do not format your URL properly, it will result to the URL showing as h in the UI. This is the expected behavior when upserting hyperlink fields. 

"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 upserts 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 is like creating your system's configuration, they are outside support scope (and are typically requests for partners) but if you have issues that are possible defects, please feel free to reach out to Support.

The following are the steps on how to properly upsert a custom URL via ODATA API.

a. This is the custom URL field definition in the application template. 

<field-definition id="BgReportUrl" type="hyperlink" required="false" custom="true" public="false" readOnly="false" anonymize="false" forward-intact="true" sensitive="false">
<field-label><![CDATA[Custom URL]]></field-label>
<field-label lang="en_US"><![CDATA[Custom URL]]></field-label>
<field-description><![CDATA[Custom URL]]></field-description>
<field-description lang="en_US"><![CDATA[Custom URL]]></field-description>
</field-definition>  

Note: Hyperlink is considered as a valid type in application template. 
https://help.sap.com/viewer/8477193265ea4172a1dda118505ca631/latest/en-US/30ea9478ee5c44b7a1aea76cbbffc655.html

b. This custom URL field is made reportable in Provisioning. If you do not have access to Provisioning, either request your partner or open a case for Support to make your field reportable. 

c. Format your URL as follows: "fieldName":"[][URL]"

REQUEST

POST: https://apisalesdemo8.successfactors.com/odata/v2/upsert

{
"BgReportUrl":"[][https://www.google.com]",
"__metadata":{

"type": "SFOData.JobApplication",
"uri": "JobApplication(applicationId=406)"
 }
}

Note: Custom URL fields are usually used for background check result URLs or assessment result URLs, hence they are typically seen in Job Applications. 

Request Breakdown

a. The main entity JobApplication is defined as follows:

"__metadata": {
    "uri": "JobApplication",
    "type": "SFOData.JobApplication(applicationId=ID)"
}

Note: It is important to define the application ID of the application you are trying to update - applicationId=ID. 

b. The properties (or fields) you want to edit are defined as follows:

Format: "property name as seen in the ODATA data dictionary": "value"
Example: "BgReportUrl":"[][https://www.google.com]"

c. The sequence of the properties in the payload is not important, the system will read them as one payload. Hence, the payload above is the same as the payload below.

d. The letter case for the entities and the properties is important. They should be consistent to the entries and properties defined in the ODATA API Data Dictionary. For example, firstName cannot be firstname, or BgReportUrl cannot be bgReportUrl.

e. The Request has to be POST and the URL to use should be defined as follows:

Format: Endpoint URL (See KBA 2215682)/odata/v2/upsert
Example: https://apisalesdemo8.successfactors.com/odata/v2/upsert

See KBA 2882860 for more information on how to update Job Application entity in general.

f. This is what the URL looks like in the UI.

g. If you do not format your URL properly like the following:

{
"BgReportUrl":"https://www.google.com",
"__metadata":{

"type": "SFOData.JobApplication",
"uri": "JobApplication(applicationId=406)"
}
}

It will result to the URL showing as h in the UI.

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
2882860 - How to edit Job Application data via ODATA API - Recruiting Management

ODATA API Reference Guide

ODATA, API, JobApplication, Upsert, Insert, Recruiting Management, RCM, Integration, URL, h, Custom URLs, BackgroundCheck URL, Assessment URL , KBA , LOD-SF-RCM-API , Webservices & APIs , How To

SAP SuccessFactors HCM Core all versions ; SAP SuccessFactors Recruiting all versions