What is a Request Variable?

Understand how ProcessMaker uses variables in Request data.

Overview

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.

Magic Variables

ProcessMaker Platform uses a set of global variables that become part of each Request. ProcessMaker Platform 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 Platform Assets.

Variables Created in Each Request

Variables are often unique to each Request. As each Request participant does an assigned Task in a Request, that Task displays a Screen. The Screen displays the information that Task assignee must enter, review, and/or approve.

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 Platform 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 value true is 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 value false is 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.

Example

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.

Example Description

Suppose the following Request variables exist in two different Screens for different Tasks in this request leave Process:

Request Starter Submits Leave Request

The Request starter for this example Process uses a Date Picker control to select leave beginning on December 16, as shown in the example description.

Approver Reviews the Leave Request

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 Request starter'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.

Request Routes Back to Request Starter for Revision

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.

pageWhat is Request Data?pageWhat is a Request?pageWhat is JSON?

© Copyright 2000-2024 ProcessMaker Inc. All rights reserved.