NOTE: Rollup fields functionality was introduced in the June 2021 release, except the part dealing with automatic rolling up of start_date and end_date, which are in the July 2021 release.
Configuration
Rollup-Target Input Type
A new input-type has been added for form fields and product fields called rollup-target. These fields, when used in a client/order/line/flight, are read-only and are set to the sum of any sub-entity rollup sources that set their rollup field name to this target (unless they are start_date or end_date). For start_date rollup targets, the value is set to the earliest sub-entity start_date, and for end_date rollup targets, the value is set to the latest sub-entity end_date.
- For clients, sub-entities are orders, and client tasks.
- For orders, sub-entities are line items and order tasks.
- For line items, sub-entities are flights and line item tasks.
- For flights, sub-entities are flight tasks.
Note that for start_date and end_date rollup targets, sub-entities cannot be tasks. The only supported date rollups are from flight to line item, and line item to order. And importantly, sub-entity start_date and end_date fields are implied rollup sources and do not need (and cannot) be explicitly configured.
Rollup targets are subject to the following rules:
-
These fields cannot be cascading fields. Their value is the sum of sub-entities' rollup field sources, which is incompatible with being a cascading field target.
-
A task field cannot be a rollup target.
-
For client rollup targets, the data types can be one of string or integer. (Clients do not currently support decimal, currency or percentage). If the rollup source is decimal, currency or percentage, then the client rollup target’s data type should be string so the value can be displayed correctly.
-
For other rollup targets (i.e., orders, line items, flights), data types can only be one of percentage, currency, decimal or integer. For start_date and end_date order and product fields, the only supported data type is date.
Here is a screenshot showing a rollup target field definition:
A new form and product field parameter called Rollup Field Name has been introduced to configure rollup sources. These indicate which rollup target to add values to. This field is available on order, flight and task forms, as well as products. It is not available on client custom forms, since these have nowhere to rollup to (i.e. no possible rollup targets).
Because start_date and end_date are implied rollup sources, these fields do not need to be configured as rollup sources and therefore do not need to set the Rollup Field name. The system behaves as if any start_date field had its Rollup Field name set to ‘start_date’, and similarly for the end_date fields.
These values are not free-form but selectable from a drop-down list of possible targets. Note that targets are not filtered according to business units, so some values may appear that are for forms defined on other business units (and might not be reachable to the current form). In addition, start_date and end_date cannot be possible targets.
Rollup sources configured in this field are subject to a few rules:
-
They cannot also be a cascading field. This is to prevent infinite loops, with entities being updated from above (fields cascading down), rolling up to some target that would cascade down again, etc.
-
For the same reason, they cannot be calculated or calculated-override fields.
-
These fields cannot have a parent field. If they had parents, computing their total values would be complicated since any given attribute could be hidden by their parent’s value, complicating the backend immensely.
-
These fields’ data types can only be one of percentage, currency, decimal or integer. This is to ensure compatibility with rolling targets.
Here is a screenshot of this parameter:
We currently do not support recalculation of existing clients/orders/lines/flights if their form is modified to add a rollup target field. Newly modified rollup targets are only recomputed when rollup sources are next modified.
Client Page Modifications (Old UI)
The old UI client edit page has been enhanced to support the new rollup-target input type. Such fields are read-only. There cannot be rollup source fields on the client page. Here is an example of a client edit page with custom rollup target fields:
Here is an example of a client edit field in the New UI with a custom rollup target field (called child):
Order, task, line item and flight pages can both have rollup sources and rollup targets, as configured for the relevant fields. Rollup sources can be modified, but rollup targets cannot. Here is an example for an order with both a rollup source and a rollup target:
Run-Time Behavior
Rollup Target Count Computation
Rollup targets are computed whenever an event happens that might modify their value. This includes the following:
-
When a source field is modified. This can be via the front-end, or an integration such as flatfile or webhook consume. It can also be following the cloning of an entity that contains source fields. Moving a flight from one line item to another can also trigger rollup target computation.
-
When a source entity changes state (see next section).
Source Entity States
Rollup sources are only counted towards the rollup target sum if their entity is in “non closed” state. This means that an order/line/flight must be in a state other than closed, cancelled or rejected. For tasks, it means a state other than closed.
Tasks
Note that when tasks are assigned to a given entity (client/order/line/flight), their attribute value is stored in such a way that all instances (i.e., assignments) of a given task share the same value. You can see it if you modify it for one instance, its value changes on another instance (of the same task only). Nevertheless, even though a single value is internally stored, if that value is a rollup source, the rollup target will add the value for all task assignments that are in non-closed state.
Note also that if a task field is a rollup source, task values will be added to sub-entities' values if they all have the same rollup target field name. Tasks are never rollup start_date or end_date sources.
Workflow Execution and Notifications
Starting with the September 2022 release, a rollup target modification does not trigger workflow (i.e., edit action) execution, webhook pushes and notifications. Modification of rollup source fields do, but not the system update to the rollup target field(s). This is in line with cascading field updates, which do not trigger workflows, webhook pushes and notifications either at the cascading field destination(s).
For example, modifying a flight-level rollup source will trigger an EDIT workflow action on the flight workflow, along with any configured webhooks and notifications for the modified flight. However, if a rollup target at the line item level is modified as a consequence, an EDIT action is not executed on the line item workflow, and there are no line item webhook pushes and notifications at that time.
Interactions
With cascading fields
As mentioned in the Configuration section, a rollup target field cannot be a cascading field destination. However, it can be a cascading field source. This allows sub-entities to see the rolled up value.
For example, if a line item field called publicity_budget rolls up to an order-level all_line_item_budgets, then this field can cascade down to a line item field called total_line_item_budgets, which is visible on line items for information purposes. In this example:
-
publicity_budget is a rollup source (line item level)
-
all_line_item_budgets is both a rollup target and a cascading field source (order level)
-
total_line_item_budgets is a cascading field destination (line item level)
Also as mentioned above, a rollup source cannot be a cascading field destination (to avoid infinite update loops).
With calculated fields
Rollup sources cannot be a calculated (or calculated-override) field. This is to avoid infinite update loops.
Rollup targets cannot be either, since they are incompatible. (Would you use the formula to compute the value or add the rollup sources?)
Parent fields
Rollup sources cannot have parent fields, for technical reasons. It would in theory be possible however, but it would be an enhancement with significant development effort. They can however be parent fields themselves.
Rollup targets have no parent field limitations,. They can both have a parent or be a parent themselves.
Editable fields
For rollup targets, the editable field parameter has no effect and rollup targets are always treated as read-only fields. There are no specific interactions for rollup sources.
Required fields
Rollup sources can be required or not, there is no specific interaction here.
Rollup targets can be marked as required (the front-end does not prevent it), but this configuration is not valid since the user cannot directly update rollup target fields.
Flight and line item to order date validation
Adding or updating a flight or line item start_date or end_date is subject to validation against the order’s start_date and end_date. However, if those new or modified dates affect the order’s own start_date/end_date (i.e., if the flight dates roll up to the order level, via the line item, or if the line item dates rollup to the order level), then this validation is disabled.
This is necessary because otherwise it would be impossible to expand the range of the flight or line item dates outside the existing order date range, effectively freezing the order’s start_date/end_date range to what it was the first time it was set.