Loading
Set Up Trade Promotion Management
Table of Contents
Filter by (0)Add
Select Filters

          No results
          No results
          Here are some search tips

          Check the spelling of your keywords.
          Use more general search terms.
          Select fewer filters to broaden your search.

            Search all of Salesforce Help
            Search all of Salesforce Help
            Core Business Object API Rule Definitions

            You are here:

            1. Salesforce Help
            2. Docs
            3. Set up and Maintain Trade Promotion Management

            Core Business Object API Rule Definitions

            Trade Promotion Management includes some methods that are used to create Business Object (BO) API Workflow Steps. These steps are used to create the output JSON that's used during BO API Transaction creation and mass-copy promotion.

            Required Editions

            Available in: Lightning Experience

            Available in: Enterprise and Unlimited Editions where Consumer Goods Cloud is enabled

            Generic Method

            This method belongs to the PromotionBoApiCoreWorkflowSteps class.

            Method Description
            mapValues

            Maps values from the input to the output structure without any processing. The method can be used to map promotion values (mapPromotionValues) and tactic values (mapTacticValues).

            The method reads the value of the Maps To field and maps the field to the output fields. For instance, CG_Slogan_Language_1__c is an output field that's used to set the slogan for a promotion.

            The input properties of this method depend on the entity for which you use this method.

            Entity Input Properties
            Promotion (create and update workflow)
            • Slogan: Sets the slogan for a promotion.
            • Comment: Sets the comment for a promotion.
            Tactic
            • Amount: Sets the tactic amount for a tactic.
            • CompensationModel: Sets the compensation model for a tactic.
            • .CreateDefaultConditions: Determines whether default Tactic Condition Creation Definition (TCCD) records are created for a tactic via Tactic Template Condition Creation Definition (TTCCD). If this field is set to true, the system creates default TCCD records in addition to those records created via BO API.

            Note
            Note You can specify multiple fields as comma-separated values in the output.

            Promotion Methods

            These methods belong to the PromotionBoApiCoreWorkflowSteps class.

            Method Description
            loadPromotionDefaults

            Loads promotion values. Based on the input, the method can load promotions in these ways:

            • When a promotion ID or external ID is provided: The system loads the records of the specified promotion. If the promotion and the external ID in the input don’t exist, then the system creates a promotion with the same promotion and external ID as the input.
            • When no ID is provided: The system instantiates a new promotion with the record type provided by the promotion template, which is a mandatory input.
            Note
            Note
            • The promotion ID or external ID is a mandatory input for the update workflow, but an optional input for the create workflow. 
            • The system raises an exception if:
              • The user doesn’t have access to the promotion template and promotion record. This rule is applicable during promotion creation and update.
              • The promotion template is inactive. This rule is applicable only during promotion creation wherein the promotion isn’t created. The rule isn’t applicable during promotion update.
              • The user doesn’t have a valid promotion role.
            setPromotionAnchor

            Checks the value of the promotion anchor. Depending on the anchor type of the promotion template, the promotion anchor can be customer, customer set, or null.

            • setPromotionAnchor is run after loadPromotionDefaults. The method is run only during promotion creation.
            • While running this method, the system raises an exception in these scenarios:
              • The promotion template is invalid based on the anchor type of the promotion.
              • The customer has an invalid promotion role. Here, the promotion isn’t created. This exception is raised only during promotion creation.
              • The input property is missing.
            setPromotionDates

            Sets the promotion dates (Date From, Date Thru, commit date, in-store dates, order dates, and shipment dates).

            The input properties are:

            • .DateFrom
            • .DateThru
            • .CommitDate
            • .PlacementDateFrom
            • .PlacementDateThru
            • .OrderDateFrom
            • .OrderDateThru
            • .DeliveryDateFrom
            • .DeliveryDateThru

            During promotion creation, the Date From and Date Thru of a promotion are mandatory inputs. The system raises an exception if these inputs are missing.

            applyPromotionDateHandling Applies automatic promotion date handling rules to new promotions. The method updates the promotion and tactic periods based on the Timeframe Determination Policy of the promotion, and is applicable only when the timeframe determination policy is set to Automatic Simple.
            Note
            Note You need the in-store dates of the promotion to apply the automatic promotion date handling rules. Run applyPromotionDateHandling after setPromotionDates. To achieve this, when adding Business Object API Workflow Steps to the Business Object API Workflows, the workflow step that uses applyPromotionDateHandling is assigned a higher sort value compared to the one using setPromotionDates.
            setPromotionCategories Sets the promotion categories. During promotion creation, the system reads all the categories the user has access to, and adds a new entry with proper categories in the output JSON. When a promotion is created or updated, the system generates new records on promotion product share to store the categories to which the user has access.
            setPromotionSubAccounts Takes the sub accounts associated with the anchor customer of the promotion and places the sub accounts in the promotion.

            If the Sub Accounts Enabled option is set to True, this method sets the information of the sub accounts in the promotion.
            setPromotionParticipatingCustomers

            Sets the participating customer information for a promotion.

            If the Pushable option is set to True, this method sets the values of the Aggregation Category and Push Target Account Selection fields of the promotion. These fields aren’t visible on the UI.

            BOPromotion Methods

            These methods belong to the PromotionBoApiCopyCoreWorkflowSteps class.

            Method Description
            loadPromotionBOForCopy

            Loads the promotion business object and copies the object's properties into the output object while mass copying promotions.

            The mandatory input property of this method is .Id, which refers to the promotion’s Salesforce ID or external ID.

            The system raises an exception if the promotion isn’t found or if the copyable option of the promotion template is set to False.
            loadPromotionAttachmentsForCopy

            Loads the promotion attachments while mass copying promotions.

            The input properties of this method are:

            • .Id: This mandatory input determines the promotion’s Salesforce ID or external ID.
            • .CopyAttachments: This optional input determines whether to load the attachments.
            Note
            Note This method is applicable only if the .CopyAttachments property is set to True.
            loadCategoryShareLO Loads the details of category sharing for a promotion while mass copying promotions.

            The mandatory input property of this method is .Id, which refers to the promotion’s Salesforce ID or external ID. The system raises an exception if the promotion isn’t found.

            This method is run based on this logic:

            If the Promotion Access Definition Policy of the sales organization is---and the anchor type of the promotion template is set to...Ensure that the current user...
            Combined AnchorsCustomerConforms to one of these criteria:
            • Is an active or to-be-deactivated product manager with read or write access to all categories of the anchor customer of the source promotion.
            • Is an active or to-be-deactivated product manager with read or write access to all categories of the source promotion for all the customers that belong to the sales org.
            Combined AnchorsCustomer SetConforms to one of these criteria:

            • Is an active or to-be-deactivated product manager with read or write access to all categories of the source promotion for at least one customer that belongs to the anchor customer set.

            • Is an active or to-be-deactivated product manager with read or write access to all categories of the source promotion for all the customers that belong to the sales org.

            Independent AnchorsNAIs an active or to-be-deactivated product manager with read or write access to all categories for all the customers that belong to the sales org.
            resetPromotion

            Resets the promotion structure to insert as a new one.

            This method sets the values of these output fields:

            • originalId: Promotion ID
            • Id: null
            • External Id: Empty
            • Phase: Planning
            • Active: Value of the Active Policy option
            • Is Frozen: False
            • Is Locked: False
            • Scenario 1 / Scenario 5 parameters: Empty
            • Scenario 1 / Scenario 5 manual inputs: Empty
            • Selected Scenario: 1 (default)
            • Trade Calendar Color Codes and Transparency: Set based on a predefined logic
            • Slogan: Set based on a predefined formula
            • KPI Value 1/4: Empty
            • Push in Progress: Empty
            • Version: Empty
            • Version Synced Off Platform: Empty
            • Outdated Staging Records: No
            • Lock Deletion: False
            • Effective Categories: Empty
            • Effective Brands: Empty
            • Parent Promotion: Empty
            • Aggregation Category: If Is Pushable or Is Derivable is set to True, the system sets a unique identifier on this field; else this field is empty.
            • flags: c
            • __ObjectStatus: New
            movePromotionTimeframe

            Advances the promotion dates by the specified number of years.

            This method is used during mass copy of promotions to set the values of these promotion and tactic dates:

            • Promotion Dates:
              • Date From and Date Thru
              • Commit date
              • Reference date
              • Shipment dates
              • Order dates
              • In-store dates
              • Custom date range

            • Tactic Dates:

              • Date From and Date Thru
              • Shipment dates
              • In-store dates
              • Custom date range

            The optional input property of this method, .AddYears, determines the number of years by which to move the promotion dates. This method sets the promotion dates based on the offset defined in this input property and calculates the offset years based on the value of the Mass Copy Start Date option.

            Note
            Note If the .AddYears property isn't set, the promotion dates are advanced by one year.

            After the dates are changed, the system validates that the selected customer or customer set is valid for the new promotion period.
            managePromotionProductFilterCopy

            Filters the product filter criteria by removing products that are no longer valid for the promotion period. This method is used during mass copy of promotions.

            This method sets the output based on this logic:

            • If the relevant promotion template doesn’t include products as part of the Copied Components, an empty filter criteria is set on the output.

            • Otherwise, this method evaluates the promotion template’s Consider Account Product List and Consider Product KAM status options to determine valid manual products. Manual products that don’t pass this criteria are removed from the product filter criteria. The filtered manual products are set as the new value of the filter criteria on the output.
            manageParticipatingCustomersCopy

            Identifies and removes invalid customers from the list of participating customers in the target promotion period during mass copy of promotions.

            If the promotion template isn’t pushable, this method sets the Promotion Push Target Account Selection field to empty. This field isn’t visible on the UI. Otherwise, for each participating customer, the method evaluates these criteria:

            • The customer is below the anchor customer of the promotion in the trade org hierarchy at the commit date of the target promotion.

            • The customer has a valid promotion role for the complete time frame (Date From - Date Thru) of the target promotion.

            • The Account Plan Type of the customer is set to Plan.

            The system classifies the customers that don’t meet any of these criteria as invalid customers and removes them from the list of participating customers.

            Note
            Note For all valid customers, the system copies the Included option from the source promotion to target promotions.
            manageSubAccountsCopy

            Identifies and removes invalid sub accounts from the list of sub accounts in the target promotion time frame during mass copy of promotions.

            This method sets the output based on this logic:

            If the Sub Accounts Enabled option of the promotion template is set to... then...
            False This method sets the Promotion Sub Accounts Selection and Promotion Volume Percent options as empty. These fields aren’t visible on the UI.
            True For each sub account, this method checks that the customer is a valid sub account to the anchor customer on the commit date of the target promotion. After that, the system removes the invalid sub accounts and recalculates the value of Promotion Volume Percent using summation by considering the percentage of volumes for only the selected remaining customers.
            Note
            Note For all valid sub accounts, the system copies the Included option from the source promotion to target promotions.
            manageManualInputCopy

            Manages manual inputs during mass copy of promotions.

            This method sets the output based on this logic:

            If manual inputs are...then...
            Not included in Copied ComponentsAn empty value is set on Promotion Manual Input field. This field isn’t visible on the UI.
            Included in Copied Components

            This method copies only the copyable measure codes. The method also adjusts the manual input periods and takes care of these aspects:

            • If the source promotion includes manual inputs for a product that's no longer valid for the target promotion, the manual inputs for that product aren’t applied.
            • If the source promotion includes manual inputs for a tactic that isn’t copied to the target promotion, the manual inputs for that tactic aren’t applied. A tactic isn't copied if it isn’t included in copied components or if it has an inactive tactic template.

            Copies the manual input relevant for the nth week or period of the source promotion to the nth week or period of the target promotion. If the source promotion has a greater number of weeks or periods than the target promotion, the manual inputs of extra weeks or periods of the source promotion are lost. But if the source promotion has a lesser number of weeks or periods than the target promotion, then no values are copied to the extra weeks or periods of the target promotion.

            Tactic Methods

            These methods belong to the PromotionBoApiCoreWorkflowSteps class.

            Method Description

            loadTacticDefaults

            Loads tactic values during tactic creation and update. Based on the input, the method can load tactics in these ways:

            • When a tactic ID or external ID (optional input) is provided, the system loads the records of the specified tactic. If the tactic ID or external ID that's provided in the input doesn’t exist, the system creates a tactic with the same tactic or external ID that's provided in the input.

            • When no ID is provided, the system instantiates a new tactic with the record type provided by the tactic template, which is a mandatory input.

            This method also sets the value of the product filters as the output in this manner:

            If the Filter_Criteria property is... Then...
            Defined for the parent promotion The value of this property is used to set the value of the product filters.
            Not defined for the parent promotion An empty filter criteria is generated.
            Note
            Note
            • During tactic creation and update, the system raises an exception if:
              • The user doesn’t have access to the tactic template or tactic record.
              • The tactic template isn’t specified.
            • If the tactic template is inactive or isn’t associated with the promotion template, the system raises an exception during promotion creation and the promotion isn’t created. No exception is raised on promotion update.

            • The tactic ID or external ID is a mandatory input for the Update workflow, but an optional input for the Create workflow.

            setTacticDates

            Sets the tactic dates (Date From, Date Thru, instore, and shipment) when a tactic is created or updated.

            The input properties of this method are:

            • .DateFrom

            • .DateThru

            • .InStoreDateFrom

            • .InStoreDateThru

            • .ShipmentDateFrom

            • .ShipmentDateThru

            During tactic creation, if no values exist in the input, the equivalent values are copied from the promotion. During tactic update, the missing values remain untouched.

            LOTactic Methods

            These methods belong to the PromotionBoApiCopyCoreWorkflowSteps class.

            Method Description
            loadTacticsLOForCopy

            Loads the promotion tactic list while mass copying promotions. The method removes all the tactic records with an inactive tactic template.

            The mandatory input property is .Id, which refers to the promotion’s Salesforce ID or external ID.

            The system raises an exception if the promotion isn’t found.

            Note
            Note This method is applicable only if the relevant promotion template includes tactics as a part of the Copied Components.
            resetTactic

            Resets the tactic structure to insert the structure as new.

            The method sets the values of these output fields:

            • originalId: Tactic ID

            • Id: New temporary ID

            • External Id: Empty

            • Effective Categories: Empty

            • Effective Brands: Empty

            • Scenario Participation: Empty

            • Parent Tactic: Empty

            • KPI Value 1–4: Empty

            • Aggregation Category: If the Pushable or Derivable option is set to True, then a unique identifier is set on this field. Otherwise, this field is empty.

            • flags: c

            • __ObjectStatus: NEW

            • Create Default Conditions: False
            manageTCCDsLOForCopy

            Copies the Tactic Condition Creation Definition (TCCD) records from the source promotion tactics to the target promotion tactics. The method uses the current BO Promotion output JSON as the input to retrieve the details of relevant tactics and fetch the related TCCD records.

            Note
            Note
            • This method is applicable only if the relevant promotion template includes tactics as a part of the Copied Components.
            • Run loadTacticsLOForCopy and resetTactic methods before this method. Otherwise, the system raises an exception. To achieve this, ensure that the sort value of this method is greater than the sort values of the loadTacticsLOForCopy and resetTactic methods.
            manageTacticProductFilterCopy

            Filters the product criteria by removing products that are no longer valid for the promotion period while mass copying promotions.

            This method sets the output based on this logic:

            • If the relevant promotion template doesn’t include products as part of the Copied Components, an empty filter criteria is set on the output.

            • Otherwise, this method evaluates the promotion template’s Consider Account Product List and Consider Product KAM status to determine valid manual products. Manual products that don’t pass this criteria are removed from the product filter criteria. The filtered manual products are set as the new value of the filter criteria on the output.

            Product Method

            This method belongs to the PromotionBoApiCoreWorkflowSteps class.

            Method Description
            setProductFilter

            Sets the product filter criteria provided in the input to the promotion’s filter criteria value.

            Note
            Note Provide the filter criteria at the promotion level in the input JSON. You can’t add products individually to tactics.

            The input properties of this method are:

            • .IncludedProducts[*]: Determines the external IDs of the products to include

            • .ExcludedProducts[*]: Determines the external IDs of the products to exclude

            • .Criteria.Category[*]: Determines the external IDs of the categories to include

            • .Criteria.Subcategory[*]: Determines the external IDs of the subcategories to include

            • .Criteria.Brand[*]: Determines the external IDs of the brands to include

            • .Criteria.Package[*]: Determines the external IDs of the packages to include

            • .Criteria.Flavor[*]: Determines the external IDs of the flavors to include

            Each input property accepts only string values with a maximum of 40 characters.

            The Maps To field includes the name of the field on which the filter criteria is set. Each criteria property is mapped to the Salesforce object field that represents it.

            For instance, the .Criteria.Brand [*] property is mapped to the Brand__c field in the core application as:

            ".Criteria.Brand[*]" => "brand__c"

            Projects can map their own customized fields to each property.

            Note
            Note

            • The system raises an exception if the IDs of the brand, category, or products (included and excluded) aren’t accessible.

            • If the BOM Handling field of the promotion template that's passed in the input is set to Exclude BOMs, the system:

              • Sets the Is Bill of Material filter to False for the dynamic products.

              • Validates if the BOM flag is set to False for the manual products included in the input

            In the product filter criteria, when you add multiple categories, include at least one brand corresponding to each category for the selection to be valid. When you add multiple categories and one or more brands of one category and no brand of the other category, the category for which no brands are included is ignored by the system and not included in the promotion. To avoid this, include all the brands of each product category in the input.

            Manual Input Method

            This method belongs to the PromotionBoApiCoreWorkflowSteps class.

            Method Description
            handleManualInputs

            Handles the list of manual inputs provided by the user at product, component, promotion, or tactic total level.

            The input properties of this method are:

            • [*].KPI: Specifies the KPI name to be set. The method accepts only string values with a maximum of 80 characters.
            • [*].Value: Specifies the value to be set to the KPI. The method accepts only numeric values.
            • [*].Product: Specifies the product ID to set the KPI value to. If not set, the KPI value is set as the total value for the promotion or tactic. If the manual input is for a BOM component, this parameter specifies the product ID of the parent product (BOM header) of the BOM component. In both cases, specify the product ID as Salesforce ID or external ID.
            • [*].Component: Specifies the product ID of the child product (BOM component). Specify the product ID as Salesforce ID or external ID. This parameter is applicable only for manual inputs of BOM components.

            When the BOM Scope of the input KPI contains Component, the system sets the KPI value as the total value of the corresponding product, component, promotion, or tactic in this manner:

            If the input JSON contains a value for... the system...
            Product (header) and component Sets the KPI value as the total value of the corresponding component.
            Only product Sets the KPI value as the total value of the corresponding product.
            Neither product nor component Sets the KPI value as the total value at the corresponding promotion or tactic level depending on the object scope of the KPI.
            Component but not product Raises an exception.

            Depending on whether Scenario Planning is enabled, these options are possible:

            Scenario Planning Status Action
            Enabled
            • The system adds manual inputs for a KPI with promotion object scope to the manual input field of the active scenario and to the manual calculation input field of the promotion.
            • The system adds manual inputs for a KPI with promotion tactic object scope to the manual calculation input field of the promotion.
            Disabled The system adds manual inputs for a KPI with promotion or promotion tactic object scope to the manual calculation input field of the promotion.
            Note
            Note The system validates these conditions on the input parameters and raises exceptions if the conditions aren’t met:
            • The KPI is the Editable or Editable Calculated record type.
            • The KPI has the edit mode set to All or Total, object scope set to Promotion or Promotion Tactic, and fixed totals set to False.
            • The KPI is included in the KPI set that's linked to the corresponding promotion template.
            • If the KPI is of the Editable Calculated record type and a part of a Compound KPI, ensure that the compound main of the KPI is set to True.
            • If the parent object is a promotion, ensure that the KPI is of promotion level. If the parent object is a tactic, ensure that the KPI is of tactic level.

            • The product is valid (the product exists) for the sales org.

            • If the BOM Handling option of the corresponding promotion template is set to Exclude BOMs, the BOM field of the product is set to False.

            • If the BOM scope of the KPI contains Component, the system additionally validates that:

              • The KPI is of the Editable record type.

              • The BOM Handling option of the corresponding promotion template is set to Consider BOMs.

              • The product and component parameters of the input isn't empty.

              • The specified BOM component is valid (the BOM component product exists) for the sales org.

              • The product part that links the BOM component and the BOM header exists in the system.

            Tactic Condition Creation Definition Method

            This method belongs to the PromotionBoApiCoreWorkflowSteps class.

            Method Description
            SetTacticConditionCreationDefinitions Creates Tactic Condition Creation Definition (TCCD) records when a new promotion is created and updates TCCD records when a promotion is updated.

            The input properties of this method are:

            • [*].SourceKPI

            • [*].AdditionalKPI1/2/3

            • [*].ProductLevel

            • [*].MeasureCode

            • [*].Maintenance

            • [*].ChangeRule

            • [*].Targets

            • [*].AllowedProductLevels

            • [*].DuplicateCheck

            • [*].UniqueMeasureCode

            Note
            Note

            • The source KPI is a mandatory input for the Create workflow and the system raises an exception if the KPI isn’t defined in the input. In case of the Update workflow, none of the inputs are mandatory.

            • The system raises an exception if the source KPI isn’t included in the KPI set that's linked to the corresponding promotion template.

            • During the update workflow, the system uses the unique measure code field in the input to identify the TCCD record to update.

            This table lists the different scenarios that the system can encounter:

            WorkflowIf...then...
            CreateThe mandatory fields of the TCCD object (Duplicate Check, Change Rule, Target, and Maintenance) aren’t defined in the inputFor the Duplicate Check, Change Rule, and Target fields, the system uses the values defined in the TTCCD record that's created for the corresponding tactic template. If multiple TTCCD records exist, the system determines the fallback TTCCD record in this manner:
            • If the corresponding tactic template has a TTCCD record with the source KPI and measure code matching the ones provided in the input, the system uses that TTCCD record.
            • If the corresponding tactic template has TTCCD records with the source KPI matching the one provided in the input, the system uses the first found TTCCD record with the matching source KPI.
            • If the corresponding tactic template doesn’t have any TTCCD record that meets the conditions, the system uses the first found TTCCD record.
            Note
            Note If no TTCCD records exist for the corresponding tactic template, the system uses the default value of the fields in the TCCD object.

            For the Maintenance field, the system uses the maintenance value that's defined in the tactic. If maintenance value isn’t available in the tactic, the system uses the default value of the maintenance field in the TCCD object.

            UpdateThe unique measure code isn’t defined in the input The system creates a TCCD record.
            Note
            Note Run the mapTacticValues method before this method. Ensure that the sort value of this method is greater than the sort value of the mapTacticValues method.
             
            Loading
            Salesforce Help | Article