SAP Knowledge Base Article - Public

2817669 - ODATA API Data Dictionary - Recruiting Management

Symptom

This article describes the information inside the ODATA API Data Dictionary.

"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

General Information:

  1. OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs.
  2. Structure - The structure of the entities and properties in the ODATA API is a little different from SFAPI which is now deprecated.
    sfapi.png
    • In SFAPI, if you want to call a field or property inside the Job Requisition, your main entity will be JobRequisition$TemplateID of whichever Job Requisition Template that field is defined. So, if you have a custom field called salary that is defined in Requisition Template 8 and 661 but not defined in the other templates, you can only query the field from under JobRequisition$8 andJobRequisition$661, else you will encounter an error message saying the field cannot be found.
      odata.png
    • In ODATA, there will be an entity for the Job Requisition Templates and also a main entity called JobRequisition. It is advisable to always use the main entity for queries and upsert requests for your integrations, i.e., JobRequisition, JobApplication, Candidate, JobOffer, and OfferLetter.
    • There are also Recruiting Management Entities that do not have a template equivalent (like Job Requisition and Job Application) that are available in the API dictionary by design, i.e., JobApplicationInterview, JobApplicationAssessmentOrder, etc.
    • Almost all entities that start with Job* and Candidate* are managed by Recruiting Management.
      odata3.png
  3. There are 3 ways for a property to be reported in the ODATA API Data Dictionary.
    odata2.png
    • They are standard fields defined in any Recruiting Template (i.e., Job Requisition, Job Application, Candidate Profile, and Offer).
    • They are custom fields defined in any Recruiting Template (i.e., Job Requisition, Job Application, Candidate Profile, and Offer) and the field is declared as custom reportable in Provisioning > Configure Reportable Custom Fields.
    • They are default fields like applicationInterviewId and expectedAnswer that are readily available in the API dictionary by design. Most properties from non-template entities, like JobApplicationInterview and JobApplicationAssessmentOrder which do not have corresponding templates like Job Requisition and Candidate, fall under this category.
    • Note: As a rule of thumb, if the field is not in any of the Recruiting Management templates, that field is considered as a default field predefined in the ODATA API DATA Dictionary. Moreover, unless you can add the field in any of your Recruiting Management templates so that it will be considered as a custom field, we cannot add any fields in the API Data Dictionary.
  4. When looking at the properties from template entities (like Job Requisition, Job Application, Candidate Profile, and Offer), the value in the type column of the data dictionary should reflect the type in the template.
    • For example, the address is defined as a text in the application template.
      <field-definition id="address" type="text" required="true" custom="false" public="false" readOnly="false" anonymize="true" forward-intact="true" sensitive="false">
    • It should be appearing as string in the API dictionary. If the field is a curreny, it should be appearing as a decimal, etc.
      odata5.png
  5. The ODATA API Dictionary does not mirror Ad Hoc Reports. This means the fields/properties that can be found in the Ad Hoc Reports may not necessarily be available in the ODATA API Data Dictionary and vice versa. For example, the JobReqScreeningQuestion is available in ODATA API Dictionary but it is not in Ad Hoc Reports.
    • Moreover, ODATA API Dictionary has JobApplicationStatusAuditTrail while Ad Hoc Reports > Recruiting V2 has App Status Audit Trail.
      odata6.png
    • If you compare the properties inside the 2 entities there are several similaries but there are also differences, notably, the App Status Audit Trail has Time in Status and Is Current Status that are not in the JobApplicationStatusAuditTrail entity in ODATA API Data Dictionary.
      odata7.png
  6. The columns across the properties are attributes.
    • Nullable: Determines whether a property can be set to blank or null.
    • Required: Determines whether a property is a required field or not. If you try to make an upsert request for an Entity and you missed a certain required property, your request will error out.
    • Creatable: Determines whether a property can be created.
    • Updatable: Determines whether a property can be updated.
    • Upsertable: This is a combination of create and update. Determines whether a property can be created when it is not yet available or updated if it is already existing.
    • Visible: Determines whether a property can be queried.
    • Sortable: Determines whether a property can be sorted.
    • Filterable: Determines whether a property can be used as a filter, i.e., be used for $filter option.
      odata8.png
  7. The same entity and properties are available in the Integration Center.

See Also

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

ODATA API Reference Guide

Keywords

ODATA, ODATA API, Data Dictionary, Recruiting Management, RCM, Integration , KBA , LOD-SF-RCM-API , Webservices & APIs , How To

Product

SAP SuccessFactors Recruiting all versions