3.2 - 3.8 - REST API Administration - Users

Users

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

Get Users List: GET /users

Returns the 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}& status={status}

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 user's first name, last name or username. For example: api/1.0/workspace/users?filter=mit will return the users "smith", "Mitter" and "solmit".
start	integer	The 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 will start the list of users with the fourth user.
limit	integer	The maximum number of users which are returned in the list. For example: To return 10 users at a time if there are 25 users in total, call this endpoint 3 times: /api/1.0/workspace/users?limit=10 will return users 0-9. /api/1.0/workspace/users?start=10&limit=10 will return users 10-19. /api/1.0/workspace/users?start=20&limit=10 will return users 20-24.
status	string	Available Version: The status parameter is available as of ProcessMaker version 3.2.2. Filters the users by their status. If not included, the result will only list ACTIVE users. To show only active users: /api/1.0/workspace/users?status=active To show only inactive users: /api/1.0/workspace/users?status=inactive To show users in vacations: /api/1.0/workspace/users?status=vacation To show all the users: /api/1.0/workspace/users?status=all

Result:

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

Element	Description	Example
[	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_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.

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.

Get User Information: GET /user/{usr_uid}

Get information about a specified user.

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

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
usr_uid	String	User UID

Result:

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

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

Example in PHP:

Create User: POST /user

Create a new user.

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

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Parameters:

Name	Type	Description
usr_username	String	Username which is used to login to ProcessMaker and is unique.
usr_firstname	String	User's first name
usr_lastname	String	User's last name
usr_email	String	User's email address
usr_due_date	String	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_status	String	The user's status, which can be "ACTIVE", "INACTIVE" or "VACATION".
usr_role	String	The user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role.
usr_new_pass	String	The user's password. Remember that passwords should adhere to the password security policies.
usr_cnf_pass	String	Enter the password a second time to confirm it.
usr_address	String	Optional. The user's address. Use \n to include line breaks in the address. Ex: "345 Radcliff Drive\nC/O Brad Williams"
usr_zip_code	String	Optional. User's zip or postal code.
usr_country	String	Optional. Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database.
usr_city	String	Optional. 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_location	String	Optional. 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_phone	String	Optional. The user's telephone number.
usr_position	String	Optional. The user's position in the organization.
usr_replaced_by	String	Optional. Unique ID of another user who will replace this user if his/her status changes to "INACTIVE" or "VACATION".
usr_calendar	String	Optional. 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.
usr_time_zone	string	Optional parameter that is only available in the Enterprise Edition. The time zone of the user. Use one of the PHP time zones, such as "America/Mexico_City" or "Asia/Shanghai". In the US, use these time zones: US standard time zone PHP time zone Eastern America/New_York Central America/Chicago Mountain America/Denver Mountain no DST America/Phoenix Pacific America/Los_Angeles Alaska America/Anchorage Hawaii America/Adak Hawaii no DST Pacific/Honolulu

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:

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:

PHP Example:

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.

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}/user/{usr_uid}/image-upload

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
usr_uid	String	User UID

POST Parameters:

Name	Type	Description	Examples
USR_PHOTO	string	The 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:

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.

Update User Information: PUT /user/{usr_uid}

Update the information about a specified user.

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

URL Parameters:

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

Name	Type	Description
usr_username	String	Optional. Username which is used to login to ProcessMaker and is unique.
usr_firstname	String	Optional. User's first name
usr_lastname	String	Optional. User's last name
usr_email	String	Optional. User's email address
usr_due_date	String	Optional. 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_status	String	Optional. The user's status, which can be "ACTIVE", "INACTIVE" or "VACATION".
usr_role	String	Optional. The user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role.
usr_address	String	Optional. The user's address. Use \n to include line breaks in the address. Ex: "345 Radcliff Drive\nC/O Brad Williams"
usr_zip_code	String	Optional. User's zip or postal code.
usr_country	String	Optional. Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database.
usr_city	String	Optional. 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_location	String	Optional. 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_phone	String	Optional. The user's telephone number.
usr_cellular	String	Optional. The user's cellular phone number.
usr_fax	String	Optional. The user's fax number.
usr_position	String	Optional. The user's position in the organization.
usr_birthday	String	Optional. The user's birthday in "YYYY-MM-DD" format. Ex: "1984-08-23"
usr_replaced_by	String	Optional. Unique ID of another user who will replace this user if his/her status changes to "INACTIVE" or "VACATION".
usr_new_pass	String	Optional. The user's password. Remember that passwords should adhere to the password security policies.
usr_cnf_pass	String	Optional. 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:

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

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

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 User: DELETE /user/{usr_uid}

Delete a specified user. 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.

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

URL Parameters:

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

PHP Example: