Magic Variables

Prev Next

ProcessMaker Platform provides a set of Magic Variables that store system-level data related to users, processes, and requests. These variables can be referenced in ProcessMaker Query Language (PMQL) queries, Scripts and Screens.

JSON Data Model Overview

ProcessMaker uses a schema-less JSON data model to read, write, and store request data. Because it is schema-less, the structure is dynamically built as a request progresses through the process. This model includes:

  • Data from Screens using the Variable Name setting

  • Variables generated by Scripts

  • Magic Variables automatically injected by the platform

As the request moves through tasks and elements, the JSON data model evolves, aggregating the data into a unified structure known as request data.

Magic Variables

Magic Variables are a predefined set of variables automatically included in every request’s JSON data model. These variables contain key metadata about:

  • The current user

  • The process

  • The request and its context

All Magic Variables are prefixed with an underscore (_) to differentiate them from user-defined variables. Examples include _user, _request, and _task.

Viewing the JSON Data Model

Users with the Requests: Edit Request Data permission can inspect the full JSON data model of a completed request by navigating to the Data tab in the request’s summary view.


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

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.

_user.created_at

Datetime the user account was created.

_user.deleted_at

Datetime the user account was deleted, if applicable.

_user.expires_at

Datetime the user account expires, if applicable.

_user.updated_at

Datetime the user account was updated, if applicable.

_user.loggedin_at

Datetime the user logged on to the account, if applicable.

_user.datetime_format

Datetime format setting as selected in the user's profile.

_user.is_administrator

Indicates if the user account is granted the Make this user a Super Admin option. true or false values.

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

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.


How to Use Magic Variables

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:

Where

Example

Request Data Type PMQL Properties

(process_id = 3 OR process_id = 7)

Task Data Type PMQL Properties

(task = "Submit Purchase Request") AND (status = "in progress")

Reference in Screens

Permissions

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:

Where

Example

Reference a Magic Variable's value in a Rich Text control through the Rich Text Content setting.

{{ _user.fullname }}. Spaces surrounding the Magic Variable reference are allowed.

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.

return  this._user.fullname


Example of the Data Structure

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"
    }
}