tpm-promotion Component

The tpm-promotion LWC is a service component that loads a TPM promotion, exposing methods to update the promotion state, and events to keep all UI components of the promotion page in sync when the promotion state changes. This component is provided as part of the released managed package.

Namespace

1cgcloud

Events

Here’s the event payload structure.

1{
2    detail : {
3        value: <<new value of the property>>,
4        property: <<property name>>,
5        recordId: <<promotionId>>
6    }
7}

onfocusedareachange

This event is triggered when a different area of the application is navigated to.

1{
2    detail: {
3        value: {
4            area: 'PROMOTION_PLANNING',
5            section: 'PROMOTION'
6        },
7        property: 'focusedArea',
8        promotionId: 'a2WTC0000000F772AE'
9    }
10}

The possible values of area are:

PROMOTION_PLANNING: This area identifies the Promotion Planning UI.
PL_GRID: This area identifies the Promotion PL.

The possible values of section are:

PROMOTION: Promotion level components section.
TACTIC: Tactic level components section.

onisplgridfilteropenchange

This event is triggered when the P&L filters are opened (true) or closed (false).

1{
2    detail : {
3        value: true,
4        property: 'isPLGridFilterOpen',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

onstatuschange

This event is triggered when the lifecycle state of the TPM promotion component changes. Status changes are triggered by lifecycle operations on the promotion record.

1{
2    detail : {
3        value: 'VALID',
4        property: 'status',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

The possible values are:

LOADING: The promotion is being loaded.
VALID: The promotion is loaded and can be interacted with.
SAVING: The promotion is being saved to the database.
ERROR: An irrecoverable error has occurred.

oncalculationstatuschange

This event is triggered when the promotion grids are calculated or recalculated.

1{
2    detail : {
3        value: 'LOADING',
4        property: 'calculationStatus',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

The possible values are:

LOADING: The calculations are being processed, or the engine is loading.
VALID: The calculations are completed and values can be requested
ERROR: An irrecoverable error has occurred.
DISABLED: Calculations Engine is disabled for the promotion.

oneditmodechange

This event is triggered when the edit mode changes for the page.

1{
2    detail : {
3        value: true,
4        property: 'editMode',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

onselectedtacticidchange

This event is triggered when the focused tactic changes.

1{
2    detail : {
3        value: 'a37TC00000014j8YAA',
4        property: 'tacticId',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

The possible values of are:

null: No focused tactic found.
A tactic ID: The ID of the focused tactic.

onpromotionchange

This event is triggered when the promotion attributes change.

The event value contains all the Promotion SObject attributes.

1{
2    detail : {
3        value: {
4            IsNew: false, // Flag to indicate if the record is new
5            IsDeleted: false, // Flag to indicate if the record is deleted
6            Id : 'a2WTC0000000F772AE', // Record id
7            cgcloud__Slogan__c: 'Sample Promotion' // Record attribute. 
8            // All Promotion record fields will be present as attributes
9        },
10        property: 'promotion',
11        promotionId: 'a2WTC0000000F772AE'
12    }
13}

oneffectivecategorieschange

This event is triggered when the effective categories of the promotion change.

The event value contains an array of product IDs from the effective categories.

1{
2    detail : {
3        value: [ // Array of Category product IDs
4            "01t17000001siy5AAA"
5        ],
6        property: 'effectiveCategories',
7        promotionId: 'a2WTC0000000F772AE'
8    }
9}

oneffectivebrandschange

This event is triggered when the effective brands of the promotion change.

The event value contains an array of product IDs from the effective brands.

1{
2    detail : {
3        value: [ // Array of Brand product IDs
4            "01t17000001siy5AAA"
5        ],
6        property: 'effectiveBrands',
7        promotionId: 'a2WTC0000000F772AE'
8    }
9}

ontacticschange

This event is triggered when the tactic attributes change.

The event value contains all the Tactic sObjects and their attributes.

1{
2    detail : {
3        value: [ // An array of objects
4            {
5                IsNew: false, // Flag to indicate if the record is new
6                IsDeleted: false, // Flag to indicate if the record is deleted
7                Id : 'a37TC00000014j8YAA', // Record ID
8                cgcloud__Comment__c: 'Sample Tactic', // Record attribute. 
9                // All tactic record fields will be present as attributes
10                ...
11                // Additional Fields
12                ProductFilter: {...}, // contains the Tactic Product Filter
13                EffectiveCategories: [...], // List of effective categories for the tactic
14                EffectiveBrands: [...] // List of effective brands for the tactic 
15                },
16            ...
17        ],
18        property: 'tactics',
19        promotionId: 'a2WTC0000000F772AE'
20    }
21}

ontacticfundschange

This event is triggered when the Tactic fund properties change.

The event value contains all the Tactic Fund sObjects and their attributes.

1{
2    detail : {
3        value: [ // An array of objects
4            {
5                IsNew: false, // Flag to indicate if the record is new
6                IsDeleted: false, // Flag to indicate if the record is deleted
7                Id : 'a38TC00000014j8YAA', // Record ID
8                cgcloud__Fund__c: 'a39TC00000014j8YAA', // Record attribute. Reference to the Fund__c record
9                cgcloud__Tactic__c: 'a37TC00000014j8YAA', // Record attribute. Reference to the Tactic__c record
10                // All Tactic Fund record fields will be present as attributes
11                ...
12            },
13            ...
14        ],
15        property: 'tacticFunds',
16        promotionId: 'a2WTC0000000F772AE'
17    }
18}

onpromotionattachmentlinkschange

This event is triggered when the properties of the Promotion Attachment link change.

Promotion attachment links are junction objects between a Promotion record and a Promotion Attachment Record.

The event value contains all the Promotion Attachment Link sObjects and their attributes.

1{
2    detail : {
3        value: [ // An array of objects
4            {
5                IsNew: false, // Flag to indicate if the record is new
6                IsDeleted: false, // Flag to indicate if the record is deleted
7                Id : 'a40TC00000014j8YAA', // Record ID
8                cgcloud__Promotion_Attachment__c: 'a41TC00000014j8YAA', // Record attribute. Reference to the Promotion_Attachment__c record
9                // All Tactic Fund record fields will be present as attributes
10                ...
11            },
12            ...
13        ],
14        property: 'promotionAttachmentLinks',
15        promotionId: 'a2WTC0000000F772AE'
16    }
17}

onpromotionattachmentschange

This event is triggered when the properties of the Promotion Attachment sObject change.

Promotion Attachment records must be created before they can be linked to a promotion during the save process.

The event value contains all the Promotion Attachment Link sObjects and their attributes.

1{
2    detail : {
3        value: [ // An array of objects
4            {
5                IsNew: false, // Flag to indicate if the record is new. Promotion attachments cannot be flagged as new
6                IsDeleted: false, // Flag to indicate if the record is deleted. Promotion attachments cannot be flagged as deleted
7                Id : 'a41TC00000014j8YAA', // Record ID
8                cgcloud__Description_Language_1__c: 'Sample Attachment', // Record attribute. Reference to the Promotion_Attachment__c record
9                // All Tactic Fund record fields will be present as attributes
10                ...
11            },
12            ...
13        ],
14        property: 'promotionAttachments',
15        promotionId: 'a2WTC0000000F772AE'
16    }
17}

onpromotioncategorieschange

This event is triggered when the promotion categories change.

The event value is an array of Product2 IDs referencing Category records.

1{
2    detail : {
3        value: [ "01t17000001siy5AAA" ],
4        property: 'promotionCategories',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

onsubaccountschange

This event is triggered when the promotion sub-accounts change.

1{
2    detail : {
3        value: [ // Array of items
4            {
5                "volume": 50, // Percent of volume for this sub account. Sum of included sub accounts volume must be 100 or less
6                "included": true, // Is Included?
7                "externalid": "Supermarkets" // External id of the SubAccount
8            }
9        ],
10        property: 'subAccounts',
11        recordId: 'a2WTC0000000F772AE'
12    }
13}

onparticipatingcustomerschange

This event is triggered when the participating customers of a promotion change. The participating customers list is used to determine the customers the promotion is pushed to during the push process.

1{
2    detail : {
3        value: [ // Array of items
4            {
5                "included": true, // Is Included?
6                "externalid": "Supermarkets" // External id of the Participating Customer
7            }
8        ],
9        property: 'participatingCustomers',
10        promotionId: 'a2WTC0000000F772AE'
11    }
12}

ontacticconditioncreationdefinitionschange

This event is triggered when the Tactic Condition Creation definitions for the tactics included in the promotion change.

The event value is an array of Tactic Condition Creation Definition sObject records and their attributes.

1{
2    detail : {
3        value: [ // An array of objects
4            {
5                IsNew: false, // Flag to indicate if the record is new
6                IsDeleted: false, // Flag to indicate if the record is deleted
7                Id : 'a50TC00000014j8YAA', // Record id
8                cgcloud__Tactic__c: 'a37TC00000014j8YAA', // Record attribute. 
9                // All Tactic condition creation definition record fields will be present as attributes
10                ...
11            },
12            ...
13        ],
14        property: 'tacticConditionCreationDefinitions',
15        promotionId: 'a2WTC0000000F772AE'
16    }
17}

oncustomstatechange

This event is triggered when the custom state changes. Custom State is a special area of the promotion state where customers can set their custom structures that are processed and committed in Salesforce at the same time as the promotion.

1{
2    detail : {
3        value: {...} // Custom object
4        property: 'customState',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

onpromotionproductschange

This event is triggered when the promotion products change.

The event value is an array of all promotion product IDs.

1{
2    detail : {
3        value: [
4            '00X000000000000AAA'
5        ],
6        property: 'promotionProducts',
7        promotionId: 'a2WTC0000000F772AE'
8    }
9}

onupliftpredictionavailablechange

This event is triggered when the uplift prediction availability changes. It indicates if the feature is enabled for the promotion.

1{
2    detail : {
3        value: {
4            available: true
5            kpi: "PredictedUplift"
6        },
7        property: 'upliftPredictionAvailable',
8        promotionId: 'a2WTC0000000F772AE'
9    }
10}

onupliftpredictionenabledchange

This event is triggered based on whether the uplift prediction can be performed on the current promotion or not. It indicates possible errors with the promotion state that prevent uplift prediction from being executed.

1{
2    detail : {
3        value: {
4           enabled: false, 
5           reasons: [
6               "No Uplift Prediction KPI is defined."
7           ]
8        },
9        property: 'upliftPredictionEnabled',
10        promotionId: 'a2WTC0000000F772AE'
11    }
12}

onupliftpredictionprocessstatuschange

This event is triggered when the uplift prediction process state changes.

The possible values are:

RUNNING
IDLE

1{
2    detail : {
3        value: "RUNNING",
4        property: 'upliftPredictionProcessStatus',
5        promotionId: 'a2WTC0000000F772AE'
6    }
7}

onmanualinputschange

This event is triggered when the promotion manual inputs change. The event payload contains an array of TPMManualInput instances being used for the TPM Grids.

1{
2    detail : {
3        value: [
4            {}, // TPMManualInput instance
5            {}  // TPMManualInput instance
6        ],
7        property: 'manualInputs',
8        recordId: 'a2WTC0000000F772AE'
9    }
10}

onaclchange

This event is triggered when the edit access rights in the Access Control List (ACL) changes for a promotion or tactic. This event notifies about an ACL change. Get the actual value of an edit access right element using the isVisible and isEditable methods of the tpm-promotion class.

1{
2    detail : {
3        property: 'acl',
4        recordId: 'a2WTC0000000F772AE'
5    }
6}

onkpivalidationschanges

This event is triggered when the promotion grids are calculated or recalculated, and validation KPIs are emitting error messages.

1{
2    detail : {
3        value: {
4            errorAmount: 1, // Total number of errors
5            errorMessages: [ // Sample of messages
6                {
7                     productid: '01tXXXXXXXXXXXXXXX', // Product
8                     productgroupid: '01tYYYYYYYYYYYYYYY', // Product Group
9                     kpiname: 'TEST', // Name of the KPI
10                     values: [
11                        1,
12                        2
13                     ],
14                     tacticid: 'aaa000000000000000', // Tactic Id
15                     weeklabel: '03/2023' // Period label
16                }
17            ]
18        },
19        property: 'calculationStatus',
20        recordId: 'a2WTC0000000F772AE'
21    }
22}

Example Implementation

Here’s an example of how to use the tpm-promotion component to interact with a promotion:

1// myComponent.html
2<template>
3    <!-- Instantiate a tpm-promotion component to bridge -->
4    <!-- with the Promotion state  -->
5    <cgcloud-tpm-promotion 
6        promotion-id={recordId}
7        onpromotionchange={onPromotionChange}
8        oneditmodechange={onEditModeChange}>
9    </cgcloud-tpm-promotion>
10
11    <!-- Create a card component with a Form item to allow a field -->
12    <!-- to be editable, this field will be aligned to page edit mode -->
13    <lightning-card  title="My Card">
14        <lightning-record-form
15            object-api-name="cgcloud__Promotion__c"
16            record-type-id={myRecordTypeId} <!-- Used to load field specific metadata -->
17        >
18            <lightning-input-field 
19                field-name="MyPromotionField__c"
20                disabled={notInEditMode}
21                value={myPromotionFieldValue}
22                onchange={onFieldValueChange}
23            ></lightning-input-field>
24        </lightning-record-form>
25    </lightning-card>
26</template>

1import { LightningElement, api } from 'lwc';
2
3export default class SampleTpmPromotionDetails extends LightningElement {
4    // Required to get the promotion id of the page
5    @api recordId;
6    
7    notInEditMode = false;
8    myPromotionFieldValue = '';
9    myRecordTypeId = '';
10
11    // Executed every time the editMode changes for the promotion
12    // Field will be editable if in Edit mode
13    onEditModeChange(event) {
14        this.notInEditMode = !event.detail.value;
15    }
16
17    // Executed every time the promotion value changes 
18    onPromotionChange(event) {
19        this.myPromotionFieldValue = event.detail.value['MyPromotionField__c'];
20        this.myRecordTypeId = event.detail.value['RecordTypeId'];
21    }
22
23    // Executed when the editable field changes
24    onFieldValueChange(event) {
25        // Get the tpm-promotion component
26        const component = this.template.querySelector('cgcloud-tpm-promotion');
27        
28        // Update the promotion state with the new field value
29        component.setPromotionField(
30           'MyPromotionField__c',
31           event.detail.value
32        );     
33}

tpm-promotion Component Methods

Here are all the tpm-promotion methods.

tpm-promotion Component Methods

Here are all the tpm-promotion methods.

exportKPIs

This method returns a promise resolving to the values of the KPIs for the selected KPI subsets or names, levels, and period types.
duplicateTactic

The method returns a promise resolving to a JavaScript object with all the tactic attributes preset.
generateTactic

This method generates a Tactic record using the tacticTemplateId as a base. The method returns a promise resolving to a Javascript object with all the tactic attributes preset. After generating the tactic, it can be added to the promotion data by calling setTacticField for all the fields.
getProperty

Imperatively retrieve promotion state properties.
getLevelNames

This method returns a promise resolving to the list of levels that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.
getKPISubsets

This method returns a promise resolving to the list of KPI Subsets that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.
getKPIs

This method returns a promise resolving to the list of KPIs that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.
getPeriods

This method returns a promise resolving to the list of Periods that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.
getPeriodTypes

This method returns a promise resolving to the list of Period Types that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.
isEditable

This method returns true if an EARight element is flagged as editable for the passed record ID.
isVisible

This method returns true if an EARight element is flagged as visible for the passed record ID.
navigateTo

Moves the page focus to the passed in target. The target object requires an area attribute and an optional section attribute:
push

Begins the promotion push process. Saves the current state of the promotion SObject and all of its related SObjects.
reload

Reloads the promotion SObject and all the related records.
removeCallback

Remove already setup callback functions that will be called as part of method flows.
save

Begins the promotion save process. Saves the current state of the promotion SObject and all of its related SObjects. I’ll also save the custom state. During the save process, the component will emit events to notify custom components about different events that might happen during the process.
close

This process initiates the close promotion process. It sets the promotion phase to ToBeFinanciallyClosed and initiates the save process. This triggers the financial closure workflow in Processing Services, which handles the promotion’s accruals and final calculations. The method also saves the related SObjects and custom state.
selectTactic

Sets the internally selected tactic to the passed in tactic ID.
setCallback

Setup callback functions that will be called as part of method flows.
setCustomState

This object will be sent along with the promotion information during save to SFDC in order to be processed and committed. Using the custom state, customers can set up additional data to send along the promotion data to be saved in the same transaction as the promotion. This custom state will be forwarded to the customized APEX class handling promotion save customizations..
setEditMode

Sets the promotion into edit mode or exits edit mode.
setEditable

This method sets the editability value of an EARight element for the given promotion or tactic record ID.
setVisible

This method sets the visibility value of an EARight element for the given promotion, or tactic record ID.
setParticipatingCustomers

Lists the objects with the participating customers format.
setPLGridFilterOpen

Displays or hides the P&L filter section on the promotion P&L view.
setPromotionAttachmentLinks

Sets the related promotion attachment links to the promotion.
setPromotionAttachments

Sets the related promotion attachments to the promotion. Promotion attachments cannot be created or deleted from the tpm-promotion component API. Promotion attachment records need to be previously created before linking them to a promotion with a promotion attachment link record.
setPromotionCategories

Sets the list of categories of the promotion. TPM Application will only detect category changes after a reload.
setPromotionField

Sets a promotion SObject field.
setPromotionManualInputs

This method sets an array of manual inputs in the TPM promotion service component.
setSubAccounts

Lists the objects with the SubAccounts format.
setTacticConditionCreationDefinitions

Sets the related tactic condition creation definition records to the promotion.
setTacticField

Sets the tactic SObject field.
setTacticFunds

Sets the related tactic funds to the Promotion. To delete the tactic fund record, set the IsDeleted attribute to true. To flag a record as new, set the IsNew attribute to true. If the Sales Org has Fund Autodetermination enabled, TPM Application will always overwrite tactic funds with the records generated by the autodetermination process.
predictUplift

This method returns a promise resolved when an uplift prediction is completed for the promotion. If the uplift prediction is disabled or the promotion isn’t in a correct status, the promise is rejected with an error stating the cause.

exportKPIs

This method returns a promise resolving to the values of the KPIs for the selected KPI subsets or names, levels, and period types.

API Version

58.0

Signature

exportKPIs(options)

Properties

Name	Type	Description	Required or Optional
`options.subsets`	List<String>	List of loaded KPI subsets to retrieve data from. You can get a list of loaded subsets using the `getKPISubsets()` method. Provide either the KPI subsets or the KPI names.	Optional
`options.kpis`	List<String>	List of KPI names to retrieve data from. You can get a list of loaded KPI names using the `getKPIs()` method. Provide either the KPI subsets or the KPI names.	Optional
`options.levels`	List<String>	List of loaded levels to retrieve data from. You can get a list of loaded levels using the `getLevelNames()` method.	Optional
`options.periods`	List<String>	List of loaded period types to retrieve data. You can get a list of loaded period types using the `getPeriodTypes()` method.	Optional
`options.format`	List<String>	Format in which the response is returned. Possible formats are: JSON: The response is an array of JavaScript objects. Serialized: The response is a JSON string of JavaScript objects. CSV: The response is a CSV string. The default format is JSON.	Optional

The returned data is a list of rows (JavaScript objects or CSV rows). Each row represents the value of the KPI for the determined level. Each row contains values for all the periods specified in the request.

Example Implementation

1const api = this.template.querySelector('cgcloud-tpm-promotion');
2
3// Export options, the possible values can be extracted using
4// the other described methods
5const exportOptions = {
6    subsets: ["Planning"], // Subsets to request data
7    periods: [
8        "Total",
9        "Week"
10    ],
11    levels: [
12        "Total",
13        "Category",
14        "Product"
15    ],
16    format: "json"
17};
18
19// Correct Scenario
20api.getProperty('calculationStatus'); // 'VALID'
21
22api.exportKPIs(exportOptions)
23    .then((data) => {
24        // Example response as CSV
25        //
26        // kpiName,Category,Product,AP_LBL_TOTAL,03/2022,04/2022
27        // SampleKPI1,,,246,123,123
28        // SampleKPI1,01tTC0000000001AAA,,246,123,123
29        // SampleKPI1,01tTC0000000001AAA,01tTC0000000002AAA,246,123,123
30        // SampleKPI2,,,1974,987,987
31        // SampleKPI2,01tTC0000000001AAA,,1974,987,987
32        // SampleKPI2,01tTC0000000001AAA,01tTC0000000002AAA,1974,987,987
33        
34        // Example response as JSON
35        //
36        // [{
37        //    kpiName: "SampleKPI1",
38        //    Category: null,
39        //    Product: null,
40        //    AP_LBL_TOTAL: 246,
41        //    "03/2022": 123,
42        //    "04/2022": 123     
43        // }, {
44        //    kpiName: "SampleKPI1",
45        //    Category: "01tTC0000000001AAA",
46        //    Product: null,
47        //    AP_LBL_TOTAL: 246,
48        //    "03/2022": 123,
49        //    "04/2022": 123
50        // },{
51        //    kpiName: "SampleKPI1",
52        //    Category: "01tTC0000000001AAA",
53        //    Product: "01tTC0000000002AAA",
54        //    AP_LBL_TOTAL: 246,
55        //    "03/2022": 123,
56        //    "04/2022": 123
57        // },{
58        //    kpiName: "SampleKPI2",
59        //    Category: null,
60        //    Product: null,
61        //    AP_LBL_TOTAL: 1974,
62        //    "03/2022": 987,
63        //    "04/2022": 987
64        // },{
65        //    kpiName: "SampleKPI2",
66        //    Category: "01tTC0000000001AAA",
67        //    Product: null,
68        //    AP_LBL_TOTAL: 1974,
69        //    "03/2022": 987,
70        //    "04/2022": 987
71        // },{
72        //    kpiName: "SampleKPI2",
73        //    Category: "01tTC0000000001AAA",
74        //    Product: "01tTC0000000002AAA",
75        //    AP_LBL_TOTAL: 1974,
76        //    "03/2022": 987,
77        //    "04/2022": 987
78        // }]
79        
80        
81        // We can access the properties on the result:
82        const firstRecord = data[0];
83        
84        console.log(firstRecord["kpiName"]); // "SampleKPI1"
85        // Since we request the total period, 
86        // we can read the total period value
87        console.log(firstRecord["AP_LBL_TOTAL"]); // 246
88        // We can also read specific periods information
89        console.log(firstRecord["03/2022"]); // 123
90        // We can also know which level the row references 
91        console.log(firstRecord["Category"]); // null
92        console.log(firstRecord["Product"]); // null
93        // Since Category is null, it means this data row 
94        // represents the total value for KPI "SampleKPI1" 
95        
96        // For last record
97        const lastRecord = data[data.length - 1];
98        
99        console.log(lastRecord["kpiName"]); // "SampleKPI2"
100        // Since we request the total period, 
101        // we can read the total period value
102        console.log(lastRecord["AP_LBL_TOTAL"]); // 1974
103        // We can also read specific periods information
104        console.log(lastRecord["03/2022"]); // 987
105        // We can also know which level the row references 
106        console.log(lastRecord["Category"]); // "01tTC0000000001AAA"
107        console.log(lastRecord["Product"]); // "01tTC0000000002AAA"
108        // Since Product is not null, it means this data row 
109        // represents the value for KPI "SampleKPI2" for that
110        // specific product
111    });
112
113// Error Scenario
114api.getProperty('calculationStatus'); // 'LOADING'
115
116api.exportKPIs(exportOptions)
117    .catch((error) => {
118        console.log(error.message); // CalculationStatus is not "VALID". Current Status "LOADING"
119    });

duplicateTactic

The method returns a promise resolving to a JavaScript object with all the tactic attributes preset.

This method generates a tactic record using the tacticId as a base. You can add the generated tactic record to the promotion data by calling setTacticField for all the fields.

API Version

60.0

Signature

duplicateTactic(tacticTemplateId)

tacticTemplateId: String. Record ID of the tactic template.

Example Implementation

1component.duplicateTactic('a43TC00000014j8YAA') // tactic ID as a parameter
2    .then((tactic) => {
3        // Add the tactic to the promotion component
4        Object.keys(tactic).forEach((key) => {
5            component.setTacticField(tactic.Id, key, tactic[key]);
6        });
7    });

generateTactic

This method generates a Tactic record using the tacticTemplateId as a base. The method returns a promise resolving to a Javascript object with all the tactic attributes preset. After generating the tactic, it can be added to the promotion data by calling setTacticField for all the fields.

API Version

Signature

generateTactic(tacticTemplateId)

Example Implementation

1component.generateTactic('a43TC00000014j8YAA') // tactic Id as parameter
2    .then((tactic) => {
3        // Add the tactic to the Promotion component
4        Object.keys(tactic).forEach((key) => {
5            component.setTacticField(tactic.Id, key, tactic[key]);
6        });
7    });

getProperty

Imperatively retrieve promotion state properties.

API Version

55.0

Signature

getProperty(propName)

The available properties to retrieve are:

focusedArea
status
calculationStatus
editMode
selectedTacticId
promotion
tactics
tacticFunds
promotionAttachments
promotionAttachmentLinks
promotionCategories
productFilter
subAccounts
participatingCustomers
tacticConditionCreationDefinitions
upliftPredictionProcessStatus
upliftPredictionEnabled
upliftPredictionAvailable
promotionProducts
manualInputs
kpiValidations
customState

Example Implementation

1component.getProperty('promotion');
2
3// Returns a Javascript object with attributes mapped to all promotion SObject
4// attributes
5// {
6//     IsNew: false, // Flag to indicate if the record is new
7//     IsDeleted: false, // Flag to indicate if the record is deleted
8//     Id : 'a2WTC0000000F772AE', // Record id
9//     cgcloud__Slogan__c: 'Sample Promotion', // Record attribute. 
10//     // All Promotion record fields will be present as attributes
11//     ...
12// }

getLevelNames

This method returns a promise resolving to the list of levels that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.

API Version

58.0

Signature

getLevelNames()

Example Implementation

1const api = this.template.querySelector('cgcloud-tpm-promotion');
2
3// Correct Scenario
4api.getProperty('calculationStatus'); // 'VALID'
5
6api.getLevelNames()
7    .then((levels) => {
8        console.log(levels); // ["Tactic", "Category", "Brand", "Product"]
9    });

getKPISubsets

This method returns a promise resolving to the list of KPI Subsets that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.

API Version

58.0

Signature

getKPISubsets()

Example Implementation

1const api = this.template.querySelector('cgcloud-tpm-promotion');
2// Correct Scenario
3api.getProperty('calculationStatus'); // 'VALID'
4
5api.getKPISubsets()
6    .then((subsets) => {
7        console.log(subsets); // ["Planning", "VPC", "SPC", "PromoUI", …]
8    });

getKPIs

This method returns a promise resolving to the list of KPIs that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.

API Version

58.0

Signature

getKPIs()

Example Implementation

1const api = this.template.querySelector('cgcloud-tpm-promotion');
2
3// Correct Scenario
4api.getProperty('calculationStatus'); // 'VALID'
5
6api.getKPIs()
7    .then((kpis) => {
8        // 0 
9        console.log(kpis[0].id); // "0"
10        console.log(kpis[0].name); // "BasePrice"
11        console.log(kpis[0].kpitype); // "promotion"
12        console.log(kpis[0].skipped); // ["Tactic"]
13        console.log(kpis[0].type); // "read"
14        console.log(kpis[0].valuetype); // "Price"
15    });

getPeriods

This method returns a promise resolving to the list of Periods that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.

API Version

58.0

Signature

getPeriods()

Example Implementation

1const api = this.template.querySelector('cgcloud-tpm-promotion');
2
3// Correct Scenario
4api.getProperty('calculationStatus'); // 'VALID'
5
6api.getPeriods()
7    .then((periods) => {
8        // 0 
9        console.log(periods[0].id); // "0"
10        console.log(periods[0].name); // "AP_LBL_TOTAL" (label of the period)
11        console.log(periods[0].periodtype); // "Total"
12        console.log(periods[0].dateFrom); // null
13        console.log(periods[0].dateThru); // null
14        // 1 
15        console.log(periods[1].id); // 1
16        console.log(periods[1].name); // "36/2022" // label in case of label is specified alternativly it returns the ....
17        console.log(periods[1].periodtype); // "Week"
18        console.log(periods[1].dateFrom); // 1661731200000 timestamp
19        console.log(periods[1].dateThru); // 1662249600000 timestamp
20    });

getPeriodTypes

This method returns a promise resolving to the list of Period Types that are currently loaded in the Calculation Engine. If the calculation status isn’t valid, the method returns an error.

API Version

58.0

Signature

getPeriodTypes()

Example Implementation

1const api = this.template.querySelector('cgcloud-tpm-promotion');
2
3// Correct Scenario
4api.getProperty('calculationStatus'); // 'VALID'
5
6api.getPeriodTypes()
7    .then((periodTypes) => {
8        console.log(periodTypes); // ["Total", "Week"]
9    });

isEditable

This method returns true if an EARight element is flagged as editable for the passed record ID.

The record ID must be a promotion ID or a tactic ID.

API Version

60.0

Signature

isEditable(recordId, eaRight)

isVisible

This method returns true if an EARight element is flagged as visible for the passed record ID.

The record ID must be a promotion ID or a tactic ID.

Promotion Closure should be enabled in the Promotion Template before using this method.

Note

API Version

Signature

close()

During the close promotion process, the TPM component notifies custom components about different events that might happen during the process. Before using the close promotion method, you must set a callback using the setCallback(event, callback) method. During the close promotion process, the following callbacks are executed:

onBeforeSave: Executes before the promotion saves to SFDC.
onAfterSave: Executes after the promotion saves to SFDC.
onAfterSync: Executes after the promotion synchronizes to Processing Services.
onError: Executes if any error occurs during all the close steps.

In the callback function, it’s possible to return a promise. If it returns a promise, the process pauses until the promise is resolved. If the promise is resolved correctly, the next step continues. If the promise is rejected, it is treated as an error and the onError callback is executed.

Example Implementation

1// Create callback functions
2const onBeforeSaveCallback = (data) => console.log('onBeforeSave', data.operation === 'save');
3const onAfterSaveCallback = (data) => console.log('onAfterSave', data.operation === 'save');
4const onAfterSyncCallback = () => console.log('onAfterSync - Financial closure initiated');
5
6// Setup callback functions
7component.setCallback('onBeforeSave', onBeforeSaveCallback);
8component.setCallback('onAfterSave', onAfterSaveCallback);
9component.setCallback('onAfterSync', onAfterSyncCallback);
10
11component.close();
12
13// Phase is set to "ToBeFinanciallyClosed"
14// onBeforeSaveCallback is executed
15// Data is saved to Salesforce
16// onAfterSaveCallback is executed
17// Promotion is synchronized to Processing Services
18// onAfterSyncCallback is executed
19// Financial closure process begins in Processing Services

selectTactic

Sets the internally selected tactic to the passed in tactic ID.

API Version

Signature

selectTactic(tacticId)

Example Implementation

1component.selectTactic('a37TC00000014j8YAA');
2
3// After executing, the TPM UI will focus the tactic 'a37TC00000014j8YAA'

setCallback

Setup callback functions that will be called as part of method flows.

API Version

Signature

setCallback(tacticFunds)

Example Implementation

1// Resolved promise
2
3// Create callback functions
4const onBeforeSaveCallback = (data) => {
5    return new Promise((resolve, reject) => {
6        window.setTimeout(() => {
7            resolve();
8        }, 2000);
9    });
10};
11const onErrorCallback = (error) => console.log('onError', error);
12
13// Setup callback functions
14component.setCallback('onBeforeSave', onBeforeSaveCallback);
15component.setCallback('onError', onErrorCallback);
16
17component.save();
18
19// onBeforeSaveCallback is executed
20// Process wait the returned promise is resolved
21// Data is saved to SFDC
22// Save process continues
23
24// Rejected promise
25
26// Create callback functions
27const onBeforeSaveCallback = (data) => {
28    return new Promise((resolve, reject) => {
29        window.setTimeout(() => {
30            reject(new Error('My Error'));
31        }, 2000);
32    });
33};
34const onErrorCallback = (error) => console.log('onError', error);
35
36// Setup callback functions
37component.setCallback('onBeforeSave', onBeforeSaveCallback);
38component.setCallback('onError', onErrorCallback);
39
40component.save();
41
42// onBeforeSaveCallback is executed
43// Process wait the returned promise is resolved
44// Promise is rejected
45// onErrorCallback is executed with the rejected error

setCustomState

This object will be sent along with the promotion information during save to SFDC in order to be processed and committed. Using the custom state, customers can set up additional data to send along the promotion data to be saved in the same transaction as the promotion. This custom state will be forwarded to the customized APEX class handling promotion save customizations..

API Version

Signature

setCustomState(customState)

Example Implementation

1component.setCustomState(
2    Object.assign({}, 
3        oldCustomState, // Create a new object using the old one as baseline
4        {
5            myProp: 'Test'
6        }
7    )
8);

setEditMode

Sets the promotion into edit mode or exits edit mode.

API Version

Signature

setEditMode(value)

Example Implementation

1component.setEditMode(true);
2
3// After executing, the TPM UI will set the promotion into edit mode
4
5component.setEditMode(false);
6
7// After executing, the TPM UI will set the promotion into read only mode

setEditable

This method sets the editability value of an EARight element for the given promotion or tactic record ID.

After the editability value of an EARight element is set for the record, the promotion UI is re-rendered to reflect the changes. But, after you save the promotion, the EARight elements are reset to the initial values provided by TPM and the customization hook.

API Version

60.0

Signature

setEditable(recordId, eaRight, value)

recordId: ID of a promotion or tactic
eaRight: An EARight element
value: A boolean value

setVisible

This method sets the visibility value of an EARight element for the given promotion, or tactic record ID.

After the EARight element visibility value is set for a record, the promotion UI is re-rendered to reflect the changes. But, after you save the promotion, the EARight elements are reset to the initial values provided by TPM and the customization hook.

API Version

60.0

Signature

setVisible(recordId, eaRight, value)

recordId: ID of a promotion or tactic
eaRight: An EARight element
value: A Boolean value

setParticipatingCustomers

Lists the objects with the participating customers format.

API Version

Signature

setParticipatingCustomers(participatingCustomers)

Example Implementation

1component.setParticipatingCustomers([ // Array of items
2    {
3        "included": true, // Is Included?
4        "externalid": "Supermarkets" // External id of the Participating Customer
5    }
6]);

setPLGridFilterOpen

Displays or hides the P&L filter section on the promotion P&L view.

API Version

Signature

setPLGridFilterOpen(value)

Example Implementation

1component.setPLGridFilterOpen(true);
2
3// After executing, the TPM UI will open the PL Grid filters
4
5component.setPLGridFilterOpen(false);
6
7// After executing, the TPM UI will close the PL Grid filters

setPromotionAttachmentLinks

Sets the related promotion attachment links to the promotion.

API Version

Signature

setPromotionAttachmentLinks(attachmentLinks)

Example Implementation

1component.setPromotionAttachmentLinks([ // An array of objects
2    {
3        IsNew: false, // Flag to indicate if the record is new
4        IsDeleted: false, // Flag to indicate if the record is deleted
5        Id : 'a40TC00000014j8YAA', // Record id of the Promotion Attachment Link record
6        cgcloud__Promotion_Attachment__c: 'a41TC00000014j8YAA', // Record attribute. 
7            // Reference to the Promotion_Attachment__c record
8        // All Tactic Fund record fields will be present as attributes
9        ...
10    },
11    ...
12]);

setPromotionAttachments

Sets the related promotion attachments to the promotion. Promotion attachments cannot be created or deleted from the tpm-promotion component API. Promotion attachment records need to be previously created before linking them to a promotion with a promotion attachment link record.

API Version

Signature

setPromotionAttachments(attachments)

Example Implementation

1component.setPromotionAttachments([ // An array of objects
2    {
3        IsNew: false, // Flag to indicate if the record is new. Promotion attachments cannot be flagged as new
4        IsDeleted: false, // Flag to indicate if the record is deleted. Promotion attachments cannot be flagged as deleted
5        Id : 'a41TC00000014j8YAA', // Record id of Promotion Attachment record
6        cgcloud__Description_Language_1__c: 'Sample Attachment', // Record attribute. Reference to the Promotion_Attachment__c record
7        // All Tactic Fund record fields will be present as attributes
8        ...
9    },
10    ...
11]);

setPromotionCategories

Sets the list of categories of the promotion. TPM Application will only detect category changes after a reload.

API Version

Signature

setPromotionCategories(categories)

Example Implementation

1component.setPromotionCategories([ // Array
2    '01t17000001siy5AAA' // Product2 Id referencing a Category record
3]);

setPromotionField

Sets a promotion SObject field.

API Version

Signaturei

setPromotionField(field, value)

Example Implementation

1component.setPromotionField(
2    'cgcloud__Slogan_Language_1__c', // Field name
3    'Test Slogan' // value
4);

The field value sets that are managed by KPI Maps are ignored if provided through Business Objects API. This behaviour prevents any outdated data being sent to Trade Promotion Management.

Note

setPromotionManualInputs

This method sets an array of manual inputs in the TPM promotion service component.

Manual grid edits are an array of TPMManualInput instances. You can add new entries, or remove entries from the existing array of elements.

API Version

60.0

Signature

setPromotionManualInputs(manualInputs)

Example Implementation

1// Import the TPMManualInput class to create new instances
2import { TPMManualInput } from 'cgcloud/tpmGenericUtils';
3
4...
5   
6// In this method, we will be adding a new manual input to the grid.
7// This can, for instance, be executed in the click of a button or after
8// some user interaction
9async addNewManualInputs() {
10    const tpmPromotion = this.template.querySelector('cgcloud-tpm-promotion');
11        
12    // Extract the current manual inputs
13    const currentManualInputs = tpmPromotion.getProperty('manualInputs');
14        
15    // You can read information from the current manual inputs:
16    currentManualInputs.forEach((mi) => {
17        console.log(mi.getKPICode()); // 'ABCD'
18        console.log(mi.getPeriodDateFrom()); // Date
19        console.log(mi.getPeriodDateThru()); // Date
20        console.log(mi.ProductId()); // '01tXXXXXXXXXXXXXXX'
21        console.log(mi.getValue()); // 123
22    });
23        
24    // Example: KPI code to set the manual input to
25    const kpiCode = 'ABCD';
26
27    // Example: Product Id to set the manual input to. If null,
28    // the manual input will be applied to the "Total" for the KPI
29    // productId can be any level on the product hierarchy that is part of 
30    // the calculation (SubCategory, Brand, etc)
31    const productId = '01tXXXXXXXXXXXXXXX';
32        
33    // Methods used to extract data from the grid require the grid to be in valid
34    // status. If you try to extract data from the grid when not in the correct status,
35    // an exception will be thrown
36    if (tpmPromotion.getProperty('calculationStatus') !== 'VALID') {
37        throw new Error('Grid not in VALID status');
38    }
39        
40    // Extract the periods information from the grid
41    const periods = await tpmPromotion.getPeriods();
42        
43    // We find the period where we want to set the manual input.
44    // You can find periods by name or use the periods "dateFrom, "dateThru" and "periodtype"
45    // attributes to search for an specific period.
46    // In this example, we will set the manual input on the "Total" period
47    // that uses a specific label
48    const manualInputPeriod = periods.find((p) => p.periodtype === 'Total');
49        
50    // Create a new instance
51    const newManualInput = new TPMManualInput({
52        kpiCode: kpiCode,
53        period: manualInputPeriod,
54        productId: productId,
55        value: 123 // Value to set
56    });
57        
58    // Create a new array with our new manual input appended
59    const newManualInputArray = [...currentManualInputs, newManualInput];
60        
61    // Set the manual inputs
62    tpmPromotion.setPromotionManualInputs(newManualInputArray);
63        
64    // After setting the new manual inputs, the grids will be automatically
65    // reloaded and re-rendered with the new values in place.
66    
67    // At this point, manual inputs are still not saved to SFDC database.
68    // the user must save the promotion
69}

setSubAccounts

Lists the objects with the SubAccounts format.

API Version

Signature

setSubAccounts(subAccounts)

Example Implementation

1component.setParticipatingCustomers([ // Array of items
2    {
3        "volume": 50, // Percent of volume for this sub account. 
4                // Sum of included sub accounts volume must be 100 or less
5        "included": true, // Is Included?
6        "externalid": "Supermarkets" // External id of the SubAccount
7    }
8]);

setTacticConditionCreationDefinitions

Sets the related tactic condition creation definition records to the promotion.

API Version

Signature

setTacticConditionCreationDefinitions(tacticConditionCreationDefinitions)

Example Implementation

1component.setTacticConditionCreationDefinitions([ // An array of objects
2    {
3        IsNew: false, // Flag to indicate if the record is new
4        IsDeleted: false, // Flag to indicate if the record is deleted
5        Id : 'a50TC00000014j8YAA', // Record id
6        cgcloud__Tactic__c: 'a37TC00000014j8YAA', // Record attribute. 
7        // All Tactic condition creation definition record fields will be present as attributes
8        ...
9    },
10    ...
11]);

setTacticField

Sets the tactic SObject field.

API Version

Signature

setTacticField(tacticId, field, value)

Example Implementation

1component.setTacticField(
2    'a37TC00000014j8YAA', // Tactic field to set
3    'cgcloud__Comment__c', // Field name
4    'Sample Tactic' // value
5);

The field value sets that are managed by KPI Maps are ignored if provided through Business Objects API. This behaviour prevents any outdated data being sent to Trade Promotion Management.

Note

setTacticFunds

Sets the related tactic funds to the Promotion. To delete the tactic fund record, set the IsDeleted attribute to true. To flag a record as new, set the IsNew attribute to true. If the Sales Org has Fund Autodetermination enabled, TPM Application will always overwrite tactic funds with the records generated by the autodetermination process.

API Version

Signature

setTacticFunds(tacticFunds)

Example Implementation

1component.setTacticFunds(
2    [ // An array of objects
3        {
4            IsNew: false, // Flag to indicate if the record is new
5            IsDeleted: false, // Flag to indicate if the record is deleted
6            Id : 'a38TC00000014j8YAA', // Record id
7            cgcloud__Fund__c: 'a39TC00000014j8YAA', // Record attribute. Reference to the Fund__c record
8            cgcloud__Tactic__c: 'a37TC00000014j8YAA', // Record attribute. Reference to the Tactic__c record
9            // All Tactic Fund record fields will be present as attributes
10            ...
11        },
12        ...
13]);

The field value sets that are managed by KPI Maps are ignored if provided through Business Objects API. This behaviour prevents any outdated data being sent to Trade Promotion Management.

Note

predictUplift

This method returns a promise resolved when an uplift prediction is completed for the promotion. If the uplift prediction is disabled or the promotion isn’t in a correct status, the promise is rejected with an error stating the cause.

API Version

58.0

Signature

predictUplift()

Example Implementation

1const api = this.template.querySelector('cgcloud-tpm-promotion');
2
3
4api.predictUplift()
5    .then(() => {
6        // Uplift Prediction success
7    })
8    .catch((error) => {
9        console.log(error.message); // error message
10    });