Script Editor

Develop and test your Script in a secure and isolated environment.‌

Overview

Use Script Editor to develop and test your Scripts. Any Script can be used in any Process in your organization developed using programming languages that Script Editor supports.‌

Scripts run securely and in isolation from within Docker containers called Script Executors. The Script Executor for each supported programming language contains the Software Development Kit (SDK) that supports extensibility to provide programmatic interaction with ProcessMaker Platform. When the ProcessMaker Platform instance calls a Script to run, the Script Executor for that programming language creates a Docker container corresponding with that programming language, runs the Script, and then destroys the Docker container. This ensures that any malicious script that anyone in your organization might inadvertently introduce to ProcessMaker Platform does not affect the instance or its hosting environment: Docker containers cannot access them. Furthermore, Docker containers cannot listen for inbound connections; therefore, a Docker container cannot be accessed externally.

Scripts are developed and tested in the same environment.

‌Below is the Script Editor displaying a Script written in PHP.‌

Permissions Required

Your user account or group membership must have the following permissions to create or edit a Script:

Scripts: View Scripts
Scripts: Create Scripts
Scripts: Edit Scripts

See the Scripts permissions or ask your Administrator for assistance.

Access the Script Editor in the following ways:

Script Editor Usage Guidelines

‌Follow these guidelines to develop and test Scripts in the Script Editor.‌

Develop Your Script

‌Develop the Script below the script's name and language description. Use the scroll panel to navigate your code not currently displayed. This is useful especially when you are editing a long Script.‌

Automatically Save Your Script

Script Editor automatically saves your Script every five (5) seconds when changes are made to any of the configuration panels. Regardless of whether you publish your Script prior to leaving Script Editor, the next time you edit that Script, the changes since its last publication remain intact.

Revisions made to Script Config Editor screen do not save until the Close button is clicked.

Discard Changes to Your Script

When discarding a draft of your Script, Script Editor discards all changes to that Script since its last publication.

Follow these steps to discard changes to your Script since its last publication:

While in Script Editor, click the ellipses menu, and then select Discard Draft.
Click the Discard button. Script Editor discards the changes since last starting to edit that Script, and then closes. The Scripts page displays.

Close Script Editor with Your Saved Changes

Since Script Editor saves changes to your Script automatically, it is not necessary to manually save your changes. However, you may close Script Editor without publishing your changes, but keep all your changes intact.

While in Script Editor, click the Close button. Script Editor closes with your saved changes. The Scripts page displays.

Publish Your Script

A Script can be published in two ways depending if the Versioning package is installed. See the following sections regarding how a Script may be published:

Versioning package is not installed: Publish a single version of your Script.
Versioning package is installed: Publish distinct versions of your Script.

Publish a Single Version of a Script

Permissions are required to do this.

Click the Publish button from Script Editor's top menu to publish the Script.‌ When the Versioning package is not installed, this action overwrites the previous publication of this Script without maintaining a record of its previous publication(s). To publish distinct versions of a Script, the Versioning package must be installed.

Publish Distinct Versions of a Script

Permissions Required

Permissions are required to do this.

Package Required

The Versioning package must be installed to publish distinct versions of a Script.

When the Versioning package is installed, distinct versions of a Script can be published. A version is a set of changes published for a Script since the last publication. Versioning maintains a record of all named and unnamed publications to that Script. Any of these versions may be viewed or retrieved, if needed. See the Versioning package for more information.

Follow these guidelines to publish a new distinct version of your Script:‌

Click the Publish button from Script Editor's top menu.‌
If the Versioning package is installed, the Commit Changes screen displays to name that published version of this Script.
Do one of the following:
- Publish an unnamed version:
  Follow these steps to publish an unnamed version:
  1. Click Save to publish an unnamed version. Otherwise, click Cancel to return to Script Editor without publishing. As a best practice, name each published version to provide auditing and documentation to what has changed in each publication. Otherwise, Process Designers that manage versions of this Script do not view unnamed versions when the Only show named versions toggle key is enabled while viewing that Script's version history.
- Save a named version:
  Follow these steps to publish a named version:
  1. In the Version Name setting, enter a name for this version. The version name displays when viewing the version history of that Script and helps identify this version. Although this setting is not required, as a best practice name each version for easier maintenance, documentation, and auditing purposes. Name the version that describes changes in this Script.
  2. In the Additional Details (optional) setting, optionally enter details of the changes made in this version. The additional details display when viewing the version history of that Script and helps other Process Designers or Administrators understand the changes made in that version. Enter details which concisely summarize the changes made in this version.
  3. Click Save to save this version. Otherwise, click Cancel to return to Script Editor without publishing.

Enter Mock Request Data Coming Into Your Script

‌Use the Sample Input panel to mock Request data that comes into your Script to test how the Script runs using Request data you expect.

Define the variables in a Screen when you configure its controls. See information about each control.‌

Follow these guidelines to mock Request data coming into your Script:‌

Open the Screen in which to view its JSON data model.
Enter Preview mode on the Screen page to view its JSON data model. Click the Preview button from Screen Builder's top menu to enter Preview mode.
Enter values into the control settings as if you were using the Screen in a Request. In the Data Preview panel, the JSON data model displays the key-value pairs in each object element. The keys' values are those you enter in the Screen preview. Understand what the key names are. Each key is derived from a Screen control's Variable Name setting value. Use these key names as variables in your Script. The Variable Name setting values become part of the Request data and contain the content that Request participants enter into that Screen during a Request. Mock these Variable Name setting values as input data to your Script.
After you have entered values into the Screen in Preview mode, the entire JSON data model displays in the Data Preview panel. Copy the JSON data model.
Paste the JSON data model into the Sample Input panel in Script Editor. If you use any variables as defined in the JSON data model in your Script, Script Editor uses those variable values during script testing.
Optionally, mock the Magic Variables that your Script would reference during an in-progress Request. 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. During an in-progress Request, these Magic Variables are updated. All Magic Variables are preceded by an underscore (_) character in the JSON data model. Enter the Magic Variable into the Sample Input panel as part of the JSON data model, and then enter mock values for each. See Magic Variable Descriptions.
Click Run.
In the Output panel, view the mocked Request data.

‌Enter Other JSON Data as Input to Your Script

‌Use the Configuration panel to include JSON configuration settings your Script uses when it runs. For example, include the Client ID and Client Secret values in JSON format for OAuth 2.0 verification to a third-party service's API your Script must access to access the API. By entering these values into the Configuration panel, you can verify during testing that these values are valid for the third-party service.‌

A Script may reference Screen control values during a Request by placing their Variable Name setting values within quotation marks ("). In the example below, FullName is the Variable Name setting value for a control to store a Request participant's full name:

{
    "Name": "FullName"
}

‌Test Your Script

‌Click the Run button to test your Script. Script Editor evaluates any JSON data entered into the Configuration and Sample Input panels.‌

If the Script evaluates successfully, its output displays in the Output panel. If the Script does not evaluate successfully, the language engine evaluating the script displays an error.‌

Pass Request Data Into Your Script

‌Pass Request-related data into your Script in the following ways:‌

Request data: 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, such as the Variable Name setting values in a Screen or 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. Users or group members 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. Scripts can call Request data by referencing these JSON objects derived from Variable Name setting values in Screens.
Script Task element Configuration: Enter JSON data to pass to the Script when configuring the Script task element in Process Modeler. In the example below, the data from JSON Variable Email is being passed to the Script using the Script Configuration panel of a Script Task element. Note that revisions made to Script Config Editor screen do not save until the Close button is clicked.
Magic Variables: 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. During an in-progress Request, these Magic Variables are updated. All Magic Variables are preceded by an underscore (_) character in the JSON data model. See Reference Magic Variables in ProcessMaker Platform Assets.
Environment Variables: The sensitive information that an Environment Variable represents can pass to a Script when it runs. Usage depends on the programming language that the Script uses. In the usage examples below, ENV_VAR_NAME represents the name of the Environment Variable. See Variable Syntax, Usage, and Examples.

‌ProcessMaker Platform and Environment Variable Syntax, Usage, SDK, and Examples

‌ProcessMaker Platform uses two global variables that Scripts can call. Variable usage depends on the programming language that the Script uses. Below is a description of these global variables:‌

Data: The data variable is a JSON object that contains all Request data to the moment a Script runs.
Config: The config variable is a JSON object that contains any special configuration to be passed to the Script prior to it running. In Script Task elements of a Process model, special configurations are entered into the Script Configuration setting. See Reference a Request Variable from a Script Configuration Setting as to the best practice when configuring Scripts from Script Task elements in a Process model.

Every Script Executor from which a Script runs has the following default Environment Variables from which a Script may get its value. Refer to the tabs below how to get these Environment Variable values for each supported programming language. Below is a description of these default Environment Variables.

Environment Variable

Description

HOST_URL

Domain for the ProcessMaker Platform instance.

API_HOST

ProcessMaker Platform instance API to which to make all RESTful API calls.

API_TOKEN

Token a Script uses to authenticate to our API host. Note that this API token is only valid for the lifetime of the Script: after the Script runs and the Script Executor's Docker container from which that Script ran, its API token is no longer valid.

‌Refer to the tabs below how to use variables in supported programming languages.

Below is a sample Script that uses PHP. Refer to the comments denoted with // that describe how the sample functions:

How to get an Environment Variable.
How to get a value from the configuration object.
How to get a value from a data object.
Call the Software Development Kit (SDK).

<?php
$output = [];
// Get a ProcessMaker Platform Environment Variable, in this case TEST_VAR.
$output['envVar'] = getenv('TEST_VAR');
// Get a value from the config object.
// In this example, 'test' in the JSON config: {"test":"test config value"}
$output['configTest'] = $config["test"];
// Get a value from the data object.
// In this example, the user_id for the _request.
$output['requestUserId'] = $data['_request']['user_id'];
// Get the email address for user id 1 using the API/SDK.
// Use the global `$api_config` to set credentials automatically.
$usersApi = new ProcessMaker\Client\Api\UsersApi(null, $api_config);
$user = $usersApi->getUserById("1");
$output['userEmail'] = $user->getEmail();
return $output;

Below is a sample Script that uses Lua. Refer to the comments denoted with -- that describe how the sample functions:

How to get an Environment Variable.
How to get a value from the configuration object.
How to get a value from a data object.
Call the Software Development Kit (SDK).

-- Get a ProcessMaker Platform Environment Variable, in this example TEST_VAR.
local envVar = os.getenv("TEST_VAR")
   
-- Get a value from the config object.
-- In this example, 'test' in the JSON config: {"test":"test config value"}
local configTest = config["test"]

-- Get a value from the data object.
-- In this example, the user_id for the _request.
local requestUserId = data["_request"]["user_id"]

-- Get the email address for user id 1 using the API/SDK.
-- Use client.make to get a pre-configured api client.
-- See https://github.com/ProcessMaker/sdk-lua/tree/master/pmsdk/api for available clients.
local users_api = client.make('users_api')
local user = users_api:get_user_by_id("1")
local userEmail = user.email

return {envVar=envVar, configTest=configTest, requestUserId=requestUserId, userEmail=userEmail}

Below is a sample Script that uses JavaScript. Refer to the comments denoted with // that describe how the sample functions:

How to get an Environment Variable.
How to get a value from the configuration object.
How to get a value from a data object.
Call the Software Development Kit (SDK).

// A Script written in JavaScript should return a Promise that
// resolves with the output data. You can also return a basic object.
// For example `return {"key":"value"}`
return new Promise((resolve, reject) => {

    // Get a ProcessMaker Platform Environment Variable, in this example TEST_VAR.
    const envVar = process.env['TEST_VAR'];
    
    // Get a value from the config object.
    // In this example, 'test' in the JSON config: {"test":"test config value"}
    const configTest = config['test'];
    
    // Get a value from the data object.
    // In this case the user_id for the _request.
    const requestUserId = data["_request"]["user_id"];
    
    // Get the email address for user id 1 using the API/SDK.
    // Use the global `api` object to get a pre-configured client.
    let usersApi = new api.UsersApi();
    usersApi.getUserById("1", (error, user) => {
    
        const userEmail = user.email;
        
        resolve({
            'envVar' : envVar,
            'configTest' : configTest,
            'requestUserId' : requestUserId,
            'userEmail' : userEmail
        });
    });
});

The C# package must be installed.

Below is a sample Script that uses C#. Refer to the comments denoted with // that describe how the sample functions:

How to get an Environment Variable.
How to get a value from the configuration object.
How to get a value from a data object.
Call the Software Development Kit (SDK).

using System;
using ProcessMakerSDK.Api;
using ProcessMakerSDK.Client;
using ProcessMakerSDK.Model;

// A Script written in C# must have a 'Script' class that implements 'BaseScript'.
// It must include a method named 'Execute'. Results must be added to the 'output' map.
public class Script : BaseScript
{
    public override void Execute(
        dynamic data,
        dynamic config,
        dynamic output,
        Configuration apiConfig)
    {
        // Get a ProcessMaker Platform Environment Variable, in this example TEST_VAR.
        output.envVar = Environment.GetEnvironmentVariable("TEST_VAR");
        
        // Get a value from the config object.
        // In this example, 'test' in the JSON config: {"test":"test config value"}
        output.configTest = config["test"];
        
        // Get a value from the data object.
        // In this example, the user_id for the _request.
        output.requestUserId = data["_request"]["user_id"];
        
        // Get the email address for user id 1 using the API/SDK.
        try {
            var apiInstance = new UsersApi(apiConfig);
            Users user = apiInstance.GetUserById("1");
            output.userEmail = user.Email;
        } catch (ApiException e) {
            Console.WriteLine(e.StackTrace);
        }
    }
}

The Java package must be installed.

Below is a sample Script that uses Java. Refer to the comments denoted with // that describe how the sample functions:

How to get an Environment Variable.
How to get a value from the configuration object.
How to get a value from a data object.
Call the Software Development Kit (SDK).

import java.io.*;
import java.util.*;
import ProcessMaker_Client.ApiClient;
import ProcessMaker_Client.ApiException;
import ProcessMaker_Model.Users;
import ProcessMaker_Api.UsersApi;

// A Script written in Java must have a 'Script' class that implements 'BaseScript'.
// It must include a method named 'execute'. Results must be pushed to the 'output' map.
public class Script implements BaseScript {
    public void execute(
        Map<String, Object> data,
        Map<String, Object> config,
        Map<String, Object> output,
        ApiClient api
    ) {

        // Get a ProcessMaker Platform Environment Variable, in this example TEST_VAR.
        Map<String, String> env = System.getenv();
        output.put("env-var", env.get("TEST_VAR"));
        
        // Get a value from the config object.
        // In this example, 'test' in the JSON config: {"test":"test config value"}
        output.put("config-test", config.get("test"));

        // Get a value from the data object.
        // In this example, the user_id for the _request.
        Map requestData = ((Map)data.get("_request")); 
        output.put("data-request-user-id", requestData.get("user_id"));
        
        // Get the email address for user id 1 using the API/SDK.
        try {
            UsersApi apiInstance = new UsersApi(api);
            Users user = apiInstance.getUserById("1");
            output.put("user-1-email", user.getEmail());
        } catch (ApiException e) {
            e.printStackTrace();
        }
    }
}

The Python package must be installed.

Below is a sample Script that uses Python. Refer to the comments denoted with # that describe how the sample functions:

How to get an Environment Variable.
How to get a value from the configuration object.
How to get a value from a data object.
Call the Software Development Kit (SDK).

# A Script written in Python must set a dict
# named `output` with the data to return.

# Get a ProcessMaker Platform Environment Variable, in this case TEST_VAR
envVar = os.getenv('TEST_VAR')

# Get a value from the config object.
# In this case, 'test' in the json config: {"test":"test config value"}
configTest = config['test']

# Get a value from the data object.
# In this case the user_id for the _request
requestUserId = data['_request']['user_id']

# Get the email address for user id 1 using the API/SDK
# Use the global `configuration` object to set auth tokens
users_api_instance = pmsdk.UsersApi(pmsdk.ApiClient(configuration))
user = users_api_instance.get_user_by_id(1)
userEmail = user.email

output = {
    "envVar": envVar, 
    "configTest": configTest, 
    "requestUserId": requestUserId, 
    "userEmail": userEmail
}

The R package must be installed.

Below is a sample Script that uses R. Refer to the comments denoted with # that describe how the sample functions:

How to get an Environment Variable.
How to get a value from the configuration object.
How to get a value from a data object.
Call the Software Development Kit (SDK).

# Get a ProcessMaker Platform Environment Variable, in this example TEST_VAR.
envVar <- Sys.getenv("TEST_VAR")

# Get a value from the config object.
# In this example, 'test' in the JSON config: {"test":"test config value"}
configVar <- config[["test"]]

# Get a value from the data object.
# In this example, the user_id for the _request.
dataVar <- data[["_request"]][["user_id"]]

output

<- list(envVar = envVar, configVar = configVar, dataVar = dataVar)

Retrieve All Tasks for a User

The following sample PHP script provides an example to get all Tasks currently assigned to a user. This example also demonstrates the use of optional arguments such as the Request ID or a Task filter.

// Sample PHP script to get all current Tasks for a user
<?php
$apiInstance = $api->tasks();
$tasks = [];

// Returns all Tasks that the user has access to
$result = $apiInstance->getTasks();
foreach ($result->getData() as $task) {
    $tasks[] = [
        'id' => $task->getId(),
        'name' => $task->getElementName(),
        'processRequestId' => $task->getProcessRequestId(),
        'status' => $task->getStatus(),
        'userId' => $task->getUserId(),
    ];
}

// Optional arguments
$process_request_id = 5; // int | Process request_id
$filter = 'Form Task'; // string | filter by Taskid, node name, or Request data
$order_by = 'id'; // string | Field to order results by
$order_direction = 'asc'; // string | 
$include = 'process,user'; // string | Include data from related models in payload. Comma separated list.

$result = $apiInstance->getTasks($process_request_id, $filter, $order_by, $order_direction, $include);
foreach ($result->getData() as $task) {
    $tasks[] = [
        'id' => $task->getId(),
        'name' => $task->getElementName(),
        'status' => $task->getStatus(),
        'userEmail' => $task->getUser()['email'],
        'processName' => $task->getProcess()['name']
    ];
}

return ['tasks' => $tasks];

Get a Task using the Task ID

The following sample PHP script provides an example to retrieve a single Task using its Task ID.

// Sample PHP script to get the Task for a certain TaskID
<?php
$apiInstance = $api->tasks();
$taskId = 15;
$task = $apiInstance->getTasksById($taskId);

return [
    'task' => [
        'name' => $task->getElementName(),
        'status' => $task->getStatus(),
        'userId' => $task->getUserId()
    ]
];

Complete a Task

The following sample PHP script provides an example of completing a Task when the Task ID is known.

// Sample PHP Script to complete a Task
<?php
$apiInstance = $api->tasks();
$taskId = 15;
$task = $apiInstance->getTasksById($taskId);

$process_request_token_editable = new \ProcessMaker\Client\Model\ProcessRequestTokenEditable();
$process_request_token_editable->setStatus('COMPLETED');
$process_request_token_editable->setData(['addToRequestData' => 'a value']);

$result = $apiInstance->updateTask($taskId, $process_request_token_editable);

// If there are no error, then the Task was successfully completed
return ['success' => true];
return ['tasks' => $tasks];