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

Output Documents

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

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

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

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

URL Parameters:

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

Result:

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

For example:

[
   {
      "app_doc_uid":         "14155521453271dd8a16fd9010864110",
      "app_doc_filename":    "Output 2.pdf",
      "doc_uid":             "10401087752fa8bc6f0cab6048419434",
      "app_doc_version":     1,
      "app_doc_create_date": "2014-03-17 12:07:52",
      "app_doc_create_user": "Jones, Mary (maryj)",
      "app_doc_type":        "OUTPUT PDF",
      "app_doc_index":       1,
      "app_doc_link":        "cases/cases_ShowOutputDocument?a=14155521453271dd8a16fd9010864110&v=1&ext=pdf&random=1910389699"
   },
   {
      "app_doc_uid":         "30145523653271ddb4b7936097604166",
      "app_doc_filename":    "asdsa.pdf",
      "doc_uid":             "67423604152fa88941c44d5089456849",
      "app_doc_version":     1,
      "app_doc_create_date": "2014-03-17 12:07:55",
      "app_doc_create_user": "Administrator (admin)",
      "app_doc_type":        "OUTPUT BOTH",
      "app_doc_index":       2,
      "app_doc_link":        "cases/cases_ShowOutputDocument?a=30145523653271ddb4b7936097604166&v=1&ext=pdf&random=996247643"
   }
]

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

PHP Example

This example downloads the generated DOC file for each Output Document. The generated DOC file is really just an HTML file which has a ".doc" extension added, so it can be opened and searched like a normal text file, once it has been converted to plain text. This code uses strip_tags() to remove the HTML tags and uses preg_replace() to replace the <p> and <br> tags with new lines (\n). Then, it searches for "Due Date: ..." in the plain text, and then prints out the filename and its due date for each Output Document.

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

$caseId = '14822205755e60222b0ca68094757835';
$url  = "/api/1.0/workflow/cases/$caseId/output-documents";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   foreach ($oRet->response as $oDoc) {
      $link = "http://localhost:301/sysworkflow/en/neoclassic/" . $oDoc->app_doc_link;
      //get the DOC instead of the PDF file to text searches:
      $link = str_replace('&ext=pdf', '&ext=doc', $link);
      $contents = file_get_contents($link) or die("Error: Unable to get file:\n$link");

      //strip HTML tags and replace <p> and <br> with new lines.
      $contents = strip_tags($contents, "<br><p>");
      $contents = preg_replace('/<(br|p)*?>/i', "\n", $contents);
      $contents = html_entity_decode($contents);

      //If found "Due Date: (...)\n", then get the date:
      if (preg_match('/Due Date: (.+?)$/mi', $contents, $matches))
         $dueDate = $matches[1];
      else
         $dueDate = "NO_DATE";

      print "File {$oDoc->app_doc_filename} is due $dueDate.\n";
   }
}

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

Return a generated Output Document for a given case.

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

Parameters:

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

Result:

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

{
   "app_doc_uid":         "30145523653271ddb4b7936097604166",
   "app_doc_filename":    "clientBill.pdf",
   "doc_uid":             "67423604152fa88941c44d5089456849",
   "app_doc_version":     1,
   "app_doc_create_date": "2014-03-17 12:07:55",
   "app_doc_create_user": "Jones, Mary (mary)",
   "app_doc_type":        "OUTPUT BOTH",
   "app_doc_index":       2,
   "app_doc_link":        "cases/cases_ShowOutputDocument?a=30145523653271ddb4b7936097604166&v=1&ext=pdf&random=996247643"
}

Note 1: The partial link returned by "app_doc_link" can be appended to:
http{s}://{IP-ADDRESS}/sys{WORKSPACE}/{LANG}/{SKIN}/

For example:
https://example.com/sysworkflow/en/neoclassic/

Note 2: A new security restriction prevents files from being downloaded without verifying that the logged-in user has rights to access the file, which isn't possible with the provided link. To allow download of files, add this line to the env.ini file: disable_download_documents_session_validation = 1

PHP Example

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

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

$caseId    = '14822205755e60222b0ca68094757835';
$caseDocId = '55757090055e4d643040a15027216052';

$url = "/api/1.0/workflow/cases/$caseId/output-document/$caseDocId";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   $link = "http://localhost:301/sysworkflow/en/neoclassic/" . $oRet->response->app_doc_link;

   //Download binary PDF file:
   $contents = file_get_contents($link);
   ob_start();
   header('Content-Type: application/pdf');
   header('Content-disposition: attachment; filename="' . $oRet->response->app_doc_filename . '"');
   echo $contents;
   ob_flush();

   //save file to the local harddrive
   file_put_contents('/home/foo/reports/' . $oRet->response->app_doc_filename, $contents) or
      die("Error: Unable to save file to harddrive:\n" . $oRet->response->app_doc_filename);
}

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

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

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

Permission:

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

Structure:

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

URL Parameters:

Name Description Example
workspace Workspace name. https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288
app_uid Unique ID of the case. https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288
del_index The delegation index, which counts the assignment of tasks to users, where the first assigned task is 1, the second is 2, etc. https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288
out_doc_uid The unique ID of the Output Document, which can be obtained by clicking on the Show ID button when viewing the list of Output Documents. https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288

POST fields:

None.

Result:

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

Example:

Response

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

{
   "app_doc_uid":         "30145523653271ddb4b7936097604166",
   "app_doc_filename":    "sample.pdf",
   "doc_uid":             "67423604152fa88941c44d5089456849",
   "app_doc_version":     1,
   "app_doc_create_date": "2014-03-17 12:07:55",
   "app_doc_create_user": "Administrator (admin)",
   "app_doc_type":        "OUTPUT BOTH",
   "app_doc_index":       2,
   "app_doc_link":        "cases/cases_ShowOutputDocument?a=30145523653271ddb4b7936097604166&v=1&ext=pdf&random=996247643"
}

The Output Document must be a step in the task indicated by the delegation index number and the logged-in REST user must be assigned to that task in the specified case. Otherwise, this endpoint will return the following error object:

{ "error": { "code": 400, "message": "Bad Request: The user with \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\" not have permissions to perform this action." } }

Note: In order to be able to download files outside ProcessMaker's interface in version 3.1.3 or later, either the user has to have an open login session in ProcessMaker or the disable_download_documents_session_validation setting has to be enabled in the env.ini file.

PHP Example

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

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

$caseId   = '14822205755e60222b0ca68094757835';
$delIndex = 2;
$outDocId = '39558947555df747738bc05034476159';
$url = "/api/1.0/workflow/cases/$caseId/$delIndex/output-document/$outDocId";
$oRet = pmRestRequest("POST", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   $link = 'http://' .$_SERVER['SERVER_NAME']. '/sysworkflow/en/neoclassic/' . $oRet->response->app_doc_link;
   //Download binary PDF file:
   $handle = fopen($link, "rb") or die("Error: Unable to open file:\n$link");
   $contents = stream_get_contents($handle) or die("Error: Unable to get file:\n$link");
   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
}

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

Remove a generated Output Document from a case.

Permission:

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

Structure:

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

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

URL Parameters:

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

Result:

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

Example:

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "silvia", "sample");

$caseId = '14822205755e60222b0ca68094757835';
$caseDocId = '62062886955e6022776e618009059390';
$url = "/api/1.0/workflow/cases/$caseId/output-document/$caseDocId";

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

if ($oRet->status == 200) {
   print "Output Document deleted.\n";
}