Contracts
This article describes how to configure a partition so that end users can create promotions in the Agreements & Promotions module. 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.
About Promotions
In marketing, a promotion 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.
Variety of Use cases
In Pricefx the Agreements & Promotions module 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: 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 Module
The Agreements & Promotions module lets the end users — typically marketeers — define promotions in one central place. Here, the end user 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 modules — or exported to external systems.
When end-users — typically sales representatives — create quotes in Quoting, the quote pricing logic automatically applies the promotion discount.
Contracts
To set up a promotion, the end user must navigate to the contract detail page: Agreements & Promotions › Agreements & Promotions › New Agreement & Promotion:
In Pricefx, promotions are set up in contracts.
In Unity, the labels can be changed to display Promotions — instead of Contracts.
Similarly to the quote, a contract consists of:
A Header section
An [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.
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.
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 Administration › Logics › Header Logics › Agreements & Promotions, and set the Default Agreement & Promotion 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.
Contract terms are an abstraction of the terms and conditions of a promotion.
When the end user adds a line item, he/she selects a Contract Term Type, which is an entity that determines how the line items will be calculated.
A line item has input parameters — which allow the end users to specify thresholds, discounts, product ranges, etc. — and element outputs — which typically contain estimations of the impact of the promotion.
Contract Term Types
The contract term type (Condition Type) references a contract calculation logic. This logic generates input parameters (during input generation) and calculates outputs during recalculation.
The contract term type also has attribute1..30 fields, which can be read by the calculation logic and used to parametrize the behavior of 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 type applies to the line item.
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 contract terms to external systems.
Query the contract terms in other Pricefx modules.
Accessing the Contract Term Type Within the Logic
Sometimes, it can be useful to access the contract term type from within the calculation logic. For example:
When there is information stored in attribute fields of the contract term.
When a single logic is shared between multiple contract term types; the logic behaves differently depending on the associated contract term 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 contract term 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 is 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:
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 PromotionManager Price Record page: Agreements & Promotions › Price Records.
The Agreements & Promotions Price Record page only displays price records that originate from contracts. (Unity applies a filter on the Source ID field when it queries the Price Record table).
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.
Contract Term Type (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 match. The price records are used by the other modules and/or by external systems.
Price Record
Stores the details of the promotions that need 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.
Found an issue in documentation? Write to us.