ProcessMaker API Documentation
Script Central

Scripts Editor

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

Overview

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

  • Scripts: View Scripts

  • Scripts: Create Scripts

  • Scripts: Edit Scripts

See the ProcessMaker Scripts permissions or ask your ProcessMaker Administrator for assistance.

Use Scripts Editor to develop and test your ProcessMaker Scripts. Any ProcessMaker Script can be used in any Process in your organization. See What is a Script? for information regarding which programming languages Scripts Editor supports.

Scripts Editor evaluates a ProcessMaker Script securely and in isolation. This ensures that any malicious script that anyone in your organization might inadvertently introduce to ProcessMaker does not affect the ProcessMaker application or its environment.

ProcessMaker Scripts are developed and tested in the same environment.

Access Scripts Editor in the following ways:

Below is Scripts Editor displaying a ProcessMaker Script written in PHP.

Scripts Editor

Scripts Editor Usage Guidelines

Follow these guidelines to develop and test ProcessMaker Scripts in Scripts Editor.

Develop Your ProcessMaker Script

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

Mock Request Data Coming Into the ProcessMaker Script

Use the Sample Input panel to mock Request data that comes into the ProcessMaker Script.

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

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

  1. Open the ProcessMaker Screen in which to view its JSON data model.

  2. Enter Preview mode on the ProcessMaker Screen page to view its JSON data model. Click the Preview button from Screen Builder's top menu to enter Preview mode.

  3. Enter values into the control settings as if you were using the ProcessMaker 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 ProcessMaker Screen preview. Understand what the key names are. Each key is derived from a ProcessMaker Screen control's Variable Name value. Use these key names as variables in your ProcessMaker Script.

    The JSON data model within a ProcessMaker Screen becomes the variables in any Task element of a Process model that uses that Screen. Use these variables to capture what Request participants enter into a ProcessMaker Screen as input data to a ProcessMaker Script.

  4. After you have entered values into the ProcessMaker Screen in Preview mode, the entire JSON data model displays in the Data Preview panel. Copy the JSON data model.

  5. Paste the JSON data model into the Sample Input panel in Scripts Editor. If you use any variables as defined in the JSON data model in your ProcessMaker Script, Scripts Editor uses those variable values during script testing.

  6. Optionally, mock the ProcessMaker Magic Variables that your ProcessMaker Script would reference during an in-progress Request. 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 ProcessMaker user, Process, and Request related data for all Requests. During an in-progress Request, these ProcessMaker Magic Variables are updated. All ProcessMaker Magic Variables are preceded by an underscore (_) character in the JSON data model. Enter the ProcessMaker 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.

  7. Click Run.

  8. In the Output panel, view the mocked Request data.

Enter Other JSON Data as Input to Your ProcessMaker Script

Use the Configuration panel to include JSON configuration settings your ProcessMaker 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 ProcessMaker 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 ProcessMaker Script may reference ProcessMaker Screen control values during a Request by placing their Variable Name setting values within mustache syntax. 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 ProcessMaker Script

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

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

Pass Request Data Into Your ProcessMaker Script

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

  • Request data: 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 ProcessMaker assets used in a Request, such as the Variable Name setting values in a ProcessMaker Screen or variables a ProcessMaker Script creates. When an in-progress Request routes through the Process, Request data aggregates into the JSON data model, thereby becoming Request data. ProcessMaker users or ProcessMaker 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. ProcessMaker Scripts can call Request data by referencing these JSON objects derived from Variable Name setting values in ProcessMaker Screens.

    JSON data model in a Completed Request, as viewed from the "Data" tab

  • ProcessMaker Magic Variables: 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 ProcessMaker user, Process, and Request related data for all Requests. During an in-progress Request, these ProcessMaker Magic Variables are updated. All ProcessMaker Magic Variables are preceded by an underscore (_) character in the JSON data model. See Reference Magic Variables in ProcessMaker Assets.

  • ProcessMaker Environment Variables: The sensitive information that a ProcessMaker Environment Variable represents can pass to a ProcessMaker Script when it runs. Usage depends on the programming language that the ProcessMaker Script uses. In the usage examples below, ENV_VAR_NAME represents the name of the ProcessMaker Environment Variable. See ProcessMaker Variable Syntax, Usage, and Examples.

ProcessMaker uses two global variables that can ProcessMaker Scripts can call. Variable usage depends on the programming language that the ProcessMaker Script uses. See ProcessMaker Variable Syntax, Usage, and Examples. Below is a description of these global variables:

  • Data: The data variable contains all Request data to the moment a ProcessMaker Script runs.

  • Config: The config variable contains any special configuration to be passed to the ProcessMaker Script prior to it running.

ProcessMaker Variable Syntax, Usage, and Examples

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

PHP
Lua
JavaScript
C#
Java
R
PHP

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

  • How to get a ProcessMaker Environment Variable.

  • How to get a value from the configuration object.

  • How to get a value from a data object.

You may also use ProcessMaker's PHP SDK to design custom applications.

<?php
$output = [];
// Get a ProcessMaker 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;
Lua

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

  • How to get a ProcessMaker Environment Variable.

  • How to get a value from the configuration object.

  • How to get a value from a data object.

You may also use ProcessMaker's Lua SDK to design custom applications.

-- Get a ProcessMaker 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}
JavaScript

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

  • How to get a ProcessMaker Environment Variable.

  • How to get a value from the configuration object.

  • How to get a value from a data object.

You may also use ProcessMaker's JavaScript SDK to design custom applications.

// A ProcessMaker 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 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
});
});
});
C#

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

  • How to get a ProcessMaker Environment Variable.

  • How to get a value from the configuration object.

  • How to get a value from a data object.

You may use ProcessMaker's C# SDK to design custom applications.

The C# package is not available in the ProcessMaker open-source edition. Contact ProcessMaker Sales or ask your ProcessMaker sales representative how the C# package can be installed in your ProcessMaker instance.

using System;
using ProcessMakerSDK.Api;
using ProcessMakerSDK.Client;
using ProcessMakerSDK.Model;
// A ProcessMaker 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 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);
}
}
}
Java

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

  • How to get a ProcessMaker Environment Variable.

  • How to get a value from the configuration object.

  • How to get a value from a data object.

You may use ProcessMaker's Java SDK to design custom applications.

The Java package is not available in the ProcessMaker open-source edition. Contact ProcessMaker Sales or ask your ProcessMaker sales representative how the Java package can be installed in your ProcessMaker instance.

import java.io.*;
import java.util.*;
import ProcessMaker_Client.ApiClient;
import ProcessMaker_Client.ApiException;
import ProcessMaker_Model.Users;
import ProcessMaker_Api.UsersApi;
// A ProcessMaker 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 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();
}
}
}
R

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

  • How to get a ProcessMaker Environment Variable.

  • How to get a value from the configuration object.

  • How to get a value from a data object.

The R package is not available in the ProcessMaker open-source edition. Contact ProcessMaker Sales or ask your ProcessMaker sales representative how the R package can be installed in your ProcessMaker instance.

# Get a ProcessMaker 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)

Save Your ProcessMaker Script

Click the Save iconfrom Script Editor's top menu to save the ProcessMaker Script.

Related Topics