User prompt

Value resolver – Abstract
Purpose: Requests text input from the user in an interactive context via a modal prompt.
Tooltip
Usage: The value resolver opens a prompt in an interactive context, taking into account the parameters described below, allowing the user to enter text.
When the input is completed with the OK button (or – for the Prompt type 'Single-line text' – with the 'Enter' key), the text entered is returned.
After the maximum waiting time (Timeout (s)) has elapsed, the value is returned if the Timeout value has been exceeded.
In a non-interactive context (e.g. profile call), the Timeout value is returned immediately without waiting.
When clicking the optional Cancel button, 'No value' ($null) is returned.
Parameter: The Title, Message, Default value, and Timeout value text parameters can be specified statically by direct entry or defined by value resolvers at runtime.
The Title and Message parameters define the output text for the corresponding areas of the prompt.
The Default value optionally defines text with the input area of the prompt preset.
The Timeout value defines the return value in the event that the maximum waiting time (see Timeout) expires without 'OK' or 'Cancel' being clicked, OR the value resolver is executed in a non-interactive context.
The Prompt type parameter defines which type of input should be offered in the prompt.
The User resizable and Full screen parameters affect the behavior of the prompt window in terms of its size.
The Can cancel option decides whether the prompt offers a button to 'Cancel' the prompt with the return value $null.
The Timeout (s) with a default value of 30 specifies the maximum number of seconds the prompt will remain open before returning the Timeout value.
►CAUTION◄ Entering 0 seconds is possible, but causes a timeout after 60 seconds. However, settings >60 seconds are explicitly accepted.
Note: The Clear button in the prompt replaces the value in the input area with an empty string rather than 'no value' ($null).
Important: This resolver is not available in a Client Workflow!

images/download/attachments/201662080/image-2025-3-14_8-33-34-version-1-modificationdate-1741937614410-api-v2.png

►IMPORTANT◄ This resolver is not available in a Client Workflow!

The User prompt value resolver requests a text input from the user in an interactive context via a modal prompt, which usually defines the return value of the value resolver.

Exceptions:

If no input is made by the user within the waiting time parameterized as Timeout (s), the prompt is closed and the Timeout value is returned.
If Can cancel is checked, then when the user cancels the prompt, the value resolver returns 'no value' ($null) rather than the Prompt type or the Default value.

►NOTE◄ If there is no interactive context, e.g. because event handling was triggered by an Import profile, then no prompt can follow. In this case, the Timeout value (and not the Default value) is processed as the return value without any waiting time.

Runtime examples:

Single-line input area with Cancel button:

images/download/attachments/201662080/image-2025-3-14_8-36-30-version-1-modificationdate-1741937790046-api-v2.png

Multiline JSON input area:

images/download/attachments/201662080/image-2025-3-14_8-39-10-version-1-modificationdate-1741937950368-api-v2.png

The Clear button removes all text from the input area. However, when the OK button is clicked, the prompt will still return an empty string (''), which is not the same as 'no value' ($null).
Even after manually removing all entered text characters from the input area, an empty string ('') remains.
So the input area returns 'no value' ($null) exactly when either the optionally offered Cancel button has been used or 'no value' ($null) is present as the Default value at runtime and no input is made until the OK button is clicked.
For the Prompt type 'Single line', pressing the Enter key is equivalent to clicking the OK button. If clicking OK without input should be distinguishable from clicking Cancel, (at least) an empty string should be preset as the Default value, otherwise 'no value' ($null) would be present.
For the ‘JSON’ Prompt type (example below left), specific highlighting and a syntax check take effect in the multi-line input area with line numbers.
- In the example, the error icon marks a non-compliant line (no. 1). When hovering over it with the mouse cursor, a tooltip appears with more information (here: Unexpected: '/')
- A comment is not permitted in JSON ( /* ... */ ), but is nevertheless highlighted.

Configuration

The input value is only relevant as a reference object for value resolvers in parameters.

The Title, Message, Default value, and Prompt type value text parameters can be specified statically via direct input or defined via value resolvers at runtime.

By default, the direct input is active (see Message in the following screenshot), from which it is possible to switch to the value resolver definition by clicking on the small gray arrow at the bottom right of the text field.

The Title parameter defines the text for the window title of the prompt by direct input or (see example) by value resolver.

The Message parameter defines the message text of the prompt by direct input (see example) or by value resolver.

The Default value parameter defines the text with which the input area is pre-populated when the prompt is opened.

The Timeout value parameter is assigned when the user has not exited the prompt by either entering or 'Canceling' by the time the maximum waiting time defined by the Timeout (s) parameter has elapsed.

The selection for Prompt type defines the format for the input area in the prompt ('Single line', 'Multiline' and other options similar to the Text field) form element).

The User resizable option defines whether and, if so, in which dimensions (width, height) the prompt window can be resized by drag and drop in the bottom right corner. If resizing is allowed, then the mouse cursor icon changes in this area:

With the Full screen option checked, the prompt automatically fills the entire view slot in the context. The window size cannot then be changed regardless of the selection for User resizable.

With the Can cancel option, the prompt offers the 'Cancel' button in addition to the default buttons ('Clear' and 'OK'), which can be used to terminate the prompt with a return value $null.

The integer for the Timeout (s) parameter defines the waiting time in seconds in an interactive session after which the prompt is automatically cancelled. Then the Timeout value parameter defines the return value.
- By default, the Timeout (s) is preset to 30 seconds.
- With a Timeout (s) of 0 seconds, a timeout is triggered after 60 seconds.

images/download/attachments/201662080/image-2025-3-14_8-42-27-version-1-modificationdate-1741938146823-api-v2.png

Example

Certain Working state values (such as 'Completed', 'Canceled', etc.) should permanently terminate the life cycle of business objects of the 'Shipment' type. If one of these terminal working states is assigned in an interactive workflow, the user is given the opportunity to enter a 'Final remark' in the 'Reason' (reason) field of the added working state entry. Detailed requirements for this:

If a text for the 'Reason' (reason) has already been predefined in the context of the workflow, this should appear as the 'default value' so that it can be revised, supplemented or completely replaced or deleted by the user if necessary.
The user should be given the option to rollback the entire transaction by clicking the 'Cancel' button in the prompt, thus preventing the change to a terminal work state.
If the user does not make any entries within 5 minutes, the prompt is closed and the working state change including the predefined 'Reason', if any, takes effect.

Runtime example:

images/download/attachments/201662080/image-2025-3-14_8-44-7-version-1-modificationdate-1741938247392-api-v2.png

Since English is the official language for handling shipments, the English text GOODS_RECEIPT confirmed is automatically set as the 'Reason' when confirming the receipt of goods for a shipment. Appropriately, the 'Title' (internal name for the target working state) and the 'Message' for the prompt should also appear in English as an exception.
The user can make entries in any language of choice, but should be made aware of the English 'Address' and the default setting that English content is actually expected.
On the other hand, the prompt button labels appear for the session's Current locale.

Configuration:

Before discussing details of the User prompt value resolver, an overview of the solution approach is explained using the configuration shown for an event handler:

Triggering events must be selected for all relevant working states, i.e. those from the Working state (Events) category that are triggered when a working state is added to any entity that is considered a 'terminus' for Shipments in the context of the example.

The Validating rule uses Check type to ensure that actions are only performed when one of the relevant working states has been added to a 'Shipment'.

As an Action on passed rule, an Execute with event action is used to set the working state entry referred to by the shipment in the 'Current working state (currentWorkingState) field as the reference object for all further event actions:

The Set value event action assigns the return value of the prompt opened via the User prompt value resolver to the 'Reason' (reason) field in the current working state entry.
As shown in the image, any terminal whitespace characters (spaces, line breaks, etc.) previously entered by the concatenated Right trim value resolver are removed from the return value.
Subsequently, an If then else event action determines whether the value for the 'Reason' field is 'No value' ($null). This is exactly when the event processing in whose context the event handling was triggered at runtime is cancelled altogether and a rollback is executed.

images/download/attachments/201662080/image-2025-3-14_8-48-30-version-1-modificationdate-1741938509924-api-v2.png

The User prompt value resolver is configured as shown on the right:

The Title is defined by the Triggering event value resolver, which returns the internal (in general English) name of the event as a string mapping.
The FINAL REMARKS? text is defined for the Message by direct input.
The Default value is first read by an Object property value resolver from the 'Reason' (reason) field, which may contain pre-populated text.
The concatenated Default value resolver here explicitly defines an empty string ('') in case there is no 'Reason' (value $null in the reason field) yet. So the input area of the prompt always appears at least one empty string as Default value. The concatenated Store value as variable value resolver writes the effective Default value to the default variable, since the same value applies as the Timeout value.
The Timeout value is taken from the default variable.
The remaining settings define a prompt with an input area for multiline text (Prompt type), for which Resize is not allowed and which – including the optional 'Cancel' button (Can cancel) – is displayed for a maximum of 300 seconds (Timeout (s)).

►NOTE◄ With this configuration, the prompt returns $null only if the 'Cancel' button was pressed by the user. The Right trim value resolver then passes $null unchanged.

images/download/attachments/201662080/image-2025-3-14_8-49-59-version-1-modificationdate-1741938599407-api-v2.png

The Entity property rule within the downstream If then else event action explicitly checks the 'No value' (as a comparison value) per Equals to detect an abort executed by the user.

If this condition is met, an Abort event action is executed, which notifies the user in a warning about the rollback.

►NOTE◄ A check via Is empty would not be suitable here, because this would also be passed for the empty string (''), which is returned with the configuration above if the user does not react until the 'Timeout', confirms an empty default value via 'OK' or enters text and this is removed again via 'Empty' and then confirmed via 'OK'. However, according to the requirement in our example, the rollback should only be triggered by clicking 'Cancel'.

images/download/attachments/201662080/image-2025-3-14_8-51-21-version-1-modificationdate-1741938680588-api-v2.png