Event action – Abstract

Purpose: Fills barcode attributes of line items of a general business object with values from a number range. Optionally, the number of barcode attributes within a line item is synchronized with the 'Number of packages' of the same line item by adding or removing barcode attributes, if necessary

images/download/attachments/78255453/image2021-8-20_21-36-35-version-1-modificationdate-1629488199610-api-v2.png

Barcode attributes background

At the item level of business transaction objects, the 'barcode attribute' can be assigned as a multiple attribute, if necessary, several attribute instances with the fields 'barcode' (barcode) and "barcode reference" (barcodeReference). The same item can therefore have multiple barcode values.

CAUTION There must be no duplicates for the value in the 'Barcode' field within the barcode attribute instances for a given line item, otherwise saving the transaction object will fail with an error.
This is true even if for several barcode_attribute_instances of the same item the 'Barcode' field is empty.

The Generiere Barcodes (Allgemeines Geschäftsobjekt) event action can be used to maintain barcode uniqueness by populating each empty 'Barcode' field with unique values from a number range. Event handling that reacts to the triggering events 'Create' and/or 'Modify' (see Common action event) allows missing barcodes to be added in time before the transaction is completed when clicking on 'Save'.

The Generiere Barcodes (Allgemeines Geschäftsobjekt) event action generates barcodes via a specific Number range type (see Number range) in order to assign these 'empty' instances of barcode attributes to relevant line items of a reference object of the Allgemeines Geschäftsobjekt type as 'barcode' (barcode).

Relevant line items can alternatively be defined using one of the following methods:

The Line items parameter allows an explicit definition of the relevant line items via a Wertauflöser that provides a list of Line items (e.g. Direct line items and/or Rule list resolver).
The Line item types parameter defines one or more Line item types by multiple selection (see Line item type). All line items that belong to a selected Line item type are considered to be relevant.
If no information is available for any of these parameters, all line items with the Line item type 'Default' (DEFAULT) are considered relevant.

All relevant line items are processed according to the following schema:

If the Sync barcodes with number of packages option is selected in the Generiere Barcodes (Allgemeines Geschäftsobjekt), the number of barcode attribute instances within the line item is matched to the 'number of packages' (numberOfPackages):
1. If the line item currently contains more barcode attribute instances than the Number of packages field specifies, then 'excess' instances of the barcode attribute are removed from the end of the list. It does not matter if they are already assigned barcodes.
2. If the item currently contains fewer barcode attribute instances than the Number of packages field indicates, then additional instances of the barcode attribute are added to the list at the end.
All barcode attributes contained in the item whose 'Barcode' (barcode) field is empty are assigned an automatically generated value depending on the specified Number range type.

►NOTE◄ Which of the Number range configured for the selected Number range type are used to generate barcode values depends on the evaluation of their Association criteria according to the best-matching principle.

►IMPORTANT◄ If no number range is assigned for the Number range type for the call context or the assigned number range does not provide any more values, some or all 'Barcode' fields will not be populated. If this results in barcode duplicates for the same line item, the reference object cannot be saved in this state (see 'Barcode attributes background', above).

Configuration

The Generiere Barcodes (Allgemeines Geschäftsobjekt) event action expects a Allgemeines Geschäftsobjekt as the reference object. In the context of another object type, the event action has no effect without an error occurring at runtime.

The selection for the Number range type parameter (required field) controls which Number range are candidates for generating barcode values. The selection is made by association according to the best-matching principle (see Association criteria).

The Sync barcodes with number of packages option can be selected to ensure that the number of barcode attribute instances exactly matches the 'number of packages' (numberOfPackages) of the line item for all relevant line items. Based on the given 'Number of packages' line items, 'surplus' barcode attribute instances are removed or 'missing' ones are added as required for this purpose and automatically assigned a barcode value from the applicable number range.

The Sync barcodes with number of packages option is deselected by default. Then the 'Barcode' field – if empty – is only filled for barcode attribute instances that already exist in the volatile data of the reference object.

images/download/attachments/78255453/image2021-8-20_21-36-48-version-1-modificationdate-1629488210996-api-v2.png

The Line items parameter can be used to explicitly define, via a Wertauflöser, relevant line items whose barcode attributes are processed by the event action.

In the example on the right, all direct line items for the Line item type 'Service' are determined via the Direct line items value resolver.

►NOTE◄ The result for the selection of relevant line items is identical to the selection of 'Service' in the Line item types parameter (see below) only if the reference object for this Line item type does not contain any child items. Otherwise, child items are not processed because the Direct line items value resolver does not list them.
As soon as a Wertauflöser is configured for the Line items parameter, the Line item types disactivated parameter appears. It becomes active again only when the Wertauflöser in the Line Wertauflöser parameter is removed.
The parameter can only be configured if no Line item types (see below) have been selected yet.

images/download/attachments/78255453/image2021-8-20_21-37-50-version-1-modificationdate-1629488273738-api-v2.png

Alternatively, the Line item types parameter can be used to define relevant line items whose barcode attributes are to be processed by the event action in a blanket manner via their Line item type.

In the example on the right, the Line item type 'Default' has already been selected. In addition, the Line item type 'Service' is selected, which was looked up in the image using the search function of the Multiselect combobox. This selection must be confirmed by pressing the enter key or by clicking on the symbol.
A selection for Line item types is only possible if no explicit definition of the relevant line items is configured under Line Items.
As soon as a selection is made for one or more Line item types, the configuration for the Line items parameter is deactivated.

►NOTE◄ Only if there is neither a configuration under Line items nor a selection under Line item types, all line items with the Line item type 'Default' (DEFAULT) are considered as relevant.

images/download/attachments/78255453/image2021-8-20_21-38-22-version-1-modificationdate-1629488304991-api-v2.png

Example

Simple example

When saving a general business object, a barcode attribute is automatically generated at line item level for the Line item type 'Default' for each package and filled with a value from a number range set up for this purpose.

As the following screenshot illustrates, the input form allows changes to the Number of packages of a line item. In addition, new line items can be added by and removed by .

images/download/attachments/78255453/image2021-8-20_21-39-18-version-1-modificationdate-1629488361546-api-v2.png

Already generated barcodes appear read-only in the 'Barcode' field. However, an existing barcode attribute instance can be deleted altogether by clicking on the associated symbol again.
The number of barcode attribute instances per line item can therefore differ from the 'Number of packages'. Before saving, any surplus barcode attributes should be deleted and any missing ones added.

Configuration:

Within an event handling that reacts to the 'Create"'and 'Modify' of a general business object (Typprüfung), one of the following configurations can be used for the Generiere Barcodes (Allgemeines Geschäftsobjekt) event action:

Variant 1	Variant 2	Variant 3

Variant 1: The relevant line items (all default line items) are determined overall based on the default rule for no configuration under Line items and no selection for Line item types.
Variant 2: The relevant items (all default line items) are determined overall based on the selection of 'Default' under Line item types.
Variant 3: The relevant items (all direct default line items) are determined explicitly using the value resolver of the Direct line items type.
►NOTE◄ Variant 3 is the same as the other variants only for reference objects that do not use child items for default line items.

Runtime example:

Starting from the data state for a general business object shown in the screenshot above, the following image appears after saving:

Before saving	After saving

There are no barcode attributes yet.	Barcode attributes were added to match the 'Number of packages' and filled from the addressed number range.

The general business object enhanced with barcodes is now revised once again in this way:

Before saving	After saving

The number of packages per line item is uniformly set to 2. The barcode of the first line item is removed by clicking .	In line item 1, a barcode attribute instance has been added. Both barcodes have been reassigned. Line item 2 is unchanged. In line item 3, the last has been removed.

More complex example

Based on the 'Simple example' above, it should be possible to create 'Service' line items in addition to 'Default' line items in the general business object.

The 'Service' line items are also automatically barcoded using the same Number range type ('Barcode'). However, with a slightly different logic:

There is no maintenance for the 'Number of packages' for the 'Service' line item.
A 'Service' line item optionally receives no, one or more barcodes, depending on how many instances the user interactively creates before saving.
When saving, a barcode should be automatically assigned to all barcode attribute instances in 'Service' line items IF the text attribute 'Service code' of the line item has been defined.
Without 'Service code' no barcode attribute instance should be able to be added to the 'Service' line item.
When removing the 'Service code' in a line item, existing barcode attribute instances are deleted.

Runtime example:

Two barcodes were requested for the 'Service' line item SER1.
Exactly one barcode is to be assigned to the 'Service' line item SER2.
The 'Service' line item SER3 does not receive a barcode. Here the symbol was not clicked. That is why the symbol appears inactive and the label 'Barcode' is black and not red.
No 'Service code' was specified for the 'Service' line item SER4. Therefore, no barcode attribute instance can be added.

images/download/attachments/78255453/image2021-8-20_21-46-34-version-1-modificationdate-1629488797051-api-v2.png

►NOTE◄ The symbols and in the last line item are related to adding/removing a line item and not a barcode attribute instance.

Configuration:

In the event handling from the previous example, another instance of the Generiere Barcodes (Allgemeines Geschäftsobjekt) is added and parameterized as shown on the right:

As the Number range type, the 'Barcode' type is selected, as above.
The option Sync barcodes with number of packages is deselected, since only existing attribute instances are processed.
The value resolver of the Input object (type safe) type is used to declare the type of reference object within the configuration for Line items.
The chained value resolver of the Direct line items returns all direct line items of the 'Service' Line item type.
The Rule list resolver below 'filters' this list to the subset of the line item for which the text attribute 'Service code' is not empty. This is done by selecting the Resolve all as list option and then using an Entity property rule that checks the 'Text' field (textValue) against not (Is empty).

►NOTE◄ The Rule list resolver can be used to define more complex 'filters'. Instead of Direct line items, the lineItems field of the reference object can also be used. Then the result list can also contain line items with different Line item type.

images/download/attachments/78255453/image2021-8-20_22-6-50-version-1-modificationdate-1629490013678-api-v2.png

Runtime example:

Before saving	After saving

For each position, several (SER1), one (SER2) or no (SER3, SER4) barcode assignments are expected when saving.	When saving, only the 'requested' barcodes were entered into the attribute instances.
In the same input form, both line item types can be used at the same time and literally 'side by side':