Event action – Abstract

Purpose: This function aggregates, for one or more Line item types in a common business object, the individual values for a selected Numeric types in a Source Level of the line item hierarchy to calculate subtotals for the line items of a parent Target level. The subtotals are assigned as a value (value) to the (aggregated) numeric attribute of the same number type in the Target level.

images/download/attachments/78255455/image2021-8-24_20-25-47-version-1-modificationdate-1629829550629-api-v2.png

The Sum numeric attribute event action creates subtotals for the numeric attribute values for exactly one Numeric types selected by Type within the item hierarchy of a reference object of the Allgemeines Geschäftsobjekt type.

For each line item of a selectable Target level (target item), a subtotal is determined that combines all single values from a selectable subordinate Source level. The summary of single values from the direct or indirect sub line items is assigned as a value to the aggregated numeric attribute for the same Numeric types at the Target level. A value existing at the target item will be overwritten. The subtotal is rounded or not depending on the setting for the Decimal places parameter.

CAUTION If the subhierarchy below a certain target item does not contain any values in the Source Level for the Numeric types to be summarized, then the value 0 is assigned for the target item.

Source level and Target level can be identified in either an absolute or relative way to the lowest hierarchy level (see 'Configuration'). Under certain circumstances, the header level of the reference object can also serve as the Target level.

►NOTE◄ Regardless of whether absolute or relative references are used, the Target level must effectively always be above the Source level, otherwise no aggregation takes place.

The Line item types parameter defines by multiple selection a positive list for the line item types relevant for the aggregation. Without specifications for the Line item type, only line items of the 'Default' (DEFAULT) type are considered relevant.

The Sum numeric attribute event action processes only the volatile data of the reference object and does not save it.

Specific variants of this event action are provided for the entity types Orders and Shipments, which work according to the same principles.

Configuration

The event action Sum numeric attribute expects a Allgemeines Geschäftsobjekt as the reference object. In the context of entities of other types, the event action has no effect without an error occurring at runtime.

As a required field, the Type statically determines by single selection the Numeric types of the attributes whose values are to be summed up.

The Target level parameter uses a positive or negative integer index to define the hierarchy level for which subtotals are to be calculated:

Value> 0: absolute level; number of levels below the header level.
Value< 0: relative level; number of levels above the 'lowest level' (per Line item type).
Value= 0: 'Header level' of the reference object (see note below).

The Source level parameter uses a positive or negative integer index to define the hierarchy level in which to search for single values for the Numeric types:

Value> 0: absolute level; number of levels below the header level
Value< 0: relative level; number of levels above the 'lowest level' (per Line item type).
Value= 0: 'lowest level' (per Line item type).

Decimal places defines if and how the total is rounded:

Value= 0: No rounding.
Value> 0: Number of decimal places for rounding the single values before summing up.

The relevant Line item types for the calculation can be qualified by multiple selection.

images/download/attachments/78255455/image2021-8-24_20-26-21-version-1-modificationdate-1629829583787-api-v2.png

►NOTE◄ In Lobster Data Platform / Orchestration, each Line item type creates an independent line item hierarchy, so that the subtotals always summarize only single values for the same Line item type. If several Line item types are selected as relevant, then the entire event handling calculation procedure is repeated sequentially for each relevant Line item type. Therefore, the following aspects have to be considered:

If the Source level and/or the Target level is defined relative to the 'lowest level' of the line item hierarchy, the 'lowest level' is determined individually for each Line item type. The aggregation then concerns individual levels per Line item type.
If the Target level refers relatively or absolutely to the header level of the reference object, then each processed Line item type on this level uses the same numeric attribute for the selected Numeric types as the target item. This will be overwritten again and again, and the result will show only the partial total for the last processed Line item type. This is usually not desirable. A total sum over different Line item types at header level cannot be calculated with the event action in this way.

Example

A common business object is to be used to collect data for 'Investment proposals for energy optimization' in a company.

The structure of the proposal provides an outline of the 'line items' of a proposal in four levels, as shown in the following screenshot.

images/download/attachments/78255455/image2021-8-24_20-22-58-version-1-modificationdate-1629829381253-api-v2.png

Levels 1 to 3 in this scheme refer to a Numeric types 'Costs' (COSTS) to budget the respective item in the unit 'T€' (1000 euros) to budget.
In levels 1 and 2, the numeric attribute in question is used exclusively for aggregation. In the image, the element is still empty and therefore hidden.
Only level 3 is used to enter 'Costs', which are to be added upwards when the application is saved. The total costs at header level (top right) are then also updated.
Level 4 is not yet used in the example. It is used for the optional entry of 'Details' for a line item of level 3, to which no individual 'Costs' should be assigned.

For the input in the unit 'T€' (1000 euros), level 3 provides three decimal places so that the entry can be made to the nearest €1. When summarizing, however, these amounts are rounded to one decimal place, i.e. with an accuracy of 100 €. However, each aggregation level refers to the rounded 'raw data' from level 3 and not the subtotals from the next subordinate level.

Configuration:

Within an event handling that is triggered each time a request is 'saved', i.e. via the events 'Create' and 'Modify' (see Common action event) with a corresponding Typprüfung, the event action Sum numeric attribute must be configured three times for this purpose.

Each step of the aggregation refers to the Type (Numeric types) 'Cost" (COSTS).
The Target level varies, with the positive integers interpreted as an absolute indication of the target level:
- The first step summarizes the rounded 'Costs' from level 3 in the immediate parent item level (2).
- The second step summarizes the rounded 'Costs' from level 3 in the highest item level (1).
- The third step summarizes the rounded 'Costs' from level 3 as a total in the header of the application.
The Source level is always level 3, with the scalar values to be added.
Decimal places is also set to 1.
Under Line item types the used Line item type 'Service' (SERVICE) is selected uniformly.

►NOTE◄ The calculation results are entered by the event action in the respective Target level as the value of the 'Cost' attribute, which is also newly created as usual if it does not yet exist in the volatile data of the reference object.

images/download/attachments/78255455/image2021-8-24_20-28-21-version-1-modificationdate-1629829704427-api-v2.png

Runtime example:

The example on the right shows the calculation results for a concrete investment proposal with seven line items provided with costs on level 3.

Since the input fields for 'Costs' in levels 1 and 2 show three decimal places of the calculated value, the rounding to one decimal can be read there.

►NOTE◄ The values in the concrete example show the special influence of the rounding of single values before summing up within the position SER2.1:

The single items in the sub-items are rounded up by one decimal when rounding (from 18.858 to 18.9 T€ and 12.567 to 12.6 T€), which results in a subtotal of 31.5 T€ for SER2.1.
Adding up without rounding would result in a subtotal of €31.425 thousand, which, when rounded to one decimal, would result in €31.4 thousand after addition.

In view of the single values, this valuation of the aggregated position could be considered more appropriate than the value of €31.5 thousand determined with the rounding of the single values. However, in the example, there would then be a difference between the addition of the reported interim results for SER2.1 (in the amount of 31.4 T€) and
SER2.2 (in the amount of 16.1 T€), which results in a total of 47.5 T€, and the value for item SER2 (in the amount of 47.6 T€) determined by rounding after adding up all individual values.
Rounding before the addition therefore ensures that any summation over several levels results in a consistent set of numbers. And this is independent of whether the summation is performed continuously in steps or – as in the example – also partially over several steps.

images/download/attachments/78255455/image2021-8-24_20-18-47-version-1-modificationdate-1629829130069-api-v2.png

►NOTE◄ The buttons '1', '2' and '3' in the header of the data input form created for the example can be used to select the level of detail of the display.

In the screenshot on the right, the sub line item level 3 has been hidden by clicking the '2' button, so that only the aggregated figures (deactivated) are visible.

images/download/attachments/78255455/image2021-8-24_20-37-9-version-1-modificationdate-1629830232515-api-v2.png