Process variables
Using process variables¶
We have already seen in an example Expression(read-only) Question how an expression with parameters is evaluated at runtime. In addition to the input and output parameters, process variables can also be used between process steps and in the survey forms. With these variables we can control the flow of the process, for example assigning the activity to a specific agent or repeating a step a certain number of times etc. A list of the process variables and how they can be used can be found under Documentation in the SurveyJS Creator, see the next image. They are variables related to agents, instances, nodes and execution that are internally necessary to the process during execution. For the correct functionality, the following user guide of the process variables must be strictly followed when entering into the survey.
The earlier direct use of the process variable (e.g. ${Node.name} as title) in survey question is deprecated and should no longer be continued.
Agent variables¶
Due to a change in date and time formatting, the former ${Agent.dateFormat} and ${Agent.timeFormat} process variables are no longer needed and are removed from the process variables. Locale-specific formatting is now done in the browser corresponding to the browser's language. Since the date and time are now always in ISO format, the uniqueness of this information is guaranteed, regardless of the time zone in which the individual process steps are carried out. However, compatibility with older versions can no longer be supported because the two variables ${Agent.dateFormat} and ${Agent.timeFormat} are no longer used. The current supported process variables are as follows:
Instance variables¶
Node variables¶
Execution variables¶
Using Process variables in SurveyJs Forms¶
SurveyJs Creator offers custom variables in which we can integrate our process variable. To use process variables in survey forms, you must first define them as a custom variable under Conditions and then reference these variables from individual questions.
Process variables as custom variables¶
The process variables defined under Custom variables can be used throughout the survey. For that, select the survey in the top right corner of the Creator and enter the name of the process variable (optionally with a corresponding expression) in the Survey / Conditions under Custom Variables. We enter the process variables exactly as they are specified, just without the dollar sign and curly brackets, eg ${Node.id} ->Node.id, ${Agent.userName} -> Agent.userName etc. The name of the custom variable must exactly match the name of the process variable and it does not need to be assigned an expression. In fact, it doesn't matter which expression you assign to this variable, since the current value of the process variable is automatically assigned at runtime. For this reason, the preview in Survey Creator cannot provide the corresponding values and only displays the unresolved name of the variable. For example, if a constant is assigned to the expression, the constant is displayed in the preview and a test for resolution becomes possible. However, if the process variable is declared incorrectly, it cannot be evaluated and will also be displayed at runtime as in the preview. For an example with expressions in SurveyJs see the chapter Example Expression(read-only) question.
Reference to process variables¶
After declaring the process variable, you need to reference it in the question to show its value. As with usual variables in SurveyJs, you also need curly brackets for the reference of these variables. For example to display the node name as the title of the question enter {Node.name} in the title of the question. To assign the value of the process variable to default value of the question, you have to enter it in the Conditions -> Default value expression of the question.
Example: Title and default value¶
In the next example, the name of the process step is used as the title for the form. To do this, we define the variable Node.name under custom variables and then enter it in title of the survey.
To display the username as the default value of the question, after the declaration under custom variables, we enter the following expression {Agent.userName} in the Default value expression of the question.
As result, you can then see the node name as the title of the survey and the username as default answer from the question at runtime.
Process variables in conditional logic¶
In order to make the functionality of the survey elements dependent on the process variables, we can use the variables defined in custom variables in the conditional logic of the question. For more information on conditional logic in SurveyJS, see the documentation ⧉. By adding conditions to the logic of the question, we can make the question visible, editable or required according to the entered expression with the process variable. For example, if the current node id is '2', then the question is mandatory and editable. To do this, we need another auxiliary variable that evaluates the expression with the already defined process variable. In this example, we first define the process variable Node.id then another variable var1 which evaluates to true, if the Node.id has the value '2'.
After that we add the var1 under the condition Disable the read-only mode if and Make the question required if of the question. This then results in the question1 being editable at runtime and mandatory if the node id is '2'.
Form master¶
Processes often go through steps in which information is recorded, checked and supplemented. As in the previous section, we can pass this information to the elements of the survey using the process variables, so that at runtime a survey looks different at each step, although it is always the same. We call this type of survey a form master, because it contains all input fields and information for the entire process but adapts to the respective step in the course of the process. This form master, created in one process step, can be inserted into other process steps via copy/paste form from the context menu. In this way, all forms get the same appearance when modeling in the Process Template Editor and we can make changes in one central place. A form master can be created by showing or hiding multiple survey elements. For a small example using process variables in a form master, see the tutorial Hide/Show parts of the form.