See also: Open portal (Behaviour type), Open view (Action)

Event action – Abstract

Purpose: This opens a portal to which a data object can be passed and optionally waits for the return of a data object.

The Open portal (Action) event action opens a portal to which a data object can be passed and optionally waits for a data object to be returned.

images/download/attachments/177911770/image-2024-9-17_14-57-46-version-1-modificationdate-1726577865754-api-v2.png

Configuration

The configuration of the Open portal (Action) event action covers a wide range of application scenarios and therefore offers numerous parameters. These are presented below in a table and grouped by focus. The right column of the table always shows the relevant section of the configuration dialog.

Selection or definition of the portal to be opened
The portal to be opened can either be selected under Portal name or provided as XML structure via the parameter Portal XML. If only the Portal name parameter is used, then the selected portal will open – if it exists, has been published at least once, and is applicable at runtime (see Association criteria, Company authorizations). If, on the other hand, the Portal XML parameter is used to provide the XML structure for a portal definition (see `master` field of a Portal entity) as a direct text input or as a return value of a resolver, then the corresponding portal appears at runtime. The Portal name parameter can then be used to override the default title ('Portal') in the portal. In doing so, the opened portal may also inherit the relevant help context (see Online help).	►NOTE◄ By clicking on the gray arrow at the bottom left of the input field for the Portal XML parameter, it is possible to switch from direct input mode to the definition of a value resolver.
Data association for the portal to be opened
The value resolver in the Entity parameter defines a data object that is passed to the portal to be opened as form data if no Prepare profile is selected. If a Lobster_data profile is selected by Prepare profile, it is called synchronously with the data object as input data in SERVER XML format, waiting for a response from the profile in a selectable Profile output format (JSON, SERVER, CLIENT, TEXT, CSV, BYTE_ARRAY), which the portal to be opened receives as form data.
Data return from the portal (optional)
The optional Name of result variable can be used to specify the name of a variable that can be used to access return data from the opened portal, provided that: The Wait time value return >0 (unit: seconds) is configured. And the Request close action is executed in the portal at runtime before this waiting time expires. If the Wait time (>0 seconds) elapses without Request close being executed, the portal is automatically closed and the return data is empty. If, on the other hand, the value 0 (default) is set as the Wait time, event processing is continued immediately after the portal is opened and without waiting for return data.	►IMPORTANT◄ The Wait time must be >0 for the portal to be called 'synchronously' at all. Only then will return data from a Request close action be waited for in the portal. If the portal is closed without executing the Request close data action, the result variable remains empty. (see the Closable option below).
Display behaviour of the portal
If the Modal option is not checked (default), the portal should appear in a standalone view when opened. Then the Unique option decides whether the portal will be opened even if (at least) one instance of the portal is already open non-modally – i.e. as a standalone view. If the Modal option is checked, the portal will be displayed within the current view when it is opened. The Unique option will then be ignored. Additional options also appear in the configuration: The Full screen option decides whether the opened portal fills the current view in full screen or appears as a dialog box within this view. If this option is unchecked, additional settings for the size are displayed (width, height, minimum width and minimum height). The specifications are to be given in pixel measure. The selection for Resizable only applies to the display as a dialog (not Full screen). The Closable option can be unchecked to prevent the title bar of the modal window from displaying the 'X' symbol to close the modally displayed portal. This is recommended if return data is expected from the portal. Clicking the 'X' icon otherwise closes the portal without executing the behaviour with the Request close action that is supposed to provide the return data.

Example

Display'detailed information' on demand

In the following example, a portal is used to display certain detailed information on request in a dialog box when the user performs a certain action.

Specifically, the user of an overview for business objects is shown details of the user who last changed certain business objects in a 'business card' form.

Runtime example:

images/download/attachments/177911770/image2021-3-11_7-27-32-version-1-modificationdate-1726576983627-api-v2.png

The 'business card' should display a text concatenation of the values from the 'user name' (username) and 'Name 1', 'Name 2' and 'Name 3' fields from the address of the user (address.name1/2/3) who last modified the business object in question.

The text field below should display the 'Name 1' from the address of the company that owns this user account.

In addition, an Image/Icon element (on the left) should reflect the user's profile picture (see Change profile picture), if one has been uploaded.

The portal call should be controlled by a Custom action event in an event handling, so that it can be triggered by different actions (e.g. by clicking into a 'Custom column' of the overview or a ribbon macro).

Configuration:

After creating a Custom action event named 'Whois' (`WHOIS`), it can be assigned to an event handling as a Triggering event. A Check type is selected as the Validating rule, which is based on the type of Business transaction object, which is superior to all business objects. The 'business card' can be displayed with this configuration for Orders, Shipments, Manifests as well as for a Common business object. Since the portal is supposed to combine a few pieces of information from different entities (user and company accounts), these are then first 'assembled' and passed in variables: Within an Execute with event action, the user account whose ID is noted in the 'Last modifier' (`lastModifierId`) field of the business transaction object is first set as the reference object. This enables a concatenation of the Object property and Input object (type safe) value resolvers (not expanded in the image). Afterwards, the relevant field values from the Users account are transferred to a string variable (`name`) via Set value, which is optionally possible via the Concat strings or Template value resolver. Another Execute with event action then changes the related object again to the company account specified as the 'owner' (`ownerID`) of the user account. This in turn allows a combination of Object property and Input object (type safe) value resolver. In the context of the company account, the 'Name 1' (`address.name1`) field is transferred from the address to a string variable (`company`).
Now another Execute with event action follows, whose Object resolver creates a new 'Client object' as a reference object via the Create instance value resolver. This data structure, which is undefined in terms of type and content, is then assigned the fields and values that the portal expects through a series of Set value event actions: The `function` field fills the heading (see 'Last modifier' above), which should clarify the 'function' of the user in relation to the business object. The value can be entered as static text or, even better, assigned via a Value from localization value resolver. The `name` field defines the first text field in the portal. The value that was previously compiled from characteristics of the user account and stored in the `name` variable will appear here. The `pic` field defines the URL for the image in the portal. This feature can be taken directly from the `avatarURL` field of the user account, which can be accessed via the `user` variable (see Save User in variable parameter). The `context` field defines the second text field in the portal. The name of the company that owns the user account appears here. This name was stored in the `company` variable in the last Execute with event action in the previous section.
The 'Client object' contains – with the data from the runtime example – the data structure shown on the right in JSON format.	`{` `"function": "Last modifier",` `"name": "Q - ☺ Karola Mustermann",` `"context": "Xflow AG",` `"pic": "img://avatar/user_avatar_1901.png?c=1583340638977"` `}`
This data is still passed to the portal within the same Execute with event action: The Portal name identifies the portal to be displayed, whereby ultimately Association criteria determine whether this happens in a particular context and which portal, from several possible, appears with the name `WHOIS`. The Portal XML parameter and the Prepare profile are not used. No value resolver is configured for the Entity, so the current reference object – here the ad hoc generated 'Client object' – is passed to the portal as form data. The Wait time parameter ensures that the displayed 'business card' is automatically closed again after 5 seconds. A value return from the portal is not provided. Therefore, the Name of result variable remains empty. The Unique option is set by default, but has no effect in connection with the selected Modal option. Since the modally opened portal blocks any new interactive triggering event within the same view until it is closed, it cannot be opened a second time by the user in this constellation. The portal should appear as a dialog (not in Full screen), the size of which cannot be changed. The Closeable option allows the user to click the 'X' icon in the upper right corner of the dialog title to close the 'business card' before the waiting time (see above) has expired.