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,descdesc /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 " %20and "?" 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. The date displays in the UTC time zone. "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.
$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 \nto insert a new line in the text.send_mail Optional. Set to 1to send an email with the content of the case note in its body to all the participants in the case. The default is0, 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:
$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.";
}
