Advanced Options

From ProcessMaker

Jump to: navigation, search

Contents

ProcessMaker offers powerful options to help you automate and simplify your workflow.

Process Supervisors

Process supervisors are users who have special privileges to oversee and review the cases for a particular process. Often the manager or department head in an organization will be assigned as a process supervisor.

Process supervisors can see all the cases in a process even if they aren’t assigned to any tasks in the case or haven’t participated in the case. If they have been assigned as process supervisor to DynaForms, they can edit the data in those DynaForms after they have been submitted. Likewise, if they have been assigned as process supervisor to Input Documents, they can delete and resubmit those Input Documents.

Defining a Process Supervisor

Only users which have the permission "PM_SUPERVISOR" in their role can be assigned as a process supervisor. This permission is included by default in the role "PROCESSMAKER_ADMIN", but not in the role "PROCESSMAKER_OPERATOR". It is generally not a good idea to give managers and department heads the full powers of a PROCESSMAKER_ADMIN, because they might accidentally modify the definition of processes or delete users. Only people who know how what they are doing should be given those powers. Therefore it is recommended to create a new role for process supervisors with the PM_LOGIN, PM_CASES, PM_SUPERVISOR, PM_REASSIGNCASES, PM_PASSWORD permissions. If the process supervisor should be able to see all the cases from all the other processes as well, consider added PM_ALLCASES and PM_DASHBOARD to the new role as well.

After creating the new supervisor role, then assign that role to the user(s) who will be the processes supervisor(s). Go to USERS > USERS LIST and click the View link for the user. Then in the form displaying information about the user, click 'Edit', go to the Role dropdown box and select the new supervisor role for the user.

Then open the process which will be assigned a process supervisor. Right click on a blank area in the process map and select Process Supervisors > Supervisors from the menu.

Adding a new supervisor

In the "Supervisors" dialog box a list of process supervisors will be displayed. To add a new supervisor, click on the Assign link. Select a user from the list of users who have PM_SUPERVISOR in their role and click Assign. As many supervisors can be assigned to the process as needed.

Reviewing cases as the process supervisor

After being assigned as a process supervisor, the user can go to CASES > FOR SUPERVISOR and see all the open cases for the process. (To see cases which are finished or canceled, either add the PM_ALLCASES permission to the role of the supervisor and go to the CASES > GENERAL tab or add a Process Permission for the supervisor and go to the CASES > ALL tab.)

For each case, the process has the option to Edit, Cancel or Delete a case.

The Edit link will open a case and display the "Steps List" window for the case. In that window, the supervisor can view any Input Documents and Output documents for the case. The supervisor will only be able to view and edit those DynaForms to which he/she has been assigned as process supervisor. While the supervisor can view all Input Documents, he/she will only be able to delete or upload Input Documents to which he/she has been assigned as process supervisor. See Assigning Supervisors to DynaForms and Assigning Supervisors to Input Documents below.

Clicking the Delete link will erase the case entirely, whereas Cancel will stop the case with the status of "CANCELED", but will not remove the case from the database, so it can later be examined if needed. It is often a good idea to cancel, rather than delete, a case so that good records can be kept. In addition, it is often useful to examine the canceled cases to determine what are the points of failure in the process and where clients are not being adequately served.

Image:Dynaforms_supervisor.png

Users who are assigned as process supervisors will have the right to view all the open cases for a process, plus view any input and output documents for the case. If they need the power to review and edit DynaForms as well, right click on the process map and select Process Supervisors > Dynaforms from the menu.

A list of the DynaForms to which the process supervisor(s) have access will appear. To add a DynaForm to the list, click Assign. Select a DynaForm from the list and click its Assign link.

The process supervisor should now be able to edit the data in an already submitted dynaform.


Image:Dynaforms_supervisor2.png

Sub-Process

This feature allows for a Sub-process to be inserted into a Master process. This means that when a case reaches a certain task in the Master process, it will cause a new case to be started in the Sub-Process. Case variables from the Master process can be used in the Sub-Process.

The Sub-process can be synchronous or asynchronous, according to process design.

Assigning a Sub-Process to a Master Process

  • Open the process for which you would like to insert a Sub-process. In the process map which appears, right click on a blank area of the map and select Add Sub-Process from the menu.


  • A new Sub-Process task will appear in the process map, as shown in the following image.

Image:Subprocess2.png

  • Define the Sub-Process properties by right clicking on the Sub-Process and selecting Properties from the dropdown menu.

Image:Subprocess3.png

  • Then fill in the following information in the "Properties" dialog box:
  • Process: Defines the existing process that should be used as a Sub-Process in this task. Choose from the list of your existing ProcessMaker processes.
  • Type: choose Synchronous or Asynchronous process type. A synchronous Sub-process must be completed before the Master Process can continue. An asynchronous process does not have to be completed for the Sub-process to continue. A parent process running a synchronous parent process will continue to run, for as long the the sub-process runs. However, your To-Do list will not show the parent task.
  • Variables Out: Choose which variables from the Master Process (Origin) you would like to appear as variables in the Sub-Process (Target). Use the variable names as they appear in the Dynaforms. Do not prepend variables with @@ formations, just the plain name. If you use the @@ button to select variables, be sure to truncate the variable of any leading @@.
  • Variables In: ONLY if you choose Synchronous, a second section will appear where you can add variables from the Sub-Process (Origin) to be used in the Master Process (Target). Be aware that the @@ buttons on both origin and target sides are linked to the wrong field. Clicking @@ on the Origin side, mistakenly shows the list of options valid for the Target side, but invalid for Origin side.


For further clarification, please see the following example:

Sub-Process Example

The Master Process shown in the image includes a Sub-Process.

Image:Subprocess4.png Image:Subprocess5.png

When a case arrives at the second task, Sub-process Junior, it begins a new case in the Sub-process.

The Sub-Process properties are defined as follows:

  • The Sub-Process is called "Junior"
  • The Sub-Process is Asynchronous
  • Variables in the Master Process give the input for Variables in the Sub-Process.

Image:Subprocess3.png

Case Tracker

Case Tracker Option

This option generates a PIN that allows an external user to log into ProcessMaker and review the progress of a given case. The external user can see information including pending tasks, a summary of the derivations and information related to the specific case.

Defining Case Tracker Information

To define what information can be tracked, follow the next steps:

  • Open the Process that you would like to be traced. The related process map will appear, an interactive and user-friendly Business Process Design environment. Right-click on the design area and select Case Tracker. Two options will appear: Properties and Objects:






Case Tracker Properties
  • Defining Case Tracker Properties: The external user can see the either the whole ProcessMap or only pre-defined Stages. Likewise the external user can have access to the derivation or message history. Please define what kind of information the external user can access.





Case Tracker Objects
  • Defining Case Tracker Objects: It is also possible to define what process objects can be traced by the external user. This refers to which process dynaforms, input documents or output documents will be available to view from the case tracker. To add a new object to the list, please click on the Assign link and select the new object.





Stage Map
  • Defining Case Tracker Stage: A stage is any distinct time period in a sequence of events. In the case tracker option, the stage defines a sequential group of tasks. To define the stages please click on the Edit link in the Case Tracker Properties window; the Stage Map will appear.

By right clicking anywhere on the Stage Map you can add a new Stage. If you right click on the new stage and select Tasks Assigned, you can define what tasks belong to this particular stage.




Tracking Case Information

External users can trace information in the following URL in their web browsers: 

 http://<IP-ADDRESS>:<PORT>/sys<WORKSPACE>/<LANGUAGE>/<SKIN>/tracker/login

For instance if the ProcessMaker server is located at the IP address of 192.168.1.100, the workspace is the default "workflow" and the language is English, then direct the web browser to: 

 http://192.168.1.100/sysworkflow/en/green/tracker/login

By entering the required information (PIN and Case Number) the user will get access to the defined case tracker information, as shown in the following figures.

Case Stages View
Case Objects View
Case History View

Case Code and Pin can be sent by email through a notification, this information can be obtained as follow:

Getting the Case Code

The Case Code corresponds to the case number, it can be obtained as follows through the following trigger: 

  @@aux="SELECT APP_NUMBER FROM APPLICATION WHERE APP_UID='". @@APPLICATION ."'";
  @@rows=executeQuery(@@aux);
  @%CaseCode=@@rows[1]['APP_NUMBER'];

Where: The variable @@APPLICATION contains the application "UID" and the Case code is assigned into @#CaseCode variable. The associated trigger it must be executed before you send case tracker information to the external user.

Getting the PIN

The PIN for case tracker is available in the System Variable @@PIN

Web Entry

The Web Entry option allows a user to access ProcessMaker from an external web link and from this access point it is possible to start a case for a given Process. Therefore anonymous / external users can initiate a new case by connecting to ProcessMaker Web Services.


  • Open the Process for which you would like to define a web entry form. Right click in a blank area of the process map and select Web Entry from the menu.


  • The different web entry properties are displayed, as shown in the following illustration:

Image:Webentry-properties.png

Define the following Web Entry properties:

Initial Task: Defines the starting task for the case initiated by web entry

Initial Dynaform: Defines what form will be used for the web entry form. This form should be assigned as the first step on the initial task.

Method: Web Entry forms can be created based in two different methods: Single HTML web entry form and PHP page with web services



Single HTML web entry form

Creates a form based on HTML code, this code can be copied in your website for example. From this HTML form it is possible to start a new case. This case is available in the first task of the related process, under the Draft List. This option is recommended only for simple forms because dependent fields are not supported.

PHP page with web services

It creates a link for the web entry form. This link can be copied to your website for example. For this method, the user who can start a new case must have user credentials. Also define if cyclical assignment is required or not.

This option generates three files in the related public process folder located at: 

  /opt/processmaker/shared/sites/YOUR_WORKSPACE/public/YOUR_PROCESS_UID/
  
  YOUR_DYNAFORM_NAME_Form.php   YOUR_DYNAFORM_NAME_FormPost.php   wsClient.php

These files interact with ProcessMaker web services. The file wsClient.php defines the required functions that allow the related web entry form not only to initiate a case, but also to send it to the second task. The new case will be available in the To Do list of the second task.

Conditional Notifications

From release pmos.1.1-1901 on, Conditional Notifications are available. This option allows for the sending of customized notifications according to a certain condition in a given process. Since this option is implemented through triggers, it offers a way to set advanced notifications among the process steps.

In order to configure the notification, the following steps are necessary:

  1. Create the HTML email template.
  2. Create a trigger containing the PMFSendMessage() function.
  3. Assign the trigger to a step in the process.

Create the HTML email Template

  • In a plain text editor you should define the text of your notification. This text can contain case variables and HTML tags, as in this example. 
  Dear @#reqUserName, <br>
  Your leave request has been approved.  Please find details below. <br>
  Once your leave period has ended, please do not forget to fill out the Report Details upon returning. <br>
  Regards, <br><br>
  @#reqSup <br><br>
  
  @#fromReq <br>
  @#toReq <br>
  @#daysReq <br>
  • Once the notification text is ready, please save the template notification as a HTML file, like positiveResponse.html.
  • To upload this template file in ProcessMaker, open the Process for which you would like to define customized notifications. Right click on a blank area in the process map and select Process File Manager from the menu. A list of the different process directories will be displayed.

Image:Conditional1.png

  • The notification template file should be uploaded in the mailTemplates directory. By clicking on the mailTemplates directory, a list of the different process files is displayed as shown in the following illustration:

Image:Conditional2.png

  • To upload a new notification template, please click on the Upload Files link. Then you should select the corresponding HTML files.

Image:Conditional3.png

  • After that, the uploaded files are available for the related process.

Sending emails with PMFSendMessage()

The PMFSendMessage() function sends out customized email notifications. This function can be used in a trigger. Note that due to this bug, PMFSendMessage currently only works with the Email configuration of SMTP (PHPMailer). 

int PMFSendMessage(string caseId, string from, string to, string cc, string bcc, 
    string subject, string template, array fields=array())

Where:

  • string caseId : The UID (unique identification) for a case, which is a string of 32 hexadecimal characters to identify the case. Case UIDs can be looked up in the wf_<WORKSPACE>.APPLICATION.APP_UID field with executeQuery(). The case UID for the current case can be found in the system variable @@APPLICATION.
  • string from : The email address of the person who sends out the email.
  • string to : The email address(es) to whom the email is sent. If multiple recipients, separate each email address with a semicolon.
  • string cc : The email address(es) of people who will receive carbon copies of the email.
  • string bcc : The email address(es) of people who will receive blind carbon copies of the email. Unlike a normal carbon copy, the other recipients won't see who has received blind carbon copies.
  • string subject : The subject (title) of the email.
  • string template : The name of the template file in plain text or HTML format which will produce the body of the email. The template file must be located in the shared/sites/<WORKSPACE>/mailTemplates/<PROCESS-UID>/ directory. It can be uploaded to the mailTemplates section with the Process File Manager (which is available by right clicking in the process map). The template file can contain system variables or any variables which are passed in the fields parameter. See the previous section for how to insert variables in an email template.
  • array fields : Optional parameter. An associative array where the keys are the variable name and the values are the variable's value. If no array is included, an empty array is included by default.

Example:

For the email template above, the following trigger code could be used: 

$aFields = array('reqUserName' => @=reqUserName, 'reqSup' => @=reqSup, 
    'fromReq' => @=fromReq, 'toReq' => @=toReq, 'daysReq' => @=daysReq);
$usr = userInfo(@@USER_LOGGED);
$to = $usr['mail'];     
PMFSendMessage(@@APPLICATION, 'manager@acme.com', $to, '', 'ceo@acme.com; cfo@acme.com', 
    'LeaveRequestTemplate.html', $aFields);

Assigning the trigger to step(s)

Once you have uploaded your template email file and defined a trigger to send the email, it is possible to assign the related trigger to steps in different instances:

  • before/after a object process is displayed
  • before the assignment is performed
  • before/after a derivation is completed

In each case, it is also possible to define conditions that dictate when a trigger should be executed or not. For example, the following condition defines that the trigger will be executed only if @@repFinalDec case variable is 0. In other words, the notification will be sent only when this condition is true. Image:Conditional4.png

Process Permissions

The Process Permissions option allows for the definition of permissions for specific users to view different objects (i.e. Dynaforms, Input Documents and Output Documents) of a given process. This new feature offers advanced control over how users participate in a process and what information they can see at what time.

In releases previous to pmos.1.1-1774, the user participants in a process were able to view the different objects of the process. From this release on, the permissions should be assigned during the process design.


Assigning Permissions to a given Process

Process Permissions
  • Open the Process for which you would like to assign specific permissions. The related process map will appear, an interactive and friendly Business Process Design environment.
  • Right-click on the design area and select Process Permissions:







New Process Permissions
  • A list of the different Process permissions is displayed, as shown in the following illustration:




  • Create a new Process Permission by clicking on the New link. Then you should fill in the following information:
  • Target Task: Defines the task where the permission is valid. In others words, the assigned user will have the permission when s/he is performing the task defined in this parameter.
  • Group or User: To whom the permission will be assigned.
  • Origin Task: Defines that only the objects associated with this parameter are valid for permission.
  • Participation Required?: Defines if the user/group must have already participated in the process or not. When the participation is NOT required then the user has the permission throughout to the whole process, otherwise the user will have the permission only after he has participated in the process.
  • Type: Defines object types for which the permission is valid. They can be Dynaforms, Input Documents and Output Documents or ALL.

When you choose one of the types, a corresponding dropdown appears with the list of the related objects defined in the process.

  • Permission: Permissions include the following options:


• VIEW = Access to view the object • BLOCK = It is not possible to view the object


For further clarification, please see the following examples:

Examples

In the following process,

  • User 1 is assigned to tasks 1 and 5.
  • User 2 is assigned to task 2,
  • User 3 is assigned to task 3
  • And user 4 is assigned to task 4.





Then possible specific process permissions are: 1. User1 has permission to [VIEW] [ALL] process objects, no matter what task user1 is participating in [target task = ALL TASKS]. The only condition is that user1 must have already participated in the process [participation=YES].




It is also possible to [BLOCK] the access to certain objects. For example user1 already has permission to [VIEW] [ALL] objects. You can restring this permission by defining the following specific process permission:

2. User1 has no permission to view [BLOCK] the dynaform [fields test] of [e_Task 2], no matter what task user1 is participating in [target task = ALL TASKS].





Then with the permission defined in steps 1 and 2, user1 has permission to [VIEW] all process objects except for the [dynaform] [field test] of [e_Task 2]. In this way you can customize the access to the different process objects.


3. User2 has permission to [VIEW] [ALL] [Input Documents] belonging to the [e_Task 2], only when user2 is participating in [Target task = e_Task 4].





Note that with these conditions, the participation parameter is not required, therefore it has the value [participation=NO].

The created permissions are displayed in the Specific Permission List as shown below:

PM Tables

As of version 1.2-2425, tables of data can be created and updated inside of ProcessMaker. PM Tables are designed for users who do not wish to go through the hassle of maintaining an external database. Even users who have external databases may find PM Tables handy for quickly creating data which will be used in their DynaForms or reports. The data in PM Tables is stored the MySQL database wf_<workspace> (which by default is wf_workflow), so the data could theoretically be accessed by an external program. Nonetheless, it is recommended that you only use PM Tables for data which will be used inside ProcessMaker. It is better to create an external database if you want to access that same data outside of ProcessMaker.


Creating PM Tables

Editing a PM Table structure

To create PM Tables, go to ADMIN > PM Tables (in versions 1.2-2425 and 1.2-2467 it was available from the main tab bar). Click on New and enter a table name and define the fields in the table.


Table Information:

  • Table Name: Enter the name of the new table, which is case insensitive because this is the name which will be used for the MySQL table.
  • PHP Class Name: The case sensitive PHP class name used by Propel to identify the PM Table. You can use this class name to access the PM Table in your PHP code in triggers. If the name of your PM Table is already being used by a class in your PHP code or it might cause errors, enter an alternative name for the PHP Class Name.
  • Description: A description or any additional information about the table.


Log Configuration:

ProcessMaker provides options to log changes to the data and the structure of PM Tables. This log information is stored in wf_<WORKFLOW>.shadow_table in MySQL. (Check wf_<WORKSPACE>.additional_tables to find the table UIDs used in shadow_table.) Future versions of ProcessMaker will provide options to undo changes to PM_Tables, so it is a good idea to activate the log options if you will want to be able to undo changes to the tables in the future.

image:checkbox.png Save log for insert actions: Activate to record all insertions to the PM Table's structure and its data.
image:checkbox.png Save log for update actions: Activate to record all updates to the PM Table's structure and its data.
image:checkbox.png Save log for delete actions: Activate to record all deletions to PM Table's structure and its data.
image:checkbox.png Delete log related when table is deleted: Activate to delete the log when the PM Table is deleted.


Fields:

  • Field Name: A unique case-insensitive name to identify the field. Names should be 64 or less characters long and should not begin or end with numbers or spaces, nor contain the characters '\', '/' or '.'
  • Field Label: The displayed label for the field, which the user will see when editing data in the table.
  • Type: Fields can be one of the five MySQL data types: VARCHAR, TEXT, DATE, INT, FLOAT.

       VARCHAR is a string of 255 or fewer characters.
       TEXT is a string of characters which is 65,536 or fewer bytes long.
       DATE is a date in the format YYYY-MM-DD.
       INT is an integer between -2147483648 and 2147483647.
       FLOAT is a 4 byte floating point number between -3.402823466E+38 and 3.402823466E+38.
       See the MySQL manual for more information on these data types.

  • Size: For VARCHAR fields, the maximum number of characters. For INT and FLOAT fields, the maximum number of digits of precision. For DATE and TEXT fields, size is not applicable.
  • Null: Select if the field may be a NULL value, which means "no data".
  • Primary key: Select if the field (or a combination of fields) will hold a unique, unalterable value which is used to index the table. All PM tables must contain at least one primary key.

After defining the fields, click the Save button to store the structure of the table.

List of PM Tables

After creating a PM Table, it will be displayed in the list of available tables under ADMIN > PM Tables. To sort the list of PM Tables by its name or description, click on a column header. Up or down arrows will appear in the column header to indicate whether sorting in ascending or descending order. Click in the header to reverse the sorting order.

  • Edit: Click to alter the fields in a field or change a table's name or description. The properties of the fields can be safely changed without loosing the data already stored in those fields. However, be aware that changing the names of tables and their fields can cause problems in existing DynaForms, reports and your PHP code which accessed PM tables.
  • Data: Click to view, add, delete or update records in the table.
  • Delete: Click to delete a PM Table.

image:PMTableList.png

To select which columns will be displayed in the list of PM Tables, right click on the column header and select which columns are displayed. Hide the Edit and Delete columns to prevent careless users from accidently editing the table structure or deleting it.

image:PMTableSelectFields.png


Viewing and Editing PM Table Data

To view the data stored in a PM Table, click on the Data link in the PM Table list. The data can be sorted by columns by clicking on the column headers. Up or down arrows will appear in the column header to indicate whether sorting in ascending or descending order. Click in the header to reverse the sorting order.

image:PMTableViewData.png

To add a new record to a PM Table, click on the New link at the top of the table. Click on the Edit and Delete links on the right-hand side to edit or delete a record in the PM Table. To prevent careless users from accidently editing or deleting a record or seeing a particular column of data, right click on the PM Table header and select the columns which will be displayed.


Importing PM Tables

From version 1.2-2552 on, it is possible it import data into PM Tables from a CSV (comma separated values) file. The CSV file should be a plain text file containing the field values separated by semicolons. List the field values in the same order as they appear in the PM Table, so the first semicolon separated value will go into the first field, the second value in the second field, and so on. The first line of text in the CSV file will be ignored, because it is assumed to contain the column headers (field names). If multiple rows contain the same primary keys, only the first row will be inserted and all additional rows with the same primary key will be discarded. Likewise, if trying to import a record with a primary key which already exists in the PM Table, the imported record will be discarded and a warning will inform the user on which line the duplicate record was found in the CSV file.

Image:WarningDuplicateKeysPMTable.png

Note that ProcessMaker does not currently follow the CVS specification, which allows the use of commas to separate values. It only allows semicolons. Likewise, ProcessMaker doesn't allow the use of double quotation marks around values, nor the use of semicolons, commas, double quotation marks and line breaks within values which are enclosed in double quotation marks.

To import a CVS file into a PM Table, go to ADMIN > PM Tables. Find the desired table in the list and click on its Data link. At the top of the table, click on the link Import data (CSV File). Then select the CSV file and click the Save button.

image:ImportPMTable.png

Exporting PM Tables

Currently it is not possible to export PM Tables from inside ProcessMaker, but this can be done by entering MySQL. The PM Table is stored in the wf_<WORKSPACE> database. To export the table to a file, use a SELECT command with the INTO OUTFILE option: 

mysql -u root -p
SELECT * FROM wf_<WORKSPACE>.<PM-TABLE> INTO OUTFILE 'outfile.csv' FIELDS TERMINATED BY ';';
EXIT;

The CSV outfile will be saved to the /mysql/data/wf_<WORKSPACE>/ directory. If you want to import the PM Table back into ProcessMaker, you will have to edit the CVS file and add an extra line at the top of the file. ProcessMaker will assume that the first line in the file is the header line and ignore it when importing.

Accessing PM Tables from Triggers

It is possible to use PHP code in triggers to read and manipulate the information in PM Tables. Either use the executeQuery() function or Propel classes to access PM Tables.

For example, a PM Table called "CONTACTS", which contains the fields "ID", "FIRSTNAME", "LASTNAME" and "BIRTHDAY" can be accessed with executeQuery("SQL_STATEMENT"): 

@@RESULT = executeQuery("SELECT * FROM CONTACTS WHERE ID='1'");
@@RESULT = executeQuery("INSERT CONTACTS SET FIRSTNAME='Jane', LASTNAME='Doe', BIRTHDAY='1969-03-24', ID='4'");
@@RESULT = executeQuery("UPDATE CONTACTS SET FIRSTNAME='Buster', LASTNAME='Brown' WHERE ID='2'"); 
@@RESULT = executeQuery("DELETE FROM CONTACTS WHERE ID='4'");

Note: It is not necessary to specify the database, since executeQuery() uses by default the wf_<WORKSPACE> database where the PM Tables are stored.

PM Tables can also be accessed through Propel classes in triggers. For instance, the same table could be accessed through its PHP class name of "Contacts". (Remember that class names are case sensitive). This example inserts a new record in the contacts PM Table: 

$oContacts = new Contacts(); 
$oContacts->setId(23);
$oContacts->setFirstname('John');
$oContacts->setLastname('Doe');
$oContacts->setBirthday(@@field1);
$oContacts->save();

See the Propel documentation for more information on how to access tables through Propel classes.

Accessing PM Tables in DynaForms

DynaForm fields can obtain read-only access to PM Tables with a standard SQL SELECT statement. Since PM Tables are stored in the wf_<WORKSPACE> database, the SQL Connection property can be left blank, since it will select that database by default if blank. In the SQL property, put the SELECT statement.

For example, a dropdown box could populate its list of options with the names found in the CONTACTS table used in the previous example. Its SQL property would be: 

SELECT ID, CONCAT(FIRSTNAME, ' ', LASTNAME) FROM CONTACTS

and its complete XML definition would look something like this: 

<SelectContact type="dropdown" required="0" readonly="0" savelabel="0" mode="edit" options="Array">
  <![CDATA[SELECT ID, CONCAT(FIRSTNAME, ' ', LASTNAME) FROM CONTACTS]]>
  <en>Select Contact  <option name=""></option>
  </en>
</SelectContact>

Note that the SQL SELECT statements to populate the list of options for dropdown boxes, listboxes, checkgroups and radiogroups should return two columns, where the first column is the value and the second column is the label for each option.

To populate the value of a textbox, currency box, percentage box, textarea, or hidden field from a PM Table, use an SQL SELECT statement which only returns one field from one record. If more than one record is returned, only the first record will be used.

For instance, to select the contact whose ID is 907: 

 SELECT CONCAT(FIRSTNAME, ' ', LASTNAME) FROM CONTACTS WHERE ID='907'

If a dependent relationship has been established with another field, then the ID can be determined by the value in the independent field. In this example, the value in the "ContactId" field will determine which contact's full name is displayed in a textbox: 

 SELECT CONCAT(FIRSTNAME, ' ', LASTNAME) FROM CONTACTS WHERE ID=@@ContactId

PM Tables in a DynaForm Grid

In order to display a PM Table in a DynaForm grid, first create a grid form which has the field names which are the same as those found in the PM Table. Then, embed that grid form in a master form. Finally, create a trigger which will use executeQuery("SELECT ...") to return an array of records from the PM Table. Assign that array of records to a case variable which has the same names as the grid object in the master DynaForm. Set the trigger to fire before the master DynaForm is displayed.

For example, the following trigger code would populate a grid object named "ContactsGrid": 

@@ContactsGrid = executeQuery("SELECT ID, FIRSTNAME, LASTNAME, BIRTHDAY FROM CONTACTS");

If the field names in the grid form are not named "ID", "FIRSTNAME", "LASTNAME" and "BIRTHDAY", then use AS to rename the returned fields from the PM Table to the names used in the grid form. For example, the fields from the CONTACTS table could be renamed as "ContactID", "ContactFName", "ContactLName" and "ContactBirthday", respectively: 

@@ContactsGrid = executeQuery("SELECT ID AS ContactID, FIRSTNAME AS ContactFName, " .
   "LASTNAME AS ContactLName, BIRTHDAY AS ContactBirthday FROM CONTACTS");

To write the changes in a DynaForm grid to a PM Table, set a trigger to fire after the DynaForm with code to delete all the contents of the old PM Table. Then write each row from the grid into the new PM Table. For example: 

executeQuery("TRUNCATE TABLE CONTACTS");
$grid = @@ContactsGrid;
foreach ($grid as $row)
   executeQuery("INSERT INTO CONTACTS (ID, FIRSTNAME, LASTNAME, BIRTHDAY) VALUES " .
      "('$row['ID']', '$row['FIRSTNAME']', '$row['LASTNAME']', '$row['BIRTHDAY']')");

Read/Write Access to a PM Table

As of version 1.2-2552, it is possible to obtain both read and write access to single record in a PM Table through a DynaForm. A field in a PM Table record can be associated with a DynaForm field by editing its XML definition. The data entered in the DynaForm field will be automatically updated in the PM Table.

In order to associate fields in a DynaForm with the fields from a single record in a PM Table, first go to the PM TABLES tab under ADMIN (formerly called SETUP). Select the desired PM Table from the list and click its Edit link. Then, look in the address of your web browser to find the UID of the PM Table. For instance, in the URL:

http://localhost/sysworkflow/en/green/additionalTables/additionalTablesEdit?sUID=8978302234afeaeff4f2773061370232

Copy the UID of the PM Table. Then, open a DynaForm and go to the XML tab to directly edit the XML code. Add a line near the top to establish a pmconnection to the PM Table. The pmconnection should be given a name which will be used to identify it when used in later elements of the DynaForm. Use the XML attribute pmtable to specify the UID of the PM Table and the XML attribute keys to specify the primary key(s) of the record to be retrieved from the PM Table: 

<PM-CONNECTION-NAME type="pmconnection" pmtable="PM-TABLE-UID" keys="PRIMARY-KEY-VALUE" />

In this example a pmconnection called "CONTACTS_CONNECTION" is defined for the record whose primary key is 909. 

<CONTACTS_CONNECTION type="pmconnection" pmtable="6119139294a843924e70988028788673" keys="909" />

Always enclose the primary key value in quotes, even if its data type is not a string. If the primary key is a date, use the format "YYYY-MM-DD".

If a PM Table contains multiple primary keys, the key values can be separated by pipes (|) or by commas (,). List the values in the same order which the fields appear in the PM Table. For instance, if a PM Table has a primary key which is a combination of the fields "name", "birthday" and "income": 

<CONTACTS_CONNECTION type="pmconnection" pmtable="6119139294a843924e70988028788673" keys="John Doe|1973-12-31|35000" />

The keys attribute can also be set to a variable referring to another field in the DynaForm, however, the value of the variable will only be read when the DynaForm is first displayed, so it must be the default value of the field or a value set by a trigger beforehand. (Setting the value of the field with JavaScript will not work, since JavaScript code is run after the DynaForm is displayed.) For example, if trigger is fired beforehand with code: 

@#SelectID = 3;

and a DynaForm contains a hidden field named "SelectID", then the following pmconnection could refer to @#SelectID: 

<CONTACTS_CONNECTION type="pmconnection" pmtable="6119139294a843924e70988028788673" keys="@#SelectID" />

After creating a pmconnection, its data can be accessed from a DynaForm field by using the XML attribute pmconnection to specify the name of the pmconnection and the XML attribute pmfield to specify the name of the field in the PM Table which will be associated with the field in the DynaForm: 

<DYNAFORM-FIELD-NAME ... pmconnection="PM-CONNECTION-NAME" pmfield="PM-FIELD-NAME"> ... </DYNAFORM-FIELD-NAME>

For example, here the DynaForm field "ContactId" is associated with the "ID" field in the CONTACTS table: 

<ContactId type="text" maxlength="64" validate="Any" required="0" readonly="0" size="50" 
  mode="edit" pmconnection="CONTACTS_CONNECTION" pmfield="ID">
  <en>ID</en>
</ContactId>

It is possible to have any number of different pmconnections to PM Tables in a DynaForm. The pmconnections can be different queries to the same PM Table and/or queries to different PM Tables.

For instance, it this example, DynaForm fields are associated with two different pmconnections: 

<CONTACTS_CONNECTION  type="pmconnection" pmtable="611a139c94a843924e709eb028788673" keys="@#ContactId" />
<COMPANIES_CONNECTION type="pmconnection" pmtable="347a7b790cd119139294a84392bf709c" keys="ACME" />
<FirstName type="text" maxlength="64" validate="Any" required="0" readonly="0" size="50" 
  mode="edit" pmconnection="CONTACTS_CONNECTION" pmfield="FIRSTNAME">
  <en>First Name</en>
</ContactId>
<LastName type="text" maxlength="64" validate="Any" required="0" readonly="0" size="50" 
  mode="edit" pmconnection="CONTACTS_CONNECTION" pmfield="LASTNAME">
  <en>Last Name</en>
</LastName>
<Company type="text" maxlength="64" validate="Any" required="0" readonly="0" size="50" 
  mode="edit" pmconnection="COMPANIES_CONNECTION" pmfield="CO_NAME">
  <en>Company Name</en>
</Company>

At this point it is not possible to obtain use a pmconnection to obtain read/write access to grids or query more than one record at a time, but that functionality will come in future versions of ProcessMaker.

It is not possible to automatically create new records in the PM Table using a DynaForm. If a new record in the PM Table needs to be created every time the DynaForm is displayed, fire a trigger before the DynaForm is displayed to create a new blank record, then use the DynaForm to fill the values in that blank record.

In this example, a trigger is used to create a new record in the PM Table before the DynaForm is displayed. A primary key is generated for the new record by adding one to the highest current primary key in the PM Table: 

$result = $executeQuery("SELECT MAX(ID) FROM CONTACTS");
if (is_array($result) && count($result) > 0)
    $nextId = $result[1]['MAX{ID)'] + 1;
else // if no table records
    $nextId = 1;
$executeQuery("INSERT INTO CONTACTS (ID) VALUES ('$nextId')");
@#NewID = $nextId;

The DynaForm has a hidden field named "NewID" and its pmconnection is defined as: 

<CONTACTS_CONNECT  type="pmconnection" pmtable="611a139c94a843924e709eb028788673" keys="@#NewID" />

Events

Most actions in a process are executed in response to the user, but sometimes an action needs to be executed according to a specific timing in the process. In ProcessMaker, events are actions which execute relative to the time when a task or a series of consecutive tasks begins or ends. Currently events can execute either the action of sending a message or executing a trigger (but future releases may offer addition options).

Creating an Event

To create a new event, right click on a blank area in the process map and choose “Events” from the menu. Click on the New link at the upper left corner of the list.

Define the task(s) and timing of the new event:

Events properties

  • Description: A description of the event, which is how the event will be identified and displayed in the list.
  • Status: Set to “Active” for the event to go into effect. To disable the event, set to “Inactive”.

Set Interval

  • Related to: Select whether the event's timing will be set in relation to a “Single Task” or “Multiple Tasks”. If the latter, then the event's timing can span multiple consecutive tasks in the process.
  • Interval: Select the starting task from which the event will be timed.
    • To: If the option "Multiple Tasks" was selected, then also select the ending task.
  • Interval Time: Enter the anticipated amount of time in days which will pass before the task or tasks are completed. (Currently the timing can only be in whole days, but in future releases, there will be an option to set the time in hours and months as well.)
  • Timer: Enter the number of whole days relative to the beginning or end of the task when the event will be executed. The timer can be set to either a positive or negative number of days, which are counted either from the start or end of the interval.
    • Select whether the timer will be set to "After interval ends" or "After interval starts".
  • Action: Select whether the timer will "Send Message" which is the default or "Execute Trigger".

Graphical representation of the timer

The timer setting can be confusing. To visually verify the timer, check the graphical representation of the timer settings to see when the event will fire relative to the time of the selected task(s). Note: PHP's GD library has to be installed in order for the graphic representation of the timer to be displayed.

Once the tasks and timing are defined, click the Continue button to define the action for the event.

Examples:

If an event has an Interval Time of 5 days and its Timer is set to 8 days "After the interval starts", then event is anticipated to execute 3 days after the end of the task(s).

If an event has an Interval Time of 7 days and its Timer is set to -3 days "After the interval ends", then event is anticipated to execute 4 days after the first task begins.

Note: No event can be before the starting task, since ProcessMaker has no idea when the starting task will begin in absolute time. If a negative number is used to set the timing before the starting task, the event icon will disappear from the graphical representation, indicating that the timing is impossible.

Configuring a Send Message Event

If the selected action for an event is "Send Message", then define the properties of the email to be sent:

  • Subject: The subject of the email.
  • Send To: Select who will receive the email will be sent to. The (Current Task User) can be added to the Send To list by clicking on (which is already selected by default). To add a ProcessMaker user, click on and select a user to add to the list. To add everyone in a ProcessMaker group, click on image:EventAddGroup.png and select the group to add to the list. To add the email of a user who is not a registered user, enter their email address in the textbox at the top of the list and click on image:EventAddEmail.png. (Only their email addresses will be accepted and not their names.) To remove email recipient(s) from the Send To list, select one or more recipients and click on .
  • Carbon Copy: Add email addresses or users to receive an exact copy of the email.
  • Blind Carbon Copy: Add email addresses or users to receive a blind carbon copy of the email, which means that the other recipients will not be informed that the BBC recipients were sent the email.
  • E-Mail Template: Select one of the HTML template files which will form the body of the message. If the template file contains system and case variables they will be automatically inserted. Template files can uploaded by right clicking on the Process Map and selecting Process File Manager from the menu, then selected the mailTemplates directory and clicking the Upload File link. The templates are stored in the shared/sites/<WORKSPACE>/mailTemplates/<PROCESS-UID>/ directory.

When done defining the email properties, click on Save.

Defining a Trigger Event

If the selected action for an event is "Execute Trigger", then enter the PHP code for the trigger. Use the [@@] button to insert case and system variables into the trigger. When done entering the code, click Save.

Managing Events

To manage the events for a process, right click on a blank area in the Process Map and select Events from the menu.

image:EventsList.png

The events defined for the current process are listed with the following columns:

  • Description: The description of the event.
  • When occurs: Whether the timing is set according to "After task starts" or "After task ends".
  • Action: Whether the event will "Send Message" or "Execute Trigger".
  • Status: Whether the event is set to "Active" or "Inactive" Status.
  • Edit: Click this link to edit the definition of the event.
  • Action: Click this link to edit the definition of the email if a "Send Message" event or edit the Trigger code if an "Execute Trigger" event.
  • Delete: Click this link to delete the event.

The following links are provided in the upper left-hand corner of the "Events" dialog box:

  • New: Click this link to create a new Event.
  • Pending: Click this link to display a list of the events which are planned, but haven't yet executed in cases for the current process.
  • Completed: Click this link to display a list of the events which have already executed in cases for the current process.

Image:EventsCompletedList.png

Configuring to execute events

ProcessMaker is a program which executes actions in response to user actions, and not according to an external clock. In order for events to be executed in time with the server's clock, the file http://<IP-ADDRESS>/sys<WORKSPACE>/en/green/services/cron.php has to be periodically executed. This php file causes pending events to be executed. You can run cron.php by directing your web browser to that address, but it is best to automate the execute of cron.php as detailed below.

Configuring crontab in Linux/UNIX

In Linux/UNIX, commands can be executed at scheduled time with the cron daemon. To configure cron to execute ProcessMaker's cron.php file, log in as the root user and edit the file /etc/crontab with your favorite plain text editor such as vim or gedit.

In the crontab file, the timing of commands is listed according to the format: 

minute hour day-of-month month day-of-week user command

Where:

Field Description
minute The minute of the hour when the command is executed. Can be between 0 and 59.
hour The hour when the command is executed. Can be between 0 and 23. 0 is midnight.
day-of-month Day of the month when the command is executed. For example 20 would be the 20th day in each month.
month Month when the command is executed. Can be a number between 1 and 12 or the first three letters of the month in English, such as jan, feb, etc.
day-of-week Day of the week when the command is executed. Can be a number between 0 and 7, where 0 and 7 are both Sunday, 1 is Monday, 2 is Tuesday, etc. Alternatively, can be the first three letters of the day in English such as sun, mon, etc.
user The username which will execute the command.
Comand Command, script or program to execute.

An asterisk * in the first five columns indicates all possible values. For instance, an asterisk in the minutes column indicates all the minutes in the hour. If an asterisk is divided by a number "*/#", then it stands for any time unit which can be cleanly divided without any remainder. For instance in a day with 0-23 hours, "*/5" would execute on hours 0, 5, 10, 15 and 20.

For example to execute cron.php found in the server at 192.168.2.100 in the "workflow" workspace every 30 minutes: 

*/30 * * * * root wget -q -F -O - http://192.168.2.100/sysworkflow/en/green/services/cron.php

In this example, the first column "*/30" means every 30 minutes. wget is a program which downloads files. -q stands for --quiet, which suppresses output. -F stands for --force-html, which treats the downloaded file as an HTML file. -O stands for --output-document which concatenates all the downloaded file(s) to write them to one location, which in this case is "-", which stands for the current output. This output is all treated as a command to be executed by cron.

It is not recommended to execute cron.php more than once every 5 minutes due to the heavy processing which it incurs. For more information on how to configure the crontab, see this tutorial (or this tutorial in Spanish).

Scheduling a task in Windows XP

  • On the server running ProcessMaker, open the Scheduler by going to Start > Programs > Accessories > System Tools > Scheduled Tasks
  • Double-click Add Scheduled Task
  • The Scheduled Task Wizard will appear. Click Next.
  • Enter a command to start up your web browser and execute the cron.php script. For example, if using the Mozilla Firefox on a server located at 192.168.2.100, which uses the "workflow" workspace, then the command would be:
C:\PROGRA~1\MOZILL~1\firefox.exe http://192.168.2.100/sysworkflow/en/green/services/cron.php
Then click Next.
  • Give the task a Name, such as "ProcessMaker Cron Job", and choose the Frequency with which to perform the task (for example, Daily)). Click Next.
  • Choose specific date and time options (this step will vary, depending on the option selected in the previous step). When finished, click Next.
  • Enter your password if prompted. Change the username if required (for example, you'd like the task to run under a user with fewer privileges security reasons). Click Next.
  • On the final page, select the checkbox Open advanced properties for this task when I click Finish and click Finish.


This Scheduled Task will cause the web browser to pop-up periodically to execute the cron.php script. If this solution is undesirable, the cron.php script can be executed in the background with wget on Windows. To install it, download the wget zipped executable. Create a folder to store the executable such as C:\Program Files\wget\ and unzip it there. Then follow the steps listed above to create a Scheduled Task which executes the command: 

c:\PROGRAM~1\WGET\wget.exe -q -F -O - http://192.168.2.100/sysworkflow/en/green/services/cron.php

Remote access with WebDAV

WebDAV (Web-based Distributed Authoring and Versioning) is a protocol which provides the abilityto create, change and move files in a remote server. Through WebDAV documents can be easily uploaded and downloaded to a ProcessMaker server. WebDAV can also be used to easily edit documents stored in a ProcessMaker server, because the files in a WebDAV server appear in the file browser of a remote computer as locally stored files.

WebDAV permits process designers to directly edit the documents stored in a remote ProcessMaker server with their local PC. This can be very useful when editing the XML or HTML in a DynaForm, because a process designer can use their favorite text editor running in their local PC.

ProcessMaker's files in WebDAV are available under the following directory structure: 

- Classes
- Processes
|—- mailTemplates
|—- public_html
|—- xmlforms

Classes are all the *.php files used to create and control PM Tables. Editing these files will extend the functionality of the Propel classes for PM Tables.

Processes/mailTemplates are the *.html files which are used to generate emails based upon HTML templates. These are the files which are uploaded with the Process File Manager (which is available in the right click menu in the Process Map) in the mailTemplates directory.

Processes/public_html are the publicly accessible files for a process, which can be uploaded with the Process File Manager. These files are accessible from a web browser. Files generated by Web Entry are also stored in this directory.

Processes/xmlform are the *.xml and *.html files which corresponde to the XML and HTML code for the DynaForms in a process. With WebDAV the DynaForms can be edited on your local machine with your preferred text editor.

To access these files, open your file browser and direct it to the address: 

http://<IP-ADDRESS>/sys<WORKSPACE>/en/green/services/webdav

Note: It is not possible to create new files, nor erase existing files, because only the ProcessMaker system should carry out these functions.

Configuring WebDAV

There are a number of different programs which can access WebDAV, such as Windows Explorer, Internet Explorer, Konqueror and Nautilus. For a full listing see: http://webdav.org/projects

Novell's client software netdrive.exe allows a disk to be mapped to a WebDAV directory (or "collection" as they are known according to the WebDAV protocol). It can be downloaded for gratis from this link: http://www.theblog.ca/novell-netdrive

To use WebDAV in different operating systems, see: http://in.solit.us/about/webdav


Accessing WebDAV in Windows Explorer

The WebDAV client in Windows XP known as "Web Folder" can be configured with the following steps:

  1. In Windows Explorer, open My Network Places.
  2. Go to the Tools menu and select the option Map Network Drive...
  3. Use the option “Sign up for online storage or connect to a network server”
  4. Select the option “Choose another network location”. Specify the address of a Web site, network location, or FTP site.
  5. In the textbox “Internet or network address”, enter the WebDAV which corresponds to a workspace in the ProcessMaker server. For instance, a ProcessMaker server using the default "workflow" workspace located at 192.168.2.100 would have a network address of http://192.168.2.100/sysworkflow/en/green/services/webdav
  6. Click Next and in the creditials verification window, enter the username of a ProcessMaker user who has the permission PM_WEBDAV in his/her role. All users with the role PROCESSMAKER_ADMIN have this permission, but additional roles with this permission can also be defined.
Retrieved from "http://wiki.processmaker.com/index.php/Advanced_Options"
Personal tools