Please rate how useful you found this document: 
Average: 2 (4 votes)

Mobile Endpoints

The following endpoints are used by the ProcessMaker App installed on mobile devices. Although originally designed for the mobile app, these endpoints can be used in any context and they often return more information than the normal REST endpoints. They are defined in workflow/engine/src/ProcessMaker/Services/Api/Light.php and call code in workflow/engine/src/ProcessMaker/BusinessModel/Light.php.

Create case file record(s): POST /light/case/{app_uid}/upload

Create new case file record(s) in a specified case. These case files can be attached files (used by File controls), Input Document files, or Output Document files in version 1.0.1.8 and later. In version 1.0.1.7 and earlier, the case files can only be attached files. (Note that case files are known as AppDocuments in ProcessMaker).

This endpoint adds new record(s) in the APP_DOCUMENT table and stores their filename(s) in the CONTENT table in the database. It returns the generated case file ID and version number for each file. This information can then be used to call the POST /light/case/{app_uid}/upload/{app_doc_uid} endpoint to upload each file.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

POST /api/1.0/{workspace}/light/case/{app_uid}/upload

URL Parameters:

Name Description Example
workspace Workspace name https://example.com/api/1.0/workflow/cases/115968518533473068ad299078535175/upload
app_uid Unique ID of the case. https://example.com/api/1.0/workflow/cases/115968518533473068ad299078535175/upload

POST Fields:

Example Description
[ Start array of objects.
{ Start object, which holds information about the case file.
"name": "scannedReceipts2016-05.jpg", Required. The filename of the file which will later be uploaded with POST /light/case/{app_uid}/upload/{app_doc_uid}.
"appDocType": "INPUT", Optional, available in version 1.0.1.8 and later. The type of case file, which can be:
"ATTACHED": an attached file which is uploaded to a File control which isn't associated with an Input Document,
"INPUT": an Input Document file (or uploaded to a File control which is associated with an Input Document),
"OUTPUT": an Output Document file. Note: Instead of this option, it is recommended to use POST /cases/{app_uid}/output-document to generate Output Document files.
If not included, then set to "ATTACHED" by default.
"docUid": "26489274557325e0cefb242036509648", Optional, available in version 1.0.1.8 and later. The unique ID of the Input Document or Output Document. Set to -1 for an attached file which is uploaded through a file control which isn't associated with an Input Document. If not included then set to -1 by default.
"fieldName": "receiptFile" Optional, available in version 1.0.1.8 and later. The name of the File control where the file will be uploaded. If uploaded to File controls inside a grid, set to "GridVariable_RowNumber_FileFieldName". For example, a value of "clientList_2_contractFile", means that the file was uploaded to the second row of a grid whose variable is "clientList" and whose File field has the name "contractFile". If the file will be uploaded in an Input Document step (not a File control in a Dynaform), then set to NULL or do not include this parameter.
} End object.
{...} Any additional objects with information about case files, which will later be uploaded.
] End array of objects.

Result:

If the case file record(s) were created, then the HTTP status code is set to 200 (OK) and an array of objects is returned with the following information about the generated case file record(s):

Example Description
[ Start array of objects.
{ Start object, which holds information about the new case file record.
"docVersion": 1, The document version number which will always be 1 for the first version of the case file.
"appDocUid" : "82749015357325e0d1cfef6058054658" The generated unique ID for the new case file.
} End object.
{...} Any additional objects with information about new case files.
] End array of objects.

If a bad case ID is specified, then the HTTP status code will be set to 400 and the following error object will be returned:

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

If the "name" parameter is not included, then the HTTP status code is set to 200 and the response is NULL.

Example:

Request:

[
  {  //attached file uploaded through Home > Documents
     "name": "requestedBudget.xls"
  },
  {  //attached file uploaded to File control with the name "employeePhoto" in a DynaForm
     "name":      "johnDoePhoto.jpg",
     "fieldName": "employeePhoto"
  },
  {  //attached file uploaded to File control with the name "receiptFile" in the first row of grid with "receiptList" variable
     "name":      "officeSupplies.doc",
     "fieldName": "receiptList_1_receiptFile"
  },
  {  //attached file uploaded to File control with the name "receiptFile" in the second row of grid with "receiptList" variable
     "name":      "newOfficeFurniture.doc",
     "fieldName": "receiptList_2_receiptFile"
  },
  {  //Input Document file associated with a File control with the name "contractFile"
     "name":      "AcmeServicesContract.pdf",
     "appDocType":"INPUT",
     "docUid":    "26489274557325e0cefb242036509648"
     "fieldName": "contractFile"
  },
  {  //Input Document file (which is uploaded in an Input Document step and not a File control)
     "name":      "NewWidgetPrices.xls",
     "appDocType":"INPUT",
     "docUid":    "1a8598f3d7d6ce40dc2abbdbd7cdaa49"
  },
]

Response:

[
  {
     "docVersion": 1,
     "appDocUid" : "189395356573278c8b2d799089824447"
  },
  {
     "docVersion": 1,
     "appDocUid" : "201295905573278c8e45438092199134"
  },
  {
     "docVersion": 1,
     "appDocUid" : "9886722215731415bb671a0038276864"
  },
  {
     "docVersion": 1,
     "appDocUid" : "24454306957325ad4205899098323500"
  },
  {
     "docVersion": 1,
     "appDocUid" : "35313659957324f217ccda7000260391"
  },
  {
     "docVersion": 1,
     "appDocUid" : "5876481515732526a093938002875566"
  },
]

PHP Example:

The following example creates a file case record for an Input Document file which is associated with a File control which has the name "expenses".

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "mary", "p4sSw0rD");

$caseId = '9886722215731415bb671a0038276864';
$url = "/api/1.0/workflow/light/case/$caseId/upload";
$filePath = '/home/amos/Pictures/ReceiptListAmountFieldRed.png';
$aVars = array(
  array(
    'name'       => 'newFurnitureReceipt.jpeg',
    'appDocType' => 'INPUT',
    'docUid'     => '26489274557325e0cefb242036509648',
    'fieldName'  => 'expenses'
  )
);

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

if ($oRet->status == 200 and is_array($oRet->response)) {
  $caseFileId = $oRet->response[0]->appDocUid;
  $docVersion = $oRet->response[0]->docVersion;
}