Dispatch UI – sending a command to the user interface¶
The command "Dispatch UI" sends a named command to the user interface of the user running the action – for interactions that no other command covers, such as a short notification, reloading the page or opening the spotlight search. This page is for administrators who build interactive actions.
1. At a glance¶
| Purpose | Trigger a function of the user interface from an action |
| Typical use | Show a notification ("toast"), go to the home page, reload the page, redraw all forms, put the cursor into a field |
| Where in the editor | Toolbar menu "UI" → "Dispatch UI" |
| Needs a user interface | Yes |
| Needs a current record | No |
| Related | Show Popup, Navigate, quick action "Home" |
2. Settings¶
The settings are on the tab "General", below "Display Name", "Description" and "Execution Condition" (see Actions).
| Setting | Meaning | Default / Required |
|---|---|---|
| "Action" | The command for the user interface, chosen from a list of technical names, for example DisplayToastAction, GoHomeAction, RequestPageReloadAction, RerenderFormsAction, FocusInputBlockAction, OpenSpotlightSearchAction, OpenGlobalSearchAction, ToggleLeftAppBarAction |
Required |
| "Payload Example" (button) | Shows the data the selected command expects, in a dialog "Example Payload for …" | – |
| "Payload" | Expression that computes the data of the command as a JSON object. Use {} for a command without data. |
Required |
The list also contains commands that open editors and administration pages (for example
LoadAdminStudioAction). They are meant for administrative tools; ordinary users should not get
buttons that use them.
3. Behaviour¶
- Without a user interface or without "Action", the command is skipped.
- The payload expression is evaluated against the current record.
- The user interface looks up the command by name (upper and lower case do not matter) and builds it from the payload. Properties are matched by name.
- If the name is unknown, or the payload is empty or not valid JSON for this command, nothing happens; a warning is written to the log. The action continues in every case.
- The action waits until the user interface has taken the command and then continues. It does not wait for what the command starts (for example a page reload).
4. Examples¶
Notification after saving. After Save:
| Setting | Value |
|---|---|
| "Action" | DisplayToastAction |
| "Payload" | Text expression {"Message":"Invoice created","Severity":2} |
A short notification "Invoice created" appears. Severity controls the colour and the icon: 0
normal, 1 info, 2 success, 3 warning, 4 error. Notifications with a value above 2 stay
visible a little longer.
Notification with its own image. The optional Image takes the result of an
image expression – an icon or a picture – and shows it instead of the
icon of the severity, for example {"Message":"Saved","Severity":2,"Image": followed by the image
expression and }. Without Image the notification shows the icon of its severity.
Cursor into a field. After a check found a missing value:
| Setting | Value |
|---|---|
| "Action" | FocusInputBlockAction |
| "Payload" | Text expression {"TargetRefId":"<id of the field>"} |
The cursor is placed into the input of the form that shows this field. Instead of the id of the field, the id of the input block can be used. If the field is on a tab that is not selected, in a collapsed accordion item or in a folded stack, that tab or item is opened first. If the field is shown more than once, the one in a dialog is preferred, then the one the user can already see.
Back to the start page. "Action" GoHomeAction, "Payload" {}. The quick action
"Home" does exactly this without a stored action.
5. Limitations¶
- The names are technical and not translated. Use "Payload Example" to see which data a command expects.
- Errors in the payload are only written to the log; the user sees nothing.
- Commands that reload the page end everything that runs in the page – place them last.
FocusInputBlockActiononly reaches input, date range input, radio button, button and related items selector blocks that are shown and not disabled; buttons and selectors only by the id of the block. A field that is hidden by its visibility condition or sits on a disabled tab cannot be focused; nothing happens then. Tabs of dashboards are not opened.