3.1 - 3.8 - REST API Administration - Groups

Groups

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

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:

Name	Type	Description
workspace	String	Workspace name

Optional GET Parameters:

Name	Type	Description
filter	string	Case 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".
start	integer	The 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.
limit	integer	The 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:

Element	Description
[	Start array
{	Start group object
grp_uid	The group's unique ID.
grp_title	The group's title.
grp_status	The group's status, which can be "ACTIVE" or "INACTIVE".
grp_users	The number of users who are members of the group, including users who have "INACTIVE" and "VACATION" status.
grp_tasks	The 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:

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.

Get Group Information: GET /group/{grp_uid}

Get information about a specified group.

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

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group UID

Result:

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

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

PHP Example:

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

Create Group: POST /group

Create a new group.

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}/group

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Fields:

Name	Type	Description
grp_title	String	The name of the group.
grp_status	String	The 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:

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

PHP Example:

Update Group: PUT /group/{grp_uid}

Update information about a specified group.

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}/group/{grp_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group unique ID.

Optional Fields:

Name	Type	Description
grp_title	String	The group's title.
grp_status	String	Group 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:

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

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

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.

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}/group/{grp_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group 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:

PHP Example:

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:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group UID

Optional GET Parameters:

Name	Type	Description
filter	string	Case 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".
start	integer	The 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.
limit	integer	The 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:

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

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.

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:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group unique ID.

Optional GET Parameters:

Name	Type	Description
filter	string	Case 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".
start	integer	The 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.
limit	integer	The 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:

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

PHP Example:

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

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

Assign a user to a specified group.

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}/group/{grp_uid}/user

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	The group's unique ID

POST Fields:

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

Name	Type	Description
usr_username	String	Username
usr_firstname	String	User first name
usr_lastname	String	User last name
usr_email	String	User email
usr_status	String	User 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:

PHP Example:

Batch assignment of users to a group: POST /group/batch-users

Assign a group of users to a specified group or groups.

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. As of ProcessMaker 3.7.6, there is no need to have the PM_USERS in the role.

Structure:

POST /api/1.0/{workspace}/group/batch-users

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Fields:

Name	Type	Description
group_uid	String	The unique ID of the group.
usr_uid	String	The 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.

Example:
Request

Response

If the users were assigned to the groups, then the HTTP status code is 201 (Created) and there is a return object with the state of the assignment of each user.

Otherwise, it is 400 or greater and returns a JSON error object like:

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.

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}/group/{grp_uid}/user/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group UID
usr_uid	String	Group 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:

PHP Example: