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.13.tar
Author: Amos Batto (amos@processmaker.com)
Version: 1.13 (2019-05-13)
Tested in: ProcessMaker 3.2.1 - 3.3.8 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. This endpoint also allows a Process Supervisor to assign the task to another user.

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/open?APP_UID={app_uid}&DEL_INDEX={delegation_number}&action=todo&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/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}?sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/opencase/9777918985a8dddbf884236088281261?sid=1234567890abcde1234567890abcde

Open a Dynaform:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/cases/cases_Step?TYPE=DYNAFORM&UID={dynaform_uid}&POSITION={position}&ACTION=EDIT&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/cases/cases_Step?TYPE=DYNAFORM&UID=7415122705c46899b4b08c6022893958&POSITION=3&ACTION=EDIT&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/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}/designer?prj_uid={process_uid}&prj_readonly=true&app_uid={app_uid}&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/designer?prj_uid=6135378175a8dcdca9a2641037096319&prj_readonly=true&app_uid=9777918985a8dddbf884236088281261&sid=1234567890abcde1234567890abcde

Show the case tracker's process map:

  • http://{domain_or_ip}/sys{workspace}/{lang}/{skin}/designer?prj_uid={process_uid}&prj_readonly=true&app_uid={app_uid}&tracker_designer=1&sid={session_id}
  • Ex: http://example.com/sysworkflow/en/neoclassic/designer?prj_uid=6135378175a8dcdca9a2641037096319&prj_readonly=true&app_uid=9777918985a8dddbf884236088281261&tracker_designer=1&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 information: GET extrarest/user

Available in version 1.13 and later.

Get the account information about a specified user, including the default menu preferences and a URL to download the user's profile photo, which isn't provided by the official GET /users/{uid_uid} endpoint.

The official endpoint also requires the PM_USERS permission, but this endpoint only requires a valid login to get information about the currently logged-in user. However, it requires the PM_USERS permission to acquire information about a different user.

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

URL parameters:

  • string usr_uid: Optional. Unique ID of user whose account information will be retrieved. If not included or empty, then the ID of the currently logged user will be used by default.

Response:

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

{
    "usr_uid":                 "2338262825c64d93a6c75c6051533271",
    "usr_username":            "amosbatto",
    "usr_firstname":           "Amos",
    "usr_lastname":            "Batto",
    "usr_email":               "amos@example.com",
    "usr_due_date":            "2024-12-31",
    "usr_create_date":         "2019-02-14 02:58:02",
    "usr_update_date":         "2019-06-14 00:20:31",
    "usr_status":              "VACATION",
    "usr_country":             "US",
    "usr_city":                "CA",
    "usr_location":            "SPQ",
    "usr_address":             "636 W. Almond Av.\nSan Pedro, CA 45837",
    "usr_phone":               "1-874-382-7633",
    "usr_fax":                 "",
    "usr_cellular":            "",
    "usr_zip_code":            "45135",
    "dep_uid":                 "",
    "usr_position":            "Chief accountant",
    "usr_resume":              "",
    "usr_birthday":            "2019-02-14",
    "usr_role":                "PROCESSMAKER_MANAGER",
    "usr_reports_to":          "",
    "usr_replaced_by":         "2053768455c6cab4500e4b1062491650",
    "usr_calendar_uid":        "4244358425d0075ec7ede17084040535",
    "usr_calendar_name":       "Bolivian Calendar",
    "usr_ux":                  "NORMAL",
    "usr_photo_path":          "/opt/pm3.3.3/shared/sites/workflow/usersPhotographies/2338262825c64d93a6c75c6051533271.gif",
    "pref_default_lang":       "en",
    "pref_default_menu":       "PM_CASES",
    "pref_default_cases_menu": "CASES_SENT",
    "usr_photo_url":           "http://localhost:333/sysworkflow/en/neoclassic/users/users_ViewPhotoGrid?pUID=2338262825c64d93a6c75c6051533271"
}

Note: If called for ProcessMaker Enterprise Edition, the returning JSON object will also include the following user information:

{
    "usr_time_zone":           "America/New_York", 
    "usr_cost_by_hour":        "15.50", 
    "usr_unit_cost":           "dollars"
}

Note: The usr_fax, usr_cellular, usr_birthday and usr_resume are deprecated and no longer used by the ProcessMaker interface, but it is still possible to set these values in the USERS table in the database.


PHP Example:

$userId = '2338262825c64d93a6c75c6051533271';
$url = "/api/1.0/workflow/extrarest/user?usr_uid=$userId";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);
print "\n\n".json_encode($oRet->response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)."\n\n";

//display user profile photo, if set:
if ($oRet->status == 200 and isset($oRet->response['usr_photo_url'])) {
   print '<img src="'.$oRet->response['usr_photo_url'].'">';
}

Get user information for editing: GET extrarest/user/edit

Available in version 1.13 and later.

Get information about a specified user for editing the user's account. This endpoint returns similar information to GET extrarest/user, but it also includes the list of available roles, calendars and statuses that can be displayed in a dropdown's list of options. It also returns the list of permissions in the logged-in user's role, in order to know what user account information can be changed by the user.

It requires that the user either has the PM_USERS or PM_EDITPERSONALINFO permission to edit her own account or the PM_USERS permission to edit another user's account. If using version 3.1 or later, then it will remove information for which the logged-in user doesn't have the PM_EDIT_USER_PROFILE_* permissions.

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

URL parameters:

  • string usr_uid: Optional. Unique ID of user whose account information will be retrieved. If not included or empty, then the ID of the currently logged user will be used by default.

Response:

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

{
    "usr_uid": "2338262825c64d93a6c75c6051533271",
    "usr_username": "amosbatto",
    "usr_firstname": "Amos",
    "usr_lastname": "Batto",
    "usr_email": "amos@example.com",
    "usr_due_date": "2024-12-31",
    "usr_create_date": "2019-02-14 02:58:02",
    "usr_update_date": "2019-06-14 00:20:54",
    "usr_status": "VACATION",
    "usr_country": "US",
    "usr_city": "CA",
    "usr_location": "SPQ",
    "usr_address": "636 W. Almond Av.\nSan Pedro, CA 45837",
    "usr_phone": "1-874-382-7633",
    "usr_fax": "",
    "usr_cellular": "",
    "usr_zip_code": "45135",
    "dep_uid": "",
    "usr_position": "Chief accountant",
    "usr_resume": "",
    "usr_birthday": "2019-02-14",
    "usr_role": "PROCESSMAKER_MANAGER",
    "usr_reports_to": "",
    "usr_replaced_by": "2053768455c6cab4500e4b1062491650",
    "usr_calendar_uid": "4244358425d0075ec7ede17084040535",
    "usr_calendar_name": "Bolivian Calendar",
    "usr_ux": "NORMAL",
    "usr_photo_path": "/opt/pm3.3.3/shared/sites/workflow/usersPhotographies/2338262825c64d93a6c75c6051533271.gif",
    "usr_photo_url": "http://localhost:333/sysworkflow/en/neoclassic/users/users_ViewPhotoGrid?pUID=2338262825c64d93a6c75c6051533271",
    "pref_default_lang": "en",
    "pref_default_menu": "PM_CASES",
    "pref_default_cases_menu": "CASES_SENT",
    "permissions": [
        "PM_ALLCASES",
        "PM_CANCELCASE",
        "PM_CASES",
        "PM_DASHBOARD",
        "PM_DELETE_PROCESS_CASES",
        "PM_EDITPERSONALINFO",
        "PM_EDITPERSONALINFO_CALENDAR",
        "PM_EDIT_USER_PROFILE_ADDRESS",
        "PM_EDIT_USER_PROFILE_CALENDAR",
        "PM_EDIT_USER_PROFILE_COSTS",
        "PM_EDIT_USER_PROFILE_COUNTRY",
        "PM_EDIT_USER_PROFILE_DEFAULT_CASES_MENU_OPTIONS",
        "PM_EDIT_USER_PROFILE_DEFAULT_LANGUAGE",
        "PM_EDIT_USER_PROFILE_DEFAULT_MAIN_MENU_OPTIONS",
        "PM_EDIT_USER_PROFILE_EMAIL",
        "PM_EDIT_USER_PROFILE_EXPIRATION_DATE",
        "PM_EDIT_USER_PROFILE_FIRST_NAME",
        "PM_EDIT_USER_PROFILE_LAST_NAME",
        "PM_EDIT_USER_PROFILE_LOCATION",
        "PM_EDIT_USER_PROFILE_PASSWORD",
        "PM_EDIT_USER_PROFILE_PHONE",
        "PM_EDIT_USER_PROFILE_PHOTO",
        "PM_EDIT_USER_PROFILE_POSITION",
        "PM_EDIT_USER_PROFILE_REPLACED_BY",
        "PM_EDIT_USER_PROFILE_ROLE",
        "PM_EDIT_USER_PROFILE_STATE_OR_REGION",
        "PM_EDIT_USER_PROFILE_STATUS",
        "PM_EDIT_USER_PROFILE_TIME_ZONE",
        "PM_EDIT_USER_PROFILE_USERNAME",
        "PM_EDIT_USER_PROFILE_USER_MUST_CHANGE_PASSWORD_AT_NEXT_LOGON",
        "PM_EDIT_USER_PROFILE_ZIP_CODE",
        "PM_FOLDERS_ADD_FILE",
        "PM_FOLDERS_ADD_FOLDER",
        "PM_FOLDERS_VIEW",
        "PM_FOLDER_DELETE",
        "PM_LOGIN",
        "PM_REASSIGNCASE",
        "PM_REST_API_APPLICATIONS",
        "PM_SETUP_CALENDAR",
        "PM_SETUP_CASES_LIST_CACHE_BUILDER",
        "PM_SETUP_CLEAR_CACHE",
        "PM_SETUP_DASHBOARDS",
        "PM_SETUP_EMAIL",
        "PM_SETUP_ENVIRONMENT",
        "PM_SETUP_HEART_BEAT",
        "PM_SETUP_LANGUAGE",
        "PM_SETUP_LOGIN",
        "PM_SETUP_LOGO",
        "PM_SETUP_LOGS",
        "PM_SETUP_PLUGINS",
        "PM_SETUP_PM_TABLES",
        "PM_SETUP_PROCESS_CATEGORIES",
        "PM_SETUP_SKIN",
        "PM_SETUP_USERS_AUTHENTICATION_SOURCES",
        "PM_SUPERVISOR",
        "PM_UNCANCELCASE",
        "PM_USERS"
    ],
    "available_roles": [
        [
            "PROCESSMAKER_ADMIN",
            "System Administrator"
        ],
        [
            "PROCESSMAKER_MANAGER",
            "Manager"
        ],
        [
            "PROCESSMAKER_OPERATOR",
            "Operator"
        ]
    ],
    "available_statuses": [
        [
            "ACTIVE",
            "Active"
        ],
        [
            "INACTIVE",
            "Inactive"
        ],
        [
            "VACATION",
            "Vacation"
        ]
    ],
    "available_calendars": [
        [
            "4244358425d0075ec7ede17084040535",
            "Bolivian Calendar"
        ],
        [
            "00000000000000000000000000000001",
            "Default Calendar"
        ]
    ]
}

PHP Example:

$userId = '2338262825c64d93a6c75c6051533271';
$url = "/api/1.0/workflow/extrarest/user/edit?usr_uid=$userId";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);
print "\n\n".json_encode($oRet->response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)."\n\n";

//display user profile photo, if set:
if ($oRet->status == 200 and isset($oRet->response['usr_photo_url'])) {
   print '<img src="'.$oRet->response['usr_photo_url'].'">';
}



Update a user's account information: PUT extrarest/user/update

Available in version 1.13 and later.

Update a user's account information.

The logged-in user requires the PM_USERS permission if updating another user's account. If updating her own account, then requires the PM_USERS or PM_EDITPERSONALINFO permission in her role. If the user doesn't have PM_EDIT_USER_PROFILE_* permissions in version 3.1 and later, then the user properties which lack permissions won't be set, but no Exception will be called. Check the endpoint's output to verify which properties were able to be set.

PUT http://{domain-or-ip}/api/1.0/{workspace}/extrarest/user/update

URL parameters:

  • string usr_uid: Optional. Unique ID of user whose account information will be updated. If not included or empty, then the ID of the currently logged user will be updated by default.
  • string usr_username: Optional. A case-insensitive username which is unique and can't contain spaces. It is recommended to only use ASCII letters and underscores in the username.
  • string usr_firstname: Optional. User's first name, upt tp 50 characters long.
  • string usr_lastname: Optional. User's last name, up to 50 characters long.
  • string usr_email: Optional. User's email address, up to 100 characters long. This address must be unique, meaning that two users cannot share the same email address.
  • string usr_address: Optional. The user's address, up to 255 characters long. It may include hard returns (\n). If the user's country, region or location are not found in the database, then recommended to include them here.
  • string usr_zip_code: Optional. Zip code or postal code, up to 16 characters long.
  • string usr_country: Optional. Two uppercase letters for the ISO 3166-1 country code, which is found in the ISO_COUNTRY table in database.
  • string usr_region: Optional. Three uppercase letter or number for the ISO 3166-2 code for the region, which can be found in the ISO_SUBDIVISION table in the database.
  • string usr_location: Optional. Three uppercase letter or number for the ISO 3166-2 code for the location, which is found in the ISO_LOCATION table in the database. Usually location names in a non-Roman alphabet like Russian or Chinese use numbers to identify their locations.
  • string usr_phone: Optional. The user's phone number. {@from body}{@max 24}
  • string usr_position: Optional. The user's position, up to 100 characters long. There is no fixed set of positions available, so any value can be entered.
  • string usr_replaced_by: Optional. Unique ID of user who will be assigned to the user's new cases if her status is changed to "INACTIVE" or "VACATION".
  • string usr_due_date: Optional. Expiration date of user's account in "YYYY-MM-DD" format.
  • string usr_calendar: Optional. Unique ID of calendar to assign to user.
  • string usr_status: Optional. The user's status which can be: ACTIVE, INACTIVE or VACATION
  • string usr_role: Optional. The role to assign to the user, such as 'PROCESSMAKER_OPERATOR', 'PROCESSMAKER_MANAGER', 'PROCESSMAKER_ADMIN' or a custom role.
  • string usr_time_zone: Optional. Enterprise Edition Only. The user's time zone which will be used to adjust datetimes to the time zone of the user. The available time zones are found at https://www.php.net/manual/en/timezones.php
  • float usr_cost_by_hour: Optional. Enterprise Edition Only. Cost of user working for an hour. This value used when calculating KPIs in the Enterprise Edition.
  • string usr_unit_cost: Optional. Enterprise Edition Only. Currency unit of the usr_cost_by_hour, such as "dollars", "euros", "yen", etc.
  • string usr_new_pass: Optional. New password to set, up to 64 characters long.
  • string usr_cnf_pass: Optional. Confirm the new password by repeating it. If set, then will be checked to verify that the same as usr_new_pass. Otherwise, not used.
  • string usr_logged_next_time: Optional. Set to 1 to force user to change password on next login. Otherwise, set to 0 or don't include.
  • string usr_default_lang: Optional. Default interface language in "xx" or "xx-CC" format, such as "es" (Spanish) or "pt-BR" (Brazilian Portuguese).
  • string pref_default_lang: Optional. In form of "xx" or "xx-CC" where xx is the language code, such as "en" (English) and CC is the ISO country code, such as "pt-BR" (Brazilian Portuguese).
  • string pref_default_menuselected: Optional. The default main menu which will be displayed when the user initially logs in. Available options:
    • "": Default for role,
    • "PM_CASES": Home,
    • "PM_FACTORY": Designer,
    • "PM_SETUP": Admin,
    • "PM_DASHBOARD": Dashboard,
    • "PM_STRATEGIC_DASHBOARD": KPIs,
    • or any custom menu defined by a plugin.
  • string pref_default_cases_menuselected: Optional. The default submenu selected by default in the cases sidebar under Home. 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 contains an object holding the properties which were changed in the user's account.

Example:

Request:

PUT http://example.com/api/1.0/workflow/extrarest/user/update
{
  "usr_uid"                         : "2338262825c64d93a6c75c6051533271",
  "usr_username"                    : "amosbatto",
  "usr_firstname"                   : "Amos",
  "usr_lastname"                    : "Batto",
  "usr_email"                       : "amos@example.com",
  "usr_address"                     : "636 W. Almond Av.\nSan Pedro, CA 45837",
  "usr_zip_code"                    : "45135",
  "usr_country"                     : "US",
  "usr_region"                      : "CA", 
  "usr_location"                    : "SPQ",
  "usr_phone"                       : "1-874-382-7633",
  "usr_position"                    : "Chief accountant",
  "usr_replaced_by"                 : "2053768455c6cab4500e4b1062491650",
  "usr_due_date"                    : "2024-12-31",
  "usr_calendar"                    : "4244358425d0075ec7ede17084040535", 
  "usr_status"                      : "VACATION",
  "usr_role"                        : "PROCESSMAKER_MANAGER",
  "usr_time_zone"                   : "America/New_York",  
  "usr_cost_by_hour"                : 15.50,
  "usr_unit_cost"                   : "dollars",
  "usr_new_pass"                    : "sample1234",
  "usr_cnf_pass"                    : "sample1234",
  "usr_logged_next_time"            : 1,
  "usr_default_lang"                : "en",
  "pref_default_lang"               : "en",
  "pref_default_menuselected"       : "PM_CASES",
  "pref_default_cases_menuselected" : "CASES_SENT"
}

Response:

200 OK
{
    "usr_uid": "2338262825c64d93a6c75c6051533271",
    "usr_username": "amosbatto",
    "usr_firstname": "Amos",
    "usr_lastname": "Batto",
    "usr_email": "amos@example.com",
    "usr_address": "636 W. Almond Av.\nSan Pedro, CA 45837",
    "usr_zip_code": "45135",
    "usr_country": "US",
    "usr_region": "CA",
    "usr_city": "CA",
    "usr_location": "SPQ",
    "usr_phone": "1-874-382-7633",
    "usr_position": "Chief accountant",
    "usr_replaced_by": "2053768455c6cab4500e4b1062491650",
    "usr_due_date": "2024-12-31",
    "usr_calendar": "4244358425d0075ec7ede17084040535",
    "usr_status": "VACATION",
    "usr_role": "PROCESSMAKER_MANAGER",
    "usr_new_pass": "sample1234",
    "usr_cnf_pass": "sample1234",
    "usr_logged_next_time": 1,
    "usr_default_lang": "en",
    "pref_default_lang": "en",
    "pref_default_menuselected": "PM_CASES",
    "pref_default_cases_menuselected": "CASES_SENT"
}

PHP Example:

$aUserProps = [
  'usr_uid'                         => '2338262825c64d93a6c75c6051533271',
  'usr_username'                    => 'amosbatto',
  'usr_firstname'                   => 'Amos',
  'usr_lastname'                    => 'Batto',
  'usr_email'                       => 'amos@example.com',
  'usr_address'                     => "636 W. Almond Av.\nSan Pedro, CA 45837",
  'usr_zip_code'                    => '45135',
  'usr_country'                     => 'US',
  'usr_region'                      => 'CA', 
  'usr_location'                    => 'SPQ',
  'usr_phone'                       => '1-874-382-7633',
  'usr_position'                    => 'Chief accountant',
  'usr_replaced_by'                 => '2053768455c6cab4500e4b1062491650',
  'usr_due_date'                    => '2024-12-31',
  'usr_calendar'                    => '4244358425d0075ec7ede17084040535', 
  'usr_status'                      => 'VACATION',
  'usr_role'                        => 'PROCESSMAKER_MANAGER',
  'usr_time_zone'                   => 'America/New_York', 
  'usr_cost_by_hour'                => 15.50,
  'usr_unit_cost'                   => 'dollars',
  'usr_new_pass'                    => 'sample1234',
  'usr_cnf_pass'                    => 'sample1234',
  'usr_logged_next_time'            => 1,
  'usr_default_lang'                => 'en',
  'pref_default_lang'               => 'en',
  'pref_default_menuselected'       => 'PM_CASES',
  'pref_default_cases_menuselected' => 'CASES_SENT' 
];
	
$url = '/api/1.0/workflow/extrarest/user/update';
$oRet = pmRestRequest("PUT", $url, $aUserProps, $oToken->access_token, 'json');
print "\n\n".json_encode($oRet->response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)."\n\n";



Upload a user's photo: POST extrarest/user/{usr_uid}/photo

Available in version 1.13 and later.

Upload a user's photo.

The logged-in user requires the PM_USERS permission to upload another user's photo. If uploading her own photo, then requires the PM_USERS or PM_EDITPERSONALINFO permission in her role. If using Processmaker version 3.1 or later, then also requires the PM_EDIT_USER_PROFILE_PHOTO permission.

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

URL parameters:

  • string usr_uid: Unique ID of user whose photo is uploaded.

POST parameters:

  • usr_photo: The contents of a PNG, JPEG or GIF file containing the user's new photo. It will be resized to a 96 by 96 GIF file.

Response:

If successful, the HTTP status code is set to 200 and there is no response.


PHP Example:

$imageFilePath = "/home/amos/pmusers/decisionOptionsInGrid.png";
$userId = '2338262825c64d93a6c75c6051533271';
$aVars = [
  'usr_photo' => curl_file_create($imageFilePath, 'image/png') 
];
$url = "http://example.com/api/1.0/workflow/extrarest/user/$userId/photo";

$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) {
   if (!empty($oResponse) and isset($oResponse->error)) {
       print "Error $httpStatus: ".$oResponse->error."\n";
   }
   else {
      print "Error $httpStatus\n";
   }
}

Get user location information: GET extrarest/user/location

Available in version 1.13 and later.

Get country, region or location information for editing a user's account. Returns a list of options which can be displayed as lists of options in three dropdown boxes which are used to select the user's country, region and location.

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

URL parameters:

  • string category The category which can be:
    • country (such as "United States") which is the default,
    • region (such as "Florida"),
    • location (such as "Miami")
  • string search Optional. Case insensitive string to search for in the category.
  • string country Optional. Two uppercase letter ISO 3166-1 country code such as "US" (United States), found in the ISO_COUNTRY table in the database.
  • string region Optional. ISO 3166-2 subdivision code (which is 3 uppercase letters for countries with Roman alphabets and numbers for other alphabets), found in the ISO_SUBDIVISION table in the database.

Response:

If successful, the HTTP status code is set to 200 and the response contains an array of arrays.


List of countries example:

Search for countries that contain the string "stan".

Request:

GET http://example.com/api/1.0/workflow/extrarest/user/location?category=country&search=stan

Response:

200 "OK"
[
    [
        "AF",
        "Afghanistan"
    ],
    [
        "KG",
        "Kyrgyzstan"
    ],
    [
        "KZ",
        "Kazakhstan"
    ],
    [
        "PK",
        "Pakistan"
    ],
    [
        "TJ",
        "Tajikistan"
    ],
    [
        "TM",
        "Turkmenistan"
    ],
    [
        "UZ",
        "Uzbekistan"
    ]
]

South Korean regions example:

Get a list of the regions in South Korea.

Request:

GET http://example.com/api/1.0/workflow/extrarest/user/location?category=region&country=KR

Response:

200 "OK"
[
    [
        "26",
        "Busan Gwang'yeogsi [Pusan-Kwangy kshi]"
    ],
    [
        "43",
        "Chungcheongbugdo [Ch'ungch' ngbuk-do]"
    ],
    [
        "44",
        "Chungcheongnamdo [Ch'ungch' ngnam-do]"
    ],
    [
        "27",
        "Daegu Gwang'yeogsi [Taegu-Kwangy kshi]"
    ],
    [
        "30",
        "Daejeon Gwang'yeogsi [Taej n-Kwangy kshi]"
    ],
    [
        "42",
        "Gang'weondo [Kang-won-do]"
    ],
    [
        "29",
        "Gwangju Gwang'yeogsi [Kwangju-Kwangy kshi]"
    ],
    [
        "41",
        "Gyeonggido [Ky nggi-do]"
    ],
    [
        "47",
        "Gyeongsangbugdo [Gyeongsangbuk-do]"
    ],
    [
        "48",
        "Gyeongsangnamdo [Ky ngsangnam-do]"
    ],
    [
        "28",
        "Incheon Gwang'yeogsi [Inch n-Kwangy kshi]"
    ],
    [
        "49",
        "Jejudo [Cheju-do]"
    ],
    [
        "45",
        "Jeonrabugdo [Ch llabuk-do]"
    ],
    [
        "46",
        "Jeonranamdo [Ch llanam-do]"
    ],
    [
        "11",
        "Seoul Teugbyeolsi [Seoul-T' kpy lshi]"
    ],
    [
        "31",
        "Ulsan Gwang'yeogsi [Ulsan-Kwangy kshi]"
    ]
]

List of US states example:

Get a list of regions (i.e., states) in the US that contain the string "mis" in their name.

Request:

GET http://example.com/api/1.0/workflow/extrarest/user/location?category=region&country=US&search=mis

Response:

200 "OK"
[
    [
        "MS",
        "Mississippi"
    ],
    [
        "MO",
        "Missouri"
    ]
]

Locations example:

Get a list of locations in the Seoul region of South Koria, which contain the string "seoul" in their name.

Request:

GET http://example.com/api/1.0/workflow/extrarest/user/location?category=location&country=KR&region=11&search=seoul

Response:

200 "OK"
[
    [
        "SEL",
        "Seoul"
    ],
    [
        "SIG",
        "Siheung-dong/Seoul"
    ]
]

Search for user: GET extrarest/user/search

Available in version 1.13 and later.

Get a list of users matching a case insensitive search in the first name, last name and username. This information can be used to create the list of options to select the "Replaced By" user when editing a user's account.

The logged-in user must have the PM_USERS or PM_EDITPERSONALINFO permission in role to call this endpoint.

GET http://{domain-or-ip}/api/1.0/{workspace}/extrarest/user/search?match={string}

URL parameters:

  • string match: Optional. Case insensitive string to search for in the first name, last name and username of the user.

Response:

If successful, the HTTP status code is set to 200 and the response contains an array of arrays holding the following information:

[
    [
        "{user-uid}",
        "{first-name} {last-name} ({username})"
    ],
    ...
]

Example:

Request:

GET http://example.com/api/1.0/workflow/extrarest/user/search?match=AM

Response:

[
    [
        "2338262825c64d93a6c75c6051533271",
        "Amos Batto (amosbatto)"
    ],
    [
        "e78a5c92acb3248372baac6051533ee1",
        "Amy Wyron (amywyron)"
    ]    
]

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,
    • "PM_STRATEGIC_DASHBOARD": KPIs,
    • 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.13 (2019-05-13)

File: extraRest-1.13.tar

Added endpoints:

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.