<comment>

Summary

Provides an XML representation of a single comment, including the following:

Text/actual content.
HTML content.
Attachments.

The service API returns the child elements* of <comment> in the following order:

<comment>
  <title />
  <labels />
  <author />
  <modifiedby />
  <assignedto />
  <properties />
  <content />
  <context />
  <attachment />
  <group />
</comment>

*@attributes and content omitted

Usage context

Permitted content	`<assignedto> <attachment> <author> <content> <context> <group> <labels> <modifiedby> <properties> <title>`
Permitted parent	`<attachedto> <discussion> <comment-archive> <comment-creation> <comment-modification> <comment-unarchive> <comments> <task> <workflow-creation> <workflow>`

Attributes

This element includes the following attributes:

Name	Type	Required	Description
contentrole	`enum`	no	The content role for the comment
created	`xs:dateTime`	no	When the comment was created
discussionid	`xs:long`	no	The ID of the discussion in PageSeeder
draft	`xs:boolean`	no	Whether the comment is a draft
due	`xs:dateTime`	no	When the task is due when comment was made
id	`xs:long`	yes	The ID of the comment in PageSeeder
moderated	`xs:boolean`	no	Whether the comment is being moderated
priority	`xs:string`	no	Priority of a task when comment was made
properties	`xs:string`	no	Custom properties (excluding labels)
status	`xs:string`	no	Status of a task when comment was made
type	`xs:string`	no	Type of comment

The @due, @priority and @status attributes are task or workflow attributes. Their value reflects respectively the due date, priority and status at the time the comment was made, rather than the current value for the task or workflow, unless the comment is the last comment. A change from the previous comment indicates a change in the task or workflow.

These values can be edited if the comment itself is edited.

`@contentrole`

This attribute defines the kind of comment being made based on PageSeeder predefined types. Its value can be the following:

Comment
Workflow
Archive if the comment is archived
File Attachment

Custom comment types are returned in the @type attribute.

`@created`

This optional attribute indicates when the comment was created. Once this value is set, it is immutable.

`@discussionid`

This optional attribute indicates the task or discussion identifier that the comment is part of.

`@draft`

A boolean attribute indicating whether the comment is a draft. This attribute is only returned if the value is true.

A comment is a draft until it has been posted to PageSeeder. After a comment has been posted, it can only be modified.

`@due` (task/workflow only)

This optional attribute provides the due date and time for a task or a workflow when the comment was made.

`@id`

The PageSeeder database identifier for the comment. It is always an immutable positive long value that is unique on a specific PageSeeder server within the set all comments.

`@moderated`

A boolean attribute indicating whether the comment is being moderated. In other words, it indicates that the Moderator has not accepted the comment yet. Generally, comments in that state are not be displayed to end-users except for the Moderator.

This attribute is only returned if the value is true.

`@priority` (task/workflow only)

This optional attribute provides the priority of the task or workflow when the comment was made. The possible values for the priority are defined in the group properties.

The default values are Low, Medium, High.

`@properties`

The unparsed properties as stored in the database if any.

This attribute is useful to understand how properties are stored, however, they follow specific parsing rule, and it is often more convenient to use the <properties> element which provides the property list already parsed.

`@status` (task/workflow only)

This optional attribute provides the status of the task or workflow when the comment was made. The possible values for the status are defined in the group properties.

The default values are Open, Resolved, Closed.

`@type`

A custom type that is given to the comment. The comment type can only be specified through the service API.

Examples

Basic comment

A baisc comment to group with a label.

<comment id="1234"
         discussionid="1234"
         contentrole="Comment" 
         created="2017-01-05T15:23:03+11:00">
  <title>Ski season</title>
  <labels>Feature</labels>
  <author id="66"
          firstname="Hugh"
          surname="Mungus"
          username="hmungus"
          status="activated">
    <fullname>Hugh Mungus</fullname>
  </author>
  <content type="text/plain">
       Hello everyone,

       Anyone interested in going skiing?
  </content>
  <context>
    <group id="99"
           name="example-general"
           description="General discussions at Example"
           owner="Example"
           access="member"
           common="false"/>
  </context>
</comment>

Comment for task

<comment id="616946"
         discussionid="616946"
         contentrole="Comment"
         created="2017-01-10T11:03:32+11:00"
         status="Open"
         priority="Medium">
  <title>Fix stuff</title>
  <author id="123"
          firstname="John"
          surname="Smith"
          username="jsmith"
          status="activated">
    <fullname>John Smith</fullname>
  </author>
  <assignedto id="123"
              firstname="John"
              surname="Smith" username="jsmith"
              status="activated"
              date="2017-01-10T11:03:32+11:00">
    <fullname>John Smith</fullname>
  </assignedto>
  <content type="text/plain">
        Something got broken,
        remember to fix it!
  </content>
  <context>
    <group id="724"
           name="example-stuff"
           description="Random stuff"
           owner="Example"
           access="member"
           common="false"/>
  </context>
</comment>

Typed comment with properties

<comment id="616351"
         discussionid="560264"
         contentrole="Comment"
         type="timesheet"
         created="2017-01-05T20:07:26+11:00"
         status="Open"
         priority="Medium"
         properties="date=2017-01-04|time=8.00|">
  <title>Documentation</title>
  <author id="123"
          firstname="John"
          surname="Smith"
          username="jsmith"
          status="activated">
    <fullname>John Smith</fullname>
  </author>
  <assignedto id="123"
              firstname="John"
              surname="Smith"
              username="jsmith"
              status="activated"
              date="2017-01-10T11:03:32+11:00">
    <fullname>John Smith</fullname>
  </assignedto>
  <properties> 
    <property name="date" value="2017-01-04"/>
        <property name="time" value="8.00"/>
  </properties>
  <content type="text/plain">Continue work on documentation
  </content>
  <context>
    <group id="724"
           name="example-stuff"
           description="Random stuff"
           owner="Example"
           access="member"
           common="false"/>
  </context> 
</comment>

Schema

XML Schema

<xs:element name="comment" type="comment"/>

<xs:complexType name="comment">
  <xs:sequence>
    <xs:element name="title"      type="comment-title"/>
    <xs:element name="labels"     type="label-list"/>
    <xs:element name="author"     type="author"      minOccurs="0"/>
    <xs:element name="modifiedby" type="modifiedby"  minOccurs="0"/>
    <xs:element name="assignedto" type="assignedto"  minOccurs="0"/>
    <xs:element name="properties" type="properties"  minOccurs="0"/>
    <xs:element name="content"    type="content"     minOccurs="0"
                maxOccurs="unbounded"/>
    <xs:element name="context"    type="context"     minOccurs="0"/>
    <xs:element name="attachment" type="attachment"  minOccurs="0"
                maxOccurs="unbounded"/>
    <xs:element name="group"      type="group-core"  minOccurs="0"
                maxOccurs="unbounded"/>
  </xs:sequence>
  <xs:attribute name="contentrole"  type="xs:string"/>
  <xs:attribute name="created"      type="xs:dateTime"/>
  <xs:attribute name="discussionid" type="id"/>
  <xs:attribute name="draft"        type="boolean"/>
  <xs:attribute name="due"          type="xs:dateTime"/>
  <xs:attribute name="id"           type="id"       use="required"/>
  <xs:attribute name="moderated"    type="boolean"/>
  <xs:attribute name="priority"     type="xs:string"/>
  <xs:attribute name="properties"   type="xs:string"/>
  <xs:attribute name="status"       type="xs:string"/>
  <xs:attribute name="type"         type="xs:string"/>
</xs:complexType>

<xs:simpleType name="comment-title">
  <xs:restriction base="xs:string">
    <xs:maxLength value="250"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="label-list">
  <xs:restriction base="xs:string">
    <xs:pattern value="[a-zA-Z0-9_\-,]*"/>
  </xs:restriction>
</xs:simpleType>

Relax Schema

element member {
   attribute contentrole   { text }?,
   attribute created       { xs:dateTime }?,
   attribute discussionid  { xs:long }?,
   attribute draft         { xs:boolean }?,
   attribute due           { xs:dateTime }?,
   attribute id            { xs:long },
   attribute moderated     { xs:boolean }?, 
   attribute priority      { text }?, 
   attribute properties    { text }?,
   attribute status        { text }?,
   attribute type          { text }?,
   element title { text }
   element labels { text }
   author?
   modifiedby?
   assignedto?
   properties?
   content*
   context?
   attachment*
   group*
}

Compatibility

No change since initial API release.

Created on 6 January 2017, last edited on 7 June 2024 at 18:15

Element reference

<comment>

Summary

Usage context

Attributes

@contentrole

@created

@discussionid

@draft

@due (task/workflow only)

@id

@moderated

@priority (task/workflow only)

@properties

@status (task/workflow only)

@type