Cases Notes

The following endpoints are used to manipulate case notes:

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

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

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

Parameters:

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

Result:

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

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

For example:

[
  {
    "app_uid":      "17969179752e27c4b3027c3006962937",
    "usr_uid":      "00000000000000000000000000000001",
    "note_date":    "2015-06-01 12:12:12",
    "note_content": "This case needs more review before approval is given."
  },
  {
    "app_uid":      "17969179752e27c4b3027c3006962937",
    "usr_uid":      "39558947555df747738bc05034476159",
    "note_date":    "2015-06-01 16:12:12",
    "note_content": "Please check the services rendered in this contract."
  }
]

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

{
   "error": {
      "code":    400,
      "message": "Bad Request: You do not have permission to access the cases notes"
   }
}

PHP Example:

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

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

$caseId = '78014942855e4a66cb0f531062309584';
$url = "/api/1.0/workflow/cases/$caseId/notes";

$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);
if ($oRet->status == 200) {

   //get users to display their full names for each note:
   $url = "/api/1.0/workflow/users";
   $aUsers = pmRestRequest("GET", $url, null, $oToken->access_token);

   $aUserInfo = array(); //empty array to hold info about users.
   foreach ($aUsers as $oUser)
      $aUserInfo[$oUser->usr_uid] = "{$oUser->usr_firstname} {$oUser->usr_lastname} ({$oUser->usr_username})";

   foreach ($oRet->response as $oNote) {
      $sUser = $aUsers[$oNote->usr_uid];
      print "<p>{$oNote->note_content}<br>
         "
<small>Posted by $sUser on {$oNote->note_date}</small></p>";
   }
}

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

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

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

URL Parameters:

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

Result:

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

{
   "total":     2,
   "start":     0,
   "limit":     25,
   "sort":      "APP_NOTES.NOTE_DATE",
   "dir":       "DESC",
   "usr_uid":   "",
   "date_to":   "",
   "date_from": "",
   "search":    "",
   "data":
   [
      {
         "app_uid":      "115968518533473068ad299078535175",
         "usr_uid":      "39558947555df747738bc05034476159",
         "note_date":    "2015-03-28 11:10:51",
         "note_content": "Is the purchase price too high for office furniture?"
      },
      {
         "app_uid":      "115968518533473068ad299078535175",
         "usr_uid":      "00000000000000000000000000000001",
         "note_date":    "2015-03-28 17:19:45",
         "note_content": "I have approved the purchase request, despite the high price."
      }
   ]
}

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

{
   "error": {
      "code":    400,
      "message": "Bad Request: You do not have permission to access the cases notes"
   }
}

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

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

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}/note

URL Parameters:

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

POST Fields:

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

Result:

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

{
   error: {
      "code":    400,
      "message": "Bad Request: You do not have permission to access the cases notes"
   }
}

PHP Example:

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

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

$caseId = '57793680455e7a4326b71f5064060314';
$aVars = array(
   'note_content' => "Please review the Invoice totals.\nThey look too low to cover the costs",
   'send_mail'    => 1
);

$url = "/api/1.0/workflow/cases/$caseId/note";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   print "Case note added.";
}