Concept

The concept of how our rates computation is something called a decision tree which can be visualized as below where the green path is an example of the elements of a traversed path:

Definitions:

  • Root Node (R): This node acts as the entry point to the tree.
  • Child Node (C): Child nodes contain the computation steps. Different combinations of child nodes will produce different end value.
  • Selector (S): Selectors acts like paths connecting nodes to one another. Each selector contain a specific characteristic that a booking must match to traverse to through.


Views

List View (Tree)

Chart View (Node)


Setup

Step 1: Root Node

In Manage > Rates, click on the 'Create' button to create a Root Node.



This opens up a new pricing tree and a form to set up the root node.

  1. Name of the root node that will be displayed when selecting rate IDs.
  2. Reference that will be displayed when selecting rate IDs. This will act as the entry point to the tree. Therefore, it must be unique.
  3. Sequence of selector keys that will be traversed when using this tree. You may set this up later once you set the children, or you may set this up at this stage if you already know what fields are you going to check.
  4. Description is mainly to help you understand what the tree is calculating, displayed in the previous page.
  5. Leave status as ACTIVE to be able to use this tree.
  6. Click 'Create' once you're done setting.


TIP: A combination of name & code will be displayed on rate ID selectors as follows:


TIP: Having a description helps you identify the rate tree's function when in the Manage > Rates page.

Step 2: Child Node

In the pricing tree page, hover over the 3 dots of your created root node, then click on 'Add Child Node'

List View

Chart View

The base setting of each child node has 2 sections. One for the selectors, which are conditions you will use to enter the node, and the other for nodes which are the computation to use when you traverse that node.


Selector Section


  1. Key: the accessor you would use to check the booking for the conditions. You can find these at the Booking Field Accessor section. For example, to get billing customer, use 'billTo.code'.
  2. Match any: Check this box if you provide more than 1 valid condition. However, if it needs to fit all the given condition, leave it unchecked. eg:
    1.  If the tree is valid for either billTo.code = ABC and billTo.code = DEF, Match Any ✅
    2. If the tree is valid only if the jobs.length >= 1 and jobs.length < 6, Not Match Any
  3. Add Child Selector: Click this button to add selectors (conditions). More below.
  4. Compute for each: Select a field to iterate through. Use this for aggregation nodes. More below.
  5. Traverse All: Check this box if you want to traverse through all the children to get separate chargeItems. If left unchecked, the traversing algorithm will traverse to only one child where the first condition met. Be reminded that Traverse All does NOT aggregate the children values.


When typing in keys, add a sample booking to see whether you're referring to the correct key. Sample booking will not be attached to the rates and is just there to guide you through the key selection.



The Selector section of the child node determines the characteristic that a booking must fulfill to traverse into the child node.



The fields are:

  1. Comparator: You have a selection of:
    1. Equals
    2. Not equals
    3. Greater than
    4. Greater than or equals to
    5. Lesser than
    6. Lesser than or equals to
  2. Value: The value to compare to the booking field.
  3. For example, if the node is valid for trip sequence 6 and above, you can setup the selector section to be:
    1. Key: jobs[0].trips[0].sequence 
    2. Comparator: Greater than or equals to
    3. Value: 6


Value Section

The value field determines the computation that will be added onto the sequence of operations when childNode is traversed through.


Basic Node

  • Operator determines the arithmetic operations to be carried out in that step on top of the base value. Base value is taken from the previous computation and initialized at 0. For example, if the value is set to 100:
    • ADD -> base value + 100
    • SUBTRACT -> base value - 100
    • MULTIPLY -> base value x 100
    • DIVIDE -> base value ÷ 100
    • BASE -> base value = 100 (replace the base value entirely)
    • CASCADE works in brackets. Each bracket will iterate through the given value and do the bracket specific computation. For example, in cases where the brackets is set up like this:
  • Value field determines the value that will be used. This depends on the Node Value Type.
  • Node Value Type: This will determine how the computation gets the value you want.

    • Number: Insert a number to use as value. You are allowed to use decimal points. If you're multiplying by a percentage, remember to use the decimal value. For example 40% = 0.4

    • Functions:

      • Choose from predefined functions.

      • Specify arguments directly in the node.

      • Example: GetDailyNumberOfTripsAfter(2)

    • Trees:

      • Input root codes of other trees to fetch their computed values.

      • Supports modular and reusable tree structures.

    • BookingField:

      • Use accessors to obtain value based on the booking object.

      • Eg: jobs.length will give you the number of jobs in that booking

  • ChargeItemCode: A selection of chargeItemCode that will be attached to the value computed. Computation will run on chargeItem codes and will appear in the cost sheet as separate line items.

  • Unit: If the line item in the cost sheet should have a unit, fill it here\

  • Use as quantity: Check this box when the value from the node represents the quantity of the unit you filled in instead of the value. For eg, if the node is meant to count the number of MT in the job, you set it up like this:

    • Node Value Type: Booking Field

    • Node Value: jobs[0].details.uom

    • Charge Item Code: YOUR_CODE_HERE

    • Operator: Base

    • Unit: MT

    • Use as quantity: ✅


Aggregation Node

In aggregation nodes (when you fill in the Compute For Each field), the form will show different fields.

  • The key for Compute For Each is formatted similarly to the key in the selector section.
  • There are the options for aggregator:
    • Max - take the highest value
    • Min - take the lowest value
    • Sum - sum up all the values obtained from the children nodes
  • In the example above, the compute engine will traverse the children nodes once per trip (for the first job of the booking) and use the one with the highest value as the node value.
  • For example, assuming each trip has different area code which results in producing different charges:
    • Trip 1 - 100
    • Trip 2 - 300
    • Trip 3 - 150
  • The setup above will use Trip 2 value.


Traverse All Node

When you check the Traverse All box, the node will not take any value. Traverse all nodes are meant to take all correct children instead of just traversing the first one. Each of these will be treated as separate line items in the cost sheet/incentive sheet.


Step 3 (Optional): Connecting multi-parent nodes

If you have setup a tree and wish to connect other parents to a node, simply drag from the dot at the bottom of the parent node onto the dot at the top of the child node

Doing this allows you to simplify your setup without needing to make duplicate nodes.