Incent Upload Titles

Summary

The incent upload titles command allows developers to create and maintain title records within the Incent application. Examples of titles include, “Vice President”, “Sales Director”, and “Regional Sales Manager”. Your business likely has its own set of possible title values. The command transfers data from staging.title table into Incent’s xactly schema tables.

The Title object defines the compensation title (often different than a person’s HR title). Title is a grouping element in Incent that administrators use for mass plan assignment, quota setting, payout rate definition, and more. https://helpcenter.xactlycorp.com/article/incent-administrator-titles/

Title is directly assigned on the Position object. Position is one of 5 objects that define the organization structure in Incent:

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

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

Delete any old rows from the staging.title and staging.title_exception tables. Archive any rows as needed by per your business requirements.
Insert rows with your title data into the staging.title table. This data is usually sourced from an HRMS or defined during requirements gathering for your Incent deployment.
Call incent upload titles to transfer the data from staging into Incent.
Check for and fix any processing errors in the staging.title_exception table.

Syntax

incent [synchronous] upload titles;

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 titles. The table, staging.title, is described in detail below. Once populated, invoking incent upload titles will process each staging row. Any errors the upload encounters during processing will be written to the staging.title_exception table. Xactly recommends the developer check for any errors in staging.title_exception after the command completes to ensure all title rows were uploaded into Incent as expected.

The following tables describe the columns in each of the staging tables:

Column Name	Data Type	Description	`xactly` Target Table
staging.title – (Required)
action	string	(Required) The value instructs the type of operation the upload should perform on the row. `incent upload titles` has two options: ‘SAVE’ tells the upload command to perform an upsert operation. If the title name does not exist in Incent, save will insert a new title. The Incent title is updated if it already exists in xactly.xc_title. ‘DELETE’ is the other supported action. Delete attempts to remove a title from Incent. Deletes are permitted when the title is not linked to other Incent data (positions, for example).	n/a
name	string	(Required) Unique value for the title.	`xactly.xc_title.name`
description	string	(Optional) Any notes or other free form information to describe the title.	`xactly.xc_title.descr`
category	string	(Required) Must be one of the following values. Used to classify data in Xactly Insights. These values are the primary keys for the values displayed in the Incent UI when viewing titles. ACCOUNT_EXECUTIVE ALLIANCE_PARTNERSHIP_MANAGER APPLICATIONS_SYSTEM_ENGINEER FIELD_SALES_REPRESENTATIVE INSIDE_SALES_REPRESENTATIVE LEAD_GENERATION_REPRESENTATIVE SALES_MANAGER SALES_DIRECTOR SALES_EXECUTIVE SALES_SUPPORT_OPS VICE_PRESIDENT* *Prior to the December 2016 release of Incent, this label was misspelled VICE_PRESEIDENT in the application. The misspelling has since been corrected.	`xactly.xc_title.category_name`
function	string	(Optional) Must be one of the following values. Used to classify data in Xactly Insights. ACCOUNTING_AUDITING EDUCATION ENGINEERING CONSULTING ADMINISTRATIVE CUSTOMER_SERVICE SALES MARKETING HUMAN_RESOURCES TRAINING FINANCE INFORMATION_TECHNOLOGY MANUFACTURING LEGAL PRODUCT_MANAGEMENT PURCHASING PRODUCTION	`xactly.xc_title.function_name`
market	string	(Optional) Must be one of the following values. Used to classify data in Xactly Insights. GLOBAL SMALL_MEDIUM_BUSINESS EMERGING KEY ENTERPRISE MID_MARKET	`xactly.xc_title.market`
level	string	(Optional) Must be one of the following values. Used to classify data in Xactly Insights. I_ENTRY II_INTERMEDIATE IV_LEAD III_SENIOR V_CONSULTANT_SPECIALIST	`xactly.xc_title.title_level`

Column Name	Data Type	Description
staging.title_exception – The upload command writes any errors encountered during process to this table. incent upload users truncates this table automatically for each run. Archive any existing error rows as needed before running the command.
action	string	Refer to staging.title
name	string	Refer to staging.title
description	string	Refer to staging.title
category	boolean	Refer to staging.title
function	string	Refer to staging.title
market	string	Refer to staging.title
level	string	Refer to staging.title
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 Code	Exception Message	How to Resolve
Exception Messages
102	Title not found	Thrown when attempting to delete to title that does not exist in Incent.
103	unknown	Check that any values in staging.title.category, function, market, and level are found in the lists of valid values for each column (find lists in staging table column descriptions above).
1239	Missing required parameters in the request:Category Name	Provide a valid value in staging.title.category. Refer to list above.