2.x - REST API Cases

Overview

This documentation covers the following endpoints in the ProcessMaker REST API 1.0, which deal with accessing and executing cases:

Cases

The following endpoints are used to obtain information about cases and control the execution of cases:

1. Get To Do Cases: GET /cases
2. Get Page of To Do Cases: GET /cases/paged
3. Get Draft Cases: GET /cases/draft
4. Get Page of Draft Cases: GET /cases/draft/paged
5. Get Participated Cases: GET /cases/participated
6. Get Page of Participated Cases: GET /cases/participated/paged
7. Get Unassigned Cases: GET /cases/unassigned
8. Get Page of Unassigned Cases: GET /cases/unassigned/paged
9. Get Paused Cases: GET /cases/paused
10. Get Page of Paused Cases: GET /cases/paused/paged
11. Get Advanced Search Cases: GET /cases/advanced-search
12. Get Page of Advanced Search Cases: GET /cases/advanced-search/paged
13. Get Case Information: GET /cases/{app_uid}
14. Get Case's Current Task(s): GET /cases/{app_uid}/current-task
15. Get Case's Tasks: GET /cases/{app_uid}/tasks (Version 3.0 and later.)
16. New Case: POST /cases
17. New Case Impersonate: POST /cases/impersonate
18. Reassign Case: PUT /cases/{app_uid}/reassign-case
19. Route Case: PUT /cases/{app_uid}/route-case
20. Cancel Case: PUT /cases/{app_uid}/cancel
21. Pause Case: PUT /cases/{app_uid}/pause
22. Unpause Case: PUT /cases/{app_uid}/unpause
23. Execute Trigger: PUT /cases/{app_uid}/execute-trigger/{tri_uid}
24. Delete Case: DELETE /cases/{app_uid}

Filters for listing cases

The endpoints which return a list of cases, such as GET /cases, /cases/paged, /cases/draft, etc., will return by default up to 25 cases and sort the cases in descending order according to their case number, which means that cases created more recently will be listed first. Additional GET parameters can be included in the URL to change how many cases are returned, what database field is used to sort the cases and the sort order, plus include filters to only return cases from a specified process or process category or search for cases which contain a specified string.

URL Parameters:

Parameter	Description	Default value	Example
start={number}	The number of cases where the list begins. If set to 0 or 1, then begins with the first case. 2 begins with the second case, 3 begins with the third case, etc.	0	/api/1.0/workflow/cases?start=1&limit=10
limit={number}	The maximum number of cases in the list.	25	/api/1.0/workflow/cases?start=11&limit=10
sort={field}	The field in the wf_<WORKSPACE>.APP_CACHE_VIEW table by which the list of cases is sorted. The default is "APP_CACHE_VIEW.APP_NUMBER", which lists cases in the order they were created.	APP_CACHE_VIEW.APP_NUMBER	/api/1.0/workflow/cases?sort=APP_CACHE_VIEW.APP_UPDATE_DATE
dir={order}	The order by which cases are listed which can be "ASC" (ascending) or "DESC" (descending).	DESC	/api/1.0/workflow/cases?dir=ASC
cat_uid={uid}	The unique ID of a category. Only return cases whose process is in the specified category. To find the UIDs for categories in the wf_<WORKSPACE> database, use the following query: SELECT CATEGORY_UID, CATEGORY_NAME FROM PROCESS_CATEGORY;		/api/1.0/workflow/cases?cat_uid=11609821854ca4355344560009542371
pro_uid={uid}	The unique ID of a process. Only return cases for the specified process. To find the UIDs for processes in the wf_<WORKSPACE> database, use the following query: SELECT CON_ID, CON_VALUE FROM CONTENT WHERE CON_CATEGORY='PRO_TITLE';		/api/1.0/workflow/cases?pro_uid=28468941754ca473f9db401077958260
search={string}	Case insensitive search for cases in the case's title and current task title. Make sure to URL encode the searched text in UTF-8, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3.		/api/1.0/workflow/cases?search=Evaluate%20Costs

Calling /cases endpoints

After calling a GET /cases... endpoint, first decode the JSON string returned by the endpoint with a function such as JSON.parse() or eval() in JavaScript or json_decode() in PHP.

If it returns a list of cases, then it will be an array of case objects. If it returns a page of cases, then access the array of cases objects located in its data member.

Case Object

The GET endpoints which return cases (such as /cases, /cases/paged, /cases/draft, etc.) enclose the information about each case in the following case object:

Element	Description	Example
{	Begin case object.
"app_uid":	Unique ID of case.	"50576446953235bfb797531078087088"
"del_index":	Delegation index of case, which counts tasks executed in the case, starting from 1.	"1"
"del_last_index":	Last delegation index, which is the previous task in the case.	"1"
"app_number":	The Case Number, which counts cases in the workspace, starting from 1.	"66"
"app_status":	Current status of case: "TO_DO" (current task is assigned but not yet worked on), "DRAFT" (current task has been worked on, but not yet completed), "COMPLETED" (case terminated at an end event), "CANCELLED", "PAUSED", "DELETED" or "UNASSIGNED" (unclaimed self service cases)	"TO_DO"
"usr_uid":	Unique ID of user currently assigned to work on case.	"00000000000000000000000000000001"
"previous_usr_uid":	Unique ID of the previous user assigned to case. Set to empty string if the first task in the case and the current user is the first user assigned to the case.	""
"tas_uid":	Unique ID of current task in case.	"7983935495320c1a75e1df6068322280"
"pro_uid":	Unique ID of the case's process.	"2317283235320c1a36972b2028131767"
"del_delegate_date":	Datetime in "YYYY-MM-DD HH:MM:SS" format when case was routed to the current task.	"2014-03-14 15:43:55"
"del_init_date":	Datetime in "YYYY-MM-DD HH:MM:SS" format when current task was initiated. If a self service task which hasn't yet been claimed by a user, then set to null.	"2014-03-14 15:43:55"
"del_task_due_date":	Datetime in "YYYY-MM-DD HH:MM:SS" format when the current task is due (scheduled to be completed).	"2014-03-17 15:43:55"
"del_finish_date":	Datetime in "YYYY-MM-DD HH:MM:SS" format when the current task was completed. Set to null if not yet completed.	null
"del_thread_status":	Status of the delegation thread which can be "OPEN" or "CLOSED", which indicates whether the current parallel task is still executing or has been completed or canceled.	"OPEN"
"app_thread_status":	Status of the case thread which can be "OPEN" or "CLOSED", which indicates whether the current task is still executing or has been completed or canceled.	"OPEN"
"app_title":	The case title, which by default is its case number, but can be customized by task properties.	"#66"
"app_pro_title":	The title for the case's process.	"My process title"
"app_tas_title":	The title of the current task in the case.	"Task 1"
"app_current_user":	The last name and first name (separated by space) of the user currently assigned to the case.	" Administrator"
"app_del_previous_user":	The last name and first name (separated by space) of the user assigned to the case's previous task.	""
"del_priority":	The case's delegation priority which can be "VERY LOW" (1), "LOW" (2), "NORMAL" (3), "HIGH" (4) and "VERY HIGH" (5).	"NORMAL"
"del_duration":	No longer used and always set to "0".	"0"
"del_queue_duration":	No longer used and always set to "0".	"0"
"del_delay_duration":	No longer used and always set to "0".	"0"
"del_started": "0",	No longer used and always set to "0".	"0"
"del_finished": "0",	No longer used and always set to "0".	"0"
"del_delayed": "0",	No longer used and always set to "0".	"0"
"app_create_date":	Datetime in "YYYY-MM-DD HH:MM:SS" format when the case was first created.	"2014-03-14 15:43:55"
"app_finish_date":	Datetime in "YYYY-MM-DD HH:MM:SS" format when the case was completed or canceled. Set to null if not yet completed.	null
"app_update_date":	Datetime in "YYYY-MM-DD HH:MM:SS" format when the case was last updated, meaning data was changed, files were uploaded or the case was routed to another task.	"2014-03-14 15:43:57"
"app_overdue_percentage":	No longer used and always set to "0".	"0"
"usr_firstname":	First name of the user currently assigned to work on case.	"Administrator"
"usr_lastname":	Last name of the user currently assigned to work on case.	" "
"usr_username":	Username of the user currently assigned to work on case.	"admin"
"appcvcr_app_tas_title":	Title of the current task in the case.	"Task 1"
"usrcr_usr_uid":	Unique ID of the user currently assigned to work on case.	"00000000000000000000000000000001"
"usrcr_usr_firstname":	First name of the user currently assigned to work on case.	"Administrator"
"usrcr_usr_lastname":	Last name of the user currently assigned to work on case.	" "
"usrcr_usr_username":	Username of the user currently assigned to work on case.	"admin"
"app_status_label":	The current case status, which can be "To do", "Draft", "Completed", "Cancelled", "Paused" or "Deleted".	"To do"
}	End case object.

Returning a list of cases

The GET endpoints which return a list of cases (such as /cases, /cases/draft, etc.) will return an array of case objects with the following structure:

Reading a list of cases with JavaScript:

Reading a list of cases with PHP:

Returning a page of cases

Each GET endpoint which returns a list of cases also has a corresponding endpoint which returns a page of cases, such as /cases/paged, /cases/draft/paged, /cases/participated/paged etc. A page is an object containing information about the total number of cases and the filters used to retrieve the cases. Its data member holds an array of case objects:

Element	Description
{
"total": 6,	Total number of cases found.
"start": 1,	Number where the list of cases begins. The default is 1.
"limit": 25,	Maximum number of cases returned. The default is 25.
"sort": "app_cache_view.app_number",	The field in the wf_<WORKSPACE>.APP_CACHE_VIEW table which is used to sort the cases. The default is "app_cache_view.app_number".
"dir": "desc",	The sort order of the cases, which can be "asc" (ascending) or "desc" (descending, which is the default).
"cat_uid": "",	The unique ID of a process category. Only cases whose processes are in the given category will be returned.
"pro_uid": "",	The unique ID of a process. Only cases in the given process will be returned.
"search": "",	A case insensitive string to search for in the case title and task title.
"data":	An array of case objects.
[    { //first case object      "app_uid": "50576446953235bfb797531078087088",      ...    },    { //second case object      "app_uid": "33432552454f5c38aa3a620081949840",      ...    }  ]
}	End of the page object.

It is recommended to use the endpoints which return a page of cases when needing to know the total number of cases which are available. If needing to retrieve all the available cases at once, first call the GET /cases.../paged endpoint and examine its total in the page object. Then call the same endpoint a second time, with the limit set to the size of the total.

For example, if needing to retrieve all the cases that a user participated in, then first call:

/api/1.0/workflow/cases/participated/paged

If the page's total is 239, then call the endpoint a second time to retrieve all the cases at once:

/api/1.0/workflow/cases/participated/paged?limit=239

If there is a large number of cases, it may be recommended to download them with multiple calls:

/api/1.0/workflow/cases/participated/paged?start=1&limit=100
/api/1.0/workflow/cases/participated/paged?start=101&limit=100
/api/1.0/workflow/cases/participated/paged?start=201&limit=100

Reading a page of cases with JavaScript:
This example prints out in the <body> of the current web page when each case in the logged-in user's inbox is due:

Reading a page of cases with PHP:
This example prints out when each case in the logged-in user's inbox is due:

Get To Do Cases: GET /cases

Get the list of To Do cases for the logged in user. Cases with "TO DO" status have been assigned to the user, but the current task in the case hasn't yet been worked on.

GET /api/1.0/{workspace}/cases

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases
filters	See Filters for Listing cases.	/api/1.0/workflow/cases?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

JavaScript Example:

This example prints a list of To Do cases which are overdue. It compares the due date of the current task with the current datetime. The two datetimes are instantiating as Date() objects so they can be compared. (Note that the date comparison will only be exact if the time of the local computer is the same as the time on the ProcessMaker server.) In order to instantiate the due date as a Date object, the replace(/-/g, ' ')) method is used to convert its value from "YYYY-MM-DD HH:MM:SS" to "YYYY MM DD HH:MM:SS" (without hyphens).

The above JavaScript code should add text to the bottom of the web page, such as:

PHP Example:

This example prints a list of To Do cases which are overdue. It compares the due date of the current task with the current datetime which is obtained using the date('Y-m-d H:i:s') function. Note that it compares the two dates as strings, which works because both are in standard "YYYY-MM-DD HH:MM:SS" format.

The above PHP code print text, such as:

Get Page of To Do Cases: GET /cases/paged

Get a page of cases with "To do" status for the logged-in user.

GET /api/1.0/{workspace}/cases/paged

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/paged
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

JavaScript Example:

This example calls the /cases/paged?limit=0 endpoint to find out how many total cases the logged-in user has in his/her inbox. Then it calls the /cases/paged?limit=X endpoint again to download all the cases at once. It then generates statistics on how many cases are in each task and prints this information in the <body> of the web page.

The above JavaScript code should add text to the bottom of the web page, such as:

PHP Example:

This example prints a list of To Do cases which are overdue. It compares the due date of the current task with the current datetime which is obtained using the date('Y-m-d H:i:s') function. Note that it compares the two dates as strings, which works because both are in standard "YYYY-MM-DD HH:MM:SS" format.

Get Draft Cases: GET /cases/draft

Get the list of Draft cases for the logged-in user.

GET /api/1.0/{workspace}/cases/draft

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/draft
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/draft?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned with "DRAFT" status. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Page of Draft Cases: GET /cases/draft/paged

Get a page of Draft cases for the logged-in user.

GET /api/1.0/{workspace}/cases/draft/paged

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/draft/paged
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/draft/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Participated Cases: GET /cases/participated

Get the list of cases in which the logged in user has participated.

GET /api/1.0/{workspace}/cases/participated

Function: getList makes the request to obtain data from all cases.

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/participated
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/participated?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Page of Participated Cases: GET /cases/participated/paged

Get a page the cases in which the logged-in user has participated.

GET /api/1.0/{workspace}/cases/participated/paged

Function: getList makes the request to obtain data from all cases.

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/participated/paged
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/participated/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Unassigned Cases: GET /cases/unassigned

Get the list of Unassigned cases, which the logged-in user may claim (i.e., assign to him/herself to work on). These are cases whose current task have a self-service assignment rule, but have not yet been claimed by any user. Note: In order to claim a case, the logged-in user must either be assigned as a user or an ad hoc user to the case's current task.

GET /api/1.0/{workspace}/cases/unassigned

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/unassigned
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/unassigned?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Page of Unassigned Cases: GET /cases/unassigned/paged

Get a page of Unassigned cases, which the logged-in user may claim (i.e., assign to him/herself to work on). These are cases whose current task have a self-service assignment rule, but have not yet been claimed by any user. Note: In order to claim a case, the logged-in user must either be assigned as a user or an ad hoc user to the case's current task.

GET /api/1.0/{workspace}/cases/unassigned/paged

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/unassigned/paged
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/unassigned/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Paused Cases: GET /cases/paused

Get a list of Paused cases which are assigned to the logged-in user.

GET /api/1.0/{workspace}/cases/paused

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/paused
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/paused?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

PHP Example:

Get Page of Paused Cases: GET /cases/paused/paged

Get a page of Paused cases assigned to the logged-in user.

GET /api/1.0/{workspace}/cases/paused/paged

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/paused/paged
filters	See Filters for Listing cases.	/api/1.0/workflow/cases/paused/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Advanced Search Cases: GET /cases/advanced-search

Get a list of cases obtained with advanced search. Unlike the other GET /cases... endpoints, /cases/advanced-search returns all the cases in the workspace which meet the search criteria, including cases to which the logged-in user is not assigned.

GET /api/1.0/{workspace}/cases/advanced-search

Warning: If the logged-in user does not have the PM_ALLCASES permission in his/her role, this endpoint should only be able to search for cases in which the user has participated, has process permissions or is assigned as a process supervisor.

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/advanced-search
app_status	Optional. Case status which can be "TO_DO", "DRAFT", "PAUSED", "CANCELLED", or "COMPLETED"	/api/1.0/workflow/cases/advanced-search?app_status=CANCELLED
usr_uid	Optional. Unique ID of the user who is currently assigned to the case.	/api/1.0/workflow/cases/advanced-search?usr_uid=29131200354d248b15df286060262849
date_from	Optional. Search for cases which were routed to their current task on or after this date in 'YYYY-MM-DD' format.	/api/1.0/workflow/cases/advanced-search?date_from=2013-01-31
date_to	Optional. Search for cases which were routed to their current task on or before this date in 'YYYY-MM-DD' format.	/api/1.0/workflow/cases/advanced-search?date_to=2015-01-31
filters	Optional. See the standard Filters for Listing cases.	/api/1.0/workflow/cases/advanced-search?search=training

Result:

If a successful, then the HTTP status code is set to 200 and an array of case objects is returned. If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

Example:

Response

Get Page of Advanced Search Cases: GET /cases/advanced-search/paged

Get a page of cases obtained with advanced search. Unlike the other GET /cases... endpoints, /cases/advanced-search/paged returns all the cases in the workspace which meet the search criteria, including cases to which the logged-in user is not assigned.

GET /api/1.0/{workspace}/cases/advanced-search/paged

Warning: If the logged-in user does not have the PM_ALLCASES permission in his/her role, this endpoint should only be able to search for cases in which the user has participated, has process permissions or is assigned as a process supervisor.

URL Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/advanced-search/paged
app_status	Optional. Case status which can be "TO_DO", "DRAFT", "PAUSED", "CANCELLED", or "COMPLETED"	/api/1.0/workflow/cases/advanced-search/paged?app_status=CANCELLED
usr_uid	Optional. Unique ID of the user who is currently assigned to the case.	/api/1.0/workflow/cases/advanced-search/paged?usr_uid=29131200354d248b15df286060262849
date_from	Optional. Search for cases which were routed to their current task on or after this date in 'YYYY-MM-DD' format.	/api/1.0/workflow/cases/advanced-search/paged?date_from=2013-01-31
date_to	Optional. Search for cases which were routed to their current task on or before this date in 'YYYY-MM-DD' format.	/api/1.0/workflow/cases/advanced-search/paged?date_to=2015-01-31
filters	Optional. See the standard Filters for Listing cases.	/api/1.0/workflow/cases/advanced-search/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. Unlike a normal page of cases, the object includes the additional members app_status, usr_uid, date_from and date_to. For example:

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

Get Case Information: GET /cases/{app_uid}

Get Information about a specified case.

GET /api/1.0/{workspace}/cases/{app_uid}

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/51382566154f7180953b5e1028461947
{app_uid}	The unique ID of the case to get information about.	/api/1.0/workflow/cases/51382566154f7180953b5e1028461947

Result:

If a successful, then the HTTP status code is set to 200 and the following information about the case and its current task(s) are returned. For example:

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

PHP Example:

This example prints information about a particular case:

Get Case's Current Tasks: GET /cases/{app_uid}/current-task

Get the current task(s) of a case. Note that if this endpoint is called for a case that has already been completed, then there is no current task and an error will be returned. Note that the logged-in user must either be currently assigned to work on the case or have Process Permissions to access the task(s).

GET /api/1.0/{workspace}/cases/{app_uid}/current-task

URL Parameters:

Parameter	Description	Example
workspace	Workspace name which by default is "workflow".	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/current-task
app_uid	Case's unique ID.	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/current-task

Result:

If successful, then sets the HTTP status code to 200 and returns an array of task objects, such as:

Otherwise, the HTTP status code is set to 400 or greater and a error is returned, such as:

Note: If a case has "COMPLETED", "PAUSED", "CANCELLED" or "DELETED" status, then the above error object is returned.

PHP Example:

Get Case's Tasks: GET /cases/{app_uid}/tasks

Get all the tasks of a case, including completed, current and future tasks. Available in version 3.0 and later.

GET /api/1.0/{workspace}/cases/{app_uid}/tasks

Method: workflow/engine/src/ProcessMaker/Services/Api/Cases.php: doGetTasks($app_uid)

Note: This endpoint will not indicate whether a case has been canceled, paused or completed. The task's status property it returns can be deceptive, since it lists "TASK_COMPLETED" when all the steps are completed but before routing to the next task. If needing to know the overall status of a case or to be sure which is the current task, is recommended to call another endpoint such as GET api/1.0/{workspace}/cases/{app_uid} and check its app_status and current_task.

URL Parameters:

Parameter	Description	Example
workspace	Workspace name which by default is "workflow".	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/tasks
app_uid	Case's unique ID.	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/tasks

Result:

PHP Example:

New Case: POST /cases

Start a new case and assign the logged-in user to work on the initial task in the case. Note that the logged-in user must be in the pool of assigned users for the initial task.

POST /api/1.0/{workspace}/cases

URL Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases

POST Parameters:

Parameter	Type	Description	Example
pro_uid	String	Unique ID of process/project.	"11703471254f718165880f2035616306"
tas_uid	String	Unique ID of the initial task to start the case. This should be a task with a start event.	"33432552454f5c38aa3a620081949840"
variables	Array	Optional. An object of case variables inside an array, that will be set in the new case. These variables can be used in DynaForm fields, triggers and the templates for email notifications and Output Documents. See Format of Variables below.	[{   "client": "Acme Inc.",   "amount": 23456.99,   "dateDue": "2015-12-31 23:59:59",   "contractCheckbox": ["1"],   "contactCheckgroup": ["fax","email","phone"] }]

Result:

If a new case was created, then the HTTP status code is set to 200 and the following object is returned:

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

Format of Variables

The case variables to be set in the new case passed are placed in a object, which is enclosed in an array in this format: [ { "variable1": "value1", "variable2": "value2", ... } ]

The variable names in the object are case sensitive and must start with a letter or underscore. Numbers may be used in variable names as long as they are not the first letter, but spaces and symbols are not allowed. Variable names may contain international letters with a value of less than 256 are allowed, but they aren't recommended, because they can cause character set translation problems.

ProcessMaker will save the variables to a MySQL database which uses the UTF-8 character set, so strings which are in other character sets need to be converted to UTF-8. mb_convert_encoding() in PHP or iconv-lite in JavaScript can be used to convert to UTF-8.

Boolean values of true and false will automatically be converted to "1" and "0" when passed to ProcessMaker, and all numbers will automatically be converted to strings. If the value is a floating point number (i.e., real number with decimal), remember to NOT use a thousands separator and to use a dot for the decimal point.

If setting the value of a dropdown box or radiogroup, remember to set the variable to the value, and not its label. The value(s) of checkboxes and checkbox groups are enclosed inside an array, but when a field inside a grid, the values of checkboxes are enclosed inside an array. If a checkbox is based on boolean variable, then use ["0"] (unmarked) or ["1"] (marked). If a checkbox is based on a string variable, then use [""] to unmark it or ["value"] to mark it. For a checkbox group (i.e., multiple checkboxes), use an array of the values of the marked options: ["value1", "value2", ...]

To set the value of a datetime field, use "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS" format, such as "2015-12-31 23:59:59"

Most types of DynaForm input fields have an associated variable and a corresponding variable_label. For textboxes and textareas, the variable_label holds the same value as the variable. For dropdown boxes and radiogroups, the variable_label holds the label of the selected option. For checkboxes and checkbox groups, variable_label holds a JSON string of the labels of the selected option(s): '["label1", "label2", ...]'
For datetimes, variable_label holds the formatted datetime according to its Format property.

DynaForm fields only use the variable and ignore the variable_label when setting their values, so it isn't necessary to set the variable_label for DynaForms, although if may be necessary if using variable_label in triggers, Output Document templates or email notification templates.

To set the contents of a grid, use an object of row objects. Each row in the grid is numbered starting from 1 and each row object contains properties which are the IDs of the fields in the grid: { "1": {"field1-id": "value1", "field2-id": "value2", ...}, "2": {"field1-id": "value1", "field2-id": "value2", ...}, ... } If using PHP, it is also possible to use an associative array of associative arrays, which is how ProcessMaker stores grids. The rows are numbered starting from 1 and the IDs of the fields in the grid are the keys in the inner associative arrays: array( "1" => array("field1-id" => "value1", "field2-id" => "value2", ...), "2" => array("field1-id" => "value1", "field2-id" => "value2", ...), ... )

If using PHP, associative arrays will automatically be converted to objects when passed to a REST endpoint since JSON doesn't support associative arrays, but ProcessMaker can read either objects or associative arrays when loading values in a DynaForm grid. The only problem is if using trigger code to access a grid which is stored in ProcessMaker as an object rather than an associative array, because this will NOT work:

It is not possible to access an object's property whose name is a number. The solution is to use the get_object_vars() function to convert the object into an associative array:

PHP Example:

To create a new case without setting new variables in the case:

This example shows how to create a new case which contains different types of fields and different types of variables. Note that the variables are placed inside an associative array, which is inside an array. The grid is a numbered array of associative arrays.

JavaScript Example:

New Case Impersonate: POST /cases/impersonate

Creates a new case. It is similar to POST /cases, but it allows cases to be created which are assigned to other users. It also impersonates the session variables, so it is more robust than POST /cases. Note that the specified user to work on the case must be assigned to the pool of users for the initial task. Also note that the new case's status will be set to "DRAFT", not "TO_DO". If wishing to change the new case's status to "TO_DO", then create the following trigger in the process and use PUT /cases/{app_uid}/execute-trigger/{tri_uid} to execute it.

POST /api/1.0/{workspace}/cases/impersonate

URL Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/impersonate

POST Parameters:

Parameter	Type	Description	Example
pro_uid	String	Unique ID of process/project.	"11703471254f718165880f2035616306"
usr_uid	String	Unique ID of user who will be assigned to initial task in case.	"51382566154f7180953b5e1028461947"
tas_uid	String	Unique ID of the initial task to start the case. This should be a task with a start event.	"33432552454f5c38aa3a620081949840"
variables	Array	Optional. Variables that are set in the new case. See New Case: POST /cases for more information.	[{"client": "Acme Inc.", "amount": 23456.99}]

Result:

If a new case was created, then the HTTP status code is set to 200 and the following object is returned:

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

PHP Example:

Reassign Case: PUT /cases/{app_uid}/reassign-case

Reassign a case to a different user. Note that the logged-in user needs to have the PM_REASSIGNCASE permission in his/her role in order to be able to reassign the case.

PUT /api/1.0/{workspace}/cases/{app_uid}/reassign-case

URL Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/reassign-case
app_uid	Case's unique ID.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/reassign-case

PUT Parameters:

Parameter	Type	Description	Example
usr_uid_source	String	Required. Unique ID of user currently assigned to case.	"41089101154de3b97536fc0077548396"
usr_uid_target	String	Required. Unique ID of user to be assigned to case. Make sure that this user is in the pool of assigned users or ad hoc users for the case's current task.	"98883020754dd1f052ee1f1034403381"
del_index	integer	Optional. The delegation index of the task which will be reassigned. If not specified, then automatically set to the most recent open task in the case. Only needs to be specified if there are multiple open tasks in the case.	5

Result:

If successful, then the HTTP status code will be set to 200 and there will be no return value. If unsuccessful, then the HTTP status code will be 400 or higher and an error object will be returned.

Example:

Request

Response

Route Case: PUT /cases/{app_uid}/route-case

Route a case (i.e., move the case to the next task in the process according to the routing rules). Cases may only be routed if the logged-in user is the case's currently assigned user. If needing to route a case which is assigned to another user, then first reassign the case to the logged-in user and then route the case. Note that "routing" is also known as "derivating" in ProcessMaker.

PUT /api/1.0/{workspace}/cases/{app_uid}/route-case

Method: workflow/engine/src/ProcessMaker/Services/Api/Cases.php: doPutRouteCase($app_uid, $del_index = null)

URL Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/route-case
app_uid	Case's unique ID.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/route-case

PUT Parameters:

Parameter	Description
del_index	Optional. Specify the delegation index of a current task which will be routed. The delegation index counts the routings for a case starting from 1. The first task in a process has a delegation index of 1, the second task is 2, etc. If this parameter is not included, then the current task with the highest delegation index will be routed.

Result:

If successful, then the HTTP status code is set to 200 and there is no return object. If an error occurred, then the HTTP status code is set to 400 or greater and an error object is returned, such as:

PHP example:

In this example, there are 3 parallel current tasks, so the delegation index 5 will be specified to route the case:

Cancel Case: PUT /cases/{app_uid}/cancel

Cancel a case. The case's status is changed to "CANCELLED" and it is no longer possible to open or changed the case, but all the data for the case remain in the database.

PUT /api/1.0/{workspace}/cases/{app_uid}/cancel

Warning: The logged-in user should only be able to cancel a case if he/she is the the currently assigned user to the case or the logged-in user has the PM_CANCELCASE permission in his/her role.

Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/cancel
app_uid	Case's unique ID.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/cancel

Result:

If successful, the HTTP status code is set to 200 and there is no return value. If an error occurred, then the HTTP status code is set to 300 or greater, and an error object is returned, such as:

PHP example:

Pause Case: PUT /cases/{app_uid}/pause

Pause a case.

PUT /api/1.0/{workspace}/cases/{app_uid}/pause

which allows any user to change the variables on any case. This endpoint also

Warning: In order to pause a case, the logged-in user should either be currently assigned to work on the case or should have access to the case as a Process Supervisor.

URL Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/pause
app_uid	Case's unique ID.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/pause

PUT Parameters:

Parameter	Description	Example
unpaused_date	Date in "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS" format when the case will be unpaused. If the case will be paused indefinitely, then set this parameter as "" (empty string).	"2015-05-21 23:59:59"

Result:

If successful, then the HTTP status code will be set to 200 and there will be no return value. If an error occurred, then the HTTP status code will be 300 or greater and an error object will be returned, such as:

PHP example:

Unpause Case: PUT /cases/{app_uid}/unpause

Unpause a case which was previously paused. After being unpaused, the case may be opened and worked on again.

PUT /api/1.0/{workspace}/cases/{app_uid}/unpause

Warning: In order to unpause a case, the logged-in user should either be currently assigned to work on the case or should have access to the case as a Process Supervisor.

URL Parameters:

Parameter	Description	Example
{workspace}	Workspace name.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/unpause
app_uid	Case's unique ID.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/unpause

PUT Parameters:

Parameter	Description	Example
unpaused_date	Optional. The date in "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS" format when the cases will be unpaused. If not included or set to "" (empty string), then the case will be immediately unpaused.	"2015-12-31"

Result:

If successful, then the HTTP status code is set to 200 and there is no return object. Otherwise, the HTTP status code is set to 300 or higher and an error object is returned, such as:

PHP example:

Execute Trigger: PUT /cases/{app_uid}/execute-trigger/{tri_uid}

Execute a trigger in a case.

PUT /api/1.0/{workspace}/cases/{app_uid}/execute-trigger/{tri_uid}

URL Parameters:

Parameter	Description	Example
workspace	Workspace name.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674
app_uid	Unique ID of the case where the trigger will be executed.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674
tri_uid	Unique ID of the trigger to execute. To find a trigger's UID, search in the wf_{workspace}.TRIGGERS.TRI_UID field in the database. Note that the trigger can be executed, even if it is not assigned to fire in the case's process.	/api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674

Result:

If successful, then the HTTP status code is set to 200 and there is no return object. If an error occurred, then the HTTP status code is set to 400 or greater and an error object is returned, such as:

 

PHP Example:

A trigger with the ID "37823572555ba5891041136049273220" contains the code:

This trigger is executed and then the endpoint GET cases/{app_uid}/variables endpoint is executed to retrieve the @@dueDate and @@usersQuery variables which were set by the trigger.

Delete Case: DELETE /cases/{app_uid}

Delete a case, which means that its record is removed from the wf_<WORKSPACE>.APPLICATION table, so its case data is deleted. Other information may remain about the case in other database tables, such as APP_DELEGATION, APP_DOCUMENT, APP_MESSAGE, etc., plus any files uploaded or generated in the case will remain in the shared directory on the ProcessMaker server. Only cases in their initial task may be deleted by the currently assigned user to the case. For all other cases, it is recommended to cancel them using PUT /cases/{app_uid}/cancel.

DELETE /api/1.0/{workspace}/cases/{app_uid}/

URL Parameters:

Parameter	Description	Example
workspace	Workspace name which by default is "workflow".	/api/1.0/workflow/cases/37213410154d375de3e3620044382558
app_uid	Case's unique ID.	/api/1.0/workflow/cases/37213410154d375de3e3620044382558

Result:

If the case was deleted, the HTTP status code is set to 200 and there is no response. If an error occurs, the HTTP status code is 400 or greater and an error object is returned, such as:

PHP Example:

Case Variables

These endpoints get or set the variables for a given case. Use the GET method to obtain the variables from a case and the PUT method to set variables in a case.

Get Variables: GET /cases/{app_uid}/variables

Get variables from a case. Note that this endpoint can return the variables from any case, regardless of its status, so it can get the variables for paused, completed or even canceled cases. The only cases for which it can't get the variables are deleted cases, because their records has been removed from the APPLICATION table in the database.

GET /api/1.0/{workspace}/api/1.0/{workspace}/cases/{app_uid}/variables

URL Parameters:

Parameter	Description	Example
workspace	Workspace name which by default is "workflow".	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/variables
app_uid	Case's unique ID.	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/variables

Result:
If successful, then returns HTTP status code of 200 (OK) and returns an object of variables, such as:

Note: DynaForm fields which have integer or float variables have their values stored as strings, so it may be necessary to convert their values to numbers if doing mathematical operations. Grids and the results of database queries are stored as an associative array of associative arrays in ProcessMaker, but they are converted into an object of objects, because JSON doesn't support associative arrays.

When reading this object of objects in PHP, it is recommended to either use json_decode($json, true) to convert the return object into an associative array or get_object_vars() to convert the rows in a grid to an associative array. See the example below.

PHP Example:

This example, using the case variables returned in the example, converts the "reviewersList" grid from an object to an associative array and then loops through that array to print out the names of the reviewers and their decision to approve or disapprove the contract.

Set Variables: PUT /cases/{app_uid}/variable

Set variable(s) in a case.

PUT /api/1.0/{workspace}/api/1.0/{workspace}/cases/{app_uid}/variable

URL Parameters:

Parameter	Description	Example
workspace	Workspace name which by default is "workflow".	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/variable
app_uid	Case's unique ID.	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/variable

PUT Parameters:

A object where the name of each element is the variable name and its value will be the new value of the case variable in the specified case. If the variable doesn't already exist, it will be automatically created. See New Case: POST /cases for more information on how to set the values of different types of fields.

Result:
If successful, sets the HTTP status code to 200 (OK) and there is no return object. If an error occurred, then the HTTP status code is set to 300 or greater and an error object is returned, such as:

JavaScript example:

PHP example:

Input Documents

The following endpoints are used to control Input Document files uploaded to cases:

1. Get Input Documents for case: GET /cases/{app_uid}/input-documents
2. Get an Input Document file: GET /cases/{app_uid}/input-document/{app_doc_uid}
3. Upload Input Document: POST /cases/{app_uid}/input-document
4. Remove an Input Document file: DELETE /cases/{app_uid}/input-document/{app_doc_uid}

Get Input Documents: GET /cases/{app_uid}/input-documents

Returns a list of the uploaded Input Document files for a given case. If versioning is enabled, it only returns the most recent versions of Input Document files. Note that only Input Document files are returned when the logged in user has one of the following rights to view the files:

• The Input Document is a step in the current task of the case and the logged-in user is currently assigned to work on the case.
• The logged in user has process permissions to view the task where the Input Document is a step.

Note that it is possible to still get the list of Input Documents for a case, regardless of the case's status, so it is possible to get the Input Document files for cases which have been paused, canceled or completed if the user has process permissions.

Note that this endpoint does NOT return Input Document files when the logged-in user is assigned as Process Supervisor to the Input Document, so the user will have to be given Process Permissions (This issue is fixed from version 3.0.1.5).

GET /api/1.0/{workspace}/cases/{app_uid}/input-documents

URL Parameters:

Parameter	Description	Example
workspace	Workspace name which by default is "workflow".	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/input-documents
app_uid	Case's unique ID.	/api/1.0/workflow/cases/37213410154d375de3e3620044382558/input-documents

Result:

If successful, the HTTP status is set is 200 and array of objects is returned with information about each uploaded Input Document file:

[	Start array of file objects.
{	Start first file object.
"app_doc_uid",	Unique ID of Input Document file.
"app_doc_filename",	Filename of Input Document file
"doc_uid",	Unique ID of the Input Document definition.
"app_doc_version",	Version of the uploaded file, with counts starting from "1". If versioning isn't enabled, then this value is always "1".
"app_doc_create_date",	Datetime in "YYYY-MM-DD HH:MM:SS" format when file was uploaded.
"app_doc_create_user",	User who uploaded file to the case in "last-name, first-name (username)" format.
"app_doc_type",	Type of document which can be: "INPUT", "OUTPUT" or "ATTACHED". (An "ATTACHED" file is uploaded through a DynaForm's file field which isn't associated with an Input Document).
"app_doc_index",	The case document index which counts the files in the order they were uploaded/created in the case, regardless of whether they are Input Document files, Output Document files or attached to a file field in a DynaForm. The first file has an index of 1, the second has an index of 2, etc. This index also counts files which are uploaded as previous versions of Input Document files.
"app_doc_link",	Relative URL to download the file at "cases/cases_ShowDocument?a={app_doc_uid}&v={app_doc_version}". To form a complete URL, prepend "https://{domain}/sys{workspace}/{lang}/{skin}/" to this relative URL. It is possible to download the file as long as the user has an active login session, which by default should last for 24 minutes, so the file can be downloaded by the same script which called this endpoint, using a download program such as cURL or wget. In PHP, functions like file() and file_get_contents() can be used to download the contents of a file from a URL. In JavaScript, the web browser can be redirected to open this URL by assigning it to window.location.href. XMLHttpRequest can be used to download the contents of the file to a variable.
},	End first file object
...	Any additional file objects
]	End array.

For example:

Note: The logged-in user may only see information about Input Document files if he/she is currently assigned to the case or has process permissions to see the Input Document to which the files were uploaded.

PHP examples:

This example looks for an Input Document file named "client_bill.txt" and then uses the file_get_contents() function to download it. It then uses the preg_match() function to look for the first line which contains "Invoice No: XXXXXXXXXXXX" so it can extract the invoice number. Note that file_get_contents() can be used to download both text files and binary files, but preg_match() can only be used to search in text files.

This example uses cURL to download all the Input Document file(s) for a case. If image files are found, then they are stored on the harddrive. Using cURL downloads both the contents of the file and its header, which can be useful if needing information from the header. The tricky part is separating the contents from the header.

The following example first uses cURL to download the first file in the case, then it serves up that same file so the user can download the file as an attachment in the user's web browser. Depending on the configuration of the web browser, file will either be automatically downloaded to the user's local computer or a dialog box will open asking where the user wants to save the file, which gives the user the opportunity to cancel the download.

Note that nothing should be printed by the code or it will corrupt the contents of the downloaded file. It is only possible to download one file at a time with this sample code, so it is recommended to combine all the files in a ZIP file if needing to download more than one file.

Get Input Document: GET /cases/{app_uid}/input-document/{app_doc_uid}

Return an uploaded document for a given case.

GET /api/1.0/{workspace}/cases/{app_uid}/input-document/{app_doc_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name
app_uid	String	Case unique ID
app_doc_uid	String	Input Document file's unique ID, which

Result:

Returns an object with the same information about the specified Input Document file which is returned by GET /cases/{app_uid}/input-documents. For example:

Upload Input Document: POST /cases/{app_uid}/input-document

Uploads a new Input Document file to a specified case. Note that the logged-in user must either be currently assigned to work on the case or a Process Supervisor with permissions to access the Input Document; otherwise, this endpoint returns an HTTP status code of 302.

POST /api/1.0/{workspace}/cases/{app_uid}/input-document

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
app_uid	String	Case UID

POST Fields:

Name	Type	Description
inp_doc_uid	String	The unique ID of the Input Document definition.
tas_uid	String	The unique ID of the task where the Input Document is a step.
app_doc_comment	String	A comment in plain text about the uploaded file.
form	String	The path to the file to upload to the ProcessMaker server. This path cannot be a web URL. If needing to use a file located on the internet, first download the file and save it as a local file to be uploaded. If using PHP, be sure to place "@" before the path to include the file. If @ is not used, the status code will be 400 with the message "Bad Request: This filename does not exist!". If using PHP 5.5 or later, a new security feature has been added to prevent code injection attacks, so use a CurlFile object instead of @. See the code example below. The uploaded file will have the same filename. To rename the file, move it to a new file location before uploading it to this REST endpoint.

Result:

If the file was successfully uploaded, it returns an HTTP status code of 200 and a response object with information about the new Input Document file, such as:

If an error occurs, an HTTP status code of 300 or greater is returned with a message object such as:

Note: If using PHP, in order to send POST fields to REST endpoints which contain objects or arrays, the POST fields have to be encoded with the http_build_query() function. However, passing the filename through the http_build_query() function mangles it and this endpoint will return a status code of 400 and the message "Bad Request: This filename does not exist!". Either make a pmRestRequest() function which doesn't use the http_build_query() function or use code like the example below to upload the file.

Note: If the uploaded file is larger than the upload_max_filesize setting in the php.ini file on the ProcessMaker server, then the HTTP status code will be 413 with the error message "Request Entity Too Large: Uploaded file (filename) is too big.". If the uploaded file is larger than the post_max_size setting in the php.ini file on the ProcessMaker server, then the endpoint will return a status code and the message "Bad Request: `tas_uid` is required but missing".

Note: It is not possible to send a file to the POST cases/{app_uid}/input-document endpoint using JavaScript, because the JavaScript language is not designed to handle file uploads. If using JavaScript, then some server-side code will need to be added to handle file uploads. See the PHP code examples below.

PHP Example 1:

PHP Example 2:

The following HTML form contains a file input field named "receipts[]" which allows multiple files to be selected and uploaded at the same time:

When file(s) are selected and the above form is submitted, the $_FILES superglobal in PHP will contain information about the files which were uploaded to the "receipts[]" file field. For example, if two files were uploaded named "officeExpenses.jpg" and "inventoryList.xls", then $_FILES might contain:

In the same directory, the following processFiles.php file takes the files which were uploaded and sends them to the POST cases/{app_uid}/input-document endpoint:

Delete Input Document: DELETE /cases/{app_uid}/{del_index}/input-document/{app_doc_uid}

Remove an Input Document file from a given case.

DELETE /api/1.0/{workspace}/cases/{app_uid}/{del_index}/input-document/{app_doc_uid}

Note: In version 3.0.1.4 and later, this endpoint checks whether the user has the Process Permissions to delete the Input Document file.

Note: This endpoint does not delete the record of the Input Document file from the database, nor delete its file on the server's harddrive, stored at {install-directory}/shared/sites/{workspace}/files/XXX/XXX/XXX/XXXXXXXXXXXXXXXXXXXXXXX/{app_doc_uid}_{version}.{extension}, where XXX... is the app_uid (case ID). All it does change the value of the wf_{workspace}.APP_DOCUMENT.APP_DOC_STATUS field in the database from "ACTIVE" to "DELETED" so the file will not appear in the ProcessMaker interface. Therefore, the deletion of the file can be undone by updating the database record to change the status back to "ACTIVE".

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
app_uid	String	Unique ID for case.
del_index	Integer	Delegation index for the task where the Input Document file was uploaded.
app_doc_uid	String	Unique ID for the Input Document file.

Result:

If the file was successfully removed, then the HTTP status code is set to 200 and there is no return object. Otherwise, the HTTP status code is set to 300 or greater and an error object is returned, such as:

PHP example:

Output Documents

The following endpoints are used to access and control generated Output Documents:

1. Get the generated Output Documents for a case: GET /cases/{app_uid}/output-documents
2. Get one generated Output Document: GET /cases/{app_uid}/output-document/{app_doc_uid}
3. Generate an Output Document for a case: POST /cases/{app_uid}/output-document
4. Removes a generated Output Document from a case: DELETE /cases/{app_uid}/output-document/{app_doc_uid}

Get Output Documents: GET /cases/{app_uid}/output-documents

Return a list of generated Output Documents for a given case.

GET /api/1.0/{workspace}/cases/{app_uid}/output-documents

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-documents
app_uid	Unique ID of case	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-documents

Result:

If successful, the HTTP status code is set to 200 and it returns the following array of objects with information about the generated Output Documents in the case:

[	Start array.
{	Start first Output Document object.
"app_doc_uid",	Unique ID of generated case document.
"app_doc_filename",	Filename of the generated output document file. If
"doc_uid",	Unique ID of the Output Document definition.
"app_doc_version",	Number of the version of the generated Output Document, which is 1 for the first time it is generated, 2 for the second, etc.
"app_doc_create_date",	Datetime in "YYYY-MM-DD HH:MM:SS" format when the Output Document was generated. Hours are on a 24 clock system.
"app_doc_create_user",	The user who generated the Output Document in "last-name, first-name (username)" format.
"app_doc_type",	Type of document which is "OUTPUT DOC" if generating a MS Word file, "OUTPUT PDF" if generating a PDF file, or "OUTPUT BOTH" if generating both types of files.
"app_doc_index",	The index number of files in the case, which starts counting all uploaded Input Document files, generated Output Documents and attached files (from file fields in DynaForms), so the first file is 1, the second is 2, etc. Note that a new index number is generated for each version of a generated Output Document.
"app_doc_link",	The relative link to download the generated Output Document file in the format "cases/cases_ShowOutputDocument?a={app_doc_uid}&v={version}&ext={extension}&random={random}", where the version is 1 if the first time it is generated, 2 for the second time it is generated, etc. The extension can be pdf or doc. If available in both formats then it will be pdf and needs to be caused to doc to download the MS Word file. To form the complete URL to download the file, prepend "http://{domain}/sys{workspace}/{lang}/{skin}/" to this relative URL, such as "https://example.com/sysworkflow/en/neoclassic/"
},	End first Output Document object array.
...	Any additional Output Document objects.
]	End array.

For example:

Note that if the logged-in user doesn't have rights to view the generated Output Documents or if there are no generated Output Documents in the case, then an empty array will be returned.

PHP Example

This example downloads the generated DOC file for each Output Document. The generated DOC file is really just an HTML file which has a ".doc" extension added, so it can be opened and searched like a normal text file, once it has been converted to plain text. This code uses strip_tags() to remove the HTML tags and uses preg_replace() to replace the

and
tags with new lines (\n). Then, it searches for "Due Date: ..." in the plain text, and then prints out the filename and its due date for each Output Document.

Get Output Document: GET /cases/{app_uid}/output-document/{app_doc_uid}

Return a generated Output Document for a given case.

GET /api/1.0/{workspace}/cases/{app_uid}/output-document/{app_doc_uid}

Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_uid	Unique ID of the case	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_doc_uid	Unique ID of the case document	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166

Result:

If successful, it returns an HTTP status code of 200 and an object containing information about the specified output document, such as:

PHP Example

Download the generated PDF file for an Output Document and save it to the local harddrive.

Generate Output Document: POST /cases/{app_uid}/output-document

Generate a specified Output Document for a given case, meaning that a PDF, a DOC or both files (depending on options selected in the definition of the Output Document) will be created, inserting any variables in the template.

If the Output Document already exists, then it will be regenerated. If versioning is enabled, then the regenerated files will be given a new version number and document index number, but if version is NOT enabled, then the existing files will be overwritten with the same version number and document index number.

POST /api/1.0/{workspace}/cases/{app_uid}/output-document

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document
app_uid	Unique ID of the case	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document

POST fields:

Name	Description	Example
out_doc_uid	Unique ID of the Output Document definition.

Result:

Type	Description
object	Returns an object with information of the generated document

Example:
Request

Response

If the Output Document was successfully generated, then the HTTP status code is set to 200 and it returns a object with information about the generated Output Document, such as:

PHP Example

Generate the Output Document and then force the PDF file to be downloaded as an attachment by the user's web browser.

Delete Output Document: DELETE /cases/{app_uid}/output-document/{app_doc_uid}

Remove a generated Output Document from a case.

DELETE /api/1.0/{workspace}/cases/{app_uid}/output-document/{app_doc_uid}

Note: This endpoint does not delete the record for the generated Output Document located in the wf_{workspace}.APP_DOCUMENT table in the database, nor does it delete the physical file(s) from the file system which are located at: {Install-Directory}/shared/sites/{workspace}/files/XXX/XXX/XXX/XXXXXXXXXXXXXXXX/outdocs/{app_doc_uid}, where XXX... is the app_uid. Instead, it simply changes the value of the wf_{workspace}.APP_DOCUMENT.APP_DOC_STATUS field in the database from "ACTIVE" to "DELETED" so that the files can not be seen in the ProcessMaker interface. Writing to the database to change this value back to "ACTIVE" will undelete the file.

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_uid	Unique ID of the case	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_doc_uid	Unique ID of the case document	/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166

Result:

If the generated Output Document was removed, then it returns an HTTP status code of 200 and no response object.

Example:

Cases Notes

The following endpoints are used to manipulate case notes:

1. Get a list of notes for a case: GET /cases/{app_uid}/notes
2. Get a page of notes for a case: GET /cases/{app_uid}/notes/paged
3. Create a new note for a case: POST /cases/{app_uid}/note/

Get Case Notes: GET /cases/{app_uid}/notes

Get a list of the case notes for a specified case.

GET /api/1.0/{workspace}/cases/{app_uid}/notes

Parameters:

Name	Description	Default	Example
workspace	Workspace name		/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes
app_uid	Unique ID of the case where the notes are attached.		/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes
Filters for case notes
start={num}	Optional. Number where the list of notes starts.	0	/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?start=30
limit={num}	Optional. The number of notes to list.	25	/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?limit=10
sort={field}	Optional. Field used to order the list, which is one of the APP_NOTES fields)	APP_NOTES.NOTE _DATE	/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?sort=APP_NOTES.USR_UID
dir={dir}	Optional. Order which notes are listed: asc, desc	desc	/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?dir=asc
usr_uid={uid}	Optional. Unique ID of the user who posted the case note.		/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?usr_uid=86994841555ce4e51406a80055794876
date_from={date}	Optional. Notes which were created from this date on, in "YYYY-MM-DD" format.		/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?date_from=2015-01-31
date_to={data}	Optional. Notes which were created up to (but not including) this date in "YYYY-MM-DD" format.		/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?date_to=2015-12-31
search={text}	Optional. Search for notes with the specified text in the note's content. Make sure to URL encode in UTF-8 the searched text, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3.		/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?search=contract%20details

Result:

If successful, the HTTP status code is set to 200 and the response is a array of case note objects:

[	Start array.
{	Start first case note object.
"app_uid",	The unique ID of the case where the note is attached.
"usr_uid",	The unique ID of the user who added the note.
"note_date",	The date when the note was added in "YYYY-MM-DD HH:MM:SS" format.
"note_content"	The content of the case note.
},	The date when the note was added in "YYYY-MM-DD HH:MM:SS" format.
...	Any additional case notes.
]	End array.

For example:

Note: Only users who have been assigned Process Permissions to case notes may access them. Even the user who is currently assigned to work on the case may not see the case notes without Process Permission for case notes. If the logged-in user doesn't have proper permissions to access case notes, the following error object is returned:

PHP Example:

Prints out the notes for a case. Looks up information about users to add the full name and username to notes.

Get Page of Case Notes: GET /cases/{app_uid}/notes/paged

Get a page of the cases notes for a specified case.

GET /api/1.0/{workspace}/cases/{app_uid}/notes/paged

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes/paged
app_uid	Unique ID of case	/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes/paged
filters	Optional. Any of the filters listed above.	/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes/paged?search=contract

Result:

If successful, the HTTP status code is set to 200 (OK) and the response is a page object with information about the results and an array of case note objects in the data member, such as:

Note: Only users who have been assigned Process Permissions to case notes may access them. Even the user who is currently assigned to work on the case may not see the case notes without Process Permission for case notes. If the logged-in user doesn't have proper permissions to access case notes, the following error object is returned:

Create Case Note: POST /cases/{app_uid}/note

Create a new case note for a given case. Note that only users who are currently assigned to work on the case or have Process Permissions to access case notes may create a case note.

POST /api/1.0/{workspace}/cases/{app_uid}/note

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/cases/115968518533473068ad299078535175/note
app_uid	Unique ID of the case.	/api/1.0/workflow/cases/115968518533473068ad299078535175/note

POST Fields:

Name	Description
note_content	Content of the case note in plain text. Use \n to insert a new line in the text.
send_mail	Optional. Set to 1 to send an email with the content of the case note in its body to all the participants in the case. The default is 0, which doesn't send an email. Note that this endpoint adds the emails to the queue, but they only sent out when the cron.php file executes.

Result:

If the case note was created, then the HTTP status code is set to 200 (OK) and there is no return value. If the status code is 300 or higher then an error occurred, and an error object will usually be returned, such as:

PHP Example:

The following example creates a new case note, which is sent out in an email to all the participants in the case: