Logic Execution

Logics act as hooks; they are functional building blocks that allow businesses to call their custom code under specific circumstances. A logic typically requires to be executed remotely — within a specific context. If you run a groovy script locally on you machine, it will likely fail, since you won’t have access to any of the operations that the Pricefx Logic API otherwise provides.

Logic accepts inputs as arguments and returns an array of results. An input or result can be any (JSON) serializable object. Logics are sensitive to the underlying state of the Pricefx application, which means that they are not pure function.

Testing Logics

To test your logic, use Pricefx Studio to invoke the logic remotely. When you open a logic.json file in IntelliJ with Pricefx Studio installed, you will notice a button that allows you to execute the logic in test mode. Since the logic is executed remotely, you need to provide the environment that it will execute in. This environment is called a partition.

Figure 1. Pricefx Studio provides a graphical user interface for executing logics. You need to specify a partition. That is, the environment that the logic will execute in.

Beneath the hood, pricefx studio combines the logic.json and .groovy files into a single JSON file, which it uses as payload in an API call to the backend application.

Deploying Logics

Before you can execute a logic, you need to deploy it to a partition. There are different ways how you can deploy a logic:

Pricefx Studio

Pricefx’s plugin for IntelliJ lets you deploy logics via the IntelliJ’s user interface.It also lets you run the logic remotely for debugging purposes.This is an option during development, when you only need to deploy the logic(s) that you’re working on.

Pricefx Maven Plugin

Pricefx’s Maven plugin adds several maven goals to your maven project that can be used to deploy data, including logics.This option is useful when you want to deploy a whole solution from scratch.It shouldn’t be used on production environments.

Pricefx Packaging tool

Pricefx’s command line tool for deploying logic.This option should be used in CI/CD pipelines.

When a logic is deployed to a partition, the backend application compiles the groovy source code it into bytecode. Later, when a scheduled job triggers a calculation, the compiled classes are dynamically loaded into the JVM and executed in a sandbox environment.

Since a logic is essentially just a function without interface, Pricefx won’t necessarily know in what context to execute it in. Therefore, most types of hooks require some additional configuration that tells Pricefx how the logic should be used. How to do this depends on the type of context the logic should execute in.

Logic Inputs

A logic takes inputs similar to how a function takes arguments. When you directly execute a logic via the REST API (for example via Studio), you get to specify the inputs as a JSON object. When a deployed logic is executed by the backend, the backend supplies the inputs depending on the context which it is executed in. For example, when calculating prices in a quote, the pricing logic gets the inputs from the end-user.

Example input

{
    "quantity": 12,
    "discount": 0.12,
    "countryCode": "SE"
}

Each input consists of a key-value pair; name and value. From within a script, you can access the inputs from the input binding variable. This is a variable that is injected into the scope of the script by the logic engine. The input binding variable is of the type Map<String, Object>, and can be accessed as such:

Three equivalent ways to read input.

input.hello
input['hello']
input.getAt('hello')

Logic Outputs (Results)

When a logic is executed, the scripts are executed in a fixed order. The elements property in the logic.json file specifies the order in which the scripts are executed.

Each Groovy script returns a value. Unlike Java, the return statement must not be contained within a method, but can appear at the root-level of the scripts. For example, the following script contains only a single line of code:

elements/Example.groovy

return "Hello Pricefx"

If a closing return statement is omitted from the script, the value of the final statement will be used as a return value. If that value is void, the returned value defaults to null.

For clarity, always include an explicit return statement:

When the logic execution completes, the engine collects the set of element results (outputs). Similar to the inputs, each result has a name and a value. The name is always equivalent to the element name.

Example Results

For example, when a price is calculated, a reference to a singe product is passed to the logic. The logic executes the element scripts in sequential order. The returned values are mapped to an array of results. One of the results in this array represents the calculated price, while the other results might represent other properties of interest; such as margins, quantities, manufacturing costs, currency, etc.

Result Formatting

While inputs consists of plain key-value pairs, results can contain additional properties. These properties are used by the frontend application to determine how the result values should be presented. Some examples are:

elementName

A unique identifier the element.

elementResult

The value returned by the script.

elementLabel

The text that will be displayed on the screen.If this value is omitted, the frontend application will default to the name.

formatType

Determines how the value should be formatted.For example, as a percentage

suffix

The string specified here will be appended after the value, when displayed on the screen.

warnings

Used to signal to the end-user that something in the calculation went wrong due to an error in the configuration.

alertMessage & alertType

Used to draw attention to specific calculation results.For example, to indicate for the end-user where a calculation failed, or that some value is outside some business-defined boundaries and needs extra attention.

Example Results

Some values in the logic result is determined during the execution of the script — by invoking certain methods — while others stem from the element properties within the logic.json file:

elementName

Determines the result name.

elementLabel

Determines the result label.

formatType

Determines the result formatType.

elementSuffix

References another element.The output from that element will be used as a suffix for this element.

hideWarnings

If set to true, all warnings will be hidden by the frontend application.