References and IDs are a crucial element of Arengu. With the editor, you can create complex server-side logic for your forms, which means you will need to connect several pieces of your form, like your users' data on the form with the corresponding actions.
If you are using Arengu's templates, the variables will be automatically referenced, and you will only have to edit the forms to your tastes. But, how to reference them when starting a form from scratch?
This is how to reference variables in Arengu, so you can connect all the data contained in the forms and in the flows.
Including variables in forms
You can add variables to the inputs with the plus button, simply by clicking on it, and also in the HTML field. You can recall variables from all the previous steps of the form and the flows that have already been executed.
To recall variables from a flow, simply use the ‘Store state variable’ action on the flow whose variables you want to store. You can learn more about it here.
The autocomplete variables menu
To make it unnecessary to remember or search the data structure of each variable, Arengu provides a menu to easily find and reference variables.
To open it, just click on the + button of the input in which you want to recall a variable. A panel, where you can search and add it, will be displayed.
To find the proper variable, first select the source: Forms or Executions, depending on where the variable you want to recall comes from.
Then, you can use the search bar to find it but, if you don't remember the ID, you can also find it by navigating the menu.
Under each source, the list of variables to recall is provided. Remember to select the form or execution that you want to use. By default, the most recent execution is shown but you can change it by clicking on the selector.
On the Executions list, variables are organized in two tabs, depending on whether they come from an action or if they are state variables. Once you have found the proper one, just click on the variable to add it to the input.
It is important to note that if you change the ID of a field or action, the data structure of the variables will be different.
In this case, execute the form and its flows again, and click the refresh button on the menu to start using the latest version of the references. Simply remember to replace the variables whose IDs have been changed.
Using variables in flows
There are three types of variables in flows that we can use and recall:
- Form variables, like the data that the user has input in the form.
- Flow variables, from the previous actions of the flow.
- State variables, like tokens, claim URLs or any other variable that we want to store from the flow.
Let's see how we can use and reference each of them.
Input variables: Referencing data from the form
Input variables may refer to many different concepts, depending on which context you use this term. In this case, input variables refer to data coming from the form fields, for example, what the user wrote in the form's fields.
Each form field has a unique ID that it is used to reference its value. When you click on any field of a form, a settings menu will open on the right side of the editor. Right after the field type, you will find it.
IDs are mandatory and they can't be deleted, but you can modify them to make them easier to find and reference.
To reference the values that come from the form, follow the structure {{input.body.field_id}} or {{fields.field_id}}.
Let's see an example. This is a multi-step form. The first step contains a registration form, while the second step contains a field to enter a verification code. The flows linked to this form include several actions, like the generation of a one-time password, an email sending the OTP, and the OTP verification.
To configure flow actions, you will need to reference form values, that is, what the user has input the form fields (email, password, OTP).
In this case, when you click on the email field, you will see the field ID is 'email'.
The flow connected to this step of the form includes the actions Generate one-time password and Send SendGrid email, to send the user an email with a one-time password in order to verify the identity.
To configure this action, just reference the value of the email field in the Recipient email input. That is, {{input.body.email}} or {{fields.email}}. That’s all!
Output variables: Referencing data from previous actions
Output variables correspond to IDs coming from previous actions of a flow.
Just like the fields of the form, each flow action has a unique ID. Click on any action of the flow, and a menu will open on the right side of the editor. The first field you'll see is the action's ID. It is mandatory too, although you can modify it if you want to simplify it.
To reference values that come from a flow action, follow the structure: {{action_id.output_variable}}
Let’s see an example with the same use case: the registration form that sends a one-time password to verify the user's identity. In this flow, there is an action to go to the next step of the form when the mail is sent or to display an error message in the form if there is any error when sending the email.
To configure this logic, we need to include an If/then condition action to check if the sending has been successful and to set a condition in this action. In this case, this action has to scan if there is an error or not after the email is sent. Therefore, reference the error output from the previous action.
How to find the output variables in the Executions tab
If you're not sure what the output variable should be, you could also find it in the Executions tab. After your forms have been submitted and the flows have been executed, go to Executions and inspect one execution. Click on Output to see the names of the outputs and just follow the data structure.
State variables: Referencing flow variables in forms
With the 'Store state variable' action, you can also define and save custom variables in flows and then use them in the following flows and steps of the form. For example, to configure or prefill fields.
Just add the action to the flow after the action which outputs you want to store and list the variables to store.
To set it up, define an ID for each custom variable in the first input and list the corresponding variables in the second one. You can get these variables from the autocomplete menu, by clicking on the plus button. Note that you need to run the flow at least once to have the outputs available.
To reference these new variables both in the form and the following flows, use the data structure {{state.variable_id}}.
You can use them, for example, to prefill the fields of a form by simply referencing the {{state.variable_id}} in the Default value input of its settings, as you can see in the previous example.
Just remember that the flow with the ‘Store state variable’ action has to be executed before that step of the form or the flow in which you are going to use those custom variables.
Allow references: Referencing external data in actions.
This option allows you to reference data that may be stored in a different actions, variables, external APIs or URLs.
Keep in mind that the data being referenced must be formatted to match the payload of the action.
Use case 1: Display dynamic messages
Referencing values is necessary to connect form's fields to flow actions, but you can also use them to display dynamic messages to your users.
In this use case, we are sending a one-time password to the user who provided the email address in the first form step. To do so, just reference the OTP variable in the email.
To find this variable, simply check the outputs of the Generate one-time password action. As you can see in the screenshot above, it is referenced with the output variable format: {{generateOtp.code}}.
Here, generateOtp is the ID of the previous action, while code is the output variable of the action that includes the code.
Use case 2: Configure form fields
Another of the uses that our variables system allows is to use them to configure form fields, for example, to build dynamic payment forms.
In this use case, we have a two-step subscription form. In the first step, it asks the user for an email, password and to choose a subscription plan, and in the second, the user will be able to pay for the chosen subscription plan.
In the first step of the form, we have included an Email field, a Password field and a Cards field to allow the user to choose one of the pricing options.
In the second step of the form, we have included the Payment field that will charge the user the amount that he chose in the cards.
To configure this, we just have to reference the {{fields.cards}} variable in the Price ID field, to automatically get the price that the user has chosen.
Note that the form variables that we want to recall must be input in a step prior to the one in which we want to configure the field.
Good to know
- Field IDs consistency. If you change a form field ID, remember that you'll have to change it accordingly in the flows. In future releases, it will be possible to automatically change all references. For example, if you have a form field ID which is fullName and you want to rename it to name, you need to replace {{fields.fullName}} with {{fields.name}} in all the flow actions you are using it.
- Action IDs consistency. Same happens with flow action IDs: if you change one and you're using it in another flow action, remember to update the references. As an example, if you have a flow action ID with generateOtp and you rename it to generate_otp, you will need to replace {{generateOtp.code}} by {{generate_otp.code}} in all flow actions you are using the output code.
- Check the available variables on the menu. Remember you can use the autocomplete variable component by clicking the + icon on the right side of an input field. You'll see a list with all the variables you can reference from your form and all previous flow actions outputs.
- Refresh the autocomplete menu after modifying IDs. If you have made changes and you cannot find the variable you are looking for, run the flow again and click on the refresh button on the menu to update it.
- Check the debugger mode. If you click in the Executions tab inside your flow editor, you will find a detailed debug mode with all input/output/errors of all your executed flow actions and you can easily identify variable references or errors.
Always use the same style to represent variables. We love using the Camel case. This case style combines words without spaces, and capitalizes only the first letter of the words, except for the first word. For instance, if we want to name an action ID with ‘generate OTP’ we use generateOtp.
Functions
You can do calculations and transform data in your flows with these functions. Just remember to enclose them in brackets {{ }} to make them work properly.
For example:
The value (1234) of a number input field with id 'units' can be converted into a string
{{ toString(input.body.units) }} = '1234'