Follow examples that use ProcessMaker Script Executors to guide and inspire your own ProcessMaker implementations.
Loading...
Loading...
Loading...
Follow an example to configure a PHP executor with the SQLSRV module.
Intended audience: ProcessMaker Administrators, coding engineers
Tags: Script Executor; PHP; SQLSRV
This example outlines best practices when creating a PHP script executor with the SQLSRV module in ProcessMaker. This example ensures a seamless integration of the SQL Server functionality into your scripts.
Follow the next steps to configure the PHP executor with the SQLSRV module:
View your Script Executors. The Script Executors page displays.
Click the +Script Executor button. The Add New Script Executor screen displays.
In the Name setting, enter the unique name for the Script Executor. This name displays from Script configuration settings, so enter a descriptive name so that Process designers configuring their Scripts understand what customization this Script Executor provides. For example, you can enter PHP + SQLSRV.
In the Description setting, enter a description for the Script Executor.
From the Language setting, select the PHP programming language that the Script Executor uses to run the Script. After selecting the programming language, the default Dockerfile content to run Scripts using that language displays in the Dockerfile setting. The Dockerfile content includes the SDK for that language.
From the Dockerfile setting, append the default Dockerfile content with the Docker commands the Script Executor runs when it builds the Docker container. Consider following best practices for writing Dockerfiles. For this example, enter the following code to integrate correctly the SQL Server functionality.
Click Save and Build to build the Docker container from which the Script Executor runs Scripts. The Build Command Output setting displays below the Dockerfile setting as the Script Executor builds the Docker container in real-time. If the Docker container builds successfully, the following message displays: Executor Successfully Built. You can now close this window. If building the Docker container is unsuccessful, the following message displays: Error Building Executor. See Output Above.. The Build Command Output setting displays the Dockerfile error.
Click Close. The PHP Script Executor with the SQLSRV module is now available in the list of languages when creating a new script.
Reference Environment Variables and Magic Variables in your Scripts.
‌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.
‌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).
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).
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).
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).
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).
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).
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).
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.
The following sample PHP script provides an example to retrieve a single Task using its Task ID.
The following sample PHP script provides an example of completing a Task when the Task ID is known.
Follow an example that uses a Process, a custom Script Executor and a Script to migrate records in a Microsoft Excel spreadsheet to a Collection.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Script Executor; Collection; administration; Microsoft Excel; record migration; employee data
This example demonstrates how to migrate records in a Microsoft Excel spreadsheet to an existing Collection. In this example, the Collection stores information about each company employee, such as each employee's first and last name, hire date, salary, and how many vacation days used. These employee records already exist in an Excel spreadsheet, but must be migrated to the Collection to save time and prevent human error. The Collection must already exist with its Screens that correspond with the fields in the Excel spreadsheet records.
While it would be easier to export a Comma-Separated Values (CSV) file from the Excel spreadsheet and then import that CSV file into the Collection to automatically create multiple records, this use case and its accompanying ProcessMaker Platform assets benefits those organizations where business stakeholders do not have access to Collections or the appropriate permissions to edit them. Any User may benefit from this use case.
This example uses the following ProcessMaker Platform assets:
Process: This example uses a Process named "Excel Spreadsheet Records to Collection Records Example," which may be downloaded for this example and then imported. Except for the Script Executor and Collection, the remaining ProcessMaker Platform assets in this example import with the Process and are already referenced in appropriate Process model nodes. This Process manages the migration process as summarized below:
A specified Request participant uploads the Excel file from which to migrate its records to the Collection.
A Script reads the Excel file records and stores them in that Request's JSON data model.
A specified Request participant reviews the migrated Excel file records.
If that Request participant indicates that the Excel file records read correctly, save those records to an existing Collection; otherwise, workflow returns to the same Request participant who uploaded the Excel file to do so again.
Script Executor: This example uses a custom Script Executor based on the default PHP Script Executor, but requires the PHPSpreadsheet. The PHPSpreadsheet is an open-source PHP library that reads and writes spreadsheet files. Note that after creating this Script Executor, it may be used for any Script that uses PHP and requires the PHPSpreadsheet.
Scripts: This example uses the following Scripts:
Read Excel File to JSON: This Script reads the records from the Excel file, then stores the Excel spreadsheet records in that Request's JSON data model. This Script runs from the custom PHP Script Executor to read the records from the Excel spreadsheet. By default, this Script stores the Excel spreadsheet records in a Request variable named persons
.
Save Records to Collection: This Script writes the records stored in the Request variable persons
to the Collection.
Screens: This example uses the following Screens:
Upload Person Records: This Screen allows a specified Request participant to upload the Excel file from which to migrate its records.
Review Uploaded Person Records: This Screen allows a specified Request participant to review the migrated Excel file records and then indicate if those records migrated correctly.
The Collection uses its own Screens which are not relevant to how this example functions.
Collection: This example uses an existing Collection to save the read spreadsheet records that the Save Records to Collection Script writes to create the Collection records. This Collection contains 18 records already to demonstrate the content of each record and how fields in the Excel spreadsheet must correspond with the Collection content.
Click the video below to watch a demonstration of this example.
This example contains the following procedures in this order:
Import the Collection: Since the purpose of this example is to demonstrate how to use a custom Script Executor, this example provides the Collection that the example uses. See Import the Collection.
Import the Process: Import the Process that this example uses. The Process contains the two Scripts and Screens this example uses. See Import the Process.
Create the custom Script Executor: Create the Script Executor that builds the PHPSpreadsheet into its Docker container. See Create the Custom Script Executor.
Configure the Script that reads the Excel file: Configure the Script named "Read Excel File to JSON" to run using the custom Script Executor. See Configure the Script That Reads the Excel File.
Download the Excel file: Download the Excel file that contains sample records to be migrated to the Collection. See Download the Excel File.
Start a Request: Start a Request for the Process this example uses. See Start a Request for the Example Process.
Prior to importing the Collection, download the Collection this example uses named people.json
:
Follow these steps to import the Collection as described in this example:
View your Collections. The Collections page displays.
Click Browse to locate the Collection you downloaded named people.json
.
Click List Collections. The Collections page displays.
Make note of the imported Collection's ID as displayed in the Collection ID column. This ID is required to specify to which Collection to write the read Excel spreadsheet records that are stored in the persons
Request variable during a Request. You will revise the Collection ID after you import the Process for this example.
View the records for the Collection named People that this example uses.
View a record in this Collection to see an example of the information to be migrated from the Excel spreadsheet.
Prior to importing the Process, download the Process model this example uses named Process - Excel Spreadsheet Records to Collection Records Example.json
:
Below is the Process model after the Process described in this example is imported and edited in Process Modeler.
Follow these steps to import the Process:
View your active Processes. The Processes tab displays.
Click the Import button. The following message displays: You are about to import a Process. After importing, you can reassign users and groups to your process.
Click Browse to locate the Process model you downloaded named Process - Excel Spreadsheet Records to Collection Records Example.json
.
Click Import. The Import Process screen displays.
From the Configuration section, assign the Request participants and user accounts for this example. Follow these guidelines:
Assign the Start Event element named "Start Event" to the user and/or group
Assign which user and/or group can start a Request of your imported Process. Type into the Assign Start Event setting to filter users and/or groups that display in that setting's drop-down menu. If you will start a Request for this example, then assign the Start Event element to your user.
Assign the Form Task element named "Upload File" to the user and/or group
Assign which user and/or group uploads the Excel file to the Process from which its records migrate to the Collection. Type into its Assign Task setting to filter users and/or groups that display in that setting's drop-down menu. Optionally, use the Requester option to assign that Task to the user that started that Request.
Assign the Form Task element named "Review Upload" to the user and/or group
Assign which user and/or group reviews the records after they have been read from the Excel file. Type into its Assign Task setting to filter users and/or groups that display in that setting's drop-down menu. Optionally, use the Previous Task Assignee option to assign the Task to the assignee of the "Upload File" Form Task.
Select which user to run the "Read Excel File to JSON" Script
Select which user account to run the "Read Excel File to JSON" Script, which is the Script that reads the Excel spreadsheet records and stores them to that Request's JSON data model. This Script runs when the Process File
Script Task element triggers. Type into its Run script setting to filter users and/or groups that display in that setting's drop-down menu. Ensure that the selected user or group members have appropriate permissions to run Scripts.
Select which user to run the "Save Records to Collection" Script
Select which user account to run the "Save Records to Collection" Script, which is the Script that writes the records stored in that Request's JSON data model to the Collection. This Script runs when the Save to Collection
Script Task element triggers. Type into its Run script setting to filter users and/or groups that display in that setting's drop-down menu. Ensure that the selected user or group members have appropriate permissions to run Scripts.
Assign which user and/or group can cancel Requests
Assign which user and/or group can cancel Requests for your imported Process. If no user or group are selected, no one can cancel a Request from this Process. Type into the Assign Cancel Request setting to filter users and/or groups that display in that setting's drop-down menu.
Assign which user and/or group can edit Request data
Assign which user or group has permission to edit Request data from this Process. By editing Request data, these users and group members can adjust the data that Request participants have submitted during a Request. If no user or group are selected, no one can edit Request data from this Process. Type into the Assign Edit Data setting to filter users and/or groups that display in that setting's drop-down menu.
Click Save. The Processes page displays the imported Process.
View and then edit the imported Process. The Process model displays.
The settings for this Script Task element display.
{
"recordsVariableName": "persons",
"collectionId": 18
}
Change the value of the collectionID
key name to the Collection ID you imported for this example.
Save the Process model.
Would you prefer to save the Excel spreadsheet records to a different Request variable than persons when the Read Excel File to JSON
Script that run when the Process File Script Task element triggers? Locate the Script Configuration setting for the Process File Script Task element as described above, and then change the JSON key name recordsVariableName
's value to the Request variable name you want:
{ "fileVariableName": "recordsFile", "recordsVariableName": "persons" }
Ensure to change the JSON key name recordsVariableName
's value for the Save to Collection
Script's configuration to the same value.
Follow these steps to create the custom Script Executor as described in this example:
View your Script Executors. The Script Executors page displays.
In the Name setting, enter the unique name for the Script Executor. This name displays from Script configuration settings, so enter a descriptive name that designers configuring their Scripts understand what customization this Script Executor provides. This example uses the name PHP with PHPSpreadsheet
.
In the Description setting, enter a description for the Script Executor.
From the Language setting, select the PHP option. The default Dockerfile content to run PHP Scripts displays in the Dockerfile setting. The Dockerfile content includes the SDK for that language.
From the Dockerfile setting, add the following commands that contain the dependencies to use the PHPSpreadsheet and integrate this into this Docker container:
RUN apt-get update -y \
&& apt-get install -y \
libpng-dev \
&& apt-get clean -y \
&& docker-php-ext-install gd zip \
&& docker-php-ext-enable gd zip
RUN composer require phpoffice/phpspreadsheet
Click Save and Build to build the Docker container from which the Script Executor runs Scripts. The Build Command Output setting displays below the Dockerfile setting as the Script Executor builds the Docker container in real-time. If the Docker container builds successfully, the following message displays: Executor Successfully Built. You can now close this window. If building the Docker container is unsuccessful, the following message displays: Error Building Executor. See Output Above.. The Build Command Output setting displays the Dockerfile error.
Click Close.
Follow these steps to configure the Scripts as described in this example:
View your Scripts. The Scripts page displays.
From the Script Executor drop-down menu, select the Script Executor you created for this example to run this Script.
Click Save.
The second Script this example uses, Save Records to Collection
, by default configures to use the Script Executor named PHP Executor
when it is imported.
Download the Excel file that this example uses to migrate its records to an existing Collection.
The example is ready to demonstrate. To demonstrate this example, start a Request of this Process.
Follow these steps to start a Request of this Process as described in this example:
Log on as a user you configured from the Start Event element that can start Requests for this Process.
Start a Request of this Process. Remember that the Process name is Excel Spreadsheet Records to Collection Records Example
.
Open the Upload File Task from your To Do Tasks. After opening the Task, the Screen to upload the Excel file in the example displays. Ensure that you have downloaded the Excel file.
From the Upload File Task, click the Select File button, locate the Excel file you downloaded, and then click the Upload File button.
The Review Upload Task automatically opens because the Upload File Form Task element in the Process model uses the Display Next Task to Task Assignee option. The Read Excel File to JSON
Script read the records from the Excel spreadsheet, stored them into the persons
Request variable, and now displays their contents in the Review Upload Task.
From the Review Upload Task, click the Save File button.
View the imported Collection records to see two additional records in this Collection that have been migrated from the Excel spreadsheet.
Click the Import button. The Import Collection screen displays.
Click Import. The Import Collection screen displays to indicate that the Collection imported correctly.
From the Import Process screen, locate the Configuration section below the Status section.
Select the Save to Collection
Script Task element that runs a Script to write the Excel spreadsheet records stored in that Request's JSON data model in the persons Request variable.
From the Configuration panel, locate the Script Configuration setting, and then click theicon to edit this Script's configuration. The Script Config screen displays with configuration settings the Request sends to the Script when the Save to Collection
Script runs.
Click the +Script Executor button. The Add New Script Executor screen displays.
Click the Configure iconfor the Script named Read Excel File to JSON
. The Edit Configuration page displays.
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.