Action variables – passing values between commands¶
Variables carry values from one command of an action to the next: the answer of a popup, the result of an HTTP request, a number computed once and used three times. This page describes how variables are declared, how long they live, how values get in and out of an action, and which special variables nexxcite provides. It is intended for administrators who build actions.
1. Variables at a glance¶
| Kind | Declared | Written by | Read by |
|---|---|---|---|
| Variable of the action | Tab "Variables" of the action | Update Variable and every command with a "… Variable" setting | Expressions of type "Variable" |
| Input parameter | A variable with "Input Parameter" on | A caller: Execute Action, the REST API, a mail form | Like any variable |
| Output parameter | A variable with "Output Parameter" on | The action itself | The calling action after Execute Action, the REST API |
| Special variable | Provided by nexxcite | The trigger of the action (mailbox listener, business rule, …) | Expressions, once enabled in "Enabled Special Variables" |
Summary¶
- Variables have no type and no default value. A variable starts empty and holds whatever was last written into it – a text, a number, a date, a JSON text.
- A variable lives for one run of the action. Pre commands, main commands, post commands, loops and switch cases share it.
- A called action has its own variables. Values go in through input parameters and come back through output parameters.
- Commands refer to a variable by its identity, not by its name – renaming a variable does not break the commands that use it.
2. Declaring variables¶
Select the start symbol of the action and open the tab "Variables". The add button creates a variable; each variable has:
| Setting | Meaning | Default |
|---|---|---|
| "Name" | The name shown in the drop-downs of the commands and in the expression editor | Empty |
| "Input Parameter" | A caller may hand in a value | Off |
| "Output Parameter" | The value is handed back when the action has run to completion | Off |
The remove button next to a variable deletes it. Commands and expressions that used it keep their setting, but find nothing: reading returns an empty value, writing has no visible effect. Check the commands before you remove a variable.
Declare every variable a command is meant to write into – a command cannot create one by itself.
3. Writing and reading values¶
Writing¶
- Update Variable writes one or several variables, each with a value expression and an optional condition.
- Many commands write their result into a variable you pick, for example "Button Response Variable" of Show Popup, "Dialog ID Variable" of Open Form Dialog, or the response variables of HTTP Request.
- The loop commands for JSON, XML, files and file lines write the current element into a variable for every pass.
Reading¶
Expressions in the action read a variable with the expression type "Variable". The expression editors of an action offer:
- the variables of the action,
- the special variables switched on in "Enabled Special Variables",
- the output parameters of the actions called with Execute Action, named
<Action>.<Variable>, - in a custom action written for a particular place, the values that place provides.
A variable that was never written reads as an empty value. Because variables have no type, the expression that reads one converts the value as needed – see Expressions.
Example: A popup asks "Approve or reject?" with two buttons whose results are approve and
reject. "Button Response Variable" is "Decision". A following Switch has
the case "Approved" with the condition "Decision = approve".
4. Lifetime and scope¶
| Situation | Variables |
|---|---|
| Pre commands, main commands, post commands of one run | Shared |
| Commands inside a loop or a switch case | Shared with the rest of the action – a value written in the loop is still there after it |
| Action called with Execute Action | Its own variables. It receives the arguments and the special variables of the caller; its output parameters come back after it ran to completion. |
| Action that runs against a group of records | The same variables for the pre commands, every record and the post commands. A value written while processing one record is still there for the next one. |
| Next run of the same action | Starts with empty variables |
Variables are never stored. To keep a value beyond the run, write it into a field of a record or into a global value.
Example: An action runs against the query "Open tasks" (12 records). The pre commands set the variable "Count" to 0. For each record, Update Variable sets "Count" to "Count + 1". The post command writes "Count" into the log: 12.
5. Input and output parameters¶
Handing values in¶
| Caller | How |
|---|---|
| Execute Action | Tab "Arguments": one entry per input parameter of the called action, with a value expression evaluated in the calling action |
| REST API | params in the request body. The keys can be the id or the name of a variable (not case-sensitive). |
| Mail form (Open E-Mail Form) | Arguments of the action that runs on send |
"Input Parameter" marks a variable for callers – the Execute Action command only offers those. It is not enforced: a caller that hands in nothing leaves the variable empty, and the REST API accepts any variable of the action, also one without "Input Parameter".
Handing values back¶
When an action with output parameters runs to completion, their values are handed back:
- to the calling action after Execute Action – they appear in its
expression editors as
<Action>.<Variable>; - to the REST API caller that waited for the result, in
output.
If the called action ends early or fails, nothing is handed back to a calling action.
6. Special variables¶
nexxcite fills special variables depending on how the action was started. Switch the ones you want to use on in "Enabled Special Variables" (tab "General" of the action); that only makes the expression editors offer them.
| Special variable | Filled when | Content |
|---|---|---|
| "Event Based Action Data" | A background business rule started the action | The change that triggered the rule, as JSON |
| "Entity Set Changed Data" | The action is the history action of an entity, started after every save | What was changed, as JSON |
| "Send E-Mail Metadata", "Send E-Mail Attachments" | The action runs when a mail form is sent | The edited mail (recipients, subject, body) and its attachments, as JSON |
| "Received E-Mail From Address", "… To Addresses", "… CC Addresses", "… BCC Addresses", "… Subject", "… Plain Body", "… HTML Body", "… Importance", "… Has Attachments", "… Attachments", "… DateTime" | A mailbox listener started the action | The parts of the received mail |
| "Search Field Content" | A search field widget started the action | The text the user entered |
| "AI Chat Message", "AI Chat Identifier", "AI Chat Message Direction", "AI Chat Message Timestamp", "AI Chat Message Event Data" | The action keeps the history of an AI chat | The message and its details |
| "Action Iteration", "Action Iteration Total Records" | The action runs against a group of records | Position of the current record (from 0) and number of records |
Special variables are handed on to actions called with Execute Action.
7. Recommendations¶
- Give variables a default at the start of the action (or in the pre commands) with Update Variable, if later commands rely on a value.
- Name variables after their content – "Invoice total", not "var1". The name is what other administrators and the AI assistant work with.
- Check error variables of integration commands before you use their result: an HTTP request that failed leaves an empty body, which a later command would happily write into a record.
- Use output parameters instead of writing intermediate results into records when a sub-action only computes something.
8. Limitations¶
- Variables have no type and no default value.
- There are no variables that live longer than one run.
- "Input Parameter" is not checked: an action cannot require a caller to provide a value.
- In a run against a group of records, values carry over from one record to the next. Reset variables at the start of the commands if each record needs a fresh value.