Web service API

How to use PageSeeder's Web service API

<comment>

Summary

The XML representation of a single comment.

The <comment> element provides information about a single comment.

There are several variations depending on whether the following are included:

  • text/actual content
  • HTML content
  • attachments

The comment child elements are returned in the following order (attributes and text content omitted):

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

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

Note

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 the current value for the task or workflow unless the comment is the last comment. A change from the previous comment indicate 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:

  • "Comment"
  • "Workflow"
  • "Archive" if the comment is archived
  • "File Attachment"

Note

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 should 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 provide the priority of the task or work 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.

Warning!

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 provide the status of the task or work 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 via the service API.

Examples

Simple comment

A simple 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 to the snow?
   </content>
   <context>
      <group id="99" name="example-general" description="General discussions at Example" owner="Example" access="member" common="false"/>
   </context>
</comment>

Simple 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

See also

Created on , last edited on