Header Logics

This handbook will go over header logics for Quotes, Agreements/Promotions and Rebate Agreements. There are other documents which also have header logics (Price Lists) but these work in a different way and will not be covered in this handbook.

Business Use Case

For your quotes created in Quoting you want to calculate and display the total invoice price for the entire quote. This will be the sum of the output from the TotalInvoicePrice element over all line items. You need the result to be displayed on the quote’s header.
As a sales person your quotes contain an invoice price for each product, but you want all your quotes to have the total invoice price for the entire quote which is the sum of each product invoice price.
As a sales person you are working with quotes which contain an invoice price for each product. You want the quote to contain the total invoice price for the entire quote which is the sum of each product invoice price.
When the sales representatives are creating quotes, they need to be able to specify delivery type. The delivery type will apply for the whole quote, thus the input field must appear on the root level of the quote (and only on the root level, together with the input field for the customer).

Concept

Each document has a header that contains certain types of information about the document. Using the header logics we can manipulate these headers to add new inputs, outputs or change the structure of folders.

What Are Header Logics

Header Logics are a special type of Logics which work on the headers of either Quotes, Agreements/Promotions or Rebate Agreements. The most used functionality of these Logics is to add new inputs to the headers or do aggregation or rollups.

Flow / Execution

All header logics will be executed twice: before the line item calculation and after it. When the logic is being executed before the line item calculation we call it the Pre Line Item Logic Execution Phase (pre phase). When the logic is executed after the line item calculation it is called the Post Line Item Logic Execution Phase (post phase). The pre and post phases are essentially just independent executions of the header logic.

The header logic can determine the phase it is in via the binding variable with methods: isPrePhase() and isPostPhase()

During the document recalculation the header Logic and line item Logic are used to perform various tasks:

In the pre phase of the header Logic can:
1. Generate new input parameters at the root level (root folder).
2. Create, update and delete sub-folders and line items.
3. Generate new input parameters at sub-folders.
Execution of line item logic for each line item:
1. Can read input values from the header (root folder) and parent sub-folders.
In the post phase of the header logic can:
1. Gather information from the line items and do aggregations or other summary calculations.
2. The logic then adds these calculation results to the header results (root folder) or sub-folders results.

Data Model

Quotes, Rebate Agreements, Agreements/Promotions are broken down in to header and line items. The header contains information that applies to all line items (products) in a quote, while the line item contains information relevant only to that one quote line item.

The Root folder is actually virtual (not an item) and it’s created via the data in the Header.

Implementation / Configuration

Logics

The header has its own logic and logic execution sequence (see “Execution Phases” below) while the line item logic is executed as a generic logic by the header calculation.

When creating a header logic you need to pick the logic nature to provide the correct context for the logic.

Quote Header (quoteHeader)
Rebate Agreement Header (rebateAgreementHeader)
Agreements/Promotions Header (contractHeader)

Binding Variables

The header logic exposes a Builder object through the context supplied binding variable. This object can be used to read and modify the line items, and to read and modify the header inputs and outputs. The binding variables for each document are listed in the table bellow.

Logic Type	Binding Variable	Class

Logic Type	Binding Variable	Class
Quote Header Logic	quoteProcessor	QuoteBuilder
Rebate Agreement Header Logic	raProcessor	BasicRebateAgreementBuilder
Contract Header Logic	cProcessor	ContractBuilder

All of these classes extend the class CalculableLineItemCollectionBuilder

Inputs

Two types of methods for input creation:

addOrUpdateInput(String lineId, Map<String,Object> contextParameter)
- Adds or updates an input parameter on a folder (or line) with given lineId.
addOrUpdateInput(Map<String,Object> contextParameter)
- Adds or updates an input parameter on the ROOT level.

This method accepts a JSON record that may contain the following attributes:

name - Attribute value name.
label - Label appearing on the Quote Header form.
type - Specifies the input element type (list box, text, etc).
required - Determines if it is a required field.
value - Generates any default values.
valueOptions - Displays a mutually exclusive selection.

if (quoteProcessor.isPrePhase()) {
    quoteProcessor.addOrUpdateInput(
            [
                    name    : "Customer",
                    label   : "Customer Name",
                    required: true
            ])
}

Same functionality as code before, but we use the Input Builders

if (quoteProcessor.isPrePhase()) {
    api.inputBuilderFactory()
            .createUserEntry("Customer")
            .setLabel("Customer Name")
            .setRequired(true)
}

Outputs

Two types of methods for output creation

addOrUpdateOutput(Map<String,Object> calculationResult)
- Adds or updates a result value (an output value) on the ROOT level.
addOrUpdateOutput(String lineId, Map<String,Object> calculationResult)
- Adds or updates a result value (an output value) on a folder (or line item) with given lineId.

Add output to quote header for Margin %

quoteProcessor.addOrUpdateOutput(
        [
                "resultName" : "MarginPct",
                "resultLabel": "Margin %",
                "result"     : MARGIN_PCT_RESULT
        ]
)

Testing

When testing inputs for the header one thing which can be done is to use the method api.isDebug() to check whether the logic is executing in debug mode and use mocked values.

Otherwise for testing purposes, the Logic needs to be deployed to the partition and tested with a new document or modify an existing one.

Configuration

After the logic is deployed to the partition, the next step is to set it as a header logic for the document.

In the partition go to Quote / Contract Term / Rebate type.
Add a new type.
Select the Header Logic.

Now when you create a new document it will automatically use your Header Logic.

Summary

This handbook showed the most important principles of header logics, such as generating new inputs for headers and sub-folders in the pre phase. In the post phase header logics are capable of gathering information from line items and then doing aggregations or summary calculation which is then added as an output to the header or sub-folders.

References

Documentation

Knowledge Base

How to Understand Object Structures for API Calls

Groovy API

CalculableLineItemCollectionBuilder