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

Roles

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

Get Roles List: GET /roles

Get a list of the roles in the workspace.

GET /api/1.0/{workspace}/roles

URL Parameters:

Name Description Example
workspace Workspace 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:

Name Type Description
workspace String Workspace name
rol_uid String Role 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.

Permission:

The logged-in user needs to have the PM_USERS permission in his/her role in order to be able to perform this action.

Structure:

POST /api/1.0/{workspace}/role

URL Parameters:

Name Description Example
workspace Workspace name /api/1.0/workflow/role

POST fields:

Name Description
rol_code The role code, which is an identifier consisting of letters, numbers and underscores ("_"). It may not contain any spaces or special characters.
rol_name The role name, which is any identifier which can contain any type of characters and is displayed in the ProcessMaker.
rol_status Optional. 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.

Permission:

The logged-in user needs to have the PM_USERS permission in his/her role in order to be able to perform this action.

Structure:

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

URL Parameters:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988
rol_uid Unique ID of role /api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988

POST fields:

Name Description
rol_code Optional. The role code, which is an identifier consisting of letters, numbers and underscores ("_"). It may not contain any spaces or special characters.
rol_name Optional. The role name, which is any identifier which can contain any type of characters and is displayed in the ProcessMaker.
rol_status Optional. 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.

Permission:

The logged-in user needs to have the PM_USERS permission in his/her role in order to be able to perform this action.

Structure:

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

URL Parameters:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988
rol_uid Unique 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:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000003/users
rol_uid Unique 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:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000003/available-users
rol_uid Unique 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.

Permission:

The logged-in user needs to have the PM_USERS permission in his/her role in order to be able to perform this action.

Structure:

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

URL Parameters:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000003/user
rol_uid Unique 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:

Name Type Description
usr_uid String Unique 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.

Permission:

The logged-in user needs to have the PM_USERS permission in his/her role in order to be able to perform this action.

Structure:

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

URL Parameters:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000003/user/55625662755e0e42fe83f41018778834
rol_uid Unique 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_uid Unique 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:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000002/permissions
rol_uid Unique 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:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000003/available-permissions
rol_uid Unique 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.

Permission:

The logged-in user needs to have the PM_USERS permission in his/her role in order to be able to perform this action.

Structure:

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

URL Parameters:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000003/permission
rol_uid Unique 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:

Name Type Description
per_uid String Unique 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.

Permission:

The logged-in user needs to have the PM_USERS permission in his/her role in order to be able to perform this action.

Structure:

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

URL Parameters:

Name Description Example
workspace Workspace name /api/1.0/workflow/role/00000000000000000000000000000003/permission/00000000000000000000000000000007
rol_uid Unique 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_uid Unique 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";
}