2085185 - Worksheet Design - API comp-group id Feature - Compensation

SAP Knowledge Base Articles - public

2085185 - Worksheet Design - API comp-group id Feature - Compensation


  • Entity type allows you to import employee current salary data to a staging table in the SuccessFactors system. This data can then be updated to in-process compensation forms through Compensation Admin Tools. 

    The API will expose a unique EmployeeCompensationStagingFields entity for each Compensation Group ID found. <comp-group id="some value">
  • How do we get Group ID option added to our compensation template?


  • Compensation


How to Update Templates

  • Adding the Group ID entity to your template is something currently not available via Comp Admin Tools and will need to be added by your support team.
  • Since this is a change to your current template xml it will require regular CCOR process, but can be completed by our Customer Support Tier 3 team once you provide us the completed CCOR along with the name you want to call your Group ID.


      Customer support will add the tag

       <comp-group id="some-value">  to your template. Please just provide us the id you actually want to use as your id, and we will use that in place of "some-value".

  • As a best practive please make it all one word, no spaces or special characters.
    (Note to Support & Partners: this tag goes below the tag <comp-manager-hierarchy type="2"/> in the template. You can add this via Provisioning > Form Templates. Backup a copy or original before applying changes.)


More Information About comp-group


  • The fields that appear in the EmployeCompensationStagingFields entity come from the compensation plan templates which are assigned a Compensation Group ID. The API will expose an entity with the name "EmployeeCompensationStagingFields_<groupId>" where <groupId> is a value that is entered into one or more compensation plan templates. These compensation plan templates will drive the fields that appear in the corresponding EmployeeCompensationStagingFields_<groupId> entity. See details below for configuring the Compensation Group ID.


    Compensation Group ID

  • Compensation Plan templates have a new optional XML attribute <comp-group id="some value"> called the "Compensation Group ID" which is used group one or more compensation plan templates into a single EmployeeCompensationStagingFields API entity. The API will expose only those Compensation Plan Templates that have added a <comp-group> tag. See configuration details in the configuration section below.


  • The Compensation Group ID will allow you to design an import intended only for the Compensation Plan templates that share the same unique Group ID. For example, assume a customer has the following four Compensation Plan templates:

    1.2015 Compensation Planning
    2.2015 Executive Stock and Bonus Planning
    3.2014 Compensation Planning
    4.2014 Executive Stock and Bonus Planning
  • We can provide a Compensation Group ID of "2015" for both the "2015 Compensation Planning" and the "2015 Executive Stock and Bonus Planning" templates. When this is done, the SFAPI will generate an API Entity named "EmployeeCompensationStagingFields_2012" which will include a union of all the unique compensation field ids that are enabled in both of these entities. Fields with the same id in each template will share the same data from the staging table based on a key of the field id and the Compensation Group ID. For example, if both the "2015 Compensation Planning" and "2015 Executive Stock and Bonus Planning" templates have a "currentSalary" field, they will share the same field data in the staging table because both of these templates share the same Compensation Group of "2012".


  • In the file based import strategy, we could achieve the same effect by assigning unique import field keys for each field in the templates, and deciding on a field by field basis whether to share a import key values on fields across different templates. For example, in the file based import, you would have to assign import key values of "2015_currentSalary" in each template that wanted to share the same data from the staging table. Then you would use the "2015_currentSalary" key as a field header in the Employee Import file. The Compensation Group ID attempts to make sharing easier across templates by using a key at the template level for all fields.


             If sharing imported field data across templates is not desired, then assign unique Compensation Group IDs to each compensation plan template.


  • Once data is imported to the staging tables, this data can be used to update in process compensation forms. This update will pull data from the staging table for the form template. It will use the compensation group ID to find the correct data. The forms can be updated from the staging table data through one of two mechanisms:
  1. Manually: You can trigger update of compensation forms for one or more templates in Admin Tools.
  2. Scheduled: Update of compensation forms for one or more templates can be scheduled on a nightly (or other interval) basis.


 Compensation Template Configuration

  1. Define the compensation planning templates.
  2. Assign a Compensation Group ID to each compensation template that you want import through the same API data feed. This is done by manually editing the Compensation Form Template in Provisioning.
  3. You can share a single Group ID among multiple compensation templates. One strategy is to group templates by yearly process, where you would designated "2015" as a group id for all the 2012 compensation planning forms. The decision on which templates to group together is an integration choice, and should be driven by how many templates you want to import in a single data feed.

          The steps to define a Group ID for a Compensation Plan template are:

     a. In the Provisioning tool, select "Form Template Administration" >

     b. Select the desired Compensation Plan Template from the list that appears. >
     c. Add a <comp-group> tag entry to specify a desired Compensation Group ID in the location below (near the very end of the XML file). The id attribute value can be any string value desired. >
     d. If desired, you can share this Group ID value with other Compensation Plan Templates, or give different values to other Compensation Plan Templates.


  • The API will expose one EmployeeCompensationStagingFields entity for each unique Group ID it encounters in all the Compensation Plan Templates. The entity will be named EmployeeCompensationStagingFields_<group_id> where the <group_id> is the string value you assigned to the "id" attribute of the <comp-group> tag above. If more than one Compensation Plan Template shares the same Compensation Group ID, then the fields that appear in the related API entity will be a union of all the unique compensation fields that appear in the related templates. And fields with the same compensation field id (ie, "currentSalary" field) will share the same data for this field from the staging table.


  • Now that the entity is available in the API, you must give permission to an API user to access this entity. The following permissions must be granted to your desired API user:


  1. Decide with user you will use to access the API. It is common to create a special user account for the purpose of API integration.
  2. Grant the API user with "API Login Permission". a.For the legacy permissions framework, this is available in Admin Tools — Manage User Security — API Login Permission.
    b.For RBP, this is available in permission settings under General User Permission — API User Login.
  3. Grant the user with "Employee Import" permission. a.For the legacy permissions framework, this is granted in the following ways: i.New Admin Tools: Admin Tools — Set User Permissions — Administrative Privileges — Manage Users — Employee Import. 
    ii.Old Admin Tools: Admin Tools — Manage Security — Administrative Privileges — Manager Users — Employee Import.
    b.For Role Based Permissions, this is granted in the following ways: i.New Admin Tools: Admin Tools — Set User Permissions — Manage Employee Import.
    ii.Old Admin Tools: Admin Tools — Manage Security — Manage Employee Import.
  • Note: Customer support typically cannot assist with API setup and anything beyond these instructions is typically handled via a paid Professional Services or Partner engagement. Customer support cannot help troubleshoot any API issues except to provide API error logs if you open a case to request these.


KBA , sf api , sf compensation worksheet design , LOD-SF-CMP , Compensation Management , How To


SAP SuccessFactors HCM Core all versions