ExtraRest plugin

From pmusers
Jump to: navigation, search

The extraRest plugin includes extra REST endpoints to be used in ProcessMaker. Some of these endpoints get around security restrictions in ProcessMaker's official endpoints. Others provide functionality not provided by the official endpoints.


Plugin: extraRest-1.12.tar
Author: Amos Batto (amos@processmaker.com)
Version: 1.11 (2019-02-06)
Tested in: ProcessMaker 3.2.1 - 3.3.0 Community in Debian 9.5 with PHP 5.6.37
License: Public Domain


Contents

Install this plugin in ProcessMaker

  • Save the plugin's .tar file to your local computer.
  • Then, login to ProcessMaker as a user with the PM_SETUP_ADVANCE permission in her role (such as the "admin" user).
  • Then, go to Admin > Plugins > Plugin Manager and click on the Import button and select the .tar file to upload it to ProcessMaker.
  • Once uploaded, then select the plugin in the list and click on Enable.

Upgrade this plugin in ProcessMaker

  • Download the new version of this plugin's .tar file to your local computer.
  • Then, login to ProcessMaker as a user with the PM_SETUP_ADVANCE permission in her role (such as the "admin" user).
  • Then, go to Admin > Plugins > Plugin Manager and select the existing version of this plugin in the list. Then, click on the Disable button to deactivate the plugin. Then, click on Delete to remove the old version's files from the workflow/engine/plugins directory.
  • Then, click on the Import button and select the .tar file to upload the new version of the plugin to ProcessMaker.
  • Once uploaded, then select the plugin in the list and click on Enable.

More Information

For more information, untar the plugin and examine the source code in the file extraRest/src/Services/Api/ExtraRest/extra.php.

REST endpoints

Claim case: POST extrarest/case/{app_uid}/claim

Claim a case for a user where a task is unassigned because the task is Self Service or Self Service Value Based Assignment.

POST http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/{app_uid}/claim

URL parameters:

  • app_uid: Unique ID of case to claim.

POST parameters:

  • int del_index: Optional. The delegation index of the task to claim. Only needs to be included if there are multiple open tasks in the case.
  • string usr_uid: Optional. Unique ID of the user to assign to case. Only include if the logged-in user is a process supervisor assigning another user.

Response:

HTTP status code is 200 and no response if successful.

PHP example 1:

Assign the logged-in user to a Self Service Task where there is only one open task in case:

$caseId = '2554682895ac25995666e24055342045';
$url = "/api/1.0/workflow/extrarest/case/$caseId/claim";
$aVars = array();
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

PHP example 2:

Assign the logged-in user to a Self Service Task where there are 2 open tasks in case:

$caseId = '2554682895ac25995666e24055342045';
$url = "/api/1.0/workflow/extrarest/case/$caseId/claim";
$aVars = array(
   'del_index' => 3
);
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

PHP example 3:

Assign another user to Self Service Task when the logged-in user is a Process Supervisor:

$caseId = '2554682895ac25995666e24055342045';
$url = "/api/1.0/workflow/extrarest/case/$caseId/claim";
$aVars = array(
  'del_index' => 2,  
  'usr_uid'   => '10654575559caec5e953104064429578' //unique ID of user to assign to task
);
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

Route case: PUT extrarest/case/{app_uid}/route-case

Available in version 1.5 and later.

Route a case to the next task(s) in the process. Unlike the official PUT /cases/app_uid/route-case endpoint, this endpoint has an option to allow Process Supervisors to route the case. The logged-in user must either be assigned to the task indicated by the del_index or must be assigned as the Supervisor for the case's process.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/{app_uid}/route-case

URL parameters:

  • app_uid: Unique ID of case to be routed.

POST parameters:

  • int del_index: Optional. The delegation index of the task to be routed. If not included, then the most recently opened task will be selected. Only needs to be included if there are multiple open tasks in the case.
  • string usr_uid: Optional. Unique ID of the user who routes the task. Only need to include if not wishing the assigned user to be listed as the router of the case.
  • boolean execute_triggers: Optional. Set to true if any triggers before assignment should be executed. Default is false.


Response:

The HTTP status code is 200 if successful and an object which holds a routing array with the next task(s) in the case is returned:

{
    "routing": [
        { 
            "userId":          "00000000000000000000000000000001", 
            "userName":        "Administrator admin", 
            "taskId":          "2084179395b0345cd555746076390652", 
            "taskName":        "Task 2", 
            "delIndex":        "2", 
            "delThread":       "1", 
            "delThreadStatus": "OPEN" 
        } 
    ] 
}

If the case has completed (i.e., reached an end event), then the the HTTP status code will be 200 and an empty routing array will be returned:

{
  "routing": []
}

If the case has already been routed, then the HTTP status code will be set to 400 and the following error object is returned:

{
    "error": {
        "code": 400,
        "message": "Bad Request: This case delegation is already closed or does not exist"
    }
}

PHP example:

Route a case which only has one open task and print out the title and assigned user of the next task in the case:

$caseId = '2554682895ac25995666e24055342045';
$url = "/api/1.0/workflow/extrarest/case/$caseId/route-case";
$aVars = array();
$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);
if ($oRet and $oRet->status == 200)
   if (empty($oRet->response->routing)) {
      echo "Case '$caseId' completed.";
   }
   else {
      echo "Case '$caseId' routed to task '{$oRet->response->routing[0]->taskName}' ".
         "assigned to user '{$oRet->response->routing[0]->taskName}'.");
   }
}

PHP example 2:

Route a task with a delegation index of 3 and execute any triggers before assignment:

$caseId = '2554682895ac25995666e24055342045';
$url = "/api/1.0/workflow/extrarest/case/$caseId/claim";
$aVars = array(
   'del_index'        => 3,
   'execute_triggers' => true
);
$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);

Get Next tasks: GET extrarest/case/{app_uid}/next-tasks

Available in version 1.12 and later.

Get the next task(s) in a case, which is useful to know where a case will go next before executing extrarest/cases/{app_uid}/route-case.

This endpoint should only be called for an open delegation in a case. Only the currently assigned user to the case or a Supervisor to the case's process can call this endpoint.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/{app_uid}/next-tasks?del_index={index}
    &execute_triggers={yes_or_no}&revert_vars={yes_or_no}

URL parameters:

  • app_uid: Unique ID of the case.
  • del_index: Optional. The index of an open delegation in a case. If not specified, then the last open delegation assigned to the logged-in user will be looked up.
  • execute_triggers: Optional. If set to yes, then execute any triggers before assignment and before routing, which is recommended if the routing depends on case variables. Default is no.
  • $revert_vars: Optional. If executing triggers and set to yes (which is the default), the case variables will be reverted, so the data isn't changed by executing the triggers. To not revert the variables, set to no.

Response:

The HTTP status code is 200 if successful and a JSON object is returned which holds information about the currently open delegation. Under "NEXT_TASK", it holds information about the next task in the process.

For example:

Request:

GET http://example.com/api/1.0/workflow/extrarest/case/1015821305c3427b0a83074003569194/next-tasks?del_index=4&execute_triggers=yes&revert_vars=yes

Response:

{
    "1": {
        "TAS_UID": "1302300845c708f87cc67d7033708318",
        "ROU_NEXT_TASK": "2851013045c708f87da4c10047434757",
        "ROU_TYPE": "PARALLEL",
        "ROU_DEFAULT": "0",
        "ROU_CONDITION": "",
        "APP_UID": "9949957565c70907377e521000682848",
        "DEL_INDEX": 1,
        "USER_UID": "00000000000000000000000000000001",
        "PRO_UID": "2914468325c708f5e391090035643978",
        "TAS_ID": 103,
        "TAS_TITLE": "Employee reads rules",
        "TAS_DESCRIPTION": "",
        "TAS_DEF_TITLE": "",
        "TAS_DEF_SUBJECT_MESSAGE": "",
        "TAS_DEF_PROC_CODE": "",
        "TAS_DEF_MESSAGE": "",
        "TAS_DEF_DESCRIPTION": "",
        "TAS_TYPE": "NORMAL",
        "TAS_DURATION": 1,
        "TAS_DELAY_TYPE": "",
        "TAS_TEMPORIZER": 0,
        "TAS_TYPE_DAY": "",
        "TAS_TIMEUNIT": "DAYS",
        "TAS_ALERT": "FALSE",
        "TAS_PRIORITY_VARIABLE": "",
        "TAS_ASSIGN_TYPE": "BALANCED",
        "TAS_ASSIGN_VARIABLE": "@@SYS_NEXT_USER_TO_BE_ASSIGNED",
        "TAS_GROUP_VARIABLE": "",
        "TAS_MI_INSTANCE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCE",
        "TAS_MI_COMPLETE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCES_COMPLETE",
        "TAS_ASSIGN_LOCATION": "FALSE",
        "TAS_ASSIGN_LOCATION_ADHOC": "FALSE",
        "TAS_TRANSFER_FLY": "FALSE",
        "TAS_LAST_ASSIGNED": "00000000000000000000000000000001",
        "TAS_USER": "0",
        "TAS_CAN_UPLOAD": "FALSE",
        "TAS_VIEW_UPLOAD": "FALSE",
        "TAS_VIEW_ADDITIONAL_DOCUMENTATION": "FALSE",
        "TAS_CAN_CANCEL": "FALSE",
        "TAS_OWNER_APP": "FALSE",
        "STG_UID": "",
        "TAS_CAN_PAUSE": "FALSE",
        "TAS_CAN_SEND_MESSAGE": "TRUE",
        "TAS_CAN_DELETE_DOCS": "FALSE",
        "TAS_SELF_SERVICE": "FALSE",
        "TAS_START": "TRUE",
        "TAS_TO_LAST_USER": "FALSE",
        "TAS_SEND_LAST_EMAIL": "FALSE",
        "TAS_DERIVATION": "NORMAL",
        "TAS_POSX": 175,
        "TAS_POSY": 99,
        "TAS_WIDTH": 110,
        "TAS_HEIGHT": 60,
        "TAS_COLOR": "",
        "TAS_EVN_UID": "",
        "TAS_BOUNDARY": "",
        "TAS_DERIVATION_SCREEN_TPL": "",
        "TAS_SELFSERVICE_TIMEOUT": 0,
        "TAS_SELFSERVICE_TIME": 0,
        "TAS_SELFSERVICE_TIME_UNIT": "",
        "TAS_SELFSERVICE_TRIGGER_UID": "",
        "TAS_SELFSERVICE_EXECUTION": "EVERY_TIME",
        "TAS_NOT_EMAIL_FROM_FORMAT": 0,
        "TAS_OFFLINE": "FALSE",
        "TAS_EMAIL_SERVER_UID": "",
        "TAS_AUTO_ROOT": "FALSE",
        "TAS_RECEIVE_SERVER_UID": "",
        "TAS_RECEIVE_LAST_EMAIL": "FALSE",
        "TAS_RECEIVE_EMAIL_FROM_FORMAT": 0,
        "TAS_RECEIVE_MESSAGE_TYPE": "text",
        "TAS_RECEIVE_MESSAGE_TEMPLATE": "alert_message.html",
        "TAS_RECEIVE_SUBJECT_MESSAGE": null,
        "TAS_RECEIVE_MESSAGE": null,
        "NEXT_TASK": {
            "PRO_UID": "2914468325c708f5e391090035643978",
            "TAS_UID": "2851013045c708f87da4c10047434757",
            "TAS_ID": 104,
            "TAS_TITLE": "Safety procedures",
            "TAS_DESCRIPTION": "",
            "TAS_DEF_TITLE": "",
            "TAS_DEF_SUBJECT_MESSAGE": "",
            "TAS_DEF_PROC_CODE": "",
            "TAS_DEF_MESSAGE": "",
            "TAS_DEF_DESCRIPTION": "",
            "TAS_TYPE": "NORMAL",
            "TAS_DURATION": 1,
            "TAS_DELAY_TYPE": "",
            "TAS_TEMPORIZER": 0,
            "TAS_TYPE_DAY": "",
            "TAS_TIMEUNIT": "DAYS",
            "TAS_ALERT": "FALSE",
            "TAS_PRIORITY_VARIABLE": "",
            "TAS_ASSIGN_TYPE": "BALANCED",
            "TAS_ASSIGN_VARIABLE": "@@SYS_NEXT_USER_TO_BE_ASSIGNED",
            "TAS_GROUP_VARIABLE": "",
            "TAS_MI_INSTANCE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCE",
            "TAS_MI_COMPLETE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCES_COMPLETE",
            "TAS_ASSIGN_LOCATION": "FALSE",
            "TAS_ASSIGN_LOCATION_ADHOC": "FALSE",
            "TAS_TRANSFER_FLY": "FALSE",
            "TAS_LAST_ASSIGNED": "0",
            "TAS_USER": "0",
            "TAS_CAN_UPLOAD": "FALSE",
            "TAS_VIEW_UPLOAD": "FALSE",
            "TAS_VIEW_ADDITIONAL_DOCUMENTATION": "FALSE",
            "TAS_CAN_CANCEL": "FALSE",
            "TAS_OWNER_APP": "FALSE",
            "STG_UID": "",
            "TAS_CAN_PAUSE": "FALSE",
            "TAS_CAN_SEND_MESSAGE": "TRUE",
            "TAS_CAN_DELETE_DOCS": "FALSE",
            "TAS_SELF_SERVICE": "FALSE",
            "TAS_START": "FALSE",
            "TAS_TO_LAST_USER": "FALSE",
            "TAS_SEND_LAST_EMAIL": "FALSE",
            "TAS_DERIVATION": "NORMAL",
            "TAS_POSX": 479,
            "TAS_POSY": 43,
            "TAS_WIDTH": 110,
            "TAS_HEIGHT": 60,
            "TAS_COLOR": "",
            "TAS_EVN_UID": "",
            "TAS_BOUNDARY": "",
            "TAS_DERIVATION_SCREEN_TPL": "",
            "TAS_SELFSERVICE_TIMEOUT": 0,
            "TAS_SELFSERVICE_TIME": 0,
            "TAS_SELFSERVICE_TIME_UNIT": "",
            "TAS_SELFSERVICE_TRIGGER_UID": "",
            "TAS_SELFSERVICE_EXECUTION": "EVERY_TIME",
            "TAS_NOT_EMAIL_FROM_FORMAT": 0,
            "TAS_OFFLINE": "FALSE",
            "TAS_EMAIL_SERVER_UID": "",
            "TAS_AUTO_ROOT": "FALSE",
            "TAS_RECEIVE_SERVER_UID": "",
            "TAS_RECEIVE_LAST_EMAIL": "FALSE",
            "TAS_RECEIVE_EMAIL_FROM_FORMAT": 0,
            "TAS_RECEIVE_MESSAGE_TYPE": "text",
            "TAS_RECEIVE_MESSAGE_TEMPLATE": "alert_message.html",
            "TAS_RECEIVE_SUBJECT_MESSAGE": null,
            "TAS_RECEIVE_MESSAGE": null,
            "TAS_PARENT": "",
            "USER_ASSIGNED": {
                "USR_UID": "6177238035c3d4f9b069616035753517",
                "USR_USERNAME": "amos",
                "USR_FIRSTNAME": "Amos",
                "USR_LASTNAME": "Batto",
                "USR_FULLNAME": "Batto, Amos",
                "USR_EMAIL": "amos@processmaker.com",
                "USR_STATUS": "ACTIVE",
                "USR_COUNTRY": "",
                "USR_CITY": "",
                "USR_LOCATION": "",
                "DEP_UID": ""
            }
        },
        "SOURCE_UID": "2851013045c708f87da4c10047434757"
    },
    "2": {
        "TAS_UID": "1302300845c708f87cc67d7033708318",
        "ROU_NEXT_TASK": "8446840565c708f87e39090040622552",
        "ROU_TYPE": "PARALLEL",
        "ROU_DEFAULT": "0",
        "ROU_CONDITION": "",
        "APP_UID": "9949957565c70907377e521000682848",
        "DEL_INDEX": 1,
        "USER_UID": "00000000000000000000000000000001",
        "PRO_UID": "2914468325c708f5e391090035643978",
        "TAS_ID": 103,
        "TAS_TITLE": "Employee reads rules",
        "TAS_DESCRIPTION": "",
        "TAS_DEF_TITLE": "",
        "TAS_DEF_SUBJECT_MESSAGE": "",
        "TAS_DEF_PROC_CODE": "",
        "TAS_DEF_MESSAGE": "",
        "TAS_DEF_DESCRIPTION": "",
        "TAS_TYPE": "NORMAL",
        "TAS_DURATION": 1,
        "TAS_DELAY_TYPE": "",
        "TAS_TEMPORIZER": 0,
        "TAS_TYPE_DAY": "",
        "TAS_TIMEUNIT": "DAYS",
        "TAS_ALERT": "FALSE",
        "TAS_PRIORITY_VARIABLE": "",
        "TAS_ASSIGN_TYPE": "BALANCED",
        "TAS_ASSIGN_VARIABLE": "@@SYS_NEXT_USER_TO_BE_ASSIGNED",
        "TAS_GROUP_VARIABLE": "",
        "TAS_MI_INSTANCE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCE",
        "TAS_MI_COMPLETE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCES_COMPLETE",
        "TAS_ASSIGN_LOCATION": "FALSE",
        "TAS_ASSIGN_LOCATION_ADHOC": "FALSE",
        "TAS_TRANSFER_FLY": "FALSE",
        "TAS_LAST_ASSIGNED": "00000000000000000000000000000001",
        "TAS_USER": "0",
        "TAS_CAN_UPLOAD": "FALSE",
        "TAS_VIEW_UPLOAD": "FALSE",
        "TAS_VIEW_ADDITIONAL_DOCUMENTATION": "FALSE",
        "TAS_CAN_CANCEL": "FALSE",
        "TAS_OWNER_APP": "FALSE",
        "STG_UID": "",
        "TAS_CAN_PAUSE": "FALSE",
        "TAS_CAN_SEND_MESSAGE": "TRUE",
        "TAS_CAN_DELETE_DOCS": "FALSE",
        "TAS_SELF_SERVICE": "FALSE",
        "TAS_START": "TRUE",
        "TAS_TO_LAST_USER": "FALSE",
        "TAS_SEND_LAST_EMAIL": "FALSE",
        "TAS_DERIVATION": "NORMAL",
        "TAS_POSX": 175,
        "TAS_POSY": 99,
        "TAS_WIDTH": 110,
        "TAS_HEIGHT": 60,
        "TAS_COLOR": "",
        "TAS_EVN_UID": "",
        "TAS_BOUNDARY": "",
        "TAS_DERIVATION_SCREEN_TPL": "",
        "TAS_SELFSERVICE_TIMEOUT": 0,
        "TAS_SELFSERVICE_TIME": 0,
        "TAS_SELFSERVICE_TIME_UNIT": "",
        "TAS_SELFSERVICE_TRIGGER_UID": "",
        "TAS_SELFSERVICE_EXECUTION": "EVERY_TIME",
        "TAS_NOT_EMAIL_FROM_FORMAT": 0,
        "TAS_OFFLINE": "FALSE",
        "TAS_EMAIL_SERVER_UID": "",
        "TAS_AUTO_ROOT": "FALSE",
        "TAS_RECEIVE_SERVER_UID": "",
        "TAS_RECEIVE_LAST_EMAIL": "FALSE",
        "TAS_RECEIVE_EMAIL_FROM_FORMAT": 0,
        "TAS_RECEIVE_MESSAGE_TYPE": "text",
        "TAS_RECEIVE_MESSAGE_TEMPLATE": "alert_message.html",
        "TAS_RECEIVE_SUBJECT_MESSAGE": null,
        "TAS_RECEIVE_MESSAGE": null,
        "NEXT_TASK": {
            "PRO_UID": "2914468325c708f5e391090035643978",
            "TAS_UID": "8446840565c708f87e39090040622552",
            "TAS_ID": 105,
            "TAS_TITLE": "Diversity training",
            "TAS_DESCRIPTION": "",
            "TAS_DEF_TITLE": "",
            "TAS_DEF_SUBJECT_MESSAGE": "",
            "TAS_DEF_PROC_CODE": "",
            "TAS_DEF_MESSAGE": "",
            "TAS_DEF_DESCRIPTION": "",
            "TAS_TYPE": "NORMAL",
            "TAS_DURATION": 1,
            "TAS_DELAY_TYPE": "",
            "TAS_TEMPORIZER": 0,
            "TAS_TYPE_DAY": "",
            "TAS_TIMEUNIT": "DAYS",
            "TAS_ALERT": "FALSE",
            "TAS_PRIORITY_VARIABLE": "",
            "TAS_ASSIGN_TYPE": "BALANCED",
            "TAS_ASSIGN_VARIABLE": "@@SYS_NEXT_USER_TO_BE_ASSIGNED",
            "TAS_GROUP_VARIABLE": "",
            "TAS_MI_INSTANCE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCE",
            "TAS_MI_COMPLETE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCES_COMPLETE",
            "TAS_ASSIGN_LOCATION": "FALSE",
            "TAS_ASSIGN_LOCATION_ADHOC": "FALSE",
            "TAS_TRANSFER_FLY": "FALSE",
            "TAS_LAST_ASSIGNED": "0",
            "TAS_USER": "0",
            "TAS_CAN_UPLOAD": "FALSE",
            "TAS_VIEW_UPLOAD": "FALSE",
            "TAS_VIEW_ADDITIONAL_DOCUMENTATION": "FALSE",
            "TAS_CAN_CANCEL": "FALSE",
            "TAS_OWNER_APP": "FALSE",
            "STG_UID": "",
            "TAS_CAN_PAUSE": "FALSE",
            "TAS_CAN_SEND_MESSAGE": "TRUE",
            "TAS_CAN_DELETE_DOCS": "FALSE",
            "TAS_SELF_SERVICE": "FALSE",
            "TAS_START": "FALSE",
            "TAS_TO_LAST_USER": "FALSE",
            "TAS_SEND_LAST_EMAIL": "FALSE",
            "TAS_DERIVATION": "NORMAL",
            "TAS_POSX": 479,
            "TAS_POSY": 138,
            "TAS_WIDTH": 110,
            "TAS_HEIGHT": 60,
            "TAS_COLOR": "",
            "TAS_EVN_UID": "",
            "TAS_BOUNDARY": "",
            "TAS_DERIVATION_SCREEN_TPL": "",
            "TAS_SELFSERVICE_TIMEOUT": 0,
            "TAS_SELFSERVICE_TIME": 0,
            "TAS_SELFSERVICE_TIME_UNIT": "",
            "TAS_SELFSERVICE_TRIGGER_UID": "",
            "TAS_SELFSERVICE_EXECUTION": "EVERY_TIME",
            "TAS_NOT_EMAIL_FROM_FORMAT": 0,
            "TAS_OFFLINE": "FALSE",
            "TAS_EMAIL_SERVER_UID": "",
            "TAS_AUTO_ROOT": "FALSE",
            "TAS_RECEIVE_SERVER_UID": "",
            "TAS_RECEIVE_LAST_EMAIL": "FALSE",
            "TAS_RECEIVE_EMAIL_FROM_FORMAT": 0,
            "TAS_RECEIVE_MESSAGE_TYPE": "text",
            "TAS_RECEIVE_MESSAGE_TEMPLATE": "alert_message.html",
            "TAS_RECEIVE_SUBJECT_MESSAGE": null,
            "TAS_RECEIVE_MESSAGE": null,
            "TAS_PARENT": "",
            "USER_ASSIGNED": {
                "USR_UID": "9322161755c3d4fd937db22046389022",
                "USR_USERNAME": "freddy",
                "USR_FIRSTNAME": "Freddy",
                "USR_LASTNAME": "Mercado",
                "USR_FULLNAME": "Mercado, Freddy",
                "USR_EMAIL": "freddy.mercado@processmaker.com",
                "USR_STATUS": "ACTIVE",
                "USR_COUNTRY": "",
                "USR_CITY": "",
                "USR_LOCATION": "",
                "DEP_UID": ""
            }
        },
        "SOURCE_UID": "8446840565c708f87e39090040622552"
    }
}

If the task is the last one in the case, then its HTTP status code will still be 200, but the "TAS_TITLE" under "NEXT_TASK" will be set to "End of process", like the following response:

 
{
    "1": {
        "TAS_UID": "6391766225c3410f38934f1056651488",
        "ROU_NEXT_TASK": "-1",
        "ROU_TYPE": "SEQUENTIAL",
        "ROU_DEFAULT": "0",
        "ROU_CONDITION": "",
        "APP_UID": "3265927215c3428c5808f37086338132",
        "DEL_INDEX": 4,
        "USER_UID": "00000000000000000000000000000001",
        "PRO_UID": "6579030565c340791787669008961750",
        "TAS_ID": 67,
        "TAS_TITLE": "Negotiate contract",
        "TAS_DESCRIPTION": "",
        "TAS_DEF_TITLE": "",
        "TAS_DEF_SUBJECT_MESSAGE": "",
        "TAS_DEF_PROC_CODE": "",
        "TAS_DEF_MESSAGE": "",
        "TAS_DEF_DESCRIPTION": "",
        "TAS_TYPE": "NORMAL",
        "TAS_DURATION": 1,
        "TAS_DELAY_TYPE": "",
        "TAS_TEMPORIZER": 0,
        "TAS_TYPE_DAY": "",
        "TAS_TIMEUNIT": "DAYS",
        "TAS_ALERT": "FALSE",
        "TAS_PRIORITY_VARIABLE": "",
        "TAS_ASSIGN_TYPE": "BALANCED",
        "TAS_ASSIGN_VARIABLE": "@@SYS_NEXT_USER_TO_BE_ASSIGNED",
        "TAS_GROUP_VARIABLE": "",
        "TAS_MI_INSTANCE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCE",
        "TAS_MI_COMPLETE_VARIABLE": "@@SYS_VAR_TOTAL_INSTANCES_COMPLETE",
        "TAS_ASSIGN_LOCATION": "FALSE",
        "TAS_ASSIGN_LOCATION_ADHOC": "FALSE",
        "TAS_TRANSFER_FLY": "FALSE",
        "TAS_LAST_ASSIGNED": "00000000000000000000000000000001",
        "TAS_USER": "0",
        "TAS_CAN_UPLOAD": "FALSE",
        "TAS_VIEW_UPLOAD": "FALSE",
        "TAS_VIEW_ADDITIONAL_DOCUMENTATION": "FALSE",
        "TAS_CAN_CANCEL": "FALSE",
        "TAS_OWNER_APP": "FALSE",
        "STG_UID": "",
        "TAS_CAN_PAUSE": "FALSE",
        "TAS_CAN_SEND_MESSAGE": "TRUE",
        "TAS_CAN_DELETE_DOCS": "FALSE",
        "TAS_SELF_SERVICE": "FALSE",
        "TAS_START": "FALSE",
        "TAS_TO_LAST_USER": "FALSE",
        "TAS_SEND_LAST_EMAIL": "FALSE",
        "TAS_DERIVATION": "NORMAL",
        "TAS_POSX": 626,
        "TAS_POSY": 79,
        "TAS_WIDTH": 110,
        "TAS_HEIGHT": 60,
        "TAS_COLOR": "",
        "TAS_EVN_UID": "",
        "TAS_BOUNDARY": "",
        "TAS_DERIVATION_SCREEN_TPL": "",
        "TAS_SELFSERVICE_TIMEOUT": 0,
        "TAS_SELFSERVICE_TIME": 0,
        "TAS_SELFSERVICE_TIME_UNIT": "",
        "TAS_SELFSERVICE_TRIGGER_UID": "",
        "TAS_SELFSERVICE_EXECUTION": "EVERY_TIME",
        "TAS_NOT_EMAIL_FROM_FORMAT": 0,
        "TAS_OFFLINE": "FALSE",
        "TAS_EMAIL_SERVER_UID": "",
        "TAS_AUTO_ROOT": "FALSE",
        "TAS_RECEIVE_SERVER_UID": "",
        "TAS_RECEIVE_LAST_EMAIL": "FALSE",
        "TAS_RECEIVE_EMAIL_FROM_FORMAT": 0,
        "TAS_RECEIVE_MESSAGE_TYPE": "text",
        "TAS_RECEIVE_MESSAGE_TEMPLATE": "alert_message.html",
        "TAS_RECEIVE_SUBJECT_MESSAGE": null,
        "TAS_RECEIVE_MESSAGE": null,
        "NEXT_TASK": {
            "TAS_UID": -1,
            "TAS_ASSIGN_TYPE": "nobody",
            "TAS_PRIORITY_VARIABLE": "",
            "TAS_DEF_PROC_CODE": "",
            "TAS_PARENT": "",
            "TAS_TRANSFER_FLY": "",
            "TAS_TITLE": "End of process",
            "USR_UID": "",
            "USER_ASSIGNED": {
                "USR_UID": "",
                "USR_USERNAME": ""
            }
        },
        "SOURCE_UID": "-1"
    }
}

If the delegation has already been closed, then the HTTP status code is set to 400 and the following error object is returned:

{
    "error": {
         "code": 400,
        "message": "Bad Request: Delegation 3 assigned to user '00000000000000000000000000000001' was closed on 2019-01-22 02:51:07."
     }
}

PHP example:

$caseId = '2554682895ac25995666e24055342045';
$url = "/api/1.0/workflow/extrarest/case/$caseId/next-tasks";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200)
   print "Task '". $oRet->response->{1}->NEXT_TASK->TAS_TITLE ."' will be assigned to ".
         $oRet->response->{1}->NEXT_TASK->USER_ASSIGNED->USR_FULLNAME .".";
}



Reassign case: PUT extrarest/case/{app_uid}/reassign-case

Available in version 1.8 and later.

Reassign a task in a case to another user. In order to use this endpoint, either the logged-in user must be assigned to the case or must be assigned as a Supervisor to the case's process.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/{app_uid}/reassign-case

URL parameters:

  • app_uid: Unique ID of case to be reassigned.

POST parameters:

  • int del_index: Optional. The delegation index of the task to be reassigned. If not included, then the most recently created delegation in the case will be selected. Only needs to be included if there are multiple open tasks in the case.
  • string usr_uid_target: Optional. Unique ID of the user to whom the task will be reassigned. If not included, the task will be reassigned to the logged-in user.


Response:

The HTTP status code is 200 if successful and an object which holds information about new delegation is returned:

{
   "app_uid":   "9139066105b7cf3e6b909a1094180193",  //case ID
   "del_index": 5,                                   //new delegation index in case 
   "usr_uid":   "10654575559caec5e953104064429578"   //ID of new user assigned to task
}

If there is some problem in the reassignment, then the HTTP status code will be set to 400 and an error object is returned:

{
   "error": {
      "code": 400,
      "message": "Bad Request: Target and Origin user are the same"
   }
}

PHP example:

Reassign a case which has multiple open tasks, so the delegation index is specified:

$caseId = '2554682895ac25995666e24055342045';
$index = 3;
$assignToUserId = '10654575559caec5e953104064429578';
$url = "/api/1.0/workflow/extrarest/case/$caseId/reassign-case";

$aVars = array(
   'del_index' => $index,
   'usr_uid_target' => $assignToUserId
);

$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);

if ($oRet and $oRet->status == 200) {
   echo "Case '$caseId' has new delegation index {$oRet->response->del_index}.";
}

Upload file to case: POST extrarest/case/{app_uid}/upload

Available in version 1.6 and later.

Uploads a file to a case. This endpoint provides more options than the POST /cases/{app_uid}/input-document endpoint, including the ability to upload attached files, place the file in a Dynaform's File or MultipleFile field, and specify the folder where the file will be placed (if an attached file). Note that the logged-in user must either be the assigned user to the task indicated by the delegation index or be a supervisor to the case's process.

POST extrarest/case/{app_uid}/upload

URL parameters:

  • app_uid: Unique ID of the case where the file will be uploaded.

POST parameters:

  • string doc_type: Optional. Type of document, which can be "ATTACHED" or "INPUT". Set to "ATTACHED" by default if not included.
  • string app_doc_uid: Optional. Unique ID of case file (AppDocument) if adding a new version or overwriting an existing case file. If adding a new case file, set to "" (empty string) or don't include this parameter.
  • int doc_version: Optional. Document version, which is set to 1 by default. Don't include if not overwriting an existing version or adding a new version of an existing case file.
  • int del_index: Optional. Delegation index in the case where the file will be uploaded. If not included, then set to the more recently opened delegation index in the case. Remember that the logged-in user must be assigned to the task indicated by this delegation index if not a Supervisor to the case's process.
  • string inp_doc_uid: Optional. Input Document's unique ID or set to "-1" if an attached file which isn't placed in an Input Document. Set to "-1" by default if not included.
  • string app_doc_comment: Optional. Comment about the file.
  • string field_name: Optional. The name of a File field or the variable associated with a MultipleFile (fileupload) field. If a file field in a grid, set to "{grid-variable} {row-number} {field-name}". If a MultipleFile field in a grid, then set to "{grid-variable} {row-number} {field-id}", for example: "clientList 2 contractFile".
  • string field_type: Optional. Type of field which can be "file" (default) or "multipleFile". It is not used if the field_name is blank or not included.
  • string new_file_name: Optional. New filename if wishing to store the file with a different filename. If not included, the original filename will be retained.
  • string folder_uid: Optional. Unique ID of the folder where the file will be added, which is "" by default. If an Input Document file, then the folder of the Input Document will be used instead.

Response:

If the file was uploaded successfully, the HTTP status code is 200 and the response contains the information like the following about the uploaded file:

{
  "filename":    "accounting_2017.xls",
  "app_doc_uid": "1279188535b18a2cbc86377049850997",
  "doc_version": 1,
  "app_uid":     "8888182905b0f471ec39166020975357",
  "del_index":   2,
  "file_path":   "/opt/processmaker/shared/sites/workflow/files/888/818/290/5b0f471ec39166020975357/1279188535b18a2cbc86377049850997_1.xls",
  "url":         "http://example.com/sysworkflow/en/neoclassic/cases/cases_ShowDocument?a=1279188535b18a2cbc86377049850997&v=1"
}

PHP Example:

$caseId = '8888182905b0f471ec39166020975357';
$url = "http://example.com/api/1.0/workflow/extrarest/case/$caseId/upload";
$filePath = '/home/bob/docs/accounting_2017.xls';

$aVars = array(
   'type'       => 'ATTACHED',
   'del_index'  => 2,
   'field_name' => 'accountingFiles',
   'field_type' => 'multipleFile',
   'file'       => curl_file_create($filePath)
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer ' . $oToken->access_token));
curl_setopt($ch, CURLOPT_POSTFIELDS, $aVars);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oResponse = json_decode(curl_exec($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpStatus == 200) {
    print "File ". $oResponse->app_doc_uid ." uploaded.\n";
}
elseif (is_object($oResponse) and isset($oResponse->error)) {
    print "Error code: {$oResponse->error->code}\n" .
          "Message: {$oResponse->error->message}\n";
}
else {
    print "Error code: $httpStatus";
}

Set case status: PUT extrarest/case/status/{app_uid}

Change the case's status from TO_DO to DRAFT or from DRAFT to TO_DO. The logged-in user must either be the assigned user to the specified delegation index or a process supervisor for the case's process.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/status/{app_uid}

URL parameters:

  • app_uid: Unique ID of case to claim.

POST parameters:

  • string status: Case status to set, which can be "TO_DO" or "DRAFT"
  • int del_index: Optional delegation index. If not set, then the current delegation in case.

Response:

HTTP status code is 200 and no response if successful.

PHP example:

Change a case's status from DRAFT to TO_DO:

$caseId = '7647950535a9f46ade01ab3092163527';
$url = "http://pm.example.com/api/1.0/workflow/extrarest/case/status/$caseId";
$aVars = array(
   'status' => 'TO_DO' 
);
$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);

Get case info: GET extrarest/case/{app_uid}

Get case information, including information about the last task delegation in the case. Unlike the official endpoint GET cases/{app_uid}, this endpoint doesn't check whether the logged-in user had rights to access the case.

Note: In version 1.7, this endpoint was changed to include information about the last task delegation in the case and fixed the APP_STATUS to be 'PAUSED' if the case is paused.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/{app_uid}

URL parameters:

  • app_uid: Unique ID of case.

Response:

If successful, the HTTP status code is set 200 and the response is a JSON object with information about the case and last task delegation in the case.

Example:

Request:

http://pm.example.com/api/1.0/workflow/extrarest/case/72415796659f95bf89a59e2011357239

Response:

{
    "APP_UID":             "72415796659f95bf89a59e2011357239",
    "APP_TITLE":           "#79",
    "APP_DESCRIPTION":     "",
    "APP_NUMBER":          79,
    "APP_PARENT":          "",
    "APP_STATUS":          "TO_DO",
    "APP_STATUS_ID":       2,
    "PRO_UID":             "73387376659f92ecf7a9382090189764",
    "APP_PROC_STATUS":     "",
    "APP_PROC_CODE":       "",
    "APP_PARALLEL":        "N",
    "APP_INIT_USER":       "00000000000000000000000000000001",
    "APP_CUR_USER":        "00000000000000000000000000000001",
    "APP_CREATE_DATE":     "2017-11-01 01:30:32",
    "APP_INIT_DATE":       "2017-11-01 01:30:32",
    "APP_FINISH_DATE":     null,
    "APP_UPDATE_DATE":     "2017-11-03 19:42:06",
    "APP_DATA": {
        "SYS_LANG":        "en",
        "SYS_SKIN":        "big",
        "SYS_SYS":         "workflow",
        "APPLICATION":     "72415796659f95bf89a59e2011357239",
        "PROCESS":         "73387376659f92ecf7a9382090189764",
        "TASK":            "32685606259f92ed00fc0d0080958682",
        "INDEX":           "2",
        "USER_LOGGED":     "00000000000000000000000000000001",
        "USR_USERNAME":    "admin",
        "accountNo":       "RS-321",
        "orderAmount":     342.50,
        "APP_NUMBER":      "79",
        "PIN":             "Z7OX",
        "__VAR_CHANGED__": "PROCESS,PROCESS,SYS_SYS,SYS_LANG,SYS_SKIN,htmlTable,htmlTable,htmlTable",
        "typeCurrentTask": "1"
    },
    "APP_PIN":             "63d21dfd49d86fb7650efbcd24ca4010",
    "APP_DURATION":        0,
    "APP_DELAY_DURATION":  0,
    "APP_DRIVE_FOLDER_UID":"",
    "APP_ROUTING_DATA":    "a:0:{}",
    "STATUS":              "To do",
    "TITLE":               "#79",
    "DESCRIPTION":         "",
    "CREATOR":             "Administrator admin",
    "CREATE_DATE":         "2017-11-01 01:30:32",
    "UPDATE_DATE":         "2017-11-03 19:42:06",
    "TAS_UID":             "89054932459f92ed0438d57068674497",
    "DEL_INDEX":           1,
    "DEL_PREVIOUS":        0,
    "DEL_TYPE":            "NORMAL",
    "DEL_PRIORITY":        "3",
    "DEL_THREAD_STATUS":   "CLOSED",
    "DEL_THREAD":          1,
    "DEL_DELEGATE_DATE":   "2017-11-01 01:30:32",
    "DEL_INIT_DATE":       "2017-11-01 01:30:33",
    "DEL_TASK_DUE_DATE":   "2017-11-01 17:00:00",
    "DEL_FINISH_DATE":     "2017-11-01 01:31:17",
    "CURRENT_USER_UID":    "00000000000000000000000000000001",
    "TASK":                "89054932459f92ed0438d57068674497",
    "INDEX":               1,
    "PRO_ID":              29,
    "CURRENT_USER":        "Administrator admin"
}

Get case and task info: GET extrarest/case/{app_uid}/{del_index}

Get case and task information. Unlike the official endpoint GET cases/{app_uid}/{del_index}, this endpoint doesn't check whether the logged-in user had rights to access the case.

Note: In version 1.7, this endpoint was fixed so the APP_STATUS is set to 'PAUSED' when the case is paused.

GET http://{domain-or-ip}/api/1.0/workflow/extrarest/case/{app_uid}/{del_index}

URL parameters:

  • app_uid: Unique ID of case.
  • del_index: Delegation index of a task in the case. If a task wasn't reassigned to another user, then the first task will usually have an index of 1, the second task will be 2, etc.

Response:

If successful, the HTTP status code is set 200 and the response is a JSON object with information about the case and its task.

Example:

Request:

http://pm.example.com/api/1.0/workflow/extrarest/case/72415796659f95bf89a59e2011357239/3

Response:

{
    "APP_UID":             "72415796659f95bf89a59e2011357239",
    "APP_TITLE":           "#79",
    "APP_DESCRIPTION":     "",
    "APP_NUMBER":          79,
    "APP_PARENT":          "",
    "APP_STATUS":          "TO_DO",
    "APP_STATUS_ID":       2,
    "PRO_UID":             "73387376659f92ecf7a9382090189764",
    "APP_PROC_STATUS":     "",
    "APP_PROC_CODE":       "",
    "APP_PARALLEL":        "N",
    "APP_INIT_USER":       "00000000000000000000000000000001",
    "APP_CUR_USER":        "00000000000000000000000000000001",
    "APP_CREATE_DATE":     "2017-11-01 01:30:32",
    "APP_INIT_DATE":       "2017-11-01 01:30:32",
    "APP_FINISH_DATE":     null,
    "APP_UPDATE_DATE":     "2017-11-03 19:42:06",
    "APP_DATA": {
        "SYS_LANG":        "en",
        "SYS_SKIN":        "big",
        "SYS_SYS":         "workflow",
        "APPLICATION":     "72415796659f95bf89a59e2011357239",
        "PROCESS":         "73387376659f92ecf7a9382090189764",
        "TASK":            "32685606259f92ed00fc0d0080958682",
        "INDEX":           "2",
        "USER_LOGGED":     "00000000000000000000000000000001",
        "USR_USERNAME":    "admin",
        "accountNo":       "RS-321",
        "orderAmount":     342.50,
        "APP_NUMBER":      "79",
        "PIN":             "Z7OX",
        "__VAR_CHANGED__": "PROCESS,PROCESS,SYS_SYS,SYS_LANG,SYS_SKIN,htmlTable,htmlTable,htmlTable",
        "typeCurrentTask": "1"
    },
    "APP_PIN":             "63d21dfd49d86fb7650efbcd24ca4010",
    "APP_DURATION":        0,
    "APP_DELAY_DURATION":  0,
    "APP_DRIVE_FOLDER_UID":"",
    "APP_ROUTING_DATA":    "a:0:{}",
    "STATUS":              "To do",
    "TITLE":               "#79",
    "DESCRIPTION":         "",
    "CREATOR":             "Administrator admin",
    "CREATE_DATE":         "2017-11-01 01:30:32",
    "UPDATE_DATE":         "2017-11-03 19:42:06",
    "TAS_UID":             "89054932459f92ed0438d57068674497",
    "DEL_INDEX":           1,
    "DEL_PREVIOUS":        0,
    "DEL_TYPE":            "NORMAL",
    "DEL_PRIORITY":        "3",
    "DEL_THREAD_STATUS":   "CLOSED",
    "DEL_THREAD":          1,
    "DEL_DELEGATE_DATE":   "2017-11-01 01:30:32",
    "DEL_INIT_DATE":       "2017-11-01 01:30:33",
    "DEL_TASK_DUE_DATE":   "2017-11-01 17:00:00",
    "DEL_FINISH_DATE":     "2017-11-01 01:31:17",
    "CURRENT_USER_UID":    "00000000000000000000000000000001",
    "TASK":                "89054932459f92ed0438d57068674497",
    "INDEX":               1,
    "PRO_ID":              29,
    "CURRENT_USER":        "Administrator admin"
}

Get supervisor's list of review cases: GET extrarest/cases/review

Returns the list of cases found under Home > Review for Process Supervisors. The logged-in user must have the PM_SUPERVISOR permission in role to use this endpoint.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/cases/review

Response:

If successful, the HTTP status code is set to 200 and the response is an array of objects holding information about cases, like the following:

[
  {
    "APP_UID":               "2554682895ac25995666e24055342045",
    "DEL_INDEX":             "2",
    "DEL_LAST_INDEX":        "1",
    "APP_NUMBER":            "368",
    "APP_STATUS":            "TO_DO",
    "USR_UID":               "10654575559caec5e953104064429578",
    "PREVIOUS_USR_UID":      "00000000000000000000000000000001",
    "TAS_UID":               "9002452665ac24b3bc92243059239995",
    "PRO_UID":               "9399997805ac24afc9c3a52000021391",
    "DEL_DELEGATE_DATE":     "2018-04-02 12:26:14",
    "DEL_INIT_DATE":         "2018-04-02 12:27:29",
    "DEL_FINISH_DATE":       null,
    "DEL_TASK_DUE_DATE":     "2018-04-03 12:26:14",
    "DEL_RISK_DATE":         "2018-04-03 10:50:14",
    "DEL_THREAD_STATUS":     "OPEN",
    "APP_THREAD_STATUS":     "OPEN",
    "APP_TITLE":             "#368",
    "APP_PRO_TITLE":         "Customer complaint process",
    "APP_TAS_TITLE":         "Review complaint",
    "APP_CURRENT_USER":      "Batto Amos",
    "APP_DEL_PREVIOUS_USER": "admin Administrator",
    "DEL_PRIORITY":          "NORMAL",
    "DEL_DURATION":          "0",
    "DEL_QUEUE_DURATION":    "0",
    "DEL_DELAY_DURATION":    "0",
    "DEL_STARTED":           "0",
    "DEL_FINISHED":          "0",
    "DEL_DELAYED":           "0",
    "APP_CREATE_DATE":       "2018-04-02 12:25:57",
    "APP_FINISH_DATE":       null,
    "APP_UPDATE_DATE":       "2018-04-02 12:28:30",
    "APP_OVERDUE_PERCENTAGE":"0",
    "USR_FIRSTNAME":         "Amos",
    "USR_LASTNAME":          "Batto",
    "USR_USERNAME":          "amos",
    "APPDELCR_APP_TAS_TITLE":"Task 2",
    "USRCR_USR_UID":         "10654575559caec5e953104064429578",
    "USRCR_USR_FIRSTNAME":   "Amos",
    "USRCR_USR_LASTNAME":    "Batto",
    "USRCR_USR_USERNAME":    "amos",
    "PREVIOUS_USR_FIRSTNAME":"Administrator",
    "PREVIOUS_USR_LASTNAME": "admin",
    "PREVIOUS_USR_USERNAME": "admin",
    "APP_STATUS_LABEL":      "To do"
  },
  //the rest of the cases here
]

If the logged-in user does not have the PM_SUPERVISOR permissions in her role to access the Home > Review submenu, then the HTTP status code is set to 400 and the response is the following error object:

{
  "error": {
    "code":    400,
    "message": "Bad Request: Logged-in user lacks the PM_SUPERVISOR permission in role."
  }
}

Get logged-in user info: GET extrarest/login-user

Get information about the logged-in user.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/login-user

Response:

If successful, the HTTP status code is set to 200 and the response an object holding information about the logged-in user.

Example:

Request:

http://pm.example.com/api/1.0/workflow/extrarest/login-user

Response:

{
  "uid":                "10654575559caec5e953104064429578",
  "username":           "amos",
  "firstname":          "Amos",
  "lastname":           "Batto",
  "mail":               "amos@processmaker.com",
  "address":            "45 Elm St.",
  "zipcode":            "53827",
  "country":            "United States",
  "state":              "North Carolina",
  "location":           "Ellenboro",
  "phone":              "765-654-6523",
  "fax":                "",                    //deprecated
  "cellular":           "",                    //deprecated
  "birthday":           "2017-09-26",          //deprecated
  "position":           "Accounting",
  "role":               "PROCESSMAKER_OPERATOR",
  "replacedby":         "24141295159e5658e2e0fd9028990395",
  "replacedbyfullname": "Arturo Lopez",
  "duedate":            "2018-09-26",
  "calendar":           "00000000000000000000000000000001",
  "calendarname":       "Default Calendar",
  "status":             "ACTIVE",
  "department":         "13726536259e566c09db6f6075845729",
  "departmentname":     "Sales",
  "reportsto":          "92729925059e5652bebac55017512864",
  "userexperience":     "NORMAL",
  "photo":              "/opt/pm3.2.1/shared/sites/workflow/usersPhotographies/10654575559caec5e953104064429578.gif"
}

Get system language: GET extrarest/language

Get the system language of the logged-in user's session. This language is used by ProcessMaker when translating elements such as the case status.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/language

Response:

If successful, the HTTP status code is 200 and the response is the system language in "xx" or "xx-CC" format, such as "es" (Spanish) or "pt-BR" (Brazilian Portuguese).

Example:

Request:

GET http://pm.example.com/api/1.0/workflow/extrarest/language

Response:

200 (OK)
"pt-BR"

Set system language: PUT extrarest/language/{lang}

Set the system language of the login session. This language will be used by subsequent REST calls. In an ordinary login in the graphical interface, the user can select the system language, but the oAuth2 login doesn't provide this option when using REST, so this endpoint can be used instead.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/language/{lang}

URL parameters:

  • string lang: The language in xx or xx-CC format, such as es (Spanish) or pt-BR (Brazilian Portuguese).

POST parameters:

None.

Response:

HTTP status code is 200 and no response if successful.

Example:

Request:

PUT http://pm.example.com/api/1.0/workflow/extrarest/language/fr

Response:

200



Get login session ID: GET extrarest/session-id

Get a login session ID that can be attached to URLs to access pages and files inside ProcessMaker

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/session-id

Response:

If successful, the HTTP status code is set to 200 and the response is a session ID, which is a string consisting of 32 hexidecimal characters.

Note: The session ID can be attached to the end of URLs in ProcessMaker to access those pages with a login session:

http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/{folder}/{method}.php?sid={session_id}

Open a case in the first step in a specified delegation:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/cases_Open?APP_UID={app_uid}&DEL_INDEX={delegation}&action=todo&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/cases_Open?APP_UID=9777918985a8dddbf884236088281261&DEL_INDEX=3& action=todo&sid=1234567890abcde1234567890abcde

Open a case with menus like in the ProcessMaker interface:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/opencase/{app_uid}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/opencase/9777918985a8dddbf884236088281261

Open a Dynaform:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/cases_Open?APP_UID={app_uid}&DEL_INDEX={delegation}&action=todo&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/cases_Open?APP_UID=9777918985a8dddbf884236088281261&DEL_INDEX=3& action=todo&sid=1234567890abcde1234567890abcde

Open an Output Document:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/cases_Step?TYPE=OUTPUT_DOCUMENT&UID={out_doc_uid}&POSITION={position}&ACTION=GENERATE&sid={session_id}
  • Ex: http://localhost:330/sysworkflow/en/neoclassic/cases/cases_Step?TYPE=OUTPUT_DOCUMENT&UID=6966864235c4689a79f3b61013623162&POSITION=4&ACTION=GENERATE&sid=1234567890abcde1234567890abcde

Open an Input Document:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/cases_Step?TYPE=INPUT_DOCUMENT&UID={inp_doc_uid}&POSITION={position}&ACTION=ATTACH&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/cases_Step?TYPE=INPUT_DOCUMENT&UID=7415122705c46899b4b08c6022893958&POSITION=3&ACTION=ATTACH&sid=1234567890abcde1234567890abcde

End of task:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/cases_Step?TYPE=ASSIGN_TASK&UID=-1&POSITION=10000&ACTION=ASSIGN&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/cases_Step?TYPE=ASSIGN_TASK&UID=-1&POSITION=10000&ACTION=ASSIGN&sid=1234567890abcde1234567890abcde
Note: The URL cases/cases_Step/... should only be used after opening a task in a case with cases/cases_Open?APP_UID={app_uid}&DEL_INDEX={index} or cases/opencase/{app_uid}. It is generally only used to open the second or subsequent steps in tasks, since opening the case will also open its first task.

Show a case's process map:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/designer?prj_uid={process_uid}&prj_readonly=true& app_uid={app_uid}&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/designer?prj_uid=6135378175a8dcdca9a2641037096319&prj_readonly=true& app_uid=9777918985a8dddbf884236088281261&sid=1234567890abcde1234567890abcde

Download an Input Document or attached file:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/cases_ShowDocument?a={app_doc_uid}&v={version}&sid={session_id}
    (&v={version} is optional)
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/cases_ShowDocument?a=4699401854d8262f569e9a1070221206&sid=1234567890abcde1234567890abcde
Note: The above example only works if the source code has been changed to use a session ID. Otherwise, set disable_download_documents_session_validation=1 in the env.ini'configuration file to download files without a session ID.

Example:

Request:

GET http://pm.example.com/api/1.0/workflow/extrarest/session-id

Response:

200 (OK)
"2554682895ac25995666e24055342045"

Execute database query: POST extrarest/sql

Execute an SQL SELECT query in the current workspace's workflow database, which by default is named "wf_workflow".

POST http://{domain-or-ip}/api/1.0/{workspace}/extrarest/sql

POST parameters:

  • string sql: SQL SELECT statement to execute.

Note 1: For security reasons, the code for this endpoint is commented out, but it can be enabled if removing the /* ... */ around the code. If needing to executing SQL queries, it is recommended to adapt the code for your specific purpose and include the specific query in the code of the endpoint and only pass the parameters that need to be changed to the endpoint. If this endpoint is allowed to execute any SQL query, a hacker could use it to steal all the information from the ProcessMaker database.

Note 2: If thinking of modifying this endpoint to allow UPDATE, INSERT and DELETE statements, then make sure to change the ProcessMaker configuration files.

Response:

If successful, the HTTP status code is set to 200 and the response contains an array of objects which hold each record retrieved from the database, such as in the following example:

[
  {
    "USER":        "Wilson Jane",
    "NUM_OVERDUE": "8"
  },
  {
    "USER":        "Batto Amos",
    "NUM_OVERDUE": "6"
  },
  {
    "USER":        "Gomez Freddy",
    "NUM_OVERDUE": "1"
  }
]

PHP example:

The database is queried to find the number of open cases assigned to each user since the beginning of the year 2018, which are overdue:

$url = "/api/1.0/workflow/extrarest/sql";
$sql = "SELECT APP_CURRENT_USER AS USER, COUNT(*) AS NUMBER_OVERDUE 
   FROM APP_CACHE_VIEW WHERE DATE(DEL_INIT_DATE) >= '2018-01-01' AND 
   DEL_FINISH_DATE IS NULL AND DEL_TASK_DUE_DATE < NOW() 
   GROUP BY USR_UID ORDER BY APP_CURRENT_USER";
$oRet = pmRestRequest("POST", $url, array("sql"=>$sql), $oToken->access_token);

if ($oRet->status == 200) {
   foreach ($oRet->response as $aRow) {
      print "User ".$aRow->USER." has ".$aRow->NUMBER_OVERDUE.
         " cases since the start of the year 2018.\n";
   }
}

This script will produce the following output:

User Wilson Jane has 8 cases since the start of the year 2018.
User Batto Amos has 6 cases since the start of the year 2018.
User Gomez Freddy has 1 cases since the start of the year 2018.

This example is only provided to show what is possible with a REST endpoint. If needing to use this endpoint in production, remember to modify the source code of this endpoint to only execute the specific SQL query that you need, and not use it to execute any SQL query as shown in this example. Otherwise, you are providing a way for hackers to attack your installation of ProcessMaker.

For example, instead of using the above endpoint, it is recommended to edit the source code of workflow/engine/plugins/extraRest/src/Services/Api/ExtraRest/extra.php and create the specific endpoint that is needed with its SQL query like this:

    /**
     * Get the number of open cases assigned to each user which are overdue in the workspace.
     * The logged-in user needs the PM_ALLCASES permission in his/her role.
     * 
     * @url GET /cases/number-overdue-by-user
     * @access protected
     *
     * @param string $date_from Optional. Task assigned after date in 'YYYY-MM-DD' format  {@from query}
     * @param string $date_to   Optional. Task assigned before date in 'YYYY-MM-DD' format {@from query}
     *   
     * @return array
     * 
     * @author Amos Batto <amos@processmaker.com>
     * @copyright Public Domain
     */
    public function getNumberCasesOverdueByUser($date_from=null, $date_to=null) {
        try {
            if ($this->userCanAccess('PM_ALLCASES') == 0) {
                throw new \Exception("Logged-in user lacks the PM_ALLCASES permission in role.");
            }
            
            $sqlLimitDate = '';
            
            if (!empty($date_from)) {
               if (!preg_match('/^\d{4}-[0-2]\d-[0-3]\d$/', $date_from)) {
                  throw new \Exception("Bad date in date_from. Use format: date_from=YYYY-MM-DD");
               }
               
               $sqlLimitDate = "DATE(DEL_INIT_DATE) >= '$date_from' AND ";
            }
            
            if (!empty($date_to)) {
               if (!preg_match('/^\d{4}-[0-2]\d-[0-3]\d$/', $date_to)) {
                  throw new \Exception("Bad date in date_to. Use format: date_to=YYYY-MM-DD");
               }
               
               $sqlLimitDate .= "DATE(DEL_INIT_DATE) <= '$date_to' AND ";
            }
               
            $g = new \G();
            $g->loadClass("pmFunctions");
            
            $sql = "SELECT USR_UID AS USER_ID, 
                APP_CURRENT_USER AS USER, 
                COUNT(*) AS NUMBER_OVERDUE 
                FROM APP_CACHE_VIEW 
                WHERE $sqlLimitDate 
                DEL_FINISH_DATE IS NULL AND DEL_TASK_DUE_DATE < NOW() 
                GROUP BY USR_UID ORDER BY APP_CURRENT_USER";
        
            $aResult = executeQuery($sql);
            
            $aRows = array();
            foreach ($aResult as $aRow) {
                $aRows[] = $aRow;
            }
            return $aRows;
        } 
        catch (\Exception $e) {
            throw new RestException(Api::STAT_APP_EXCEPTION, $e->getMessage());
        }  
   }

Notice how this endpoint allows optional dates to be specified to limit the scope of the SQL query, but it uses preg_match() to check that the dates have a specific format to prevent SQL injection attacks. It is a good idea to check that the input to an endpoint matches a specific pattern with preg_match() or to pass the input through mysqli_real_escape_string() sanitize it.

After editing the plugin's source code to add a new endpoint, login to ProcessMaker as a user such as "admin" with the PM_SETUP_ADVANCE permission in her role. Go to Admin > Settings > Plugins > Plugins Manager and disable the extraRest plugin. Then, reenable it so it will recreate the list of available endpoints stored in the shared/sites/{workspace}/routes.php file.

Then, the custom endpoint can be executed, as shown in this example in PHP:

$url = "/api/1.0/workflow/extrarest/cases/number-overdue-by-user?date_from=2018-01-01";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   foreach ($oRet->response as $aRow) {
      print "User ".$aRow->USER." has ".$aRow->NUMBER_OVERDUE.
         " cases since the start of the year 2018.\n";
   }
}

Get user's default menu: GET extrarest/user/{usr_uid}/config

Get a user's default menu, which is stored in a serialized array in the CONFIGURATION.CFG_VALUE field in the database. This endpoint can only be called by users who have the PM_USERS permission in their role.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/user/{usr_uid}/config

URL parameters:

  • string usr_uid: Unique ID of user.

Response:

If successful, the HTTP status code is set to 200 and the response contains an object holding the user's configuration, such as:

{
   "DEFAULT_LANG":       "",          
   "DEFAULT_MENU":       "PM_CASES",
   "DEFAULT_CASES_MENU": "CASES_SENT"
}

Note that the DEFAULT_LANG is deprecated and no longer used by ProcessMaker.

PHP Example:

$url = "/api/1.0/workflow/extrarest/user/10654575559caec5e953104064429578/config";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);
if ($oRet->status == 200) {
   $userMenu = $oRet->response['DEFAULT_MENU'];
}

Set user's default menu: PUT extrarest/user/{usr_uid}/config

Set a user's default menu, which is stored in a serialized array in the CONFIGURATION.CFG_VALUE field in the database. This endpoint can only be called by users who have the PM_USERS permission in their role.

POST http://{domain-or-ip}/api/1.0/{workspace}/extrarest/user/{usr_uid}/config

URL parameters:

  • string usr_uid: Unique ID of user.

POST parameters:

  • string default_lang: Optional. Default interface language in "xx" or "xx-CC" format,

such as "es" (Spanish) or "pt-BR" (Brazilian Portuguese). Note that this parameter is deprecated and no longer used by ProcessMaker.

  • string default_menu: Optional. Default main menu to set for the user:
    • "": Default for role,
    • "PM_CASES": Home,
    • "PM_FACTORY": Designer,
    • "PM_SETUP": Admin,
    • "PM_DASHBOARD": Dashboard,
    • or any custom menu defined by a plugin.
  • string default_cases_menu: Optional. The default submenu selected in the cases sidebar under Home. Only used if the default_menu is set to "PM_CASES". Available options:
    • "": The default which is the Inbox,
    • "CASES_START_CASE": New case,
    • "CASES_INBOX": Inbox,
    • "CASES_DRAFT": Draft,
    • "CASES_PAUSED": Paused,
    • "CASES_SENT": Participated,
    • "CASES_SELFSERVICE": Unassigned,
    • "CASES_SEARCH": Advanced search (need PM_ALLCASES in role),
    • "CASES_TO_REVISE": Review (need PM_SUPERVISOR in role),
    • "CASES_TO_REASSIGN": Reassign (need PM_SUPERVISOR and PM_REASSIGNCASE in role),
    • "CASES_FOLDERS": Documents (need PM_FOLDERS_VIEW in role),
    • or any custom submenu defined by a plugin.

Response:

If successful, the HTTP status code is set to 200 and the response is an object holding the updated user configuration.

PHP example:

$userId = '92729925059e5652bebac55017512865';
$defaultMenu = 'PM_CASES';
$defaultCasesMenu = 'CASES_SENT';
$url = "/api/1.0/workflow/extrarest/user/$userId/config";
    
$aVars = array(
  'default_lang'       => 'el',
  'default_menu'       => $defaultMenu,
  'default_cases_menu' => $defaultCasesMenu
);
$oRet = pmRestRequest('PUT', $url, $aVars, $oToken->access_token);

Get user's case list: GET extrarest/cases/user/{usr_uid}

Return the list of cases for a specified user. Extra query string parameters can be added to get a customized list of cases. If retrieving the case list for a user other than the logged-in user, then the logged-in user must have the PM_ALLCASES permission in her role.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/user/{usr_uid}?{param=option}

URL parameters:

  • string usr_uid: Unique ID of user for whom to retrieve the case list. Set to 00000000000000000000000000000000 to retrieve a case list of the logged-in user.

Optional query string parameters:

  • start={integer}: The number where to begin listing cases.
  • limit={integer}: The maximum number of cases to list.
  • action={option}: Specify the type of cases, which can be:
    todo, draft, sent (participated), unassigned (self service), paused, completed, cancelled, search (Home > Advanced Search for users with PM_ALLCASES in role), simple_search (normal search), to_revise (Home > Review for process supervisors), to_reassign (Home > Reassign for process supervisors with PM_REASSIGNCASE permission), all, gral (general), default (like todo)
  • filter={option}: An additional filter for the type of case, which can be:
    read, unread, started, completed
  • search={string}: Case-insensitive string to search for in the case number, case title, process title, task title, assigned user's name and any additional fields if using the Custom Case List Builder plugin.
  • pro_uid={uid}: Retrieve cases from a particular process, specified by its unique ID.
  • app_status={status}: If action=search, then this parameter is used to specify the case's status which can be:
    TO_DO, DRAFT, PAUSED, CANCELLED, COMPLETED, ALL
  • date_from={YYYY-MM-DD}: Retrieve cases whose task started or ended after or on the specified date.
  • date_to={YYYY-MM-DD}: Retrieve cases whose task started or ended before or on the specified date.
  • dir={order}: Set to ASC to sort cases in ascending order or DESC in descending order.
  • sort={field}: Database field in the APP_CACHE_VIEW table by which to sort cases.
  • cat_uid={uid}: Retrieve cases whose process is in a category, specified by its unique ID (found in the PROCESS_CATEGORY.CATEGORY_UID field in the database).
  • configuration={integer}: Set to 1 to use the configuration or 0 to not use it when searching for cases.
  • paged={integer}: Set to 1 to return a page of cases or 0 to not return the cases in a page. It is recommended to use pages when dealing with a large numbers of cases.
  • newer_than={YYYY-MM-DD}: Retrieve cases whose task started or ended after the specified date. This parameter is like date_from, but it is > rather than >= the date.
  • older_than={YYYY-MM-DD}: Retrieve cases whose task started or ended before the specified date. This parameter is like date_to, but it is < rather than <= the date.

Response:

If successful, the HTTP status code is set to 200 and the response is an object with the totalCount member which lists the total number of cases which match the search criteria and the data member which is an array of objects holding information about each case.

Example:

Get a list of participated cases for the logged-in user since the start of the year 2018.

Request:

GET http://pm.example.com/api/1.0/workflow/extrarest/cases/user/00000000000000000000000000000000?action=sent&date_from=2018-01-01

Response:

200 (OK)
{
  "totalCount": 2,
  "data": [
    {
      "APP_UID":               "5295973255ac51bf10472f6060420954",
      "DEL_INDEX":             "1",
      "DEL_LAST_INDEX":        "1",
      "APP_NUMBER":            "374",
      "APP_STATUS":            "DRAFT",
      "USR_UID":               "00000000000000000000000000000001",
      "PREVIOUS_USR_UID":      "",
      "TAS_UID":               "1029336105ac5121d1624d5021075541",
      "PRO_UID":               "5348454895ac4096b9c3544003146878",
      "DEL_DELEGATE_DATE":     "2018-04-04 14:39:45",
      "DEL_INIT_DATE":         "2018-04-04 14:39:45",
      "DEL_FINISH_DATE":       null,
      "DEL_TASK_DUE_DATE":     "2018-04-05 14:39:45",
      "DEL_RISK_DATE":         "2018-04-05 13:03:45",
      "DEL_THREAD_STATUS":     "OPEN",
      "APP_THREAD_STATUS":     "OPEN",
      "APP_TITLE":             "#374",
      "APP_PRO_TITLE":         "New Product Testing",
      "APP_TAS_TITLE":         "Document New Product",
      "APP_CURRENT_USER":      "admin Administrator",
      "APP_DEL_PREVIOUS_USER": "",
      "DEL_PRIORITY":          "NORMAL",
      "DEL_DURATION":          "0",
      "DEL_QUEUE_DURATION":    "0",
      "DEL_DELAY_DURATION":    "0",
      "DEL_STARTED":           "0",
      "DEL_FINISHED":          "0",
      "DEL_DELAYED":           "0",
      "APP_CREATE_DATE":       "2018-04-04 14:39:45",
      "APP_FINISH_DATE":       null,
      "APP_UPDATE_DATE":       "2018-04-04 16:25:59",
      "APP_OVERDUE_PERCENTAGE":"0",
      "USR_FIRSTNAME":         "Administrator",
      "USR_LASTNAME":          "admin",
      "USR_USERNAME":          "admin",
      "APPDELCR_APP_TAS_TITLE":"Task 1",
      "USRCR_USR_UID":         "00000000000000000000000000000001",
      "USRCR_USR_FIRSTNAME":   "Administrator",
      "USRCR_USR_LASTNAME":    "admin",
      "USRCR_USR_USERNAME":    "admin",
      "APP_STATUS_LABEL":      "Draft"
    },
    {
      "APP_UID":               "3633901045ac51b2bac1c58087855401",
      "DEL_INDEX":             "1",
      "DEL_LAST_INDEX":        "1",
      "APP_NUMBER":            "373",
      "APP_STATUS":            "DRAFT",
      "USR_UID":               "00000000000000000000000000000001",
      "PREVIOUS_USR_UID":      "",
      "TAS_UID":               "1029336105ac5121d1624d5021075541",
      "PRO_UID":               "5348454895ac4096b9c3544003146878",
      "DEL_DELEGATE_DATE":     "2018-04-04 14:36:28",
      "DEL_INIT_DATE":         "2018-04-04 14:36:28",
      "DEL_FINISH_DATE":       null,
      "DEL_TASK_DUE_DATE":     "2018-04-05 14:36:28",
      "DEL_RISK_DATE":         "2018-04-05 13:00:28",
      "DEL_THREAD_STATUS":     "OPEN",
      "APP_THREAD_STATUS":     "OPEN",
      "APP_TITLE":             "#373",
      "APP_PRO_TITLE":         "Customer Complaint Process",
      "APP_TAS_TITLE":         "Review Complaint",
      "APP_CURRENT_USER":      "admin Administrator",
      "APP_DEL_PREVIOUS_USER": "",
      "DEL_PRIORITY":          "NORMAL",
      "DEL_DURATION":          "0",
      "DEL_QUEUE_DURATION":    "0",
      "DEL_DELAY_DURATION":    "0",
      "DEL_STARTED":           "0",
      "DEL_FINISHED":          "0",
      "DEL_DELAYED":           "0",
      "APP_CREATE_DATE":       "2018-04-04 14:36:27",
      "APP_FINISH_DATE":       null,
      "APP_UPDATE_DATE":       "2018-04-04 14:36:27",
      "APP_OVERDUE_PERCENTAGE":"0",
      "USR_FIRSTNAME":         "Administrator",
      "USR_LASTNAME":          "admin",
      "USR_USERNAME":          "admin",
      "APPDELCR_APP_TAS_TITLE":"Task 1",
      "USRCR_USR_UID":         "00000000000000000000000000000001",
      "USRCR_USR_FIRSTNAME":   "Administrator",
      "USRCR_USR_LASTNAME":    "admin",
      "USRCR_USR_USERNAME":    "admin",
      "APP_STATUS_LABEL":      "Draft"
    }
  ]
}

Append rows to a PM Table: PUT extrarest/pmtable/{pmt_uid}/append

Available in version 1.2 and later.

Append records to the end of a PM Table. The logged-in user must have the PM_SETUP and PM_SETUP_PM_TABLES permissions in his/her in role to use this endpoint.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/pmtable/{pmt_uid}/append

URL parameters:

  • string pmt_uid: The unique ID of the PM Table (which can be found with GET /pmtable or by querying the ADDITIONAL_TABLES.ADD_TAB_UID field in the database).

POST parameters:

  • array rows: An array of objects, where each object represents a row to add to the table and its properties are the field names:
[
  {
    "FIELD1": "VALUE1",
    "FIELD2": "VALUE2",
    ...
  },
  ...
]

Note: This endpoint does not check whether the fields in the PM Table are not allowed to be NULL (left blank) nor does it check whether they are primary keys, so their values should be unique.

Response:

If the new rows were added, then the HTTP status code will set to 200 and the response will be the number of inserted rows.

If the name of a field is misspelled or not included, the record will be inserted and the field will set to NULL (left blank). Fields which are auto-increment do not need to be included.

If none of the names of the fields passed to this endpoint match any of the names of the PM Table's fields, then the HTTP status code will be 400 and the following response will be returned:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The value of key column is required"
   }
}

Example:

Request:

PUT http://example.com/api/1.0/workflow/extrarest/pmtable/2714474795ad61591723eb7014657886/append
Content-Type: application/json
{
  "rows": [
    {"CLIENT_NAME": "Jane Doe", "CONTRACT_DATE": "2018-06-20", "AMOUNT": 4500.00 },
    {"CLIENT_NAME": "Bill Row", "CONTRACT_DATE": "2017-12-31", "AMOUNT": 999.99  },
    {"CLIENT_NAME": "Sam Slow", "CONTRACT_DATE": "2018-01-01", "AMOUNT": 27573.50}
  ]
}

Response:

200 (OK)
3

PHP Example:

$tableId = '2714474795ad61591723eb7014657886'; //ID for PMT_CONTRACTS
$aVars = array(
   'rows' => array(
      array('CLIENT_NAME'=>'Jane May', 'CONTRACT_DATE'=>'2018-06-20', 'AMOUNT'=>4500.00),
      array('CLIENT_NAME'=>'Bill Row', 'CONTRACT_DATE'=>'2017-12-31', 'AMOUNT'=>2699.99),
      array('CLIENT_NAME'=>'Sam Slow', 'CONTRACT_DATE'=>'2018-01-01', 'AMOUNT'=>78.99  )
   )
);

$url = "/api/1.0/workflow/extrarest/pmtable/$tableId/append";
$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   echo $oRet->response . " records were inserted.";
}

Overwrite a PM Table: PUT extrarest/pmtable/{pmt_uid}/overwrite

Available in version 1.2 and later.

Remove all the existing records in a PM Table and then refill the table with new records. The logged-in user must have the PM_SETUP and PM_SETUP_PM_TABLES permissions in his/her in role to use this endpoint.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/pmtable/{pmt_uid}/overwrite

URL parameters:

  • string pmt_uid: The unique ID of the PM Table (which can be found with GET /pmtable or by querying the ADDITIONAL_TABLES.ADD_TAB_UID field in the database).

POST parameters:

  • array rows: An array of objects, where each object represents a row to add to the table and its properties are the field names:
[
  {
    "FIELD1": "VALUE1",
    "FIELD2": "VALUE2",
    ...
  },
  ...
]

Note: This endpoint does not check whether the fields in the PM Table are not allowed to be NULL (left blank) nor does it check whether they are primary keys, so their values should be unique.

Response:

If the new rows were added, then the HTTP status code will set to 200 and the response will be the number of inserted rows.

If the name of a field is misspelled or not included, the record will be inserted and the field will set to NULL (left blank). Fields which are auto-increment do not need to be included.

If none of the names of the fields passed to this endpoint match any of the names of the PM Table's fields, then the HTTP status code will be 400 and the following response will be returned:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The value of key column is required"
   }
}

Example:

Request:

PUT http://example.com/api/1.0/workflow/extrarest/pmtable/2714474795ad61591723eb7014657886/overwrite
Content-Type: application/json
{
  "rows": [
    {"CLIENT_NAME": "Jane Doe", "CONTRACT_DATE": "2018-06-20", "AMOUNT": 4500.00 },
    {"CLIENT_NAME": "Bill Row", "CONTRACT_DATE": "2017-12-31", "AMOUNT": 999.99  },
    {"CLIENT_NAME": "Sam Slow", "CONTRACT_DATE": "2018-01-01", "AMOUNT": 27573.50}
  ]
}

Response:

200 (OK)
3

PHP Example:

$tableId = '2714474795ad61591723eb7014657886'; //ID for PMT_CONTRACTS
$aVars = array(
   'rows' => array(
      array('CLIENT_NAME'=>'Jane May', 'CONTRACT_DATE'=>'2018-06-20', 'AMOUNT'=>4500.00),
      array('CLIENT_NAME'=>'Bill Row', 'CONTRACT_DATE'=>'2017-12-31', 'AMOUNT'=>2699.99),
      array('CLIENT_NAME'=>'Sam Slow', 'CONTRACT_DATE'=>'2018-01-01', 'AMOUNT'=>78.99)
   )
);

$url = "/api/1.0/workflow/extrarest/pmtable/$tableId/overwrite";
$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   echo $oRet->response . " records were inserted.";
}

Get document folders: GET extrarest/documents/{fdr_uid}/folders

Available in version 1.3 and later.

Retrieve a list of subfolders found in a specified parent folder. These are the folders displayed by going to Home > Documents in the ProcessMaker interface. The logged-in user must have the PM_FOLDERS_VIEW permission in his/her role.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/documents/{fdr_uid}/folders
GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/documents/{fdr_uid}/folders?
limit={int}&start={int}&direction={dir}&sort={field}&search={str}

URL parameters:

  • string fdr_uid: The unique ID of the folder or root if the base folder is "/".

Optional query string parameters:

  • limit={int}: The maximum number of folders to return. If set to 0, which is the default, then an unlimited number of folders will be returned.
  • start={int}: The number where to start listing folders. If set to 0, which is the default, then will start from the first folder. This parameter is often used in conjunction with limit={int} when only displaying a fixed number of folders at a time.
  • direction={dir}: The sort direction which can be ASC (ascending which is the default) or DESC (descending).
  • sort={field}: The field used to sort the folders, which can be appDocCreateDate (the date the folder was first created), name (the folder name) or "" (no sort order).
  • search={str}: A case insensitive string to search for in the folder names. Make sure to use a function such as PHP's urlencode() or JavaScript's encodeURIComponent() so " " (space) becomes %20 and "é" becomes %C3%A9.

Response:

An object holding the following two properties:

  • folders: An array of folder objects. Each folder object has the following properties:
    • FOLDER_UID: The unique ID of the folder.
    • FOLDER_PARENT_UID: The unique ID of the parent folder or "\/" if the parent is the root folder.
    • FOLDER_NAME: The folder's name.
    • FOLDER_CREATE_DATE: The datetime when the folder was created in "YYYY-MM-DD HH:MM:SS" format.
    • FOLDER_UPDATE_DATE: The datetime when the folder was last updated in "YYYY-MM-DD HH:MM:SS" format.
  • totalFoldersCount: The total number of subfolders.

Example:

Request:

GET http://example.com/api/1.0/workflow/extrarest/documents/root/folders

Response:

{
   "folders": [
      {
         "FOLDER_UID":         "6268552735ade43f898a294019015502",
         "FOLDER_PARENT_UID":  "\/",
         "FOLDER_NAME":        "invoices",
         "FOLDER_CREATE_DATE": "2018-04-23 16:37:12",
         "FOLDER_UPDATE_DATE": "2018-04-23 16:37:12"
      },
      {
         "FOLDER_UID":         "5250317125ade44071e56e2014209371",
         "FOLDER_PARENT_UID":  "\/",
         "FOLDER_NAME":        "reports",
         "FOLDER_CREATE_DATE": "2018-04-23 16:37:27",
         "FOLDER_UPDATE_DATE": "2018-04-23 16:37:27"
      }
   ],
   "totalFoldersCount":        2
}

Get documents in folder: GET extrarest/documents/{fdr_uid}/contents

Available in version 1.3 and later.

Retrieve the documents in a specified folder. The logged-in user must have the PM_FOLDERS_VIEW permission in his/her role.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/documents/{fdr_uid}/contents
GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/documents/{fdr_uid}/contents?keyword={str}&search_type={type}
&limit={int}&start={int}&user={uid}&only_active={boolean}&direction={dir}&sort={field}&search={str}

URL parameters:

  • string fdr_uid: The unique ID of the folder or root if the base folder "/".

Optional query string parameters:

  • keyword={str} Only return files which have the specified keyword in the filename or in the document's tag if search_type=TAG.
  • search_type={type}: The type of search, which can be TAG or ALL.
  • limit={int}: The maximum number of folders to return. If set to 0, which is the default, then an unlimited number of folders will be returned.
  • start={int}: The number where to start listing folders. If set to 0, which is the default, then will start from the first folder. This parameter is often used in conjunction with limit={int} when only displaying a fixed number of folders at a time.
  • user={uid}: Only return files that can be accessed by the specified user, indicated by his/her unique ID. This parameter can only be specified if the logged-in user has the PM_ALLCASES permission in his/her role.
  • only_active={boolean}: Set to true if only active files (not deleted and not overwritten with new versions) will be returned. Default is false so all files will be returned.
  • direction={dir}: The sort direction which can be ASC (ascending which is the default) or DESC (descending).
  • sort={field}: The field used to sort the folders, which can be appDocCreateDate (the date the folder was first created), name (the folder name) or "" (no sort order).
  • search={str}: A case insensitive string to search for in the folder names. Make sure to use a function such as PHP's url_encode() or JavaScript's encodeURIComponent() so " " (space) becomes %20 and "é" becomes %C3%A9.

Response:

An object holding the following two properties:

  • documents: An array of document objects.
  • totalDocumentsCount: The total number of documents in the directory.

Example:

Request:

GET http://example.com/api/1.0/workflow/extrarest/documents/root/contents

Response:

{
   "documents": [
      {
         "APP_DOC_UID":              "4674916455a9611cfa0e8e6010566295",
         "APP_DOC_FILENAME":         "invoice_Acme_Inc",
         "APP_DOC_COMMENT":          null,
         "DOC_VERSION":              2,
         "APP_UID":                  "4731930415a9611cb69fca4029962239",
         "DEL_INDEX":                1,
         "DOC_UID":                  "6146400035a8f9fd86551f3042633729",
         "USR_UID":                  "00000000000000000000000000000001",
         "APP_DOC_TYPE":             "OUTPUT",
         "APP_DOC_CREATE_DATE":      "2018-02-27 21:21:15",
         "APP_DOC_INDEX":            2,
         "FOLDER_UID":               "",
         "APP_DOC_PLUGIN":           "",
         "APP_DOC_TAGS":             "",
         "APP_DOC_STATUS":           "ACTIVE",
         "APP_DOC_STATUS_DATE":      null,
         "APP_DOC_FIELDNAME":        null,
         "APP_DOC_DRIVE_DOWNLOAD":   null,
         "SYNC_WITH_DRIVE":          "UNSYNCHRONIZED",
         "SYNC_PERMISSIONS":         null,
         "APP_TITLE":                "#279",
         "APP_DESCRIPTION":          "",
         "APP_NUMBER":               279,
         "APP_PARENT":               "",
         "APP_STATUS":               "DRAFT",
         "PRO_UID":                  "4942606665a8f9f9f2860f0087218330",
         "APP_PROC_CODE":            "",
         "STATUS":                   "Draft",
         "CREATOR":                  "Administrator admin",
         "CREATE_DATE":              "2018-02-27 21:19:55",
         "UPDATE_DATE":              "2018-02-27 21:21:19",
         "PRO_TITLE":                "Purchase Request",
         "OUT_DOC_UID":              "6146400035a8f9fd86551f3042633729",
         "OUT_DOC_TITLE":            "Invoice for client",
         "OUT_DOC_DESCRIPTION":      "",
         "OUT_DOC_FILENAME":         "invoice_@#client",
         "OUT_DOC_REPORT_GENERATOR": "HTML2PDF",
         "OUT_DOC_LANDSCAPE":        0,
         "OUT_DOC_MEDIA":            "Letter",
         "OUT_DOC_GENERATE":         "BOTH",
         "OUT_DOC_TYPE":             "HTML",
         "OUT_DOC_CURRENT_REVISION": null,
         "OUT_DOC_FIELD_MAPPING":    null,
         "OUT_DOC_VERSIONING":       1,
         "OUT_DOC_DESTINATION_PATH": "",
         "OUT_DOC_TAGS":             "",
         "OUT_DOC_PDF_SECURITY_ENABLED": 0,
         "OUT_DOC_PDF_SECURITY_OPEN_PASSWORD": "",
         "OUT_DOC_PDF_SECURITY_OWNER_PASSWORD": "",
         "OUT_DOC_PDF_SECURITY_PERMISSIONS": "",
         "OUT_DOC_OPEN_TYPE":        1,
         "USR_USERNAME":             "johndoe",
         "USR_FIRSTNAME":            "John",
         "USR_LASTNAME":             "Doe",
         "DELETE_LABEL":             "Delete",
         "DOWNLOAD_LABEL":           ".pdf",
         "DOWNLOAD_LINK":            "..\/cases\/cases_ShowOutputDocument?a=4674916455a9611cfa0e8e6010566295&v=2&ext=pdf&random=98480022",
         "DOWNLOAD_LABEL1":          ".doc",
         "DOWNLOAD_LINK1":           "..\/cases\/cases_ShowOutputDocument?a=4674916455a9611cfa0e8e6010566295&v=2&ext=doc&random=2117881970",
         "APP_DOC_UID_VERSION":      "4674916455a9611cfa0e8e6010566295_2"
      },
      {
         "APP_DOC_UID":              "6339878345a8664d1553481052427126",
         "APP_DOC_FILENAME":         "labor_contract_mary_williams.doc",
         "APP_DOC_COMMENT":          "final draft of contract",
         "DOC_VERSION":              1,
         "APP_UID":                  "6450207755a8664b146d762079795117",
         "DEL_INDEX":                1,
         "DOC_UID":                  "3361325995a866456c2e8c3050631873",
         "USR_UID":                  "00000000000000000000000000000001",
         "APP_DOC_TYPE":             "INPUT",
         "APP_DOC_CREATE_DATE":      "2018-02-15 23:57:53",
         "APP_DOC_INDEX":            1,
         "FOLDER_UID":               "",
         "APP_DOC_PLUGIN":           "",
         "APP_DOC_TAGS":             "INPUT",
         "APP_DOC_STATUS":           "ACTIVE",
         "APP_DOC_STATUS_DATE":      null,
         "APP_DOC_FIELDNAME":        "contractFile",
         "APP_DOC_DRIVE_DOWNLOAD":   null,
         "SYNC_WITH_DRIVE":          "UNSYNCHRONIZED",
         "SYNC_PERMISSIONS":         null,
         "APP_TITLE":                "#269",
         "APP_DESCRIPTION":          "",
         "APP_NUMBER":               269,
         "APP_PARENT":               "",
         "APP_STATUS":               "DRAFT",
         "PRO_UID":                  "1953128925a864f18e70955009266756",
         "APP_PROC_CODE":            "",
         "STATUS":                   "Draft",
         "CREATOR":                  "Baker Sally",
         "CREATE_DATE":              "2018-02-15 23:57:21",
         "UPDATE_DATE":              "2018-02-16 00:13:49",
         "PRO_TITLE":                "Onboard New Employee",
         "INP_DOC_UID":              "3361325995a866456c2e8c3050631873",
         "INP_DOC_TITLE":            "Contract File",
         "INP_DOC_DESCRIPTION":      "",
         "INP_DOC_FORM_NEEDED":      "VIRTUAL",
         "INP_DOC_ORIGINAL":         "ORIGINAL",
         "INP_DOC_PUBLISHED":        "PRIVATE",
         "INP_DOC_VERSIONING":       0,
         "INP_DOC_DESTINATION_PATH": "",
         "INP_DOC_TAGS":             "INPUT",
         "INP_DOC_TYPE_FILE":        ".*",
         "INP_DOC_MAX_FILESIZE":     0,
         "INP_DOC_MAX_FILESIZE_UNIT":"KB",
         "USR_USERNAME":             "sallybaker",
         "USR_FIRSTNAME":            "Sally",
         "USR_LASTNAME":             "Baker",
         "DELETE_LABEL":             "Delete",
         "DOWNLOAD_LABEL":           "Download",
         "DOWNLOAD_LINK":            "..\/cases\/cases_ShowDocument?a=6339878345a8664d1553481052427126&v=1",
         "DOWNLOAD_LABEL1":          "",
         "DOWNLOAD_LINK1":           "",
         "APP_DOC_UID_VERSION":      "6339878345a8664d1553481052427126_1"
      },
   ],
   "totalDocumentsCount":            38
}

Get Dynaform fields: GET extrarest/dynaform/{dyn_uid}

Available in version 1.9 and later.

Similar to the PMFDynaformFields() function, this endpoint retrieves the fields and all their properties in a specified Dynaform.

If the unique ID of a case and its delegation index is specified, then the values and their labels from the specified case will be inserted in the Dynaform fields. Note that the label is the same as the value for textboxes and textareas, but it is the displayed text of a selected option in a dropdown box, suggest box, radio button, checkbox and checkgroup.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/dynaform/{dyn_uid}

or:

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/dynaform/{dyn_uid}?app_uid={app_uid}&del_index={del_index}

URL parameters:

  • string dyn_uid: The unique ID of a Dynaform.

Optional query parameters:

  • string app_uid: The unique ID of a case, whose data will be inserted in the fields.
  • string del_index: The delegation index. This must also be specified if app_uid is specified.

Response:

An array of objects holding the properties of the fields in the Dynaform. If the app_uid and del_index are included, then the value and value_label properties are included in fields which have an associated variable to hold data entered by users.

Example:

Request:

http://pm.example.com/api/1.0/workflow/extrarest/dynaform/3226989465af1b019429411086511542?app_uid=1394624895c394426572487032943271&del_index=3

Response:

200 OK
[ 
  {
    "type":              "title",
    "id":                "title0000000001",
    "label":             "Review Order List",
    "colSpan":           12,
  },
  {
    "type":              "text",
    "variable":          "productName",
    "var_uid":           "6339878345a8664d1553481052427126",
    "dataType":          "string",
    "protectedValue":    false,
    "id":                "productName",
    "name":              "productName",
    "label":             "Product Name",
    "defaultValue":      "",
    "placeholder":       "",
    "hint":              "",
    "required":          false,
    "requiredFieldErrorMessage": "",
    "textTransform":     "none",
    "validate":          "",
    "validateMessage":   "",
    "maxLength":         1000,
    "formula":           "",
    "mode":              "parent",
    "operation":         "",
    "dbConnection":      "workflow",
    "dbConnectionLabel": "PM Database",
    "sql":               "",
    "var_name":          "productName",
    "colSpan":           12,
    "value":             "Acme Coyote Trap",
    "value_label":       "Acme Coyote Trap"
  },
  {
    "type":              "dropdown",
    "variable":          "productCategory",
    "var_uid":           "6797822835c3ff7355edee9030700606",
    "dataType":          "string",
    "protectedValue":    false,
    "id":                "productCategory",
    "name":              "productCategory",
    "label":             "Product Category",
    "defaultValue":      "",
    "placeholder":       "",
    "hint":              "",
    "required":          false,
    "requiredFieldErrorMessage": "",
    "mode":              "parent",
    "datasource":        "dataVariable",
    "dbConnection":      "workflow",
    "dbConnectionLabel": "PM Database",
    "sql":               "",
    "dataVariable":      "@@categoryList",
    "options":           [],
    "var_name":          "productCategory",
    "colSpan":           12,
    "value":             "consumer_electronics",
    "value_label":       "Consumer Electronics"
  },
  {
    "type":              "submit",
    "id":                "submit0000000001",
    "name":              "submit0000000001",
    "label":             "Submit",
    "colSpan":           12
  }
]

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

Available in version 1.9 and later.

Execute a trigger with input and output variables. Unlike the official endpoint PUT /cases/{app_uid}/execute-trigger/{tri_uid}, this endpoint has a option to write variables to the case before executing the trigger and another option to specify case variables which should be returned after executing the trigger. There is also an option to restore the case variables to their original state before the trigger was executed.

Security: In order to execute this endpoint, the logged-in user needs to either be currently assigned to the open delegation specified by the del_index parameter or needs to be assigned as a process supervisor to the case's process.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/{app_uid}/execute-trigger/{tri_uid}

URL Parameters:

  • string app_uid: Unique ID of case where the trigger will be executed.
  • string tri_uid: Unique ID of the trigger to execute.

POST Parameters:

  • int del_index: Optional. Delegation index where the trigger will be executed. If not included or set to -1, then the last open delegation assigned to the logged-in user will be used. If there are no open delegations in the case, then it will cause an error.
  • array input_vars: Optional. A JSON string containing an object of variables to set in the case before executing the trigger.
    Use this format: {variable1: "value1", variable2: "value2"}
  • string return_vars: Optional. Which type of variables should be returned from the case after executing the trigger. The available options are:
    • "NONE": No variables are returned, which is the default if not specified,
    • "ALL": All variables, including both case and system variables,
    • "ONLY_CASE": Only case variables,
    • "ONLY_SYSTEM": Only system variables,
    • "SPECIFY": Only varibles specified by the list_vars parameter are returned,
    • "ALL_EXCEPT": All variables except the variables specified by the list_vars parameter are returned.
  • string list_vars: Optional. If return_vars is set to "SPECIFY" or "ALL_EXCEPT", then list the names of the case variables separated by commas to return.
    Note: If a specified variable is missing, then it will be listed in a "__MISSING_VARS__" element in the return array.
  • int revert_vars Optional. If set to 1, then the case's variables will be reverted to their original state before the trigger was executed. Set to 0 or don't include to not revert the case variables.
    Remember that reverting will remove the __ERROR__ variable if it was set, so don't use this option if needing to debug.

Response:

An array with the variables indicated by the return_vars parameter:

{
  "variable1": "value1",
  "variable2": "value2",
  ...
}

PHP example:

$caseId    = '2996151895c3d5e0b826e22066338193';
$triggerId = '7854719025c3d5dc0c6f196036376771'; //trigger to calculate total price with tax

$aVars = array(
   'productName' => 'Brass ball bearings',
   'quantity'    => 58,
   'price'       => 8.99,
   'taxRate'     => 0.06
);

$aParams = array(
   'input_vars'  => $aVars,
   'return_vars' => 'SPECIFY', 
   'list_vars'   => 'totalOrder,salesRepresentative,productUrl',
   'revert_vars' => 1
);

$url = "/api/1.0/workflow/extrarest/case/$caseId/execute-trigger/$triggerId";
$oRet = pmRestRequest("PUT", $url, $aParams, $oToken->access_token);

if ($oRet->status == 200) {
   $totalOrder = $oRet->response->totalOrder;
}

Starting Tasks in Process: GET extrarest/project/{prj_uid}/starting-tasks

Available in version 1.10 and later.

Gets the starting task(s) for a specified project or process. Unlike the official endpoint GET /project/{prj_uid}/starting-tasks, which only gets the starting tasks assigned to the logged-in user, this endpoint can also get the starting task(s) assigned to a specified user.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/project/{prj_uid}/starting-tasks

or:

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/project/{prj_uid}/starting-tasks?usr_uid={usr_uid}

URL Parameters:

  • string prj_uid: Unique ID of the project or process whose starting tasks will be returned.
  • string usr_uid: Optional. Unique ID of the user who is assigned to the starting tasks. If not specified, then will return the starting task(s) assigned to the logged-in user.

Response:

The HTTP status code is 200 if successful and an array of objects holding information about the starting tasks is returned in the following format:

[
  {
    "act_uid":  "{task_uid}",
    "act_name": "{task_title}"
  },
  ...
]

Example:

Request:

GET https://pm.example.com/api/1.0/workflow/extrarest/project/6579030565c340791787669008961750/starting-tasks?usr_uid=6177238035c3d4f9b069616035753517

Response:

200 (OK)
[
  {
    "act_uid":  "5047009445c3407bb8ca2f4064496770",
    "act_name": "Calculate Estimate"
  },
  {
    "act_uid":  "5883742585c539a031e32b1075243298",
    "act_name": "Customer Lead"
  }
]

PHP example:

$oToken = pmRestLogin($clientId, $clientSecret, 'freddy', 'p@sSw0rd');

$processId = '6579030565c340791787669008961750'; //process "Consult external user via email"
$userId    = '6177238035c3d4f9b069616035753517'; //user "mary"
$url = "/api/1.0/workflow/extrarest/project/$processId/starting-tasks?usr_uid=$userId";

$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);
	
if ($oRet->status != 200) {
   print "Unable to get the starting tasks assigned to user.\nError " . $oRet->status;
   if (isset($oRet->error->message)) {
      print ": " . $oRet->error->message . "\n";
   }
}
else {
   $aTasks = $oRet->response;
   if (count($aTasks) == 0) {
      print "User is not assigned to any tasks.\n";
   }
   elseif (count($aTasks) == 1) {
      $taskTitle = $aTasks[0]['act_name'];
   }
   else { //more than one starting task
      //get list of tasks for in an associative array for user to select one in a dropdown   
      $aSelectTasks = array();   
      foreach ($aTasks as $oTask) {
         $aSelectTasks[ $oTask['act_uid'] ] = $oTask['act_name'];
      }
  }
}





Generate Output Document: POST extrarest/case/{app_uid}/output-doc...

Available in version 1.11 and later.

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.

Unlike the official endpoint POST /cases/{app_uid}/{del_index}/output-document/{out_doc_uid}, this endpoint will look up the delegation index if not specified and allows Process Supervisors to generate Output Documents for another user assigned to the case.

POST http://{domain-or-ip}/api/1.0/{workspace}/extrarest/case/{app_uid}/output-document/{out_doc_uid}

URL parameters:

  • string app_uid: Unique ID of case where the Output Document will be generated.
  • string out_doc_uid: Unique ID of the Output Document definition.

POST variables:

  • string del_index: Optional. The delegation index of the task where the Output Document will be generated. If not specified, then the last open delegation index assigned to the user will be used. Note that this delegation must be open and it must contain an Output Document step, or a error will be returned.
  • string usr_uid: Optional. The unique ID of the user assigned to the open task where the Output Document file will be generated. If not specified, then the logged-in user will generate the Output Document. If specifying a user who is not the logged-in user, then the logged-in user must be assigned as a Supervisor to the case's process.

Response:

If successful, the HTTP status will be set to 200 and a JSON object will be returned with information about the generated Output Document file, which contains:

  • "app_doc_uid": Unique ID of the generated Output Document file, which corresponds to the field APP_DOCUMENT.APP_DOC_UID in the database.
  • "app_doc_filename": The filename of the generated Output Document.
  • "doc_uid": Unique ID of the Output Document definition.
  • "app_doc_version": The version of the Output Document file, which starts numbering from 1. Each time the Output Document is generated for a case, this number is incremented by 1.
  • "app_doc_create_date": The datetime when the Output Document was generated in the format "YYYY-MM-DD HH:MM:SS".
  • "app_doc_create_user": The name of the user who generated the Output Document file in the format "{last_name}, {first_name} ({username})".
  • "app_doc_type": What type of document will be generated, which can be "OUTPUT DOC", "OUTPUT PDF" or "OUTPUT BOTH".
  • "app_doc_index": The case document index of the generated Output Document file. This number counts all files in a case, regardless of type. The first file in a case with have an index of 1, the second file will be 2, the third file will be 3, etc.
  • "app_doc_link": A partial URL to download the generated Output Document file, such as:
    "cases/cases_ShowOutputDocument?a=9106085455c5a76593e4305055948142&v=1&ext=pdf&random=449132548"
    If the type of generated document is DOC, the URL will contain "&ext=doc", and if the type is PDF, then it will contain "&ext=pdf". If the type is BOTH, then it will contain "&ext=pdf", so the URL will have to changed to "&ext=doc" to download the Microsoft Word file. The partial URL can be appended to http{s}://{domain}/sys{workspace}/{lang}/{skin}/" to download the file. For example:
    https://pm.example.com/sysworkflow/en/neoclassic/cases/cases_ShowOutputDocument?a=9106085455c5a76593e4305055948142&v=1&ext=pdf&random=449132548

If trying to generate an Output Document for another user, then the logged-in user must be assigned as a Supervisor to the processs. Otherwise, the endpoint will fail and the HTTP status will be set to 400 and the following error object will be returned:

{
  "error": {
    "code":    400,
    "message": "Bad Request: User '00000000000000000000000000000001' must be assigned as a Supervisor for process '1337727455c5a6dbcf41ef7022485832'."
  }
}

If the case is already closed or the user isn't assigned to any open tasks in the case, then the HTTP status will be set to 400 and the following error object will be returned:

{
  "error": {
    "code":    400,
    "message": "Bad Request: This case has 0 current delegations"
  }
}

Note: In order to be able to download files from ProcessMaker, make sure to add the following line to the env.ini configuration file:

disable_download_documents_session_validation = 1

Example:

Request:

POST https://pm.example.com/api/1.0/workflow/extrarest/case/6704951675c5a72d74fe049066797294/output-document/4231550895c5a6e04f02fe8020541789

Response:

200
{
  "app_doc_uid":         "9106085455c5a76593e4305055948142",
  "app_doc_filename":    "product_invoice.pdf",
  "doc_uid":             "4231550895c5a6e04f02fe8020541789",
  "app_doc_version":     1,
  "app_doc_create_date": "2019-02-06 05:53:29",
  "app_doc_create_user": "Batto, Amos (amos)",
  "app_doc_type":        "OUTPUT BOTH",
  "app_doc_index":       1,
  "app_doc_link":        "cases/cases_ShowOutputDocument?a=9106085455c5a76593e4305055948142&v=1&ext=pdf&random=449132548"
}

PHP Example:

$oToken = pmRestLogin($clientId, $clientSecret, 'admin', 'p@sSw0rD');

$outDocId = '4231550895c5a6e04f02fe8020541789';
$caseId = '6704951675c5a72d74fe049066797294'; 
$index = 3;
$aVars = array(
   'del_index' => 1,
   'usr_uid'   => '6177238035c3d4f9b069616035753517'
);

$url = "/api/1.0/workflow/extrarest/case/$caseId/output-document/$outDocId";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   $baseUrl = 'https://pm.acme.com/sysworkflow/en/neoclassic';
   //assuming that Output Document generates both DOC and PDF files:
   $pdfLink = $baseUrl . $oRet->response->app_doc_link;
   $docLink = $baseUrl . str_replace('=pdf', '=doc', $oRet->response->app_doc_link);
   
   //Download binary PDF file:
   $handle = fopen($pdfLink, "rb") or die("Error: Unable to open file:\n$pdfLink");
   $contents = stream_get_contents($handle) or die("Error: Unable to get file:\n$pdfLink");
   //save file on local computer:
   file_put_contents('/user/bob/reports/'.$oRet->response->app_doc_filename, $contents); 
   fclose($handle);

   //serve up the PDF file for download as attachment in user's browser:
   header('Content-Description: File Transfer');
   header('Content-Type: application/octet-stream');
   header('Content-Disposition: attachment; filename="' . $oRet->response->app_doc_filename . '"');
   header('Content-Transfer-Encoding: binary');
   header('Expires: 0');
   header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
   header('Pragma: public');
   header('Content-Length: ' . strlen($contents));
   print $contents;
   die;            //die here so that ?> at end of script isn't printed
}

Version Control

Version 1.12 (2019-02-22)

File: extraRest-1.12.tar

Added endpoint:

Version 1.11 (2019-02-06)

File: extraRest-1.11.tar

Added endpoint:

Version 1.10 (2019-01-31)

File: extraRest-1.10.tar

Added endpoint:

Version 1.9 (2019-01-16)

File: extraRest-1.9.tar

Added endpoints:

Fixed plugin so it can be imported in PHP 7.0 and later.

Version 1.8 (2018-09-23)

File: extraRest-1.8.tar

Added endpoint:

Version 1.7 (2018-07-24)

File: extraRest-1.7.tar

Changed endpoints:

Fixed bug that APP_STATUS was not set to 'PAUSED' for paused cases. Also, now returns information about the last task delegation in the case.

Fixed bug that APP_STATUS was not set to 'PAUSED' for paused cases.

Version 1.6 (2018-06-06)

File: extraRest-1.6.tar

Added endpoint:

Version 1.5 (2018-05-21)

File: extraRest-1.5.tar

Added endpoint:

Version 1.4 (2018-05-10)

File: extraRest-1.4.tar

Fixed bug in GET extrarest/documents/{fdr_uid}/contents when listing fewer files than the number of available files in a directory.

Version 1.3 (2018-04-23)

File: extraRest-1.3.tar

Added endpoints:

Version 1.2 (2018-04-17)

File: extraRest-1.2.tar

Added endpoints:

Commented out the code of Execute database query: POST extrarest/sql for security reasons, but left it in the source code in case anyone wants to enable it for testing or adapting.

Commented out the code to use extraRest/setup.xml because people reported that it caused problems installing the plugin.

Version 1.1 (2018-04-04)

File: extraRest-1.1.tar

First version posted on Github. There are several versions 1 which were posted on the forum, so numbered 1.1 to distinguish this version.