Incent Upload Users

Summary

The incent upload users command allows developers to create and maintain user accounts within the Incent application. The command transfers data from staging.user* tables into Incent’s xactly schema tables.

The User object is the login credential for each user of the application. The user record controls all access to Incent and related modules. Users also assign the Role(s) of the user that defines page level access through out the application. https://helpcenter.xactlycorp.com/article/users/

User 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 series of Connect staging tables with user account data before invoking incent upload users. The general process flow is:

Delete any old rows from the staging.user* tables. Archive any rows as needed by per your business requirements.
Insert rows with user account data into staging.user* tables.
Call incent upload users.
Check for and fix any processing errors in the staging.user_exception table.

Syntax

incent [synchronous] upload users;

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.

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 three tables that a developer can populate before invoking incent upload users. The tables are described in detail below. Once populated, invoking incent upload users will process each staging row. Any errors the upload encounters during processing will be written to the staging.user_exception table. Xactly highly recommends the developer check for any errors instaging.user_exception after the command completes to ensure all user rows were uploaded into Incent as expected.

Note: Before any new user account can access the Incent UI, your Incent compensation administrator will need to grant access to the Incent application. This step can be performed by the administrator via the User setup configuration tab in Incent. Refer to “Accessible Applications” in each user’s configuration setup. Once the Incent application is enabled, the system will send a “welcome” email to the user’s email address inviting them to login and reset their password.

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

Column Name	Data Type	Description	`xactly` Target Table
staging.user – (Required)
action	string	(Required) The value instructs the type of operation the upload should perform on the row. `incent upload users` has two options: ‘save’ tells the upload command to perform an upsert operation. If the user does not exist, save will insert a new user. If the user already exists in Incent, save will perform an update. ‘delete’ is the other supported action. Delete removes a user from Incent if the user does not have ties to other Incent data (people record or compensation results, for example).	n/a
name	string	(Required) The user’s name. Typically this value is set to a person’s full name, e.g. “Bob Smith”.	xactly.xc_user.name
email_address	string	(Required) Uniquely identifies a user account within Incent. Also used as the user’s login name.	xactly.xc_user.email
enabled	boolean	(Optional) Defaulted to false in Incent if null value given.	xactly.xc_user.enabled
locale	string	(Optional) Upload will set null values will be set to the Incent system default, most likely “English (United States)”. Other valid values include: French (France), German (Germany), Spanish (Spain), Swedish (Sweden), Dutch (Netherlands), Norwegian Bokmal (Norway)	xactly.xc_user.locale
ip_address	string	(Optional) Sets the IP address a given user may access Incent from. Null allows users to access the Incent UI from any address.	xactly.xc_user.ip_address

Column Name	Data Type	Description	`xactly` Target Table
staging.user_business_group – (Optional)
email_address	string	(Optional) Corresponds to a row in `staging.user`	n/a
business_group	string	(Optional) If no value is given, upload will set the user’s business group to the system default. Value should correspond to a valid business group name found in the xactly.xc_business_group table. A user may be assigned to multiple business groups; insert one row for each business group assignment for the user.	xactly.xc_user_bg_asgnmt.business_group_id

staging.user_role – (Required)
Column Name	Data Type	Description	`xactly` Target Table
email_address	string	(Required) Corresponds to a row in `staging.user`	n/a
user_role	string	(Required) Valid values are determined by the security roles configured within Incent by your comp admin. A user may be assigned to multiple roles; insert one row for each distinct role assigned to the user. Default values include: ‘Administrator’, ‘Sales Representative’, ‘Sales Manager’, and ‘Executive’. These roles control the level of access a given user has within the Incent application.	staging.user.primary_role_type

staging.user_role – (Required)

Column Name Data Type Description xactly Target Table

email_address string (Required) Corresponds to a row in staging.user n/a

user_role

string

(Required) Valid values are determined by the security roles configured within Incent by your comp admin. A user may be assigned to multiple roles; insert one row for each distinct role assigned to the user. Default values include:

‘Administrator’, ‘Sales Representative’, ‘Sales Manager’, and ‘Executive’. These roles control the level of access a given user has within the Incent application.

staging.user.primary_role_type

Column Name	Data Type	Description
staging.user_exception – The upload command writes any errors encountered during the 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.user
name	string	Refer to staging.user
email_address	string	Refer to staging.user
enabled	boolean	Refer to staging.user
locale	string	Refer to staging.user
ip_address	string	Refer to staging.user
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
0	Row: 2, Field: Assigned Roles, Error:Required field. Enter a value.	Assign user to a valid security role in the staging.user_role table. Check your Incent configuration for a list of valid security roles.
0	Row: 2, Field: Name, Error:Required field. Enter a value	Input a value in staging.user.name
101	duplicate email in staging.user	The same email address can only be used once in staging.user. Delete any duplicate occurrences.