INCENT UPLOAD GEOGRAPHIES

 

Summary

The INCENT UPLOAD GEOGRAPHIES command allows developers to load information about sales territories into Incent. Geography and territory information is often included on sales orders for calculating sales commissions and display on reports.

The Geography area enables companies to create geographies that can be used in the incentive compensation rules, formulas, attainment measures, lookup tables, and the Incentive Estimator. Geography name and the  detail fields can also be used for reporting in Xactly Analytics.

Note: Geography under the company data tab is a different object than and not connected to the region field on the Person record.

Incent Admin Guide: https://helpcenter.xactlycorp.com/article/incent-administrator-geography-2/

The command transfers data from the staging.geography table into Incent. The command is often called as part of a larger ETL pipeline before validating staged sales orders. Geography names found on a staged sales order must be present in Incent for the staged order row to validate properly. Refer to INCENT UPLOAD ORDERS and INCENT VALIDATE ORDERS.

The following list provides the generic steps to follow:

  1. DELETE data from the staging.geography and staging.geography_exception tables. Archive rows as necessary as dictated by your business requirements.
  2. Perform any ETL transformations necessary to prepare your raw geography data for upload into Incent. INSERT the transformed data into staging.geography.
  3. Call INCENT UPLOAD GEOGRAPHIES.
  4. Check the staging.geography_exception table for any processing and data validation errors. Fix or archive any staging rows that failed validate and call the upload command again as necessary.

Syntax

 

incent [synchronous] upload geographies; 

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 upload command operates against the complete set of rows found in the staging.geography table.  The following tables describe the staging and exception log tables used to move geography information into Incent. Unlike other types of reference data in Incent, geographies are not effective dated.

 

staging.geography – (Required) Use this table to transfer geography data into Incent.
Column Name Data Type Description xactly Target Table
action string (Required) The value instructs the type of operation the upload should perform on the row. INCENT UPLOAD GEOGRAPHIES has two options:

  • ‘save’ tells the upload command to perform an upsert operation. If the geography does not exist, save will insert a new one. If the geography already exists in Incent, save will perform an update.
  • ‘delete’ is the second supported action. Delete removes a geography from Incent if it does not have ties to other Incent data (sales orders, for example).
 n/a
name string (Required) Unique business identifier for a geography. xactly.xc_geography.name
description string (Optional) Free-form text for notes or other details about the geography. xactly.xc_geography.descr
parent_name string (Optional) Reserved for future use to create a geography hierarchy. xactly.xc_geography.parent_geography_id

 

 

staging.geography_exception – The upload command writes any errors encountered during processing to this table. INCENT UPLOAD GEOGRAPHIES truncates 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.geography
name string Refer to staging.geography
description string Refer to staging.geography
parent_name string Refer to staging.geography
exception_code string 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.

 

Examples

incent upload geographies;

screen-shot-2016-09-08-at-8-48-16-am

 

Related Commands

INCENT CREDENTIAL

INCENT UPLOAD CUSTOMERS

INCENT UPLOAD PRODUCTS

INCENT VALIDATE ORDERS

SHOW INVOCATIONS