Definition of the reference object

In the simplest case, the current reference object is the entity defined by the data context of the event handling.

However, there are also event actions (e.g. Execute with or For each loop) that can temporarily override the current reference object at runtime. The configuration of such event actions provides a defined block for event actions to be executed in the context of the alternative reference object. At runtime, the alternative reference object is considered the current reference object for these event actions, as can be traced via the value of the variable entity, if applicable. Within such an action block, the event action Save changes later also refers exclusively to the entity temporarily defined as the reference object.

Within an event action that provides for an alternative reference object, Resolvers can usually be used to define a specific reference object:

• The data object of an entity can possibly be resolved directly via a Variable or an Object property.

• Often the value resolver Input object (type safe) must also be used, e.g. to retrieve the data object of an entity starting from a reference to its ID (e.g. Linked entity type or Linked line item type).

• The Create instance value resolver can also be used to create a new reference object and edit it as part of the transaction. Then the event action Save changes later 'later' causes the creation of the entity in question.

►IMPORTANT◄ The action should be performed only with independent entities as reference objects and not, for example, with attributes or positions of business objects. No corresponding check takes place at runtime, and executing the event action for a related object that cannot actually be stored (interactively) on its own may lead to unexpected results when the transaction is completed.

Flag to save

The flag to save takes into account the logon context (company, role, user) applicable at the time of execution of the Save changes later event action, which may be defined at runtime as a temporary alternative from the current session by the Run as event action.

• If the event action Save changes later is executed multiple times within the same transaction for the same reference object, the flag only takes into account the logon context of the last execution.

• The determining logon context affects the checking of permissions and – if applicable – the value assignment for entity attributes when saving (see below).

The fact that saving is not directly triggered by executing the event action Save changes later also causes the following effects:

• If a rollback (by a Abort or a 'real' process exception) is triggered for the same transaction after executing Save changes later, the 'save later' is omitted and any pending changes are lost.

• The time of execution of the event action for a specific reference object within the same transaction is irrelevant. All changes to the reference object within the transaction are taken into account cumulatively when saving is to be performed.

• Repeated execution of the event action for the same reference object within the same transaction has no effect, unless different logon contexts are used (see above).

Execute save

The flag to save is taken into account only when the current transaction is completed. If one of the marked reference objects would not be saved by the transaction anyway, an attempt is made to save it explicitly. If this attempt fails because an error message occurs, the transaction as a whole is considered a failure and a rollback is performed. The following aspects must be considered in this regard:

• The logon context applicable in the course of the flagging (see above) must have sufficient permissions for the reference object ('Change' or 'Create' for new instances).

• If the system checks content requirements for the entity type of the reference object (required disclosures, uniqueness of characteristics or combinations of characteristics, etc.), the reference object should meet them by the time the transaction is completed.

• Executing the event action Save changes later in the Try block of a Try/Catch actor does not result in catching errors that occur 'later' (when saving).

►IMPORTANT◄ If upon completing the transaction the same entity is flagged to save as well as flagged to delete (see Delete later), the save-flag is disregarded completely.

►NOTE◄ Saving objects is generally not supported in the context of Tests for event handlers. However, when the event handler is triggered while running a form in test mode, Save changes later may effectively update or create entities.

Example

A Custom action event 'Save business object' is triggered in the context of various Input forms when a specific business object is to be saved automatically. The data context for the Dispatch custom action event (Form designer) behaviour type can be either the form data (or the entity displayed in the data entry screen) or the data of an embedded form (see Embed forms (Sub-forms)), with the data of an additional entity loaded into the form.