Establishing Promotions with Contracts
Introduction
This lecture describes how to configure a partition so that end-users can create promotions in the Agreements & Promotions capability. When setting up a promotion, the end-users will set the contract terms with input parameters, and see the estimated impact of the promotion in the calculation results.
Overview
About Promotions
In marketing, a promotion or an agreement is an incentive for buyers to initiate purchases. Typically, it lowers the prices of selected products and services — for selected buyers — during a limited amount of time. For example:
Lower the prices of all products in product group G by 5% for customer C, during the time period 2021-01-01 — 2021-03-31.
Promotions and Agreements are different names that typically refer to the same thing, based on the use case.
Variety of Use cases
In Pricefx the Agreements & Promotions capability is often used also for quote type activities or complicated contracts, where:
Prices need to be set at the product group or customer group levels rather than just individual customer / sku
There are distinctly different types of pricing that need to be done in a single “document” – like a standard price agreement and another type of term that is managed by the same business process.
example for this: both "standard" pricing (which had several distinctly different levels) and "supplemental" agreements need to be handled as one “deal” by the sales team.
The Agreements & Promotions Capability
The Agreements & Promotions lets the end-users — typically marketeers — define promotions in one central place. Here, the end-users creates a document which specifies the terms and conditions. The document will then display estimations of how big impact the discount will have.
When submitted and approved, the promotion can be used in Pricefx’s other capabilities — or exported to external systems.
When end-users — typically sales representatives — creates quotes in Quoting, the quote pricing logic automatically applies the promotion discount.
Figure 1. Schematic representation of the life cycle of a promotion. The promotion is negotiated with the customers by the sales managers/marketeers, who then proceeds to create a contract document. When submitted and approved, the resulting price records can be used by the other modules and/or in external systems.
Contracts
To set up a promotion, the end-user must navigate to the Agreements & Promotions page: Agreements & Promotions Agreements & Promotions New Agreement & Promotion:
Figure 2. Setting up a new contract
Figure 3. The contract detail page
In Pricefx, contract is the technical name for a promotion or agreement document
In Unity, the labels can be changed to display Promotions — or Contracts or Agreements.
Similarly to the quote, a contract consists of
Header section
[Line] Items section
Contract Header
Information about the contract as a whole is stored in the header. Like the quote, the header has input parameters and output values; both of which are controlled by a header logic.
Figure 4. The contract Header with inputs and outputs
In Pricefx Studio, a header logic can be added by selecting the formula nature Contract Header. In most aspects, the contract header logic works like the quote header logic, but the document is traversed by utilizing the binding variable cProcessor, which references the ContractBuilder.
Example 1. Accessing the contract, represented as a Map, from within a contract header logic.
cProcessor.getContractView()To ensure that the header logic is used for new contracts, navigate to Configuration Logics Header Logics Contracts, and set the Default Contract Header Logic.
Contract Line Items
Unlike the quote, contract line items represent a broader set of contract pricing terms, not necessarily related to only one product.
Conditions are an abstraction of the terms and conditions of a promotion.
When the end-user adds a line item, he/she selects a Condition Type, which is an entity that determines how the line items will be calculated.
A line item has input parameters — which allows the end-users to specify thresholds, discounts, product ranges, etc — and element outputs — which typically contains estimations of the impact of the promotion.
Agreements & Promotions Types
For Agreements & Promotions you can create multiple different types. Navigate to Agreements & Promotions → Agreements & Promotions types.
Here you can create different types of Agreements & Promotions, where you can specify the header logic and the workflow logic as well.
Condition Types
The Condition type references a contract calculation logic. This logic generates input parameters (during input generation) and calculates outputs during recalculation.
Figure 5. Each line item (Condition) references a Condition type, and each Condition type references a calculation logic. The Condition type also has attribute1..30 columns that can be accessed by the logic.
Contract Calculation
When the end-user clicks on Recalculate, or when he/she submits the document for approval, the contract is sent to the backend for calculation. There, for each line item, the associated calculation logic is invoked and the result is saved on the line item. Thus, a big difference between quotes and contracts is that the quote’s quote type applies to the entire document, while the contract’s contract term types applies to the line item.
Figure 6. Schematic representation of the events that take place when the end-user clicks on Recalculate on the contract detail page.
Typically, the result of a contract calculation logic will be twofold:
Estimations of the impact of the promotion. An example of this can be to use transactional history to extrapolate future sales, and apply the promotion to obtain a simulated value.
Price records (created after approval), which are used to
Export the Conditions to external systems.
Query the Condition in other Pricefx capabilities.
Figure 7. Schematic representation of the contract calculation which occurs when the document is saved and approved.
Accessing the Condition Type Within the Logic
Sometimes, it can be useful to access the Condition type from within the calculation logic. For example
when there is information stored in attribute fields of the Condition term.
when a single logic is shared between multiple Condition types; the logic behaves differently depending on the associated Condition type.
In a case like this, read the line item with api.currentItem() and access the contract term type name with
String contractTermTypeName = api.currentItem().contractTermTypeTo read the Condition type’s attribute field values, use api.find(), with the type code CTT.
api.find('CTT', 0, 1, null, Filter.equal('uniqueName', contractTermTypeName))Price Records
When a promotion has been set up, it needs to be used somewhere else; either in other modules, or in some external systems. Therefore, when a contract is approved, a set of price records are generated.
Each contract line item results in the creation of one price record. The values of the line item inputs — and outputs — are mapped to those price record attribute fields where the name matches. For example:
Figure 8. Example where the values from one contract line item input (ProductGroup) and one contract line item output (PromotionDiscount) are mapped to attribute fields in the price record.
These price records are of the same type as for quotes; meaning that contract price records are stored together with quote price records in the same physical table. The way to distinguish between the two is by looking at the Source ID field; for quotes, it starts with “P-” — and for contracts, it starts with “C-”.
The price records can be viewed on the Agreements & Promotions Price Record page: Agreements & Promotions Price Records.
Figure 9. A screenshot of the PromotionManager Price Record page.
Differences between Quote and Contract
A Quote uses one Customer on the Header and then each Line item has one product. Each line represents conditions negotiated for single product.
Whereas the Contract Header can define none, one or a group of Customers and each Line item can have different Customers too (or it can simply inherit the group of Customers from the Header). A Line item of a Contract can represent conditions for one Product, but also for a group of Products.
Summary
When end-users wants to create promotions, they need to first create a contract. Among other properties, a contract has a label, a validity date range, a header and line items.
Contract
A document used for establishing the terms and conditions of one or more promotions.
Contract line items can also be referred to as contract terms. A promotion is represented by a contract line item.
Contract Line Item
Contains the terms and conditions for one specific promotion.
Each line item holds a reference to a contract term type, which in turn references a contract (calculation) logic. This calculation logic is used to generate input parameters and calculate outputs. Thus, different calculation logics may be used for different line items within a contract. This is unlike the quote, where all line items are passed to the same calculation logic.
Condition Type
Specifies how the promotion is calculated. Each contract line item references one contract term type.
When a contract gets approved, a price record is created for every line item. The values of line item inputs and outputs are copied into the price record — where the names matches. The price records are used by the other modules and/or by external systems.
Price Record
Stores the details of the promotions that needs to be exported to external systems, or used by other modules within Pricefx.
The next lecture details how a promotion can be implemented in other modules, by using the price records.
References
Developer Documentation
Documentation (Classic)
Older Training Materials
Accelerators (non-public)
Found an issue in documentation? Write to us.