find comments public
| API Support | Available since | Last updated | Output |
|---|---|---|---|
| 5.2102 | 6.0000 | xml, json |
Description
This service returns a list of public comments using parameters to filter the results. The list of groups specified must be public groups. The most recent comments are returned first.
This service performs a search directly on the database and returns the corresponding comment instances as XML. Alternatively, an index search could provide better performance with the caveat that there can be a slight delay between a comment creation or update and its availability in the index.
Parameters
| Name | Description | Required | Type | Default value |
|---|---|---|---|---|
| groups | Comma-separated list of group names the comments MUST belong to | yes | strings | |
| archived | If true, include archived comments | no | boolean | false |
| attachments | The attachments to include, can be none, context or all | no | enum | all |
| author | The ID of the comments author | no | long | |
| contents | The contents to include, can be none or all | no | enum | all |
| context | Only return comments in this context, can be group, uri, all | no | enum | all |
| createdafter | The date time after which the comments were created e.g. 2010-10-25T12:26:00+10:00 | no | datetime | |
| createdbefore | The date time before which the comments were created e.g. 2011-08-25T10:20:00-04:00 | no | datetime | |
| emails | The email addresses to include, can be none or all (all for administrators only) | no | boolean | none |
| labels | Comma-separated list of label values – comment MUST have all (not recommended for filtering large data sets) | no | string | |
| moderated | If true, include moderated (not accepted) comments | no | boolean | false |
| page | The page to load | no | long | 1 |
| pagesize | The number of results per page | no | long | 1000 |
| paths | The context URI paths for the comments – MUST be URL encoded (comma-separated list with optional * suffix) | no | paths | |
| position | If first, only the first (root) comment in a discussion is returned (might be faster when using paths) | no | string | any |
| returngroups | The groups to return in the output, can be none, specified | no | enum | none or if multiple groups specified |
| statuses | Comma-separated list of statuses | no | status | |
| title | The title the comments MUST have (optional wildcard * suffix, use ** to escape) | no | string | |
| type | The type the comments MUST have (optional wildcard * suffix, use ** to escape) | no | string | |
| types | Comma-separated list of types the comment can have (empty string means no type) | no | strings |
Including all attachments, contents and returned groups can incur a performance penalty when loading large discussions. Some of the following parameters allow developers to control whether they are loaded and returned or not.
attachments
This parameter determines whether attachments are included in the response. Possible options are:
none– No attachment is to be includedcontext– Only include the context document or URLall– Include all attachments
The context is usually the same for all comments within the same discussion.
contents
This parameter determines whether the contents of the individual comments are included in the response.
Possible options are:
none– The content is not to be loadedall– Load the content of all comments
There is usually only one content of type text/plain when comments are entered through the user interface. However, it is possible to have contents with different media type when the comment has been created through the API.
returngroups
This parameter determines whether to return groups on to which the comments were posted.
Returning the group might be unnecessary if the client knows the group and the comments aren't shared.
Possible options are:
none– The groups are not to be loadedspecified– Load the content of all comments
statuses
A comma-separated list of task status or document status values.
Permission
This service can only list comments based on the groups that user have access. If the group is public, anyone can access it.
If the parameter emails is set to all, the permission is restricted to administrator only.
Response
This service returns a list of <comment> elements wrapped in a <comments> element as in the following example.
<comments>
<comment id="234"
contentrole="File Attachment"
created="2012-03-08T12:34:00+10:00">
<title>My thread</title>
<content type="text/plain">Some text</content>
<attachment>
<uri id="189">...</uri>
</attachment>
<attachment fragment="5">
<uri id="289">...</uri>
</attachment>
<context>
<group id="3" name="acme-test" />
</context>
</comment>
<comment id="567">...
<context fragment="2">
<uri id="789">...</uri>
</context>
</comment>
</comments>
By default, all attachments and contents are included.
Effect of attachments parameter
If attachments is none:
<comments>
<comment id="33"
discussionid="33"
contentrole="Comment"
created="2017-02-15T10:17:37+11:00">
<title>Welcome</title>
<author> ... </author>
<content type="text/plain"> ... </content>
</comment>
</comments>
If attachments is context, only the <context> element is included:
<comments>
<comment id="33"
discussionid="33"
contentrole="Comment"
created="2017-02-15T10:17:37+11:00">
<title>Welcome</title>
<author> ... </author>
<!-- Context is included -->
<content type="text/plain"> ... </content>
<context>
<uri> ... </uri>
</context>
</comment>
...
</comments>
If attachments is all, both the attachments to the comment using the <attachment> element and the context are included:
<comments>
<comment id="33"
discussionid="33"
contentrole="Comment"
created="2017-02-15T10:17:37+11:00">
<title>Welcome</title>
<author> ... </author>
<content type="text/plain"> ... </content>
<!-- File attachments -->
<attachment>
<uri> ... </uri>
</attachment>
<attachment>
<uri> ... </uri>
</attachment>
<!-- Context of the comment -->
<context>
<uri> ... </uri>
</context>
</comment>
...
</comments>
Effect of contents parameter
If contents is none, the comment content is not included:
<comments>
<comment id="33"
discussionid="33"
contentrole="Comment"
created="2017-02-15T10:17:37+11:00">
<title>Welcome</title>
<author> ... </author>
<!-- Content is omitted-->
<attachment>
<uri> ... </uri>
</attachment>
<attachment>
<uri> ... </uri>
</attachment>
<context>
<uri> ... </uri>
</context>
</comment>
...
</comments>
Effect of returngroups parameter
If returngroups is none, the comment does not include the <group> element. This is the default behavior when a comment is posted on a single group.
<comments>
<comment id="33"
discussionid="33"
contentrole="Comment"
created="2017-02-15T10:17:37+11:00">
<title>Welcome</title>
<author> ... </author>
<content> ... </content>
<context>
<uri> ... </uri>
</context>
<!-- Group is omitted -->
</comment>
...
</comments>
If returngroups is specified, the comment include the groups that the comment was posted on. This is the default behavior when a comment belongs to multiple groups:
<comments>
<comment id="33"
discussionid="33"
contentrole="Comment"
created="2017-02-15T10:17:37+11:00" >
<title>Welcome</title>
<author> ... </author>
<content> ... </content>
<context>
<uri> ... </uri>
</context>
<!-- Group is included -->
<group id="123" name="acme-tomato"/>
</comment>
...
</comments>
Error Handling
| Code | Cause / Description |
|---|---|
| 0x1306 | The Group is invalid or not accessible |
| 0x1312 | The createdafter or createdbefore date is invalid |
| 0x1313 | The author is invalid |