What is a Request Variable?
Understand how ProcessMaker uses variables in Request data.
ProcessMaker uses two types of variables, both of which appear in Requests. Request variables represent placeholders for Request data that change as the Request routes through its Process.
ProcessMaker uses a set of global variables that become part of each Request. ProcessMaker uses these Magic Variables to store user, Process, and Request related data for all Requests. During an in-progress Request, these Magic Variables are updated. See Reference Magic Variables in ProcessMaker Assets.
The interactive fields in a Screen are called controls. Examples of these controls are the Line Input, Checkbox, and Date Picker controls. Many of these controls have a setting called Variable Name, which represents the content entered or stored in that Screen control. Request variables have the following attributes:
- The Variable Name setting represents a variable name.
- The value of that Request variable is one of the following:
- The information the Task assignee enters into a control using that variable name, which then becomes part of the data for that Request when that Task assignee completes the Task.
- During a Request, the value of that Request variable is replaced by another Request variable, a Script, a third-party data source, or a Magic Variable.
Therefore, every Request variable has two components:
- Name of the Request variable: The name of the Request variable is how that Request variable is referenced anytime during a Request from ProcessMaker assets such as Process models, Screens, Scripts, and Data Connectors.
- Value of the Request variable: The Request variable contains a value. Some Request variables can require a specific data type, such as whether a setting accepts only alphanumeric characters, integers, a date-type format, or currency. Alternatively, the Request variable value may contain one of the following values:
- Null: The value null means that Request variable contains no value.
true: The valuetrueis a positive state of the Boolean data type for that Request variable, such as when a Checkbox control in a Screen is selected.false: The valuefalseis a negative state of the Boolean data type for that Request variable, such as when a Checkbox control in a Screen is not selected.
Below are a few ways to use Request variables:
- Read a Request variable: A Screen may be designed to read information that has been entered in a different Screen during the same Request. To read a Request variable, the Screen designer references the Request variable name; during a Request, the value of that Request variable displays in any Screen control that uses that Request variable name, which was likely defined in the Variable Name setting of the control from which the Screen designer intends to read its value. Therefore, this requires coordination between Screen designers who work on different Screens in your organization to define names for Request variables. Alternatively, the Vocabularies package helps address this problem.
- Replace the value of one Request variable from another: Similar to reading a Request variable, a Request variable's value may be replaced by another Request variable's value. See Example.
- Store the value of a Magic Variable to a Request variable: The value of a Magic Variable can replace that of a Request variable. For example, store a Magic Variable's value at a particular time during a Request for later reference elsewhere in that Request since the Magic Variable's value may change as the Request continues.
- Replace the value of a Request variable from a third-party data source: Using a Data Connector to access data from a third-party data source, such as an Application Program Interface (API), get the value from a specified resource, and then replace a Request variable's existing value.
- Create a new Request variable during the Request using a Script: Scripts can create new Request variables that do not exist in that Request, and then assign a value to that Request variable.
Consider how two Request variables may be used in a simplified Process an organization uses to request leave, such as for a vacation. This simplified example does not discuss the procedural steps how to create these Request variables. This example is intended for conceptual purposes only to better understand how Request variables function in a Request.
- The person requesting leave, called the Request starter, uses a Date Picker control in the Screen for the Task to request the dates for his vacation. Call this Request variable
BeginLeave, which is the Variable Name setting value for the Date Picker control in that Screen. An example is shown below.
- In the Process, there is a person who is assigned the Task in the Process to approve, revise, or reject the leave request. This person may use a different Date Picker control in a different Screen to suggest a different date to begin the requester's leave. In this example, the request approver suggests a later date to start the requester's vacation, shown below. Call this Request variable
BeginLeaveRevision.
The requester for this example Process uses a Date Picker control to select leave beginning on December 16, as shown in the example description.
After completing the Task to request dates for leave, the person assigned the Task to approve, revise, or reject the leave request receives a notification to do this Task. When she opens the Task to see the Screen showing the proposed date to begin leave, stored in the
BeginLeave Request variable, she thinks that the date the requester's vacation should begin be later in that month. In her Task, she selects a later date from the Date Picker control that stores its value in the BeginLeaveRevision Request variable.Suppose that the Process is designed such that the Request returns to the requester to suggest the revised date(s) for leave if the
BeginLeave Request variable value does not match the BeginLeaveRevision Request variable value. Furthermore, when the Request returns to the requester, the BeginLeaveRevision value replaces that of the BeginLeave value so that when the requester views the Task showing the leave request change, he sees the date she adjusted to begin his vacation.