ProcessMaker is a great Open Source Business Process Management and workflow suite. One of its great features is its ease of extensibility via plugin development. The only problem is that there aren’t many plugins available to the community and that is partly contributed to a lack of documentation. There is some great data available on the Wiki, but there seems to be a lack of information available on how to use the Configure option for plugins. Through some reverse engineering I was able to figure it out and write up this post.

This post was created using ProcessMaker 3.5.7 Community Edition. I’m assuming you already know how to create a plugin and have one ready. The ProcessMaker wiki does have some good content on getting started.

Setup.xml

Before we can really do anything we first have to configure the form that is display when a user clicks the Configure button. This is done by modifying the setup.xml file gulliver created for you.

You get a very basic template when you create your plugin. Its layout is controlled using ProcessMaker’s older dynaform xml format. Basically if you know how XML wants to be formatted and you have a little help from the Wiki then you can make a pretty decent form.

<?xml version="1.0" encoding="UTF-8"?>
<dynaForm
  name="Calendar Setup Form"
  type="xmlform"
  labelwidth="200"
  width="600"
>
<TITLE1 type="title" group="1">
  <en>Calendar plugin setup page</en>
</TITLE1>

<SUBTITLE1 type="subtitle" group="1">
  <en>Edit this page to customize the plugin</en>
</SUBTITLE1>

<BTN_SUBMIT type="submit">
  <en>Save</en>
</BTN_SUBMIT>
</dynaForm>

<?xml version="1.0" encoding="UTF-8"?>
<dynaForm
  name="Calendar Setup Form"
  type="xmlform"
  labelwidth="200"
  width="600"
>
<TITLE1 type="title" group="1">
  <en>Calendar plugin setup page</en>
</TITLE1>

<CALENDAR type="dropdown" required="1">
   SELECT CALENDAR_UID, CALENDAR_NAME FROM CALENDAR_DEFINITION;
   <en>Select calendar to use.</en>
</CALENDAR>

<SHOWBIRTHDAYS type="checkbox" value="true" falsevalue="false">
  <en>Show user birthdays?</en>
</SHOWBIRTHDAYS>

<SHOWCASEDUEDATES type="checkbox" value="true" falsevalue="false">
  <en>Show Case Due Dates?</en>
</SHOWCASEDUEDATES>

<TEXTBOX type="text">
  <en>A sample textbox.</en>
</TEXTBOX>

<BTN_SUBMIT type="submit">
  <en>Save</en>
</BTN_SUBMIT>
</dynaForm>

The Class File

When you create a new plugin, ProcessMaker creates a directory structure for you in a plugins directory. For my project I am create a Calendar plugin so many of the files and folders include that in their names. Your files names will be based on the name of your own plugin. The class file we need to focus on for using the Configure button is the class.Calendar.php file.

/**
 * class.Calendar.php
 *
 */

class CalendarClass extends PMPlugin {
    function __construct() {
        set_include_path(
            PATH_PLUGINS . 'Calendar' . PATH_SEPARATOR .
            get_include_path()
        );
    }

    function setup()
    {
    }

    function getFieldsForPageSetup()
    {
    }

    function updateFieldsForPageSetup()
    {
    }
}

updateFieldsForPageSetup()

The updateFieldsForPageSetup() function works by taking the data from your form and doing pretty much anything you want with it with the intention of storing it for later retrieval by your plugin. The easiest way to do this would be with a simple JSON file. ProcessMaker delivers an associative array to the function with the variables and values provided in your setup.xml form. To store them just throw them into a file in your plugins directory.

function updateFieldsForPageSetup($data)
{
	$file = PATH_PLUGINS.$this->sPluginFolder.
		DIRECTORY_SEPARATOR.'config'.
		DIRECTORY_SEPARATOR.'setup.json';

	if(file_put_contents($file, json_encode($data['form'], JSON_PRETTY_PRINT))===false)
	{
		throw(new Exception("Failed to write contents to $file."));
	}

	return true;
}

getFieldsForPageSetup()

The getFieldsForPageSetup() function works in reverse. It needs to grab the contents of your JSON file and return them in the form of an associative array.

function getFieldsForPageSetup()
{
	$file = PATH_PLUGINS.$this->sPluginFolder.
		DIRECTORY_SEPARATOR.'config'.
		DIRECTORY_SEPARATOR.'setup.json';

	if(file_exists($file))
	{
		$result = json_decode(file_get_contents($file), true);
	}
	else
	{
		$result = array();
	}
	return $result;
}

That is it.