Incent Upload People

Summary

The incent upload people command allows developers to create and maintain participant, or “person”, records within the Incent application.  The command transfers data from staging.user* tables into Incent’s xactly schema tables.

The People object defines the details of each payee in your organization and is versioned for changes over time. https://helpcenter.xactlycorp.com/article/incent-administrator-people/

People is one of 5 objects that define the organization structure in Incent:

  1. User – login profile and role assignment
  2. People – definition of payee data such as employee id, target income, and person related fields.
  3. Position – current assignment in the organization structure (a person can move between positions)
  4. Hierarchy – the hierarchical relationship of positions in the organization
  5. Named Relationships – the non-hierarchical relationship of positions in the organization (teams, overlays, etc)

People records provide many elements needed for incentive calculations:

  • First Name / Last Name – name field used for reporting throughout the application
  • Employee ID – unique identifier for each payee in the system
  • Employee Status – often used to provide conditional logic on compensation rules
  • Hire/Termination Dates – used for conditional logic and reporting
  • Personal Target – expected variable earnings for a payee used in calculation and reporting
  • Personal Salary – fixed compensation usually only used for reporting
  • Custom Fields – additional custom fields can be added based on client needs

A developer must first populate a Connect staging table with HRMS data before invoking incent upload people. The general process flow is:

  1. Delete any old rows from the staging.person* tables. Archive any rows as needed by per your business requirements.
  2. Insert rows with user account data into staging.person* tables.
  3. Call incent upload people.
  4. Check for and fix any processing errors in the staging.person_exception table.

Syntax

incent [synchronous] upload people; 

Parameters

Parameter
Description
 
synchronous
 (Optional) The upload command runs asynchronously by default when invoked, i.e. control returns immediately to the calling program and the job runs in the background on the Connect server. Use the ‘synchronous’ keyword to force the Connect server to return control only after the upload completes.

When invoked asynchronously, you can track the status of the upload by querying the SHOW INVOCATIONS command. Xactly recommends running large data sets asynchronously to avoid client query timeouts.

Details

Ensure you have registered a valid Incent username and password within Connect before invoking the upload command. incent commands require valid credentials to modify data with Incent. Refer to INCENT CREDENTIAL.

The staging schema provides one table that a developer can populate before invoking incent upload people. The table is described in detail below along with the upload’s corresponding error log table. Once the target table is populated, invoking incent upload people will process each staging row. Any errors the upload encounters during processing will be written to the staging.person_exception table.  Xactly highly recommends the developer check for any errors in staging.person_exception after the command completes to ensure all staging person rows were uploaded into Incent as expected.

Note: Every distinct person in Incent must have a valid row in the xactly.xc_user table before the upload can create a person record. Refer to INCENT UPLOAD USERS.

The following tables describe the columns in the staging tables:

staging.person – (Required)
Column Name Data Type Description xactly Target Table
action string (Required) Instructs the type of operation the upload should perform on the row. incent upload people has five options:

  • ‘create‘ – tells the upload command to create the first master record for a new person in Incent. Leavestaging.person.effective_start_date null when using create. Incent will create the master version of a person using the start of time and end of time effective dates (1970-01-01 and 2035-12-31, respectively).
  • ‘purge‘ – attempts to delete a person from Incent. Purge works when the person does not have ties to other Incent data (position record or compensation results, for example).
  • ‘deleteversion‘ – deletes the version of the person given thestaging.person.effective_start_date. Delete will readjust thexc_participant.effective_end_date of the prior version when deleting in between versions.
  • ‘add version‘ – inserts a new version of the person into Incent and adjusts the effective_end_date of the earlier version. The upload cannot create versions between two versions that already exist within Incent; use a series of ‘delete version’ and ‘add version’.
  • ‘save version‘ – updates the values for a given person version in Incent. The version updated is driven byeffective_start_date.

incent upload people makes multiple passes over the staging.person table. The command processes “actions” in the following order: purge, create, delete version, add version, and finally, save version. Within the verb processing order, incent upload people processes the staging rows according to their natural order within thestaging.person table. Therefore, insert rows into the staging table in the desired order in which you want them processed. An example is ordering inserts into stage byemployee_id and effective_start_date.

 n/a
employee_id string (Required) The business’ unique identifier for a person.Employee_id is not a primary or unique key in the relational database sense, as the same employee may have different effective date versions withinxactly.xc_participant, all sharing the sameemployee_id value. Not to be confused withxactly.xc_participant.participant_id. xactly.xc_participant.employee_id
effective_start_date date (Required for all but ‘create’ action) Determines the date effectivity or version of a given person record. Incent supports effective dating/versioning on many, but not all, types of reference data objects. xactly.xc_participant.effective_start_date
description string (Optional) Use for any notes or other information pertinent to the person. xactly.xc_participant.descr
prefix string (Optional) Use for any name prefix or honorific (Mr., Ms., Dr, etc.) xactly.xc_participant.prefix
first_name string (Required) Person’s given name. xactly.xc_participant.first_name
middle_name string (Optional) Person’s middle name or initial. xactly.xc_participant.middle_name
last_name string (Required) Person’s surname. xactly.xc_participant.last_name
region string (Optional) Typically used to store a payee’s geographic or sales region. xactly.xc_participant.region
employee_status string (Optional) If used, must correspond to a valid value found in xactly.xc_emp_status_code.emp_status_code.Generally, used to track if a person is active, terminated, leave of absence, etc. xactly.xc_participant.emp_status_id
hire_date date (Optional) Typically, the date when a person began employment. Caution: depending on your implementation’s business requirements, hire_date may require adjustments to HRMS hire dates to accommodate compensation plan functionality. xactly.xc_participant.hire_date
termination_date date (Optional) Typically, the date when a person ended their employment. Caution: depending on your implementation’s business requirements, termination_date may require adjustments to HRMS termination dates to accommodate compensation plan functionality. xactly.xc_participant.termination_date
personal_target decimal (Required) A person’s target income. Usually the payee’s variable compensation target for a given time period. Sometimes used in compensation rules and reports to track sales performance goals. xactly.xc_participant.personal_target
personal_currency string (Required) The currency associated with a person’s personal target. Must match a valid currency value inxactly.xc_unit_type.name. xactly.xc_participant.pr_target_unit_type_id
salary decimal (Optional) A peron’s periodic salary. If used, check with your compensation admin to determine if the frequency of the value (hourly, bi-weekly, monthly, quarterly, annual, etc.). xactly.xc_participant.salary
salary_currency string (Optional) The currency associated with a person’s salary. May differ from their payment_currency. Must match a valid currency value in xactly.xc_unit_type.name. xactly.xc_participant.salary_unit_type_id
payment_currency string (Required) Incent’s rules engine will calculate commission and bonus payment values using payment_currency.Must match a valid currency value inxactly.xc_unit_type.name. xactly.xc_participant.payment_cur_unit_type_id
email_address string (Required) Value must tie to a corresponding row inxactly.xc_user.email. xactly.xc_part_user_assignment.user_name
business_group string (Optional) Set to a valid value found in xactly.xc_business_group.name. If left null, the person record will not be assigned to any business group. xactly.xc_participant.business_group_id
Custom_Fields varies (Optional) Your Incent systems administrator may have created custom fields for people records. The custom field name labels will appear in the staging table if available. xactly.xc_participant.[custom_field]

 

staging.person_exception – The upload command writes any errors encountered during process to this table. incent upload peopletruncates this table automatically for each run. Archive any existing error rows as needed before running the command.
Column Name Data Type Description
action string Refer to staging.person
employee_id string Refer to staging.person
effective_start_date date Refer to staging.person
description string Refer to staging.person
prefix string Refer to staging.person
first_name string Refer to staging.person
middle_name string Refer to staging.person
last_name string Refer to staging.person
region string Refer to staging.person
employee_status string Refer to staging.person
hire_date date Refer to staging.person
termination_date date Refer to staging.person
personal_target decimal Refer to staging.person
personal_currency string Refer to staging.person
salary decimal Refer to staging.person
salary_currency string Refer to staging.person
payment_currency string Refer to staging.person
email_address string Refer to staging.person
business_group string Refer to staging.person
exception_code integer Numeric error code returned for any row that the command cannot upload
exception_message string Text description returned for any row that the command cannot upload. Refer to possible messages in following table.

 

 

Exception Messages
Exception Code Exception Message How to Resolve
0 Invalid Action:”some invalid action” Use one of the following allowed action keywords: ‘create’, ‘purge’, ‘delete version’, ‘add version’, or ‘save version’
1200 Save failed. Object already exists Populate staging.person.personal_currency with a valid unit type name and rerun upload for row.
2700 Missing field firstName. Provide a value into staging.person.first_name and rerun upload for row.
2700 Missing field lastName. Provide a value into staging.person.last_name and rerun upload for row.
2700 Missing field personalTarget. Enter a value into staging.person.personal_target and rerun upload for row.
2700 Missing field paymentCurrencyUnitTypeId. Populate staging.person.payment_currency with a valid unit type name and rerun upload for row.
4020 Error when saving Person : {0} Thrown when attempting to ‘add version’ for a person that does not exist in Incent.
4185 Incorrect effective date range passed, save / add version failed incent upload users cannot insert a new version between two versions already found in Incent. Either create a new “last” version. Another alternative is to first delete the versions in Incent that fall after the version in the staging table, then upload the desired version. The approach taken will depend on your specific use case and business requirements.
4204 User is required field. Enter a value. Put a value in staging.person.email_address that maps to a valid Incent user in xactly.xc_user.email.
20019 “Some Incent Object” exists for this participant. Error is thrown when trying to purge a person from Incent that is tied to other Incent data (positions and compensation results, for example). The programmatic solution may not be trivial, as it could require deleting any number of Incent data attached to the person record. Manual cleanup and human decision making is most likely required.

 

 

Examples

incent synchronous upload users; 

screen-shot-2016-09-08-at-8-56-20-am

select email_address, exception_code, exception_message from staging.person_exception;

Related Commands

INCENT CREDENTIAL

INCENT UPLOAD USERS

SHOW INVOCATIONS