3.6 - 3.8 - Plugin Development

Overview

Plugins are used to give additional functionality to ProcessMaker and/or customize its interface and databases. Supporting frameworks to create new plugins are:

• In ProcessMaker 3.0.1.8 - 3.5.9, the script to create new plugins is based upon the 3.0 interface using the Ext JS framework.
• As of ProcessMaker 3.6.0, the script uses the Vue.js framework to add icons.

It is not recommended to edit the framework source code because each version upgrade will overwrite any changes in the code. Instead, it is recommended to develop a plugin to modify the source code.

Plugins are developed using the gulliver new-plugin command on a Linux/UNIX server. Plugins cannot be developed on Windows servers, because symbolic links are needed. After the plugin has been created, it can be exported to other ProcessMaker installations, including Windows servers.

Restriction

Files within the custom plugins must have the UTF-8 encoding. The use of UTF-8-BOM or other encodings may cause issues with other ProcessMaker plugins.

Step 1: Setting Up the gulliver Script

ProcessMaker is programmed using a custom PHP development framework named Gulliver. To create a plugin in Gulliver, symbolic links have to first be established in the server where ProcessMaker is installed.

The gulliver script needs to be executed inside the workflow/engine directory. Log in to the ProcessMaker server as the root user or a user with administrative powers. Then, make a symbolic link from

For example:
ln -s /opt/processmaker/gulliver/bin/gulliver /opt/processmaker/workflow/engine/gulliver

Plugins cannot be created on Windows servers, because Windows does not support symbolic links; however, there is an experimental script for Windows servers available at:

Options of the gulliver Script

As the root user (or a user with administrative permissions), go to the <INSTALL-DIRECTORY>/processmaker/workflow/engine/ directory. Then, execute the php gulliver command to see a list of the available options.

For example:

The gulliver script can only be executed when the current working directory is /processmaker/workflow/engine/, so don't try to execute it without first changing to that directory.

Step 2: Creating a New Plugin

Before creating a plugin, read the following considerations about the name:

• Plugin names must include only ASCII characters that can easily be used in a web address.
• Do not use characters like "ë", "Ñ", "?", "%", or " " (space).
• Do not use hyphens; otherwise, ProcessMaker will not be able to import the plugin.
• "Plugin" is a reserved word in ProcessMaker, so do not include it in the name of the new plugin.
• Plugin names are case sensitive.
• Plugin names must start with letters. Do not start with numbers.

To create a new plugin, use the command:

For example, create a plugin named "deleteCases":

The new-plugin script will ask a series of Yes/No questions:

• Change system logo [y/N]: See System Logo below.
• Create an example Page [y/N]: See Example Page below.
• Create new option in the menu of cases [y/N]: See New Options in the Cases Sidebar below.
• Create the Role 'PROCESSMAKER_PLUGIN-NAME' and the Permission 'PM_PLUGIN-NAME' [y/N]: See New Role and Permission below.
• Create external step for Processmaker [y/N]: See External Step below.
• Create an element for the Processmaker Dashboards [y/N]: See Dashlet for the Dashboard below.
• Create a PmFunction Class for extending Processmaker [y/N]: See PMFunction Class below.

Plugin Files

The new plugin will be created in a new plugins/pluginName directory located in the parent directory where ProcessMaker is installed. The new plugin directory will have a minimum of 4 subdirectories (classes, config, data and public_html), 2 php files, 3 xml files and 2 ini files:

These files and directories have the following purpose:

For example, if the "deleteCases" plugin is created in an installation of ProcessMaker at /opt/processmaker/, then the following directories and files will be automatically created:

pluginName.php

Inside this file the class of the plugin can be found where the user can modify the basic elements or information about the plugin.

As of ProcessMaker 3.6.0, remove the following line:

Instead, add the following line:

Importing Additional Files into a Plugin

The recommended way to import an additional file into a plugin is to use the defined constant PATH_PLUGINS, which is set to the path of your /workflow/engine/plugins/ directory. If wishing the additional file to be automatically imported when the plugin is loaded, then add it to the setup() function.

For example, an additional PHP code file is placed in the location /opt/plugins/deleteCases/deleteCases/classes/validation.php. To import this code, when the plugin is loaded, add the following line to the setup() function:

Files which are placed in the plugin's public_html directory are publicly accessible under the URL:
   http://domainOrIP/plugin/pluginName/filename.ext

For example, the file /opt/plugins/deleteCases/deleteCases/public_html/icon.png which is included in a plugin and then imported into a ProcessMaker server located at https://pm.example.com can be accessed at the URL:
   http://pm.example.com/plugin/deleteCases/icon.png

It is recommended to use a relative URL, that doesn't include the domain name or IP number, so that the file can be accessed in any server that imports the plugin. For example, the same file could be displayed in an HTML file with this code:

The file can also be accessed using its path on the ProcessMaker server with the PATH_PLUGINS constant:

Step 3: Yes/No Questions

The gulliver new-plugin script will ask a series of yes/no questions about the new plugin. If the response is "y" (yes), then additional files will be created in the new plugin directory and additional code will be added to the pluginName.php file. To better understand the plugin methods used in this file, see the code in:

System Logo

To display a new logo (the image in the upper, left hand corner of the interface) in ProcessMaker, then enter "y" for the following option:

Entering "y" will generate the following file:

A PNG image file will be generated in the plugin's public_html directory, such as:

The image will appear as:

The following code will also be added to the /plugins/pluginName/pluginName.php file:

To use a different image, simply place the image file in the public_html directory and change the path to reference that new image. For example, if using a logo located at /opt/plugins/deleteCases/deleteCases/public_html/myCompanyLogo.png, then change the path to:

Example Page

To allow the plugin to create a new top-level menu and display a new page in ProcessMaker, then enter "y" for the following option:

Entering "y" will generate 5 sample files that can be used as a model for creating pages in ProcessMaker:

For example:

The pluginName/menupluginName.php file contains code that adds a new top-level menu to the ProcessMaker interface, which appears as pluginName - APPLICATION1 by default.

Take into consideration that only one top-level menu item can be created per plugin, so create multiple plugins for multiple top-level menus.

By default, clicking on this new menu item will direct the web browser to the address:

http://<IP-ADDRESS>:<PORT>/sys<WORKSPACE>/<LANG>/<SKIN>/<pluginName>/<pluginName>Application

For example:

http://www.example.com/sysworkflow/en/classic/deleteCases/deleteCasesApplication

When the browser is redirected, a list of users will be displayed:

This page is generated by the following four files:

Data generally comes from a database query, but in this sample page, all the names in the list come from an array in the pluginNameApplication.js file and the numbers are randomly generated.

Another new menu option will be added the top-level ProcessMaker menu, with code that is inserted in the plugins/pluginName/pluginName.php file.

The PMPlugin::registerMenu() method is used to register the new menu option. The first parameter is the name of the menu where the option will be added at the end. 'processmaker' is the main ProcessMaker menu. The second parameter is the name of the file that defines the new menu option, which should be located in the plugins/pluginName/pluginName/ directory.

For example:

The menupluginName.php file (which in this example is menudeleteCases.php) will be created to define the new menu option. The following code adds the new menu to the ProcessMaker main menu with the Menu::AddIDRawOption() method:

$G_TMP_MENU is a global variable that is an instance of the Menu class defined in gulliver/system/class.menu.php. The Menu::AddIdRawOption() method is used to add a new menu option to the $G_TMP_MENU global variable. The parameters of this method can be edited to define a different menu ID, execute a different file when the user clicks on the menu option, and/or change its text label.

For example, to make the menu option execute a custom code file located at /opt/plugins/deleteCases/deleteCases/manageCases.php and use the text label "Manage Cases" instead of "deleteCases - application1", change the code to:

Embedding in an <iframe>

By default, the sample page will be displayed inside the principal window of the web browser. If the sample page should be displayed inside an <iframe> under the main ProcessMaker menu, then the plugin files need to be edited.

First, edit the $G_TMP_MENU->AddIdRawOption() function in the menupluginName.php file so that it executes a different code file when the user clicks on the menu item.

For example, change menudeleteCases.php file from:

To:

Then, create a file named main.php in the same directory with the following content:

Finally, create another file named mainLoad.php in the same directory, with the following content:

Now, when the user clicks on the menu item, it will first load the main ProcessMaker menu, then create an <iframe> under the menu that displays the contents generated by the deleteCases/deleteCasesApplication* files.

New Options in the Cases Sidebar

To add several new options to the cases sidebar under the Home menu, enter "y" at the following question:

Entering "y" will cause the following 11 files to be created:

The file pluginName/menupluginName.php is created to define 3 new options to be added to the cases sidebar. In addition, code is inserted into pluginName/pluginName.php to register a new option in the cases sidebar with the PMPlugin::registerMenu() method. For example:

As of ProcessMaker 3.6.0, the code above is:

A new option named "deleteCases application1" has been added above the inbox in the sidebar of the Home panel. When clicked, it displays the same list of users as the Example Page, but the page will be embedded in the casesSubFrame frame.

As of ProcessMaker 3.6.0, the result is something like:

A new header has also been added to the bottom of the sidebar named "deleteCases application2". Under that header is an item named "deleteCases application2", which displays the following page when clicked:

This page is generated with the following files:

• deleteCases/deleteCasesApplication2.php
• deleteCases/deleteCasesApplication2.html
• deleteCases/deleteCasesApplication2.js

Another header was also added to the sidebar named "deleteCases application3". Clicking on it displays a panel with the text "Content 3":

This page is created with the files:

• deleteCases/deleteCasesApplication3.php
• deleteCases/deleteCasesApplication3.html
• deleteCases/deleteCasesApplication3.js

New Role and Permission

To use ProcessMaker's role based access control (RBAC) so only users with the designated permission in their role will be able to access the plugin and its functionality, then enter "y" for the following option:

Entering "y" will add the following code to the pluginName.php file to generate a new role and permission:

Where:

• $roleData['ROL_UID']: The unique ID of the new role.
• $roleData['ROL_PARENT']: It's outdated and should always be set to '' (an empty string).
• $roleData['ROL_SYSTEM']: It should always be set to '00000000000000000000000000000002', which is the ID of the ProcessMaker system.
• $roleData['ROL_CODE'] The name of the new role, which is set to PROCESSMAKER_pluginName in upper case by default. The name can be changed, just make sure that it doesn't conflict with the names of any existing roles.
• $roleData['ROL_CREATE_DATE']: The date and time in the format "YYYY-MM-DD HH:MM:SS" when the plugin was created.
• $roleData['ROL_UPDATE_DATE']: The date and time in the format "YYYY-MM-DD HH:MM:SS" when the plugin was last updated.
• $roleData['ROL_STATUS']: Set to '1' to activate the new role and assign it to users. Otherwise, set to '0' if the new role shouldn't be assigned to users.
• $RBAC->createPermision ('PM_pluginName' ): Creates the name of the new permission, which is set to PM_pluginName in upper case by default. It can be changed as long as it doesn't conflict with the names of any existing permissions.

Creating the New Role and Permission

The code in the install() function will be executed when the plugin is imported into ProcessMaker. Therefore, the new role and permission will only be created in ProcessMaker when the new plugin is imported.

First, use the gulliver pack-plugin script to create an exportable .tar file for the plugin to be imported. Then, go to ADMIN > Plugins > Plugin Manager. Click on the Import button and select the plugin's .tar file to import it. Even if the plugin already appears in the list of available plugins, import the plugin again so it will execute the install() function and create the new role and permission. Finally, activate the new plugin, and the new role and permission will be available in ProcessMaker.

Redirect After Login

If a new role and permission was created in the previous step, another option to redirect users with that role to a specified page after logging into ProcessMaker will be shown. To redirect, enter "y" at this option:

Entering "y" will add code like the following to the pluginName.php file:

By default, the plugin redirects to the user list, but this can be changed. For example, to redirect all users with the PROCESSMAKER_DELETECASES role to the deleteCases/deleteCasesApplication.php page on login use the following code:

External Step

Note: The External Step feature is not available for ProcessMaker Mobile as step: it will not open the case or create a case if the External Step is the first on the display list. This feature will be implemented in future versions.

To create a custom external step for tasks, similar to steps like Dynaforms, Input Documents and Output Documents, enter "y" at this option:

Note: The external step will appear as an available step in all processes in the workspace.

Entering "y" will add a file like the following:

This file will need to be edited to add the code to handle the external step. Code will also be added to the pluginName.php file, like the following:

The first parameter of the registerStep() method is the external step's unique ID number, which was automatically generated by ProcessMaker. The second parameter is the name of the file(s) (without the extension) that will be executed when running the step. The third parameter is the name of the external step that is displayed to the user in ProcessMaker. Feel free to edit the external step's name.

The following files will be added to the plugin:

• pluginName/steppluginNameApplicationAjax.php: Defines custom functions built by the user, which can be invoked from the steppluginNameApplication.php file.
• pluginName/steppluginNameApplication.html: Defines the HTML code for the external step. By default, just defines an empty div with the id "{$form_id}".
• pluginName/steppluginNameApplication.js: Gives the external step the functionality to hide or show fields using JavaScript code.
• pluginName/steppluginNameApplication.php: Contains code to invoke the functions of the steppluginNameApplicationAjax.php file and to call functions of the ProcessMaker core.

When a case is executed with an external step, these files will display the following table of system variables from the case:

Adding an External Step to a Process

After importing and activating a plugin with an external step, the external step can be assigned as a step in a task.

Go to the DESIGNER and open a process for editing. Then, right click on a task in the process and select Steps from the dropdown menu. Locate the External(s) option where the "deleteCases" external step will be found. The external step created by the plugin should appear in the list of available steps. Drag and drop the "deleteCases external step" from the Available Elements section to the Assigned Elements section as seen in the image below.

Once the external step is dropped into the Assigned Elements section it should now appear in the list of steps added to the task.

Now the external step will be executed at this task when a case is executed.

Editing External Steps

The default external step files created by the gulliver new-plugin script can be edited to add custom content. It is important that the external step page contains links or buttons to go to the previous and next steps.

If using Ext JS to generate the page, the following JavaScript code can be used to create a previous step button in an Ext JS toolbar:

Likewise, the following JavaScript code can be used to create a next step button in an Ext JS toolbar:

In order for these links to have the proper URL and label, the CONFIG variable needs to be passed to the JavaScript file with the HeadPublisher::Assign() method in the PHP file.

By default, the gulliver new-plugin script creates the steppluginNameApplication.php file to set the URLs and labels for the "Previous Step" and "Next Step" links:

For example, the stepdeleteCasesApplication.php file contains:

Dashlet for the Dashboard

To create a custom dashlet that will be added to the Dashboard, enter "y" at this option:

Entering "y" will create two additional files in the plugin like the following:

Inside the plugins/pluginName/pluginName.php file, the following lines will be added to the pluginNamePlugin class:

To change the title and description of the new dashlet, edit the values of the "DAS_TITLE" and "DAS_DESCRIPTION" keys in the dashletsUids array.

Code to control the new dashlet is located in the file plugins/pluginName/pluginName/classes/class.dashletpluginName.php and a template for the content of the new dashlet is located in the file plugins/pluginName/pluginName/views/dashletpluginName.html. Edit these two files to modify the dashlet or simply add content to the public_html directory and change the code to use that content.

To display tables or graphs based on case data, it is recommended to export the case data in Report Tables, so it can be more easily queried. To display information in the dashlet about cases, query the wf_workspace.APPLICATION table in the database to get a list of cases and the wf_workspace.APP_CACHE_VIEW table to get a list of the tasks that have been assigned to the users in each case.

PMFunction Class

The last option sets the configuration, classes, and additional functions for the plugin:

Regardless of entering "y" or "n", the following files will be created:

The pluginName.php file defines a class for the plugin named pluginNamePlugin, which is based upon the PmPlugin class defined in workflow/engine/classes/class.plugin.php. This class sets up the plugin and registers it in ProcessMaker. The contents of the setup() and install() methods depend on which of the previous options were selected, but at a minimum this file contains code similar to the following:

PMPlugin Class Methods

The custom pluginNamePlugin class inherits a number of class methods from its parent PmPlugin class. If these methods aren't redefined in pluginNamePlugin, then the default methods from PmPlugin will be used.

It may be useful to redefine the following methods:

• setup(): This method is automatically executed by workflow/public_html/sysGeneric.php, which is called when a ProcessMaker page is loaded. setup() will be executed almost every time a user clicks on the ProcessMaker interface, so add code that will be executed with every user interaction. However, remember that the code could potentially slow down ProcessMaker, so avoid code that waits for responses from remote servers. If that kind of code is necessary, it is a good idea to implement it as a code file, which is called only when the plugin is used.
• install(): This method is called when the plugin is installed, i.e., when the plugin is imported into processMaker by going to ADMIN > Plugins and clicking on Import.
• enable(): This method is called when the plugin is enabled, i.e., when going to ADMIN > Plugins > Plugin Manager, selecting the plugin and clicking on Enable.
• disable(): This method is called when the plugin is disabled, i.e., when going to ADMIN > Plugins > Plugin Manager, selecting the plugin and clicking on Disable.
• uninstall(): This method is called when the plugin is uninstalled. Note that recent versions of ProcessMaker no longer have a Remove button to uninstall plugins so this method will never be called through the interface.

To define custom versions of these class methods, add them to the definition of the pluginNamePlugin class:

The pluginNameClass Class

The pluginName/class.pluginName.php file defines the pluginNameClass class, which is also based upon the PmPlugin class. The content of its methods also depends upon the previously selected options, but at a minimum it contains a private __construct() method that is called whenever a class instance is created, and a private setup() method that is called when a page is loaded in ProcessMaker.

For example:

Custom methods and member variables can be added to the pluginNameClass class. The inherited methods from PmPlugin can also be defined in the pluginNameClass class.

Custom pmFunctions

If "y" was entered, then in addition to the files above, the following file will also be created:

The pluginName/classes/class.pmFunctions.php file is used to define any special functions for the plugin, which can be called from inside a trigger like normal ProcessMaker Functions. These custom functions can be given any name, but the convention is to use names like pluginName_function-name(), so they can easily be distinguished from the standard ProcessMaker and PHP functions used in triggers.

By default, the class.pmFunctions.php file contains two sample functions named pluginName_getMyCurrentDate() and pluginName_getMyCurrentTime() to return the current date and current time.

For example:

New custom functions can be added. For example, to add a custom function named deleteCases_getCaseStatus() to return the status of a case:

As long as the plugin is activated, the deleteCases_getCaseStatus() function can be called in a ProcessMaker trigger. For example:

When the plugin is created, the following code is automatically added to the pluginName.php file to incorporate the plugin's custom functions into ProcessMaker:

Step 4: Linking the Plugin Files into ProcessMaker

After using the gulliver new-plugin script to create the new plugin, create symbolic links from the plugin's PHP file and its directory to the <INSTALL-DIRECTORY>/workflow/engine/plugins/ directory so the new plugin can be used by ProcessMaker.

For example:

Creating symbolic links is the recommended way, but another way to make the plugin available to ProcessMaker is to copy its files directly into ProcessMaker's plugin directory.

For example:

Step 5: Activate the New Plugin

After linking or copying the plugin's files into the ProcessMaker file system, log in to ProcessMaker as the admin user (or another user with the PM_SETUP_ADVANCE permission in his/her role). Go to ADMIN > Plugins > Plugins Manager and select the new plugin, which should appear in the list. Then, click on the Enable button to activate the plugin. The new plugin should now be ready to be used. To see any new changes to the interface (such as new menus), refresh the web browser.

Note: Each time the menu is changed in the plugin's files, the plugin will need to be deactivated and then reactivated for those changes to appear in the ProcessMaker interface.

Altering the Database Structure

Plugins can be used to alter the structure of the database(s) used by ProcessMaker. To add tables and/or fields to a database, complete these steps in order:

1. Edit the Propel XML schema file(s) to define the additional tables and/or fields.
2. Run the gulliver propel-build-model script to construct Propel classes for the data objects.
3. Run the gulliver propel-build-sql script to generate the SQL files to alter the database.
4. Run the gulliver propel-build-crud for each table to update the database.

Editing the Propel XML Schema File

Changes are made to the ProcessMaker database(s) through the XML schema file located at plugins/pluginName/pluginName/config/schema.xml, which is generated by the gulliver new-plugin script.

Edit the schema.xml file to add the tables and fields used by the plugin. By default, it contains:

To add tables and/or fields to a database, first indicate which database they should be added to in the <database name="DB-NAME"> tag. The DB-NAME is one of the databases used by the current workspace:

• "workflow" : The wf_<WORKSPACE> database
• "rbac" : The rb_<WORKSPACE> database
• "report" : The rp_<WORKSPACE> database

The <table name="TABLE-NAME"> tag is used to indicate the name of the table to be modified. The "TABLE-NAME" can either be a new table or an existing table in the database. Remember that MySQL table names are case sensitive by default in Linux/UNIX, but not in Windows. To make a cross-platform plugin, it is recommended to put table names and field names in UPPER CASE. Make sure that the same TABLE-NAME is used in the tag: <parameter name="Name" value="TABLE-NAME"/>

Fields in each table are defined with the <column name="FIELD-NAME"> tag. The properties of each field can be defined inside the <column name="FIELD-NAME" PROPERTIES/> or through separate <parameter name="PROPERTY-NAME" value="PROPERTY-VALUE"/> tags.

For example, this XML code:

Creates the same "PLG_UID" field as this XML code:

Note that the first definition uses Propel's universal properties, which are valid for all types of databases, whereas the second example uses properties that are specific to MySQL. This same "PLG_UID" field can be created using both forms of the properties:

The sample schema.xml file created by the gulliver new-plugin script duplicates the definition of each field property using both universal and MySQL properties, but that duplication is unnecessary and is not recommended. The same sample file can be written in a shorter form, such as:

For more information about Propel XML schema files, see the Propel Manual. For more examples of XML schema files, see the following files that define the <wf_<WORKSPACE> and rp_<WORKSPACE> databases in ProcessMaker:

• <INSTALL-DIRECTORY>/rbac/engine/config/schema.xml
• <INSTALL-DIRECTORY>/workflow/engine/config/schema.xml

Creating Classes with gulliver propel-build-model

After editing the config/schema.xml file, run the following script to generate the Propel classes for the tables defined in the schema file:

For example:

Note: As of ProcessMaker 3.2.2, the build result varies because the thirdparty folder is no longer part of the gulliver folder.

The propel-build-model script will add the following files to the plugin:

Note: Gulliver propel-build-model script needs to have the XSL module installed in PHP for XSLT parsing. Otherwise, the following error message will appear:

To install the XSL module:

In Debian/Ubuntu:

In Red Hat/CentOS/Fedora:

Creating SQL Files with gulliver propel-build-sql

After generating the Propel classes, create the SQL files that will insert new tables/files into the database:

The <db-type> will be "mysql", since ProcessMaker runs on a MySQL database. For example, to generate the SQL files for the "deleteCases" plugin:

Applying Changes With gulliver propel-build-crud

After generating the SQL files, apply the database changes to each new or altered table:

Step 6: Creating Exportable Plugins

After creating the new plugin, use the gulliver pack-plugin script to pack the plugin files into a tar archive that can be exported.

Using the gulliver pack-plugin Script

From the command line, log in as the root user or any user with rights to the plugins directory. Then, change to the workflow/engine directory and execute the gulliver pack-plugin script.

Remember that the pluginName is case sensitive and needs to be spelled exactly the same as the plugin's directory.

For example, to create an export file for the deleteCases plugin:

The .tar file created by the gulliver pack-plugin script will be named NAME-VERSION.tar and will be located in the plugins/pluginName directory. If the tar file already exists, it will automatically be overwritten.

Then, copy the plugin's .tar file to the local computer. If working on a remote server, then scp in Linux/UNIX or pscp in Windows can be used to copy the .tar file to the local computer.

For example in Linux/UNIX:

Importing a Plugin

After using the gulliver pack-plugin script to create a tar file for the plugin, log in to ProcessMaker as a user, such as the admin, who has the PM_SETUP_ADVANCE permission in his/her role. Go to ADMIN > Plugins and click on the Import button. Select the plugin's tar file and click on Import to upload and install the new plugin in ProcessMaker.

The new plugin should appear in the list in the Plugins Manager. Then, activate the new plugin to use it.

Note: Importing a plugin that already exists in ProcessMaker will overwrite the existing plugin. This is the proper way to upgrade plugins that already exist in ProcessMaker.

Create Custom Menu Icons

Available Version: As of ProcessMaker 3.6.0

To have visual descriptive menus, add icons next to the menu name. Due to the Vue.js framework, there are two ways to add icons to the custom left menus.

• By configuring each menu function of the plugin file.
• By creating a new setting file where is using the AddIdRawOption() function.

Remember to add icons before to package the plugin.

Add Icons Through the Plugin File

This method involves the following:

• Select the menus order by setting the Index value.
• Similar view as in previous versions to ProcessMaker 3.6.0 with groups and subgroups.

Follow the next steps to add icons:

1. The icons supported are the Font Awesome. Go to this page.

   

2. Click a selected font. Font details display.

3. Copy the i class value for the font to use as a custom icon.

   

4. Go to the plugin directory /opt/plugins/testPlugin/testPlugin.

5. Open the menuCasestestPlugin.php file, which was created for the Home left menu.

   nano menuCasestestPlugin.php

6. For each menu function, in the ​$tmpIcons​, replace the null value by the copied value in the step 3.

   

7. Using the $index setting, select the menus order in the left menu.

8. To correctly enable and disable plugin, clean the cache or open and close the web browser.

Add Icons Through the AddIdRawOption() Function

For this method, take into account the following:

• It does not support the menus order. Plugin menus and icons locate at the end of the left sidebar by default.
• The menu display asterisks preceding and after the plugin name.
• Vertical scroll displays in the menu.
• The menu with ​blockHeader​ does not display as a folder.

Follow the next steps to add icons:

1. In the plugin directory /opt/plugins/testPlugin/testPlugin, create the ​menuHome.php​ file by running the command nano menuHome.

2. In the new file copy the following code that the menuCasestestQA.php file uses to replace the default icons with those for the custom plugin:

   AddIdRawOption('ID_TESTQA_MNUCASE_01', '../testQA/testQAApplication', G::LoadTranslationPlugin('plugins', 'NH1 - testQA application1'), 'fas fa-user', '', ''); $G_TMP_MENU->AddIdRawOption('ID_TESTQA_MNUCASE_02', null, G::LoadTranslationPlugin('blockHeader', 'NH2 - testQA application2'), 'fas fa-camera', '', ''); $G_TMP_MENU->AddIdRawOption('ID_TESTQA_MNUCASE_03', '../testQA/testQAApplication2', G::LoadTranslationPlugin('plugins', 'NH3 - testQA application2'), 'fab fa-font-awesome', '', ''); $G_TMP_MENU->AddIdRawOption('ID_TESTQA_MNUCASE_04', '../testQA/testKarlApplication3', G::LoadTranslationPlugin('blockHeaderNoChild', 'NH4 - testQA application3'), 'fas fa-air-freshener', '', '');

3. In the plugin file testQA.php add the following line to register the main menu Home: $this->registerMenu("home", "menuHome.php");

4. Pack the plugin as in Creating Exportable Plugins.

Creating Custom Pages

In ProcessMaker 3.0, either Gulliver + XML->HTML + Maborak or Gulliver + HTML + Ext JS can be used to generate custom pages in plugins. Gulliver is a custom PHP framework and Maborak is a custom JavaScript library used by ProcessMaker.

Ext JS generates very nice interface objects and is very flexible; however, it is more difficult to generate a basic page using Gulliver + HTML + Ext JS. In contrast, it is much easier to generate basic pages using Gulliver + XML->HTML + Maborak. Unfortunately, the Maborak framework is not documented, hard to understand, and not very flexible. It generates simpler interfaces compared to Ext JS. Nonetheless, it is much easier to create pages using Gulliver + XML->HTML + Maborak, because the same XML used to create Dynaforms can be used to create custom pages for a plugin.

Custom Pages with HTML + Ext JS

To create a custom page using Gulliver + HTML + Ext JS, create the following five files:

• A PHP Page Setup file: Sets the HTML and JavaScript files for the custom page, passes variables to the JavaScript, and then renders the page.
• A HTML Template file: Sets the HTML content of the page. If using Ext JS to generate the interface items, this often is just an HTML page with an empty <div> that serves as a container for the HTML generated by Ext JS.
• An Ext JS code file: Generates the content for the custom page, such as toolbars, buttons, links, fields and labels.
• A PHP AJAX file: Handles the submission of forms from the page and any AJAX calls.
• A PHP Menu file: Creates a menu item that displays the custom page when clicked.

PHP Page Setup

To setup a custom page to be displayed using Gulliver + HTML + Ext JS, create a PHP file that does the following steps:

• First, get a single instance of the [class|headPublisher] class using the headPublisher::getSingleton() method. Remember that the Gulliver framework should only use a single instance of the headPublisher (or Publisher class for displaying pages.
• Then, use the headPublisher::addContent() method to add one or more HTML files to the next page that will be displayed.
• Then, use the headPublisher::addExtJsScript() method to add one or more JavaScript files to be executed when the HTML files are loaded. The Ext JS library is used to create interface items, forms and fields that will be inserted in the HTML code.
• Then, use the headPublisher::assign() method to set JavaScript variables, which can be used by the JavaScript code to generate content in the HTML. For example, links, labels and the values in fields can be passed to the JavaScript.
• Finally, call G::RenderPage() to generate the content of the next page and display it.

Creating a cron Using ProcessMaker Classes

To create a cron using ProcessMaker classes, first create a PHP file by following the steps below:

• First create the PHP file, for example Plugin_File_Name.php inside the services folder.
• Then, add the following code:

• Then, create a different PHP file, myClass.php, where the code that will be executed by the cron will be introduced. Actions the code might do include sending emails, starting cases automatically, assigning permissions, etc.

Extending the ProcessMaker REST API

Extend the REST API in ProcessMaker by changing the code inside the deleteCases.php file. Take into consideration that when a plugin is created there are two files, which include:

• A folder (deleteCases)
• A php extension file (deleteCases.php)

Remember that the deleteCases.php file is critically involved when introducing modifications into the plugin. Both files have the same name of the plugin created. Open deleteCases.php in an editor. Observe the image below for guidance.

After the editor has been opened in any remote control program (for example Mobaxterm) the following script must be added:

Add the script in the public function enable() section and paste it after the following code:

Save the file and close it.

Now, go into the deleteCases plugin directory:

Inside deleteCases proceed to create the following new directories:

Note: Take into consideration that the DeleteCases folder refers to the name of the plugin. This name must have the first letter in uppercase, for example "PluginName".

Then, inside Delete Cases create a file named "Sample.php". The final result of the structure created is the following:

The created Sample.php file will look like the image below:

Once this file has been created in the new directory, edit the file and add the following code:

Observe the image below for guidance:

After including the script, save the Sample.php file and start using this extension by enabling the plugin being used in ProcessMaker.

Consuming an API Endpoint

After extending the REST API in ProcessMaker it can be consumed by an endpoint. This endpoint, which is a unique URL representing an object, can be tested by using the Postman extension in Chrome. This test will be a response test of the working endpoint, which is a message in this case. To obtain this message an "access_token" must be obtained and with that token the message will be able to be seen. First of all, to call any ProcessMaker Endpoint, the external application needs to be registered in OAuth to obtain the "Client ID" and the "Client Secret".

After getting the access token, go to the Headers tab in Postman and copy the token number next to the Bearer as seen in the image.

Change "POST" to "GET" in the dropdown and change the URL field to obtain the message from the Sample.php file. The URL must have the following structure: http://{ProcessMaker-Server}/api/1.0/{workspace}/{PluginName}/{class}/{function}/{var}

This will work with the code in the Sample.php file, which contains the following code:

The image below shows an example of how the URL must be constructed:

Where:

• Sample: The PHP class to be called.
• Hello: A method inside this class.
• John: The input variable ($var) sent to this method.

Finally, click on Send to receive the message intended as seen in the image below.