3.1 - 3.8 - REST API Administration - Departments

Departments

These are the REST endpoints to manage departments in ProcessMaker:

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:

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

For example:

PHP Example:

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

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

Get Department Information: GET /department/{dep_uid}

Get information about a specified department.

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

URL Parameters:

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

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

PHP Example:

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

Create Department: POST /department

Create a new department.

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

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Fields:

Name	Type	Description
dep_title	String	Department'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_parent	String	Optional. Parent department's unique ID. If not included or set to "" (empty string), then this is a top-level department.
dep_manager	String	Optional. 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_status	String	Optional. 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:

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:

PHP Example:

Update Department: PUT /department/{dep_uid}

Update the information about a department.

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}/department/{dep_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Department UID.

Optional Fields:

Name	Type	Description
dep_title	String	The department title (name), which must be unique.
dep_parent	String	Unique ID of the parent department. Set to "" (empty string) to make a top-level department.
dep_manager	String	Unique ID of the department supervisor, to whom the members of the department [[1]], as well as the supervisors of subdepartments.
dep_status	String	Department 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:

PHP Example:

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.

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}/department/{dep_uid}

URL Parameters:

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

PHP Example:

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:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.

Result:

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

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.

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:

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

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:

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.

Assign User to Department: POST /department/{dep_uid}/assign-user

Assign a user to a specified department. Take into acount the following considerations:

• If the user is already a member of another department, the user is assigned to the specified department.
• If the department does not have a manager, the user is assigned to the specified department as a manager.

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}/department/{dep_uid}/assign-user

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.

POST Fields:

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

PHP Example:

Unassign User from Department: DELETE /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.

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}/department/{dep_uid}/unassign-user/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.
usr_uid	String	Unique 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:

PHP Example:

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.

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}/department/{dep_uid}/set-manager/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of the department.
usr_uid	String	Unique 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:

PHP Example: