Searching the Help
To search for information in the Help, type a word or phrase in the Search box. When you enter a group of words, OR is inferred. You can use Boolean operators to refine your search.
Results returned are case insensitive. However, results ranking takes case into account and assigns higher scores to case matches. Therefore, a search for "cats" followed by a search for "Cats" would return the same number of Help topics, but the order in which the topics are listed would be different.
Search for | Example | Results |
---|---|---|
A single word | cat
|
Topics that contain the word "cat". You will also find its grammatical variations, such as "cats". |
A phrase. You can specify that the search results contain a specific phrase. |
"cat food" (quotation marks) |
Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase. |
Search for | Operator | Example |
---|---|---|
Two or more words in the same topic |
|
|
Either word in a topic |
|
|
Topics that do not contain a specific word or phrase |
|
|
Topics that contain one string and do not contain another | ^ (caret) |
cat ^ mouse
|
A combination of search types | ( ) parentheses |
|
- Developer reference
- Overview of the REST API
- Connect to the REST API
- Authentication endpoint service
- Single record APIs
- Record bulk update and collection APIs
- REST API queries
- REST API collection query protocol
- Analytics REST API
- Manage Persons API
- BI Integration API
- Case Exchange REST API
- Encryption domain API
- Comments API
- REST API use-case scenario - import REST API
Comments API
The following APIs are available for use in connection with comments to records:
Add single comment
Enter the following POST request URI:
https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>
where EntityType specifies the record type and EntityId specifies the required record.
An example of a POST request JSON is:
{ "IsSystem": false, "Body": "This is a new comment!", "AttachmentIds": [], "PrivacyType": "PUBLIC", //INTERNAL,PUBLIC,AGENTPUBLIC "Submitter": { "UserId": 10016 }, "ActualInterface": "API", //SAW,ESS,EMAIL,API,SYSTEM "CommentFrom": "User", //System,Agent,User,Vendor,ExternalServiceDesk, SocialUser "CommentTo": "", //Agent,User,Vendor,ExternalServiceDesk,Stakeholder "FunctionalPurpose": "StatusUpdate", //StatusUpdate,RequestMoreInformation, ProvideInformation,EndUserComment,Diagnosis,Resolution,ResolutionActivity, FollowUp "Media": "Unknown", //Unknown,UI,Email,Phone,Fax,InstantMessage, InternalChat "PersonParticipant": "", "CompanyVendor": "", "Group": "" }
The response includes the comment entered in the Body property along with a generated comment ID:
{ "IsSystem": false, "Body": "This is a new comment!", "PrivacyType": "PUBLIC", "Submitter": { "UserId": "10015" }, "ActualInterface": "API", "CommentFrom": "User", "FunctionalPurpose": "StatusUpdate", "Media": "Unknown", "PersonParticipant": "", "CompanyVendor": "", "Group": "", "CreateTime": 1452751016929, "UpdateTime": 0, "Id": "bae223e7-a1e6-4f73-90c3-fd92345c4d7e" }
The comment is posted to the specified record.
Add multiple comments
Enter the following POST request URI:
https://<serverAddress>/rest/<tenant-id>/collaboration/comments/bulk/<EntityType>/<EntityId>
where EntityType specifies the record type and EntityId specifies the required record.
A POST request should include an array of JSONs such as this:
{ "IsSystem": false, "Body": "This is a new comment!", "AttachmentIds": [], "PrivacyType": "PUBLIC", //INTERNAL,PUBLIC,AGENTPUBLIC "Submitter": { "UserId": 10016 }, "ActualInterface": "API", //SAW,ESS,EMAIL,API,SYSTEM "CommentFrom": "User", //System,Agent,User,Vendor,ExternalServiceDesk, SocialUser "CommentTo": "", //Agent,User,Vendor,ExternalServiceDesk,Stakeholder "FunctionalPurpose": "StatusUpdate", //StatusUpdate,RequestMoreInformation, ProvideInformation,EndUserComment,Diagnosis,Resolution,ResolutionActivity, FollowUp "Media": "Unknown", //Unknown,UI,Email,Phone,Fax,InstantMessage, InternalChat "PersonParticipant": "", "CompanyVendor": "", "Group": "" }
No data is returned for this request.
The comments are posted to the specified record.
Get comments
Enter the following GET request URI:
https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>
where EntityType specifies the record type and EntityId specifies the required record.
There is an optional parameter PrivacyType, which can be used to specify the comment type. For example, the following request retrieves all public comments:
rest/<tenant>/collaboration/comments/<EntityType>/<EntityId>?PrivacyType=PUBLIC
The response is an array of comments posted to the specified record:
[{ "IsSystem": false, "Body": "This is a new comment2!", "AttachmentIds": [], "PrivacyType": "PUBLIC", "Submitter": { "UserId": 10016 }, "ActualInterface": "API", "CommentFrom": "User", "CommentTo": "", "FunctionalPurpose": "StatusUpdate", "Media": "Unknown", "PersonParticipant": "", "CompanyVendor": "", "Group": "" }, { "IsSystem": false, "Body": "This is a new comment3!", "AttachmentIds": [], "PrivacyType": "PUBLIC", "Submitter": { "UserId": 10016 }, "ActualInterface": "API", "CommentFrom": "User", "CommentTo": "", "FunctionalPurpose": "StatusUpdate", "Media": "Unknown", "PersonParticipant": "", "CompanyVendor": "", "Group": "" }, … ]
Get comments with anonymous agent info
Enter the following GET request URI:
https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/WithAnonymousAgentInfo
where EntityType specifies the record type and EntityId specifies the required record.
There is an optional parameter PrivacyType, which can be used to specify the comment type.
If the Enable agent anonymity setting is set to On for the tenant and the user running the API does not have login authorization, then when the privacy type is AGENTPUBLIC, the submitter's ID is hidden. A false ID of -9999 is returned instead.
The response is an array of comments posted to the specified record (see the example under Get comments).
Get single comment
Enter the following GET request URI:
https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/<CommentId>
where EntityType specifies the record type and EntityId specifies the required record. CommentId is the ID of the specific comment.
There are no parameters for this URI.
The response includes the specific comment requested:
{ "IsSystem": false, "Body": "This is a new comment!", "PrivacyType": "PUBLIC", "Submitter": { "UserId": "10016" }, "ActualInterface": "API", "CommentFrom": "User", "FunctionalPurpose": "StatusUpdate", "Media": "Unknown", "PersonParticipant": "", "CompanyVendor": "", "Group": "", "CreateTime": 1452749848614, "UpdateTime": 0, "Id": "92334628-6e8e-46d6-b799-8948e4cd0f89" }
Update comment
Enter the following PUT request URI:
https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/<CommentId>
where EntityType specifies the record type and EntityId specifies the required record.
An example of a PUT request JSON is:
{ "IsSystem": false, "Body": "Updated body!", "AttachmentIds": [], "PrivacyType": "PUBLIC", //INTERNAL,PUBLIC,AGENTPUBLIC "Submitter": { "UserId": 10016 }, "ActualInterface": "API", //SAW,ESS,EMAIL,API,SYSTEM "CommentFrom": "User", //System,Agent,User,Vendor,ExternalServiceDesk,SocialUser "CommentTo": "", //Agent,User,Vendor,ExternalServiceDesk,Stakeholder "FunctionalPurpose": "StatusUpdate", //StatusUpdate,RequestMoreInformation, ProvideInformation,EndUserComment,Diagnosis,Resolution,ResolutionActivity,FollowUp "Media": "Unknown", //Unknown,UI,Email,Phone,Fax,InstantMessage,InternalChat "PersonParticipant": "", "CompanyVendor": "", "Group": "", “CreateTime”: 1451360022122, “Id”: “abdec6fb-0bac-4a7b-a533-6735cabf9c88” }
The response includes the updated comment:
{ "IsSystem": false, "Body": "Updated body!", "PrivacyType": "PUBLIC", "Submitter": { "UserId": "10016" }, "UpdatedBy": { "UserId": "10015" }, "ActualInterface": "API", "CommentFrom": "User", "FunctionalPurpose": "StatusUpdate", "Media": "Unknown", "PersonParticipant": "", "CompanyVendor": "", "Group": "", "CreateTime": 1452749848614, "UpdateTime": 1452751819091, "Id": "92334628-6e8e-46d6-b799-8948e4cd0f89" }
Note To update existing comments of a record, you must have Comments permission for the relevant record type.
Delete comment
Enter the following DELETE request URI:
https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/<CommentId>
where EntityType specifies the record type and EntityId specifies the required record.
No data is returned for this request.
Note To delete existing comments of a record, you must have Comments permission for the relevant record type.
Related topics