Magic Variables

ProcessMaker Platform provides a set of Magic Variables that store data for users and requsts. Designers may reference these variables in ProcessMaker Query Language (PMQL) queries and in other ProcessMaker assets, such as Scripts and Screens.

ProcessMaker Platform 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 Platform 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 Platform uses a set of Magic Variables that become part of the JSON data model for all Requests. ProcessMaker Platform uses these Magic Variables to store user, Process, and Request related data for all Requests. 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 in the Data tab in a completed Request's summary.

Magic Variable Descriptions

The following Magic Variables are available to you when designing processes. 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.

_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.

How to Use Magic Variables

Magic Variables can be used in a variety of ways in ProcessMaker Platform and in ProcessMaker Platform 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

Reference in Screens

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.

• Calculated Properties: Reference a Magic Variable's value from a Calculated Property. Use JavaScript to return a Magic Variable's value, then store it in a Calculated Property.

Example of Magic Variable Usage

This example indicates the JSON structure for each Magic Variable. Each contains a value as it might be read from the Data tab in a completed Request summary.

{
    "_user": {
        "id": 1,
        "fax": "723.743.8058 x00631",
        "cell": "585.620.0749",
        "city": "Donnaland",
        "email": "lauretta.okuneva@robel.com",
        "media": [],
        "phone": "1-316-934-1911 x762",
        "state": "WV",
        "title": "Customer Service Representative",
        "avatar": "",
        "postal": "97304-3230",
        "status": "ACTIVE",
        "address": "8547 Marielle Hills",
        "country": "US",
        "fullname": "admin admin",
        "language": "en",
        "lastname": "admin",
        "timezone": "America/Los_Angeles",
        "username": "admin",
        "birthdate": "1962-10-23",
        "firstname": "admin",
        "created_at": "2019-07-19T08:13:13-07:00",
        "deleted_at": null,
        "expires_at": null,
        "updated_at": "2019-07-19T08:14:35-07:00",
        "loggedin_at": "2019-07-19T08:14:35-07:00",
        "datetime_format": "m/d/Y H:i",
        "is_administrator": true
    },
    "_request": {
        "id": 1,
        "name": "Pet adoption",
        "status": "ACTIVE",
        "process": {
            "id": 1,
            "name": "Pet adoption",
            "status": "ACTIVE",
            "user_id": 1,
            "created_at": "2019-03-25T10:50:46-07:00",
            "deleted_at": null,
            "updated_at": "2019-07-19T08:15:18-07:00",
            "description": "Pet rescue",
            "cancel_screen_id": null,
            "pause_timer_start": 0,
            "process_category_id": 1,
            "has_timer_start_events": false
        },
        "user_id": 1,
        "created_at": "2019-07-19T08:15:24-07:00",
        "process_id": 1,
        "updated_at": "2019-07-19T08:15:24-07:00",
        "callable_id": "ProcessId",
        "initiated_at": "2019-07-19T08:15:24-07:00"
    }
}