Dispatch custom action event (Form designer)
The behaviour type Dispatch custom action event (Form designer) triggers a Custom action event and therefore Event handling, which refers to this custom action event as a triggering event
The following sections explain details of the following mechanisms:
Providing data from the form for the event
Return data of the behaviour
Executing actions
Providing data from the form for the event
With regard to the provision of data from the form, the following cases must be distinguished:
If no element is linked, the entire form data is transferred to the event.
If an element is linked, its element data is transferred to the event.
If the element data relates to an entity, such as a business object, a company account or an address, then this appears as the input value for the event.
If the element data is an anonymous data structure, it is made available to the event via the Variable formData.
By default, the value Parameter (see screenshot above) also provides any input data ($input) for the event, so that the $input can be accessed in Event handling using a Variable (value) with the same name. Using the same methodology, further data or calculation results from the context of the form can be bound to the event by adding further parameters (and corresponding variables) by clicking on the related (+) symbol.
Return data of the behaviour
With regard to the return data of the behaviour, the following cases must be distinguished:
If an event is transferred as a data object with an entity as input value, this data object is returned to the behaviour, including any changes made by all Event handling.
If the entity is the data object to which the calling data entry screen refers to as a whole, the return data is automatically loaded as form data so that the form reflects this changed status. However, this is only carried out if data has been changed. As a result, the triggering event Form data loaded and 'context changed' is activated for the form.
If an entity is transferred to the event from a linked element that does not comprise the entire reference object of the form, its data is returned to the behaviour, including any changes made by Event handling, but is not automatically loaded into the form. However, they may be included in the form data (e.g. in the case of a business object item) using the Populate element data action.
If an anonymous data structure was transferred to the event by element linking (and the formData variable), the value of this variable is returned to the behaviour including the changes by all Event handling called, if applicable. This data can then, for example, be assigned within the form using the action Populate element data.
►NOTE◄ The transferred data structure can be modified by Event handling and then mapped back to the linked 'source element' by an action, for example. Or a completely new data object is created as a return value by the event handlers (e.g. by Create instance), which is set to another form element.
Which data is passed on to the actions can also be controlled by the optional Results expression parameter. The content of the storage is available as a database, i.e. a list of all variables from the context of the event, which are assigned values via parameters with behaviour, either by assignments within Event handling or automatically.
If a Result expression is defined, it determines the return value of the behaviour. Examples:
The result expression $input returns a data object that contains all storage, so that any action can access the values of all contained variables.
The result expression {value} returns the input data (i.e. $input) which was present when the behaviour was triggered, including any changes due to Event handling.
If no Result expression is defined, the following case distinction applies to the return value:
If an entity as input value was transferred, then the standard result expression {entity} is applied in a similar way, so that the possibly edited data of the entity is transferred.
If an anonymous data structure was transferred, then the standard result expression {formData}, is applied in a similar way, so that any edited or replaced content of this variable is transferred.
Executing actions
If all triggered Event handling are processed without errors, the Actions on 'true' with the return data of the behaviour ($input) are executed. If necessary, the Results expression is taken into account, as described in the previous section.
If an error (exception) occurs during event processing (usually due to the Abort), the Actions on 'false' with the error object (Fault) as input data ($input) are executed.
►NOTE◄ To analyze the error structure, the action Log to console is a useful tool.
Examples
The application possibilities for a Custom action event in combination with the triggered Event handling are extremely diverse. In the following examples, different combinations for the use of Dispatch custom action event (Form designer) are presented, without describing all the details of event handling and master data. In an abstract way, the examples illustrate the following applications:
Example 1: Calling the behaviour from an input form with the complete data of the entity displayed there (Shipment). The data is changed by the event and automatically copied to the form.
Example 2: Calling the behaviour from an input form with the data of a certain position as entity (shipment position). The data is changed by the event and then set as element data by the action.
Example 3: Calling the behaviour with an anonymous data structure acquired in a portal. The data is changed by the event and then set as element data in the portal by the action.
Example 1: Transferring header data from an interactively selected shipment to initialize another
In an entity form for Shipments, certain header data for the shipment (see screenshot below: Shipment type, Service type and Mode of transport) are transferred from another existing shipment at the push of a button. It should be possible to select the shipment after clicking on a Button by making an interactive selection from a list of shipments with specific restrictions (e.g. timescale for 'Created').
Runtime example:
Clicking on the Button '... copy from existing shipment' opens a specific shipment overview for selection (see Select from overview behaviour):
Confirming the selection with the 'Commit' button in the ribbon closes the shipment overview and transfers the data of the shipment into the input form.
If there are already data entries for the Shipment type, Service type and Mode of transport fields for the selected shipment in the overview, these are copied into the input form for the shipment.
Configuration:
The following configurations are assumed for the behaviour type configuration discussed below and are not discussed in detail:
Creating the shipment overview for selecting the shipment to be used as a template (see Custom overviews) and setting up the data grid settings for the list.
Creating a custom action event (in the dynamic enumeration Custom action event) with the name 'Initialize shipment header'.
|
Behaviour for selecting the shipment for which the data is to be transferred: |
|
|
|
For the Button in the input form, the behaviour shown on the left is first configured to enable selection of the shipment for which the header data is copied to the current shipment:
|
|
Behaviour for the transferring of header data by a custom action event |
|
|
|
The behaviour shown on the left is also configured for the Button to initialize a shipment header:
|
|
Event handling for the transfer of header data |
|
|
|
For reasons of space, the configuration for event handling is shown here in two sections. The first section (left) shows the Triggering events (here only the custom action event 'Initialize shipment header') and the Checking rules:
Only if both rules are fulfilled, are the Actions shown in the second section (below) executed. These are three similarly configured actions of the Set value type, which transfer the values of three fields from the shipment header of the selected shipment transferred by value to the shipment header of the shipment transferred as input value from the input form according to the same scheme:
|
|
|
|
Example 2: Lookup details for a shipment in the line items of a corresponding purchase order
Based on Orders received via the interface, Shipments are created for delivery, the shipment items of which are created with reference to order line items, however this is not mandatory. To facilitate this, the input form for shipments offers a lookup function that can be started by pressing F2 after a string has been entered in the 'Goods description' field. This string is then searched for as part of the 'Goods description' of the items in the corresponding purchase order. Alternatively, the four-digit reference number of a purchase order item can be entered in full. The first match is used to fill certain shipment item fields ('Order line item reference', 'Number of packages', 'Goods description'), which can then be edited if necessary.
Runtime example:
Here the views for order and shipment details have been arranged above each other.
The input form for the shipment details already contains 'suitable' search terms for the order line items. The following screen appears after pressing F2 in the respective field:
Configuration:
As in the previous example, two behaviours are linked to implement the lookup process.
|
The behaviour for adopting the 'Receipt No. Reference.' (in the shipment form) for lookup purposes |
|
|
|
For the Text field 'Goods description', the behaviour shown on the left is configured:
|
|
Behaviour to look up the order line item via a custom action event |
|
|
|
This behaviour is also configured for the same Text field and shown on the left. Since it is triggered exclusively by the above behaviour and by the Execute behaviour action, the Triggering event (not in the screenshot) remains empty.
|
Within event handling, which is not described in detail here, the Variable value can be accessed during lookup to determine the corresponding purchase order by a Search (Event action). The Direct line items can then be evaluated with a Rule list resolver to search for a match for the value in the Text field 'Goods description'. Once a suitable order line item has been determined, the desired properties or attribute values are transferred to the shipment line item entity via Set value, which is the input value for the event.
Example 3: Registration of 'Membership accounts' entered in a portal by assigning a number range value
In a portal, a list of 'members' (identified by the fields First name and Last name) should be entered, for each of which a unique member account number should be assigned in a common 'registration run', which is taken from a range of numbers. The process could initiate further steps, such as printing membership cards, sending notifications, etc., but these are not described here.
Runtime example:
|
|
|
Configuration:
|
|
For the Register Button, the behaviour displayed on the left is configured.
|
|
|
The event handling for the custom action event 'Register account' is configured as shown on the left:
|
