Territory Management and Credit Assignment Module (TMCA)
Summary
Use the incent upload tmca orders command to evaluate raw sales orders against compensation rules configured in the Territory Mapping and Credit Assignment module (TMCA).
Note: The TMCA module is an add-on offering and may or may not be enabled in your company’s Incent instance. Contact your Xactly sales representative or customer support for more information about enabling the module.
Raw transactions generally represent a sales event (for example, customer account ABC123 purchased 10 widgets on April 1, 2016). In many cases, a sales transaction may already contain the sales person or persons involved in the deal. The transaction or other logical business rules may also reflect each rep’s split percentage for the sales event.
Xactly calls the relationship between a sales transaction row and a sales rep a credit assignment. Since credit assignments are explicitly known based on data already present on the transaction (for example, employee ids or other identifiers), developers can bypass the TCMA module and commands and proceed directly to uploading the sales orders and credit assignments into Incent. (See Incent Upload Orders for more information.)
However, the sales reps responsible for a given sales transaction are sometimes unknown. Your company may assign credits to sales reps based on geographical sales territories or product groupings. In these cases, TMCA rules configured in the Incent application by your compensation administrator evaluate data elements found on the raw transactions against corresponding territory and credit assignment rules to generate the credit assignments. For example, if the sales transaction occurred in zip code 80304, John and Sally should receive credit for the sales event.
These lookups and evaluation logic are configured by your compensation admin in the Incent application, whereas the Connect commands listed on this page describe how a data integration developer can use Connect to programmatically interact with the TMCA rules your admin configured within Incent.
Syntax
Invoking the TMCA module from Connect requires using a set of four commands in the following order:
incent [synchronous] purge tmca(PeriodName='<PeriodName>');
Deletes any stale data from the temporary/working tables in the tmca schema for the indicated period.
incent[synchronous] validate tmca orders;
Runs standard data validations against all rows present in the staging.tmca_order_item table. The command writes any errors to the staging.tmca_order_item_validation_error table. Note that you need to delete any rows with errors from staging.tmca_order_item before proceeding to the upload command.
incent [synchronous] upload tmca orders;
Transfers rows from the staging.tmca_order_item table into the tmca.tmca_raw_transaction table. The calculate step (described next) reads the data from thetmca.tmca_raw_transaction table as its input.
incent [synchronous] calculate tmca(PeriodName='<PeriodName>');
Evaluates each tmca.tmca_raw_transaction row for the specified period against the territory and crediting dimensions configured within the Incent TMCA module. The rules-based crediting assignments are written to the tmca.tmca_credited_trans table.
Parameters
|
Parameter
|
Description
|
|---|---|
synchronous |
(Optional) By default, the upload command runs asynchronously when invoked (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 |
PeriodName |
(Required for purge and calculate commands) Must match a valid monthly period name. Refer to data in the xactly.xc_period table. |
Details
Ensure you have registered a valid Incent username and password within Connect before invoking the upload command. The incent commands require valid credentials to modify data within the Incent application. See Incent Credential for more information.
The upload command operates against the complete set of rows found in the staging.tmca_order_item table. All rows must have passed the validation command (described below).
The following provides the generic steps to follow:
1. TMCA transactions are handled at a period level. If you are processing a period, use the following command to clean up existing records for the period:
incent [synchronous] purge tmca(PeriodName='<Period_Name>');
2. Insert the raw sales transactions in the staging.tmca_order_item table. The data is most likely sourced from your company’s CRM or ERP system.
3. Validate the transactions for uniqueness (the Order Code, Item Code combination must not already exist in the tmca.tmca_raw_transaction table).
incent validate tmca orders;
Example error codes:
• 9042 — tmca_order_item.incentive_date cannot be null
• 9071 — tmca_order_item.order_code/item_code is duplicated in order_item
4. The previous command writes data validation errors to the staging.tmca_order_item_validation_error table. Before proceeding to the next step, delete any rows flagged in error from the staging.tmca_order_item table.
5. Upload the raw transactions to the TMCA module using the following command:
incent [synchronous] upload tmca orders;
The command transfers rows from the staging.tcma_order_item table to the tmca.tmca_raw_transaction table. This is the initial table read during the upcoming “calculate” credit assignment command.
| staging.tmca_order_item – (Required) Insert sales order and line item detail into this table. | |||
| Column Name | Data Type | Description | tmca Schema Target Table |
|---|---|---|---|
| order_code | string | (Required) Incent enforces a constraint on order_code and item_code to uniquely identify a sales order.
A single |
|
| item_code | string | (Required) Incent enforces a constraint on order_code and item_code to uniquely identify a sales order.
Use |
|
| amount | decimal | (Required) The total transactional amount for a given line_item.
Typically, orders represent sales transaction events as currency values (one widget sold for $50), but can also track non-currency decimal values. |
|
| amount_unit_type_name | string | (Required) Should correspond to a valid xactly.xc_unit_type.name value. Many numeric values in Incent must be assigned to a unit type.
Examples include USD, EUR, quantity, and percent. |
|
| discount | decimal | (Optional) Sometimes used in compensation rules and reporting to track any discount amounts or percentages given to a buyer for a sales orders.
The field’s use and context depends entirely on your company’s business requirements and Incent implementation. |
|
| quantity | decimal | (Optional) Generally used to track the number of product units sold for the order line item. |
|
| incentive_date | date | (Required) Represents the transaction or close date of the order line item. The value determines the monthly period to which the line item is assigned.
Refer to |
|
| order_date | date | (Optional) Records when a customer first placed the sales order. |
|
| order_type_name | string | (Optional) Should correspond to a valid xactly.xc_order_type.name value.
Business requirements might specify that compensation rules behave differently for different types of orders. |
|
| period_name | string | (Required) The leaf level, monthly period name for the given incentive_date. Use theLookupPeriodName() function to return a period name given a date value.
The function helps you avoid cluttering your SQL statements with joins to the The upload command converts the |
|
| product_name | string | (Optional) If populated, must correspond to a valid xactly.xc_product.name.
Use The upload transforms the |
|
| customer_name | string | (Optional) If populated, must correspond to a valid xactly.xc_customer.name.
Use The upload transforms the |
|
| geography_name | string | (Optional) If populated, must correspond to a valid xactly.xc_geography.name.
Use The upload transforms the |
|
| related_order_code | string | (Optional) Use related_order_code and related_item_code to associate a staging sales order with a different sales order that already exists in Incent.
The related sales order may exist in a different batch and period. |
|
| related_item_code | string | (Optional) Use related_order_code and related_item_code to associate a staging sales order with a different sales order that already exists in Incent.
The related sales order may exist in a different batch and period. |
|
| description | string | (Optional) Can store notes or other information regarding the sales order. |
|
| Custom_Fields | varies | (Optional) Incent allows compensation administrators to add custom string, numeric, and date columns to sales orders.
The column labels supplied by the business user in the Incent UI should be present in the Note: If they are not, please contact Xactly Support, who can can work with you to make the custom column labels visible. The sync must be performed by Xactly personnel. |
tmca.tmca_raw_transaction.Custom_Fields |
6. Calculate the TMCA orders using the following command:
incent synchronous calculate tmca(PeriodName='OCT-2017');
Note that the PeriodName input parameter is mandatory.
The command matches the territory and crediting dimensions that compensation administrators configured in your company’s instance of Incent. The command evaluates each row found in the tmca.tmca_raw_transaction table against the TCMA dimensions. When a transaction row is evaluated successfully, the command writes credit assignment rows to the tmca.tmca_credited_trans table.
| tmca.tmca_credited_trans – (Required) The calculate command populates this table with any credit assignments generated by the raw sales orders and TMCA territory and credit rules configured within Incent. | ||
| Column Name | Data Type | Description |
|---|---|---|
| credit_trans_id | string | Unique identifier for row. |
| transaction_id | string | Joins to tmca.tmca_raw_transaction.transaction_id. |
| employee_id | string | Derived from TMCA rules in Incent. |
| split_percentage | decimal | Derived from TMCA rules in Incent. |
| period_name | string | Derived from TMCA rules in Incent. |
| created_date | offset_date_time | The date the row was created. |
| modified_date | offset_date_time | The date the row was modified. In this table, should always equal created_date. |
| version | decimal | |
| created_by_id | decimal | The Connect user who invoked the incent calculate tmca command. |
| modified_by_id | decimal | |
| asgnmt_type | string | |
| terr_person_asgnmt_id | string | |
At this point, credit assignments have been generated but the credit assignments and sales transactions have not yet been transferred to Incent.
7. Process the data using the following command:
incent upload orders
See Incent Upload Orders for more information.
Related Tables
The following lists the tables used by the TMCA module (the tables in bold are most relevant to the Connect TMCA commands). The other tables might be useful for data lookups depending on your company’s data integration and business logic.
- tmca.tmca_credited_trans
- tmca.tmca_credited_trans_duplicate
- tmca.tmca_dimension
- tmca.tmca_dimension_data_interface
- tmca.tmca_dimension_definition
- tmca.tmca_dimension_value
- tmca.tmca_field_mapping
- tmca.tmca_flex_field_asgmnt
- tmca.tmca_hierarchy
- tmca.tmca_raw_transaction
- tmca.tmca_raw_transaction_preview
- tmca.tmca_rule
- tmca.tmca_terr_person_asgnmt
- tmca.tmca_territory