2.0.36 - Plugin Development

By default the sample page will be displayed inside the principal window in 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 which displays the contents generated by thedeleteCases/deleteCasesApplication* files.

New Options in the Cases Sidebar

To add several new options in 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 in pluginName/pluginName.php to register a new option in the cases sidebar with the PMPlugin::registerMenu() method. For example:

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

A new header has also been added to the bottom of the sidebar named "deleteCases application2". Under that header is an item also 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 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

If the plugin will need to use ProcessMaker's role based access control (RBAC) so that 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 for the new role.
• $roleData['ROL_PARENT']: It's deprecated and should always be set to (an empty string).
• $roleData['ROL_SYSTEM']: It should always be set to '00000000000000000000000000000002' which is the ID for the ProcessMaker system. (In previous versions, there used to be an RBAC system with the ID '00000000000000000000000000000001', but it is no longer used.)
• $roleData['ROL_CODE'] The name of the new role, which by default is set to PROCESSMAKER_pluginName in upper case. 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' if the new role is activated and can be assigned 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 by default is set to PM_pluginName in upper case. 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 which can be imported. Then, go to ADMIN > Plugins > Plugin Manager. Click 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 were created in the previous step, a further question will be asked whether to redirect users with that role to a specified page after logging into ProcessMaker. 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's list, but this can be changed. For example, for all users with the PROCESSMAKER_DELETECASES role to be redirected to thedeleteCases/deleteCasesApplication.php page on login:

External Step

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

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

This file will need to be edited to add the code to handle the external step. In addition, code will 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) which will be executed when running the step. The third parameter is the name of the external step which 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: The
• pluginName/steppluginNameApplication.html: Defines the HTML code for the external step. By default, just defines a div with the id "
• pluginName/steppluginNameApplication.js:
• pluginName/steppluginNameApplication.php:

When a case is executed with an external step, these files will display the following table of system variables for 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 DESIGNER and open a process for editing. Right click on a task in the process and select Steps from the dropdown menu. In the Steps Of: dialog box that appears, go to the Stepstab and click on New to add a step. The external step created by the plugin should appear in the list of available steps

Click on the Select button to the right of the external step to insert it as a step in the task. The external step should now appear in the list of steps.

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

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

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:

PMFunction Class

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

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

The pluginName.php file defines a class for the plugin named pluginNamePlugin, which is based upon the PMPlugin class, which is 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 like:

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 in :

• 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 in the ProcessMaker interface, so add code which needs to be executed with every user interaction. However, remember that that code could potentially slow down ProcessMaker, so avoid code which might wait for responses from remote servers. If needing that kind of code, 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 depend upon the previous selected options, but at a minimum it contains a private __construct() which is called whenever a class instance is created and a private setup() method which 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 above files, 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 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, if needing a add a custom function named deleteCases_getCaseStatus() to return the status of a case:

As long as the plugin is activated, then 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 in order to incorporate the plugin's custom functions into ProcessMaker:

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:

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

For example:

Activate the New Plugin

After linking or copying the plugin's files into the ProcessMaker file system, then login 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 that 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 tables 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 for 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 modify. The "TABLE-NAME" can either be a new table or an existing table in the database. Remember that MySQL table names by default are case sensitive in Linux/UNIX, but not in Windows. In order to make a cross-platform plugin, it is recommended to use 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 for 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 which are specific to MySQL. This same "PLG_UID" field could 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 could be written in a shorter form as:

For more information about Propel XML schema files, see the Propel Manual. For more examples of XML schema files, see the following files which define the <wf_<WORKSPACE> and rp_<WORKSPACE> databases for 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, the run the following script to generate the Propel classes for the tables defined in the schema file:

For example:

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

Note: The 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, then create the SQL files which will insert new tables/files in 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 for each new or altered table:

Creating Exportable Plugins

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

Using the gulliver pack-plugin script

From the command line, login as root (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 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, then login to ProcessMaker as a user such as "admin" who has the PM_SETUP_ADVANCE permission in his/her role. Go to ADMIN > Plugins and click on the Import button. Select the tar file for the plugin 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 in order to use it.

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

Creating Custom Pages

In ProcessMaker 2.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 used by ProcessMaker. In version 2.0, ProcessMaker added the Ext JS framework for JavaScript and is gradually replacing all the XML->HTML + Maborak pages with HTML + Ext JS pages.

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> which 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 which 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 which will be executed when the HTML files are loaded. The Ext JS library is used to create interface items and forms and fields which 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, create a PHP file by following the steps below:

• First create the PHP file, for example Plugin_File_Name.php inside 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, for example, sending emails, starting cases automatically, assigning permissions, etc.