Human Capital Management Blog Posts by SAP
Get insider info on SAP SuccessFactors HCM suite for core HR and payroll, time and attendance, talent management, employee experience management, and more in this SAP blog.
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 
Read only

Performance Management and API: How to query performance rating via ODATA v2 API as an admin user

Makki_Chen
Associate
Associate
‎2024 Aug 30 11:16 AM
2,891

This article covers pre-requisite of using Odata v2 API to retrieve rating from performance forms and provides example how-to and uri for certain scenarios.

RBP permission for API query as an admin user
Make sure the admin user has the permission: Manage Documents > Admin Access to Forms OData API permission.

Makki_Chen_0-1725000410117.png

Note
1. If you have the form OData admin permissions, you will be allowed to query the form data, but you will not be able to edit, add, or delete form data. You can only access the folders and forms, whose owner is in your target population.

**Edit via API: Users who have "Admin access to OData API" permission can access all the forms which are not in their folders, but they cannot edit it. Edit action is permitted only for the forms which are in the API users’ own inbox.

2. When using FormHeader entity to query data, if you want to fetch the deleted forms, select “Include Deleted forms in Forms ODATA API”.

3. “Admin Access to Forms OData API” permission allows you to query forms of all users, but this might be restricted by the specific form template permissions.
**What does “Form template permission” mean: section permission and field permission configured in form template.

For example, the admin user wants to query data in summary section, but hidden permission is configured for all roles in all steps for the section:

Makki_Chen_1-1725000660126.png

Then, when querying summary section, the result would return “null”:

Makki_Chen_2-1725000692649.png

 

This logic also applies to field permission:

Makki_Chen_3-1725000716849.png

If manual overall rating is enabled for summary section, but none permission is configured for “Manual Overall Rating” field for all roles in all route steps, when admin user queries form's final official rating (overallFormRating) in summary section, the API returns “null”:

Makki_Chen_4-1725000739306.png

Authentication
Please refer to the guide here for more information on authentication: Authentication

API server list
List of SAP SuccessFactors API Servers

Query options

1.You can query with key predicate, for example,

https://<API-Server>/odata/v2/FormHeader('12345')

*the number in the single quotation mark is form id (formDataId).
With this uri, you query the data for one form only.

2. Or, you can also query with system query options, for example,

https://<api server>/odata/v2/FormHeader?$format=json&$filter=formSubjectId eq 'sfadmin' and formDataStatus eq 3&$orderby=formDataId desc

*formDataStatus: 3 stands for form in completed stage. Please refer to the guide here formDataStatus for more details.
With this uri, you query data for forms whose subject is sfadmin, whose form data status is completed and ordering the returned result by descending order of form id.
More details on system query options: System Query Options

 

Basic Scenario 1: get the final rating of a performance form
In below example form, in summary section the manual overall rating is 5 and calculated form rating is 1.38.

Makki_Chen_5-1725001080013.png

Uri:
https://<api server>/odata/v2/FormHeader?$format=json&$filter=formSubjectId eq 'xxxxx' and formDataId eq XXXXX&$expand=formLastContent/pmReviewContentDetail/summarySection/overallFormRating,formLastContent/pmReviewContentDetail/summarySection/calculatedFormRating&$select=formLastContent/pmReviewContentDetail/summarySection/overallFormRating/rating,formLastContent/pmReviewContentDetail/summarySection/calculatedFormRating/rating

**Replace subject id and form data id in the uri

Query result:

Makki_Chen_7-1725001313703.png

 

Note
1.To get the latest rating info, start expanding from formLastContent.

2.To get calculated form rating, make sure that

    (1) in form template xml, in fm-meta section, display-calculated-rating is set to "true", regardless of scale adjusted calculation is enabled or not. For example:

<scale-adjusted-calculation enable="false" display-calculated-rating="true">
</scale-adjusted-calculation>

    (2) no field permission configured on the “calculated-overall-rating” field that restricts the API user from accessing it.

 

Basic Scenario 2: Not sure which navigation entity leads the rating you want to query
In this scenario, you can expand the hierarchy level by level to get to the rating you want.

Take the above form as an example,

1. Expand to summary section first: $expand=formLastContent/pmReviewContentDetail/summarySection

2. Notice that there are several navigation properties inside summaySection:

Makki_Chen_8-1725001389088.png

3. Then, try expand further the related entities from the navigation properties to check the result. For example,

$expand=formLastContent/pmReviewContentDetail/summarySection/calculatedFormRating,
formLastContent/pmReviewContentDetail/summarySection/overallFormRating

4. The example form has manual overall rating 5 and calculated form rating 1.38 on form. In the returned API result, check which rating value matches the one you want to query on form.

You can see that rating 1.38 is under “calculatedFormRating”:

Makki_Chen_9-1725001478003.png

rating 5 appears under “overallFormRating”:

Makki_Chen_10-1725001502718.png

 

Advanced Scenario: query official rating given in every route step

In ad hoc report or story report, it is not possible to retrieve official rating submitted in every route step. You can only fetch the final rating.

But it is possible with API. As a new form content is generated for every step routed in performance forms, we can fetch the rating from every generated form content via formAuditTrails/formContent.
* Different to formLastContent, which only returns the latest form content.

Uri:
https://<api server>/odata/v2/FormHeader?$select=formAuditTrails/formContent/pmReviewContentDetail/summarySection/overallFormRating/rating,formAuditTrails/formContentAssociatedStepId,formAuditTrails/formContentId,formDataId&$expand=formAuditTrails/formContent/pmReviewContentDetail/summarySection/overallFormRating&$filter=formTemplateId eq xxxx&$format=json

Note
1. Please note that it is not possible to get the rating for all forms in the instance in one go. Please consider use formTemplateId as filter so you can query the results by template.

**You can get form template id by

  •  PM domain report or via provisoning > Form Template Administration > find the template > ID;
  •  Or create an ad hoc report on performance management domain to check form template id.

2. if the returned data is too large, you may encounter timeout issue. In such case, you can customize the page size by setting a different number with parameter: Custom Page Size

 

What you need to provide to support for API case troubleshooting

  • company id
  • support access (2088892 - How to Grant Support Access to SuccessFactors Support Staff)
  • authentication used
  • uri used
  • response or error message received
  • If possible, provide API Audit log: 3141692 - How to provide API Audit Logs to Cloud Support - SuccessFactors
  • Expected result

 

Kba and guide reference

 

3 Comments