Overview

ProcessMaker offers its web services in two formats: WSDL Web Services and Simple Trigger Web Services. When controlling ProcessMaker from an external application or script, use the standardized WSDL (Web Services Description Language) functions which can be called with any programming language such as PHP, Perl, Python, Ruby, VB.NET, C# or C++, which supports SOAP 1.2 and WSDL 1.1. When working with PHP in triggers, it is recommended to use ProcessMaker's Simple Trigger Web Services functions which have a much simpler syntax and less overhead than standard WSDL functions. These functions are named "WS...()". ProcessMaker's standard WSDL web services can be called in both triggers and in external scripts, whereas its simple trigger web services will only work inside triggers.

The standard WSDL web services pass objects with complicated structures as parameters and return even more complicated objects as their return value. In contrast, ProcessMaker's Simple Trigger Web Services use simpler data types for their parameters and return either integers or arrays which are simpler to parse than WSDL objects.

In addition to the two types of web services, there are corresponding ProcessMaker Functions named PMF...() to control ProcessMaker from within triggers. Unlike the web services functions, these ProcessMaker functions do not require a login and the creation of a SOAP client. They will execute as the currently logged-in user.

Note: From Version 2.0.42 WS Functions are deprecated.

Return Values

There are three standard types of return values for ProcessMaker's Simple Trigger Web Services functions. They generally return either an associative array containing a status_code and a message, or a numbered array of associative arrays containing a guid and a name.

WS Response Associative Array:

If a WS...() function returns a status code and message, it will return an associative array with the following structure:

associative array
(
  [int status_code]
  [string message]
  [int timestamp]
)

Where:

  • int status_code : An integer indicating the status or error number returned by the web service. If zero, then the function executed correctly. If a positive integer, then this is an error number. Check the documentation for each function for the different error numbers.
  • string message : A message returned by the web service. If an error occurred, then this message will indicate the type of error.
  • int timestamp : The datatime when the web service response was returned.
WS List Array:

WS...() list functions return a numbered array containing associative arrays:

[0] array
(
   associative array
   (
      [string guid]
      [string name]
   )
)
[1] array
(
   associative array
   (
      [string guid]
      [string name]
   )
)
..

Where:

  • string guid: The unique ID (of a group, role, process, task, etc.)
  • string name: The name (of a group, role, process, task, etc.)

WSOpen()

WSOpen() opens a connection for web services and returns a SOAP client object which is used by all subsequent other WS function calls.

object SoapClient WSOpen(boolean force=false)

Note: This function currently has a bug and doesn't work.

Parameters:

  • boolean force: Optional parameter. Set to true to force a new connection to be created even if a valid connection already exists. If not included, will be set to false by default.

Return Value:

A SoapClient object. If unable to establish a connection, returns NULL.

Example:

 $oClient = WSOpen(true);
 if ($oClient !== NULL)
 {  
     // Continue with trigger code
 }

WSLogin()

WSLogin() logs in a user to initiate a web services session in a ProcessMaker server.

string WSLogin(string username, string password, string endpoint)

Note: This function currently has a bug and doesn't work.

Parameters:

  • string username : The username of the user who will login to ProcessMaker. All subsequent actions will be limited to the permissions of that user. Remember that a standard production user only has the PM_LOGIN and PM_CASES permissions in his/her role.
  • string password : The user's password encrypted as an MD5 hash with 'md5:' prepended. For example: 'md5:21232f297a57a5a743894a0e4a801fc3'. If a user's password is known, use PHP's md5() function to create the MD5 hash. If the password is not known, use executeQuery() to look up the user's password in the field wf_<WORKSPACE>.USERS.USR_PASSWORD.
  • string endpoint : The URI (address) of the WSDL definition of the ProcessMaker web services, which is found at:
http://<IP-ADDRESS>:<PORT>/sys<WORKSPACE>/en/green/services/wsdl

Return Value:

The unique ID for the initiated session.

Example:

Login as the user "admin", using the password "admin" whose hash is generated by PHP's md5() function:

 $pass = 'md5:' . md5('admin');
 $sessionId = WSLogin('admin', $pass, 'http://localhost/sysworkflow/en/green/services/wsdl');

Lookup the "admin" user's password in the ProcessMaker database and then use it to login:

 $result = executeQuery("SELECT USR_PASSWORD FROM USERS WHERE USR_USERNAME='admin'");
 if (is_array($result) &amp;&amp; count($result) > 0)
 {
    $pass = $result[1]['USR_PASSWORD'];
    $pass = 'md5:' . $pass;
    $sessionId = WSLogin('admin', $pass, 'http://localhost/sysworkflow/en/green/services/wsdl');
 }

Notice that "md5:" has to be put before the recovered password from the database, as in the example.

By default sessions will close after 5 minutes of inactivity. To extend the inactivity time, open the file: /<WORKSPACE>/engine/classes/class.wsBase.php
On a Linux/UNIX server it will generally be found at: /opt/processmaker/workflow/engine/classes/class.wsBase.php
Look for the line:

 $session->setSesDueDate(date('Y-m-d H:i:s',mktime(date('H'),date('i')+5,date('s'),date('m'),date('d'),date('Y')))

Change the number 5 to something larger. For instance to have sessions expire after 60 minutes of inactivity:

 $session->setSesDueDate(date('Y-m-d H:i:s',mktime(date('H'),date('i')+60,date('s'),date('m'),date('d'),date('Y')))

WSGetSession()

WSGetSession() returns the unique ID for the current active session.

string WSGetSession(void)

Parameters:

None.

Return Value:

The unique ID for the current active session.

Example:

 $sessionId = WSGetSession();

WSTaskCase()

WSTaskCase() returns all the tasks which has open delegations for the indicated case.

array WSTaskCase(string caseId)

Parameters:

  • string caseId :' The unique ID for the case. Case UIDs can be found with WSCaseList() and are stored in the field wf_<WORKSPACE>.APPLICATION.APP_UID.

Return Value:

An array of tasks in the indicated case which have open delegations. The array has the following structure:

[0] array ( associative array ( [string guid] [string name] ) ) ..

Where:

  • string guid : The unique ID of a task.
  • string name : The name of a task.

Example:

 @@PendingTasks = WSTaskCase(@@APPLICATION);

WSTaskList()

WSTaskList() returns a list of tasks in which the logged-in user can initiate cases or is assigned to these cases.

array WSTaskList(void)

Parameters:

  • It does not need any parameters.

Return Value:

  • This function returns a list of tasks with the following structure:
[0] array ( associative array ( [string guid] [string name] ) ) ..

Where:

  • string guid: The unique ID for a task.
  • string name: The name of a task.

Example:

 @@Tasks = WSTaskList();

WSUserList()

WSUserList() returns a list of users whose status is "ACTIVE" in the current workspace. Note that the logged-in user must have PM_USERS permission in his/her role to see UsersList.

array WSUserList(void)

Parameters:

  • It does not need any parameter.

Return Value:

  • The function returns a list of users, with the following structure:
[0] array ( associative array ( [string guid] [string name] ) ) ..

Where:

  • string guid: The unique ID for a user.
  • string name: The name of a user.

Example:

 WSLogin('admin', 'admin');
 @@aUsers = WSUserList();

WSGroupList()

WSGroupList() returns a list of active groups in a workspace. Note that the logged in user must have PM_USERS permission in his/her role to see the groups.

array WSGroupList(void)

Parameters:

  • It does not need any parameter.

Return Value:

  • It returns a list of active groups in the current workspace, with the following structure:
[0] array ( associative array ( [string guid] [string name] ) ) ..

Where:

  • string guid: The unique ID for a group.
  • string name: The name of a group.

Example:

 @@aGroups = WSGroupList();

WSRoleList()

WSRoleList() returns a list of roles in the current workspace. Note that the logged in user must have PM_USERS permission in his/her role to have permission to see the roles.

array WSRoleList(void)

Parameters:

  • This function does not need parameters.

Return Value:

  • It returns a list of roles with the following structure:
[0] array ( associative array ( [string guid] [string name] ) ) ..

Where:

  • string guid: The unique ID for a role.
  • string name: The name of a role.

Example:

 @@GridRoles = WSRoleList();

WSCaseList()

WSCaseList() returns a list of the cases to which the logged in user has privileges to see them.

array WSCaseList(void)

Parameters:

  • This function does not need any parameter.

Return Value:

  • It returns a list of cases with the following structure:
[0] array ( associative array ( [string guid] [string name] ) ) ..

Where:

  • string guid: The unique ID for a case.
  • string name: The name of a case.

Example:

 @@GRID_CASES = WSCaseList();

WSProcessList()

WSProcessList() returns a list of processes in the current workspace.

array WSProcessList(void)

Parameters:

  • It does not need any parameter.

Return Value:

A list of processes with the following structure:

[0] array ( associative array ( [string guid] [string name] ) ) ..

Where:

  • string guid: The unique ID for a process.
  • string name: The name of a process.

Example:

 @@GRID_PROCESSES = WSProcessList();

This example will return the processes list of the workflow workspace.

WSSendVariables()

WSSendVariables() sends two variables to the specified case. It will create new case variables if they don't already exist. If they do exist, it will change the value of the existing variables. If only one variable needs to be sent a case, use empty strings for the second variable name and value.

array WSSendVariables(string caseId, string varname2, string varvalue2, string varname2, string varvalue2)

Parameters:

  • string caseId : The unique ID of the case which will receive the variables. To send variables to the current case, use the system variable @@APPLICATION.
  • string varname1 : The name of the first variable to be sent to the created case.
  • string varvalue1 : The value of the first variable to be sent to the created case.
  • string varname2 : The name of the second variable to be sent to the created case.
  • string varvalue2 : The value of the second variable to be sent to the created case.

Return Value:

Example:

 WSSendVariables(@@APPLICATION, 'ContactCompany', 'Acme Inc.', 'ContactDate', '2010-12-31');

WSDerivateCase()

WSDerivateCase() routes (derivates) a case, i.e., moves the case to the next task in the process according its routing rules. Note that the logged in user must be assigned to the current task of the case or have proper permissions to route the case.

array WSDerivateCase(string caseId, int delegation)

Parameters:

  • string caseId : The unique ID for a case, which can be found with WSCaseList() or by examining the field wf_<WORKSPACE>.APPLICATION.APP_UID. To route the current case, use the system variable @@APPLICATION. Note that the case UID changes with every task in a process.
  • int delegation : The delegation index for the task, which can be found by examining the field wf_<WORKSPACE>.APP_DELEGATION.DEL_INDEX. Note that the delegation index starts counting from 1 and can change frequently, so it is a good idea to lookup the delegation index immediately before calling WSDerivateCase().

Return Value:

A WS Response associative array.

Example:

 $app = @@APPLICATION;
 $result = executeQuery("SELECT DEL_INDEX FROM APP_DELEGATION " .
     "WHERE APP_UID='$app' AND DEL_THREAD_STATUS='OPEN'");
 if (is_array($result) and count($result) > 0)
     WSDerivateCase($app, $result[1]['DEL_INDEX']);

WSNewCaseImpersonate()

WSNewCaseImpersonate() creates a case with any user with two initial case variables.

array WSNewCaseImpersonate(string processId, string userId, string varname1, string varvalue1, string varname2, string varvalue2)

Parameters:

  • string processId : The unique ID for the process.
  • string userId : The unique ID for the user.
  • string varname1 : The name of the first variable to be sent to the created case.
  • string varvalue1 : The value of the first variable to be sent to the created case.
  • string varname2 : The name of the second variable to be sent to the created case.
  • string varvalue2 : The value of the second variable to be sent to the created case.

To not to send any case variables to the new case, set varname1, varvalue1, varname2, and varvalue2 to empty strings.

Return Value:

A WS Response associative array.

Example:

 WSNewCaseImpersonate(@@PROCESS, @@USER_LOGGED, 'OrderDate', '2010-12-31', '', '');

WSNewCase()

WSNewCase() creates a new case starting with a specified task and using two initial case variables.

array WSNewCase(string processId, string taskId, string varname1, string varvalue1, string varname2, string varvalue2)

Parameters:

  • string processId : The unique ID for the process. To use the current process, use the system variable @@PROCESS.
  • string userId : The unique ID for the user. To use the currently logged-in user, use the system variable @@USER_LOGGED.
  • string varname1 : The name of the first variable to be sent to the created case.
  • string varvalue1 : The value of the first variable to be sent to the created case.
  • string varname2 : The name of the second variable to be sent to the created case.
  • string varvalue2 : The value of the second variable to be sent to the created case.

Return Value:

A WS Response associative array.

Example:

 WSNewCase(@@PROCESS, @@USER_LOGGED, 'Company', 'Acme Inc.', 'ContactDate', '2010-12-31');

WSAssignUserToGroup()

WSAssignUserToGroup() assigns a user to a group (as long as the logged in user has the PM_USERS permission in their role).

array WSAssignUserToGroup(string userId, string groupId)

Parameters:

  • string userId : The unique ID for a user.
  • string groupId : The unique ID for a group.

Return Value:

A WS Response associative array.

Example:

 $result = executeQuery("SELECT CON_ID FROM CONTENT WHERE " .
    "CON_VAL='Employees' AND CON_CATEGORY='GRP_TITLE'");
 $groupUID = result[1]['CON_ID'];
 WSAssignUserToGroup(@@USER_LOGGED, $groupUID);

WSCreateUser()

WSCreateUser() creates a new user in ProcessMaker.

array WSCreateUser(string userId, string password, string firstname, string lastname, string email, string role)

Parameters:

  • string userId: The username of the new user, which can be up to 32 characters long.
  • string password: The password of the new user, which can be up to 32 characters long. See Customizing Authentification.
  • string firstname: The first name(s) of the new user, which can be up to 50 characters long.
  • string lastname: The last name(s) of the new user, which can be up to 50 characters long.
  • string email: The e-mail of the new user, which can be up to 100 characters long.
  • string role: The role of the new user, such as 'PROCESSMAKER_ADMIN' and 'PROCESSMAKER_OPERATOR'.

To set the value of other information about the new user such as the address and phone number, use executeQuery() to insert values in the USERS table after calling WSCreateUser().

Return Value:

A WS Response associative array.

Example:

 $result = WSCreateUser('jdoe', 'P@22w0rd', 'Jane', 'Doe', 'jdoe@company.com', 'PROCESSMAKER_OPERATOR');
 if ($result['status_code'] == 0)
 {
     $result = executeQuery("INSERT INTO USERS FIELDS(USR_ADDRESS, USR_PHONE) " .
         "VALUES('123 W. Capital St.', '(276)235-1357') WHERE USR_USERNAME='jdoe'");
 }