3.0 - 3.1 - Internal Functions and Classes

Warning: It is not a good practice to use Internal Functions and Classes because they are not supported by ProcessMaker and they may be deprecated.

Overview

ProcessMaker uses a large number of functions and classes internally, which may be called inside triggers or plugins. The following is a small selection of the more useful functions, but many more can be found by looking in the source code. In PHP, variable names are case sensitive, but the names of functions, classes and class methods are not case sensitive, so the functions and classes listed below may appear with a different case in the ProcessMaker source code.

Source Code Locations

The most important PHP code files for ProcessMaker are located in the following locations:

Gulliver:

• <INSTALL-DIRECTORY>/gulliver/system/: This directory defines the principal classes for Gulliver, which is ProcessMaker's custom PHP development framework.

ProcessMaker classes:

• <INSTALL-DIRECTORY>/workflow/engine/classes/: This directory defines the principal classes used by ProcessMaker.
• <INSTALL-DIRECTORY>/workflow/engine/classes/model/: This directory defines the Propel classes and their Peer classes that correspond to tables in the database.
• <INSTALL-DIRECTORY>/workflow/engine/classes/model/om/: This directory defines the abstract base classes from which the Propel classes in the model directory are derived (inherited).

RBAC classes:

• <INSTALL-DIRECTORY>/rbac/engine/classes/: This directory defines the principal classes used by ProcessMaker's role based action control, which controls what functionality users can access based upon their roles.
• <INSTALL-DIRECTORY>/rbac/engine/classes/model/: This directory defines the Propel classes and their Peer classes that correspond to tables in the database.
• <INSTALL-DIRECTORY>/rbac/engine/classes/model/om/: This directory defines the abstract base classes from which the Propel classes in the model directory are derived (inherited).

ProcessMaker Interface Code:

• <INSTALL-DIRECTORY>/workflow/engine/methods/: This directory contains the code executed by ProcessMaker screens and dialog boxes. These files are executed when a URL is entered in the web browser.

For example, the URL:

http://www.example.com/sysworkflow/en/classic/cases/casesListExtJs.php

Executes the code file:

<INSTALL-DIRECTORY>/workflow/engine/methods/cases/casesListExtJs.php

Files whose name terminates in _Ajax.php handle AJAX calls from other pages. In ProcessMaker 2.X, many of the pages were redesigned to use the Ext JS JavaScript framework in place of the old Maborak framework; however it is possible to find both an Ext JS and Maborak version of the same page.

• <INSTALL-DIRECTORY>/workflow/menus/: This directory holds the code to define the ProcessMaker menus.

ProcessMaker Pages:

• <INSTALL-DIRECTORY>/workflow/templates/: This directory holds the HTML and JavaScript files (plus a few random PHP files) to display pages.
• <INSTALL-DIRECTORY>/workflow/xmlform/: This directory holds the XML files, which are used to generate HTML forms. The format of the XML is the same format used by Dynaforms.
• <INSTALL-DIRECTORY>/workflow/js/: This directory holds JavaScript code.

Calling Internal Functions and Classes

Some of the internal functions and classes are already included automatically when a trigger is fired, so the source files do not need to be imported into the trigger code. If using internal functions and classes in a plugin, the source files will generally need to be imported.

Use the require_once() function to import a source file into a trigger or plugin code file before calling the function or instantiating an object in that class:

require_once "path/to/file"; someFunctionOrClass(...);

The path to source files starts from the <INSTALL-DIRECTORY>/workflow/engine directory. For example, to instantiate a new webEntryProxy object, whose code is found at /opt/processmaker/workflow/engine/controllers/webEntryProxy.php, use:

The Gulliver framework also provides the following methods to import source code files:

• G::LoadClass(): Imports ProcessMaker class definition files stored at workflow/engine/classes/class.class-name.php.
• G::LoadClassRBAC(): Imports RBAC class definition files stored at rbac/engine/classes/class.class-name.php.
• G::LoadThirdParty(): Imports additional libraries/programs stored at gulliver/thirdparty/.
• G::LoadTemplate(): Imports PHP template files stored at workflow/engine/templates/filename.php or gulliver/templates/filename.php.
• G::LoadSystem(): Imports Gulliver class definition files stored at gulliver/system/class.class-name.php.
• G::LoadInclude(): Imports files stored at workflow/engine/includes/inc.filename.php.
• G::LoadAllModelClasses(): Imports all the Propel model class definition files found at workflow/engine/classes/model/class-name.php, but does not import any of the class-namePeer.php files.

For more information about how to use these methods, see the source code at gulliver/system/class.g.php and the paths defined at workflow/engine/config/paths.php.

To reference a method (member function) of a class without instantiating an object for that class, use CLASS::function-name(). For example: Cases::loadCase() or G::SendTemporalMessage(). Note that class names in ProcessMaker generally start with uppercase and methods generally start with lowercase.

Exceptions in ProcessMaker functions are generally caught and will not abort the trigger; however, ProcessMaker's internal functions may not have exception handling, so it is a good idea to wrap the code inside of try{...} catch{...} to gracefully handle exceptions.

Getting Information with ProcessMaker Classes

The information stored about ProcessMaker objects, such as processes, users, cases, etc. can be obtained by directly querying ProcessMaker's databases in MySQL (for example, using executeQuery() in a trigger, Propel::executeQuery() in a plugin or mysql_query() in an external script).

Database queries, however, are cumbersome, especially when querying several tables. It is more convenient to use ProcessMaker classes to obtain the same information.

The Load() method can be used by a variety of objects in ProcessMaker to return an associative array of information about the object. It works with many objects that have a unique ID in ProcessMaker. Most classes inherit this function from Propel, but a few reimplement it to add additional information.

array CLASS::Load()

The structure of the associative array returned by Load() depends upon each class. See the documentation below on the different classes.

For example:

Other ProcessMaker classes implement other methods to obtain information such as Cases::loadCase() and Calendar::getCalendarInfo().

AdditionalTables class

The AdditionalTables class is defined in workflow/engine/classes/model/AdditionalTables.php and is used to manipulate PM Tables and Report Tables in ProcessMaker, whose definitions are stored in the wf_<WORKSPACE>.ADDITIONAL_TABLES table in the database. The PmTable class inherits from the the AdditionalTables class.

AdditionalTables::Load()

array AdditionalTables::Load(string $uid)

Return Value:

array (

string ["ADD_TAB_UID"]: The unique ID of the table.

string ["ADD_TAB_NAME"]: The name of the table.

string ["ADD_TAB_CLASS_NAME"]: The Propel class name of the table.

string ["ADD_TAB_DESCRIPTION"]: The description of the table.

int ["ADD_TAB_SDW_LOG_INSERT"]: Set to 1 if insertions are logged. Otherwise, set to 0. No longer used in version 2.0.

int ["ADD_TAB_SDW_LOG_UPDATE"]: Set to 1 if updates are logged. Otherwise, set to 0. No longer used in version 2.0.

int ["ADD_TAB_SDW_LOG_DELETE"]: Set to 1 if deletions are logged. Otherwise, set to 0. No longer used in version 2.0.

int ["ADD_TAB_SDW_LOG_SELECT"]: Set to 1 if selects are logged. Otherwise, set to 0. No longer used in version 2.0.

int ["ADD_TAB_SDW_MAX_LENGTH"]: Set the maximum length of the log. No longer used in version 2.0.

int ["ADD_TAB_SDW_AUTO_DELETE"]: Set to 1 if the log should be automatically deleted when the table is deleted. No longer used in version 2.0.

string ["ADD_TAB_PLG_UID"]: Unique ID of the table's plugin, if it exists.

string ["DBS_UID"]: Unique ID of the database connection used by the table. Set to "workflow" for the wf_<WORKSPACE> database and "rp" for the rp_<WORKSPACE> database.

string ["PRO_UID"]: If a report table, the unique ID of the process that contains the report table. For PM Tables, set to "" (empty string).

string ["ADD_TAB_TYPE"]: Type of report table, which can be "GRID" or "NORMAL". If a PM Table, then "" (empty string).

string ["ADD_TAB_GRID"]: If a grid report table, then the name of the grid object (which is generally the grid name in camel case with spaces removed concatenated with the word "Object"), followed by a dash and the grid Dynaform's unique ID. For example, a grid named "Clients Grid" might be stored as "clientsGridObject-2426857374f3d2647f1ef11072861555".

string ["ADD_TAB_TAG"]: Tags to identify the table. In version 2.0, this is always "" (empty string).

)

Example:

AdditionalTables::loadByName()

array AdditionalTables::loadByName()

Return Value:
Same as AdditionalTables::Load().

Example:

AppDelegation class

Class to manipulate case delegations. A case delegation happens when a case is routed to another task in the process and a user is delegated to work on that task. A case delegation also happens when a case is unpaused and when a case is reassigned (i.e., delegated to a different user). Delegations are distinguished by their delegation index, which counts delegations in a case starting from the number 1 and increments with each new delegation. The case delegation information is stored in the wf_<WORKSPACE>.APP_DELEGATION table and the AppDelegation class is defined in workflow/engine/classes/model/AppDelegation.php.

AppDelegation::Load()

AppDelegation::Load() returns an array of information about a specified case delegation.

array AppDelegation::Load(string $AppUid, string $sDelIndex)

Parameters:

• string $AppUid: The unique ID for a case.
• string $DelIndex: The delegation index. This index counts the case delegations (i.e., routing the case to a task and delegation of that task to a user) starting from the number 1.

Note: $DelIndex can be set to current delegations that have a status of "OPEN" and past delegations that have a status of "CLOSED", but it can't be set to future delegations that haven't yet occurred and don't yet have a record in the wf_<WORKSPACE>.APP_DELEGATION table.

Return Value:
An associative array with the following information about the case delegation:
array (

string ["APP_UID"]: The unique ID of the case.

int ["DEL_INDEX"]: The index of this delegation in the case. Delegation indexes start counting from the number 1.

int ["DEL_PREVIOUS"]: The index of the previous delegation in the case. If there was no previous delegation, because this delegation started the case, then set to 0.

string ["PRO_UID"]: The unique ID of the process.

string ["TAS_UID"]: The unique ID of the task executed by this delegation.

string ["USR_UID"]: The unique ID of the User delegated (designated) to work on the task.

string ["DEL_TYPE"]: The type of delegation, which is almost always "NORMAL"

string ["DEL_THREAD"]: The thread of this delegation. Threads start counting from the number 1 and are used to keep track of the different branches in a process.

string ["DEL_THREAD_STATUS"]: The status of this delegation, which can be either "OPEN" or "CLOSED".

string ["DEL_PRIORITY"]: The priority of this delegation, which can be "1" (very low), "2" (low), "3" (normal), "4" (high) or "5" (very high).

string ["DEL_DELEGATE_DATE"]: The datetime in "YYYY-MM-DD HH:MM:SS" format when this delegation was designated (delegated) to a user.

string ["DEL_INIT_DATE"]: The datetime in "YYYY-MM-DD HH:MM:SS" format when this delegation was initiated. If the case was reassigned to another user, then this field will be set to NULL.

string ["DEL_TASK_DUE_DATE"]: The datetime in "YYYY-MM-DD HH:MM:SS" format when this delegation is scheduled to be completed, based upon the expected Task Duration and calculated with the calendar of the user->task->process->workspace (depending on which is defined). Note that the due date is calculated when the case routes to another task in the process or when the case is unpaused or reassigned to another user.

string ["DEL_FINISH_DATE"]: The datetime in "YYYY-MM-DD HH:MM:SS" format when the delegation was finished, meaning that its status was changed to "CLOSED". If it hasn't yet finished, then set to NULL. Note that a delegation can be finished without completing the steps in the task, which can happen when a case is canceled, paused or forcibly routed with PMFDerivateCase().

float ["DEL_DURATION"]: Deprecated field. Always set to 0.

float ["DEL_QUEUE_DURATION"]: Deprecated field in PM 2.0. Always set to 0.

float ["DEL_DELAY_DURATION"]: Deprecated field in PM 2.0. Always set to 0.

int ["DEL_STARTED"]: Deprecated field in PM 2.0. Always set to 0.

int ["DEL_FINISHED"]: Deprecated field in PM 2.0. Always set to 0.

int ["DEL_DELAYED"]: Deprecated field in PM 2.0. Always set to 0.

string ["DEL_DATA"]: Deprecated field in PM 2.0. Always set to "" (empty string).

float ["APP_OVERDUE_PERCENTAGE"]: Deprecated field in PM 2.0. Always set to 0.

)

Example:
If the due date for the current case delegation has already passed (i.e., is less than the current datetime), then display a warning message.

AppDocument class

The AppDocument class is defined in workflow/engine/classes/model/AppDocument.php and is used to manipulate uploaded files, Input Document files and generated Output Documents in ProcessMaker. Note that an AppDocument is a document associated with a particular case and is not the definition of an Input Document or an Output Document. The record for an AppDocument is stored in the wf_<WORKSPACE>.APP_DOCUMENT table and its file(s) are located in the <INSTALL-DIRECTORY>/shared/sites/<WORKSPACE>/files/<CASE-UID>/ directory.

AppDocument::Load()

AppDocument::Load() returns information about an attached file, Input Document file or generated Output Document.

array AppDocument::Load(string $uid, int $iVersion = null)

Parameters:

• string uid: The unique ID of an AppDocument, which can be found in the following ways:
  • Use the inputDocumentList() or outputDocumentList() web services.
  • Query the wf_<WORKSPACE>.APP_DOCUMENT.APP_DOC_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='APP_DOC_FILENAME'
• int iVersion: Optional. The version number of the AppDocument, where the first version is 1, the second is 2, etc. If not included or set to null, the last available version of the AppDocument is returned. The version number will always be 1 if versioning is not enabled in the definition of an Input Document.

Return Value:
An associative array with the following elements:
array(

string ["APP_DOC_UID"]: The unique ID of the AppDocument.

int ["DOC_VERSION"]: The version number of the AppDocument. Counting starts from 1. Even if versioning isn't enabled, AppDocuments will have a version number.

string ["APP_UID"]: The unique ID of the case where the AppDocument was uploaded (if an attached file or Input Document file) or generated (if an Output Document). Attached files uploaded through the HOME > Documents interface will not have an APP_UID.

int ["DEL_INDEX"]: The delegation index of the task where the AppDocument was uploaded or generated. Attached files uploaded through the HOME > Documents interface will not have an APP_UID.

string ["DOC_UID"]: The unique ID of the Input Document or Output Document definition. If an attached file, then will be set to "-1".

string ["USR_UID"]: The unique ID of the user who uploaded or generated the AppDocument.

string ["APP_DOC_TYPE"]: The type of AppDocument, which can be: "ATTACHED", "INPUT" or "OUTPUT". Note that the files uploaded through the HOME > Documents interface are "INPUT".

string ["APP_DOC_CREATE_DATE"]: Datetime when the AppDocument was created in the "YYYY-MM-DD HH:MM:SS" format. For attached files and Input Document files, this is the time when the file was uploaded. For Output Documents, this is the time when its files were generated.

int ["APP_DOC_INDEX"]: The index number for the AppDocument. Index numbers are used by Input Documents to determine the order in which they are displayed in the list of files. Counting starts from the number 1.

string ["FOLDER_UID"]: The unique ID of the folder where the file is found under HOME > Documents. If not located in a folder, then set to "" (empty string). Note that this folder is not related to the location of the AppDocument's files, which is stored in the file system.

string ["APP_DOC_PLUGIN"]: By default set to "" (empty string).

string ["APP_DOC_TAGS"]: Tags for the AppDocument, separated by commas. If there are no tags, then set to NULL. Tags are used to identify and find AppDocuments. Files uploaded through HOME > Documents will have a tag of "EXTERNAL".

string ["APP_DOC_STATUS"]: The status of the AppDocument, which can be: "ACTIVE", "INACTIVE" or "DELETED"

string ["APP_DOC_STATUS_DATE"]: The datetime when the status changed. If never changed, then set to NULL.

string ["APP_DOC_TITLE"]: The title of the AppDocument. This feature is no longer used and is always set to "" (empty string).

string ["APP_DOC_COMMENT"]: The comment that was entered when an Input Document file was uploaded.

string ["APP_DOC_FILENAME"]: The filename of the AppDocument. The extension is included in the filename for Input Document files and attached files, but not included for Output Documents.

)

Example:
Get the files for the Input Document with the UID "86062325056a02c39e62e51079553933" and place information about them in a grid variable that will be displayed in a subsequent Dynaform:

AppDocument::remove()

AppDocument::remove() deletes an AppDocument, which is can be an attached file, Input Document file or generated Output Document file. This method does not remove the file from the server's file system, nor does it remove the file's record from the APP_DOCUMENT table in the database. It simply changes the APP_DOCUMENT.APP_DOC_STATUS from 'ACTIVE' to 'DELETED'.

AppDocument::Remove(string $sAppDocUid, int $iVersion = 1)

Parameters:

• string $sAppDocUid: The unique ID of an AppDocument, which can be found in the following ways:
  • Use the inputDocumentList() or outputDocumentList() web services.
  • Query the wf_<WORKSPACE>.APP_DOCUMENT.APP_DOC_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='APP_DOC_FILENAME'
• int $iVersion: Optional. The AppDocument's version number, which starts counting from the number 1. To get the latest version, check the ['DOC_VERSION'] returned by AppDocument::load('UID', null).

Return Value:
None. Wrap the code in try{...} catch{...} to find out whether there was a failure executing the method.

Parameters:

The following code deletes all the files in the current case. For each file, it calls AppDocument::remove(). It also constructs the path to the file depending upon whether it is an Output Document file or an Input Document file (or attached file) and then calls unlink() to delete the file from the file system.

AppDocument::update()

AppDocument::update() is used to change the filename, comments and/or title of an AppDocument, which are saved in the CONTENT table in the database.

int AppDocument::update(array $aData)

Parameters:

• array $aData: An associative array of properties to set in the AppDocument, with the following content: array( 'APP_DOC_UID' => 'AppDocument ID', //required 'DOC_VERSION' => Version_Number, //required. Numbering starts from 1. 'APP_DOC_TITLE' => 'New Title', //optional. Titles are deprecated since no longer used. 'APP_DOC_COMMENT' => 'New Comment', //optional. Comments are only displayed in Input Document steps. 'APP_DOC_FILENAME' => 'filename.ext', //optional. 'APP_DOC_FIELDNAME' => 'fieldname' //optional in version 3.1 and later ) Note: Set 'APP_DOC_FIELDNAME' to 'gridID_rowNumber_fieldname' for Files in grids and '[gridID][rowNumber][fieldname]' for multipleFiles in grids.

Return Value:
An integer indicating whether commit to the database completed successfully.

Example:

If a file was uploaded to a File field associated with the @@partSpecFile variable, then it renames the file to include the part number which is stored in the variable @@partNumber:

AppFolder class

The AppFolder class is defined in workflow/engine/classes/model/AppFolder.php and is used to manipulate folders found under HOME > Documents in ProcessMaker, which are stored in the wf_<WORKSPACE>.APP_FOLDER table in the database.

AppFolder::Load()

AppFolder::Load() returns an array of information about an AppFolder object.

array AppFolder::Load(string $uid)

Parameters:

• string uid: The unique ID of the AppFolder.

Return Value:
An associative array with the following elements:
array (

string ["FOLDER_UID"]: The unique ID of the folder.

string ["FOLDER_PARENT_UID"]: The unique ID of the parent folder. If the folder is in the root folder, then set to "/".

string ["FOLDER_NAME"]: The name of the folder.

string ["FOLDER_CREATE_DATE"]: The datetime the folder was created in "YYYY-MM-DD HH:MM:SS" format.

string ["FOLDER_UPDATE_DATE"]: The datetime the folder was last updated in "YYYY-MM-DD HH:MM:SS" format.

)

Example:

AppHistory class

The AppHistory class, which is defined in workflow/engine/classes/model/AppNotes.php, is used to store the changes in field values in each Dynaform. This information is used by the Change Log and is permanently stored the wf_<WORKSPACE>.APP_HISTORY table in the database. This information can be used for auditing purposes. Note that the class doesn't automatically store changes made by Process Supervisors.

AppHistory::getDynaformHistory()

AppHistory::getDynaformHistory() returns a Criteria object to query the APP_HISTORY table for a specified case and task (and optionally a specified Dynaform). This Criteria object can be used with the AppHistoryPeer::doSelect() or AppHistoryPeer::doSelectOne() methods to get AppHistory objects.

Criteria AppHistory::getDynaformHistory(string $PRO_UID, string $TAS_UID, string $APP_UID, string $DYN_UID="")

Return Value:
A Criteria object.

Getting AppHistory Information

To get an associative array of information from an AppHistory object, first use the getDynaformHistory() method to return a Criteria object. Then, pass that Criteria object to the doSelect() or doSelectOne() method to populate objects. Finally, call the toArray() method to export an associative array of information about the AppHistory object.

Example:

The toArray() method will return an associative array with the following structure:
array (

string ["APP_UID"]: The unique ID of the case.

int ["DEL_INDEX"]: The delegation index of the task that contains the Dynaform step.

string ["PRO_UID"]: The unique ID of the process step.

string ["TAS_UID"]: The unique ID of the task that contains the Dynaform step.

string ["DYN_UID"]: The unique ID of the Dynaform.

string ["USR_UID"]: The unique ID of the user who submitted the Dynaform.

string ["APP_STATUS"]: The status of the case when the data was submitted, which can be "TO_DO" or "DRAFT".

string ["HISTORY_DATE"]: The datetime when the data was submitted in the "YYYY-MM-DD HH:MM:SS" format.

string ["HISTORY_DATA"]: A serialized associative array of the case data when it was submitted to the database. For more information on the serialized format, see Variable Storage.

)

AppMessage class

The AppMessage class is defined in workflow/engine/classes/model/AppMessage.php and is used to manipulate email notifications in ProcessMaker, which are stored in the wf_<WORKSPACE>.APP_MESSAGE table in the database.

Getting AppMessage Information

Because AppMessage doesn't have a primary key, the Load() method will not work. Instead use the toArray() method to get an array of information about the AppMessage object.

array (

string ["APP_MSG_UID"]: The unique ID of the email message (i.e., the AppMessage object).

string ["MSG_UID"]: This field is no longer used and is always "" (an empty string).

string ["APP_UID"]: The unique ID of the case that sent the message.

string ["DEL_INDEX"]: The delegation index of the task where the message was generated.

string ["APP_MSG_TYPE"]: Type of message, which can be "TEST" (when configuring Email settings), "DERIVATION" (when automatically notifying the next assigned users) or "TRIGGER" (when sending messages with a Trigger function or an Event).

string ["APP_MSG_SUBJECT"]: The subject line of the email.

string ["APP_MSG_FROM"]: The email address of the message sender.

string ["APP_MSG_TO"]: The list of email addresses of the recipients.

string ["APP_MSG_BODY"]: The text of the body of the email message.

string ["APP_MSG_DATE"]: Datetime when the message was created in "YYYY-MM-DD HH:MM:SS" format.

string ["APP_MSG_CC"]: List of email addresses of the carbon copy recipients.

string ["APP_MSG_BCC"]: List of email addresses of the blind carbon copy recipients.

string ["APP_MSG_TEMPLATE"]: The filename of the email template, which is found in the public directory.

string ["APP_MSG_STATUS"]: The status of the message which can be "sent" or "pending". When "pending", the message has not yet been sent to the email server by cron.php.

string ["APP_MSG_ATTACH"]: A serialized array of the filenames sent as attachments with the email.

string ["APP_MSG_SEND_DATE"]: Datetime when the message was sent in "YYYY-MM-DD HH:MM:SS" format.

)

Example:

AppNotes class

Case notes can be created, updated and deleted using the AppNotes class (and its parent class BaseAppNotes), which is defined in the file workflow/engine/classes/model/AppNotes.php and needs to be imported with require_once() before using the class. Case Notes are stored in the wf_<WORKSPACE>.APP_NOTES table in the database. Note that AppNotes do not have a primary key, so they do not have a Load() method.

AppNotes::postNewNote()

The postNewNote() method creates a new case note in the specified case.

array AppNotes::postNewNote(string $appUid, string $usrUid, string $noteContent, boolean $notify=true, string $noteAvailability="PUBLIC", string $noteRecipients="", string $noteType="USER", variant $noteDate="now")

Parameters:

• string $appUid: The unique ID of the case where the new note will be posted. Note that this parameter is not restricted by role based access control, so this can be any case.
• string $usrUid: The unique ID of the user who will post the note. Note that this parameter is not restricted by role based access control, so this can be any user.
• string $noteContent: The content of the note, which can contain HTML markup. The content should be passed through PHP's addslashes() function, so that it can be inserted in the database without problems.
• boolean $notify: Optional. Set to true to send an email notification with the content of the new note.
• string $noteAvailability: Optional. Set to "PUBLIC" if every user can see the case note or set to "PRIVATE" if only people who have rights to open the case can view it. Note that "PUBLIC" is not very public, since only people who can see the case in a list under the HOME menu will be able to actually view it.
• string $noteRecipients: Optional. By default, notifications will be sent to all users who have participated in the case if $notify is set to true. To send the notification to different people, enter a list of email addresses, which are separated by commas ",".

Example: "bill@example.com, Sally.Smith@example.com, Harvey Snow <snow.example.com>, \"Emerson, Ralph\" <ralph@example>"

• string $noteType: Optional. Set to "USER" to specify that the note was posted by a user.
• variant $noteDate: Optional. The date and time of the note, which is set to the current date and time by default. To set a different date and time, either enter a date-time string understood by strtotime() or a PHP timestamp.

Examples: "+5 days", "next Thursday", "+3 weeks 2 days 4 hours 40 minutes", "2012-03-25 14:07", 1307708880

Return Value:
Returns an associative array. If the new note was posted successfully, the array contains:

array('success' => 'success', 'message' => 'Saved...')

If an exception occurred, then the array contains:

array('success' => 'failure', 'message' => 'ERROR-MESSAGE')

Note that the return value does not indicate whether any exceptions occurred while sending out email notifications for the case note.

Note: Instantiate a new AppNotes object for each new case note. If trying to call the postNewNote() multiple times on the same AppNotes object, only the first note will be saved to the database.

Example:
The currently logged-in user posts a note in the current case that says, "This case is urgent!":

AppNotes::getNotesList()

AppNotes::getNotesList() searches for all the notes in a specified case that a specified user has the right to see, and returns an array with a Criteria object and an array of information about all the case notes.

array AppNotes::getNotesList(string $appUid, string $usrUid, int $start, int $limit)

Return Value:
array (

Criteria object ["criteria"]:

array ["array"]:

(

int ["totalCount"]: The number of notes.

array ["notes"]:

(

array [0]:

(

string ["APP_UID"]: The unique ID for the case.

string ["USR_UID"]: The unique ID of the user who posted the case note.

string ["NOTE_DATE"]: The datetime when the note was posted in "YYYY-MM-DD HH:MM:SS" format.

string ["NOTE_CONTENT"]: The text of the case note.

string ["NOTE_TYPE"]: The type of the case note, which is always "USER".

string ["NOTE_AVAILABILITY"]: The availability of the note, which is always "PUBLIC", meaning that anyone who can see the note in a list can also read the note.

string ["NOTE_ORIGIN_OBJ"]: The object where the note originated. This is always "" (an empty string).

string ["NOTE_AFFECTED_OBJ1"]: The first object affected by the note. This is always "" (an empty string).

string ["NOTE_AFFECTED_OBJ2"]: The second object affected by the note. This is always "" (an empty string).

string ["NOTE_RECIPIENTS"]: The recipients of the note, which by default are the email addresses of all the users who participated in the case up to the time when the note was posted.

string ["USR_USERNAME"]: The username of the user who posted the note.

string ["USR_FIRSTNAME"]: The first name of the user who posted the note.

string ["USR_LASTNAME"]: The last name of the user who posted the note.

string ["USR_EMAIL"]: The email address of the user who who posted the note.

)

...

)

)

)

Example:
Delete the first note posted by the current user in the current case (if it exists):

Base Propel classes

Most ProcessMaker classes (which are used to represent objects stored in database tables) are inherited from Propel's abstract base classes, which define the common methods and the member variables and constants. Each ProcessMaker class has a corresponding base class named BaseCLASS. For example: BaseAppNotes, BaseTriggers, BaseUsers, etc. In addition, each Peer class has a corresponding base Peer class named BaseCLASSPeer. For example: BaseAppNotesPeer, BaseTriggersPeer, BaseUsersPeer, etc.

Some of the commonly-used base class methods and member variables/constants are listed below. If a complete list is necessary, it is recommended to read the source code of the base classes.

Common Base Class Variables

The base classes commonly have the following protected variables (which can only be accessed by inherited classes).

• protected static object $peer: Holds the Peer class for this class. For example: AppNotesPeer
• protected boolean $alreadyInSave: Flag to prevent an endless validation loop that occurs if this object is referenced by another object in this transaction.
• protected boolean $alreadyInValidation: Flag to prevent an endless validation loop that occurs if this object is referenced by another object in this transaction.
• protected variant $field: Each field in the database has a corresponding protected member variable, whose name is in lowercase. For example, the APP_UID field would be $app_uid and the NOTE_ORIGIN_OBJ field would be $note_origin_obj. Because these member variables are protected, they are generally accessed through their corresponding getter and setter methods.

Field Getters and Setters

Each field in the base class has a corresponding getter and setter method to access it. These are generally named with camel case. For example, the value of the APP_UID field (whose protected member variable is named $app_uid) is retrieved with the getAppUid() method:

variant BaseCLASS::getAppUid()

Likewise, its value is set with the setAppUid() method:

void BaseCLASS::getAppUid(variant $v)

Note that these getter and setter methods will only work on classes that have been instantiated. Also note that the setter methods only change the value of protected member variables in the class instance. In order for those changes to be committed to the database, call the save() or doUpdate() methods.

For example, to get and set the APP_UID for an AppNotes instance:

BaseCLASS::fromArray()

Populates a CLASS object from data in an array.

void BaseCLASS::fromArray(array $arr, string $keyType = BasePeer::TYPE_PHPNAME)

Parameters:

• array $arr: An associative array of values to populate the object. Its keys are the field names or field positions, depending upon the $keyType parameter.
• string $keyType: The type of field names, which can be one of the following class type constants:
  • BasePeer::TYPE_PHPNAME: The PHP name for the field, which is generally in camel case, such as "AppUid" or "UsrUid".
  • BasePeer::TYPE_COLNAME: The constant name of the column in the database table, such as AppNotesPeer::APP_UID or AppNotesPeer::USR_UID.
  • BasePeer::TYPE_FIELDNAME: The name of the field in the database table, such as "APP_UID" or "USR_UID".
  • BasePeer::TYPE_NUM: The position number of the field in an array, such as 0 or 1. Note that counting starts from 0.

Note: Use BaseCLASS::getFieldNames() to get the field names for CLASS.

Return Value:
None.

BaseCLASS::toArray()

Exports the data of a CLASS object to an array.

array BaseCLASS::toArray(string $keyType = BasePeer::TYPE_PHPNAME)

Parameters:

• string $keyType: The type of field names, which can be one of the following class type constants:
  • BasePeer::TYPE_PHPNAME: The PHP names for the fields, which are generally in camel case, such as "AppUid" or "UsrUid".
  • BasePeer::TYPE_COLNAME: The constant names of the columns in the database table, such as AppNotesPeer::APP_UID or AppNotesPeer::USR_UID.
  • BasePeer::TYPE_FIELDNAME: The names of the fields in the database table, such as "APP_UID" or "USR_UID".
  • BasePeer::TYPE_NUM: The position numbers of the fields in an array. Note that counting starts from 0.

Note: Use BaseCLASS::getFieldNames() to get the field names for CLASS.

Return Value:
An associative array whose keys are the field names or field positions (depending upon the $keyType) and the values are the field values.

BaseCLASS::save()

Commits an object to the database. If it already exists, then it updates the existing record in the database. Otherwise, it inserts a new record. The commit is wrapped in a transaction, so if an exception occurs, it will automatically be rolled back. Make sure that the object's member variables are populated before calling this method.

int BaseCLASS::save(Connection $con = null)

Parameters:

• Connection $con: Optional. The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
Returns the number of affected rows. If an exception occurs, returns null and a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASS::delete()

Deletes an object from the database. The deletion is wrapped in a transaction, so if an exception occurs, it will automatically be rolled back. Make sure that the object's member variables are populated before calling this method.

void BaseCLASS::delete(Connection $con = null)

Parameters:

• Connection $con: Optional. The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
None. If an exception occurs, a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASS::validate()

Validates the object's modified field values and all objects related to this table. If $columns is specified, then only those columns are validated.

boolean BaseCLASS::validate(variant $columns = null)

Parameters:

• variant $columns: Optional. A string with a column name or an array of column names. If set to NULL, then all columns are checked.

Return Value:
Returns true if all specified columns pass validation. If one or more fail, then returns false.

BaseCLASS::getByName()

Retrieves the value of a specified field from the object. The field can be indicated by its PHP property name, its column name, its field name or its position number in an array.

mixed BaseCLASS::getByName(string $name, string $type = BasePeer::TYPE_PHPNAME)

Parameters:

• string $name: The name of the field to retrieve.
• string $type: The type of field name, which can be one of the following class type constants:
  • BasePeer::TYPE_PHPNAME: The PHP name for the field, which is generally in camel case, such as "AppUid" or "UsrUid".
  • BasePeer::TYPE_COLNAME: The constant name of the column in the database table, such as AppNotesPeer::APP_UID or AppNotesPeer::USR_UID.
  • BasePeer::TYPE_FIELDNAME: The name of the field in the database table, such as "APP_UID" or "USR_UID".
  • BasePeer::TYPE_NUM: The position number of the field in an array, such as 0 or 1. Note that counting starts from 0.

Note: Use BaseCLASS::getFieldNames() to get the field names for CLASS.

Return Value:
Returns the value of the field.

BaseCLASS::setByName()

Sets the value of a specified field in the object. The field can be indicated by its PHP property name, its column name, its field name or its position number in an array. Note that this method only sets the value of the object's member variable. Call BaseCLASS::save() to commit this value to the database.

void BaseCLASS::setByName(string $name, mixed $value, string $type = BasePeer::TYPE_PHPNAME)

Parameters:

• string $name: The name of the field whose value will be set.
• mixed $value: The value to set.
• string $type: The type of field name, which can be one of the following class type constants:
  • BasePeer::TYPE_PHPNAME: The PHP name for the field, which is generally in camel case, such as "AppUid" or "UsrUid".
  • BasePeer::TYPE_COLNAME: The constant name of the column in the database table, such as AppNotesPeer::APP_UID or AppNotesPeer::USR_UID.
  • BasePeer::TYPE_FIELDNAME: The name of the field in the database table, such as "APP_UID" or "USR_UID".
  • BasePeer::TYPE_NUM: The position number of the field in an array, such as 0 or 1. Note that counting starts from 0.

Note: Use BaseCLASS::getFieldNames() to get the field names for CLASS.

Return Value:
None.

BaseCLASS::getByPosition()

Gets the value of a specified field in the object by its position in the database table.

mixed BaseCLASS::getByPosition(int $pos)

Parameters:

• int $pos: The position of the field in the database table.

Note: Use BaseCLASS::getFieldNames() to get the field positions for CLASS.

Return Value:
The value of the field.

BaseCLASS::setByPosition()

Sets the value of a specified field in the object by its position in the database table. Note that this method only sets the value of the object's member variable. Call BaseCLASS::save() to commit this value to the database.

void BaseCLASS::setByPosition(int $pos, mixed $value)

Parameters:

• int $pos: The position of the field in the database table.

Note: Use BaseCLASS::getFieldNames() to get the field positions for CLASS.

• mixed $value: The value to set.

Return Value:
None.

BaseCLASS::getFieldNames()

Returns an array of field names for CLASS.

array BaseCLASS::getFieldNames(string $type = BasePeer::TYPE_PHPNAME)

Parameters:

• string $type: The type of field names, which can be one of the following class type constants:
  • BasePeer::TYPE_PHPNAME: The PHP names for the fields, which are generally in camel case, such as "AppUid" or "UsrUid".
  • BasePeer::TYPE_COLNAME: The constant names of the columns in the database table, such as AppNotesPeer::APP_UID or AppNotesPeer::USR_UID.
  • BasePeer::TYPE_FIELDNAME: The names of the fields in the database table, such as "APP_UID" or "USR_UID".
  • BasePeer::TYPE_NUM: The position numbers of the fields in an array, such as 0 or 1. Note that counting starts from 0.

Return Value:
An array of field names for CLASS.

BaseCLASS::getByName()

Retrieves the value of a specified field from the object. The field can be indicated by its PHP property name, its column name, its field name or its position number.

mixed BaseCLASS::getByName(string $name, string $type = BasePeer::TYPE_PHPNAME)

Parameters:

• string $name: The name of the field to retrieve.
• string $type: The type of field names, which can be one of the following class type constants:
  • BasePeer::TYPE_PHPNAME: The PHP names for the fields, which are generally in camel case, such as "AppUid" or "UsrUid".
  • BasePeer::TYPE_COLNAME: The constant names of the columns in the database table, such as AppNotesPeer::APP_UID or AppNotesPeer::USR_UID.
  • BasePeer::TYPE_FIELDNAME: The names of the fields in the database table, such as "APP_UID" or "USR_UID".
  • BasePeer::TYPE_NUM: The position numbers of the fields in an array, such as 0 or 1. Note that counting starts from 0.

Return Value:

• mixed: Value of the field.

Base Peer Class Methods

BaseCLASSPeer::doCount()

Counts the number of selects object(s) from the database query, based upon a Criteria object.

int BaseCLASSPeer::doCount(Criteria $criteria, boolean $distinct = false, Connection $con)

Parameters:

• Criteria $criteria: The Criteria object used to build the SELECT statement.
• boolean $distinct: Optional. Set to true if each row should be distinct. By default set to false.
• Connection $con: Optional. The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
Returns the number found by the SELECT statement. If an exception occurs, returns null and a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::doSelect()

Selects object(s) from the database based upon a Criteria object.

array BaseCLASSPeer::doSelect(Criteria $criteria, Connection $con)

Parameters:

• Criteria $criteria: The Criteria object used to build the SELECT statement.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
Returns an array of CLASS objects. If an exception occurs, returns null and a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::doSelectOne()

Selects one object from the database based upon a Criteria object.

ResultSet BaseCLASSPeer::doSelect(Criteria $criteria, Connection $con)

Parameters:

• Criteria $criteria: The Criteria object used to build the SELECT statement.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
Returns the first CLASS object found by the SELECT statement. If an exception occurs, returns null and a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::doSelectRS()

Selects object(s) from the database based upon a Criteria object and returns a ResultSet object.

ResultSet BaseCLASSPeer::doSelectRS(Criteria $criteria, Connection $con)

Parameters:

• Criteria $criteria: The Criteria object used to build the SELECT statement.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
Returns an ResultSet object. If an exception occurs, returns null and a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::doInsert()

Inserts an object, sending INSERT statements to the database.

int BaseCLASSPeer::doInsert(mixed $values, Connection $con = null)

Parameters:

• mixed $values: A Criteria or CLASS object containing data that is used to create the INSERT statement.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:

• mixed: The new primary key or null if an exception occurs. If an exception occurs, a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::doUpdate()

Updates object(s), sending UPDATE statements to the database.

int BaseCLASSPeer::doUpdate(mixed $values, Connection $con = null)

Parameters:

• mixed $values: A Criteria or CLASS object, a primary key or an array of primary keys for the object(s) to update in the database.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:

• int: The number of deleted rows. If an exception occurs a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::doDelete()

Deletes object(s), sending DELETE statements to the database.

int BaseCLASSPeer::doDelete(mixed $values, Connection $con = null)

Parameters:

• mixed $values: A Criteria or CLASS object, a primary key or an array of primary keys for the object(s) to delete in the database.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:

• int: The number of deleted rows. If an exception occurs a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::doDeleteAll()

Deletes all records in a database table.

int BaseCLASSPeer::doDeleteAll(Connection $con = null)

Parameters:

• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:

• int: The number of deleted rows. If an exception occurs a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::retrieveByPK()

Retrieve a CLASS object by its primary key. This method only exists if the CLASS has a primary key, which is why the AppNotes and AppHistory classes do not have this method.

object BaseCLASSPeer::retrieveByPK(mixed $pk, Connection $con = null)

Parameters:

• mixed $pk: The value of the primary key.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
A CLASS object. If an exception occurs, returns null and a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::retrieveByPKs()

Retrieve multiple CLASS objects by their primary keys. This method only exists if the CLASS has a primary key, which is why the AppNotes and AppHistory classes do not have this method.

array BaseCLASSPeer::retrieveByPKs(array $pks, Connection $con = null)

Parameters:

• array $pks: An array of primary keys.
• Connection $con: The connection to use. If set to null, then it will automatically create a Propel connection to the default database for the class.

Return Value:
An array of CLASS objects. If an exception occurs, returns null and a PropelException will be thrown. Check @@__ERROR__ or $_SESSION['__ERROR__'] for the exception message.

BaseCLASSPeer::addSelectColumns()

Adds all the columns to a Criteria object, so that it can be used with one of the doSelect() methods to retrieve CLASS object(s).

void BaseCLASSPeer::addSelectColumns(Criteria $criteria)

Parameters:

• Criteria $criteria: A criteria object, which will be configured to retrieve all of the fields in the CLASS.

Return Value:
None.

Calendar class

The Calendar class is defined in workflow/engine/classes/class.calendar.php and is used to manipulate calendars in ProcessMaker, which are stored in the CALENDAR_DEFINITION,CALENDAR_BUSINESS_HOURS, CALENDAR_HOLIDAYS and CALENDAR_ASSIGNMENTS tables in the database.

Calendar::getCalendarInfo()

Calendar::getCalendarInfo() returns information about a task.

array Calendar::getCalendarInfo(string CalendarUid)

Parameters:

• string CalendarUid: The unique ID of a Calendar, which can be found with the Calendar::loadByCalendarName() method or by querying the wf_<WORKSPACE>.CALENDAR_DEFINITION.CALENDAR_UID field in the database.

Return Value:
An associative array with the following elements:
array (

string ["CALENDAR_UID"]: Unique ID for the calendar in the CALENDAR_DEFINITION table.

string ["CALENDAR_NAME"]: The name of the calendar.

string ["CALENDAR_CREATE_DATE"]: Datetime when the calendar was created in "YYYY-MM-DD HH:MM:SS" format.

string ["CALENDAR_UPDATE_DATE"]: Datetime when the calendar was last updated in "YYYY-MM-DD HH:MM:SS" format.

string ["CALENDAR_DESCRIPTION"]: Description of the calendar.

string ["CALENDAR_STATUS"]: The calendar's status, which can be "ACTIVE" or "INACTIVE".

string ["CALENDAR_WORK_DAYS"]: The calendar's workdays, separated by "|" (vertical bars), where 0 = Sunday, 1 = Monday, 2 = Tuesday, etc. For example: "0|5|2" (Sunday, Thursday, Tuesday).

array ["CALENDAR_WORK_DAYS_A"]: The calendar's workdays in an array. For example: array("0", "5", "2")

array ["BUSINESS_DAY"]: An array of the business hours for the calendar (which are drawn from the CALENDAR_BUSINESS table). Note that the counting of the array starts from 1, and not from 0 like a normal array.

(

array [1]: An array with data from each business hour record.

(

string ["CALENDAR_UID"]: The unique ID of the calendar in the CALENDAR_DEFINITION table.

string ["CALENDAR_BUSINESS_DAY"]: The day of the week, where 0 = Sunday, 1 = Monday, 2 = Tuesday, etc. 7 represents all other business days that haven't been otherwise specified.

string ["CALENDAR_BUSINESS_START"]: The start of the business hours in "HH:MM" format.

string ["CALENDAR_BUSINESS_END"]: The end of the business hours in "HH:MM" format.

string ["UPPER(CALENDAR_BUSINESS_HOURS.CALENDAR_BUSINESS_DAY)"]: The day of the week, where 0 = Sunday, 1 = Monday, 2 = Tuesday, etc. 7 represents all other business days which haven't been otherwise specified.

string ["UPPER(CALENDAR_BUSINESS_HOURS.CALENDAR_BUSINESS_START)"]: The start of the business hours in "HH:MM" format.

)

...

)

array ["HOLIDAY"]: An array of holidays for the calendar, which are drawn from the CALENDAR_HOLIDAYS table. Note that the counting of the array starts from 1, and not from 0 like a normal array.

(

array [1]: An array of information about each holiday record.

(

string ["CALENDAR_UID"]: The unique ID of the calendar in the CALENDAR_DEFINITION table.

string ["CALENDAR_HOLIDAY_NAME"]: The name of the holiday.

string ["CALENDAR_HOLIDAY_START"]: The date when the holiday starts in "YYYY-MM-DD" format. Note that years are ignored when determining holidays.

string ["CALENDAR_HOLIDAY_END"]: The date when the holiday ends in "YYYY-MM-DD" format. Note that years are ignored when determining holidays.

)

...

)

)

Example:
Display the holidays in a grid named @@holidayGrid, which has fields named "CALENDAR_HOLIDAY_NAME", "CALENDAR_HOLIDAY_START" and "CALENDAR_HOLIDAY_END":

Calendar::loadByCalendarName()

Calendar::loadByCalendarName() looks up a calendar by its name and returns information about it.

array Calendar::loadByCalendarName(string calendarName)

Parameters:

• string calendarName: The calendar name, which is case sensitive.

Return Value:
An associative array with the following elements:
array(

string ["CALENDAR_UID"]: The unique ID of the calendar.

string ["CALENDAR_NAME"]: The name of the calendar.

string ["CALENDAR_CREATE_DATE"]: The datetime when the calendar was created in "YYYY-MM-DD HH:MM:SS" format.

string ["CALENDAR_UPDATE_DATE"]: The datetime when the calendar was last updated in "YYYY-MM-DD HH:MM:SS" format.

string ["CALENDAR_DESCRIPTION"]: The description of the calendar.

string ["CALENDAR_STATUS"]: The status of the calendar, which can be "ACTIVE" or "INACTIVE".

)

Example:

Cases class

The Cases class provides methods for manipulating ProcessMaker cases and is defined in the file workflow/engine/classes/class.case.php.

Cases::loadCase()

Cases::loadCase() returns an associative array of information about a specified case, as long as the user current logged-in has privileges to access the case. If the task is specified with the $iDelIndex parameter, it also returns information about the task.

array Cases::loadCase(string $sAppUid, int $iDelIndex = 0)

Parameters:

• string $sAppUid: The unique ID for a case. Set to @@APPLICATION for the current case or look it up in the wf_<WORKSPACE>.APPLICATION.APP_UID field for other cases.
• int $iDelIndex: Optional. The delegation index, which is a positive integer that counts tasks in a process, starting from 1. If not specified or set to 0 then no task information will be returned. Set to @%INDEX for the current task in the current process or look it up in the wf_<WORKSPACE>.APP_DELEGATION.DEL_INDEX field for other cases.

Return Value:
Returns an associative array of information about a case with the following structure:

array (

string ["APP_UID"]: The unique ID for the case. Ex: "6654103664dcaee7a15e1e5076744766"

int ["APP_NUMBER"]: The case number. Ex: 53

string ["APP_PARENT"]: This value is always '' (empty string). To find the parent case for a subprocess case, do database search with executeQuery() in the wf_WORKSPACE.SUB_APPLICATION.APP_PARENT field.

string ["APP_STATUS"]: The status of the case, which can be "TO_DO", "DRAFT", "PAUSED", "CANCELLED", "COMPLETED" or "UNASSIGNED".

string ["PRO_UID"]: The unique ID for the process.

string ["APP_PROC_STATUS"]: Indicates the status of the process, which is always '', since new cases can not be started if the process is set to 'INACTIVE'.

string ["APP_PROC_CODE"]: A string to identify the case in the case tracker. This value can be set with the setCaseTrackerCode() function.

string ["APP_PARALLEL"]: Deprecated. Always set to "N" (even when there are parallel tasks).

string ["APP_INIT_USER"]: The unique ID of the user who initiated the case.

string ["APP_CUR_USER"]: The unique ID of the user who is currently assigned to work on the case. Note that this field may not updated due to this bug, so use ["CURRENT_USER_UID"] instead.

string ["APP_CREATE_DATE"]: The datetime when the case was created in the format "YYYY-MM-DD HH:MM:SS". Ex: "2011-04-25 13:08:01"

string ["APP_INIT_DATE"]: The datetime when the case was initiated in the format "YYYY-MM-DD HH:MM:SS". This is always the same as the ["APP_CREATE_DATE"].

string ["APP_FINISH_DATE"]: The datetime when the case finished in the format "YYYY-MM-DD HH:MM:SS". If the case hasn't finished yet, then set to "1902-01-01 00:00:00".

string ["APP_UPDATE_DATE"]: The datetime when the case was last updated in the format "YYYY-MM-DD HH:MM:SS".

array ["APP_DATA"]: An associative array of the system variables and case variables for the case when it was last stored, in the following format:

string ["SYS_LANG"]: See system variables.

string ["SYS_SKIN"]: See system variables.

string ["SYS_SYS"]: See system variables.

string ["APPLICATION"]: See system variables.

string ["PROCESS"]: See system variables.

string ["TASK"]: See system variables.

string ["INDEX"]: See system variables.

string ["USER_LOGGED"]: See system variables.

string ["USR_USERNAME"]: See system variables.

string ["PIN"]: See system variables.

string ["var1"]: The first case variable (which is a Dynaform field or defined in a trigger). Note that case variables names are case sensitive.

string ["var2"]: The second case variable.

...

string ["APP_PIN"]: An MD5 hash of the case PIN, which can be used when logging in with the Case Tracker. For the unencrypted PIN, see ['APP_DATA']['PIN'].

string ["APP_TITLE"]: The case title. If a custom case title has not been set in the task properties, then this will be the case number with "#" prepended. Ex: "#53"

string ["APP_DESCRIPTION"]: The case description. If a custom case description has not been set in the task properties, then this will be "" (an empty string).

string ["STATUS"]: The case status, translated into the current system language. Check the translations of the "ID_TO_DO", "ID_DRAFT", "ID_CANCELLED", "ID_PAUSED", and "ID_COMPLETED" messages. In English, they are "To do", "Draft", "Canceled", "Paused", and "Completed", respectively.

string ["TITLE"]: The same as the ["APP_TITLE"].

string ["CREATOR"]: The first and last name of the user who created the case. Ex: "John Doe"

string ["CREATE_DATE"]: The datetime when the case was created in the format "YYYY-MM-DD HH:MM:SS".

string ["UPDATE_DATE"]: The datetime when the case last updated in the format "YYYY-MM-DD HH:MM:SS".

If the task was specified, then the following keys are also created:

string ["TAS_UID"]: The unique ID for the task.

int ["DEL_INDEX"]: The positive integer identifying the order of the specified task in the process, which starts counting from 1.

int ["DEL_PREVIOUS"]: The positive integer identifying the previous task in the process, which starts counting from 1.

string ["DEL_TYPE"]: The type of delegation for the task, which is generally "NORMAL".

string ["DEL_PRIORITY"]: The priority for the task, which can be "1" (VERY HIGH), "2" (HIGH), "3" (NORMAL), "4" (LOW), "5" (VERY LOW).

string ["DEL_THREAD_STATUS"]: The status of the task's thread, which can be "OPEN" (if the case is TO DO or DRAFT) or "CLOSED" (if the case is CANCELLED, PAUSED or COMPLETED).

int ["DEL_THREAD"]: The positive number for the task's thread, which starts counting from 1.

string ["DEL_DELEGATE_DATE"]: The datetime when the case was routed to the specified task in the process, in the format "YYYY-MM-DD HH:MM:SS".

string ["DEL_INIT_DATE"]: The datetime when the specified task was initiated, which is generally the same as the ["DEL_DELEGATE_DATE"].

string ["DEL_TASK_DUE_DATE"]: The datetime when the task is scheduled to be completed, according to the settings in the task properties and the calendar (which can be determined by the user, task, process or workspace).

string ["DEL_FINISH_DATE"]: The datetime when the task was completed (or canceled). If not yet completed, then set to NULL.

string ["CURRENT_USER_UID"]: The unique ID of the last user assigned to work on the specified task. Note that if the specified task is not the current task in the case, then this will not be the current user assigned to the case.

string ["CURRENT_USER"]: The first and last name of the last user assigned to work on the specified task. Note that if the specified task is not the current task in the case, then this will not be the current user assigned to the case.

)

Example:
Look up the case title, current user and the case variable "ClientName" for the current case and display this information in a message on the next screen:

Cases::loadCaseInCurrentDelegation()

Like Cases::loadCase(), Cases::loadCaseInCurrentDelegation() returns an associative array of information about a specified case, but the delegation index doesn't need to be specified, since it automatically selects the current delegation for the case.

array Cases::loadCaseInCurrentDelegation(string $APP_UID)

Parameters:

• string $APP_UID: The unique ID for a case. Set to @@APPLICATION for the current case or look it up in the wf_<WORKSPACE>.APPLICATION.APP_UID field for other cases.

Return Value:
Returns an associative array with information about the specified case:
array (

string ["APP_UID"]: The case's unique ID.

int ["APP_NUMBER"]: The case's number (which starts counting cases from the number 1).

string ["APP_UPDATE_DATE"]: The last time the case was updated in "YYYY-MM-DD HH:MM:SS" format.

int ["DEL_PRIORITY"]: The case's priority which is a number between 1 and 5 and defaults to 3.

string ["DEL_INDEX"]: The case's delegation index, which counts the number of times a case has been routed to the next task, starting from the number 1.

string ["TAS_UID"]: The unique ID of the current task for the case.

string ["DEL_INIT_DATE"]: The datetime when the case's current task initiated in "YYYY-MM-DD HH:MM:SS" format.

string ["DEL_FINISH_DATE"]: The datetime when the case's current task finished in "YYYY-MM-DD HH:MM:SS" format. If it hasn't finished yet, it will be set to NULL.

string ["USR_UID"]: The unique ID of the user designated to work on the case's current task.

string ["APP_STATUS"]: The case's status, which can be: "TO_DO", "DRAFT", "COMPLETED", "CANCELLED", "PAUSED" or "UNASSIGNED".

string ["DEL_TASK_DUE_DATE"]: The datetime when the current task is due (i.e., scheduled to be be finished) "YYYY-MM-DD HH:MM:SS" format.

string ["APP_CURRENT_USER"]: The name of the user designated to work on the case's current task in the format: last_name + " " + first_name

string ["APP_TITLE"]: The title for the case. For example: "#42"

string ["APP_PRO_TITLE"]: The title of the case's process.

string ["APP_TAS_TITLE"]: The title of the case's current task.

string ["APP_DEL_PREVIOUS_USER"]: The name of the user designated to work on the case's previous task in the format: last_name + " " + first_name

)

Example:
Look up the case title, current user and the case variable "ClientName" for the current case and display this information in a message on the next screen:

Cases::loadCaseByNumber()

Cases::loadCaseByNumber() no longer works in ProcessMaker version 3.

Cases::getUsersParticipatedInCase()

Cases::getUsersParticipatedInCase() returns a list of all the users who have participated in a specified case.

array getUsersParticipatedInCase(string $sAppUid)

Parameters:

• string $sAppUid: The unique ID for a case. Set to @@APPLICATION for the current case or look it up in the wf_<WORKSPACE>.APPLICATION.APP_UID field for other cases.

Return Value:
Returns an associative array containing a Criteria object to search for the users, and an array of users who have participated in the case:
array (

object ["criteria"]: A Criteria object that can be used to do a Propel query.

array ["array"]: An associative array of users who have participated in the case. The array keys are the users' unique IDs.

array ["USER1-UNIQUE-ID"]: An associative array of information about the first user.

string ["APP_UID"]: The case's unique ID.

string ["USR_UID"]: The user's unique ID.

string ["USR_USERNAME"]: The user's username.

string ["USR_EMAIL"]: The user's email address.

array ["USER2-UNIQUE-ID"]: An associative array of information about the second user.

...

...

)

Example:
Email all the users who have participated in the current case:

Cases::startCase()

Cases::startCase(), which is defined in workflow/engine/classes/class.case.php, starts a new case.

array Cases::startCase(string $sTasUid, string $sUsrUid, boolean $isSubprocess=false)

Parameters:

• string $sTasUid: The unique ID for the task where the case will start. This task must be one of the starting tasks in the process. This ID can be found by going to ADMIN > Web Services Test and logging in as the user and then using the taskList() web service.
• string $sUsrUid: The unique ID for the user that will be assigned to the starting task of the case. This user must be one of the assigned users for that task.
• boolean $isSubprocess: Optional parameter. Set to true if the case is run as a subprocess of a master process.

Return Value:
An associative array with the following elements:

array ( string ['APPLICATION']: Unique ID for the new case. int ['INDEX']: Positive integer to identify the current task of the new case. string ['PROCESS']: Unique ID for the process of the new case. int ['CASE_NUMBER']: Case number, which is a positive integer which counts cases. )

Example:
Start a new case for the currently logged in user:

Cases::cancelCase()

Cases::cancelCase() cancels a case, so it can never be reopened and worked upon.

void Cases::cancelCase(string $sApplicationUID, int $iIndex, string $user_logged)

Parameters:

• string $sApplicationUID: The unique ID for the case to cancel.
• int $iIndex: The delegation index for the case to cancel. This should be the index for the current task in the case.
• string $user_logged: The unique ID for the user who cancels the case. This should be the user who is currently assigned to work on the case.

Example:
Cancel the current case:

Cases::removeCase()

Cases::removeCase() deletes a case and all its associated Input Documents, Output Documents and uploaded files.

void Cases::removeCase(string $sAppUid)

Parameters:

• string $sAppUid: The unique ID of the case to remove.

Return Value:

Cases::removeCase() doesn't have a return value. If an exception occurs while executing Cases::removeCase(), the trigger will abort at that point and no subsequent code will be executed in the trigger and an exception message will be set in the @@__ERROR__ system variable (which can be checked in a subsequent trigger). For example, if $sAppUid is an invalid case unique ID, @@__ERROR__ will contain the message: "The row 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' in table Application doesn't exist!"

Examples:
Delete the current case and redirect back to the cases list. Then, abort with the die() function, so the case will not continue to the next step (which will no longer exist, since the case has been removed from the database).

ProcessMaker slows down with large numbers of cases in the database. If it is not necessary to keep old cases in the system, this trigger code finds all cases that were completed or canceled over one year ago and deletes them.

Cases::unpauseCase()

Cases::unpauseCase() unpauses a case (which was previously paused), so it can be worked on again.

void Cases::unpauseCase(string $sApplicationUID, int $iIndex, string $user_logged)

Parameters:

• string $sApplicationUID: The unique ID for the case to unpause.
• int $iIndex: The delegation index for the case to unpause. This should be the index for the current task in the case.
• string $user_logged: The unique ID for the user who unpauses the case. This should be the user who is currently assigned to work on the case.

Example:
Unpause the current case:

Cases::reassignCase()

Cases::reassignCase() reassigns the specified case to another user. Note that the new user must either be in the list of assigned users for the task or in its ad-hoc users.

boolean reassignCase(string $sApplicationUID, int $iDelegation, string $sUserUID, string $newUserUID, string $sType = 'REASSIGN')

Parameters:

• string $sApplicationUID: The unique ID for the case. Note that this ID changes with each new task.
• int $iDelegation: The current delegation index (which counts tasks starting from 1) for the case.
• string $sUserUID: The unique ID of the user currently assigned to the task.
• string $newUserUID: The unique ID of the user who will be assigned to the task.
• string $sType: Optional. Set the type, which in almost all cases should be the default 'REASSIGN'.

Return Value:
If the case was successfully reassigned, Cases::reassignCase() returns true. If unsuccessful, an exception is thrown and the trigger code stops at that point. An exception message is placed in the @@__ERROR__ system variable (which can be checked in a subsequent trigger).

Note: If the task is configured to send an automatic notification to the next assigned user, Cases::reassignCase() will NOT send out that notification. Instead, use PMFSendMessage() to manually notify the user. Likewise, it won't execute any triggers associated with task assignment.

Example:
When the current user goes on vacation, reassign all their cases to other users who are randomly chosen from the pool of assigned users for the current task in the case.

Cases::setCatchUser()

Assigns a user to a case whose current task has a self-service assignment rule and it is not yet assigned to a user. Note that only a user who in the list of assigned users for the task can be assigned to the case.

void Cases::setCatchUser(string $sAppUid, int $iDelIndex, string $usrId)

Parameters:

• string $sAppUid: The unique ID for a case whose current task is self-service and is still unassigned to a user.
• int $iDelIndex: The delegation index for the case.
• string $usrId: The unique ID for the user to be assigned to the case.

Example:

If the user who is assigned to the previous task in the process is the "admin" user, then automatically assign him/her to the next task in the process, which is a self-service task. This trigger should be set to execute after routing the task before the self-service task, because at that point, the self-service task has already been created in the APP_DELEGATION table in the database. If setCatchUser() is called before the record for the task has been created in the database, then it will fail.

Cases::getNextStep()

Cases::getNextStep() returns information about the next step in a task. If no parameters are specified, then it will return information about the next task in the current case.

array Cases::getNextStep(string $sProUid = '', string $sAppUid = '', int $iDelIndex = 0, int $iPosition = 0)

Parameters:

• string $sProUid: Optional. The unique ID of the process. If not included, then the current process will be used.
• string $sAppUid: Optional. The unique ID of the case. If not included, then the current case will be used.
• int $iDelIndex: Optional. The delegation index of the case, which is a positive integer counting the tasks in a case starting from 1. If not included, then the current task in the current case will be used.
• int $iPosition: Optional. The step in the case, which is a positive integer counting the steps in a case, starting from 1. If not included, then the current step in the current case will be used.

Return Value:
An associative array with information about the next step in the specified case, with the following structure:

array( ['TYPE'], ['UID'], ['POSITION'], ['PAGE'] )

Where:

• string ['TYPE']: The type of step, which can be 'DYNAFORM', 'OUTPUT_DOCUMENT', 'INPUT_DOCUMENT', 'EXTERNAL' or 'MESSAGE'.
• string ['UID']: The unique ID for the next step.
• int ['POSITION']: The position of the next step, which is a positive integer that counts the steps in a task starting from 1.
• string ['PAGE']: A relative URL that can be used to redirect to the next step with the G::header() function.

If the specified step is the last step in the task, then this array will return the last step index plus 1, assigning the case to the next user:

array( 'TYPE' => 'DERIVATION', 'UID' => -1, 'POSITION' => ($iLastStep + 1), 'PAGE' => 'cases_Step?TYPE=ASSIGN_TASK&UID=-1&POSITION=10000&ACTION=ASSIGN' )

Example:
To redirect the web browser to the next step in the current case:

Note:

is equivalent to:

Cases::getPreviousStep()

Cases::getPreviousStep() returns information about the previous step in a specified case. If no parameters are specified, then it will return information about the previous task in the current case.

array Cases::getPreviousStep(string $sProUid = '', string $sAppUid = '', int $iDelIndex = 0, int $iPosition = 0)

Parameters:

• string $sProUid: Optional. The unique ID of the process. If not included, then the current process will be used.
• string $sAppUid: Optional. The unique ID of the case. If not included, then the current case will be used.
• int $iDelIndex: Optional. The delegation index of the case, which is a positive integer counting the tasks in a case starting from 1. If not included, then the current task in the specified case will be used.
• int $iPosition: Optional. The step in the case, which is a positive integer counting the steps in a case, starting from 1. If not included, then the current step in the specified case will be used.

Return Value:
An associative array with information about the previous step in the specified case, with the following structure:

associative array ( ['TYPE'], ['UID'], ['POSITION'], ['PAGE'] )

Where:

• string ['TYPE']: The type of step, which can be 'DYNAFORM', 'OUTPUT_DOCUMENT', 'INPUT_DOCUMENT', 'EXTERNAL' or 'MESSAGE'.
• string ['UID']: The unique ID for the previous step.
• int ['POSITION']: The position of the previous step, which is a positive integer that counts the steps in a task starting from 1.
• string ['PAGE']: A relative URL that can be used to redirect to the previous step with the G::header() function.

If there is no previous step available, then a value of false will be returned.

Example:
To redirect the web browser to the previous step in the current case:

Note:

is equivalent to:

Cases::updateCase()

Cases::updateCase() overwrites a case's variables by serializing the variables and storing them in the wf_<WORKSPACE>.APPLICATION.APP_DATA field in the database.

array Cases::updateCase(string $sAppUid, array $Fields = array())

Parameters:

• string $sAppUid: The unique ID of the case whose variables will be updated.
• array $Fields: Optional. An associative array that should contain a key named "APP_DATA", which points to an associative array of the variables. In this associative array, the keys are the names of the variables and the array values are the values of the variables. If the $Fields parameter is not included, then the case's variables will be erased. The easiest way to get a correct array structure for the $Fields parameter is to use Cases::loadCase() and then use array_merge() to update its ['APP_DATA'] member array. See the example below.

Return Value:
Returns the $Fields parameter.

Note: If updating the current case in a trigger, keep in mind that many steps automatically update a case's variables, so your changes will be overwritten. For this reason, it is recommended to use PMFSendVariables() instead of Cases::updateCase() to update the current case in a trigger.

Example:
Set the variable "clientAccount" to "2012_FINANCE_Y34" and the variable "clientName" to "Jane Doe" for a case with the unique ID "8078850464f60dda169adc4033523707":

Content class

The text associated with a ProcessMaker object can be looked up using the Content class, which is defined in the file workflow/engine/classes/model/Content.php. The text for ProcessMaker objects is stored in the wf_<WORKSPACE>.CONTENT table in the database.

Content::load()

The Load() method returns the text associated with a specified ProcessMaker object, such as its title, description, comment, etc. In version 2.X, this method can also be used to return the translation for a specified language, but in version 3.X, translations no longer work.

string Content::load(string $ConCategory, string $ConParent, string $ConId, string $ConLang)

Parameters:

• string $conCategory: The category of content, such as 'DYN_TITLE', 'APP_DOC_FILENAME'. For a complete list of categories, see Finding ProcessMaker Objects.
• string $ConParent: For all objects, except the files uploaded to Input and Output Documents, this is set to "" (an empty string). If the $conCategory is "APP_DOC_FILENAME", "APP_DOC_TITLE" or "APP_DOC_COMMENT" then this parameter is set to the version number of the file, so the first version is "1", the second version is "2", etc.
• string $conId: The unique ID of the ProcessMaker object, which consists of 32 hexadecimal characters, such as "69738725456a802d97e2eb7008185603".
• string $conLangRecipients: Set to the ISO code of the language, such as "en" (English), "es" (Spanish), "fr-FR" (French from France), "pt-BR" (Portuguese from Brazil) or "zh-CN" (Chinese from Mainland China). For a list of the available languages see Translations. If set to "" (an empty string), then it will return the first record found in the CONTENT table regardless of the language. If a record doesn't exist in the CONTENT table for the specified language, then a new record will automatically be added to the CONTENT table for the language. Its content is copied from another record with the same UID, and its text will be returned.
  Note: In version 3.X, there are no translations, so set it to "".

Return Value:
Returns the text for the specified unique ID (which is stored in the CONTENT.CON_VALUE field in the database). If the UID can't be found, then an empty string is returned.

Example:
Get the title for a Dynaform with the UID "12816611256a0006a028ab7006995270" in English and its Spanish translation:

Dates class

The Dates class is defined in processmaker/workflow/engine/classes/class.dates.php. and is used to manipulate the definition of dates.

dates::calculateDate()

dates::calculateDate() is used to calculate the due date for a task (or any projected datetime), based on the configured calendar or work days. If $iTypeDay is set to 1. The calendar is selected first based on the user. If there is no selected calendar for the user, then use the selected calendar for the task. If no calendar is selected for the task, then use the selected calendar for the process. If not calendar is selected for the process, then use the default calendar for the workspace.

array calculateDate(string $sInitDate, integer $iDuration, string $sTimeUnit, integer $iTypeDay, string $UsrUid = null, string $ProUid = null, string $TasUid = null)

Parameters:

• string $sInitDate: Start Date in "YYYY-MM-DD HH:MM:SS" format.
• integer $iDuration: Integer which represents number of time units.
• string $sTimeUnit: Type units in 'DAYS' or 'HOURS'.
• integer $iTypeDay: Set to 1 if calculating work days (Monday-Friday) or 2 for calendar days.
• string $UsrUid: Set to the unique ID of the user. If not included or set to null, then don't search for a calendar set for a particular user.
• string $ProUid: Set to the unique ID of the process. If not included or set to null, then don't search for a calendar set for a particular process.
• string $TasUid: Set to the unique ID of the task. If not included or set to null, then don't search for the calendar set for a particular task.

Return Value:
An associative array with the following elements:
array (

string ["DUE_DATE"]: End date in "YYYY-MM-DD HH:MM:SS" format.

string ["DUE_DATE_SECONDS"]: Timestamp in seconds for end date.

string ["DUE_DATE_LOG"]: Log to select calendar and calculate date.

)

Example:

Calculate the due date for a task depending on its type. The @@typeTask variable must be set in a previous Dynaform and the trigger set to fire either in the task whose due date needs to be set or after routing in the previous task, because at that point, records for the case's task have already been created in the APP_DELEGATION and APP_CACHE_VIEW tables in the database.

Derivation class

Class to manipulate the routing (derivation) of cases to the next task(s) in the process and is defined in workflow/engine/classes/class.derivation.php.

Derivation::getAllUsersFromAnyTask()

Derivation::getAllUsersFromAnyTask() returns an array of unique IDs for the users assigned to a task.

array Derivation::getAllUsersFromAnyTask(string $sTasUid, $flagIncludeAdHocUsers=false);

Parameters:

• string $sTasUid: The unique ID for a task.
• boolean $flagIncludeAdHocUsers: Set to true to include users which are assigned Ad Hoc to the task. Default is false.

Return Value:
An array of unique IDs for users assigned to the task, ordered by the UIDs. Note that the function will also return users who are assigned to the task through groups. Duplicate UIDs will be eliminated.

Example:
If the case variable @@cantHandleCase is true, send an email to all the other users assigned to the current task, asking them to take the case because the currently designated user can't handle it.

Derivation::getDerivatedCases()

Derivation::getDerivatedCases() returns information about any subprocess cases that were created after a specified delegation index in a specified case. This function is used to find out which subprocess cases were created by a master case.

array Derivation::getDerivatedCases(string $sParentUid, int $sDelIndexParent)

Parameters:

• string $sParentUid: The unique ID for the parent (master) case.
• int $sDelIndexParent: The delegation index for the parent (master) case.

Return Value:
An array of associative arrays that contains information about the subprocess case(s) created after a specified delegation index in a master case. If no subprocess cases were created, then returns an empty array.
array (

[0]: array (

string ["processId"]: The unique ID of the subprocess.

string ["processTitle"]: The title of the subprocess

string ["caseId"]: The unique ID of the subprocess case.

int ["caseNumber"]: The case number of the subprocess case.

string ["taskId"]: The unique ID of the initial task in the subprocess case.

string ["taskTitle"]: The title of the initial task in the subprocess case.

string ["userId"]: The unique ID of the user designated to the initial task in the subprocess case.

string ["userName"]: The username of the user designated to the initial task in the subprocess case.

string ["userFullname"]: The first and last name (separated by a space) of the user designated to the initial task in the subprocess case.

)

[1]

...

)

Example:
Send an email to the current user of a master case about a subprocess case that was created after the second task in the process.

Derivation::setTasLastAssigned()

Derivation::setTasLastAssigned() sets the user who was last designated to work on a task, so tasks that use cyclical assignment will select the next user in the list returned by Derivation::getAllUsersFromAnyTask(). This function writes the user's unique ID to the wf_<wORKSPACE>.TASK.TAS_LAST_ASSIGNED field in the database.

void Derivation::setTasLastAssigned(string $tasUid, string $usrUid)

Parameters:

• string $tasUid: The unique ID for the task.
• int $usrUid: The unique ID for the user who will be set as the last user for the task.

Return Value:
None.

Example:
The next task in the process uses cyclical assignment, but in some special cases the user working on the current task should also be designated to work on the next task as well, so normal cyclical assignment shouldn't occur. To force the current user to be assigned to the next task, first use Derivation::getAllUsersFromAnyTask() to get a list of the users and find where the current user is in the list. Then, set the user before the current user in the list as the last one to work on the task with Derivation::setTasLastAssigned(). That way PMFDerivateCase() will assign the current user as the next user when it routes the case.

Department class

The Department class is defined in workflow/engine/classes/model/Department.php and is used to manipulate departments in ProcessMaker, which are stored in the wf_<WORKSPACE>.DEPARTMENT table in the database.

Department::Load()

Department::Load() returns information about a department.

array Department::Load(string uid)

Parameters:

• string uid: The unique ID of a department, which can be found in the following ways:
  • Use the departmentList() web service.
  • Query the wf_<WORKSPACE>.DEPARTMENT.DEP_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='DEPO_TITLE'

Return Value:
An associative array with the following elements:
array (

string ["DEP_UID"]: The unique ID of the department.

string ["DEP_PARENT"]: The unique ID of the parent department. If no parent, then set to "" (an empty string).

string ["DEP_MANAGER"]: The unique ID of the user who is the manager/supervisor of the department.

int ["DEP_LOCATION"]: Always set to 0.

string ["DEP_STATUS"]: The department's status, which can be "ACTIVE" or "INACTIVE". If "INACTIVE", then no additional users can be assigned to the department and "reports to" designation rules don't work with the department.

string ["DEP_REF_CODE"]: Generally set to "" (empty string).

string ["DEP_LDAP_DN"]: The distinguished name of the department, if the department was imported from an external authentication source, which is an option with the AdvancedLDAP plugin.

string ["DEPO_TITLE"]: The title of the department.

)

Example:

Department::getDepartmentsForUser()

Department::getDepartmentsForUser(string $userUid)

Department::getAllDepartmentsByUser()

getAllDepartmentsByUser()

Department::removeUserFromDepartment()

removeUserFromDepartment(string $DepUid, string $UsrUid)

Department::addUserToDepartment()

Department::addUserToDepartment() adds a user to a department, with an option to sync all about manager info

addUserToDepartment(string $depId, string $userId, string $manager, boolean $updateManager = false)

Department::updateDepartmentManager()

updateDepartmentManager()

Dynaform class

The Dynaform class is defined in workflow/engine/classes/model/Dynaform.php and is used to manipulate Dynaforms in ProcessMaker, which are stored in the wf_<WORKSPACE>.DYNAFORM table in the database.

Dynaform::Load()

Dynaform::Load() returns information about a task.

array Dynaform::Load(string uid)

Parameters:

• string uid: The unique ID of a Dynaform, which can be found in the following ways:
  • Query the wf_<WORKSPACE>.DYNAFORM.DYN_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='DYN_TITLE'

Return Value:
An associative array with the following elements:
array(

string ["DYN_UID"]: The unique ID of the Dynaform.

string ["PRO_UID"]: The unique ID of the process that contains the Dynaform.

string ["DYN_TYPE"]: The Dynaform type, which is "grid" or "xmlform" (for a master form).

string ["DYN_FILENAME"]: The filename (without the extension) where the XML code and HTML code is stored in the file system. The filename consists of the process UID and Dynaform UID separted by a "/" (forward slash). For example: "7766592404f358fb90dcdc9043579725/6876293754f358fcb61d704036851199"

string ["DYN_TITLE"]: The title of the Dynaform

string ["DYN_DESCRIPTION"]: The description of the Dynaform.

)

Example:

Event class

The Event class is defined in workflow/engine/classes/model/Event.php and is used to manipulate event definitions in ProcessMaker, which are stored in the wf_<WORKSPACE>.EVENT table in the database.

Event::Load()

array(

string ["EVN_UID"]: The unique ID of the event.

string ["PRO_UID"]: The unique ID of the process.

string ["EVN_STATUS"]: The event's status, which can be "ACTIVE" or "INACTIVE".

string ["EVN_WHEN_OCCURS"]: When the event is timed to occur, which can be "SINGLE", "AFTER_TIME", or "TASK_STARTED".

string ["EVN_RELATED_TO"]: Set to "SINGLE" if the event timing is based on a single task or "MULTIPLE" if based on multiple tasks.

string ["TAS_UID"]: If EVN_RELATED_TO is "SINGLE", then TAS_UID is the unique ID of the task where the event timing starts.

string ["EVN_TAS_UID_FROM"]: If EVN_RELATED_TO is "MULTIPLE", then EVN_TAS_UID_FROM is the unique ID of the task where the event timing starts.

string ["EVN_TAS_UID_TO"]: If EVN_RELATED_TO is "MULTIPLE", then EVN_TAS_UID_TO is the unique ID of the task where the event timing stops.

float ["EVN_TAS_ESTIMATED_DURATION"]: The estimated duration of the task in days.

float ["EVN_WHEN"]: The time in days when the event will fire.

int ["EVN_MAX_ATTEMPTS"]: The number of maximum attempts permitted to fire the event. This is 3 by default.

string ["EVN_ACTION"]: The event action, which can be "SEND_MESSAGE"or "EXECUTE_CONDITIONAL_TRIGGER".

string ["EVN_CONDITIONS"]: The text of a condition. The event will only fire if it evaluates to true.

string ["EVN_ACTION_PARAMETERS"]: Additional information. If a message event, it will contain a stdClass object to define the message:

object stdClass {

string ["hash"]: An MD5 hash of the text in the message's template.

string ["SUBJECT"]: The subject line of the message.

array ["TO"]: (

string [0]: First recipient. Ex: "usr|-1"

...

)

array ["CC"]: (

string [0]: First recipient. Ex: "usr|-1"

...

)

array ["BCC"]: (

string [0]: First recipient. Ex: "usr|-1"

...

)

string ["TEMPLATE"]: The filename of the template, which should be located in the Process Files Manager's public directory.

}

string ["TRI_UID"]: Unique ID of trigger fired by the event.

string ["EVN_POSX"]: The X position of the event, which is always set to 0.

string ["EVN_POSY"]: The Y position of the event, which is always set to 0.

string ["EVN_TYPE"]: The event type.

string ["TAS_EVN_UID"]: The unique ID of the task.

string ["EVN_DESCRIPTION"]: Event description.

)

Example:

Groups class

The Groups class is defined in workflow/engine/classes/class.groups.php and is used to manipulate groups in ProcessMaker.

Groups::getUsersOfGroup()

Get the assigned users of a group.

array Groups::getUsersOfGroup(string $sGroupUID)

Parameters:

• string $sGroupUID: The unique ID of a group, which can be found in the following ways:
  • Use the PMFGroupList() or WSGroupList() functions or the groupList() web service.
  • Query the wf_<WORKSPACE>.GROUPWF.GRP_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='GRP_TITLE'

Return Value:
An array of associative arrays with information about each user in the group:
array(

int [0]: array(

string ["USR_UID"]: The user's unique ID.

string ["USR_USERNAME"]: The user's username, which must be unique and is case insensitive.

string ["USR_PASSWORD"]: An MD5 hash of the user's password,

string ["USR_FIRSTNAME"]: The user's first name. Up to 50 characters long.

string ["USR_LASTNAME"]: The user's last name. Up to 50 characters long.

string ["USR_EMAIL"]: The user's email address. Up to 100 characters long.

string ["USR_DUE_DATE"]: The date when the user's account is set to expire in the "YYYY-MM-DD HH:MM:SS" format.

string ["USR_CREATE_DATE"]: The datetime when the user's profile was first created in the "YYYY-MM-DD HH:MM:SS" format.

string ["USR_UPDATE_DATE"]: The datetime when the user's profile was last updated in the "YYYY-MM-DD HH:MM:SS" format.

string ["USR_STATUS"]: The user's status, which can be: "ACTIVE", "INACTIVE" or "ON_VACATION". Only users with "ACTIVE" status can login to the system.

string ["USR_COUNTRY"]: A 2 character code to identify the user's country. To find the full name of the country, do a search in the wf_<WORKSPACE>.ISO_COUNTRY table.

string ["USR_CITY"]: This element (which is misnamed), is a 1-3 character code for the region or state. To find the full name of the region or state, do a search in the wf_<WORKSPACE>.ISO_SUBDIVISION table.

string ["USR_LOCATION"]: A 3 character code for the location (which is generally a city or county). To find the full name of the location, do a search in the wf_<WORKSPACE>.ISO_LOCATION table.

string ["USR_ADDRESS"]: The address. Up to 255 characters long.

string ["USR_PHONE"]: The telephone number. Up to 24 characters long.

string ["USR_FAX"]: The fax number. Up to 24 characters long.

string ["USR_CELLULAR"]: The cellular telephone number. Up to 24 characters long.

string ["USR_ZIP_CODE"]: The postal code or zip code. Up to 16 characters long.

string ["DEP_UID"]: The unique ID for the user's department.

string ["USR_POSITION"]: The user's position. Up to 100 characters long.

string ["USR_RESUME"]: No longer used in version 3. In ProcessMaker 2, some versions allow uploading a resume file, of which the first 100 characters are displayed.

string ["USR_BIRTHDAY"]: The date of the user's birthday in the "YYYY-MM-DD" format.

string ["USR_ROLE"]: The name of the role.

string ["USR_REPORTS_TO"]: The unique ID for the user who the user reports to, i.e., the user's department manager.

string ["USR_REPLACED_BY"]: The unique ID for the user who replaces this user when going on vacation or leave.

string ["USR_UX"]: The User Experience interface for the user, which can be: "NORMAL", "SIMPLIFIED" or "SWITCHABLE". The simplified interface is designed for smartphones and mobile devices, which use less screen space and use finger touches and no right clicks.

)

int [1]: array (

...

)

...

)

Example:
Send an email to all members of a group.

Groups::getActiveGroupsForAnUser()

Groups::getActiveGroupsForAnUser() returns a list of the groups to which a specified user is assigned. It only returns groups that have an active status.

array Groups::getActiveGroupsForAnUser(string $sUserUID)

Parameters:

• string $sUserUID: The unique ID of a user.

Return Value:
An array of group unique IDs.

Example:
Display a list of groups for the current user in a Dynaform grid named "groupsGrid", which contains the fields "uid" and "groupName".

Groups::getGroupsForUser()

Groups::getGroupsForUser() returns a list of groups to which a specified user is assigned. It is like Groups::getActiveGroupsForAnUser(), but it returns an associative array of information about the group. Note that is only returns groups that have an active status.

array Groups::getActiveGroupsForAnUser(string $usrUid)

Parameters:

• string $usrUid: The unique ID of a user.

Return Value:
An associative array of associative arrays with information about the groups. The outer associative array has keys which group unique IDs.
array (

string ["GROUP-UID-1"]: The unique ID of the first group.

array (

string ["GRP_UID"]: The group's unique ID.

string ["GRP_STATUS"]: The group's status, which can only be "ACTIVE", since searching for "ACTIVE" groups.

string ["CON_VALUE"]: The group's title, which is looked up in the wf_<WORKSPACE>.CONTENT.CON_VALUE table.

)

string ["GROUP-UID-2"]: The unique ID of the second group.

...

)

Example:
Display a list of groups for the current user in a Dynaform grid named "groupsGrid", which contains the fields "uid" and "groupName".

Groups::verifyUserToGroup()

Groups::verifyUsertoGroup() verifies whether a specified user is a member of a specified group.

int Groups::verifyUsertoGroup(string $GrpUid, string $UsrUid)

Parameters:

• string $GrpUid: The unique ID of a group.
• string $UsrUID: The unique ID of a user.

Return Value:
Returns 1 if the user is a member of the group. Otherwise returns 0.

Note: This method does not check whether the group and user have active status, so there is no guarantee that the user or group can be used after the user is added to it.

Example:
If the current user is a member of a group named "Employees", then set @@canHandleTask to "yes", which is a variable used in a subsequent condition in an evaluation routing rule. Look up the unique ID for the "Employees" group in the wf_<WORKSPACE>.CONTENT table.

Groups::addUserToGroup()

Groups::addUserToGroup() adds a user to a group.

void Groups::addUserToGroup(string $GrpUid, string $UsrUid)

Parameters:

• string $GrpUid: The unique ID of a group.
• string $sUserUID: The unique ID of the user who will be added to the group.

Return Value:
None.

Note: This method does not check whether the group and user have active status, so there is no guarantee that the user or group can be used after the user is added to it.

Example:
Add the current user to a group named "Employees"; the group's unique ID can be looked up in the wf_<WORKSPACE>.CONTENT table.

Groups::removeUserOfGroup()

Groups::removeUserOfGroup() deletes a specified user from a specified group.

void Groups::removeUserOfAllGroups(string $GrpUid, string $UsrUid)

Parameters:

• string $GrpUid: The unique ID of a group.
• string $UsrUid: The unique ID of the user who will be removed from the group.

Return Value:
None.

Example:
Remove the current user to a group named "Employees"; the group's unique ID can be looked up in the wf_<WORKSPACE>.CONTENT table.

Groups::removeUserOfAllGroups()

Groups::removeUserOfAllGroups() deletes a specified user from all groups.

void Groups::removeUserOfAllGroups(string $sUserUID = )

Parameters:

• string $sUserUID: The unique ID of the user who will be removed from all groups.

Return Value:
None.

Example:
Remove the current user from all the groups that the user is assigned to.

Groupwf class

The Groupwf class is defined in workflow/engine/classes/model/Groupwf.php and is used to manipulate groups in ProcessMaker, which are stored in the wf_<WORKSPACE>.GROUPWF table in the database.

Groupwf::Load()

Groupwf::Load() returns information about a group.

array Groupwf::Load(string $GrpUid)

Parameters:

• string GrpUid: The unique ID of a group, which can be found in the following ways:
  • Use the PMFGroupList() or WSGroupList() functions or the groupList() web service.
  • Query the wf_<WORKSPACE>.GROUPWF.GRP_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='GRP_TITLE'

Return Value:
An associative array with the following elements:
array (

string ["GRP_UID"]: The unique ID of the group.

string ["GRP_STATUS"]: The group's status, which can be "ACTIVE" or "INACTIVE". If "INACTIVE", then no additional users can be assigned to the group and designation rules don't work with the group.

string ["GRP_LDAP_DN"]: The distinguished name of the group, if the group was imported from an external authentication source, which is an option with the AdvancedLDAP plugin.

string ["GRP_UX"]: The User Experience interface for the group, which can be: "NORMAL", "SIMPLIFIED" or "SWITCHABLE". The simplified interface is designed for smartphones and mobile devices, which use less screen space and use finger touches and no right clicks.

string ["GRP_TITLE"]: The group's title.

)

Example:

Gulliver Functions

Functions and objects defined in Gulliver (the PHP development framework used internally by ProcessMaker) can be called from within triggers by prepending G:: to the function or class name. Most of Gulliver's functions are defined in the file gulliver/system/class.g.php.

G::LoadClass()

G::LoadClass() includes (i.e., imports into the code using the require_once() function) a class definition file that is stored in the location workflow/engine/classes/class.CLASS-NAME.php. The code file will only be included if it hasn't already been included.

variant G::LoadClass(string $strClass)

Parameters:

• string $strClass: The CLASS-NAME of the code file found at workflow/engine/classes/class.CLASS-NAME.php. Note that the CLASS-NAME is case sensitive and almost always starts in lowercase.

Return Value:
If able to find or open the file, then it returns false. If the code file was successfully included and it doesn't have a return statement, then it returns 1. Otherwise, it returns the value of the return statement.

Example:
Import the workflow/engine/classes/class.groups.php code file. Then instantiate the Groups class found in that code file and call its Groups::getUsersOfGroup() method:

G::LoadSystem()

G::LoadSystem() includes (i.e., imports into the code using the require_once() function) a Gulliver class definition file that is stored in the location gulliver/system/class.CLASS-NAME.php. The code file will only be included if it hasn't already been included.

variant G::LoadSystem(string $strClass)

Parameters:

• string $strClass: The CLASS-NAME of the code file found at gulliver/system/class.CLASS-NAME.php. Note that the CLASS-NAME is case sensitive and almost always starts in lowercase.

Return Value:
If able to find or open the file, then it returns false. If the code file was successfully included and it doesn't have a return statement, then it returns 1. Otherwise, it returns the value of the return statement.

Example:
Include the file /gulliver/system/class.xmlform.php:

G::header()

G::header() is a wrapper for PHP's header() function, which sends raw HTTP headers. It can be used to redirect the browser to a different web page in ProcessMaker. Note that the G::header() function redirects to the current frame. To redirect to the top frame, see Browser Redirection. If redirecting to a case or an element in a case such as Input Document, remember that the current logged-in user must have the proper permissions to access the case and its elements. A user can obtain write-access to a case and/or its elements if designated to work on a current task in the case or if a Process Supervisor. A user can obtain read-access if given Process Permissions. void G::header(string $string)

Parameters:

• string string: The header string. To do redirection to a different web page, use the string "Location: <URL>". The URL can be a complete address such as "http://www.processmaker.com" or a relative address such as:

"Location: ../cases/cases_List"

Opens the case list for the user currently logged-in.

"Location: ../cases/casesListExtJs"

Opens the case list using the new ExtJS interface (available in ProcessMaker v.2.0) for the currently logged-in user.

"Location: ../cases/casesListExtJsRedirector"

Opens the case list using the new ExtJS interface in the parent frame of ProcessMaker v.2.0.

"Location: ../cases/cases_New"

Opens the screen to select the process in which to start a new case.

"Location: ../cases/cases_Open?APP_UID=<CASE-UID>&DEL_INDEX=<INDEX>"

Opens a case in the task specified by the delegation index, as long as the current logged-in user has the proper privileges to open that case. The case is opened without the top-level menu bar or the cases sidebar, so the user is only able to see the specified case. Remember that a user must either be the user currently designated to work on the case or have Process Permissions for read-only access to the case. (For write access, make the user a Process Supervisor.) The APP_UID is the case unique ID and the DEL_INDEX is the delegation index, which is an positive integer counting the tasks in a process, starting from 1. Use the @@APPLICATION and @%INDEX system variables to get the case UID and delegation index for the current case. For other cases, these values can be looked up using the PMFCaseList() function, the caseList() web service or querying the wf_<WORKSPACE>.APP_DELEGATION.APP_UID and wf_<WORKSPACE>.APP_DELEGATION.DEL_INDEX fields in the database.

"Location: ../cases/cases_Open?APP_UID=<CASE-UID>&DEL_INDEX=<INDEX>&action=<ACTION>"

Just like the previous URL, this URL opens a case, but the URL includes the optional action GET variable. If action=sent, then it only displays a summary about the case. If action=search, then it searches for the case. If action=draft, then the case is opened to be worked on.

"Location: ../cases/opencase/<CASE-UID>"

Available in version 3.0.1.8 and later. Like the previous URL, this URL open an existing case, but it includes the top-level menu and cases sidebar. This URL does not allow the delegation index to be specified, so it opens the last open task or the case summary if the case is completed or cancelled.

"Location: ../designer?prj_uid=<PROCESS-UID>&prj_readonly=true&app_uid=<CASE-UID>"

Add link to the process map.

After calling G::header() to redirect to a different web page, it is a good idea to call the die() function to terminate the trigger and prevent the next step in the task from being executed.

Examples:
To redirect to the case list for the user currently logged-in:

To redirect back to the first task in the current case:

This example opens the overdue case assigned to the logged-in user in the current process. If there are no overdue cases, then redirect back to the cases list:

G::SendMessageText()

G::SendMessageText() displays a message to the user on the next screen. The message will flash twice and then stay on the screen until the user continues onto the next screen. It will be displayed at the top of the frame in a color that depends on the type of message.

void G::SendMessageText(string $message, string $messageType)

Parameters:

• string $message: The text to display to the user. The text can contain HTML markup, such as <font color="green">...</font> and <br> (line break).
• string $messageType: The type of message, which can be "ERROR", "INFO" or "WARNING". Any other value will be displayed as a warning. The words "ERROR: ", "Info: " or "WARNING: " will be prepended to the message text.
  • Error messages will be white text on a red background. Their style is determined by temporalMessageERROR in style.css.
  • Warnings messages will be black text on a yellow background. Their style is determined by temporalMessageWARNING in style.css.
  • Information messages will be black text on a grey background. Their style is determined by temporalMessageINFO in style.css.

Return Value:
None.

Note 1: Only one message can be displayed per frame, so don't try calling this function multiple times before a page is displayed.

Note 2: If the next screen gets completely overwritten, then the message may not be displayed to the user. This may happen if calling G::SendMessageText() in a Trigger after a step. To be absolutely sure that the user will see a message, use PHP print statements followed by die() to stop ProcessMaker.

Example:

G::SendTemporalMessage()

G::SendTemporalMessage() displays a message to the user on the next screen. This method is similar to G::SendMessageText(), but offers more options.

void SendTemporalMessage(string $msgID, string $strType, string $sType='LABEL', int $time=null, variant $width=null, array $customLabels=null)

Parameters:

• string $msgID: The content of the message. Either a custom string to display to the user (if $sType is set to "STRING") or the message ID (if $sType is set to "LABEL" or "LABELS"). If a message ID that will be displayed in the current system language (if a translation is available). To see all the available message IDs, go to ADMIN > Settings > Language, select a language in the list and click on Export. Then open the PO translation file with a bare text editor. For more information, see Translating ProcessMaker and Customizing Interface Strings. If a custom string, then it can contain HTML markup, such as <font color="green">...</font> and <br> (line break). Note that all new lines ("\n") will automatically be replaced by HTML line breaks (<br>).
• string $strType: The type of message, which is case insensitive and can be one of the following options:
  • "ERROR": Prepends the word "ERROR: " to the message and appears as white text on a red background. Its style is determined by temporalMessageERROR in style.css.
  • "TMP-ERROR": The same as "ERROR", but the message disappears from the screen after a certain amount of time.
  • "WARNING": Prepends the word "WARNING: " to the message and appears as black text on a yellow background. Its style is determined by temporalMessageWARNING in style.css.
  • "TMP-WARNING": The same as "WARNING", but the message disappears from the screen after a certain amount of time.
  • "INFO": Prepends the word "Info: " to the message and appears as black text on a grey background. Its style is determined by temporalMessageINFO in style.css.
  • "TMP-INFO": The same as "TMP-INFO", but the message disappears from the screen after a certain amount of time.

Any other value will prepend the word "Info: " to the message, but will display with the temporalMessageWARNING style. To customize how messages are handled, edit the files workflow/engine/templates/publish.php and workflow/engine/templates/publishBlank.php.

• string $sType: Set to "LABEL" or "LABELS" if the first parameter is a message ID which will be displayed in the current system language. Set to "STRING" if the first parameter is a custom string. This parameter is case insensitive and defaults to "LABEL" if not included.
• int $time: The amount of time in seconds that the message will be displayed to the user if $strType is set to "TMP-ERROR", "TMP-WARNING" or "TMP-INFO". If set to NULL or "" (empty string), then the message will be displayed for the default 5 seconds.
• variant $width: The width of the message box as a percentage of the frame width. Can either be an integer such as 70 or a string such as "70%". If not included or set to NULL, then set to 65% of the frame by default.
• array $customLabels: An associative array of custom labels to insert into the message. If the array key appears in the message as "{array-key}", then it will be replaced by the value for that key. See the example below.

Return Value:
None.

Note 1: Only one message can be displayed per frame, so don't try calling this function multiple times before a page is displayed.

Note 2: If the next screen gets completely overwritten, then the message may not be displayed to the user. This may happen if calling G::SendMessageText() in a Trigger after a step. To be absolutely sure that the user will see a message, use PHP print statements followed by die() to stop ProcessMaker.

Example:

• Display an information message in a trigger fired before a Dynaform step:

• Display a custom error message for 3 seconds with the width set to "100%". Insert the variables in the custom message using the $customLabels parameter:

G::LoadTranslation()

Returns the translation for a message ID in the specified language, which is useful if designing triggers that can work in multi-lingual processes. See Customizing Interface Strings.

string G::LoadTranslation(string $msgID, string $lang = SYS_LANG, array $data = null)

Parameters:

• string $msgID: A message ID to look up it's translation. Message IDs and their translations are stored in the wf_<WORKSPACE>.TRANSLATION database.

To see all the messages used by ProcessMaker, in the web browser go to:

http://<IP-ADDRESS:PORT>/sys<WORKSPACE>/en/<SKIN>/tools/updateTranslation

For example:

http://192.168.1.100/sysworkflow/en/classic/tools/updateTranslation

• string $lang: Optional. Specify the language code for the translation, such as "en" (English), "es" (Spanish) or "zh-TW" (Chinese from Taiwan). If not specified, it will be the current ProcessMaker language (which can be found in the @@SYS_LANG system variable).
• array$data: Optional. If the message contains text in the form "... {LABEL-ID} ...", then an associative array of keys and values can be used to replace the "{LABEL-ID}".

Return Value:
A string translated into the specified language.

Example:

G::generateUniqueID()

G::generateUniqueID() returns a hexadecimal string that is 32 characters long to uniquely identify objects such as cases, input documents, output documents, etc., in ProcessMaker. If manually creating new objects in ProcessMaker, use this function to generate the unique ID for that object.

string G::generateUniqueID(void)

Parameters:
None.

Return Value:
A hexadecimal string 32 characters long.

Example:

G::RenderPage()

G::RenderPage() sets the values of the global variables $G_TEMPLATE, $G_SKIN and $G_CONTENT, so that the content of a web page can be rendered and displayed to the user.

void G::RenderPage(string $strTemplate = "default", string $strSkin = SYS_SKIN, object $objContent = NULL)

Parameters:

• string $strTemplate: Optional. The name of the template file to use, which is defined in the workflow/engine/templates/ directory. Available ProcessMaker templates include:
  • "publish": Blank page with a header.
  • "publish-raw": Blank page which doesn't load any Javascript libraries and has no header.
  • "publishBlank": Blank page which does load the JavaScript libraries, but it doesn't have a header.
  • "publish-treeview": Page with a small sidebar and a larger content area (created with HTML DIVs).
  • "publish-twocolumns": Page with two content areas of the same size (created with HTML DIVs).
• string $strSkin: Optional. The name of the skin that replaces the existing skin when rendering the page. If this parameter is not included, then the current skin will be used by default. If specifying this parameter, either use a custom skin or one of the following skins included in ProcessMaker:
  • "classic": Default skin in ProcessMaker 2.X.
  • "green": Default skin in ProcessMaker 1.X.
  • "blank": Skin that does not include a header at the top of the screen (which is useful for conserving space).
  • "raw": Skin that doesn't load any of ProcessMaker's JavaScript libraries. This skin will prevent cases from running correctly since cases need the JavaScript libraries.
  • "extJs": Skin for displaying Ext JS content in ProcessMaker 2.X.
  • "green-submenu": Skin for displaying the content of a submenu in ProcessMaker 1.X.
• object $objContent: This parameter is almost never used. It is recommended to use the Publisher::AddContent() method to set the content of the page.

Return Value:
None.

Example:

G::getPathFromUID()

Available in version 2.5.1 and later.
G::getPathFromUID() checks whether the ProcessMaker server is using the option to store files for cases in a series of 3 subdirectories generated from the case's ID and returns the correct path from a given case ID to access the files. By default, ProcessMaker stores the uploaded files for a case in the following path:
    {INSTALL-DIRECTORY}/shared/sites/{WORKSPACE}/files/{CASE-ID}/{CASE-DOC-ID}_{VERSION-NO}.{FILE-EXTENSION}
For example:
    /opt/processmaker/shared/sites/workflow/files/42316826755cbb5e0751cd5037067960/69609740455cbbde4ef5d70008261343_1.png
To get around the limitation in Linux's ext3 file system, which limits directories to a maximum of 32K files, ProcessMaker 2.5.1 and later has an option to break the case ID into 3 subdirectories, such as:
    /opt/processmaker/shared/sites/workflow/files/423/168/267/55cbb5e0751cd5037067960/69609740455cbbde4ef5d70008261343_1.png
The G::getPathFromUID() method can be used to transform the case ID from "42316826755cbb5e0751cd5037067960" to "423/168/267/55cbb5e0751cd5037067960" if the system requires it.

string G::getPathFromUID(string $url, int $splitSize = 3, int $pieces = 3)

Parameters:

• string $url: A unique ID, which will be broken into 3 subdirectories if the 32K workaround option is activated
• int $splitSize: Optional. The number of characters in the name of each subdirectory. It is strongly recommended to always use the default 3.
• int $pieces: Optional. The number of subdirectories to be created from the unique ID. It is strongly recommended to always use the default 3.

Return Value:
The path created from the unique ID.

Example:

Get the path to access an uploaded text file for the current case and search for "Client No: XXXXXXXX" in the file to extract the client's number and assign it to a case variable:

headPublisher class

The headPublisher class is used by the Gulliver framework to display web pages. It is defined at gulliver/system/class.headPublisher.php. It is similar to the Publisher class, but it has more member functions and has been updated to deal with Ext JS. If working with Ext JS, it is recommended to use this class instead of the Publisher class.

headPublisher::AddContent()

The headPublisher::AddContent() method adds Ext JS content to a page, but it only adds an HTML template file to the private extJsContent[] array, which is a list of Ext JS files which will later be rendered when G::RenderPage() is called.

void headPublisher::AddContent(string $templateHtml)

Parameters:

• string $templateHtml: The filename of the HTML template file to add to the forthcoming page that will be rendered. If the file has the extension ".html", then the extension does not need to be included. The HTML file should be located in the workflow/engine/templates/ or the workflow/engine/plugins/ directory. For example, the file workflow/engine/templates/groups/groupsList.html would be "groups/groupsList" and the file workflow/engine/plugins/deleteCases/deleteCasesApplication1.html would be "deleteCases/deleteCasesApplication1".

Return value:
None.

headPublisher::renderExtJs()

The headPublisher::renderExtJs() method renders all the Ext JS HTML template files that have been added to the extJsContent[] array, so they can later be displayed in the web browser with G::RenderPage(). These files should have an extension of ".html". See headPublisher::AddContent().

string headPublisher::RenderExtJs()

Parameters:
None.

Return value:
The body of the HTML page, which has been created from the files in the the extJsContent[] array.

headPublisher::addExtJsScript()

The headPublisher::addExtJsScript() method adds a Ext JS code file, so it will be executed when the forthcoming page is rendered. The file must have an extension of ".js" and will be added to the extJsScript[] array, which is a list of Ext JS code files that will later be executed when the next page is rendered.

void headPublisher::addExtJsScript(string $filename, boolean $debug = false, boolean $isExternal = false)

Parameters:

• string $filename: The filename of the Ext JS code file to add to the forthcoming page that will be rendered. The file must have an extension of ".js", but do not include that extension in the filename. If the $isExternal parameter is set to false (which the default), then the Ext JS file should be found in the workflow/engine/templates/ or workflow/engine/plugins/ directories. For example, the file workflow/engine/templates/groups/groupsList.js would be "groups/groupsList" and the file workflow/engine/plugins/deleteCases/deleteCasesApplication1.js file would be "deleteCases/deleteCasesApplication1".
• boolean $debug: Set to true to display debug messages.
• boolean $isExternal: Set to true if the file is not found in the standard locations of workflow/engine/templates/ or workflow/engine/plugins/. Make sure to include the full path to the Ext JS file in the $filename.

Return value:
None.

headPublisher::Assign()

The headPublisher::Assign() method is used to pass a string variable from a PHP file to JavaScript. This variable will be added to the extVariable[] array. This method is often used to pass field labels and values to an Ext JS form.

void headPublisher::Assign(string $variable, string $value)

Parameters:

• string $variable: The name of the variable to pass to JavaScript.
• string $value: The value of the variable to pass to JavaScript. Note that this value should be a string.

Return value:
None.

headPublisher::AssignVar()

The headPublisher::Assign() method is used to pass a string variable from a PHP file to JavaScript. This variable will be added to the vars[] array. This method is often used to pass field labels and values to a form. Unlike the headPublisher::Assign() method, this method can be used to pass any type of variable.

void headPublisher::AssignVar(string $name, string $value)

Parameters:

• string $variable: The name of the variable to pass to JavaScript.
• string $value: The value of the variable to pass to JavaScript. This value can be any variable type.

Return value:
None.

headPublisher::clearScripts()

The headPublisher::clearScripts() method deletes all JavaScript files that have been added to the Ext JS content in a page, but only adds an HTML template file to the private extJsContent[] array, which is a list of Ext JS files that will later be rendered when G::RenderPage() is called.

void headPublisher::AddContent(string $templateHtml)

Parameters:

• string $templateHtml: The filename of the HTML template file to add to the forthcoming page that will be rendered. If the file has the extension ".html", then the extension does not need to be included. The HTML file should be found in the workflow/engine/templates/ directory or the workflow/engine/plugins/plugin-name/ directory. For example, the workflow/engine/templates/groups/groupsList.html file would be "groups/groupsList" and the workflow/engine/plugins/deleteCases/deleteCasesApplication1.html file would be "deleteCasesApplication1".

Return value:
None.

Example:

InputDocument class

The InputDocument class is defined in workflow/engine/classes/model/InputDocument.php and is used to manipulate the definition of Input Documents, which are stored in the wf_<WORKSPACE>.INPUT_DOCUMENT table in the database.

InputDocument::Load()

InputDocument::Load() returns information about the definition of an Input Document.

array InputDocument::Load(string uid)

Parameters:

• string uid: The unique ID of an Input Document, which can be found in the following ways:
  • Open a process, go to Input Documents and click on the UID button in the list.
  • Use the inputDocumentProcessList() web service.
  • Query the wf_<WORKSPACE>.INPUT_DOCUMENT.INP_DOC_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='INP_DOC_TITLE'

Return Value:
An associative array with the following elements:
array (

string ["INP_DOC_UID"]: The unique ID of the Input Document.

string ["PRO_UID"]: The unique ID of the process that contains the Input Document.

string ["INP_DOC_FORM_NEEDED"]: The document type, which can be: "REAL" (Printed), "VIRTUAL" (Digital) or "VREAL" (Digital/Printed).

string ["INP_DOC_ORIGINAL"]: If the INP_DOC_FORM_NEEDED is "REAL" or "VREAL"), the format of that original document can be "ORIGINAL", "COPY" or "COPYLEGAL".

string ["INP_DOC_PUBLISHED"]: Always set to "PRIVATE".

int ["INP_DOC_VERSIONING"]: Set to 1 if versioning is enabled. Otherwise, set to 0.

string ["INP_DOC_DESTINATION_PATH"]: The destination path, which is a directory or a path of directories where the Input Document files will be found under HOME > Documents.

string ["INP_DOC_TAGS"]: Tags to easily identify and find the Input Document files. If there are multiple tags, separate them with commas.

string ["INP_DOC_TITLE"]: The title of the Input Document.

string ["INP_DOC_DESCRIPTION"]: The description of the Input Document.

)

Example:

Menu class

Menus in ProcessMaker are created with the Menu class, which is defined in gulliver/system/class.menu.php. Menu files are found in the workflow/engine/menus/ directory.

ProcessMaker uses the following global variables to reference its menus:

• $G_MAIN_MENU: This variable defines the top-level menu. ProcessMaker uses the following top level menus:

"processmaker": The main ProcessMaker menu. Generally this will be the only menu used by plugins.

"caseTracker": The Case Tracker menu.

"tools": Used to update interface strings.

"workflow": Used to add new Workspaces.

"rbac": Used for administering users.

• $G_SUB_MENU: This variable defines the submenu, which is the secondary menu below the top-level menu. ProcessMaker 2.X uses sidebars with options instead of submenus, although submenus can still be created with plugins in ProcessMaker 2.X. Common submenus in ProcessMaker 1.X include:

"cases": The CASES menu in ProcessMaker 1.X.

"processes": The PROCESSES menu in ProcessMaker 1.X.

"users": The USERS menu in ProcessMaker 1.X.

"setup": The ADMIN menu in ProcessMaker 1.X

Other available submenus in ProcessMaker 1.X include:

"processCategory", "caseOptions", "appFolder", "dashboard", "toolsTranslations", "rbac.appView", "rbac.appEdit", "rbac.authSource", "rbac.role", "rbac.user","rbac.userView", "rbac.userEdit", "welcome", "cancel", "rbac.authentication", "rbac.application".

• $G_MENU_SELECTED: This variable is an integer that defines which option in the top-level menu is currently selected. A value of 0 is the first option, 1 is the second option, 2 is the third option, etc. Set to -1 or "" (empty string) to not select any option.

Note that the number of options displayed depends upon the role of the user logged in and the present plugins, so don't rely on any option having a fixed number.

• $G_SUB_MENU_SELECTED: This variable is an integer that identifies which option in the submenu is currently selected.
• $G_ID_MENU_SELECTED: This variable defines which top-level menu option is currently selected, using the ID strings for the menus.
  New menu ID strings can be created, but by default the principal ProcessMaker menu includes the following menu options:
  • "PROCESSES": The PROCESSES menu option in version 1.X. The DESIGNER menu option in version 2.X.
  • "SETUP": The ADMIN menu option.
  • "CASES": The CASES menu option in version 1.X. The HOME menu option in version 2.X.
  • "DASHBOARD": The DASHBOARD menu option in versions 1.X and 2.0.34+.
• $G_ID_SUB_MENU_SELECTED: This variable defines which submenu option is currently selected, using the ID strings for the menus.
• $G_TMP_MENU: A temporary menu option that is not displayed to the user, but is often used before adding to a normal menu.

Example:
To use the main ProcessMaker menu and the processes submenu, select the PROCESSES option in the main menu and the DYNAFORMS option in the submenu:

Menu::AddIdRawOption()

The Menu::AddIdRawOption() method adds an option to a menu using an ID string. The option will be added to the end of the list of existing options. .

void Menu::AddIdRawOption(variant $strId, string $strURL = "", string $label = "", string $icon = "", string $js = "", string $strType = "plugins", string $elementClass = "")

Parameters:

• variant $strId: Sets the unique string to identify the menu. It is recommended to use a ID in upper case like "MYMENU". This parameter can either be a string with the ID or an array that also sets both the ID and a class for the ID. For example: array("MYMENU", "MyMenuClass")
• string $strURL: Optional. A URL (which is generally a relative path) to the code file that should be executed when the menu option is clicked.
• string $label: Optional. A text label for the menu.
• string $icon: Optional. A URL (which is generally a relative path) to the icon image that is displayed next to the text label in the menu.
• string $js: Optional. A bit of JavaScript to be executed when the user clicks on the menu option, such as: 'showDbConnectionsList(Pm.options.uid); return false;'
• string $strType: Optional. Identifies the type of the menu option. Possible Values: 'settings', 'users', 'plugins'
• string $elementClass: Optional. The name of an ExtJS class associated with the menu option, such as: 'blockHeader', 'blockHeaderNoChild', 'ss_sprite ss_arrow_switch', 'ss_sprite ss_calendar_view_day', 'ss_sprite ss_page_white_put', 'ss_sprite ss_page_white_get', 'ss_sprite ss_application_form', 'ss_sprite ss_database_connect', 'ss_sprite ss_arrow_switch', 'ss_sprite ss_cog'

Return Value:
none

Example:
Use the $G_TMP_MENU global variable, which is an instance of the Menu class, to add the "Inbox" option to the temporary menu:

OutputDocument class

The OutputDocument class is defined in workflow/engine/classes/model/OutputDocument.php and is used to manipulate the definition of Output Documents, which are stored in the wf_<WORKSPACE>.OUTPUT_DOCUMENT table in the database.

OutputDocument::Load()

OutputDocument::Load() returns information about an Output Document.

array OutputDocument::Load(string uid)

Parameters:

• string uid: The unique ID of an Output Document, which can be found in the following ways:
  • Open a process, go to Output Documents and click on the UID button in the list.
  • Use the outputDocumentList() web service.
  • Query the wf_<WORKSPACE>.OUTPUT_DOCUMENT.OUT_DOC_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='OUT_DOC_TITLE'

Return Value:
An associative array with the following elements:
array (

string ["OUT_DOC_UID"]: The unique ID of the Output Document.

string ["PRO_UID"]: The unique ID of the Process.

string ["OUT_DOC_LANDSCAPE"]: Set to 1 if the layout is landscape (horizontal); otherwise, set to 0 for portrait (vertical) layout.

string ["OUT_DOC_MEDIA"]: Size of media, such as "Letter".

int ["OUT_DOC_LEFT_MARGIN"]: Left margin of paper in mm.

int ["OUT_DOC_RIGHT_MARGIN"]: Right margin of paper in mm.

int ["OUT_DOC_TOP_MARGIN"]: Top margin of paper in mm.

int ["OUT_DOC_BOTTOM_MARGIN"]: Bottom margin of paper in mm.

string ["OUT_DOC_GENERATE"]: Type of document to generate, which can be: "PDF", "DOC" or "BOTH".

string ["OUT_DOC_TYPE"]: Type of template, which the interface only allows to be "HTML".

string ["OUT_DOC_CURRENT_REVISION"]: Not used. Always set to 0.

string ["OUT_DOC_FIELD_MAPPING"]: Not used. Always set to NULL.

int ["OUT_DOC_VERSIONING"]: If versioning is enabled, set to 1. Otherwise, set to 0.

string ["OUT_DOC_DESTINATION_PATH"]: The destination path, which is a directory or a path of directories where the generated Output Documents will be found under under HOME > Documents.

string ["OUT_DOC_TAGS"]: Tags to easily identify and find the generated Output Documents. If there are multiple tags, separate them with commas.

int ["OUT_DOC_PDF_SECURITY_ENABLED"]: If PDF security is enabled, set to 1. Otherwise, set to 0.

string ["OUT_DOC_PDF_SECURITY_OPEN_PASSWORD"]: The encrypted password to open the PDF.

string ["OUT_DOC_PDF_SECURITY_OWNER_PASSWORD"]: The encrypted PDF owner password.

string ["OUT_DOC_PDF_SECURITY_PERMISSIONS"]: The PDF security permissions concatenated: "print", "|modify", "|copy" and/or "|annot-forms".

string ["OUT_DOC_TITLE"]: Title of the Output Document.

string ["OUT_DOC_DESCRIPTION"]: Description of the Output Document.

string ["OUT_DOC_FILENAME"]: Filename of the Output Document.

string ["OUT_DOC_TEMPLATE"]: Text of the Output Document template.

)

Example:

PMPlugin class

The PMPlugin class, which is defined in the file workflow/engine/classes/class.plugin.php, provides methods to define plugins and register and manipulate elements of the plugin.

PMPlugin::registerMenu()

PMPlugin::registerMenu() registers the ID for a menu bar or a menu option and its code file, so it can be used by the plugin. This function passes its parameters onto PMPluginRegistry::registerMenu() to do the registration.

void PMPlugin::registerMenu(string $menuId, string $menuFilename)

Parameters:

• string $menuId: Name to identify the menu.
• string $menuFilename: Name of the PHP file that defines the menu, which should be located in the workflow/engine/plugins/plugin-name/ directory.

PMPluginRegistry class

The PMPluginRegistry class, which is defined in the file workflow/engine/classes/class.pluginRegistry.php, is used to register the elements of a plugin.

PMPluginRegistry::registerMenu()

PMPluginRegistry::registerMenu() registers a menu option used by a plugin.

void PMPluginRegistry::registerMenu(string $sNamespace, string $sMenuId, string $sFilename)

Parameters:

• string $sNamespace: Name of the Gulliver application, which will be "processmaker" if building a plugin for ProcessMaker.
• string $sMenuId: Name of the file that defines the menu.
• string $sFilename: Name of the file that defines the menu, which should be located in the plugins/plugin-name/plugin-name/ directory.

Process class

The Process class is defined in workflow/engine/classes/model/Process.php and is used to manipulate ProcessMaker processes.

Process::Load()

Process::Load() returns information about a process.

array Process::Load(string uid)

Parameters:

• string uid: The unique ID of a process, which can be found in the following ways:
  • Use the @@PROCESS system variable for the current process.
  • Use the PMFProcessList() or WSProcessList() functions or the processList() web service.
  • Query the wf_<WORKSPACE>.PROCESS.PRO_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='PRO_TITLE'

Return Value:
An associative array with the following elements:
array(

string ["PRO_UID"]: Unique ID of the process.

string ["PRO_PARENT"]: If a subprocess, then the unique ID of the parent process. Otherwise, the same unique ID as the PRO_UID.

float ["PRO_TIME"]: By default set to 0.

string ["PRO_TIMEUNIT"]: Unit of time used by PRO_TIME, which is generally "DAYS".

string ["PRO_STATUS"]: Status of process, which is either "ACTIVE" or "INACTIVE".

string ["PRO_TYPE_DAY"]: Type of day. By default set to "" (empty string).

string ["PRO_TYPE"]: The process type, which is generally "NORMAL".

string ["PRO_ASSIGNMENT"]: The process assignment, which is generally "FALSE".

int ["PRO_SHOW_MAP"]: Set to 1 if showing the process map, otherwise 0 if not showing it.

int ["PRO_SHOW_MESSAGE"]: Set to 1 if showing case messages, otherwise 0 if not showing it.

int ["PRO_SHOW_DELEGATE"]: Set to 1 if showing task delegations, otherwise 0 if not showing it.

int ["PRO_SHOW_DYNAFORM"]: Set to 1 if showing list of Dynaforms, otherwise 0 if not showing it.

string ["PRO_CATEGORY"]: Unique ID of the process category. Set to "" (empty string) if no process category was selected.

string ["PRO_SUB_CATEGORY"]: Unique ID of the process subcategory. This feature is not supported and is always set to "" (empty string).

int ["PRO_INDUSTRY"]: The process' industry, which is no longer used and is always set to 0.

string ["PRO_UPDATE_DATE"]: The datetime when the process was last updated. This doesn't work and is always set to NULL.

string ["PRO_CREATE_DATE"]: The datetime when the process was first created in the "YYYY-MM-DD HH:MM:SS" format.

string ["PRO_CREATE_USER"]: Unique ID of the user who first created the process.

int ["PRO_HEIGHT"]: Height of the process map.

int ["PRO_WIDTH"]: Width of the process map.

int ["PRO_TITLE_X"]: X position of the process title in the process map. By default set to 0.

int ["PRO_TITLE_Y"]: Y position of the process title in the process map. By default set to 0.

int ["PRO_DEBUG"]: Set to 1 if the process debugger is enabled or 0 if disabled.

boolean ["PRO_DYNAFORMS"]: Generally set to false.

string ["PRO_DESCRIPTION"]: Description of the process.

string ["PRO_TITLE"]: Title of the process.

string ["PRO_CATEGORY_LABEL"]: The label for the process' category. If no category was selected then set to "No Category".

)

Example:
Get the category for the current process and assign it to a case variable named "processCategory", which will be displayed in a subsequent Dynaform.

Publisher class

The Publisher class is used by the Gulliver framework to display web pages. It is defined at gulliver/system/class.publisher.php.

Publisher::AddContent()

Publisher::AddContent() adds content to a page before it is displayed (with the G::RenderPage() method). This function can be called multiple times to continue adding content to a page before displaying it. The content is inserted in the $parts array, which is a member variable of the Publisher class.

void Publisher::AddContent(string $strType = "form", string $strLayout = "form", string $strName = "", string $strContent = "", array $arrData = NULL, string $strTarget = "", string $ajaxServer = "", string $mode = "", boolean $bAbsolutePath = false)

Parameters:

• string $strType: The type of content to be added. This parameter determines how the content will be added by the Publisher::RenderContent0() method. Available content types include:
  • "view": Content is rendered with a template found in the gulliver/templates/ or /workflow/engine/plugins/<PLUGIN-NAME>/ directories.
  • "content": Same as "view".
  • "xmlform": Content is defined by XML code and its file is found in the workflow/engine/xmlform/ or /workflow/engine/plugins/<PLUGIN-NAME>/ directories. See the XML code for Dynaforms to understand the format.
  • "dynaform": A Dynaform defined for a process, whose file is found in the shared/sites/<WORKSPACE>/xmlForms/<PROCESS-UID>/ directory. It is processed the same as "xmlform".
  • "pagedtable": A table of data that is displayed with button controls to navigate pages of data. The table's fields are defined in an XML file found in the workflow/engine/xmlform/ or /workflow/engine/plugins/<PLUGIN-NAME>/ directories.
  • "propeltable": Like "pagedTable", but content data drawn from a database query.
  • "smarty": Content in the $parts->dataArray is rendered with an HTML Smarty template found in the gulliver/templates/ or /workflow/engine/plugins/<PLUGIN-NAME>/ directories.
  • "template":
  • "blank": Adds a blank space to the content.
  • "panel-init": Starts a panel.
  • "panel-tab": Adds a tab to a panel.
  • "panel-close": Ends a panel.
  • "externalContent": Adds external content with an external template. The content is loaded by G::LoadContent() and the template is loaded by G::LoadTemplateExternal().
  • "image": Content is an image file.
  • "appForm":
  • "menu":
  • "varform":
  • "table":
  • "graphLayout":
• string $strLayout: A template (without the extension) that is found in workflow/engine/templates/ (or one of its subdirectories). The most common templates are:
  • "xmlform": Its file uses XML to define its fields, which are laid out vertically.
  • "paged-table": Its file also uses XML to define its fields, but displays its data in columns and rows and has paging control buttons.
• string $strName : The name of the file that defines the fields (but not the content or data). The file is found in the workflow/engine/xmlform/ or /workflow/engine/plugins/<PLUGIN-NAME>/ directory.
• string $strContent: In most cases, set this to an empty string, but if $strType is "propelTable", then enter the criteria for the database query. The results of the query will be displayed in the table.
• array $arrData: An associative array of data to include in the fields, where the keys are the field names and the values are the field values.
• string $strTarget: The file that will process the content, located in the workflow/engine/methods/ or /workflow/engine/plugins/<PLUGIN-NAME>/ directory.
• string $ajaxServer: The code file that will handle AJAX calls for the content, located in the workflow/engine/methods/ or /workflow/engine/plugins/<PLUGIN-NAME>/ directory.
• string $mode: Set to "edit" if the content contains fields whose content can be edited by the user. Set to "" or "view" if the fields can't be edited.
• boolean $bAbsolutePath: Set to true if the files have their complete path, rather than a relative path inside the default locations. If files are indicated with relative paths, then set to false.

Return value:
None.

Example:

Route class

The Route class is defined in workflow/engine/classes/model/Route.php and is used to manipulate routing rules in ProcessMaker, which are stored in the wf_<WORKSPACE>.ROUTE table in the database.

Route::Load()

Route::Load() returns information about a routing rule.

array Route::Load(string uid)

Parameters:

• string uid: The unique ID of a routing rule, which can be found in the wf_<WORKSPACE>.ROUTE.ROU_UID field in the database.

Return Value:
An associative array with the following elements:
array(

string ["ROU_UID"]: The unique ID of the routing rule.

string ["ROU_PARENT"]: The unique ID of the parent routing rule. If there is no parent, then set to "0".

string ["PRO_UID"]: The unique ID of the process.

string ["TAS_UID"]: The unique ID of the task before the routing rule. Set to "-1" if the routing rule belongs to a converging gateway.

string ["ROU_NEXT_TASK"]: The unique ID of the task after the routing rule.

int ["ROU_CASE"]: Set to 1 if the routing rule can route the case. Otherwise, set to 0.

string ["ROU_TYPE"]: The type of routing rule, which can be: "SEQUENTIAL", "SELECT", "EVALUATE", "PARALLEL", "PARALLEL-BY-EVALUATION", "SEC-JOIN" (parallel join), or "DISCRIMINATOR".

string ["ROU_CONDITION"]: The text of the condition (if an evaluation or parallel by evaluation routing rule).

string ["ROU_TO_LAST_USER"]: To route to the last user, set to "TRUE". The ProcessMaker interface will always set this to "FALSE", but it can be changed to "TRUE" with Route class methods.

string ["ROU_OPTIONAL"]: Set to "TRUE" if the routing rule is optional. Always set to "FALSE".

string ["ROU_SEND_EMAIL"]: Set to "TRUE" if a notification should be set to the user designated to work on the next task. Otherwise, set to "FALSE".

int ["ROU_SOURCEANCHOR"]: Always set to 1.

int ["ROU_TARGETANCHOR"]: Always set to 0.

int ["ROU_TO_PORT"]: Always set to 1.

int ["ROU_FROM_PORT"]: Always set to 2.

string ["ROU_EVN_UID"]: Generally set to "" (empty string).

string ["GAT_UID"]: Unique ID of the routing rule's gateway. All routing rules, except sequencial, use gateways to determine the X and Y position of the routing rule lines on the process map.

)

Note: Separate routing rules are created for each parallel task.

Example:

Step class

The Step class is defined in workflow/engine/classes/model/Steps.php and is used to manipulate steps in ProcessMaker, which are stored in the wf_<WORKSPACE>.STEP table in the database.

Step::Load()

Step::Load() returns information about a step.

array Step::Load(string uid)

Parameters:

• string uid: The unique ID of a step, which can be found in the wf_<WORKSPACE>.STEP.STEP_UID field in the database.

Return Value:
An associative array with the following elements:
array(

string ["STEP_UID"]: The unique ID for the step.

string ["PRO_UID"]: The unique ID for the task where the step occurs.

string ["TAS_UID"]: The unique ID for the task's process.

string ["STEP_TYPE_OBJ"]: The type of object executed by the task, which can be: "DYNAFORM", "INPUT_DOCUMENT", "OUTPUT_DOCUMENT" or "EXTERNAL".

string ["STEP_UID_OBJ"]: The unique ID of the object that is executed by the step.

string ["STEP_CONDITION"]: The text of the condition for the step to execute. If "" (an empty string), then the step will always execute.

int ["STEP_POSITION"]: The step's position, which indicates the order that steps execute in a task. Counting starts from 1.

string ["STEP_MODE"]: The mode of the fields in a Dynaform, which can be: "EDIT" (all fields are editable), "VIEW" (all fields are read-only) or "" (determined by the Mode property of each individual field).

)

Example:

Task class

The Task class is defined in workflow/engine/classes/model/Task.php and is used to manipulate ProcessMaker tasks.

Task::Load()

Task::Load() returns an array with information about a task.

array Task::Load(string $uid)

Parameters:

• string uid: The unique ID of a task, which can be found in the following ways:
  • Use the @@TASK system variable or $_SESSION['TASK'] for the current task.
  • Use the PMFTaskList() or WSTaskList() functions or the taskList() web service.
  • Query the wf_<WORKSPACE>.TASK.TAS_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='TAS_TITLE'

Return Value:
An associative array with the following elements:
array(

string ["PRO_UID"]: The unique ID of the process for this task.

string ["TAS_UID"]: The unique ID of the task.

string ["TAS_TYPE"]: The type of task, which is either "NORMAL" or "SUBPROCESS" for a task that is a subprocess.

float ["TAS_DURATION"]: The expected duration of the task.

string ["TAS_DELAY_TYPE"]: by default set to "" (empty string).

float ["TAS_TEMPORIZER"]: by default set to 0.

string ["TAS_TYPE_DAY"]: by default set to "" (empty string).

string ["TAS_TIMEUNIT"]: by default set to "DAYS".

string ["TAS_ALERT"]: by default set to "FALSE".

string ["TAS_PRIORITY_VARIABLE"]: Variable that determines the priority of the task, which by default is "@@SYS_CASE_PRIORITY". This variable should contain a value between 1 and 5.

string ["TAS_ASSIGN_TYPE"]: The type of assignment, which is "BALANCED" or "EVALUATE" (if using Value Based Assignment and not using the default @@SYS_NEXT_USER_TO_BE_ASSIGNED variable).

string ["TAS_ASSIGN_VARIABLE"]: The variable that determines the next designated user to work on the task if using Value Based Assignment. By default, set to "@@SYS_NEXT_USER_TO_BE_ASSIGNED".

string ["TAS_MI_INSTANCE_VARIABLE"]: The variable that determines the total number of instances if using the discriminator. By default set to "@@SYS_VAR_TOTAL_INSTANCE". This field is no longer used.

string ["TAS_MI_COMPLETE_VARIABLE"]: The variable that determines the total number of instances that need to be completed by the discriminator. By default set to "@@SYS_VAR_TOTAL_INSTANCES_COMPLETE". This field is no longer used.

string ["TAS_ASSIGN_LOCATION"]: By default set to "FALSE"

string ["TAS_ASSIGN_LOCATION_ADHOC"]: By default set to "FALSE"

string ["TAS_TRANSFER_FLY"]: By default set to "FALSE"

string ["TAS_LAST_ASSIGNED"]: The unique ID of the last user designated to work on this task. If a user has never been designated then set to "0".

string ["TAS_USER"]: By default set to "0".

string ["TAS_CAN_UPLOAD"]: By default set to "FALSE".

string ["TAS_VIEW_UPLOAD"]: By default set to "FALSE".

string ["TAS_VIEW_ADDITIONAL_DOCUMENTATION"]: By default set to "FALSE".

string ["TAS_CAN_CANCEL"]: By default set to "FALSE"

string ["TAS_OWNER_APP"]: By default set to "FALSE"

string ["STG_UID"]: By default set to "" (empty string).

string ["TAS_CAN_PAUSE"]: Set to "TRUE" if the task can be paused; otherwise, set to "FALSE".

string ["TAS_CAN_SEND_MESSAGE"]: Set to "TRUE" if the task can send out email notifications; otherwise, set to "FALSE".

string ["TAS_CAN_DELETE_DOCS"]: By default set to "FALSE".

string ["TAS_SELF_SERVICE"]: Set to "TRUE" if the task has a Self Service designation rule. Otherwise, set to "FALSE".

string ["TAS_START"]: Set to "TRUE" if the task is an initial task that can start a case. Otherwise, set to "FALSE".

string ["TAS_TO_LAST_USER"]: By default set to "FALSE".

string ["TAS_SEND_LAST_EMAIL"]: If set to "TRUE", then an email notification is sent to the next assigned user(s) when the case arrives at this task. If set to "FALSE", then no email notification is sent for this task.

string ["TAS_DERIVATION"]: The type of route, which is always "NORMAL".

int ["TAS_POSX"]: The X position of the task in pixels in the process map.

int ["TAS_POSY"]: The Y position of the task in pixels in the process map.

int ["TAS_WIDTH"]: The width in pixels of the task graphic in the process map. By default set to 165.

int ["TAS_HEIGHT"]: The height in pixels of the task graphic in the process map. By default set to 40.

string ["TAS_COLOR"]: The color of the task in the process map. By default set to "" (empty string).

string ["TAS_EVN_UID"]: By default set to "" (empty string).

string ["TAS_BOUNDARY"]: By default set to "" (empty string).

string ["TAS_DEF_DESCRIPTION"]: By default set to "" (empty string).

string ["TAS_DEF_MESSAGE"]: By default set to "" (empty string).

string ["TAS_DEF_PROC_CODE"]: By default set to "" (empty string).

string ["TAS_DEF_SUBJECT_MESSAGE"]: By default set to "" (empty string).

string ["TAS_DEF_TITLE"]: By default set to "" (empty string).

string ["TAS_DESCRIPTION"]: The description of the task.

string ["TAS_TITLE"]: The title of the task.

)

Example:
Get the title and description of the current task to display in Dynaform fields named "taskTitle" and "taskDescription":

Triggers class

The Triggers class is defined in workflow/engine/classes/model/Triggers.php and is used to manipulate the definition of Triggers, which are stored in the wf_<WORKSPACE>.TRIGGERS table in the database.

Trigger::Load()

Trigger::Load() returns information about a trigger.

array Trigger::Load(string uid)

Parameters:

• string uid: The unique ID of a trigger, which can be found in the following ways:
  • Use the triggerList() web service.
  • Query the wf_<WORKSPACE>.TRIGGERS.TRI_UID field in the database.
  • Use the query: SELECT CON_VALUE, CON_ID FROM CONTENT WHERE CON_CATEGORY='TRI_TITLE'

Return Value:
An associative array with the following elements:
array (

string ["TRI_UID"]: The unique ID of the trigger.

string ["PRO_UID"]: The unique ID of the process.

string ["TRI_TYPE"]: The trigger type, which is always "SCRIPT".

string ["TRI_WEBBOT"]: The trigger code, which comes from a mediumtext field in MySQL

string ["TRI_PARAM"]: Trigger parameters. If the trigger was created with a wizard, this field contains a serialized array with the trigger code created by the wizard and an MD5 hash of that code. If the contents of TRI_WEBBOT do not hash to the same value, then ProcessMaker knows that the trigger code has been edited and will display the code in text editing window, rather than displaying it in the wizard.

string ["TRI_TITLE"]: The trigger title.

string ["TRI_DESCRIPTION"]: The trigger description.

)

Example:

Users class

The Users class is defined in workflow/engine/classes/model/Users.php and is used to manipulate users in ProcessMaker, which are stored in the wf_<WORKSPACE>.USERS table in the database.

Users::Load()

Users::Load() returns information about a user.

array Users::Load(string uid)

Parameters:

• string uid: The unique ID of a user, which can be found in the following ways:
  • Use the @@USER_LOGGED system variable for the user currently logged-in.
  • Use the PMFUserList() or WSUserList() functions or the userList() web service.
  • Query the wf_<WORKSPACE>.USERS.USR_UID field in the database.

Return Value:
An associative array with the following elements:
array(

string ["USR_UID"]: The user's unique ID.

string ["USR_USERNAME"]: The user's username, which must be unique and is case insensitive.

string ["USR_PASSWORD"]: An MD5 hash of the user's password,

string ["USR_FIRSTNAME"]: The user's first name. Up to 50 characters long.

string ["USR_LASTNAME"]: The user's last name. Up to 50 characters long.

string ["USR_EMAIL"]: The user's email address. Up to 100 characters long.

string ["USR_DUE_DATE"]: The date when the user's account is set to expire in the"YYYY-MM-DD HH:MM:SS" format.

string ["USR_CREATE_DATE"]: The datetime when the user's profile was first created in the "YYYY-MM-DD HH:MM:SS" format.

string ["USR_UPDATE_DATE"]: The datetime when the user's profile was last updated in the "YYYY-MM-DD HH:MM:SS" format.

string ["USR_STATUS"]: The user's status, which can be: "ACTIVE", "INACTIVE" or "ON_VACATION". Only users with "ACTIVE" status can login to the system.

string ["USR_COUNTRY"]: A 2 character code to identify the user's country. To find the full name of the country, do a search in the wf_<WORKSPACE>.ISO_COUNTRY table.

string ["USR_CITY"]: This element (which is misnamed), is a 1-3 character code for the region or state. To find the full name of the region or state, do a search in the wf_<WORKSPACE>.ISO_SUBDIVISION table.

string ["USR_LOCATION"]: A 3 character code for the location (which is generally a city or county). To find the full name of the location, do a search in the wf_<WORKSPACE>.ISO_LOCATION table.

string ["USR_ADDRESS"]: The address. Up to 255 characters long.

string ["USR_PHONE"]: The telephone number. Up to 24 characters long.

string ["USR_FAX"]: The fax number. Up to 24 characters long.

string ["USR_CELLULAR"]: The cellular telephone number. Up to 24 characters long.

string ["USR_ZIP_CODE"]: The postal code or zip code. Up to 16 characters long.

string ["DEP_UID"]: The unique ID for the user's department.

string ["USR_POSITION"]: The user's position. Up to 100 characters long.

string ["USR_RESUME"]: No longer used in version 3. In ProcessMaker 2, some versions allow uploading a resume file, of which the first 100 characters are displayed.

string ["USR_BIRTHDAY"]: The date of the user's birthday in the "YYYY-MM-DD" format.

string ["USR_ROLE"]: The name of the role.

string ["USR_REPORTS_TO"]: The unique ID for the user who the user reports to, i.e., the user's department manager.

string ["USR_REPLACED_BY"]: The unique ID for the user who replaces this user when going on vacation or leave.

string ["USR_UX"]: The User Experience interface for the user, which can be: "NORMAL", "SIMPLIFIED" or "SWITCHABLE". The simplified interface is designed for smartphones and mobile devices, which use less screen space and use finger touches and no right clicks.

)

Note: In most situations, it is recommended to use userInfo() to obtain user information, but Users::Load() can be used when extra information is needed.

Example:
Send an email from the current user's supervisor to the current user. Get the position of the current user, so that it will be inserted into the body of an email which contains the variable @#userPosition:

Users::userExists()

int Users::userExists(string $UsrUid)

Users::getAllInformation()

array Users::getAllInformation(string $UsrUid)

Users::getAll()

array Users::getAll(int $start=null, int $limit=null, $search=null)