2085185 - Compensation - Using SFAPI and defining API comp-group ID feature

• 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 to get the Group ID option added to a compensation template

**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 Compensation

Updating Templates

The following explains how to update your Compensation 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.
• This can be done via a CCOR process by providing the name which you want to use for your group ID, alternatively please speak to your partner. For example

       <comp-group id="some-value">

• Please provide the ID you want to use as your ID, and we will use that in place of "some-value".
• As a best practice 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. Please backup a copy or original before applying any changes.

More Information About comp-group

Fields

• 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 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:

     > 2019 Compensation Planning
     > 2019 Executive Stock and Bonus Planning
     > 2020 Compensation Planning
     > 2020 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:

1. In the Provisioning tool, select "Form Template Administration".
2. Select the desired Compensation Plan Template from the list that appears.
3. 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.
4. 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.
• Fields with the same compensation field id (ie, "currentSalary" field) will share the same data for this field from the staging table.

Permissions

Now the entity is available in the API, you must give permission to an API user to access this entity. The following must be granted to the required API user.

• 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.
• 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.
• For RBP, this is available in permission settings under General User Permission> API User Login.

1. 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.

SFAPI ADHOC Query

At the end of the compensation planning process, the results can be exported from SuccessFactors through the Ad Hoc Reporting framework. The SuccessFactors API can be used to pull results for an existing Ad Hoc Report.
For API users with appropriate authorisation, each Ad Hoc Report that is available to the user will also be available through the API as a separate API entity. The AdhocReport entities will appear in the API with a name of "AdhocReport_<report_id>", where "<report_id>" is an internally generated unique id for each report. Through Admin Center> SFAPI Data Dictionary tool , you can view the various AdhocReport entities, and find see the report names which were given when reports are created in the AdHoc. Note that you must grant a user with permission to view the API Data Dictionary.

The AdhocReport entities are built on top of the Ad Hoc Report Builder framework. The reports are defined separately in the user interface of the Ad Hoc Report Builder tool. For a user who has API Login Permission,
any report they can run in the BizX suite is now available to be run through the API. The reports are run asynchronously by submitting an API asyncQuery job, which returns a job id. The job is posted to in internal
report server processing queue, which can be polled to see when the job is completed. When the job is finished, the results are retrieved as a CSV file attachment using the getJobResults API.

The process of this is as follows.

• Create a report from Analytics based on Compensation Planning and a selected template
• Selected the required columns and save the report. Preview this to ensure data is being populated correctly

• While still editing the report you've created, download the data set XL

Note

Should there be no option to download the data set, please check your provisioning company settings and ensure the below option is enabled.

To check and enable this, please contact your partner for this access.

• Within the exported file will be the database columns required for querying this report through API

• From Admin Center navigate to SFAPI Directory
• Locate the report created

• Here, we can see the columns selected when creating the report as well as the name, domain and so on
• Take a note of the ID from this report which will be used in the API requests. In this example we are using 598
• Using your preferred application, the first step would be to trigger a file creation using submitQueryJob on selected columns
• In this example, we are referencing the Merit values from report 598

• Execution of this will populate the following response

• Take a note of the taskId as this is what's used to export/reference this data
• A provisioning job will be triggered and once completed the data can then be queried

• Since the job has completed we can now reference the data. So, to do this we run the following getJobResults query

• The following is the response which populates the column being referenced. In this example we are looking for Merit

SF, success factors, CMP, role based permissions, rbp, EmployeeCompensationStagingFields, comp-group id , KBA , sf compensation worksheet design , sf api , LOD-SF-CMP , Compensation Management , LOD-SF-CMP-API , Webservices & APIs , How To

SAP SuccessFactors Compensation all versions ; SAP SuccessFactors HCM Suite all versions