Please rate how useful you found this document: 
Average: 3 (4 votes)

Overview

The following are the REST endpoints available for the Administration section of the ProcessMaker REST API 1.0:

All these endpoints and their methods are explained below.

Contents: [hide]
  1. Overview
  2. Users
    1. Get Users List: GET /users
    2. Get User Information: GET /user/{usr_uid}
    3. Create User: POST /user
    4. Upload User Image: POST /user/{usr_uid}/image-upload
    5. Update User Information: PUT /user/{usr_uid}
    6. Delete User: DELETE /user/{usr_uid}
  3. Groups
    1. Get Groups List: GET /groups
    2. Get Group Information: GET /group/{grp_uid}
    3. Create Group: POST /group
    4. Update Group: PUT /group/{usr_uid}
    5. Delete Group: DELETE /group/{grp_uid}
    6. Get Group Members: GET /group/{grp_uid}/users
    7. Get Available Users: GET /group/{grp_uid}/available-users
    8. Assign User to Group: POST /group/{grp_uid}/user
    9. Unassign User from Group: DELETE /group/{grp_uid}/user/{usr_uid}
  4. Departments
    1. Get Departments List: GET /departments
    2. Get Department Information: GET /department/{dep_uid}
    3. Create Department: POST /department
    4. Update Department: PUT /department/{dep_uid}
    5. Delete Department: DELETE /department/{dep_uid}
    6. Get Users List for Department: GET /department/{dep_uid}/assigned-user
    7. Available Users List for Department: GET /department/{dep_uid}/available-user
    8. v.2.8: Assign User to Department: PUT /department/{dep_uid}/assign-user/{usr_uid}
    9. v.3.0+: Assign User to Department: POST /department/{dep_uid}/assign-user
    10. Unassign User from Department: PUT /department/{dep_uid}/unassign-user/{usr_uid}
    11. Set Manager for Department: PUT /department/{dep_uid}/set-manager/{usr_uid}
  5. Roles
    1. Get Roles List: GET /roles
    2. Get Role Information: GET /role/{rol_uid}
    3. Create Role: POST /role
    4. Update Role: PUT /role/{rol_uid}
    5. Delete Role: DELETE /role/{rol_uid}
    6. Get Users with Role: GET /role/{rol_uid}/users
    7. Available Users for Role: GET /role/{rol_uid}/available-users
    8. Assign User to Role: POST /role/{rol_uid}/user
    9. Unassign User from Role: DELETE /role/{rol_uid}/user/{usr_uid}
    10. Permissions List for Role: GET /role/{rol_uid}/permissions
    11. Available Permissions for Role: GET /role/{rol_uid}/available-permissions
    12. Assign Permission to Role: POST /role/{rol_uid}/permission
    13. Unassign Permission from Role: DELETE /role/{rol_uid}/permission/{per_uid}
  6. PM Tables
    1. PM Tables List: GET /pmtable
    2. Get PM Table Structure: GET /pmtable/{pmt_uid}
    3. Get PM Table Data: GET /pmtable/{pmt_uid}/data
    4. Create PM Table: POST /pmtable
    5. Add PM Table Data: POST /pmtable/{pmt_uid}/data
    6. Update PM Table Structure: PUT /pmtable/{pmt_uid}
    7. Update PM Table Data: PUT /pmtable/{pmt_uid}/data
    8. Delete PM Table: DELETE /pmtable/{pmt_uid}
    9. Delete PM Table Data: DELETE /pmtable/{pmt_uid}/data/...
  7. Categories
    1. Get Categories List: GET /project/categories
    2. Get Category Information: GET /project/category/{cat_uid}
    3. Create Category: POST /project/category
    4. Update Category: PUT /project/category/{cat_uid}
    5. Delete Category: DELETE /project/category/{cat_uid}
  8. Calendars
    1. Get Calendar List: GET /calendars
    2. Get Calendar Information: GET /calendar/{cal_uid}
    3. Create Calendar: POST /calendar
    4. Update Calendar: PUT /calendar/{cal_uid}
    5. Delete Calendar: DELETE /calendar/{cal_uid}

Users

The following REST endpoints are used to manage users in ProcessMaker.

1. Get the list of all users

2. Get information of a specific user

3. Create user

4. Upload an image for a user

5. Update the information of a user

6. Delete user

Available methods:

Get Users List: GET /users

Returns a list of all users in the workspace, including users with "INACTIVE" and "VACATION" status. The users are returned in the order which they appear in the wf_<WORKSPACE>.USERS table.

GET /api/1.0/{workspace}/users?filter={filter}&start={start}&limit={limit}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

Optional GET Parameters:

NameTypeDescription
filterstringCase insensitive string to search for in the user's first name, last name or username.
For example, "api/1.0/workspace/users?filter=mit" would return the users "smith", "Mitter" and "solmit".
startintegerThe number of users where the list begins. The counting starts from number 0, which is always the "admin" user.
For example, "api/1.0/workspace/users?start=3" would start the list of users with the fourth user.
limitintegerThe maximum number of users which are returned in the list.
For example if wanting to return 10 users at a time and there are 25 users in total, then call this endpoint 3 times:
"api/1.0/workspace/users?limit=10" (returns users 0-9)
"api/1.0/workspace/users?start=10&limit=10" (returns users 10-19)
"api/1.0/workspace/users?start=20&limit=10" (returns users 20-24)


Result:

If a successful request, the HTTP status code is 200 and it returns a JSON array of user objects with the following structure:

ElementDescriptionExample
[Start array
{Start user object
"usr_uid"User's unique ID."11826545154db794ca22b52025081429"
"usr_username"The username, which is unique and is used to login to ProcessMaker"jdoe"
"usr_password"The MD5 hash for the user's password."21232f297a57a5a743894a0e4a801fc3"
"usr_firstname"The user's first name."John Jake"
"usr_lastname"The user's last name."Doe"
"usr_email"The user's email address."jdoe@example.com"
"usr_due_date"The date in "YYYY-MM-DD" when the user's account will expire. After this date, the user will not be able to login to ProcessMaker."2020-01-01"
"usr_create_date"The datatime in "YYYY-MM-DD HH:MM:SS" format when the user was created."2005-11-30 08:11:57"
"usr_update_date"The datetime in "YYYY-MM-DD HH:MM:SS" format when the user's record was last updated."2014-05-23 18:36:19"
"usr_status"The user's status, which can be "ACTIVE", "INACTIVE" or "VACATION""ACTIVE"
"usr_country"Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database."US" (United States)
"usr_city"One or two letter code to identify the region, state or province.

Note: This field is misnamed. See the wf_<WORKSPACE>.ISO_SUBDIVISION table in the database.

"FL" (Florida in the US)
"usr_location"Code which is 1 to 3 letters to identify the city or locality. See the wf_<WORKSPACE>.ISO_LOCATION table in the database."MMK" (Miami Lakes in Florida)
"usr_address"The user's address. This field may contain line breaks (\n)."540 Mytle Lane"
"usr_phone"The user's phone number."1-305-402-1234"
"usr_fax"The user's fax number."1-305-402-0282"
"usr_cellular"The user's cellular telephone number."1-305-675-1400"
"usr_zip_code"The user's zip or postal code"46135"
"dep_uid"The unique ID of the user's department. If the user isn't a member of a department then an empty string ""."54883398754db7993002ae1030708956"
"usr_position"The user's position."Accountant"
"usr_resume"Always set to "" since the resume is no longer used.""
"usr_birthday"The user's birthday in "YYYY-MM-DD" format."1973-02-25"
"usr_role"The user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role."PROCESSMAKER_ADMIN"
"usr_reports_to"The unique ID of the manager to whom the user reports. This is used when using a Reports To assignment rule. If the user is not a member of a department, then an empty string ""."14680180454ca4477335a27034362107"
"usr_replaced_by"Unique ID of another user who will replace this user if status changes to "INACTIVE" or "VACATION". Set to empty string "" if there is no replacement user."14680180454ca4477335a27034362107"
"usr_ux"The user experience, which is the type of interface seen by the user. It can be "NORMAL", "SWITCHABLE", "MOBILE" or "SINGLE"."NORMAL"
},End user object.
...Additional user objects.
]End array.

If a bad request, than the HTTP status code is set to 400 or greater and it returns a JSON error object.

Example in JavaScript:
This JavaScript example creates a array of active users. It obtains the list of all the users for the workspace and stores it in an array named aUsers. Then it loops through the array and checks whether the user's status is "ACTIVE". If so, it adds the user's UID and username to an new array named aActiveUsers.

var accessToken = getCookie("access_token"); //custom function to get a stored cookie
if (!accessToken) {
   accessToken = getAccessToken(); //custom function to get a new access token
}

var reqUsers = new XMLHttpRequest();
//set address to your installation of ProcessMaker:
reqUsers.open("GET", "https://example.com/api/1.0/workflow/users", true);
reqUsers.setRequestHeader("Authorization", "Bearer " + accessToken);
reqUsers.onreadystatechange = function() {
   if (reqUsers.readyState==4 &amp;&amp; reqUsers.status==200) {
      var aActiveUsers = [];
      var aUsers = JSON.parse(reqUsers.responseText);

      for (var i = 0; i < aUsers.length; i++) {
          if (aUsers[i].usr_status == "ACTIVE") {
              aActiveUsers.push({
                 uid:      aUsers[i].usr_uid,
                 username: aUsers[i].usr_username
              });
          }
      }
   }  
}
reqUsers.send(null);

Example in PHP:

This PHP example creates a array of active users. It obtains the list of all the users for the workspace and stores it in an array named $aUsers. Then it loops through the array and checks whether the user's status is "ACTIVE". If so, it adds the user's UID and username to an new array named $aActiveUsers.

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
$apiServer = "https://example.com"; //set to your ProcessMaker address

$ch = curl_init($apiServer . "/api/1.0/workflow/users");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aUsers = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
$aActiveUsers = array();
 
if ($statusCode != 200) {
   if (isset ($aUsers) and isset($aUsers->error))
      print "Error code: {$aUsers->error->code}\nMessage: {$aUsers->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
else {
   foreach ($aUsers as $oUser) {
      if ($oUser->usr_status == "ACTIVE") {
         $aActiveUsers[] = array("uid" => $oUser->usr_uid, "username" => $oUser->usr_username);
      }
   }
}

Get User Information: GET /user/{usr_uid}

Get information about a specified user.

GET /api/1.0/{workspace}/user/{usr_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
usr_uidStringUser UID

Result:

Returns the HTTP status code 200 and the same user object as the GET /users endpoint. For example:

{
  usr_uid:         "66065213554dd1feb48fe79020620851",
  usr_username:    "johndoe",
  usr_password:    "5e8ff9bf55ba3508199d22e984129be6",
  usr_firstname:   "John",
  usr_lastname:    "Doe",
  usr_email:       "janedoe@example.com",
  usr_due_date:    "2020-12-31",
  usr_create_date: "2015-02-12 16:49:31",
  usr_update_date: "2015-02-12 16:49:31",
  usr_status:      "ACTIVE",
  usr_country:     "US",
  usr_city:        "IN",
  usr_location:    "GXQ",
  usr_address:     "740 Turtle Dove lane",
  usr_phone:       "1-765-653-4478",
  usr_fax:         "1-765-862-8712",
  usr_cellular:    "1-755-644-8723",
  usr_zip_code:    "46135",
  dep_uid:         "75740355754dd28ba73d7d6082172936",
  usr_position:    "Factory Foreman",
  usr_resume:      "",
  usr_birthday:    "1980-02-12",
  usr_role:        "PROCESSMAKER_OPERATOR",
  usr_reports_to:  "14680180454ca4477335a27034362107",
  usr_replaced_by: "14680180454ca4477335a27034362107",
  usr_ux:          "NORMAL"
}

If a bad request, then it returns the HTTP status code 400 and an error object like the following:

{
  error: {
    code: 400,
    message: "Bad Request: invalid value specified for `usr_uid`. Given string is too short"
  }
}

Example in PHP:

$apiServer = "https://example.com";           //set to your ProcessMaker address
$userId = '55324179754ca442baeb994077387342'; //set to the unique ID of a user

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . '/api/1.0/workflow/user/' . $userId);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oUser = json_decode(curl_exec($ch));

if (!isset($oUser)) {
   print "Error accessing $apiServer: \n" . curl_error($ch);
}
elseif (isset($oUser->error)) {
   print "Error in $apiServer: \nCode: {$oUser->error->code}\nMessage: {$oUser->error->message}\n";
}
else {
   $fullName = $oUser->usr_firstname . ' ' . $oUser->usr_lastname;
}
curl_close($ch);

Create User: POST /user

Create a new user.

POST /api/1.0/{workspace}/user

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

POST Parameters:

NameTypeDescription
usr_usernameStringUsername which is used to login to ProcessMaker and is unique.
usr_firstnameStringUser's first name
usr_lastnameStringUser's last name
usr_emailStringUser's email address
usr_due_dateStringThe date in "YYYY-MM-DD" when the user's account will expire. After this date, the user will not be able to login to ProcessMaker. Ex: "2020-12-31"
usr_statusStringThe user's status, which can be "ACTIVE", "INACTIVE" or "VACATION".
usr_roleStringThe user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role.
usr_new_passStringThe user's password. Remember that passwords should adhere to the password security policies.
usr_cnf_passStringEnter the password a second time to confirm it.
usr_addressStringOptional. The user's address. Use \n to include line breaks in the address. Ex: "345 Radcliff Drive\nC/O Brad Williams"
usr_zip_codeStringOptional. User's zip or postal code.
usr_countryStringOptional. Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database.
usr_cityStringOptional. One or two letter code to identify the region, state or province. Note: This field is misnamed. See the wf_<WORKSPACE>.ISO_SUBDIVISION table in the database.
usr_locationStringOptional. Code which is 1 to 3 letters long to identify the city or locality. See the wf_<WORKSPACE>.ISO_LOCATION table in the database.
usr_phoneStringOptional. The user's telephone number.
usr_positionStringOptional. The user's position in the organization.
usr_replaced_byStringOptional. Unique ID of another user who will replace this user if his/her status changes to "INACTIVE" or "VACATION".
usr_calendarStringOptional. The unique ID of the calendar which is used to calculate the due dates of tasks which the user is assigned to work on. To get the UID of a calendar, see the wf_<WORKSPACE>.CALENDAR_DEFINITION.CALENDAR_UID field in the database.

Result:

If a user was successfully created, the HTTP status code will be set to 200 and a JSON object with information about the new user is returned:

{
  usr_uid:         "75740355754dd28ba73d7d6082172936",
  usr_username:    "janedoe",
  usr_password:    "5e8ff9bf55ba3508199d22e984129be6",
  usr_firstname:   "Jane",
  usr_lastname:    "Doe",
  usr_email:       "janedoe@example.com",
  usr_due_date:    "2020-12-31",
  usr_create_date: "2015-02-12 17:27:06",
  usr_update_date: "2015-02-12 17:27:06",
  usr_status:      "ACTIVE",
  usr_country:     "US",
  usr_city:        "IN",
  usr_location:    "GXQ",
  usr_address:     "740 Turtle Dove lane",
  usr_phone:       "1-765-653-4478",
  usr_fax:         "",
  usr_cellular:    "",
  usr_zip_code:    "46135",
  dep_uid:         "",
  usr_position:    "Head Accountant",
  usr_resume:      "",
  usr_birthday:    "2015-02-12",
  usr_role:        "PROCESSMAKER_OPERATOR",
  usr_reports_to:  "",
  usr_replaced_by: "14680180454ca4477335a27034362107",
  usr_ux:          "NORMAL"
}

If an error occurred, the HTTP status code will be set to 400 or greater and a JSON object will be returned like the following:

{
  error: {
    code:    400,
    message: "Bad Request: usr_username. Username 'janedoe' already exists"
  }
}

PHP Example:

$apiServer = "https://example.com"; //set to your ProcessMaker address

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();

$postParams = array(
   'usr_username'   => "janedoe",
   'usr_firstname'  => "Jane",
   'usr_lastname'   => "Doe",
   'usr_email'      => "janedoe@example.com",
   'usr_due_date'   => "2020-12-31",
   'usr_status'     => "ACTIVE",
   'usr_role'       => "PROCESSMAKER_OPERATOR",
   'usr_new_pass'   => "p4s5w0rD",
   'usr_cnf_pass'   => "p4s5w0rD",
   'usr_address'    => "740 Turtle Dove lane",
   'usr_zip_code'   => "46135",
   'usr_country'    => "US",
   'usr_city'       => "IN",
   'usr_location'   => "GXQ",
   'usr_phone'      => "1-765-653-4478",
   'usr_position'   => "Head Accountant",
   'usr_replaced_by'=> "14680180454ca4477335a27034362107",
   'usr_calendar'   => "91552296454dd0c63c477c6014743059"
);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/user");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postParams);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oUser = json_decode(curl_exec($ch));

if (!isset($oUser)) {
   print "Error accessing $apiServer: \n" . curl_error($ch);
}
elseif (isset($oUser->error)) {
   print "Error in $apiServer: \nCode: {$oUser->error->code}\nMessage: {$oUser->error->message}\n";
}
else {
   print "User '{$oUser->usr_username}' created with UID: {$oUser->usr_uid}\n";
}
curl_close($ch);

Upload User Image: POST /user/{usr_uid}/image-upload

Upload an image of the specified user, which will appear in the user's profile screen.

POST /api/1.0/{workspace}/user/{usr_uid}/image-upload

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
usr_uidStringUser UID

POST Parameters:

NameTypeDescriptionExamples
USR_PHOTOstringThe full path on the ProcessMaker server where the image file is located. The image file must be JPEG, PNG or GIF format.
Note: If using PHP, make sure to place @ in front of the path to suppress error messages. Otherwise, this endpoint will not work.
"/home/bob/images/myphoto.jpg"
"C:\Users\bob\images\myphoto.gif"

Result:
Returns an HTTP status code of 200 if the image was uploaded correctly. Otherwise, returns 0.

PHP Example:

$apiServer = 'https://example.com';           //set to your ProcessMaker address
$userId = '55324179754ca442baeb994077387342'; //set the unique ID of a user
$filePath = '/home/user/images/photo.jpg';    //set the file to upload

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();

$ch = curl_init($apiServer . "/api/1.0/workflow/user/$userId/image-upload");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

//Notice the @ to suppress error messages:
curl_setopt($ch, CURLOPT_POSTFIELDS, array('USR_PHOTO' => "@" . $filePath));

curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 200) {
   print "Error uploading user image:\nHTTP status code: $statusCode\n";
}
curl_close($ch);

If needing to upload image files which are not located on the ProcessMaker server, first use ssh2_scp_send() to copy the files to the ProcessMaker server, then use the code above to call the /api/1.0/{workspace}/user/{usr_uid}/image-upload endpoint.

$path = '/path/to/file/image.jpg';         //set the path of the image file on the local computer
$filename = basename($path);
$conn = ssh2_connect('www.example.com');   //set to the address of the ProcessMaker server
ssh2_auth_password($conn, 'username', 'password'); //set username &amp; password to login to ProcessMaker server
 
ssh2_scp_send($conn, $path, "/remote/dir/$filename");

Update User Information: PUT /user/{usr_uid}

Update the information about a specified user.

PUT /api/1.0/{workspace}/user/{usr_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
usr_uidStringUser UID

PUT Parameters:

Only set the fields which need to be updated. PUT parameters need to be URL-encoded. In PHP, place the parameters in an associative array and use http_build_query() to encode it. In JavaScript, place the parameters in an object and then use encodeURIComponent() to encode it.

NameTypeDescription
usr_usernameStringOptional. Username which is used to login to ProcessMaker and is unique.
usr_firstnameStringOptional. User's first name
usr_lastnameStringOptional. User's last name
usr_emailStringOptional. User's email address
usr_due_dateStringOptional. The date in "YYYY-MM-DD" when the user's account will expire. After this date, the user will not be able to login to ProcessMaker. Ex: "2020-12-31"
usr_statusStringOptional. The user's status, which can be "ACTIVE", "INACTIVE" or "VACATION".
usr_roleStringOptional. The user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role.
usr_addressStringOptional. The user's address. Use \n to include line breaks in the address. Ex: "345 Radcliff Drive\nC/O Brad Williams"
usr_zip_codeStringOptional. User's zip or postal code.
usr_countryStringOptional. Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database.
usr_cityStringOptional. One or two letter code to identify the region, state or province. Note: This field is misnamed. See the wf_<WORKSPACE>.ISO_SUBDIVISION table in the database.
usr_locationStringOptional. Code which is 1 to 3 letters long to identify the city or locality. See the wf_<WORKSPACE>.ISO_LOCATION table in the database.
usr_phoneStringOptional. The user's telephone number.
usr_cellularStringOptional. The user's cellular phone number.
usr_faxStringOptional. The user's fax number.
usr_positionStringOptional. The user's position in the organization.
usr_birthdayStringOptional. The user's birthday in "YYYY-MM-DD" format. Ex: "1984-08-23"
usr_replaced_byStringOptional. Unique ID of another user who will replace this user if his/her status changes to "INACTIVE" or "VACATION".
usr_new_passStringOptional. The user's password. Remember that passwords should adhere to the password security policies.
usr_cnf_passStringOptional. Enter the password a second time to confirm it. If this password doesn't match the one in usr_new_pass, then an error will occur.

Result:

If the user account was updated, the HTTP status code is set to 200 and it returns the following object with the updated information about the user:

{
  usr_uid:         "55324179754ca442baeb994077387342"
  usr_username:    "molly"
  usr_password:    "2b06a2251d39e28f8220696766dcd136"
  usr_firstname:   "Molly"
  usr_lastname:    "Moe"
  usr_email:       "molly@example.com"
  usr_due_date:    "2023-12-31"
  usr_create_date: "2015-01-20 09:31:07"
  usr_update_date: "2015-02-13 14:37:25"
  usr_status:      "VACATION"
  usr_country:     "US"
  usr_city:        "IN"
  usr_location:    "GXQ"
  usr_address:     "Dept 66\n740 Turtle Dove lane"
  usr_phone:       "1-765-653-4444"
  usr_fax:         "1-765-658-3574"
  usr_cellular:    "1-765-658-3571"
  usr_zip_code:    "46135"
  dep_uid:         "11826545154db794ca22b52025081429"
  usr_position:    "Head Accountant"
  usr_resume:      ""
  usr_birthday:    "1982-01-29"
  usr_role:        "PROCESSMAKER_MANAGER"
  usr_reports_to:  "14680180454ca4477335a27034362107"
  usr_replaced_by: "14680180454ca4477335a27034362107"
  usr_ux:          "SINGLE"
}

If an error occurred, the HTTP status code is set to 400 and an error object like the following is returned:

{
   error: {
      code:    400
      message: "Bad Request: usr_username. Username 'janedoe' already exists"
   }
}

PHP Example:
The following example, changes the status to "VACATION" and sets the user who will replace this user when she goes on vacation.

$apiServer = "https://example.com";            //set to your ProcessMaker address
$userId = "75740355754dd28ba73d7d6082172937";  //set to the unique ID of a user

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();

$postParams = array(
  'usr_status'      => "VACATION",
  'usr_replaced_by' => "14680180454ca4477335a27034362107"
);

$ch = curl_init($apiServer . "/api/1.0/workflow/user/" . $userId);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postParams));
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if (isset($oResult) and isset($oResult->error)) {
   print "Error in $apiServer: \nCode: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
}
elseif (isset($oResult) and isset($oResult->usr_uid)) {
   print "User '{$oResult->usr_uid}' updated:\n";
   print_r($oResult);
}
else {
   print "Error updating user: HTTP status code: $statusCode\n";
}
curl_close($ch);

Note that the following line sets the request to be a PUT request:

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");

Also note that the POST parameters need to be passed to http_build_query() to generate a URL-encoded query string which can be used with PUT requests.

Delete User: DELETE /user/{usr_uid}

Delete a specified user.

DELETE /api/1.0/{workspace}/user/{usr_uid}
Note: This endpoint sets the wf_<WORKSPACE>.USERS.USR_USERNAME field to "" (empty string) in the database, so that the user can no longer be used, but it does NOT delete the user's record from the database.

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
usr_uidStringUser UID

Result:

If the user was successfully deleted, then the HTTP response code will be 200. If an error occurs, then the HTTP response code is set to 400 and an object like the following is returned:

{
  error: {
    code:    400
    message: "Bad Request: The row '75740355754dd28ba73d7d6082172937' in table USER doesn't exist!"
  }
}  

PHP Example:

$apiServer = "https://example.com"; //set to your ProcessMaker address
$userId    = "75740355754dd28ba73d7d6082172937"; //set to a user's ID
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();

$ch = curl_init($apiServer . "/api/1.0/workflow/user/$userId");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($statusCode != 200) {
   if (isset($oResult) and isset($oResult->error)) {
      print "Error in $apiServer: \nCode: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   }
   else {
      print "Error: HTTP status code: $statusCode\n";
   }
}
curl_close($ch);

Groups

The following REST endpoints are used to manage groups, as well as their member users in ProcessMaker.

1. Get a list of all groups

2. Get a single group

3. Create a group

4. Update group

5. Delete a group

Groups - Users

6. List all assigned users to a group

7. List available users to assign to a group

8. Assign users to a group

9. Unassign a user from a group


Available methods:

Get Groups List: GET /groups

Get a list of all the groups in the workspace (including groups with "INACTIVE" status). The groups are returned in alphabetical order.

GET /api/1.0/{workspace}/groups?filter={filter}&start={start}&limit={limit}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

Optional GET Parameters:

NameTypeDescription
filterstringCase insensitive string to search for in the group name.
For example, "api/1.0/workspace/groups?filter=sal" would return the groups "Sales" and "Condiments & salts".
startintegerThe number of groups where the list begins. The counting starts from the number 0.
For example, "api/1.0/workspace/groups?start=3" would start the list of groups with the fourth group.
limitintegerThe maximum number of groups which are returned in the list.
For example if wanting to return 10 groups at a time and there are 25 groups in total, then call this endpoint 3 times:
"api/1.0/workspace/groups?limit=10" (returns groups 0-9)
"api/1.0/workspace/groups?start=10&limit=10" (returns groups 10-19)
"api/1.0/workspace/groups?start=20&limit=10" (returns groups 20-24)

Result:

Returns an HTTP status code of 200 and the following array of group objects:

ElementDescription
[Start array
{Start group object
grp_uidThe group's unique ID.
grp_titleThe group's title.
grp_statusThe group's status, which can be "ACTIVE" or "INACTIVE".
grp_usersThe number of users who are members of the group, including users who have "INACTIVE" and "VACATION" status.
grp_tasksThe number of tasks to which the group is assigned. Note that this number includes tasks which are in deactivated processes, but it does not include ad hoc assignment to tasks.
},End group object.
...Additional group objects.
]End array.

For example:

[
  {
    grp_uid:    "47113834154e4a6c5cd1f11014216675",
    grp_title:  "European Sales",
    grp_status: "ACTIVE",
    grp_users:  3,
    grp_tasks:  1
  },
  {
    grp_uid:    "23251789354e4a6d6812cb4062218479",
    grp_title:  "Factory Workers",
    grp_status: "INACTIVE"
    grp_users:  20,
    grp_tasks:  7
  },
  {
    grp_uid:    "92331939154e4a6b3d46cc3062046323",
    grp_title:  "Managers"
    grp_status: "ACTIVE"
    grp_users:  4,
    grp_tasks:  2
  }
]

If there is are no groups, then an empty array is returned. If an error occurs, then

PHP Example: The following example creates an array of the active groups which are assigned to one or more tasks.

$apiServer = "https://example.com"; //set to your ProcessMaker address
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();

$ch = curl_init($apiServer . "/api/1.0/workflow/groups");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aGroups = json_decode(curl_exec($ch));
curl_close($ch);

$aActiveGroups = array();

foreach ($aGroups as $oGroup) {
   if ($oGroup->grp_status == "ACTIVE" and $oGroup->grp_tasks >= 1) {
      $aActiveGroups[] = array("uid" => $oGroup->grp_uid, "title" => $oGroup->grp_title);
   }
}

Get Group Information: GET /group/{grp_uid}

Get information about a specified group.

GET /api/1.0/{workspace}/group/{grp_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
grp_uidStringGroup UID

Result:

Returns the HTTP status code 200 and the same group object as the GET /groups endpoint. For example:

{
  grp_uid:    "47113834154e4a6c5cd1f11014216675",
  grp_title:  "European Sales",
  grp_status: "ACTIVE",
  grp_users": 5,
  grp_tasks"
: 2
}

If a bad request, then it returns the HTTP status code 400 and an error object like this:

{
  error: {
    code: 400,
    message: "Bad Request: The group with grp_uid: 66065213554dd1feb48fe79020620851 does not exist."
  }
}

PHP Example:

This example prints out how many users are in a group with the ID "47113834154e4a6c5cd1f11014216675":

$apiServer = "https://example.com";           //set to your ProcessMaker address
$userId = '47113834154e4a6c5cd1f11014216675'; //set to the unique ID of a group

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . '/api/1.0/workflow/group/' . $userId);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oGroup = json_decode(curl_exec($ch));

if (isset($oGroup->error)) {
   print "Error in $apiServer: \nCode: {$oGroup->error->code}\nMessage: {$oGroup->error->message}\n";
}
else {
   print "Group '{$oGroup->grp_title}' has {$oGroup->grp_users} members.\n";
}
curl_close($ch);

Create Group: POST /group

Create a new group.

POST /api/1.0/{workspace}/group

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

POST Fields:

NameTypeDescription
grp_titleStringThe name of the group.
grp_statusStringThe group's status, which can be "ACTIVE" or "INACTIVE". If the group is assigned to a task and its status is "INACTIVE", then members of the group will NOT be assigned to the task when cases are run.

Result:

If a new group was created, then the HTTP status code is 201 and a JSON object with information about the new group is returned. For example:

{
  grp_uid:    "95436327554e4c87a5bd201063097966",
  grp_title:  "Accounting",
  grp_status: "ACTIVE"
}

If a bad request, then the HTTP status code is 400 or greater and a JSON object like the following is returned:

{
  error: {
    code:    400,
    message: "Bad Request: The group title with grp_title: \"Accounting\" already exists."
  }
}

PHP Example:

$apiServer = "https://example.com"; //set to your ProcessMaker address

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();

$postParams = array(
   'grp_title'   => "Accounting",
   'grp_status'  => "ACTIVE"
);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/group");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postParams);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oGroup = json_decode(curl_exec($ch));

if (!isset($oGroup)) {
   print "Error accessing $apiServer: \n" . curl_error($ch);
}
elseif (isset($oGroup->error)) {
   print "Error in $apiServer: \nCode: {$oGroup->error->code}\nMessage: {$oGroup->error->message}\n";
}
else {
   print "Group '{$oGroup->grp_title}' created with UID: {$oGroup->grp_uid}\n";
}
curl_close($ch);

Update Group: PUT /group/{usr_uid}

Update information about a specified group.

PUT /api/1.0/{workspace}/group/{grp_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
grp_uidStringGroup unique ID.

Optional Fields:

NameTypeDescription
grp_titleStringThe group's title.
grp_statusStringGroup status, which can be "ACTIVE" or "INACTIVE". If the group is assigned to a task and its status is "INACTIVE", then members of the group will NOT be assigned to the task when cases are run.

Result:

If the group was successfully updated, the HTTP status code is 200 and there is nothing returned.

If it is a bad request, then the HTTP status code is set to 400 or greater, and a JSON object like the following is returned:

{
  error: {
    code:    400,
    message: "Bad Request: The group with grp_uid: 47113834154e4a6c5cd1f11014216674 does not exist."
  }
}

PHP Example:
The following example changes the group title to "Accounting" and sets its status to "INACTIVE":

$apiServer = "https://example.com";            //set to your ProcessMaker address
$userId = "75740355754dd28ba73d7d6082172937";  //set to the unique ID of a group
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$postParams = array(
  'grp_title'  => "Accounting",
  'grp_status' => "INACTIVE",
);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/group/" . $groupId);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postParams));
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($statusCode != 200) {
   if (isset($oResult) and isset($oResult->error))
      print "Error Code: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
curl_close($ch);

Note that the following line sets the request to be a PUT request:

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");

Also note that the POST parameters need to be passed to http_build_query() to generate a URL-encoded query string which can be used with PUT requests.

Delete Group: DELETE /group/{grp_uid}

Delete a specified group. Note that this endpoint deletes the group's record from the GROUPWF table and its title from the CONTENT table in the database, but it doesn't delete the group's membership list from the GROUP_USER table.

DELETE /api/1.0/{workspace}/group/{grp_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
grp_uidStringGroup unique ID.

Result:

If the group was deleted, then the HTTP status code is 200. Otherwise, the HTTP status code is 400 or greater and a JSON object is returned like the following:

{
  error: {
    code:    400,
    message: "Bad Request: The group with grp_uid: 23251789354e4a6d6812cb4062218479 does not exist."
  }
}

PHP Example:

$apiServer = "https://example.com";              //set to your ProcessMaker address
$groupId   = "75740355754dd28ba73d7d6082172937"; //set to a group's ID to delete it

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "/api/1.0/workflow/group/" . $groupId);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 200) {
   if (isset($oResult) and isset($oResult->error)) {
      print "Error in $apiServer: \nCode: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   }
   else {
      print "Error: HTTP status code: $statusCode\n";
   }
}
curl_close($ch);

GROUPS - USERS

Get Group Members: GET /group/{grp_uid}/users

List the assigned users to a specified group.

GET /api/1.0/{workspace}/group/{grp_uid}/users?filter={filter}&start={start}&limit={limit}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
grp_uidStringGroup UID


Optional GET Parameters:

NameTypeDescription
filterstringCase insensitive string to search for in the user's first name, last name or username.
For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?filter=mit" would return the users "smith", "Mitter" and "solmit".
startintegerThe number of users where the list begins. The counting starts from number 0.
For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=3" would start the list of users with the fourth user.
limitintegerThe maximum number of users which are returned in the list.
For example if wanting to return 10 users at a time and there are 25 users in total, then call this endpoint 3 times:
"api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?limit=10" (returns users 0-9)
"api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=10&limit=10" (returns users 10-19)
"api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=20&limit=10" (returns users 20-24)

Result:

If a successful request, the HTTP status code is set to 200 and a JSON array of user objects is returned, like the following one:

[
  {
    usr_uid:       "55324179754ca442baeb994077387342",
    usr_username:  "jane",
    usr_firstname: "Jane",
    usr_lastname:  "Doe",
    usr_email:     "janedoe@example.com",
    usr_status:    "ACTIVE"
  },
  {
    usr_uid:       "66065213554dd1feb48fe79020620851",
    usr_username:  "sam",
    usr_firstname: "Sam",
    usr_lastname:  "Sloe",
    usr_email:     "samsloe@example.com",
    usr_status:    "INACTIVE"
  },
]

If a bad request, then the HTTP status code is 400 or greater and a JSON error object is returned, like this one:

{
  error: {
    code:    400,
    message: "Bad Request: The group with grp_uid: 47113834154e4a6c5cd1f11014216674 does not exist."
  }
}

PHP Example:
This PHP example creates a list of active users who are members of a group with the unique ID of "47113834154e4a6c5cd1f11014216675" and places them in the array $aActiveUsers.

$apiServer = "https://example.com";              //set to your ProcessMaker address
$groupId   = "47113834154e4a6c5cd1f11014216675", //set to the unique ID of a group

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "api/1.0/workspace/group/$groupId/users");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aUsers = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
$aActiveUsers = array();
 
if ($statusCode != 200) {
   if (isset ($aUsers) and isset($aUsers->error))
      print "Error code: {$aUsers->error->code}\nMessage: {$aUsers->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
else {
   foreach ($aUsers as $oUser) {
      if ($oUser->usr_status == "ACTIVE") {
         $aActiveUsers[] = array("uid" => $oUser->usr_uid, "username" => $oUser->usr_username);
      }
   }
}

Get Available Users: GET /group/{grp_uid}/available-users

Get a list of available users, which can be assigned to a specified group. All users which aren't yet assigned to the group will be listed, including users with "INACTIVE" and "VACATION" status.

GET /api/1.0/{workspace}/group/{grp_uid}/available-users?filter={filter}&start={start}&limit={limit}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
grp_uidStringGroup unique ID.

Optional GET Parameters:

NameTypeDescription
filterstringCase insensitive string to search for in the user's first name, last name or username.
For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?filter=mit" would return the users "smith", "Mitter" and "solmit".
startintegerThe number of users where the list begins. The counting starts from number 0.
For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=3" would start the list of users with the fourth user.
limitintegerThe maximum number of users which are returned in the list.
For example if wanting to return 10 users at a time and there are 25 users in total, then call this endpoint 3 times:
"api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?limit=10" (returns users 0-9)
"api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=10&limit=10" (returns users 10-19)
"api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=20&limit=10" (returns users 20-24)

Result:

If a successful request, the HTTP status code is set to 200 and a JSON array of user objects is returned, like the following one:

[
  {
    usr_uid:       "55324179754ca442baeb994077387342",
    usr_username:  "jane",
    usr_firstname: "Jane",
    usr_lastname:  "Doe",
    usr_email:     "janedoe@example.com",
    usr_status:    "ACTIVE"
  },
  {
    usr_uid:       "66065213554dd1feb48fe79020620851",
    usr_username:  "sam",
    usr_firstname: "Sam",
    usr_lastname:  "Sloe",
    usr_email:     "samsloe@example.com",
    usr_status:    "INACTIVE"
  },
]

If a bad request, then the HTTP status code is 400 or greater and a JSON error object is returned, like this one:

{
  error: {
    code:    400,
    message: "Bad Request: The group with grp_uid: 47113834154e4a6c5cd1f11014216674 does not exist."
  }
}

PHP Example:

This example gets a list of the first 10 available users to be assigned to a group with the ID ""47113834154e4a6c5cd1f11014216675":

$apiServer = "https://example.com";              //set to your ProcessMaker address
$groupId   = "47113834154e4a6c5cd1f11014216675", //set to the unique ID of a group
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "api/1.0/workspace/group/$groupId/users");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aUsers = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
$aAvailableUsers = array();
 
if ($statusCode != 200) {
   if (isset ($aUsers) and isset($aUsers->error))
      print "Error code: {$aUsers->error->code}\nMessage: {$aUsers->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
else {
   for ($i = 0; $i < 10 and $i < count($aUsers; $i++) {
      $aAvailableUsers[] = array(
         "uid" => $aUsers[$i]->usr_uid,
         "name"=> "{$aUsers[$i]->usr_firstname} {$aUsers[$i]->usr_lastname} ({$aUsers[$i]->usr_username})"
      );
   }
}

Assign User to Group: POST /group/{grp_uid}/user

Assign a user to a specified group.

POST /api/1.0/{workspace}/group/{grp_uid}/user

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
grp_uidStringThe group's unique ID

POST Fields:

NameTypeDescription
usr_uidStringThe unique ID of the user who will be added to the group as a member. Note that it is possible to add a user with "INACTIVE" or "VACATION" status to a group, but that user will not be assigned to any cases until his/her status changes to "ACTIVE" status.

Optional Fields:

These fields may be included, but they will be ignored by the REST endpoint.

NameTypeDescription
usr_usernameStringUsername
usr_firstnameStringUser first name
usr_lastnameStringUser last name
usr_emailStringUser email
usr_statusStringUser status

Result:

If the user was assigned to the group, then the HTTP status code is 201 (Created) and there is no return object. Otherwise, it is 400 or greater and returns a JSON error object like:

{
  error: {
    code:    400,
    message: "Bad Request: The user with usr_uid: 55324179754ca442baeb994077387342 is already assigned to the group."
  }
}

PHP Example:

$apiServer = "https://example.com";            //set to your ProcessMaker address
$groupId = "75740355754dd28ba73d7d6082172937"; //set to the unique ID of a group
$userId  = "14680180454ca4477335a27034362107"; //set to unique ID of user to add to group
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$postParams = array('usr_uid' => $userId);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/group/$groupId/user");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postParams);
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 201) {
   if isset($oResult) and isset($oResult->error)) {
      print "Error in $apiServer:\nCode: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   }
   else {
      print "Error: HTTP status code $statusCode\n";
   }
}
curl_close($ch);

Unassign User from Group: DELETE /group/{grp_uid}/user/{usr_uid}

Unassign (remove) a user from a group so no longer a member of the group.

DELETE /api/1.0/{workspace}/group/{grp_uid}/user/{usr_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
grp_uidStringGroup UID
usr_uidStringGroup UID

Result:

If the user was removed from the group, then the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and a JSON error object is returned, such as:

{
  error: {
    code:    400,
    message: "Bad Request: The user with usr_uid: 98883020754dd1f052ee1f1034403381 is not assigned to the group."
  }
}

PHP Example:

$apiServer = "https://example.com";              //set to your ProcessMaker address
$groupId   = "75740355754dd28ba73d7d6082172937"; //set to a group's ID
$userId    = "98883020754dd1f052ee1f1034403381"; //set to the ID of the user to be removed from the group
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "/api/1.0/workflow/group/$groupId/user/$userId");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 200) {
   if (isset($oResult) and isset($oResult->error)) {
      print "Error in $apiServer: \nCode: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   }
   else {
      print "Error: HTTP status code: $statusCode\n";
   }
}
curl_close($ch);

Departments

These are the REST endpoints to manage departments in ProcessMaker:

  1. Get a list of departments
  2. Get data of a department
  3. Create a department
  4. Update a department
  5. Delete a department
  6. Get the list of assigned users
  7. Get a list of available users in a department.
  8. v.2.8: Assign a user to a department
  9. v.3.0+: Assign a user to a department
  10. Unassign a user from a department
  11. Set manager user to department

Get Departments List: GET /departments

Get a list of all the departments in the workspace, including departments with "INACTIVE" status.

GET /api/1.0/{workspace}/departments

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

Result:

If successful, the HTTP status code is set to 200 and it returns a JSON array of department objects with the following structure:

ElementDescriptionExample
[Start array.
{Start department object
dep_uid,The department's unique ID."11826545154db794ca22b52025081429"
dep_parent,The unique ID of the parent department. If this is a top-level deparment, then set to "" (empty string).""
dep_title,The department's title."Human Resources"
dep_status,The department's status, which can be "ACTIVE" or "INACTIVE"."ACTIVE"
dep_manager,The department's supervisor, to whom the other members of the department and the supervisors of the subdepartments report. By default, the supervisor is the first user assigned to the department."14680180454ca4477335a27034362107"
dep_ldap_dn,The user's distinguished name if imported from LDAP. If a normal user whose account wasn't imported, then then set to "" (empty string).""
dep_last,If the last department object in the current array, then set to 1. If not the last, then set to 0.1
dep_manager_username,The username of the department's supervisor."liliana"
dep_manager_firstname,The first name of the department's supervisor."Liliana"
dep_manager_lastname,The last name of the department's supervisor."Ortiz"
has_children,The number of subdepartments of this department."2"
dep_childrenA array of subdepartment objects for this department. If there are no subdepartments, then an empty array.[]
},End the department object
{...}Any additional department objects.
]End array.

For example:

[
  {
    dep_uid:               "11826545154db794ca22b52025081429",
    dep_parent:            "",
    dep_title:             "Human  Resources",
    dep_status:            "ACTIVE",
    dep_manager:           "14680180454ca4477335a27034362107",
    dep_ldap_dn:           "",
    dep_last:              0,
    dep_manager_username:  "liliana",
    dep_manager_firstname: "Liliana",
    dep_manager_lastname:  "Ortiz",
    has_children:          "2",
    dep_children:
      [
        {
          dep_uid:              "54883398754db7993002ae1030708956",
          dep_parent:           "11826545154db794ca22b52025081429",
          dep_title:            "Crisis Management",
          dep_status:           "ACTIVE",
          dep_manager:          "91937880754ca444fc1e7b8079810120",
          dep_ldap_dn:          "",
          dep_last:             0,
          dep_manager_username: "sylvia",
          dep_manager_firstname:"Sylvia",
          dep_manager_lastname: "Herrero",
          has_children:         "0",
          dep_children:
            []
        },
        {
          dep_uid:               "98568611654e60da3ad38c3043219561",
          dep_parent:            "11826545154db794ca22b52025081429",
          dep_title:             "Employee Activities",
          dep_status:            "ACTIVE",
          dep_manager:           "66065213554dd1feb48fe79020620851",
          dep_ldap_dn:           "",
          dep_last:              1,
          dep_manager_username:  "johndoe",
          dep_manager_firstname: "John",
          dep_manager_lastname:  "Doe",
          has_children:          "0",
          dep_children:
            []
        }
      ]
  },
  {
    dep_uid:               "48474671254e60d7d9ac448055325161",
    dep_parent:            "",
    dep_title:             "Sales",
    dep_status:            "INACTIVE",
    dep_manager:           "00000000000000000000000000000001",
    dep_ldap_dn:           "",
    dep_last:              1,
    dep_manager_username:  "admin",
    dep_manager_firstname: "Administrator",
    dep_manager_lastname:  " ",
    has_children:          "0",
    dep_children:
      []
  }
]

PHP Example:

This example prints out the directory structure of an organization with the supervisor's name in parentheses.

//recursive function to print department's name and supervisor's username:
function printDeptArray($aDepts, $level) {
   foreach ($aDepts as $oDept) {
      //print spaces for the level of department:
      for ($ii = 0; $ii < $level; $ii++) {
         print "     ";
      }
      print "{$oDept->dep_title} ({$oDept->dep_manager_username})\n";
 
      if ($oDept->has_children != 0) {
         printDeptArray($oDept->dep_children, $level + 1);
      }
   }
}  
 
$apiServer = "https://example.com"; //set to your ProcessMaker address
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "/api/1.0/workflow/departments");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aDepts = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
$aEmptyDepartments = array();
 
if ($statusCode != 200) {
   if (isset ($aDepts) and isset($aDepts->error))
      print "Error code: {$aDepts->error->code}\nMessage: {$aDepts->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
else {
   print "<pre>";   //only necessary if used in a web page
   printDeptArray($aDepts, 0);
   print "</pre>";  //only necessary if used in a web page
}

For the departments shown in the example above, this script would print out:

Human Resources (liliana)
     Crisis Management (sylvia)
     Employee Activities (johndoe)
Sales (admin)

Get Department Information: GET /department/{dep_uid}

Get information about a specified department.

GET /api/1.0/{workspace}/department/{dep_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringDepartment UID

Result:

If successful, the HTTP status code is 200 and a department object is returned like the GET departments endpoint, but it doesn't include the dep_children array. For example:

{
  dep_uid:               "54883398754db7993002ae1030708956",
  dep_parent:            "11826545154db794ca22b52025081429",
  dep_title:             "Crisis Management",
  dep_status:            "ACTIVE",
  dep_manager:           "91937880754ca444fc1e7b8079810120",
  dep_ldap_dn:           "",
  dep_last:              0,
  dep_manager_username:  "sylvia",
  dep_manager_firstname: "Sylvia",
  dep_manager_lastname:  "Herrero",
  has_children:          "0"
}

If unsuccessful, the HTTP status code is 400 or greater and a JSON error object is returned, such as:

{
  error: {
    code:    400,
    message: "Bad Request: The department with dep_uid: '54883398754db7993002ae1030708957' does not exist."
  }
}

PHP Example:

This example prints out the department's title and its supervisor's full name:

$apiServer = "https://example.com";              //set to your ProcessMaker address
$deptId    = "54883398754db7993002ae1030708956"; //set to a department's unique ID

$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department/$deptId");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oDept = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($statusCode != 200) {
   if (isset ($oDept) and isset($oDept->error))
      print "Error code: {$oDept->error->code}\nMessage: {$oDept->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
else {
   print "{$oDept->dep_title} Department supervisor: {$oDept->dep_manager_firstname} {$oDept->dep_manager_lastname}";
}

Create Department: POST /department

Create a new department.

POST /api/1.0/{workspace}/department

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

POST Fields:

NameTypeDescription
dep_titleStringDepartment's title (name). Note that the department's title must be unique, so an error will occur if trying to create a department title which already exists.
dep_parentStringOptional. Parent department's unique ID. If not included or set to "" (empty string), then this is a top-level department.
dep_managerStringOptional. Department supervisor's unique ID. Users may only be assigned to ONE department, so the supervisor may NOT be a member of another department.
dep_statusStringOptional. Department status, which can be "ACTIVE" or "INACTIVE". If not included, then "ACTIVE" by default.

Result:

If the new department was created, the HTTP status code is 201 (Created) and a department object is returned, like the following:

{
  dep_uid:               "53126763454e62dc3284a75021962206",
  dep_parent:            "48474671254e60d7d9ac448055325161",
  dep_title:             "International Sales",
  dep_status:            "ACTIVE",
  dep_manager:           "61875549854e62c9c0bc823037974404",
  dep_ldap_dn:           "",
  dep_last:              0,
  dep_manager_username:  "kendrick",
  dep_manager_firstname: "Kendrick",
  dep_manager_lastname:  "Hillman",
  has_children:          "0"
}
Note: The dep_last element in the returned object is always set to 0 and is not correct. To check whether the new department is the last department at the current level, call the GET /departments or GET /department/{dep_uid} endpoint and check the value of the dep_last element.

If an error occurred, the HTTP status code is 400 or greater and an error object is returned, like the following:

{
  error: {
    code:    400,
    message: "Bad Request: The department with dep_parent: '48474671254e60d7d9ac448055325160' does not exist."
  }
}


PHP Example:

$apiServer = "https://example.com"; //set to your ProcessMaker address
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$postParams = array(
   'dep_title'   => 'International Sales',
   'dep_manager' => '61875549854e62c9c0bc823037974404',
   'dep_parent'  => '48474671254e60d7d9ac448055325161',
   'dep_status'  => 'ACTIVE'
);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postParams);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oDept = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($statusCode == 201) {
   print "Department '{$oDept->dep_title}' created with UID: {$oDept->dep_uid}\n";
}
else {
   if (isset($oDept) and isset($oDept->error)) {
      print "Error in $apiServer: \nCode: {$oDept->error->code}\nMessage: {$oDept->error->message}\n";
   }
   else {
      print "Error: HTTP status code: $statusCode\n";
   }
}
curl_close($ch);

Update Department: PUT /department/{dep_uid}

Update the information about a department.

PUT /api/1.0/{workspace}/department/{dep_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringDepartment UID.

Optional Fields:

NameTypeDescription
dep_titleStringThe department title (name), which must be unique.
dep_parentStringUnique ID of the parent department. Set to "" (empty string) to make a top-level department.
dep_managerStringUnique ID of the department supervisor, to whom the members of the department [[1]], as well as the supervisors of subdepartments.
dep_statusStringDepartment status, which can be "ACTIVE" or "INACTIVE".

Result:

If the department was successfully updated, then the HTTP status code is set to 200 and there is no return object. Otherwise, it is set to 400 and greater and returns an error object, such as:

{
  error: {
    code:    400,
    message: "Bad Request: The user with dep_manager: '91937880754ca444fc1e7b8079810121' does not exist."
  }
}

PHP Example:

$apiServer = "https://example.com";            //set to your ProcessMaker address
$deptId = "75740355754dd28ba73d7d6082172937";  //set to the unique ID of a department
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$postParams = array(
   'dep_title'   => 'International Sales',
   'dep_manager' => '91937880754ca444fc1e7b8079810121',
   'dep_parent'  => '48474671254e60d7d9ac448055325161',
   'dep_status'  => 'INACTIVE'
);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department/" . $deptId);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postParams));
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($statusCode != 200) {
   if (isset($oResult) and isset($oResult->error))
      print "Error Code: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
curl_close($ch);

Delete Department: DELETE /department/{dep_uid}

Delete a specified department. Note that it is not possible to delete a department while it has assigned users, so all the users must be unassigned from the department before deleting it.

DELETE /api/1.0/{workspace}/department/{dep_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringUnique ID of the department to be deleted.

Result:

If the department was deleted, the HTTP status code is set to 200 and nothing is returned. Otherwise, it is set to 400 or greater and an error object is returned like the following:

{
  error: {
    code:    400,
    message: "Bad Request: Department cannot be deleted while has assigned users."
  }
}

PHP Example:

$apiServer = "https://example.com";              //set to your ProcessMaker address
$deptId   = "75740355754dd28ba73d7d6082172937";  //set to a department ID to delete it
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department/" . $deptId);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 200) {
   if (isset($oResult) and isset($oResult->error))
      print "Error Code: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
curl_close($ch);

Departments - Users:

Get Users List for Department: GET /department/{dep_uid}/assigned-user

Get a list of the users assigned to a specified department.

GET /api/1.0/{workspace}/department/{dep_uid}/assigned-user

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringUnique ID of department.

Result:

If successful, the HTTP status code is 200 and an array of user objects is returned, like the following:

[
  {
    usr_uid:        "91937880754ca444fc1e7b8079810120",
    usr_username:   "sylvia",
    usr_firstname:  "Sylvia",
    usr_lastname:   "Herrero",
    usr_status:     "VACATION",
    usr_supervisor: true
  },
  {
    usr_uid:        "98883020754dd1f052ee1f1034403381",
    usr_username:   "janedoe",
    usr_firstname:  "Jane",
    usr_lastname:   "Doe",
    usr_status:     "ACTIVE",
    usr_supervisor: false
  }
]

PHP Example:

This example cycles through all the departments, looking for the username "janedoe" and prints out her department. First it calls the GET /departments endpoint to get a list of departments, then it calls the GET /department/{dep_uid}/assigned-user endpoint for each department and searches for the user.

//recursive function to search in the array of departments for a username in the list of members:
function searchInDepts($username, $aDepts) {
   global $apiServer, $accessToken;

   foreach ($aDepts as $oDept) {       
      $ch = curl_init($apiServer . "/api/1.0/workflow/department/{$oDept->dep_uid}/assigned-user");
      curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      $aUsers = json_decode(curl_exec($ch));
      $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);
     
      if ($statusCode != 200) {
         if (isset($aUsers) and isset($aUsers->error))
            exit("Error Code: {$aUsers->error->code}\nMessage: {$aUsers->error->message}\n");
         else
            exit("Error: HTTP status code: $statusCode\n");
      }
     
      foreach ($aUsers as $oUser) {
         if ($oUser->usr_username == $username) {
            return $oDept;
         }
      }

      if ($oDept->has_children != 0) {
         $oRet = searchInDepts($username, $oDept->dep_children);
         if ($oRet)  //if username found, return the department object
            return $oRet;
      }
   }
   return null; //username not found
}  
 
$apiServer = "shttp://example.com"; //set to your ProcessMaker address
$usernameToFind = "janedoe";        //set to a username to find
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "/api/1.0/workflow/departments");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aDepts = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($statusCode != 200) {
   if (isset ($aDepts) and isset($aDepts->error))
      exit("Error code: {$aDepts->error->code}\nMessage: {$aDepts->error->message}\n");
   else
      exit("Error: HTTP status code: $statusCode\n");
}
else {
   $oDeptFound = searchInDepts($usernameToFind, $aDepts);
   if ($oDeptFound)
      print "User '$usernameToFind' is a member of the {$oDeptFound->dep_title} Department.\n";
   else
      print "User '$usernameToFind' is not a member of any department.\n";
}

Available Users List for Department: GET /department/{dep_uid}/available-user

Get a list of the available users, which can be assigned to a specified department. The list contains all users which aren't yet assigned to any department (including users which have "INACTIVE" and "VACATION" status).

GET /api/1.0/{workspace}/department/{dep_uid}/available-user

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringUnique ID of department.

Result:

If successful, the HTTP status code is set to 200 and it returns an array of user objects, like the following:

[
  {
    usr_uid:       "43239845654e76a70ccb5a1012787498",
    usr_username:  "sally",
    usr_firstname: "Sally",
    usr_lastname:  "Slim",
    usr_status:    "INACTIVE"
  },
  {
    usr_uid:       "66065213554dd1feb48fe79020620851",
    usr_username:  "johndoe",
    usr_firstname: "John",
    usr_lastname:  "Doe",
    usr_status:    "ACTIVE"
  }
]

Note that the user objects are not arranged in any particular order.

If an error occurred, the HTTP status code is set to 400 or greater, and an error object is returned, such as:

{
  error: {
    code:    400,
    message: "Bad Request: The department with dep_uid: '54883398754db7993002ae1030708955' does not exist."
  }
}

PHP Example:

Get a list of available users and sort them in alphabetical order according to their full names and print them. All the user objects are placed in the $aUsersWithKeys array which has the full names as the keys and then they are sorted using the ksort() function.

$apiServer = "https://example.com";              //set to your ProcessMaker address
$deptId    = "54883398754db7993002ae1030708956"; //set to a department's unique ID
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department/$deptId/available-user");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aUsers = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($statusCode != 200) {
   if (isset ($oDept) and isset($oDept->error))
      print "Error code: {$oDept->error->code}\nMessage: {$oDept->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
else {
   $aUsersWithKeys = array();
   foreach ($aUsers as $oUser) {
      $fullname = $oUser->usr_firstname . ' ' . $oUser->usr_lastname . ' (' . $oUser->username . ')';
      $aUsersWithKeys[$fullname] = $oUser;
   }
   ksort($aUsersWithKeys, SORT_NATURAL | SORT_FLAG_CASE));
   
   foreach ($aUsersWithKeys as $oUser) {
      print $oUser->usr_firstname . ' ' . $oUser->usr_lastname . ' (' . $oUser->username . ")\n";
   }
}

v.2.8: Assign User to Department: PUT /department/{dep_uid}/assign-user/{usr_uid}

Assign a user to a specified department in version 2.8. If using version 3.0 or later, see POST /department/{dep_uid}/assign-user. If the user is already a member of another department, the user will be transfered to the specified department. If reassigning a user who is a supervisor of another department, see this bug.

PUT /api/1.0/{workspace}/department/{dep_uid}/assign-user/{usr_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringUnique ID of department.
usr_uidStringUnique ID of user to assign to the department.

Result:

If the user was assigned to the department, the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and there is a return object such as:

{
  error: {
    code:    400,
    message: "Bad Request: The user with usr_uid: '43239845654e76a70ccb5a1012787499' does not exist."
  }
}

PHP Example:

$apiServer = "https://example.com";            //set to your ProcessMaker address
$deptId = "75740355754dd28ba73d7d6082172937";  //set to the unique ID of a department
$userId = "14680180454ca4477335a27034362107";  //set to unique ID of user to add to department
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$postParams = array('usr_uid' => $userId);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department/$deptId/assign-user/$userId");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 200) {
   if isset($oResult) and isset($oResult->error)) {
      print "Error Code: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   }
   else {
      print "Error: HTTP status code $statusCode\n";
   }
}
curl_close($ch);

v.3.0+: Assign User to Department: POST /department/{dep_uid}/assign-user

Assign a user to a specified department in version 3.0 and later. If the user is already a member of another department, the user will be transfered to the specified department. If reassigning a user who is a supervisor of another department, see this bug.

POST /api/1.0/{workspace}/department/{dep_uid}/assign-user

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringUnique ID of department.

POST Fields:

NameTypeDescription
usr_uidStringUnique ID of a user to assign to the department.

Result:

If the user was assigned to the department, the HTTP status code is 201 and there is no return object. Otherwise, the HTTP status code is 300 or greater and there is a return object such as:

{
  error: {
    code:    400,
    message: "Bad Request: The user with usr_uid: '43239845654e76a70ccb5a1012787499' does not exist."
  }
}

PHP Example:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "p4sSw0rD");

$userId = '55625662755e0e42fe83f41018778834';  
$deptId = '49874200755e894791651c7054311031';
             
$aVars = array(
   'usr_uid' => $userId
);
   
$url = "/api/1.0/workflow/department/$deptId/assign-user";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   print "User $userId added to the Accounting Department.\n";
}      

Unassign User from Department: PUT /department/{dep_uid}/unassign-user/{usr_uid}

Unassign a user from a department, so no longer a member of the department. If unassigning a supervisor from a department, see this bug.

PUT /api/1.0/{workspace}/department/{dep_uid}/unassign-user/{usr_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringUnique ID of department.
usr_uidStringUnique ID of the user to unassign from the department.

Result:

If the user was unassigned from the department, the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and there is a return object such as:

{
  error: {
    code:    400,
    message: "Bad Request: The user with usr_uid: '43239845654e76a70ccb5a1012787499' does not exist."
  }
}


PHP Example:

$apiServer = "https://example.com";            //set to your ProcessMaker address
$deptId = "75740355754dd28ba73d7d6082172937";  //set to the unique ID of a department
$userId = "14680180454ca4477335a27034362107";  //set to unique ID of user to remove from department
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$postParams = array('usr_uid' => $userId);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department/$deptId/unassign-user/$userId");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 200) {
   if isset($oResult) and isset($oResult->error)) {
      print "Error Code: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   }
   else {
      print "Error: HTTP status code $statusCode\n";
   }
}
curl_close($ch);

Set Manager for Department: PUT /department/{dep_uid}/set-manager/{usr_uid}

Set a user to be the manager (supervisor) for a department. The other members of the department will report to the manager, as well as the managers of subdepartments. Note that this endpoint has a number of outstanding bugs.

PUT /api/1.0/{workspace}/department/{dep_uid}/set-manager/{usr_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
dep_uidStringUnique ID of the department.
usr_uidStringUnique ID of the user to become the the manager of the department.

Result:

If the manager was successfully set, then the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and an error object is returned, like the following:

{
  error: {
    code:    400,
    message: "Bad Request: The user with usr_uid: '43239845654e76a70ccb5a1012787499' does not exist."
  }
}

PHP Example:

$apiServer = "https://example.com";            //set to your ProcessMaker address
$deptId = "75740355754dd28ba73d7d6082172937";  //set to the unique ID of a department
$userId = "14680180454ca4477335a27034362107";  //set to unique ID of user to become supervisor
 
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken();
 
$postParams = array('usr_uid' => $userId);
 
$ch = curl_init($apiServer . "/api/1.0/workflow/department/$deptId/set-manager/$userId");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $accessToken"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
$oResult = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
if ($statusCode != 200) {
   if isset($oResult) and isset($oResult->error)) {
      print "Error Code: {$oResult->error->code}\nMessage: {$oResult->error->message}\n";
   }
   else {
      print "Error: HTTP status code $statusCode\n";
   }
}
curl_close($ch);

Roles

The following REST endpoints are used to manage roles in ProcessMaker.

Roles

1. Get a list of all roles

2. Get a single role

3. Create a role

4. Update a role

5. Delete a role

Roles - Users

6. List assigned users to a role

7. List available users to assign to a role

8. Assign users to a role

9. Unassign user from a role

Roles - Permissions

10. List assigned permissions to a role

11. List available permissions to assign to a role

12. Assign permissions to a role

13. Unassign permissions from a role

Get Roles List: GET /roles

Get a list of the roles in the workspace.

GET /api/1.0/{workspace}/roles

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/roles
Optional filters
filter={text}Case insensitive text to search for in the role codes (but not the role names). Remember to URL encode in UTF-8, if it contains spaces, symbols or non-ASCII characters, using a function such as urlencode() in PHP or encodeURIComponent() in JavaScript./api/1.0/workflow/roles?filter=reviewer
start={number}Integer which indicates the initial position of the role./api/1.0/workflow/roles?start=20&limit=10
limit={number}Integer which limits the number of roles returned/api/1.0/workflow/roles?start=30&limit=10

Result:

If successful, the HTTP status is 200 (OK) and an array of role objects is returned, such as:
[
   {
      "rol_uid": "00000000000000000000000000000002",      
      "rol_code": "PROCESSMAKER_ADMIN",
      "rol_name": "System Administrator",
      "rol_status": "ACTIVE",
      "rol_system": "00000000000000000000000000000002",        
      "rol_create_date": "2015-03-19 07:55:48",
      "rol_update_date": "",
      "rol_total_users": 2
        },
        {
      "rol_uid": "00000000000000000000000000000003",      
      "rol_code": "PROCESSMAKER_OPERATOR",
      "rol_name": "Operator",
      "rol_status": "ACTIVE",
      "rol_system": "00000000000000000000000000000002",        
      "rol_create_date": "2015-03-20 08:45:09",
      "rol_update_date": "",
      "rol_total_users": 0
        }
]

PHP example

Print out a list of the roles with "ACTIVE" status and the number of users assigned to each role.

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "p4sSw0rD");

$url = "/api/1.0/workflow/roles";
$oRet = pmRestRequest("GET", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   foreach ($oRet->response as $oRole) {
      print "Active Roles:\n";
      if ($oRole->rol_status == 'ACTIVE') {
          print "  {$oRole->rol_name}\t{$oRole->rol_total_users}\n";
      }
   }
}

Get Role Information: GET /role/{rol_uid}

Get information about a specified role.

GET /api/1.0/{workspace}/role/{rol_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
rol_uidStringRole UID

Result:

If successful, the HTTP status is set to 200 and an object with information about the role is returned, such as

{
        "rol_uid":         "00000000000000000000000000000002",            
        "rol_code":        "PROCESSMAKER_ADMIN",
        "rol_name":        "System Administrator",
        "rol_status":      "ACTIVE",
        "rol_system":      "00000000000000000000000000000002",  
        "rol_create_date": "2015-01-30 23:59:59",
        "rol_update_date": "",
        "rol_total_users": 2
}

Create Role: POST /role

Create a new role.

POST /api/1.0/{workspace}/role

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role

POST fields:

NameDescription
rol_codeThe role code, which is an identifier consisting of letters, numbers and underscores ("_"). It may not contain any spaces or special characters.
rol_nameThe role name, which is any identifier which can contain any type of characters and is displayed in the ProcessMaker.
rol_statusOptional. Role status, which may be "ACTIVE" or "INACTIVE". If not specified, then set to "ACTIVE" by default. If set to "INACTIVE", any users assigned to the role will not be able to login to ProcessMaker, nor may any cases be assigned to those users.

Result:

If the role was created, then the HTTP status code is set to 201 (Created) and an object containing information about the new role is returned, such as:

{
   "rol_uid":         "55625662755e0e42fe83f41018778834",        
   "rol_code":        "Case_Reviewer",
   "rol_name":        "Case Reviewer",
   "rol_status":      "ACTIVE",
   "rol_system":      "00000000000000000000000000000002",  
   "rol_create_date": "2015-11-18 22:45:52",
   "rol_update_date": "",
   "rol_total_users": 0
}

Update Role: PUT /role/{rol_uid}

Update information about a specified role.

PUT /api/1.0/{workspace}/role/{rol_uid}

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988
rol_uidUnique ID of role/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988

POST fields:

NameDescription
rol_codeOptional. The role code, which is an identifier consisting of letters, numbers and underscores ("_"). It may not contain any spaces or special characters.
rol_nameOptional. The role name, which is any identifier which can contain any type of characters and is displayed in the ProcessMaker.
rol_statusOptional. Role status, which may be "ACTIVE" or "INACTIVE". If set to "INACTIVE", any users assigned to the role will not be able to login to ProcessMaker, nor may any cases be assigned to those users.

Result:

If the information about a case has been updated, then the HTTP status is set to 200 (OK) and there is no return object.

PHP example:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "p4sSw0rD");
$roleId = '92775102755E9beea04c394090645988';
             
$aVars = array(
   'rol_code'   => 'Consultant',
   'rol_name'   => 'Consultant',
   'rol_status' => 'INACTIVE'
);
   
$url  = "/api/1.0/workflow/role/$roleId";
$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   print "Role changed to 'Consultant'.\n";
}  

Delete Role: DELETE /role/{rol_uid}

Delete a specified role. Note that it is not possible to delete a role which still has assigned users, so all users must be assigned to different roles before deleting the role.

DELETE /api/1.0/{workspace}/role/{rol_uid}

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988
rol_uidUnique ID of role/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988

Result:

If the role is deleted, the HTTP status code is set to 200 and there is no return object. If the HTTP status code is 300 or greater than an error occurred and a error object will usually be returned, such as:
{
  "error": {
     "code":    400,
     "message": "Bad Request: This role cannot be deleted while it still has some assigned users."
  }
}

PHP example:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "p4sSw0rD");

$roleId = '92775102755E9beea04c394090645988';
$url  = "/api/1.0/workflow/role/$roleId";
$oRet = pmRestRequest("DELETE", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   print "Role deleted.\n";
}  


ROLES - USERS

Get Users with Role: GET /role/{rol_uid}/users

Get a list of the users assigned to a role.

GET /api/1.0/{workspace}/role/{rol_uid}/users

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000003/users
rol_uidUnique ID of role/api/1.0/workflow/role/00000000000000000000000000000003/users
Optional filters:
filter={text}Case insensitive text to search for users in their first name, last name or username. Remember to URL encode in UTF-8, if it contains spaces, symbols or non-ASCII characters, using a function such as urlencode() in PHP or encodeURIComponent() in JavaScript./api/1.0/workflow/role/00000000000000000000000000000003/users?filter=mary
start={number}Integer which indicates the initial position of the user in the list./api/1.0/workflow/role/00000000000000000000000000000003/users?start=20&limit=10
limit={number}Integer which limits the number of users returned./api/1.0/workflow/role/00000000000000000000000000000003/users?start=30&limit=10

Result:

If successful, the HTTP status code is set to 200 (OK) and an array of user objects is returned, such as:

[
   {
      "usr_uid":       "93284375552975187b60962076613156",
      "usr_username":  "jdoe",
      "usr_firstname": "Jane",
      "usr_lastname":  "Doe",
      "usr_status":    "ACTIVE"
   },
   {
      "usr_uid":       "548562415529751a1e28ed0037315520",
      "usr_username":  "bsmith",
      "usr_firstname": "Bob",
      "usr_lastname":  "Smith",
      "usr_status":    "ACTIVE"
   }
]

If no users are assigned to the role, then an empty array will be returned.

Available Users for Role: GET /role/{rol_uid}/available-users

Get a list of users who currently are assigned to other roles and are available to be reassigned to the specified role.

GET /api/1.0/{workspace}/role/{rol_uid}/available-users
Note: The "admin" user may be returned by this endpoint, but the "admin" user cannot be reassigned to another role.

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000003/available-users
rol_uidUnique ID of role/api/1.0/workflow/role/00000000000000000000000000000003/available-users
Optional filters:
filter={text}Case insensitive text to search for in the first name, last name or username of users. Remember to URL encode in UTF-8, if it contains spaces, symbols or non-ASCII characters, using a function such as urlencode() in PHP or encodeURIComponent() in JavaScript./api/1.0/workflow/role/00000000000000000000000000000003/available-users?filter=mary
start={number}Integer which indicates the initial position of the user in the list./api/1.0/workflow/role/00000000000000000000000000000003/available-users?start=20&limit=10
limit={number}Integer which limits the number of users returned./api/1.0/workflow/role/00000000000000000000000000000003/available-users?start=30&limit=10

Result:

If successful, the HTTP status code is set to 200 (OK) and an array of user objects is returned, such as:

[
   {
      "usr_uid":       "93284375552975187b60962076613156",
      "usr_username":  "jdoe",
      "usr_firstname": "Jane",
      "usr_lastname":  "Doe",
      "usr_status":    "ACTIVE"
   },
   {
      "usr_uid":       "548562415529751a1e28ed0037315520",
      "usr_username":  "bsmith",
      "usr_firstname": "Bob",
      "usr_lastname":  "Smith",
      "usr_status":    "ACTIVE"
   }
]

If no users are assigned to other roles, then an empty array will be returned.

Assign User to Role: POST /role/{rol_uid}/user

Assign a user to a role.

POST /api/1.0/{workspace}/role/{rol_uid}/user

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000003/user
rol_uidUnique ID of role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'./api/1.0/workflow/role/00000000000000000000000000000003/user

POST Fields:

NameTypeDescription
usr_uidStringUnique ID of user to be assigned to a role.

Result:

If the user has been successfully assigned to a role, then the HTTP status is set to 201 (Created) and there is no return object.

Note that the "admin" user may not be reassigned to a different role, which generates the following error:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The role of the administrator can not be changed!"
    }
}

PHP example

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "p4aSw0rD");

$userId = '55625662755e0e42fe83f41018778834';  
$roleId = '00000000000000000000000000000003'; //Operator role
             
$aVars = array(
   'usr_uid' => $userId
);

$url = "/api/1.0/workflow/role/$roleId/user";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);  

if ($oRet->status == 201) {
   print "User $userId reassigned to Operator role.\n";
}

Unassign User from Role: DELETE /role/{rol_uid}/user/{usr_uid}

Unassign (remove) a user from a role. It is not recommended to call this endpoint, unless wishing for the user to have no role and be unable to login or be used in any capacity in ProcessMaker. The user will need to be reassigned to another role in order to have any function inside ProcessMaker.

DELETE /api/1.0/{workspace}/role/{rol_uid}/user/{usr_uid}

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000003/user/55625662755e0e42fe83f41018778834
rol_uidUnique ID of role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'./api/1.0/workflow/role/00000000000000000000000000000003/user/55625662755e0e42fe83f41018778834
usr_uidUnique ID of user/api/1.0/workflow/role/00000000000000000000000000000003/user/55625662755e0e42fe83f41018778834

Result:

If unassigned from the role, the HTTP status code is set to 200 (OK) and there is no return object. Otherwise, the HTTP status code is set to 300 or greater and an error object is often returned, such as:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The user with usr_uid: 55625662755e0e42fe83f41018778834 is not assigned to the role."
   }
}

PHP Example

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "p4sSw0rD");

$userId = '55625662755e0e42fe83f41018778834';  
$roleId = '00611547a59021abb767b6e63f772ee2';

$url = "/api/1.0/workflow/role/$roleId/user/$userId";
$oRet = pmRestRequest("DELETE", $url, $aVars, $oToken->access_token);  

if ($oRet->status == 200) {
   print "User's role removed.\n";
}


ROLES - PERMISSIONS

Permissions List for Role: GET /role/{rol_uid}/permissions

Get a list of the permissions assigned to a specified role.

GET /api/1.0/{workspace}/role/{rol_uid}/permissions

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000002/permissions
rol_uidUnique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'./api/1.0/workflow/role/00000000000000000000000000000002/permissions
Optional filters:
filter={text}Case-insensitive text to search for in the permission codes./api/1.0/workflow/role/00000000000000000000000000000002/permissions?filter=setup
start={number}Position of the initial permission be returned/api/1.0/workflow/role/00000000000000000000000000000002/permissions?start=5&limit=5
limit={number}Number of permissions to be returned./api/1.0/workflow/role/00000000000000000000000000000002/permissions?start=5&limit=5

Result:

If successful the HTTP status code is 200 and the response is an array of permission objects for the role, such as:
[
   {
      "per_uid": "00000000000000000000000000000001",
      "per_code": "PM_LOGIN",
      "per_name": "Login"
   },
   {
      "per_uid": "00000000000000000000000000000005",
      "per_code": "PM_CASES",
      "per_name": "Create cases"
   }
]

PHP example:

Print out the list of permissions in the PROCESSMAKER_ADMIN role:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "mary", "p4sSw0rD");
 
$roleId = '00000000000000000000000000000002';
$url = "/api/1.0/workflow/role/$roleId/permissions";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);  

if ($oRet->status == 200) {
   print "Permissions in role $roleId:\n";
   foreach ($oRet->response as $oPermission) {
      print "\t$oPermission->per_code\n";
   }
}

Available Permissions for Role: GET /role/{rol_uid}/available-permissions

Get a list of the available permissions, which can be assigned to a specified role.

GET /api/1.0/{workspace}/role/{rol_uid}/available-permissions

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000003/available-permissions
rol_uidUnique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'./api/1.0/workflow/role/00000000000000000000000000000003/available-permissions
Optional filters:
filter={text}Case-insensitive text to search for in the permission codes./api/1.0/workflow/role/00000000000000000000000000000003/available-permissions?filter=setup
start={number}Position of the initial permission be returned/api/1.0/workflow/role/00000000000000000000000000000003/available-permissions?start=5&limit=5
limit={number}Number of permissions to be returned./api/1.0/workflow/role/00000000000000000000000000000003/available-permissions?start=5&limit=5

Result:

If successful the HTTP status code is 200 and the response is an array of available permission objects for the role, such as:
[
   {
      "per_uid":  "00000000000000000000000000000006",
      "per_code": "PM_ALLCASES",
      "per_name": "All Cases"
   },
   {
      "per_uid":  "00000000000000000000000000000018",
      "per_code": "PM_CANCELCASE",
      "per_name": "Cancel cases"
   }
]

PHP example:

Search through the list of available permissions for the Operator role to see whether it includes the PM_DASHBOARD permission. If available, then assign it to the Operator role:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "mary", "p4sSw0rD");
 
$roleId = '00000000000000000000000000000003'; //Operator role
$url = "/api/1.0/workflow/role/$roleId/available-permissions";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);  

if ($oRet->status == 200) {
   $dashboardAvailable = false;
   foreach ($oRet->response as $oPermission) {
      if ($oPermission->per_code == 'PM_DASHBOARD') {
         $dashboardAvailable = true;
         $permissionId = $oPermission->per_uid;
   }
   //If PM_DASHBOARD available, then assign it to role
   if ($dashboardAvailable) {
      $aVars = array(
         'per_uid' => $permissionId
      );
      $url = "/api/1.0/workflow/role/$roleId/permission";
      $oRet2 = pmRestRequest("POST", $url, $aVars, $oToken->access_token);
      if ($oRet2->status == 201) {
          print "PM_DASHBOARD assigned to Operator role.\n";
      }
   }
   else {
      print "PM_DASHBOARD is already assigned to the Operator role.\n";
   }  
}

Assign Permission to Role: POST /role/{rol_uid}/permission

Assign a permission to a role.

POST /api/1.0/{workspace}/role/{rol_uid}/permission

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000003/permission
rol_uidUnique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'./api/1.0/workflow/role/00000000000000000000000000000003/permission

POST Fields:

NameTypeDescription
per_uidStringUnique ID of the permission to assign to a role.

Result:

If the permission is successfully assigned to the role, then the HTTP status code is set to 201 (Created) and there is no response.

PHP example:

This example assigns the PM_REASSIGNCASE permission to the Operator role.

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "mary", "p4sSw0rD");
 
$roleId       = '00000000000000000000000000000003'; //Operator role
$permissionId = '00000000000000000000000000000007'; //PM_REASSIGNCASE permission
$aVars = array(
   'per_uid' => $permissionId
);
$url  = "/api/1.0/workflow/role/$roleId/permission";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);
     
if ($oRet->status == 201) {
   print "PM_REASSIGNCASE permission assigned to the Operator role.\n";
}

Unassign Permission from Role: DELETE /role/{rol_uid}/permission/{per_uid}

Unassign (remove) a permission from a role.

DELETE /api/1.0/{workspace}/role/{rol_uid}/permission/{per_uid}

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/role/00000000000000000000000000000003/permission/00000000000000000000000000000007
rol_uidUnique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'./api/1.0/workflow/role/00000000000000000000000000000003/permission/00000000000000000000000000000007
per_uidUnique ID of the permission to unassign from the role./api/1.0/workflow/role/00000000000000000000000000000003/permission/00000000000000000000000000000007

Result:

If the permission is successfully unassigned from the role, then the HTTP status code is set to 200 (OK) and there is no response.

Note: Permissions may not be unassigned from the Administrator role (PROCESSMAKER_ADMIN). Trying to unassign from this role will cause the following error:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The permissions of the "PROCESSMAKER_ADMIN" role can not be changed."
   }
}

PHP example:

This example unassigns the PM_REASSIGNCASE permission from the Operator role.

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "mary", "p4sSw0rD");
 
$roleId       = '00000000000000000000000000000003'; //Operator role
$permissionId = '00000000000000000000000000000007'; //PM_REASSIGNCASE permission

$url  = "/api/1.0/workflow/role/$roleId/permission/$permissionId";
$oRet = pmRestRequest("DELETE", $url, null, $oToken->access_token);
     
if ($oRet->status == 200) {
   print "PM_REASSIGNCASE permission unassigned from the Operator role.\n";
}

PM Tables

The following REST endpoints are used to manage PM tables in ProcessMaker:

1. Get a list of PM Tables

2. Get a single PM Table

3. Get the data of a PM Table

4. Create a new PM Table

5. Create data in a PM Table

6. Update a PM Table

7. Update data of a PM Table

8. Delete a PM Table

9. Delete data of a PM Table

PM Tables:

NameDescriptionTypeValue
pmt_tab_namePM Table nameString"name" o "pmt_NAME"(String)
pmt_tab_dscPM Table descriptionString"PM table description"(String)
fieldsPM Table fieldsArray
fld_dynField name known in a DynaFormString"Acceptance"(String)
fld_nameField name for the MySQL table creationString"ACCEPTED" (String)
fld_labelField label in the PM graphicString"PM Table description"(String)
fld_typeMySQL field type, which may be: "BOOLEAN", "TINYINT", "SMALLINT", "INTEGER", "BIGINT", "DOUBLE", "FLOAT", "REAL", "DECIMAL", "CHAR", "VARCHAR", "LONGVARCHAR", "DATE", "TIME" or "DATETIME"String"VARCHAR"(String MySQL type field)
fld_sizeMySQL field sizeInteger23 (Numeric)


Available methods:

PM Tables List: GET /pmtable

Get a list of the PM tables in the workspace. It does not include any Report Tables.

GET /api/1.0/{workspace}/pmtable

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/pmtable

Result:

If successful, the HTTP status is set to 200 (OK) and an array of PM Table objects is returned:

[ Start array.
{ Start PM Table object.
"pmt_uid", Unique ID of the PM Table.
"pmt_tab_name", Table in the wf_{workspace} database.
"pmt_tab_description", Description of the PM Table.
"pmt_tab_class_name", PHP class name for the PM Table.
"pmt_num_rows", Number of records in the PM Table.
"fields": [ An array of fields in the PM Table.
{ Start Field object.
"fld_uid", Unique ID of the field.
"fld_index": Index number of the field, counting from the number 0.
"fld_name": Name of the field in the database.
"fld_description": Label of the field.
"fld_type": Type of the field.
"fld_size": Field size.
"fld_null": Set to "1" if a NULL (empty) value is allowed. Otherwise, set to "0".
"fld_auto_increment":Set to "1" if the field will be auto-incremented. Otherwise, set to "0".
"fld_key": Set to "1" if a key field, meaning that its values are unique. Otherwise, set to "0".
"fld_table_index": Set to "1" if the field will be indexed. Otherwise, set to "0".
}, End Field object.
... Any additional Field objects.
] End array of Field objects.
}, End PM Table object.
... Any additional PM Table objects.
] End array of PM Table objects.

For example:

[
   {
      "pmt_uid":             "33532851355ef56860e8297082884997",
      "pmt_tab_name":        "PMT_CLIENTS",
      "pmt_tab_description": "Table with information about clients",
      "pmt_tab_class_name":  "PmtClients",
      "pmt_num_rows":        28,
      "fields":              
      [
         {
            "fld_uid":            "22501963155ef568633c460054115944",
            "fld_index":          "0",
            "fld_name":           "ID",
            "fld_description":    "ID",
            "fld_type":           "BIGINT",
            "fld_size":           "8",
            "fld_null":           "0",
            "fld_auto_increment": "1",
            "fld_key":            "1",
            "fld_table_index":    "0"
         },
         {
            "fld_uid":            "58722687755ef568650b502051774480",
            "fld_index":          "1",
            "fld_name":           "COMPANY_NAME",
            "fld_description":    "CompanyName",
            "fld_type":           "VARCHAR",
            "fld_size":           "50",
            "fld_null":           "0",
            "fld_auto_increment": "0",
            "fld_key":            "0",
            "fld_table_index":    "0"
         }
      ]
   }
]      

PHP Example:

Print out the PM Tables and the fields in each table.

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "mary", "p4sSw0rD");
   
$url = "/api/1.0/workflow/pmtable";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);  

if ($oRet->status == 200) {
   foreach ($oRet->response as $oPmTable) {
      print "Table {$oPmTable->pmt_tab_name}:\n";
      foreach ($oPmTable->fields as $oField) {
         print "\t{$oField->fld_name} ({$oField->fld_type})\n";
      }
   }
}

Get PM Table Structure: GET /pmtable/{pmt_uid}

Get the structure from a specified PM Table, including a list of its fields and their properties.

GET /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997
pmt_uidUnique ID of the PM Table/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997

Result:

If successful, the HTTP status is set to 200 (OK) and a PM Table object is returned, such as:

{
   "pmt_uid":             "33532851355ef56860e8297082884997",
   "pmt_tab_name":        "PMT_CLIENTS",
   "pmt_tab_description": "Table with information about clients",
   "pmt_tab_class_name":  "PmtClients",
   "pmt_num_rows":        28,
   "fields":              
   [
      {
         "fld_uid":            "22501963155ef568633c460054115944",
         "fld_index":          "0",
         "fld_name":           "ID",
         "fld_description":    "ID",
         "fld_type":           "BIGINT",
         "fld_size":           "8",
         "fld_null":           "0",
         "fld_auto_increment": "1",
         "fld_key":            "1",
         "fld_table_index":    "0"
      },
      {
         "fld_uid":            "58722687755ef568650b502051774480",
         "fld_index":          "1",
         "fld_name":           "COMPANY_NAME",
         "fld_description":    "CompanyName",
         "fld_type":           "VARCHAR",
         "fld_size":           "50",
         "fld_null":           "0",
         "fld_auto_increment": "0",
         "fld_key":            "0",
         "fld_table_index":    "0"
      }
   ]
}      

PHP Example:

Print out the number of records in a PM Table and list the fields in the PM Table.

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "mary", "p4sSw0rD");

$tableId = '33532851355ef56860e8297082884997';  
$url = "/api/1.0/workflow/pmtable/$tableId";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);  

if ($oRet->status == 200) {
   print "Table {$oRet->response->pmt_tab_name} has {$oRet->response->pmt_num_rows} records\n";
}

Get PM Table Data: GET /pmtable/{pmt_uid}/data

Get the data (records) from a PM table.

GET /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data
pmt_uidUnique ID of the PM Table/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data

Optional GET Parameters:

NameTypeDescription
q={where:spec}stringThis is a generic way to search via the filterType "where" (only this one is supported) and where
spec is the specification of the filter, for example for a where filter, this is a logical condition that the results must match
For example, GET /api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data?q={"where": {"name": "Felix", "lastname": "Mondaca"}} would return the row of the PM Table that has the values: "Felix", "Mondaca" in the fields "name" and "lastname" respectively .

Result:

If successful, the HTTP status is set to 200 (OK) and an object is returned with the rows of data in the PM Table and the number of rows.

For example:

{
   "rows": [
      {
         "id":           "1",
         "company_name": "Western Fuels Corp.",
         "address":      "235 W. Elm St, Greenwood, NC 34928",
         "has_contract": "1",
         "__index__":    "lg"
      },
      {
         "id":           "2",
         "company_name": "Wrightspeed Transport",
         "address":      "2845 MLK Drive, Los Angeles, CA 28764",
         "has_contract": "0",
         "__index__":    "lw"
      },
      {
         "id":           "3",
         "company_name": "Albemarle Chemical",
         "address":      "2810 E. 26th St., Brooklyn, NY 98245",
         "has_contract": "1",
         "__index__":    "mA"
      }
   ],
   "count": 3
}

Note: The field names are automatically converted to lowercase.

Note: Integers, floating-point numbers (real numbers) and boolean values are converted to strings. In the above example, the id is an integer and the has_contract is a boolean in MySQL. Also, the __index__ field is automatically created by MySQL to index the PM Table.

PHP Example:

Print out the records in a PM Table in an HTML table. First get the structure of the PM Table with GET /api/1.0/workflow/pmtable/{pmt_uid} in order to print out the label (description) of each field in the headers of the HTML table. Then, get the records with GET /api/1.0/workflow/pmtable/{pmt_uid}/data and print out each record as a record in the HTML table.

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "mary", "p4sSw0rD");

$tableId = '33532851355ef56860e8297082884997';  
$url = "/api/1.0/workflow/pmtable/$tableId";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   $aFields = array(); //array of fields in the PM Table
   print "\n" . '<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse;">' .
      "<tbody>\n<tr>";
   
   foreach ($oRet->response->fields as $oField) {  
      $aFields[] = strtolower($oField->fld_name); //convert field names to lowercase
      print "<th>{$oField->fld_description}</th>";
   }
   print "</tr>\n";
   
   $url2  = "/api/1.0/workflow/pmtable/$tableId/data";
   $oRet2 = pmRestRequest("GET", $url2, null, $oToken->access_token);  
   
   if ($oRet2->status == 200) {
      foreach ($oRet2->response->rows as $oRow) {
         $aRow = get_object_vars($oRow); //convert object to associative array
         print "<tr>\n";
         foreach ($aFields as $fieldName) {
            print '  <td>' . $aRow[$fieldName] . "</td>\n";
         }
         print "</tr>\n";
      }
   }
   print "</tbody></table>\n";      
}

Create PM Table: POST /pmtable

Create a new PM Table.

POST /api/1.0/{workspace}/pmtable

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/pmtable

POST Fields:

NameDescription
{ Start object.
"pmt_tab_name", The name of the PM Table, which only consists of ASCII letters, numbers and underscores ("_"). It will automatically be converted to UPPERCASE. It is strongly recommended that it begin with "PMT_".
"pmt_tab_dsc", Optional. Description of the PM Table.
"fields" An array of field objects.
[ Start the array.
{ Start object defining field.
"fld_name",The field name, which should only contain ASCII letters, numbers and underscores ("_"). It will automatically be converted to UPPERCASE. It is recommended that it be in UPPERCASE.
"fld_label,The field's label.
"fld_type",The field type, which can be:
  • BIGINT: An integer of 8 bytes between -9223372036854775808 and 9223372036854775807.
  • BOOLEAN: A binary value of either 1 (true) or 0 (false), but this stored as an INTEGER in the database.
  • CHAR: A string of a characters between 0 and 255 in length. The number of characters stored in the database is fixed. If the field size is 100, then 100 characters are stored in the database, even if the value in the field has fewer characters.
  • DATE: A date in the 'YYYY-MM-DD' format. The supported range is '1000-01-01' to '9999-12-31'.
  • DATETIME: A datetime in the 'YYYY-MM-DD HH:MM:SS' format. The supported range is '1000-01-01 00:00:00' to '9999-12-31 23:59:59'.
  • DECIMAL: A decimal number, which has exactly 2 decimal digits. This is the recommended type when using currency.
  • DOUBLE: A decimal number of 8 bytes. The supported range is -1.7976931348623157E+308 to -2.2250738585072014E-308, 0, and 2.2250738585072014E-308 to 1.7976931348623157E+308.
  • FLOAT: A decimal number of 4 bytes. The supported range is -3.402823466E+38 to -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38.
  • INTEGER: An integer of 4 bytes between -2147483648 and 2147483647.
  • LONGVARCHAR: A string of a variable number of characters, between 0 and 16,777,215 characters long. This is a synonym for a MEDIUMTEXT field.
  • REAL: A synonym for DOUBLE (unless the REAL_AS_FLOAT SQL mode is enabled).
  • SMALLINT: An integer of 2 bytes between -32768 and 32767.
  • TIME: The time in 'HH:MM:SS' format.
  • TIMESTAMP: A synonym for DATETIME.
  • TINYINT: An integer of 1 byte between -128 and 127.
  • VARCHAR: A string of a variable number of characters, between 0 and 255 characters in length before MySQL 5.0.3 and between 0 and 65,535 characters in MySQL 5.0.3 and later.
"fld_size",The field size is required for CHAR and VARCHAR fields, where it sets the maximum number of allowed characters. The field size is optional for BOOLEAN, TINYINT, SMALLINT, INTEGER and BIGINT fields, where it sets the maximum number of allowed digits. It is also optional for FLOAT, REAL and DECIMAL fields, where it sets the maximum number of digits before the decimal point. The number of decimal digits cannot be specified, although it is automatically set to 2 in DECIMAL fields. For example, setting fld_size to 4 allows numbers between -9999.X and 9999.X with the number of decimals determined by the maximum for the data type.
The fld_size should NOT be included in DOUBLE, DATE, TIME, DATETIME, TIMESTAMP and LONGVARCHAR fields or it will cause a 400 error with no response object. Likewise, a 400 error will be caused if the fld_size is set to a value larger than the allowed size, such as 50 for an INTEGER.
"fld_null", Optional. Set to 1 if this field may have a value of NULL, meaning "no data". Otherwise, set to 0, meaning that the field must have a value. If not included, then set to 1 by default.
"fld_autoincrement",Optional. Set to 1 if this field will be auto-incremented, meaning that the value will be automatically inserted as the maximum existing value in the field plus 1. This option is recommended for ID fields. Otherwise set to 0, which is the default.
"fld_key" Optional. Set to 1 if this field should be a primary key field, meaning that its value will be unique and it will used to index the table. Otherwise set to 0, which is the default if not included.
} End of object defining the field.
... Any additional field objects.
] End array of field objects.
} End object.

Result:

If the table is created, then the HTTP status code is set to 201 (Created) and a object is returned with information about the new PM Table. See the JSON example below.

JSON example:

Request:

{
   "pmt_tab_name":    "PMT_CONTRACTS",
   "pmt_tab_dsc":     "Clients for accounting services",
   "fields": [
      {
         "fld_name":          "ID",
         "fld_label":         "ID number",
         "fld_type":          "INTEGER",
         "fld_size":          8,
         "fld_key":           1,
         "fld_null":          0,
         "fld_autoincrement": 1
      },
      {
         "fld_name":          "NAME",
         "fld_label":         "Contractor Name",
         "fld_type":          "VARCHAR",
         "fld_size":          120
      },
      {
         "fld_name":          "AMOUNT",
         "fld_label":         "Contract Amount",
         "fld_type":          "DECIMAL"
      },
      {
         "fld_name":          "DUE_DATE",
         "fld_label":         "Contract Due Date",
         "fld_type":          "DATE"
      }
   ]
}

Response:

{
   "pmt_uid":             "83869640955f217bb427890052454465",
   "pmt_tab_name":        "PMT_CONTRACTS",
   "pmt_tab_description": "Contracts for accounting services",
   "pmt_tab_class_name":  "PmtContracts",
   "pmt_num_rows":        0,
   "fields":              
   [
      {
         "fld_uid":            "52437664155f217bb6f79b6006806943",
         "fld_index":          0,
         "fld_name":           "ID",
         "fld_description":    "ID number"
         "fld_type":           "INTEGER"
         "fld_size":           8,
         "fld_null":           0,
         "fld_auto_increment": 1,
         "fld_key":            1,
         "fld_table_index":    0
      },
      {
         "fld_uid":            "78554318355f217bb8ea6b4079739653",
         "fld_index":          1,
         "fld_name":           "NAME",
         "fld_description":    "Contractor Name",
         "fld_type":           "VARCHAR",
         "fld_size":           120,
         "fld_null":           1,
         "fld_auto_increment": 0,
         "fld_key":            0,
         "fld_table_index":    0
      },
      {
         "fld_uid":            "11719892455f217bb999165017574602",
         "fld_index":          2,
         "fld_name":           "AMOUNT",
         "fld_description":    "Contract Amount",
         "fld_type":           "DECIMAL",
         "fld_size":           NULL,
         "fld_null":           1,
         "fld_auto_increment": 0,
         "fld_key":            0,
         "fld_table_index":    0
      },
      {
         "fld_uid":            "60151324555f217bba48057032011257",
         "fld_index":          3,
         "fld_name":           "DUE_DATE",
         "fld_description":    "Contract Due Date",
         "fld_type":           "DATE",
         "fld_size":           NULL,
         "fld_null":           1,
         "fld_auto_increment": 0,
         "fld_key":            0,
         "fld_table_index":    0
      }
   ]
}

PHP example:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "sample");

$aVars = array(
   "pmt_tab_name" => "PMT_CONTRACTS",
   "pmt_tab_dsc"  => "Contracts for accounting services",
   "fields"       => array(
      array(
         "fld_name"          => "integer_",
         "fld_label"         => "ID number",
         "fld_type"          => "INTEGER",
         "fld_key"           => 1,
         "fld_size"          => 8,
         "fld_null"          => 0,
         "fld_autoincrement" => 1
      ),
      array(
         "fld_name"  => "NAME",
         "fld_label" => "Contractor Name",
         "fld_type"  => "VARCHAR",
         "fld_size"  => 120
      ),
      array(
         "fld_name"  => "AMOUNT",
         "fld_label" => "Contract Amount",
         "fld_type"  => "DECIMAL"
      ),
      array(
         "fld_name"  => "DUE_DATE",
         "fld_label" => "Contract Due Date",
         "fld_type"  => "DATE"
      )  
   )
);

$url = "/api/1.0/workflow/pmtable";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);
       
if ($oRet->status == 201) {
   print "PM Table with UID '{$oRet->response->pmt_uid}' created.\n";
}

Note: If using PHP, the POST variables will need to be passed through the http_build_query() which will cause problems with fields which include the fld_size. The ProcessMaker source code needs to be changed to avoid an error.

Add PM Table Data: POST /pmtable/{pmt_uid}/data

Add a new record to a PM Table.

POST /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/pmtable/22815673755f209dd749c90081062413/data
pmt_uidUnique ID of PM Table/api/1.0/workflow/pmtable/22815673755f209dd749c90081062413/data

POST Fields:

The following object where the member variables have the same names as the fields in the PM Table and their values will be inserted in a new record in the PM Table.

For example:
{
   "ID":           1262,                            //INTEGER
   "CLIENT_NAME":  "Sprockets Inc.",                //CHAR
   "ADDRESS":      "214 Elm St.\nDurham, FL 47621", //VARCHAR with new line
   "AMOUNT":       13435.99,                        //DECIMAL
   "WORK_START":   "2015-10-31 14:04:45",           //DATETIME
   "PAUSE_TIME":   "13:34:20",                      //TIME
   "DUE_DATE":     "2015-12-31",                    //DATE
   "HAS_CONTRACT": 1                                //BOOLEAN
}

Result:

If successful, the HTTP status is set to 201 (Created) and the new record which has been inserted in the PM Table is returned, with the field names in lowercase.

{
   "field_name1" : "VALUE1",
   "field_name2" : "VALUE2",
   ...
}

PHP example:

 {
$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "amos", "sample");
   
$tableId = '22815673755f209dd749c90081062413'; 
   
$aVars = array(
   "ID"          => 1262,                            //INTEGER
   "CLIENT_NAME" => "Sprockets Inc.",                //CHAR
   "ADDRESS"     => "214 Elm St.\nDurham, FL 47621", //VARCHAR with new line
   "AMOUNT"      => 13435.99,                        //DECIMAL
   "WORK_START"  => "2015-10-31 14:04:45",           //DATETIME
   "PAUSE_TIME"  => "13:34:20",                      //TIME
   "DUE_DATE"    => "2015-12-31",                    //DATE
   "HAS_CONTRACT"=> 1                                //BOOLEAN
);  
$url = "/api/1.0/workflow/pmtable/";//$tableId/data";
$oRet = pmRestRequest("GET", $url, $aVars, $oToken->access_token);
       
if ($oRet->status == 201) {
   print '<html><head><meta charset="UTF-8"></head><body><pre>';
   print "Record inserted!";
        print '
'; }

Note: Remember that ProcessMaker's MySQL database stores character data in the UTF-8 character set, so any strings should be converted to UTF-8 if they are in another character set, using a function such as iconv() in PHP.

Update PM Table Structure: PUT /pmtable/{pmt_uid}

Update the structure of a PM table.

PUT /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
pmt_uidStringPM Table UID

Optional Fields:

NameTypeDescription
pmt_tab_dscStringPM Table description
fieldsArray

Result:

TypeDescription
emptyNo return

Example:
Request

 {
    "rep_tab_dsc" : "descripcion de la tabla",
    "fields" : [
        {
            "fld_name" : "CAMPO",
            "fld_label" : "CAMPITO",
            "fld_type" : "VARCHAR",
            "fld_size" : 200
        }
    ]
 }

Response

 200(OK)

Update PM Table Data: PUT /pmtable/{pmt_uid}/data

Update the data of an existing record in a PM table.

PUT /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
pmt_uidStringPM Table UID

POST Fields:

An object where the member variables have the same names as the fields in the PM Table and their values will be inserted in an existing record in the PM Table.

Result:

TypeDescription
emptyNo return

Example:
Request

 {
    "CAMPO1" : "valor1",
    "CAMPO2" : "valor2"
 }

Response

 200(OK)

Delete PM Table: DELETE /pmtable/{pmt_uid}

Delete a specified PM table and all its data.

DELETE /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
pmt_uidStringPM Table UID

Result:

TypeDescription
emptyNo return

Example
Response

 200(OK)

Delete PM Table Data: DELETE /pmtable/{pmt_uid}/data/...

Delete a record from a PM table, by specifying its primary key(s). The PM Table can have up to 3 primary key fields.

DELETE /api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}
(/api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}/{key2}/{value2})
(/api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}/{key2}/{value2}/{key3}/{value3})

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
pmt_uidStringPM Table UID
key1/key2/key3StringName of the PM Table primary key field (depending on the number of key fields in the table)
value1/value2/value3StringValue of the PM Table primary key field (depending on the number of key fields in the table)

Result:

TypeDescription
emptyNo return

Example:
Response

 200(OK)

Categories

The following REST endpoints are used to manage process categories in ProcessMaker.

1. Get a list of categories

2. Get a category

3. Create a category

4. Update category

5. Delete a category

Category:

NameDescriptionTypeValue
cat_uidCategory UIDString"9541049475298f190420f51086854718" String of 32 characters
cat_nameCategory nameString"Other categories"
cat_total_processesTotal number of processes that belong to the CategoryInteger10
Other Parameters
filterSearch filterString"a,b,c..."
startIndicates the initial position of the records returnedString0,...
limitRestricts the size of records returnedString25,...


Available methods:

Get Categories List: GET /project/categories

Get a list of the categories in the workspace.

GET /api/1.0/{workspace}/project/categories?filter={filter}&start={start}&limit={limit}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

Optional Parameters:

NameTypeDescription
filterStringSearch filter
startIntegerIndicates the initial position of the records returned
limitIntegerRestricts the size of records returned

Result:

TypeDescription
arrayReturns an array of objects with categories

Example:
Response

 200 (OK)
 [
    {
        "cat_uid": "348271339502d0a79d8dc86059093146",
        "cat_name": "Accounting",
        "cat_total_processes": 5
    },
    {
        "cat_uid": "497378380530f6bd54acc20036329683",
        "cat_name": "Human Resources",
        "cat_total_processes": 10
    },
    {
        "cat_uid": "272586185508e8644a06768068487362",
        "cat_name": "Factory Production",
        "cat_total_processes": 0
    }
 ]

Get Category Information: GET /project/category/{cat_uid}

Get the information about a category.

GET /api/1.0/{workspace}/project/category/{cat_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
cat_uidStringCategory UID

Result:

Returns an object with information about the specified category.

Example:
Response

 200 (OK)
 {
        "cat_uid": "348271339502d0a79d8dc86059093146",
        "cat_name": "Human Resources",
        "cat_total_processes": 5
 }  

Create Category: POST /project/category

Create a new process category.

POST /api/1.0/{workspace}/project/category

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

POST Fields:

NameTypeDescription
cat_nameStringCategory name

Optional POST Fields:

NameTypeDescription
cat_total_processesIntegerTotal number of processes that belong to the category

Result:

Returns an object with data about the new category.

Example:
Request

 Content-Type: application/json
 {
        "cat_name": "Human Resources"    
 }

Response

 200 (OK)
 {
        "cat_uid": "348271339502d0a79d8dc86059093146",
        "cat_name": "Human Resources",
        "cat_total_processes": 0
 }

Update Category: PUT /project/category/{cat_uid}

Update an existing category.

PUT /api/1.0/{workspace}/project/category/{cat_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
cat_uidStringCategory UID

Optional Fields:

NameTypeDescription
cat_nameStringCategory name
cat_total_processesTotal number of processes that belong to the categoryInteger

Result:

TypeDescription
emptyNo return

Example:
Request

 Content-Type: application/json
 {
   "cat_name": "Bugs"
 }

Response

 200 (OK)

Delete Category: DELETE /project/category/{cat_uid}

Delete a category.

DELETE /api/1.0/{workspace}/project/category/{cat_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
cat_uidStringCategory UID

Result:

TypeDescription
emptyNo return

Example:
Response

 200 (OK)

Calendars

The following REST endpoints are available to manage calendars in ProcessMaker.

1.Get a list of calendars

2.Get a calendar

3.Create a calendar

4.Update calendar

5.Delete calendar

Calendar:

NameDescriptionTypeValue
cal_uidCalendar UIDString"9541049475298f190420f51086854718" String of 32 characters
cal_nameCalendar nameString"Default calendar"
cal_descriptionCalendar descriptionString"Description"
cal_work_daysWork daysArray[1, 2, 3, 4, 5, 6, 7]
cal_statusStatusString"ACTIVE", "INACTIVE" (Unique values)
cal_work_hourWork hoursobjectObject array
cal_work_hour . dayDayInteger0, 1, 2, 3, 4, 5, 6, 7 (Unique values) 0: All, 1: Monday, 2: Tuesday, 3: Wednesday, 4: Thursday, 5: Friday, 6: Saturday, 7: Sunday
cal_work_hour . hour_startStart hourString"00:00"
cal_work_hour . hour_endEnd hourString"23:59"
cal_holidayHolidaysObjectObject array
cal_holiday . nameHoliday nameString"Name"
cal_holiday . date_startHoliday start dateString"2014-04-01"
cal_holiday . date_endHoliday end dateString"2014-04-01"
cal_create_dateCreation date (According to setting in "Global Date Format")Datetime"2012-10-22 14:51:11"
cal_update_dateUpdate date (According to setting in "Global Date Format")Datetime"2012-10-22 14:51:11"
cal_total_usersTotal number of users according to the calendarInteger0,1,...
cal_total_processesTotal number of processes according to the calendarInteger0,1,...
cal_total_tasksTotal number of tasks according to the calendarInteger0,1,...
filterSearch filterString"abc"
startIndicates the initial position of the records returnedInteger0,1,...
limitRestricts the number of records returnedInteger25,...


Available methods:

Get Calendar List: GET /calendars

Get a list of calendars in the workspace.

GET /api/1.0/{workspace}/calendars?filter={filter}&start={start}&limit={limit}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

Optional Parameters:

NameTypeDescription
filterStringSearch filter
startIntegerIndicates the initial position of the records returned
limitIntegerRestricts the number of records returned

Result:

TypeDescription
arrayReturns an array of objects with each calendar

Example:
Response

 200 (OK)
 [    
    {
        "cal_uid": "00000000000000000000000000000001",
        "cal_name": "Default Calendar",
        "cal_description": "Default",
        "cal_work_days": {"1": "Monday", "2": "Tuesday", "3": "Wednesday", "4": "Thursday"},
        "cal_status": "ACTIVE",
        "cal_work_hour":
        [
             {"day": 0, "hour_start": "00:00", "hour_end": "00:00"}
        ],
        "cal_holiday":
        [
             {"name": "h1", "date_start": "2014-04-02", "date_end": "2014-04-04"}
        ],
        "cal_create_date": "01/04/2014",
        "cal_update_date": "07/04/2014",
        "cal_total_users": 0,
        "cal_total_processes": 0,
        "cal_total_tasks": 0
    },
    {
        "cal_uid": "86431145652efa6f2413d29045495711",
        "cal_name": "My calendar Demo",
        "cal_description": "Default",
        "cal_work_days": {"5": "Friday", "6": "Saturday", "7": "Sunday"},
        "cal_status": "INACTIVE",
        "cal_work_hour":
        [
             {"day": 0, "hour_start": "00:00", "hour_end": "00:00"},
             {"day": 7, "hour_start": "09:00", "hour_end": "17:00"}
        ],
        "cal_holiday":
        [
            {"name": "holiday1", "date_start": "2010-01-01", "date_end": "2010-01-10"},
            {"name": "holiday2", "date_start": "2014-04-01", "date_end": "2014-04-04"}
        ],
        "cal_create_date": "01/04/2014",
        "cal_update_date": "09/04/2014",
        "cal_total_users": 0,
        "cal_total_processes": 1,
        "cal_total_tasks": 0
    }
 ]

Get Calendar Information: GET /calendar/{cal_uid}

Get information about a specified calendar.

GET /api/1.0/{workspace}/calendar/{cal_uid}

Parameters

NameTypeDescription
workspaceStringWorkspace name
cal_uidStringCalendar UID

Result

TypeDescription
objectReturns an object with data of the calendar

Response

 200 (OK)
 {
     "cal_uid": "86431145652efa6f2413d29045495711",
     "cal_name": "My calendar Demo",
     "cal_description": "Default",
     "cal_work_days":
     {
        "5": "Friday",
        "6": "Saturday",
        "7": "Sunday"
     },
     "cal_status": "INACTIVE",
     "cal_work_hour":
     [
        {"day": 0, "hour_start": "00:00", "hour_end": "00:00"},
        {"day": 7, "hour_start": "09:00", "hour_end": "17:00"}
     ],
     "cal_holiday":
     [
        {"name": "holiday1", "date_start": "2010-01-01", "date_end": "2010-01-10"},
        {"name": "holiday2", "date_start": "2014-04-01", "date_end": "2014-04-04"}
     ],
     "cal_create_date": "01/04/2014",
     "cal_update_date": "09/04/2014",
     "cal_total_users": 0,
     "cal_total_processes": 1,
     "cal_total_tasks": 0
 }

Create Calendar: POST /calendar

Create a new calendar.

POST /api/1.0/{workspace}/calendar

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name

POST Fields:

NameTypeDescription
cal_nameStringCalendar name
cal_work_daysArrayWork days

Optional POST Fields:

NameTypeDescription
cal_descriptionDescriptionString
cal_statusStringCalendar status
cal_work_hourObjectWork hours
cal_work_hour . dayIntegerCalendar days
cal_work_hour . hour_startStringStart hour
cal_work_hour . hour_endStringEnd hour
cal_holidayObjectHolidays
cal_holiday . nameStringHoliday name
cal_holiday . date_startStringHoliday start date
cal_holiday . date_endStringHoliday end date
cal_create_dateDatetimeCalendar creation date
cal_update_dateDatetimeCalendar update date
cal_total_usersIntegerTotal number of users registered according to the calendar
cal_total_processesIntegerTotal number of processes according to the calendar
cal_total_tasksIntegerTotal number of tasks according to the calendar

Result:

TypeDescription
objectReturns an object with the new calendar data plus the cal_uid attribute

Example:
Request

 Content-Type: application/json
 {
     "cal_name": "My calendar Demo",
     "cal_description": "Default",
     "cal_work_days": [5, 6, 7],
     "cal_work_hour":
        [
           {"day": 0, "hour_start": "00:00", "hour_end": "00:00"},
           {"day": 7, "hour_start": "09:00", "hour_end": "17:00"}
        ],
     "cal_holiday":
        [
           {"name": "holiday1", "date_start": "2010-01-01", "date_end": "2010-01-10"},
           {"name": "holiday2", "date_start": "2014-04-01", "date_end": "2014-04-04"}
        ]
 }

Response

 200 (OK)
 {
     "cal_uid": "86431145652efa6f2413d29045495711",
     "cal_name": "My calendar Demo",
     "cal_description": "Default",
     "cal_work_days": [5, 6, 7],
     "cal_work_hour":
        [
           {"day": 0, "hour_start": "00:00", "hour_end": "00:00"},
           {"day": 7, "hour_start": "09:00", "hour_end": "17:00"}
        ],
     "cal_holiday":
        [
           {"name": "holiday1", "date_start": "2010-01-01", "date_end": "2010-01-10"},
           {"name": "holiday2", "date_start": "2014-04-01", "date_end": "2014-04-04"}
        ]
 }

Update Calendar: PUT /calendar/{cal_uid}

Update an existing calendar.

PUT /api/1.0/{workspace}/calendar/{cal_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
cal_uidStringCalendar UID

Optional Fields:

NameTypeDescription
cal_nameStringCalendar name
cal_work_daysArrayWork days
cal_descriptionDescriptionString
cal_statusStringCalendar status
cal_work_hourObjectWork hours
cal_work_hour . dayIntegerCalendar days
cal_work_hour . hour_startStringStart hour
cal_work_hour . hour_endStringEnd hour
cal_holidayObjectHolidays
cal_holiday . nameStringHoliday name
cal_holiday . date_startStringHoliday start date
cal_holiday . date_endStringHoliday end date
cal_create_dateDatetimeCalendar creation date
cal_update_dateDatetimeCalendar update date
cal_total_usersIntegerTotal number of users registered according to the calendar
cal_total_processesIntegerTotal number of processes according to the calendar
cal_total_tasksIntegerTotal number of tasks according to the calendar

Result:

TypeDescription
emptyNo result

Example:
Request

 Content-Type: application/json
 {
    "cal_name": "My calendar Demo",
    "cal_description": "Default",
    "cal_work_days": [5, 6, 7],
    "cal_status": "INACTIVE",
    "cal_work_hour": [
        {"day": 0, "hour_start": "00:00", "hour_end": "00:00"},
        {"day": 7, "hour_start": "09:00", "hour_end": "17:00"}
    ],
    "cal_holiday": [
        {"name": "holiday1", "date_start": "2010-01-01", "date_end": "2010-01-10"},
        {"name": "holiday2", "date_start": "2014-04-01", "date_end": "2014-04-04"}
    ]
 }

Response

 200 (OK)

Delete Calendar: DELETE /calendar/{cal_uid}

Delete a calendar.

DELETE /api/1.0/{workspace}/calendar/{cal_uid}

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
cal_uidStringCalendar UID

Result:

TypeDescription
emptyNo return

Example:
Response:

 200 (OK)