Skip to main content

 Element reference

Service API elements from <alias> to <workflow>

<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:

NameTypeRequiredDescription
contentroleenumnoThe content role for the comment
createdxs:dateTimenoWhen the comment was created
discussionidxs:longnoThe ID of the discussion in PageSeeder
draftxs:booleannoWhether the comment is a draft
duexs:dateTimenoWhen the task is due when comment was made
idxs:longyesThe ID of the comment in PageSeeder
moderatedxs:booleannoWhether the comment is being moderated
priorityxs:stringnoPriority of a task when comment was made
propertiesxs:stringnoCustom properties (excluding labels)
statusxs:stringnoStatus of a task when comment was made
typexs:stringnoType 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 , last edited on