Reference Magic Variables in ProcessMaker Assets

Reference the values in Magic Variables for use in your PMQL queries. Furthermore, reference Magic Variables in Scripts and Screens during in-progress Requests.

Overview
ProcessMaker uses a set of Magic Variables that you may reference in ProcessMaker Query Language (PMQL) queries and in your ProcessMaker assets, such as Scripts and Screens.
ProcessMaker uses a schema-less JSON data model from which to read, write, and store Request data. Since the JSON data model is schema-less (meaning that it does not require a specific schema or structure from which ProcessMaker assets must conform), the JSON data model is structured from the JSON objects in assets used in a Request: the Variable Name setting values in a Screen or Request variables a Script creates. When an in-progress Request routes through the Process, Request data aggregates into the JSON data model, thereby becoming Request data.
However, ProcessMaker uses a set of Magic Variables that become part of the JSON data model for all Requests. 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. All Magic Variables are preceded by an underscore (_) character in the JSON data model.
​Users that have the Requests: Edit Request Data permission may view the JSON data model for a completed Request. This JSON data model displays from the Data tab in a completed Request's summary. Below is an example.
JSON data model in a completed Request, as viewed from the "Data" tab
How to Use Magic Variables
Use Magic Variables in a variety of ways in ProcessMaker and in ProcessMaker assets.
Reference in PMQL Queries for Request and Task Searches
Reference Magic Variables to compose ProcessMaker Query Language (PMQL) advanced queries for Request searches and Task searches. See the following topics:
​Request Data Type PMQL Properties​
​Task Data Type PMQL Properties​
Mock in Script Testing
Your user account or group membership must have the following permissions to edit a Script unless your user account has the Make this user a Super Admin setting selected:
Scripts: Edit Scripts
Scripts: View Scripts
See the Scripts permissions or ask your Administrator for assistance.
​Mock Magic Variable values while mocking Request data during testing to ensure your Script runs as you intended.
Reference in Screens
Your user account or group membership must have the following permissions to edit a Screen control unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Reference Magic Variables in Screens in the following ways:
​Rich Text controls: Reference a Magic Variable's value in a Rich Text control through the Rich Text Content setting.
​Computed Properties: Reference a Magic Variable's value from a computed Property. Use JavaScript to return a Magic Variable's value, then store it in a computed Property.
Example of All Magic Variables
Below is an example that contains all Magic Variables. Each contains a value as it might be read from the Data tab in a completed Request summary. This example indicates the JSON structure for each Magic Variable.
1
{
2
    "_user": {
3
        "id": 1,
4
        "fax": "723.743.8058 x00631",
5
        "cell": "585.620.0749",
6
        "city": "Donnaland",
7
        "email": "[email protected]",
8
        "media": [],
9
        "phone": "1-316-934-1911 x762",
10
        "state": "WV",
11
        "title": "Customer Service Representative",
12
        "avatar": "",
13
        "postal": "97304-3230",
14
        "status": "ACTIVE",
15
        "address": "8547 Marielle Hills",
16
        "country": "US",
17
        "fullname": "admin admin",
18
        "language": "en",
19
        "lastname": "admin",
20
        "timezone": "America/Los_Angeles",
21
        "username": "admin",
22
        "birthdate": "1962-10-23",
23
        "firstname": "admin",
24
        "created_at": "2019-07-19T08:13:13-07:00",
25
        "deleted_at": null,
26
        "expires_at": null,
27
        "updated_at": "2019-07-19T08:14:35-07:00",
28
        "loggedin_at": "2019-07-19T08:14:35-07:00",
29
        "datetime_format": "m/d/Y H:i",
30
        "is_administrator": true
31
    },
32
    "_request": {
33
        "id": 1,
34
        "name": "Pet adoption",
35
        "status": "ACTIVE",
36
        "process": {
37
            "id": 1,
38
            "name": "Pet adoption",
39
            "status": "ACTIVE",
40
            "user_id": 1,
41
            "created_at": "2019-03-25T10:50:46-07:00",
42
            "deleted_at": null,
43
            "updated_at": "2019-07-19T08:15:18-07:00",
44
            "description": "Pet rescue",
45
            "cancel_screen_id": null,
46
            "pause_timer_start": 0,
47
            "process_category_id": 1,
48
            "has_timer_start_events": false
49
        },
50
        "user_id": 1,
51
        "created_at": "2019-07-19T08:15:24-07:00",
52
        "process_id": 1,
53
        "updated_at": "2019-07-19T08:15:24-07:00",
54
        "callable_id": "ProcessId",
55
        "initiated_at": "2019-07-19T08:15:24-07:00"
56
    }
57
}
Copied!
Magic Variable Descriptions
Below are descriptions of each Magic Variable. Since these descriptions are outlined in tabular format, they do not imply how they are structured in the JSON data model. Refer to the example in the Example of All Magic Variables section to see how each JSON object is structured in the overall JSON data model.
_user Magic Variable
The _user Magic Variable contains data about the current user assigned a Form Task element or Manual Task element during an in-progress Request. Use JSON dot notation to reference specific data in a Magic Variable. Example: _user.fullname. If a Magic Variable contains no data, null is the value.
The following table documents the _user Magic Variable names in the order they present within the JSON object.
Magic Variable Name
Description
_user.id
A unique identifier for the user. Automatically increments for each created user. This value can be the user that is currently logged on and completing a Form Task/Manual Task.
_user.fax
Fax number as entered into the user's profile.
_user.cell
Cell number as entered into the user's profile.
_user.city
City as entered into the user's profile.
_user.email
Email address as entered into the user's profile.
_user.media
​
_user.phone
Telephone number as entered into the user's profile.
_user.state
State, region, or province as selected in the user's profile.
_user.title
Job title as entered into the user's profile.
_user.avatar
Image reference for the user's avatar as entered into the user's profile.
_user.postal
Business postal code as entered into the user's profile.
_user.status
Status of the user's account (active or inactive).
_user.address
Business address as entered into the user's profile.
_user.fullname
Full name of the user as entered into the user's profile.
_user.language
Language to display labels as selected in the user's profile.
_user.timezone
Time zone as selected in the user's profile.
_user.username
User name for the user as entered into the user's profile.
_user.birthdate
Birth date for the user. This is not entered into a user profile.
_user.firstname
First name for the user as entered into the user's profile.
_request Magic Variable
The _request Magic Variable contains data about the current Request or Process during an in-progress Request. Use JSON dot notation to reference specific data in a Magic Variable. Example: _request.process.name. If a Magic Variable contains no data, null is the value.
The following table documents the _request Magic Variable names in the order they present within the JSON object.
Magic Variable Name
Description
_request.id
Request identifier for its associated Process. Automatically increments for each Request instance.
_request.name
Name of the Process associated with the Request.
_request.errors
Contains any errors that occur during the Request.
_request.status
Status of the Request. ACTIVE or INACTIVE values.
_request.user_id
Identifier for the user that created the Process associated with the Request.
_request.created_at
Datetime the user account was create that is associated with the _request.user_id Magic Variable.
_request.process_id
Identifier for the Process associated with the Request. Automatically increments for each created Process.
_request.updated_at
Datetime the Request was updated.
_request.callable_id
Callable identifier for the Process associated with the Request. ProcessId is the value.
_request.completed_at
Datetime the Request completed.
_request.initiated_at
Datetime the Request started.
Related Topics
Search for a Request
Search for a Task
What is PMQL?
What is a Request?
What is a Task?
What is a Screen?
What is a Script?