2.0 - ProcessMaker WSDL Web Services

Contents: [hide]

Overview

ProcessMaker's WSDL Web Services provide a programming interface to remotely control and integrate ProcessMaker with external systems using SOA compliant protocols. WSDL Web Services allow ProcessMaker's functionality to be accessed remotely over the internet using the W3C's Simple Object Access Protocol (SOAP) 1.2 and Web Services Description Language (WSDL) 1.1. Unlike Simple Trigger Web Services which can only be called inside ProcessMaker triggers in PHP, WSDL web services can be called both in triggers and in external applications and scripts.

WSDL web services allow external programs to remotely retrieve lists of users, groups and roles, start and derivate cases and send notifications. These web services can be very useful when creating scripts to automate tasks in your server and creating web pages which create and derivate ProcessMaker cases.

Programming WSDL Web Services

ProcessMaker WSDL web services functions can be called by any language which has SOAP and WSDL libraries such as PHP, Java, Python, Perl, Ruby and the .NET languages like VB.NET and C#. Examples are provided using PHP, but they should work with other languages with slight modifications accounting for their particular manner of making function calls and handling objects.

The SOAP library for PHP implements both the SOAP 1.2 and WSDL 1.1 specifications. To use SOAP in a PHP script, PHP should be configured with the option --enable-soap. The ProcessMaker Windows Installer enables this option by default, but it may not be enabled in Linux/UNIX. To verify whether enabled, create the following script:

 
<?php
    phpinfo();
 ?>

Save the script to a file called phpinfo.php in your workflow/public_html directory, which is generally found in the following locations:

Linux/UNIX:

/opt/processmaker/engine/public_html

Windows:

ProcessMaker version 1-6.4260 or later in Windows XP/Server 2003:
C:\Program Files\ProcessMaker\processmaker\engine\public_html
ProcessMaker version 1-6.4260 or later in Windows Vista/7/Server 2008:
C:\Users\USERNAME\ProcessMaker\processmaker\engine\public_html
ProcessMaker before version 1-6.4260:
C:\Program Files\ProcessMaker\apps\processmaker\htdocs\workflow\public_html

Then direct your web browser to http://<your-ip-address>/phpinfo.php to see your PHP configuration. Look for a section labeled "soap" and verify that "Soap Client" is "enabled" for using external web services and "Soap Server" is "enabled" for offering ProcessMaker web services. When done, be sure to delete the file phpinfo.php because it is a security risk.

If unable to use web services, the problem may be that PHP is caching your WSDL calls for up to 24 hours. In this case, disable the WSDL cache in your PHP scipt with the line:

 ini_set("soap.wsdl_cache_enabled", "0");

When initially creating scripts which use web services, it is a good idea to display all errors to help debug the script:

 ini_set('error_reporting', E_ALL);
 ini_set('display_errors', True);

Later when your scripts are used in production, it is a good idea to turn off error reporting for security reasons.

Using External WSDL Web Services

External WSDL web services from other applications can be called from inside a ProcessMaker trigger with the SOAP library. First, find out how to call the web service by examining their WSDL page, which is in XML format.

For instance, if creating a process which has people sending in information from all over the world, a trigger could be created which looks up the IP number and determines the location of the senders. In this case, go tohttp://www.webservicex.net/geoipservice.asmx?WSDL and find out which functions are available. The XML can be examined to find the available functions, but it is easier to simply use the following script:

 
<?php
    $client = new SoapClient('http://www.webservicex.net/geoipservice.asmx?WSDL');
    foreach ($client->__getFunctions() as $func)
        print "$func <br>\n";
 ?>

Save the script to the file getfunctions.php in your workflow/public_html directory and direct your web browser tohttp://<your-ip-address>/getfunctions.php to see a listing of the available functions.

Then add a trigger which creates a SoapClient object and uses it to call web services functions. For instance, if there is a DynaForm where the user can enter an IP address in a field named "IP_ADDRESS", then the following trigger which is called after the DynaForm can look up the country of origin:

 $client = new SoapClient('http://www.webservicex.net/geoipservice.asmx?WSDL');
 $params = array('IPAddress'=> @@IP_ADDRESS);
 $result = $client->__SoapCall('GetGeoIP', array($params));
 @@COUNTRY = $result->GetGeoIPResult->CountryName;

The case variable @@COUNTRY can then be displayed on a subsequent DynaForm with a field named "COUNTRY" or in an output document containing @#COUNTRY.

To see more examples using external web services, download the "Web Services" process from the ProcessMaker library.

Testing ProcessMaker's WSDL Web Services

ProcessMaker offers its WSDL web services at the URL:

http://<IP-ADDRESS>/sys<WORKSPACE>/<LANGUAGE>/<SKIN>/services/wsdl2

For example:

http://example.com/sysworkflow/en/classic/services/wsdl2

To find out the location where your installation of ProcessMaker is offering its web services, login to ProcessMaker as a user such as "admin" who has the PM_SETUP permissions in her role. Go to ADMIN > Setting > Web Services Test and click on the Details link.

The address for the WSDL web services is listed, along with the name of the ProcessMaker workspace and the session ID. A new session ID is created each time a user logins into the web services. To test whether web services is functioning and create a new session ID, click on the [Test] link for Login and enter the name of a ProcessMaker user and his/her password.

When a new login session has been started, a session ID will be generated which can be used for all subsequent web services calls (until the session expires).

Once a login session has been started, all the other available ProcessMaker web services can also be tested by clicking on their [Test] links.

If a web service has an empty dropdown box to select a process, task, group, department, role, etc, then first click on the [Test] link for the corresponding list function to populate the dropdown box. For instance, to use the newCase() function, first test the processList() and taskList() functions, so the dropdown boxes to select the processId and taskId will be prepopulated.

Setting up the Web Services Test

By default all Web Services tests will use the address:

http://<current-address>:<current-port>/sys<current-workspace>/<current-lang>/<current-skin>/services/wsdl2

If using ProcessMaker's WSDL web services in a script, the protocol, port number and workspace can be specified in the URL which is used to create the web services connection. Nonetheless, when testing the web services inside the graphical interface, the URL can not be specified, so it has to be configured by going to ADMIN > Setting > Web Services Test and clicking on the Setup link.

The following fields can be edited:

  • Protocol: If the ProcessMaker server is configured to use a secure connection (SSL or TLS), select the shttp option. Otherwise, select the http option.
  • Server Host: The address (and port number) of the server which offers the web services.
  • Workspace: The name of a workspace to be used, such as the default "workflow". Changing this value allows logins to other workspaces.
  • Port: By default, this field will be left blank and the Server Host field will have the default port included in the address. If wishing to login to a different port number, then delete the port from the address in the Server Host field and enter the port number in this field.

After saving, the next login should use the new configuration. (If a login session is already open, wait till it expires, then login again.)

Logging in with ProcessMaker's WSDL web services

The WSDL web services can be called by an external program or by ProcessMaker triggers. First create a SOAP client object. For instance, if accessing ProcessMaker installed at http://myserver.com in the "workflow" workspace, then use:

 $client = new SoapClient('http://myserver.com/sysworkflow/en/classic/services/wsdl2');

Web services are handled through the SOAP client object, which can make function calls to ProcessMaker using the __SoapCall() method. It has two parameters:

  1. The name of the ProcessMaker web services function as a string.
  2. An array containing an associative array, which contains the parameters to pass to the web services function. Input each parameter name as a key with its value. (Remember that parameter names are case sensitive.)

To find out what functions to pass through __SoapCall() and its parameter array, see the function list below or examine the XML listing of functions in http://<IP-ADDRESS>/sys<WORKSPACE>/en/classic/services/wsdl2

login() Web Service

After instantiating a SOAP client object, then use the login() function to start a web services session in ProcessMaker:

loginResponse login(string userid, string password)

The userid is the name of the user and password is the user's password. Note that the function parameters for web service functions have to be passed as an associative array within an array.

For instance, if the user ID is 'andy' and the password is 'foobar', then login using the following script in PHP:

  $client = new SoapClient('http://myserver.com/sysworkflow/en/classic/services/wsdl2');
 $params = array(array('userid'=>'andy', 'password'=>'foobar'));
 $result = $client->__SoapCall('login', $params);

Using Hashed Passwords from the Database

The password can also be an MD5 hash, which is how the passwords are stored in the ProcessMaker database.

The hashed passwords can be found by entering MySQL and examining the field rb_<WORKSPACE>.USERS.USR_PASSWORD in your installation of ProcessMaker. For instance if using the "workflow" workspace (which is the default), enter the following commands in the command line:

C:\> cd "C:\Program Files\ProcessMaker\mysql\bin" (not necessary in Linux/UNIX) C:\Program Files\ProcessMaker\mysql\bin> mysql -u root -p Enter password: ********* mysql> select USR_USERNAME, USR_PASSWORD from rb_workflow.USERS; +--------------+----------------------------------+ | USR_USERNAME | USR_PASSWORD | +--------------+----------------------------------+ | admin | 21232f297a57a5a743894a0e4a801fc3 | | vato | 8185527669f0b54109c7c99488cd08e8 | | amy | 7771fbb20af6ef10827c593daa3aff7b | | patricia | 823fec7a2632ea7b498c1d0d11c11377 | | andy | 10b28c9abf3a62e9dcb63da27a7186d8 | +--------------+----------------------------------+ 5 rows in set (0.00 sec) mysql> quit;

The encrypted passwords need to identify their type of encryption when passed to the login() function. Prepend the string "md5:" to the front of each password, so the password for "andy"in the case above would be "md5:10b28c9abf3a62e9dcb63da27a7186d8". For example:

 $client = new SoapClient('http://myserver.com/sysworkflow/en/classic/services/wsdl2');
 $params = array(array('userid'=>'andy', 'password'=>'md5:10b28c9abf3a62e9dcb63da27a7186d8'));
 $result = $client->__SoapCall('login', $params);

If the passwords of the ProcessMaker users are already known, then PHP's md5() function can be used to create the MD5 hash for their passwords. For instance, if the user ID is 'andy' and the password is 'foobar':

 $client = new SoapClient('http://myserver.com/sysworkflow/en/classic/services/wsdl2');
 $pass = 'md5:' . md5('foobar');
 $params = array(array('userid'=>'andy', 'password'=>$pass));
 $result = $client->__SoapCall('login', $params);

Looking up Hashed Password

If passwords might change, it is a good idea to have the script lookup the encrypted MD5 password directly from the MySQL database right before calling the login() web service. If using web services inside a ProcessMaker trigger, then the password for a user can be looked up with the executeQuery() function. For instance, the following code would look up the password for the user "andy":

 $client = new SoapClient('http://myserver.com/sysworkflow/en/classic/services/wsdl2');
 $user = "andy";
 $result = executeQuery("SELECT USR_PASSWORD FROM USERS WHERE USR_USERNAME='$user'", 'rbac');
 $pass = "md5:" . $result[1]['USR_PASSWORD'];
 $params = array(array('userid'=>$user, 'password'=>$pass));
 $result = $client->__SoapCall('login', $params);

If using web services from an external script, then use the MySQL functions provided by your programming language to look up the password. For example, if programming in PHP, use themysql_query() function. The MD5 password for the user "andy" is queried on a MySQL server at 192.168.1.100, running on port 3306, which is the default port for MySQL.

 $conn = mysql_connect('192.168.1.100:3306', 'root', 'XXXXXXX') or
              die("Error connecting to MySQL database.\n");
 mysql_select_db('rb_workflow');
 $user = "andy";
 $result = mysql_query("SELECT USR_PASSWORD FROM USERS WHERE USR_USERNAME='$user'") or
              die("Error: Unable to query the USER table.\n");
 $record = mysql_fetch_array($result, MYSQL_ASSOC);
 if (!$record)
      die("Error: Unable to find password for '$user' in the USER table.\n");
 $client = new SoapClient('http://myserver.com/sysworkflow/en/classic/services/wsdl2');
 $pass = $record['USR_PASSWORD'];
 $params = array(array('userid'=>$user, 'password'=>$pass));
 $result = $client->__SoapCall('login', $params);

loginResponse object

The login() function returns a loginResponse object, which contains the following data members:

  • integer status_code: Zero if a successful login or a non-zero error number if unsuccessful.
  • string message: If a successful login, the session ID. If unsuccessful login, an error message.
  • string version: The version number of ProcessMaker's web services, which is currently "2.0". This number can be checked to verify that the web services haven't changed when upgrading ProcessMaker.
  • string timestamp: The datetime when the session began in the format "YYYY-MM-DD HH:MM:SS".

It is a good idea to check whether a login was successful by checking the status_code of the loginResponse object:

 if ($result->status_code == 0)
    $sessionId = $result->message;
 else
    print "Unable to connect to ProcessMaker.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

Once logged in, use web services to remotely control ProcessMaker.

LDAP and Active Directory Users

If logging in as a user who was imported from LDAP or Active Directory, then MD5 passwords can NOT be used. Imported users can only login using using their real passwords (except if the Authentication Source for those users is switched from LDAP or AD to MySQL).

If needing to use LDAP or Active Directory users in your scripts whose passwords might change, it is recommended to create a dummy user whose password will not change to do all your web services work. If just needing to send in variables and upload Input Documents to the case, then make the dummy user a Process Supervisor and give him/her rights to update specific DynaForms and Input Documents. If needing the dummy user to be able start cases, then assign the dummy user to the initial task(s) in the process.

If needing to route cases, then add the dummy user to the list of ad hoc users for tasks. Then, reassign the case to the dummy user and then route on the case. If needing ProcessMaker to show that a real user worked on the case, then write a trigger to set the real user in the database after the task has been closed. For example, create the following trigger in ProcessMaker:

$caseId = @@APPLICATION;
//case variables set with sendVariables() web service:
$lastIndex = @@lastIndex;
$realUserId = @@realUserId;
executeQuery("UPDATE APP_DELEGATION SET USR_UID='$realUserId' WHERE APP_UID='$caseId' AND DEL_INDEX=$lastIndex");

In the web services script, first routing on the case with routeCase(), then send in the index number for the previous task and the user unique ID for the real user with sendVariables() and then call executeTrigger() to fire the above trigger to change the user in the database. Remember to only change the user in this way for closed tasks in the case.

Web Services Response Objects

The ProcessMaker Web Services functions generally return two types of response objects, either a pmResponse object or an object containing an object containing an array of objects.

1. The ProcessMaker web services functions which do not return lists return a pmResponse object. It has the following structure:

object pmResponse ( [integer status_code] [string message] [string time_stamp] )

Where:

  • integer status_code: If the function was executed successfully this parameter is 0, otherwise it is a non-zero error number.
  • string message: The returned function message. If an error, then the error message.
  • string time_stamp: The date and time when the function was performed.

It is recommended to always check the status_code to verify that a web services function executed correctly.

2. Web services functions which return lists such as userList() and processList() will return an object containing an object which contains an array of objects. Here is the structure of theprocessListResponse object returned by processList():

object processListResponse ( object processes ( [0]array ( object processListStruct ( [string guid] [string name] ) ) [1]array ( object processListStruct ( [string guid] [string name] ) ) ... ) )

Where:

  • string guid: Process ID.
  • string name: Process name.

All the web services which return lists use the same basic object structure, although the names of the objects change. The innermost objects always contain the guid and name member variables, so the data can be accessed in the basically the same way for all the web services functions.

For each function, check the provided example to find out the names of the objects and see how to access their data. It is also recommended to use PHP's var_dump() function to investigate the structure of web services objects.

When there is an error obtaining a list, the object returned has a slightly different structure. It contains the same objects, but does not contain an array:

object processListResponse ( object processes ( object processListStruct ( [string guid] [string name] ) ) )

Where:

  • string guid: The error number.
  • string name: The error message.

When using a web services list function, it is recommended to use PHP's is_array() function to check the return object to verify whether it contains an array. If not containing an array, an error has occurred.

Web Services Error Numbers

After calling a web services function, it is a good idea to check its return object, to verify that the function executed correctly. The guid contains the error number and the name contains the error message, but these member variables have to be accessed differently depending on the type of return object. To see how to check for the error number, see the provided examples for the different web services functions.

Error NumberFunctionStatus Message
0allCommand executed successfully
1loginUser does not have access to system
2many functionsInsufficient privileges to execute this function
3login
assignUserToGroup
User not registered in the system
4loginWrong password
5loginuser is inactive
6createUserInvalid role
7createUserUser ID: $userId already exists!
8assignUserToGroupUser exists in the group
9assignUserToGroupGroup not registered in the system
10newCaseArray of variables is empty
11newCaseInvalid process $processId
12newCaseNo starting task defined
13newCaseMultiple starting tasks
14newCaseTask invalid or the user is not assigned to the task
15derivateCaseThe task is defined for Manual assignment
16getCaseInfoCase $caseNumber doesn't exist
17routeCase
executeTrigger
This case is assigned to another user
18routeCase
executeTrigger
sendVariables
This delegation is already closed or does not exist
19routeCase
executeTrigger
This case is in status $caseType
20routeCasePlease specify the delegation index
21routeCaseCan not route a case with Manual Assignment using webservices
22routeCaseTask does not have a routing rule; check process definition
23sendVariablesThe variables parameter length is zero
24sendVariablesThe variables parameter is not a array
25createUserUser ID is required
26createUserPassword is required
27createUserFirstname is required
28sendMessagetemplate file doesn't exist
29sendMessageproblems sending the email
30reassignCaseTarget and Origin user are the same
31reassignCaseInvalid origin user
32reassignCaseThis case is not open.
33reassignCaseInvalid Case Delegation index for this user
34reassignCaseThe target user does not have rights to execute the task
35reassignCaseThe target user destination is invalid
36reassignCaseThe case could not be reassigned.
100systemInformationA system error message.
100importProcessFromLibraryThe process is already in the System and the value for $importOption is not specified.
or
Error the url $downloadUrl is invalid or the process in $newfilename is invalid
or
A system error message.

Web Services Security

Remember that login passwords are sent as plain text inside SOAP packets, so any packet sniffer watching the traffic can grab passwords. For this reason, it is recommended to store and execute your web services script on the same machine as the ProcessMaker server, so the packets aren't passing over a public network. If planning on passing SOAP packets over a public network, use an SSL or TLS connection to encrypt the traffic.

Remember that using an MD5 password is little protection. MD5 hashes can be cracked (and passwords which are common words in dictionaries are especially easy to crack with password dictionary). More importantly, anyone watching the internet traffic can grab the password hashes and use those hashes directly in a script to login.

Also remember to protect your passwords if your web services script is stored in a publicly accessible place. If your script is executable from the internet, your script should NOT contain passwords either in plain text form or a MD5 hash. Either use a database query in the script to lookup the password or store the passwords in a separate file which is not publicly readable.

For example, create separate file which is not publicly accessible named credentials.php:

<?php
$username = 'janedoe';
$password = 'p@55w0rd';
?>

Then, import the credentials.php file into your publicly accessible script:

<?php
require_once('credentials.php');
$client = new SoapClient('http://myserver.com/sysworkflow/en/classic/services/wsdl2');
$params = array(array('userid'=>$username, 'password'=>$password));
$result = $client->__SoapCall('login', $params);
...

WSDL Web Services Functions

ProcessMaker provides the following web services which are listed below. These web services are all listed in the file workflow/engine/methods/services/pmos2.wsdl and they call functions which are defined in the file workflow/engine/methods/services/soap2.php.

userList()

userList() returns a list of the users. For privileges to see the list, the logged-in user must have the PM_USERS permission in his/her role.

userListResponse userList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The userListResponse object with the following structure:

object userListResponse ( object users ( [0]array ( object userListStruct ( [string guid] [string name] ) ) ... ) )

Where:

  • string guid: The user ID.
  • string name: The user name.

Example:

  $params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('userList', $params);
 $usersArray = $result->users;
 if (is_array($usersArray))
      foreach ($usersArray as $user)
           print "User name: $user->name, User ID: $user->guid \n";
 else
      print "Error: $usersArray->name \n";

UpdateUser()

UpdateUser() it updates user information.

UpdateUser(string userUid, string userName ,string firstName, string lastName, string email, string dueDate, string status, string role, string password)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string userId: The username for the new user. (The unique ID for the user will be automatically generated)
  • string userName: The username for the user.
  • string firstName: Firstname of the user.
  • string lastName: Lastname of the user.
  • string email: Email the user | Optional parameter. The email of the user, which can be up to 100 characters long.
  • string dueDate: xpiration date | Optional parameter. The expiration date must be a string in the format "yyyy-mm-dd".
  • string status: Status of the user | Optional parameter. The user's status, such as "ACTIVE", "INACTIVE" or "VACATION".
  • string role: Rol of the user | The role of the user such as "PROCESSMAKER_ADMIN" or "PROCESSMAKER_OPERATOR".
  • string password: Password of the user | The password of the user, which can be up to 32 characters long.

Return value:

The UpdateUserResponse object with the following structure:

object userListResponse ( object users ( [0]array ( object userListStruct ( [string guid] [string userName] [string firstName] [string lastName] [string email] [string dueDate] [string status] [string role] [string password] ) ) ... ) )

Example

$client = new SoapClient('127.0.0.1:8081/sysworkflow/en/classic/services/wsdl2');
$params = array(array('userid'=>'admin', 'password'=>'admin'));
$result = $client->__SoapCall('login', $params);
$sessionId = $result->message;
 
$params = array(array('sessionId'=>$sessionId, 'userUid'=>'613710077515984410747c9082456264', 'userName'=>'john', 'firstName' => 'john', 'lastName' => 'Doe', 'email' => 'johndoe@example.com', 'dueDate' => '2013-12-01', 'status' => 'ACTIVE', 'role' => 'PROCESSMAKER_OPERATOR','password' => 'johndoe'));
 $result = $client->__SoapCall('UpdateUser', $params);
 if ($result->status_code == 0)
    print "$result->message\Case UID: $result->caseUid";  
 else
    print "Unable Update User information.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

groupList()

groupList() returns a list of the groups. For privileges to see the list, the logged-in user must have the PM_USERS permission in his/her role.

groupListResponse groupList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The groupListResponse object with the following structure:

object groupListResponse ( object groups ( [0]array ( object groupListStruct ( [string guid] [string name] ) ) ... ) )

Where:

  • string guid: The group ID.
  • string name: The group name.

Example:

 $params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('groupList', $params);
 $groupsArray = $result->groups;
 if (is_array($groupsArray))
      foreach ($groupsArray as $group)
           print "Group name: $group->name, Group ID: $group->guid \n";
 else
      print "Error: $groupsArray->guid $groupsArray->name \n";

departmentList()

departmentList() returns a list of the departments. For privileges to see the list, the logged-in user must have the PM_USERS permission in his/her role. This function is available from version 1.2-3862Beta on.

departmentListResponse departmentList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The departmentListResponse object with the following structure:

object departmentListResponse ( object departments ( [0]array ( object departmentListStruct ( [string guid] [string name] [string parentUID] ) ) ... ) )

Where:

  • string guid: The department unique ID.
  • string name: The department name.
  • string parentUID: The unique ID for the parent department. If a top-level department, then will be an empty string.

Example:

 $params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('departmentList', $params);
 $deptsArray = $result->departments;
 if (is_array($deptsArray))
      foreach ($deptsArray as $dept)
           print "Department name: $dept->name, ID: $dept->guid, Parent: $dept->parentUID \n";
 else
      print "Error: $deptsArray->guid $deptsArray->name \n";

roleList()

roleList() returns a list of the roles. For privileges to see the list, the logged-in user must have the PM_USERS permission in his/her role.

roleListResponse roleList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The roleListResponse object with the following structure:

object roleListResponse ( object roles ( [0]array ( object roleListStruct ( [string guid] [string name] ) ) ... ) )

Where:

  • string guid: The role ID.
  • string name: The role name.

Example:

  $params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('roleList', $params);
 $rolesArray = $result->roles;
 if (is_array($rolesArray))
      foreach ($rolesArray as $role)
           print "Role name: $role->name, Role ID: $role->guid \n";
 else
      print "Error: $rolesArray->name \n";

createUser()

createUser() creates a new user. For privileges to create a user, the logged-in user must have the PM_USERS permission in his/her role.

pmResponse createUser(string sessionId, string userId, string firstname, string lastname, string email, string role, string password)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string userId: The username for the new user. (The unique ID for the user will be automatically generated.)
  • string firstname: The user's first name.
  • string lastname: The user's last name.
  • string email: The user's email address.
  • string role: The user's role, such as 'PROCESSMAKER_ADMIN', 'PROCESSMAKER_MANAGER' or 'PROCESSMAKER_OPERATOR'. Possible values can be looked up with the roleList() function.
  • string password: The user's password, such as 'Be@gle2'. (It will be automatically converted into an MD5 hash when inserted in the database.)

Parameters userId, firstname and role are required and may not be empty strings.

Return value:

From version 1.2-2740 on, createUser() returns a createUserResponse object with the following structure:

object createUserResponse ( [integer status_code] [string message] [string userUID] [string timestamp] )

If successful, the message will contain the firstname, lastname and username of the new user, otherwise it will contain the error message.

Before version 1.2-2740, createUser() returned a pmResponse object. If the function executed successfully, the message contained the new user's role.

Example:

 $params = array(array('sessionId'=>$sessionId, 'userId' => 'howdy4',
    'firstname'=>'Howdy', 'lastname'=>'Foobar', 'email'=>'howdy@example.com',
    'role'=>'PROCESSMAKER_ADMIN', 'password'=>'HowDy123'));
 $result = $client->__SoapCall('createUser', $params);
 if ($result->status_code == 0)
    print "$result->message\nUser UID: $result->userUID";  
 else
    print "Unable to create user.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

createGroup()

createGroup() creates a new group. For privileges to create a group, the logged-in user must have the PM_USERS permission in his/her role. Available from version 1.2-3862Beta on.

createGroupResponse createGroup(string sessionId, string name)

Parameters:

  • string sessionId: The session ID (which was obtained at login).
  • string name: The name of the new group.

Return value:

A createGroupResponse object with the following structure:

object createGroupResponse ( [integer status_code] [string message] [string groupUID] [string timestamp] )

If successful, the message will contain the text "Group X created successfully", otherwise it will contain the error message.

Example:

 $params = array(array('sessionId'=>$sessionId, 'name' => 'Independent Contractors'));
 $result = $client->__SoapCall('createGroup', $params);
 if ($result->status_code == 0)
    print "$result->message\nGroup UID: $result->groupUID";  
 else
    print "Unable to create group.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

createDepartment()

createDepartment() creates a new department. For privileges to create a department, the logged-in user must have the PM_USERS permission in his/her role. Available from version 1.2-3862Beta on.

createDepartmentResponse createDepartment(string sessionId, string name, string parentUID)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string name: The name of the new department.
  • string parentUID: The unique ID of the parent department, which can be obtained with departmentList(). To make a top-level department, set to '' (an empty string).

Return value:

A createDepartmentResponse object with the following structure:

object createDepartmentResponse ( [integer status_code] [string message] [string departmentUID] [string timestamp] )

If successful, the message will contain the text "Department X created successfully", otherwise it will contain the error message.

Example:

 $params = array(array('sessionId'=>$sessionId, 'name' => 'Human Resources', 'parentUID' => ''));
 $result = $client->__SoapCall('createDepartment', $params);
 if ($result->status_code == 0)
    print "$result->message\nDepartment UID: $result->departmentUID";  
 else
    print "Unable to create department.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

assignUserToGroup()

assignUserToGroup() assigns a user to a group. For privileges to assign a user, the logged-in user must have the PM_USERS permission in his/her role.

pmResponse assignUserToGroup(string sessionId, string userId, string groupId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string userId: The ID of the user, which can be found with the userList() function.
  • string groupId: The ID of the group, which can be found with the groupList() function.

Return value:

A pmResponse object.

assignUserToDepartment()

assignUserToDepartment() assigns a user to a department. For privileges to assign a user, the logged-in user must have the PM_USERS permission in his/her role.

pmResponse assignUserToDepartment(string sessionId, string userId, string departmentId, string manager)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string userId: The ID of the user, which can be found with the userList() function.
  • string departmentId: The ID of the group, which can be found with the departmentList() function.
  • string manager: The ID of the department's manager, which can be found with the userList() function.

Return value:

A pmResponse object.

PauseCase()

PauseCase() Pauses a specified case.

pauseCaseResponse PauseCase(string caseUid, int delIndex, string userUid, string unpauseDate)

Parameters:

  • string caseUid: The unique ID of the case.
  • int delIndex: The delegation index of the current task in the case.
  • string userUid: The unique ID of the user who will pause the case.
  • string unpauseDate: Optional parameter. The date in the format "yyyy-mm-dd" indicating when to unpause the case.

Return value:

The pauseCaseResponse object with the following structure:

object pauseCase Response ( object processes ( [0]array ( object pauseCaseStruct ( [string status_code] [int message] [string timestamp] ) ) ... ) )

Example

$client = new SoapClient('http://127.0.0.1/sysworkflow/en/classic/services/wsdl2');
$params = array(array('userid'=>'admin', 'password'=>'admin'));
$result = $client->__SoapCall('login', $params);
$sessionId = $result->message;
 
$params = array(array('sessionId' => $sessionId, 'caseUid' => @@APPLICATION, 'delIndex'=> '1',
'userUid' => '00000000000000000000000000000001', 'unpauseDate' => '2013-12-01'));
 $result = $client->__SoapCall('pauseCase', $params);
 if ($result->status_code == 0)
    print "$result->message\Case UID: $result->caseUid";  
 else
    print "Unable to pause case.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

UnpauseCase()

UnpauseCase() Unpauses a specified case.

UnpauseCaseResponse UnpauseCase(string caseUid, int delIndex, string userUid)

Parameters:

  • string caseUid: The unique ID of the case.
  • int delIndex: The delegation index of the current task in the case.
  • string userUid: The unique ID of the user who will unpause the case.
  • array $response : A WS Response associative array.

Return Value:

The UnpauseCaseResponse object with the following structure:

object UnpauseCase Response ( object processes ( [0]array ( object UnpauseCaseStruct ( [string status_code] [int message] [string time_stamp] ) ) ... ) )

A pmResponse object.

Example:

$client = new SoapClient('http://127.0.0.1:8081/sysworkflow/en/classic/services/wsdl2');
 $params = array(array('userid'=>'admin', 'password'=>'admin'));
 $result = $client->__SoapCall('login', $params);
 $sessionId = $result->message;
 
$params = array(array('sessionId'=>$sessionId, 'caseUid'=>'889465332514082aaa3d480084317536', 'delIndex' => '2', 'userUid' => @@USER_LOGGED));
 $result = $client->__SoapCall('unpauseCase', $params);
 if ($result->status_code == 0)
    print "$result->message\ caseUid WAS UNPAUSED SUCCESSFULLY: $result->caseUid";  
 else
    print "Unable to unpause case.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

CancelCase()

CancelCase() Cancels a specified case.

CancelCaseResponse CancelCase(string caseUid, int delIndex, string userUid)

Parameters:

  • string caseUid: The unique ID of the case.
  • int delIndex: The delegation index of the current task in the case.
  • string userUid: The unique ID of the user who will unpause the case.
  • array $response : A WS Response associative array.

Return Value:

The CancelCaseResponse object with the following structure:

object CancelCase Response ( object processes ( [0]array ( object CancelCaseStruct ( [string status_code] [int message] [string time_stamp] ) ) ... ) )

A pmResponse object.

Example:

 $client = new SoapClient('http://127.0.0.1:8081/sysworkflow/en/classic/services/wsdl2');
 $params = array(array('userid'=>'admin', 'password'=>'admin'));
 $result = $client->__SoapCall('login', $params);
 $sessionId = $result->message;
 
$params = array(array('sessionId'=>$sessionId, 'caseUid'=>@@APPLICATION, 'delIndex' => @%INDEX, 'userUid' => @@USER_LOGGED));
 $result = $client->__SoapCall('cancelCase', $params);
 if ($result->status_code == 0)
    print "$result->message\Case UID: $result->caseUid";  
 else
    print "Unable to cancel case.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

DeleteCase()

CancelCase() Cancels a specified case.

DeleteCaseResponse CancelCase(string caseUid)

Parameters:

  • string caseUid: The unique ID of the case.

Return Value:

The DeleteCaseResponse object with the following structure:

object DeleteCase Response ( object processes ( [0]array ( object DeleteCaseStruct ( [string status_code] [int message] [string time_stamp] ) ) ... ) )

Example:

 $client = new SoapClient('http://127.0.0.1/sysworkflow/en/classic/services/wsdl2');
$params = array(array('userid'=>'admin', 'password'=>'admin'));
$result = $client->__SoapCall('login', $params);
$sessionId = $result->message;
 
$params = array(array('sessionId'=>$sessionId, 'caseUid'=>@@APPLICATION));
 $result = $client->__SoapCall('DeleteCase', $params);
 if ($result->status_code == 0)
    print "$result->message\Case UID: $result->caseUid";  
 else
    print "Unable to delete case.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

processList()

processList() returns a list of the processes in the current workspace. For privileges to see the list, the logged-in user must have the PM_FACTORY permission in his/her role.

processListResponse processList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The processListResponse object with the following structure:

object processListResponse ( object processes ( [0]array ( object processListStruct ( [string guid] [string name] ) ) ... ) )

Where:

  • string guid: The process ID.
  • string name: The process name.

Example:

$params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('processList', $params);
 $processesArray = $result->processes;
 
 if ($processesArray != (object) NULL)
 {
    if (is_array($processesArray))
    {
        foreach ($processesArray as $process)
            print "Process name: $process->name, Process ID: $process->guid \n";
    }
    else
    {
        print "Process name: $processesArray->name, Process ID: $processesArray->guid \n";
    }
 }
 else
    print "Error: $processesArray->name \n";

taskList()

taskList() returns a list of the tasks to which the logged-in user is assigned (as either normal assignment or ad-hoc assignment).

taskListResponse taskList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The taskListResponse object with the following structure:

object taskListResponse ( object tasks ( [0]array ( object tasksListStruct ( [string guid] [string name] ) ) ... ) )

If the user has no assigned tasks, then taskList() returns an empty stdClass, which is equivalent to (object) NULL. To avoid errors, check whether the return object equals (object) NULL.

Example:

 $params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('taskList', $params);
 $tasksArray = $result->tasks;
 if ($tasksArray != (object) NULL)
      foreach ($tasksArray as $task)
           print "Task name: $task->name, Task ID: $task->guid \n";
 else
      print "There are zero tasks assigned to this user. \n";

taskCase()

taskCase() returns the current task for a given case. Note that the logged-in user must have privileges to access the case.

taskCaseResponse taskCase(string sessionId, string caseId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case ID. The caseList() function can be used to find the ID number for cases.

Return value:

A taskCaseResponse object with the structure:

object taskCaseResponse ( object taskCases ( object taskCaseStruct ( [string guid] [string name] ) ) )

Where:

  • string guid: The ID of the current task.
  • string name: The name of the current task.

If there is no current task or the user doesn't have privileges to access the current task, an empty stdClass will be returned, which is equivalent to (object) NULL. To avoid errors check whether the returned taskCaseResponse is equal to (object) NULL.

Example:

 $params = array(array('sessionId'=>$sessionId, 'caseId'=>$caseId));
 $result = $client->__SoapCall('taskCase', $params);
 if ($result != (object) NULL)
      print "Task name: {$result->taskCases->name}, Task ID: {$result->taskCases->guid} \n";
 else
      print "No task or unable to access task. \n";

caseList()

caseList() returns a list of the cases for the logged-in user.

caseListResponse caseList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The caseListResponse object with the following structure:

object caseListResponse ( object cases ( [0]array ( object caseListStruct ( [string guid] [string name] [string status] [string delIndex] [string processId] ) ) ... ) )

Where:

  • string guid: The case unique ID.
  • string name: The case name.
  • string status: The status of the case. Possible values include 'TO_DO', 'DRAFT', 'COMPLETED', 'PAUSED' and 'CANCELED'.
  • int delIndex: The delegation index, which is a positive integer to identify the current task of the case. The first task is 1, the second task is 2, etc.
  • int processId: The process Id, which is a positive integer to identify the process id of the case which belongs to. Available form version 2.0.46

If the user has no cases, then caseList() returns an empty stdClass, which is equivalent to (object) NULL. To avoid errors, check whether whether the return object equals (object) NULL.

Example:

 $params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('caseList', $params);
 $casesArray = $result->cases;
 if ($casesArray != (object) NULL)
      foreach ($casesArray as $case)
           print "Case name: $case->name, Case ID: $case->guid, Status: $case->status \n";
 else
      print "There are zero cases. \n";

unassignedCaseList()

unassignedCaseList() returns a list of the unassigned cases which the logged-in user has rights to be assigned to. Available from version 2.0.36.

unassignedCaseListResponse unassignedCaseList(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.

Return value:

The unassignedCaseListResponse object with the following structure:

object unassignedCaseListResponse ( object cases ( [0]array ( object unassignedCaseListStruct ( [string guid] [string name] [string delIndex] ) ) ... ) )

Where:

  • string guid: The case unique ID.
  • string name: The case title.
  • int delIndex: The delegation index, which is a positive integer to identify the current task of the case. The first task is 1, the second task is 2, etc.

If the user has no unassigned cases, then unassignedCaseList() returns an empty stdClass, which is equivalent to (object) NULL. To avoid errors, check whether whether the return object equals (object) NULL.

Example:

$params = array(array('sessionId'=>$sessionId));
 $result = $client->__SoapCall('unassignedCaseList', $params);
 $casesArray = $result->cases;
 if ($casesArray != (object) NULL) {
    foreach ($casesArray as $case) {
       print "Case name: $case->name, Case ID: $case->guid \n";
    }
 }
 else  
    print "There are zero unassigned cases.\n";

getCaseInfo()

getCaseInfo() returns information about a given case (as long as the logged in user has privileges to access the case).

getCaseInfoResponse getCaseInfo(string sessionId, string caseId, string delIndex)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case ID, which can be obtained with the caseList() function.
  • string delIndex: The delegation index, which is a positive integer to identify the current task of the case. The first task is 1, the second task is 2, etc. This number can be obtained with the caseList() function.

Return value:

If using version 1.2-2740 or later, then getCaseInfo() returns a getCaseInfoResponse object with the following structure:

object getCaseInfoResponse ( [integer status_code] [string message] [string caseId] [string caseNumber] [string caseName] [string caseStatus] [string caseParalell] [string caseCreatorUser] [string caseCreatorUserName] [string processId] [string processName] [string createDate] [object currentUsers] ( [0]array ( object getCaseInfoStruct ( [string userId] [string userName] [string taskId] [string taskName] [integer delIndex] [integer delThread] [string delThreadStatus] ) ) ... ) )

Example:

 $params = array(array('sessionId'=>$sessionId, 'caseId'=>'9636840824a76fab5df5714036136565',
     'delIndex'=>'3'));
 $result = $client->__SoapCall('getCaseInfo', $params);
 if ($result->status_code == 0)
      print "Case ID: $result->caseId, Current UserID: $result->caseCurrentUser \n";
 else
      print "Error: $result->message \n";

getVariablesNames()

Available Version: 2.5

getVariablesNames() get all variables the system and case selected.

GetVariableResponse getVariablesNames (string caseID)

Parameters:

  • string caseId: The unique ID of the case.

Return value:

A GetVariableResponse object with the following structure: array

( [0] ( object variableStruct ( [string name] ) ) [1] ( object variableStruct ( [string name] ) ) ... )

Return value:

A variableListResponse object, with the structure:

object variableListResponse ( [integer status_code] [string message] [string timestamp] object variables ( array ( [0] ( object variableListStruct ( [string name] [string value] ) ) [1] ( object variableListStruct ( [string name] [string value] ) ) ... ) ) )

Example:

$params = array(array('sessionId'=>$sessionId, 'caseId'=>@@APPLICATION))
 $result = $client->__SoapCall('getVariablesNames', $params);
 if ($result->status_code == 0)
    print "$result->message\Case Id: $result->caseId";  
 else
    print "Unable to get variables.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";
var_dump($result);
$result->variables;

newCase()

newCase() begins a new case under the name of the logged-in user.

newCaseResponse newCase(string sessionId, string processId, string taskId, array variables)

Parameters:

  • string sessionId: The ID of the session, which is obtained during login.
  • string processId: The ID of the process where the case should start, which can be obtained with processList().
  • string taskId: The ID of the task where the case should start, which will generally be the first task in a process. The task ID can be obtained with taskList(). Remember that the logged-in user must be assigned to this task (either normal assignment or ad-hoc assignment); otherwise, use newCaseImpersonate() to start the case.
  • array variables: An array of variables can be sent to the case when it starts, so it automatically sets the values of case variables (and DynaForm fields). It is an array ofvariableStruct objects which has the following format:
[0]array ( object variableStruct ( [string name] [string value] ) ) ...

If not wishing to set any case variables, then pass an empty array: array()

Return value:

A newCaseResponse object, with the structure:

newCaseResponse ( [integer status_code] [string message] [string caseId] [string caseNumber] [string timestamp] )

If an error occurred, status_code will contain a non-zero error number and the message will hold the error message.

Example:

 # Script to create a new case for the "Credit Card Application" process,
# which is available for download at http://library.processmaker.com
class variableStruct {
   public $name;
   public $value;
 }
 $name = new variableStruct();
 $vars = array('APPLICANT_NAME'=>'John', 'APPLICANT_LAST'=>'Doe',
     'APPLICANT_ID'=>'123456', 'APPLICANT_EMAIL'=>'johndoe@example.com',
     '$APPLICANT_EMPLOYER'=>'Example Corp, Inc.');
 $aVars = array();
 foreach ($vars as $key => $val)
 {
      $obj = new variableStruct();
      $obj->name = $key;
      $obj->value = $val;
      $aVars[] = $obj;   
 }
 
 # Use the functions processList() and taskList() to look up the IDs for the
# process and its first task.
$params = array(array('sessionId'=>$sessionId, 'processId'=>'447CEAF7BE6AEB',
     'taskId'=>'347CEB10B72D11', 'variables'=>$aVars));
 $result = $client->__SoapCall('newCase', $params);
 if ($result->status_code == 0)
      print "New case ID: $result->caseId, Case No: $result->caseNumber \n";
 else
      print "Error creating case: $result->message \n";

Note: The status of the new case will be set to "DRAFT", not "TO_DO" after being created. To get around this problem, create a trigger with the following code:

$caseId = @@APPLICATION;
executeQuery("UPDATE APPLICATION SET APP_STATUS='TO_DO' WHERE APP_UID='$caseId' AND APP_STATUS='DRAFT'");

Then call executeTrigger() to fire the above trigger after creating the case with newCase().

newCaseImpersonate()

newCaseImpersonate() creates a new case impersonating a user who has the proper privileges to create new cases. Use this function to allow any user to initiate new cases. Note that the new case's status will be set to "DRAFT", not "TO_DO". See the above workaround.

pmResponse newCaseImpersonate(string sessionId, string processId, string userId, array variables)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string processId: The ID of the process where the case should start, which can be obtained with processList().
  • string userId: The ID of the user who initiates the case, which can be obtained with userList().
  • array variables: An array of variableStruct objects which contain data to start the case. This array has the following format:
[0]array ( object variableStruct ( [string name] [string value] ) ) ...

Return value:

A pmResponse object.

reassignCase()

reassignCase() reassigns a case to a different user. Note that the logged-in user needs to have the PM_REASSIGNCASE permission in his/her role in order to be able to reassign the case.

pmResponse reassignCase(string sessionId, string caseId, string delIndex, string userIdSource, string userIdTarget)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case ID, which can be obtained with the caseList() function or by by querying the wf_<WORKSPACE>.APP_DELEGATION.APP_UID field in the database.
  • string delIndex: The current delegation index number of the case, which can be obtained with the caseList() function or by querying thewf_<WORKSPACE>.APP_DELEGATION.DEL_INDEX field in the database.
  • string userIdSource: The user who is currently assigned the case, which can be obtained with the caseList() function.
  • string userIdTarget: The target user who will be newly assigned to the case, which can be obtained with userList(). The case can only be reassigned to a user who is one of theassigned users or ad-hoc users to the current task in the case.

Return value:

A pmResponse object.

routeCase()

routeCase() routes a case (i.e., moves the case to the next task in the process according to its routing rules).

routeCaseResponse routeCase(string sessionId, string caseId, string delIndex)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case ID, which can be obtained with the caseList() web service or by examining the wf_<WORKSPACE>.APP_DELEGATION.APP_UID field in the database.
  • string delIndex: The delegation index number for the case, which can be obtained with the caseList() web service or by examining the wf_<WORKSPACE>.APP_DELEGATION.DEL_INDEXfield in the database.

Return value:

Returns a routeCaseResponse object with the following structure:

object routeCaseResponse ( [integer status_code] [string message] [string timestamp] object routing ( [0] array ( object routeListStruct ( [string userId] [string userName] [string taskId] [string taskName] [integer delIndex] [integer delThread] [string delThreadStatus] ) ) ... ) )

Considerations:

  • If routeCase() returns error number 22 ("Task does not have a derivation rule, check process definition"), the routing rule which follows the current task probably contains a condition with a case variable which has not been defined. If a case variable was defined by a DynaForm and the DynaForm was never displayed, then the case variable won't be created. In this case, you will have to use the sendVariables() function to send the case variable to the case so it can be used in the routing rule.
  • If routeCase() returns error number 18 ("This delegation is already closed or does not exist"), either the case ID is wrong (or the user doesn't have privileges to route the case) or using a delegation index from a previous task which has already been completed. Remember that a new delegation index is assigned every time a case is routed to another task. Use caseList() to find the current delIndex for the case before calling routeCase().
  • routeCase executes only on before derivation and after derivation triggers; before assignment triggers do not execute, because on the web services there isn't an equivalent on the assignation screen .

Example:

 #Use caseList() to get the caseId and delIndex.
$params = array(array('sessionId'=>$sessionId,
     'caseId'=>'3291015624a7c9d85b71b21074133813', 'delIndex'=>'1'));
 $result = $client->__SoapCall('routeCase', $params);
 if ($result->status_code == 0)
      print "Case routed: $result->message \n";
 else
      print "Error routing case: $result->message \n";

AddCaseNote()

AddCaseNote() creates a case note

AddCaseNoteResponse AddCaseNote(string caseUid, string processUid, string taskUid, string userUid, string note, int sendMail = 1)

Parameters:

  • string caseId: The case ID, which can be obtained with the caseList() web service or by examining the wf_<WORKSPACE>.APP_DELEGATION.APP_UID field in the database.
  • string processUid: The ID of the process where the case should start, which can be obtained with processList().
  • string taskUid: The ID of task where the case note will be created.
  • string userUid: The ID of the user who is owner of the task where the case note will be created. This ID can be obtained with userList().
  • string note: content of the note to be created.
  • int sendMail: Optional parameter. If set to 1, will send an email to all participants in the case.

Return value:

Returns a AddCaseNoteResponse object with the following structure:

object routeCaseResponse ( [integer status_code] [string message] [string timestamp] ( [0] array ( object AddCaseNoteStruct ( [string sessionId] [string caseUid] [string processUid] [string taskUid] [string userUid] [string note] [integer sendMail] ) ) ... ) )

If AddCaseNote() response returns 1 en email has been sent indicating the note has been creating, on the contrary 0 if not.

Example

$client = new SoapClient('http://127.0.0.1/sysworkflow/en/classic/services/wsdl2');
$params = array(array('userid'=>'admin', 'password'=>'admin'));
$result = $client->__SoapCall('login', $params);
$sessionId = $result->message;
 
$params = array(array('sessionId'=>$sessionId, 'caseUid'=>@@APPLICATION, 'processUid'=>@@PROCESS, 'taskUid' => @@TASK,
 'userUid' => '00000000000000000000000000000001', 'note' => 'Case Note's Example', 'sendMail' => '1'));
 $result = $client->__SoapCall('
AddCaseNote', $params);
 if ($result->status_code == 0)
    print "$result->message\Case UID: $result->caseUid";  
 else
    print "Unable to create a case note.\nError Number: $result->status_code\n" .
          "Error Message: $result->message\n";

getVariables()

getVariables() returns variables from a given case. The variables can be system variables and/or case variables.

variableListResponse getVariables(string sessionId, string caseId, array variables)

Parameters:

  • string sessionId: The session ID, which is obtained during the login.
  • string caseId: The ID of the case, which provides the variable values. This ID can be obtained with caseList().
  • array variables: An array of variableStruct objects, which hold the names of the variables which will be returned. The array has the following structure:
array ( [0] ( object variableStruct ( [string name] ) ) [1] ( object variableStruct ( [string name] ) ) ... )

Return value:

A variableListResponse object, with the structure:

object variableListResponse ( [integer status_code] [string message] [string timestamp] object variables ( array ( [0] ( object variableListStruct ( [string name] [string value] ) ) [1] ( object variableListStruct ( [string name] [string value] ) ) ... ) ) )

If the variables don't exist or it an error occurred, the object variables will be an empty stdClass, which is equal to (object)NULL. To avoid errors, check that variables does not equal(object)NULL.

Note 1: All value's will be returned as strings, so they may need to be converted to other variable types, such as int, float, boolean, etc. If passing complex data types, such as objects or arrays, then fire a trigger beforehand to convert them into serialized strings with serialize() or json_encode() before calling the getVariables() web service. See Variable Type Conversion and the example below.

Note 2: Due to this bug, getVariables() cannot retrieve only one variable. It must retrieve at least 2 variables. If needing only one variable, include a second variable in the variablesarray.

Example:

 class variableStruct {
   public $name;
 }
 
 $p = new variableStruct();
 $p->name = 'clientName';     //a case variable
 $s = new variableStruct();
 $s->name = 'SYS_LANG';       //a system variable
 $variables = array($p, $s);
 $params = array(array('sessionId'=>$sessionId, 'caseId'=>'3188781734a71c99e356809057266790',
     'variables'=>$variables));
 $result = $client->__SoapCall('getVariables', $params);
 if ($result->status_code == 0 && $result->variables != (object) NULL)
 {
      $variablesArray = $result->variables;
      foreach ($variablesArray as $variable)
           print "Variable name: $variable->name, Value: $variable->value \n";
 }

It is possible to dynamically construct the array of $variables, based upon an array. The following code would do the same as the example above:

 class variableStruct {
     public $name;
 }
 $vars = array('clientName', 'SYS_LANG');  
 $variables = array();
 foreach ($vars as $var)
 {
    $obj = new variableStruct();
    $obj->name = $var;
    $variables[] = $obj;         
 }
 $params = array(array('sessionId'=>$sessionId, 'caseId'=>'3188781734a71c99e356809057266790',
     'variables'=>$variables));
 $result = $client->__SoapCall('getVariables', $params);
 if ($result->status_code == 0 && $result->variables != (object) NULL)
 {
      $variablesArray = $result->variables;
      foreach ($variablesArray as $variable)
           print "Variable name: $variable->name, Value: $variable->value \n";
 }

To get a grid from ProcessMaker, which is stored as an associative array of associative arrays, it first must be converted to a serialized string, so it can returned as a string bygetVariables(). Create a trigger in ProcessMaker to convert the string. For example:

 @@MyGridSerialized = serialize(@=MyGrid);

Before calling the getVariables() web service, first call the executeTrigger() to convert the grid to a serialized string. After receiving the string, convert it into an associative array of associative arrays with the unserialize() function.

sendVariables()

sendVariables() sends variables to a case.

pmResponse sendVariables(string sessionId, string caseId, array variables)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case ID, which can be obtained with caseList() or by querying the wf_<WORKSPACE>.APPLICATION.APP_UID field in the database.
  • array variables: An array of variableListStruct objects that contains the variable names and their values to be sent. This array has the following format:
array ( [0] ( object variableListStruct ( [string name] [string value] ) ) [1] ( object variableListStruct ( [string name] [string value] ) ) ... )

Return value:

A pmResponse object. If successful, the message will indicate how many variables have been received; otherwise, it will contain an error message.

Example:

 class variableListStruct {
     public $name;
     public $value;
 }
 
 $position = new variableListStruct();
 $position->name = "position";
 $position->value = "manager";
 
 $salary = new variableListStruct();
 $salary->name = "salary";
 $salary->value = 3896.78;
 
 $startdate = new variableListStruct();
 $startdate->name = "startdate";
 $startdate->value = "2009-08-20";
 
 $variables = array($position, $salary, $startdate);
 $params = array(array('sessionId'=>$sessionId, 'caseId'=>$caseId, 'variables'=>$variables));
 $result = $client->__SoapCall('sendVariables', $params);
 if ($result->status_code != 0)
     print "Error: $result->message \n";

It is possible to dynamically construct the array of $variables, based upon an associative array. The following code would do the same as the example above:

class variableListStruct {
     public $name;
     public $value;
 }
 $vars = array('position'=>'manager', 'salary'=>3896.78, 'startdate'=>'2009-08-20');  
 $variables = array();
 foreach ($vars as $key => $val)
 {
    $obj = new variableListStruct();
    $obj->name = $key;
    $obj->value = $val;
    $variables[] = $obj;         
 }
 $params = array(array('sessionId'=>$sessionId, 'caseId'=>$caseId, 'variables'=>$variables));
 $result = $client->__SoapCall('sendVariables', $params);
 if ($result->status_code != 0)
     print "Error: $result->message \n";

Variable Type Conversion

All variable values are send as strings. In most cases, ProcessMaker will gracefully convert these string values to one of the other basic PHP data types (int, float or boolean) when needed in the process. If this doesn't occur, it may be necessary to use executeTrigger() to fire a trigger afterward which will convert the data. For example, it might be necessary to execute this trigger after sending the "salary" variable:

 @=salary = (float)@@salary; //explicit conversion

or:

 @=salary = @#salary; //convert with ProcessMaker case variable data typing

Complex data types
If sending a complex data type such as an array or an object, it is best to pass the variable as a serialized string, then use executeTrigger() to fire a trigger which will unserialize the object and assign it to a case variable.

For example, if sending this $employees associative array of associative arrays (which is how grids are stored in ProcessMaker):

$employees = array(
    '1' => array("position"=>"manager",      "salary"=>4000.00, "startdate"=>"2009-08-20"),
    '2' => array("position"=>"receptionist", "salary"=>2000.00, "startdate"=>"2007-12-01"),
    '3' => array("position"=>"grunt",        "salary"=>2500.00, "startdate"=>"2005-03-18")
 );

First, create the following Trigger in the process which will convert a serialized string into an associative array of associative arrays:

 @=EmployeesGrid = unserialize(@@EmployeesGrid);

Then, create the web service script which uses PHP's serialize() function when passing the $employees array to the case with sendVariables(). After sending the grid data to the case, then use executeTrigger() to call the trigger which will unserialize @@EmployeesGrid and convert it into an associative array of associative arrays:

 $employees = array(
    '1' => array("position"=>"manager",      "salary"=>4000.00, "startdate"=>"2009-08-20"),
    '2' => array("position"=>"receptionist", "salary"=>2000.00, "startdate"=>"2007-12-01"),
    '3' => array("position"=>"grunt",        "salary"=>2500.00, "startdate"=>"2005-03-18")
 );
 class variableStruct {
     public $name;
     public $value;
 }
 $v = new variableStruct();
 $v->name = "EmployeesGrid";
 $v->value = serialize($employees);
 
 $variables = array($v);
 $params = array(array('sessionId'=>$sessionId, 'caseId'=>$caseId, 'variables'=>$v));
 $result = $client->__SoapCall('sendVariables', $params);
 if ($result->status_code != 0)
     print "Error: $result->message \n";
 #look up the caseId and delIndex with caseList() and the triggerIndex with triggerList():
$params = array(array('sessionId'=>$sessionId, 'caseId'=>'$caseId',
       'triggerIndex'=>'3126831054a7dd8781e84a7046772575','delIndex'=>'1'));
 $result = $client->__SoapCall('executeTrigger', $params);
 if ($result->status_code != 0)
      print "Error: $result->message \n";

A subsequent DynaForm which has a grid object named "EmployeesGrid" can then display the data in a grid.

Other Programming Languages

If using a different programming language which doesn't support the serialize() function, then encode objects and arrays as JSON strings, before passing them to the sendVariables()web service. See this list of JSON encoders/decoders for different languages. After sending the variables, then call the executeTrigger() web service to decode the object or array in a ProcessMaker trigger with json_decode().

If sending associative arrays, note that they will be encoded in JSON as objects. To pass a grid (an associative array of associative arrays) to ProcessMaker with JSON, it in necessary to convert the objects to associative arrays in a trigger before trying to display them in a DynaForm grid. For example, this trigger code would decode the JSON string with the json_decode()function and then convert the object to an associative array of associative arrays which can be displayed in a grid:

 $aGrid = (array) json_decode(@@EmployeesGrid);
 @=EmployeesGrid = array();
 foreach ($aGrid as $rowNo=>$row) {
    @=EmployeesGrid[$rowNo] = (array) $row;
 }

triggerList()

triggerList() returns a list of all the available triggers in a workspace. (Available from version 1.2-2740 on.)

  triggerListResponse <strong>triggerList</strong>(<i>string</i> sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained at login.

Return value:

A triggerListResponse object, with the following structure:

[0] array ( object triggerListStruct ( [string guid] [string name] [string processId] ) ) ...

executeTrigger()

executeTrigger() executes a ProcessMaker trigger. Note that triggers which are tied to case derivation will executing automatically, so this function does not need to be called when deriving cases.

pmResponse executeTrigger(string sessionId, string caseId, string triggerIndex, string delIndex)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case ID, which is can be found with caseList().
  • string triggerIndex: The ID of the trigger to execute, which can be found with triggerList().
  • string delIndex: The delegation index number of the case, which can be found with caseList().

Return value:

A pmResponse object. If successful, the message will contain "executed: <TRIGGER_CODE>".

Note: The triggerIndex can be looked up with the triggerList() function if using version 1.2-2740 or later. For prior versions, the triggerIndex will have to be looked up in thewf_<WORKSPACE>.CONTENT table in MySQL:

C:\Program Files\ProcessMaker\mysql\bin> mysql -u root -p Enter password: ******** mysql> select con_value, con_id from wf_workflow.content where (con_category = 'TRI_TITLE'); +----------------------------+----------------------------------+ | con_value | con_id | +----------------------------+----------------------------------+ | updateAddinHistory | 10768559548a5cc2e0fbe52053131576 | | setRepFinalDec | 11249313348d67d3d7862a3048595231 | | getIssueDate | 11696570848a596568ee996042105082 | | setStatusOnHold | 16522080448a5f47eed5b21029801136 | | ws3 | 17763769948e29e195dff45029465358 | | ws2 | 21947161648e29de1ba6239054599761 | | getDateAddIn | 23391845548a5cc9a238ee9056072477 | | GET DATE | 247CEBDB202DE0 | | UpdateBugComments | 25994873048a8e0b157bd28002964410 | | getCaseNumber | 28138323548a5e9c5acbb13018874573 | | Hello World | 306900500490b24cc8fdd71038114427 | ...

Once the trigger ID is known, the code for a particular trigger can also be looked up in the wf_<WORKSPACE>.TRIGGERS table:

mysql> select tri_uid, tri_webbot from wf_workflow.triggers where tri_uid = '306900500490b24cc8fdd71038114427'; +----------------------------------+------------------------------------+ | tri_uid | tri_webbot | +----------------------------------+------------------------------------+ | 306900500490b24cc8fdd71038114427 | @@HELLO='Hello World of '.@@name; | +----------------------------------+------------------------------------+

Example:

 #look up the caseId and delIndex with the caseList() web service and the triggerIndex in MySQL
$params = array(array('sessionId'=>$sessionId, 'caseId'=>'9782409664a7c94433d0920003544388',
       'triggerIndex'=>'3126831054a7dd8781e84a7046772575','delIndex'=>'1'));
 $result = $client->__SoapCall('executeTrigger', $params);
 if ($result->status_code != 0)
      print "Error: $result->message \n";

sendMessage()

sendMessage() sends an email with the provided data. Note that ProcessMaker must be properly configured to send email for this option to work.

pmResponse sendMessage(string sessionId, string caseId, string from, string to, string cc, string bcc, string subject, string template)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case ID, which can be found with caseList().
  • string from: The email address of the sender.
  • string to: A list of email addresses (separated by commas) to receive the email.
  • string cc: A list of email addresses (separated by commas) to receive carbon copies of the email.
  • string bcc: A list of email addresses (separated by commas) to receive blind carbon copies of the email.
  • string subject: The subject line of the email.
  • string template: The file containing the body of the email. The file should be placed in the shared/sites/<WORKSPACE>/mailTemplates/<PROCESS_ID> directory. See HTML Notification Templates for more information on how to make an HTML template file containing variables.

Return value:

A pmResponse object. If unable to locate the template file for the email, the error message in the pmResponse will indicate the path where ProcessMaker is searching for the file. Check this error message to find where to save the email template file.

Example:

$params = array(array("sessionId"=>$sessionId, "caseId"=>"3188781734a71c99e356809057266790",
     "from"=>"support@colosa.com", "to"=>"joe@example.com, jane@example.com", "cc"=>"", "bcc"=>"",
     "subject"=>"Contact Information", "template"=>"mail-body.txt"));
 $result = $client->__SoapCall('sendMessage', $params);
 if ($result->status_code != 0)
     print "Email error: $result->message \n";

systemInformation()

systemInformation() returns information about the WAMP/LAMP stack, the workspace database, the IP number and version of ProcessMaker, and the IP number and version of web browser of the user. (Available from version 1.2-2740 on.)

systemInformationResponse systemInformation(string sessionId)

Parameters:

  • string sessionId: The session ID, which was obtained at login.

Return value:

A systemInformationResponse object with the following structure:

object systemInformationResponse ( [integer status_code] [string message] [string timestamp] [string version] [string operatingSystem] [string webServer] [string serverName] [string serverIp] [string phpVersion] [string databaseVersion] [string databaseServerIp] [string databaseName] [string availableDatabases] [string userBrowser] [string userIp] }

importProcessFromLibrary()

importProcessFromLibrary() downloads and imports a process from the ProcessMaker library. Available from version 1.2-2741 and later.

importProcessFromLibraryResponse importProcessFromLibrary(string sessionId, string processId, string version, string importOption, string usernameLibrary, string passwordLibrary)

Parameters:

  • string sessionId: The session ID, which was obtained at login.
  • string processId: The unique ID for the process.
  • string version: The version number.
  • string importOption: Any options.
  • string usernameLibrary: The username to obtain access to the ProcessMaker library.
  • string passwordLibrary: The password to obtain access to the ProcessMaker library.

Return value:

An importProcessFromLibraryResponse object with the following structure:

object importProcessFromLibraryResponse ( [integer status_code] [string message] [string processId] [string processTitle] [string category] [string version] )

inputDocumentList()

inputDocumentList() returns a list of the uploaded documents for a given case. Available from version 1.2-3104 and later.

inputDocumentListResponse inputDocumentList(string sessionId, string caseId)

Parameters:

  • string sessionId: The session ID, which was obtained during login.
  • string caseId: The case unique ID, which can be obtained with the caseList() web service.

Return value:

The inputDocumentListResponse object with the following structure:

object inputDocumentListResponse ( object cases ( [0]array ( object caseListStruct ( [string guid] [string filename] [string docId] [integer version] [string createDate] [string createBy] [string type] [integer index] [string link] ) ... ) )

Where:

  • string guid: The uploaded document unique ID (appDocUid). Everytime a new document is uploaded, a UID is assigned.
  • string filename: The uploaded document name.
  • string docId: Corresponds to input document object unique ID, which is assigned during the process design.
  • integer version: The uploaded document version.
  • string createDate: The date and time when the document was created.
  • string createdBy: The user name, who uploaded the document.
  • string type: The type of the document.
  • integer index