Event action – Abstract

Purpose: Memorizes the current reference object for 'export', i.e. transfer to a Lobster_data profile, at the end of the transaction.

images/download/attachments/189438746/image-2024-11-20_9-46-0-version-1-modificationdate-1732092360799-api-v2.png

The Export event action flags the current reference object for 'export', i.e. transfer to a Lobster_data profile, at the end of the transaction. Details on the processing of these flags are described in the section 'Processing diagram for flagged exports' (below).

When the profile is called, the data status of the respective earmarked reference object at the time the transaction is completed is transferred as input data (XML).

►NOTE◄ If the reference object is a new instance of an entity that has not yet been saved, the input data for the profile therefore already contains the ID (id) automatically assigned by the system as the primary key.

Information about the applicable logon context (company, role, user) is automatically assigned to the MSG_CALL variables predefined in profiles – as is usual for profile calls from Lobster Data Platform / Orchestration. These are automatically filled with values at runtime depending on the session's logon data and, if necessary, taking into account adjustments made by the Run as event action:

Data object	Value	Variable name (in Lobster_data`)`	Data type (in Lobster_data)
Company of session	ID (`id`) of the company account	MSG_CALL_SCM_Company_id	`BigInteger`
Company of session	Company account data object as XML (text)	MSG_CALL_SCM_Company_xml	`String`
Role of session	ID (`id`) of the role	MSG_CALL_SCM_Role_id	`BigInteger`
User of session	ID (`id`) of the user account	MSG_CALL_SCM_User_id	`BigInteger`
	Username (`username`)	MSG_CALL_SCM_User_username	`String`
	User account data object as XML (Text)	MSG_CALL_SCM_User_xml	`String`

Optionally, value assignments can be configured for further Variables to pass additional data to the called profile.

Processing diagram for flagged exports

►IMPORTANT◄ Since the profile is not called immediately during Export, no return value of the called profile can be expected and processed in event handling, in contrast to the call via Call profile (Event action).

If the triggering transaction is not completed successfully due to an Abort or an error, all profile calls that may have been flagged will be dropped.

Only when a transaction is successfully completed will all exports marked in the course of this transaction be triggered according to the following processing scheme:

Step 1: Profile views before commit	If available, those profile calls that are marked without the option Execute after commit are triggered first. The relevant profile calls are triggered in the same order in which they have been flagged in the course of the transaction. If the Synchronous profile call option is set for a profile call, any subsequent profile calls are not triggered until this profile call has been completely processed. If the Synchronous profile call option is not set, the subsequent profile call, if any, is triggered immediately. If multiple profiles are triggered non-synchronously, Lobster_data arbitrarily decides on their processing order.
Step 2: Commit	Commit saves manipulations made to entities within the transaction in the Lobster Data Platform / Orchestration database, so that they are taken into account by subsequently executed profile calls, for example, when executing a Search.
Step 3: Profile views after the commit	If available, the profile calls that have been marked with the Execute after commit option are triggered after the commit. Proceed with the relevant profile calls as in step 1.
Step 4: End of the transaction	A transaction in Lobster Data Platform / Orchestration, in which at least one Export has been flagged, ends – after successful processing of all related event handlings, if the following conditions are met: All synchronous profile calls were triggered and processed by Lobster_data. All asynchronous profile calls were triggered.
Step 4: End of the transaction	CAUTION If an Export is marked within a 'write' transaction in the context of an entity that is read or write accessed by a triggered profile, a dead-lock at the database level may occur if the Synchronous profile call option – as in the default – is selected and the Execute after commit option – as in the default – is deselected. Because in this scenario, the calling transaction in Lobster Data Platform / Orchestration waits for the profile to be processed before the commit, which in turn waits for the commit before executing the read or write access (e.g., by a Search or an Import). Effectively, this results in an acute blockage of the database table(s) concerned, which can only be resolved by terminating the blocking database sessions via an administrator's access.

Configuration

images/download/attachments/189438746/image-2024-11-20_9-46-40-version-1-modificationdate-1732092400458-api-v2.png

The Profile name parameter identifies the profile to be called up. Existing profile names are suggested in a drop-down list via 'Auto complete' to match the entry in the text field.
►NOTE◄ Unlike the configuration of behaviours such as Call profile in the Form designer, access to profiles in event handlers is not tied to Profile securities.

Options for sequence control

The Synchronous profile call option is selected by default. It decides whether the processing of the profile calls is embedded in the transaction or not.

'Synchronous profile call'	Runtime behaviour
	A 'Synchronous profile call' must be completely processed before subsequent profile calls flagged for the same processing step (before/after commit, see above) are triggered. If the transaction was triggered interactively, the icon in the window title of the relevant view rotates until the transaction is completed.
	An 'asynchronous profile call' is only triggered, i.e. passed to Lobster_data for processing, without subsequent profile calls flagged for the same processing step (before/after commit, see above) having to await processing. If several asynchronous profile calls are triggered by the same transaction, Lobster_data can process them in parallel. The order of triggering is then non-binding for the processing order.

The Execute after commit option is not set by default. It defines whether the marked profile calls are to be executed before or after the commit of the transaction when it is completed..

'Execute after commit' option

Runtime behaviour

The profile call is executed after the commit (see step 3 in the 'Processing diagram' above).
Manipulations to entities (creation, modification, deletion) that were made in the course of the transaction are then taken into account, for example, when a Search is performed in the profile call.

The profile call is executed before the commit (see Step 1 in the 'processing diagram' above).
Manipulations to entities (Create, Modify, Delete) that were made in the course of the transaction are then not taken into account, for example, when a search is performed in the profile call.

►NOTE◄ The reference object passed to the profile as an input value, on the other hand, includes manipulations to the reference object within the transaction even without a commit.

Variables

The Variables section offers a Repeatable element in which value assignments for variables can be defined via the and symbols.

The assignments for these variables apply only to the context of the profile call.
A variable must be defined in the profile that uses the prefix MSG_CALL__ before the entry for the Variable name.
The value resolvers configured for the Value parameter are resolved at runtime at the same time the Export event action is executed. However, the note below must be observed when a data object is assigned as the value to the variable!

images/download/attachments/189438746/image-2024-11-20_14-42-36-version-1-modificationdate-1732110156228-api-v2.png

As the example of the second Variable name attachment in the image illustrates, the option Send as file may also appear depending on the return value type of the resolver.

If the Send as file option is set, then the return value of the resolver is not assigned directly to the variable, but a path specification to a temporary file into which the corresponding content is written when the profile is called. After the profile call, such temporary files are automatically deleted again.

►NOTE◄ If a variable in Lobster Data Platform / Orchestration is assigned a data object as a value, then the variable only stores a reference to this data object and not, for example, a snapshot of the data. Only at the time of the profile call, when the value is assigned to the MSG_CALL variable of the profile, is the data object output as an XML text and therefore 'frozen'. Changes to the data object through event actions that are executed after the Export but still within the same transaction therefore always also affect the value of the profile variable during the Export. However, the profile variable can be assigned a snapshot of a data object at the time the Export event action is executed, if required, by the value resolver passing the data object via concatenation, e.g. to the Object to server xml value resolver, in order to immediately assign the returned XML as a text value to the variable that is later passed to the profile.

Examples

Simple example

Whenever a shipment newly entered in Lobster Data Platform / Orchestration is created, i.e. saved for the first time, its data is transferred via a profile call to a transport management system (TMS) connected via Lobster_data.

From the point of view of Lobster Data Platform / Orchestration, this process is an 'export' that addresses an import interface of the TMS via the specially set-up Lobster_data profile. In the present case, it is assumed that no immediate feedback or confirmation of delivery from the TMS is expected for the new creation, which would have to be processed synchronously in Lobster Data Platform / Orchestration.

Configuration:

For the Triggering event 'Create' (see Allgemein (Ereignisse) an event handling is configured as shown on the right.
The Validating rule uses Check type to ensure that the Export is executed only when Shipments are created.
As an Action on passed rule, the Export event action is configured as shown below. The Profile name of the addressed Lobster_data profile PRO2TMS_NEW_SHIPMENT calls up a Synchronous profile call, but should be executed before the commit. So both option settings correspond to the default. Additional Variables are not used.

►NOTE◄ By the fact that the Synchronous profile call is called up, the user can see when the transfer of the data via the profile has been completely processed.

images/download/attachments/189438746/image-2024-11-20_14-44-39-version-1-modificationdate-1732110279353-api-v2.png

More complex example

Whenever an existing shipment is changed to Lobster Data Platform / Orchestration (i.e. saved again after creation), each shipment item should be transferred individually and depending on its tracking status to a specific interface to the Transport Management System (TMS).

If, from the shipper's perspective, the tracking status of a shipment item is final ('Ready to ship' or 'Canceled'), the profile PRO2TMS_LINE_ITEM_FINAL is executed.
With all other tracking states, a shipment item is still considered volatile, i.e. not finally defined. Then the profile PRO2TMS_LINE_ITEM_VOLATILE is executed.
In both cases, the profile should receive the entire data object of the shipment as input data, while the decisive shipment item should only be identified by specifying the internal id as the value of a variable itemId (in the MSG_CALL_itemId profile).
For technical reasons on the TMS side of the interface, the 'volatile' positions must be passed strictly in series and the given order, while the 'final' positions may follow in any order and only afterwards.

Configuration:

Based on the Triggering event 'Change' (see Common action event), the Validating rule uses Check type to ensure that the following Actions on passed rule are only executed for shipments.

Then a For each loop is executed via Direct line items of the 'Default' type, where the shipment from the input value of the event handling is stored in the shipment variable.
Within the loop, If then else evaluates the case distinction between 'final' and 'volatile' tracking status codes for the respective shipment item.
In both branches (Then/Else) of the case distinction, this is followed by the call of the Export event handling, within an Execute with event action, which temporarily moves the reference object for the Export from the shipment item to the parent shipment. The shipment item is stored in the lineItem variable so that its id can be assigned as the value of the itemId variable during Export under Variables.
The Export for the 'volatile' positions (in the Else branch, bottom right) is configured with the Synchronous profile call option and without the Execute after commit option, so that the corresponding profile calls occur in series and before those for 'final' positions.
The Export for the 'final' items (in the Then branch, bottom left) is configured without the Synchronous profile call option being set, but with the Execute after commit option, so that any corresponding profile calls are triggered after the commit and therefore the processing of all synchronously executed profile calls for the 'final' items. Without the Synchronous profile call option being set, these profile calls are triggered almost simultaneously. Afterwards, the transaction ends from the perspective of Lobster Data Platform / Orchestration, without waiting for the profile calls to be processed.