Performance Rating and Comments Upload via Integration Centre in SuccessFactors

[Karthi_Viswa]

We do not have a standard solution for updating Ratings and Comments in the Performance form on behalf of the User or Manager.

This is one approach to uploading Ratings and comments in performance form via the Integration Centre, which is available within SuccessFactors.

Prerequisite: Step 1

Permission System	Required Settings
Role-Based Permissions	Manage Documents >> Admin Acces to Forms OData API If you want to fetch the deleted forms, select Include Deleted forms in Forms ODATA API.

NOTE: Above permission works for the FormHeader API only. If you have the parent permission, Admin Access to Forms OData API, but don't have the Include Deleted forms in Forms ODATA API permission, you can use the FormHeader API to query active forms only. For other APIs, with the parent permission, you can query both active and deleted forms.

Admin Access to Forms OData API allows you to query forms of all users, but this might be restricted by the specific form template permissions.

This is an important Prerequisite: Users with "Admin access to OData API" permission can access all the forms that are not in their folders but cannot edit them. Editing is permitted only for the forms in the user's inbox. The Admin save action is not supported now.

Reference KBA: https://me.sap.com/notes/2541548 

So, Ensure the API or admin users who perform this action have access to all the forms. It should also be visible in the Performance Inbox, so create/configure your route map accordingly.

As per the API Reference Guide, we should use "FormPMReviewContentDetail" to query and Upsert "Ratings" and "Comments"

Refer here: https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/0840ac3f68b24... 

Before Moving to Configuration, please note the entities below; we will need them as mandatory data to perform Upsert on Ratings or Comments. (Prerequisite Step 2)

• formcontentid (system generates)
• formdataid (system generates)
• itemid (system generates)
• ratingType (system generates)
• sectionIndex (system generates)
• userId - USERID
• ratingkey - (system generates)
• rating (user)
• commentkey - (system generates)
• comment (user)

All the above System generated Id can be fetched in Three ways,

• Create a standard report >> Choose domain as Performance Management >> Select the above columns under Form Section

OR

• Create a Simple File Output Integration >> Choose entity as "FormHeader" under Tag "Performance and Goals (PM/GM)" >> Query all the above entities

OR

• Contact your CPI consultant, give them the element and path and it can be queried and extracted.

Note: We cannot query all the above entities directly via "FormPMReviewContentDetail" so we will have to query via "FormHeader" entity only.

Build and Configuration:

Integration Centre >> Scheduled CSV Input Integration

Choose Tag: Performance and Goals (PM/GM) >> Entity: FormHeader >> Click Select.

Go to Configure Fields Section >> Operation: Upsert Multiple >> Purge Type: FullPurge >> Click "Add Entity" 

In Add Entity >> Choose "FormPMReviewContentDetail" >> Click "Add"

Once the "Add" button is clicked, We will end up on the page below, ready to map the fields from the extract -Prerequisite Step 2. Remember the system-generated fields in Prerequisite Step 2(refer to above). Now, you will need those extracts to map the fields for the upsert.

The extract I have based on my requirement to upload the manager's rating and comments,

Once the "Add" button is clicked, We will end up on the page below, ready to map the fields from the extract -Prerequisite Step 2.

Now Click "Upload Sample CSV" on the top right of the page >> choose the file >> and click Upload>> if there appears a warning like the file is not in UTF-8 format, that's fine. Click "OK"

Next, switch to Field Mapping View.

• Left Section - We get to view the Header.
• Middle Section - We have the fields available for mapping.
• Right Section - shows the output.

All We have to do is DRAG and MAP - From Left Section to Middle Section - Field to Field

After Drag and mapping, mapped field values will look like below,

Now, on the Destination Fields, Scroll and expand ObjectiveSections to FormObjectiveSection

Expand >> ObjectiveSections to FormObjectiveSection

Under ObjectiveSections to FormObjectiveSection Expand >> objectives to FormObjective

Under objectives to FormObjective >> Expand OfficialRating to FormUserRatingComment and do drag-and-drop mapping.

A quick overview of the entity expansion and structure to reach ratings,

NOTE:

• OfficialRating - to upsert Managers' Ratings to users
• SelfRating - to upsert employees' rating

I will upload official ratings, that is, ratings from managers to users, so I have mapped only official ratings.

Build and configure them as per your upload requirements. I just show the paths and build; it is flexible but tricky.

After the Mapping, We can view the values against mapped fields if we switch to File Import Test View.

And Source Settings >> SFTP details >> Save and Run.

Not Required to schedule it, you can run it once and it should get uploaded.

A few More Points to Note: 

• the form is in the inbox of the user who is going to upsert data.
• User with "Admin access to Forms OData API" permission is allowed to query the all form data of their target population but is not allowed to edit, add, or delete them. Edit action is permitted only for the forms which are in users' inbox.

For more details on this permission, please refer to KBA 2541548.

• If you are using employee tokens (generated by formSubjectId/userId) to upsert data to forms in an employee's inbox, please consider the following:
• if you are upserting to the latest content id, especially if the form has been routed several times (each routing of the form will generate a new content id);
• Rating Key is an important value, as it is tagged differently for each goal.
• The employee/api user has "write" permission to the field that is to be upserted.

Happy Rating! Hope this helps.

A big thanks and kudos to @JohannD  for all his extended support in achieving this.

[pmarcoavendano]

Dear @Karthi_Viswa  @JohannD 

Thanks for sharing this blog and knowledge.

One doubt on the functionality, It's still not clear for me if we need to load comments on behalf of a manager if we can do this with a technical api user and comments be saved on the manager name or not. E.g: our technical user is api_sf user id and manager id is  manager1.

Our requirement is to save comments in competencies on behalf of the  manager and we have done some checks but we havent succeeded. Therefore, we have this doubt, if even using an api user "api_sf" we can operate on behalf manager1

 (Prerequisite Step 2)

• formcontentid (system generates)
• formdataid (system generates)
• itemid (system generates)
• ratingType (system generates)
• sectionIndex (system generates)
• userId - USERID
• ratingkey - (system generates)
• rating (user)
• commentkey - (system generates)
• comment (user)

[JohannD]

Hi @pmarcoavendano 

As far as I know, the comments uploaded via API will be displayed on the form as "Comments By" the user who inserted the comment, in your case, the api_sf user.  The option I can propose is to create a custom field to store these comments.

Hoping this info be useful to you

Johann

[anastrukan]

Dear @JohannD & @Karthi_Viswa, 

As part of Prerequisite Step 2, it is mentioned that we need to fetch the system generated IDs of 10 entities (formcontentid, formdataid...) as they are mandatory data to perform Upsert on Ratings or Comments.

The majority of them are not available via Report Center (we see the fields, but not the system generated IDs behind), and when trying the second approach, to export it via Integration Centre, only group/team goals are displayed.

Have you come across such issue before?

Many thanks!
Ana