Web service API

How to use PageSeeder's Web service API

<group>

Summary

The group XML output is used to represent PageSeeder groups in many contexts, including group memberships, comments and documents.

This element is used as a base for the <project> element as they share many attributes.

There are three representations minimal, basic and extended.

The minimal representation includes only @id and @name attributes. It is used only for comment/group elements.

The extended representation includes all the basic attributes plus additional attributes that further describe the group. It also includes the welcome message if there is one. The extended representation is only used by services where the additional information is useful.

Usage context

Permitted content<message>, <uri>
Permitted parent<context>,
<group-creation>,
<group-modification>,
<discussion>,
<membership>
,
<project>,
<share>,​
<subgroup>,​
​​​​<task>

Attributes

This element includes the following attributes.

NameTypeRequiredDescription
accessenumyesWho has access to the group
commonxs:booleanyesIf it is a common group
descriptionxs:stringyesA short description of the group (250)
idxs:longyes*The ID of the group in PageSeeder
ownerxs:stringyesThe owner of the group (100)
namexs:stringyes*The full name of the group (60)
relatedurlURLnoURL to a related Website (250)
titlexs:stringnoThe title for the group (100)

* the minimal representation only includes these attributes.

The extended representation provides additional attributes to expose more advanced configuration options of the group, the extended attributes are listed below.

NameTypeRequiredDescription
commentingenumyes*Who can post comments on group
defaultnotifyenumyes*Default notification for new group members
defaultroleenumyes*Default role for new group members
detailstypexs:stringnoType of membership details (150)
editurlsxs:booleanyes*Where URL core attributes can be edited
indexversionxs:integernoVersion of the current group index
moderationenumyes*What is moderated in the group
registrationenumyes*What kind of registration is available
templatexs:stringnoThe project template in use (60)
visibilityxs:stringnoWho can self-register (60)

* when the extended representation is used, these attributes are always included.

When generating the hierarchical representation of groups and projects, the <group> element may also include the attribute below.

NameTypeRequiredDescription
subgroupsxs:stringnoComma-separated list of subgroups

Unless specified otherwise, the value of the group attributes only changes if the group configuration is changed - this can only be done by a manager of the group or an administrator.

@access

The value of this attribute corresponds to the level of access to the content of the group.  The levels of access are:

  • "member" for groups which can only be accessed by their members;
  • or "public" for groups which can be accessed by anyone.

@commenting (extended)

The value of this attribute indicates who can post comments to the group:

  • "contributor" for groups that require its members to have at least the role of 'contributor' in order to be allowed to post a new comment;
  • "reviewer" for groups that require its members to have at least the role of 'reviewer' in order to be allowed to post a new comment;
  • or "public" for groups that allow anyone to post a new comment.

When a group allows public commenting, consider using moderation to prevent spam or abuse.

@common

This attribute indicates whether this group is a common group.

@defaultnotify (extended)

This attribute indicates which is the default notification setting assigned to new members of the group in case they don't specify it.

The value of this attribute will change if the group properties for the group are updated.

The possible values are "daily", "immediate" or "none".

@defaultrole (extended)

This attribute indicates which is the default notification setting assigned to new members of the group in case they don't specify it.

The possible values are "contributor" or "reviewer".

@description

The description of the group as defined in the group configuration. The description of the group does not exceed 250 characters.

@detailstype (extended)

This attribute provides the type of membership details recorded against members of the group as membership details fields. The actual value denotes the path to the local configuration file defined at the project level; it cannot exceed 150 characters.

@editurls (extended)

This boolean attribute indicates whether it is possible to edit the path, default title, description, and labels for URLs in this group.

Note

Since URLs are defined system-wide, when this value is set to true, edited URLs will potentially affect other groups.

@id (minimal)

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

This attribute can be used as a key for caching objects based on groups (and projects) in client applications.

@indexversion (extended)

A generated value providing information about the version of the index used for this group. This value is essentially used to compare against the current version to determine whether the index content requires re-indexing. It could also indicate that index fields on older content may be missing.

@moderation (extended)

This attribute indicates which comments are moderated in this group. The possible values are:

  • "reviewer" - all public comments and comments posted by reviewers are moderated;
  • "email" - all public comments, comments posted by reviewers and comments received by email are moderated;
  • "all" - all comments are moderated (except the moderator)

@owner

This attribute provides the name of the owner of the group. Groups with the same owner can share membership details under some condition.

It never exceeds 60 characters.

@name (minimal)

The canonical name of the group. This name is unique within PageSeeder and includes the name of its parent project.

In a production system, the name of a group rarely changes as it affects document URLs, group email addresses, and indexed content, this attribute is therefore often considered immutable in practice so that it can be used as a key for caching objects based on groups or projects.

@relatedurl

An optional attribute denoting a URL related to this group. This can be a Website using this group or where the content of this group is published.

The attribute value does not exceed 250 characters.

@registration (extended)

This attribute indicates what kind of self-registration is in place for this group, that is when a member elects to join a group.

The possible values are:

  • "confirmed" - they can join the group only after confirming their request by email;
  • "moderated" - their membership request needs to be confirmed by the moderator;
  • "normal" - they can join the group immediately.

@subgroups (special)

This optional attribute is only provided in the context of a hierarchical representation of groups and projects and only applies to the <group> element. It provides the list of subgroups that are included in the group.

@template (extended)

This attribute indicates where the files the files used for custom emails, document types, and other project-level configuration items are defined.

  • For a group, the template is normally the name of the parent project.
  • For a project, it is the same name as the project.

@title

An optional title for the group to display as an alternative to the name. Its value does not exceed 100 characters.

@visibility (extended)

This attribute is the name of a group that a member must belong to in order to be abe to self-register to this group. It can also be set to "public" in which case anyone can see that group and request to join. The value does not exceed 60 characters.

Examples

Common minimal

A group with minimal attributes.

<group   id="123" 
       name="dev-example" />

Common basic

A group with basic attributes.

<group   id="123" 
       name="dev-example"
description="The example development group" 
      owner="Example Corp" 
     access="member" 
     common="false" />

Common extended

A group with extended attributes.

<group      id="123" 
          name="dev-example" 
   description="The example development group" 
         owner="Example Corp" 
        access="member"
        common="false" 
    visibility="dev" 
      editurls="false" 
    commenting="reviewer" 
    moderation="email" 
  registration="normal" 
   defaultrole="reviewer"
 defaultnotify="immediate" 
  indexversion="3300">
  <message>Hello and welcome to the development group!</message>
</group>

 

Schema

XML Schema

Minimal group
<xs:element name="group" type="group-minimal"/>

<xs:complexType name="group-minimal">
  <xs:attribute name="id"            type="id" use="required"/>
  <xs:attribute name="name"          type="group-name" use="required"/>
</xs:complexType>
Basic group
<xs:element name="group" type="group-basic"/>

<xs:complexType name="group-basic">
  <xs:sequence>
    <xs:element name="message" type="xs:string"/>
  </xs:sequence>
  <xs:attribute name="access"        type="group-access" use="required"/>
  <xs:attribute name="common"        type="boolean" use="required"/>
  <xs:attribute name="description"   type="group-description" use="required"/>
  <xs:attribute name="id"            type="id" use="required"/>
  <xs:attribute name="owner"         type="group-owner" use="required"/>
  <xs:attribute name="name"          type="group-name" use="required"/>
  <xs:attribute name="relatedurl"    type="group-relatedurl"/>
  <xs:attribute name="subgroups"     type="xs:string"/>
  <xs:attribute name="title"         type="group-title"/>
</xs:complexType>
Extended group
<xs:element name="group" type="group-extended"/>

<xs:complexType name="group-extended">
  <xs:complexContent>
    <xs:extension base="group-basic">
      <xs:attribute name="defaultnotify" type="group-notify"/>
      <xs:attribute name="defaultrole"   type="group-defaultrole"/>
      <xs:attribute name="detailstype"   type="group-detailstype"/>
      <xs:attribute name="editurls"      type="boolean"/>
      <xs:attribute name="indexversion"  type="xs:positiveInteger"/>
      <xs:attribute name="moderation"    type="group-moderation"/>
      <xs:attribute name="registration"  type="group-registration"/>
      <xs:attribute name="template"      type="group-template"/>
      <xs:attribute name="visibility"    type="group-visibility"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>
Attributes types
<xs:simpleType name="group-access">
  <xs:restriction base="xs:string">
    <xs:enumeration value="member" />
    <xs:enumeration value="public" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="group-notify">
  <xs:restriction base="xs:string">
    <xs:enumeration value="daily" />
    <xs:enumeration value="immediate" />
    <xs:enumeration value="none" />
    <xs:enumeration value="weekly" />
    <xs:enumeration value="limited" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="group-defaultrole">
  <xs:restriction base="xs:string">
    <xs:enumeration value="contributor" />
    <xs:enumeration value="reviewer" />
  </xs:restriction>
</xs:simpleType>

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

<xs:simpleType name="group-detailstype">
  <xs:restriction base="xs:string">
    <xs:maxLength value="150"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="group-moderation">
  <xs:restriction base="xs:string">
    <xs:enumeration value="reviewer" />
    <xs:enumeration value="email" />
    <xs:enumeration value="all" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="group-owner">
  <xs:restriction base="xs:string">
    <xs:maxLength value="60"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="group-name">
  <xs:restriction base="xs:string">
    <xs:maxLength value="60"/>
  </xs:restriction>
</xs:simpleType>

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

<xs:simpleType name="group-registration">
  <xs:restriction base="xs:string">
    <xs:enumeration value="confirmed" />
    <xs:enumeration value="moderated" />
    <xs:enumeration value="normal" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="group-template">
  <xs:restriction base="xs:string">
    <xs:maxLength value="60"/>
  </xs:restriction>
</xs:simpleType>

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

<xs:simpleType name="group-visibility">
  <xs:restriction base="xs:string">
    <xs:maxLength value="60"/>
  </xs:restriction>
</xs:simpleType>
Relax Schema
element group {
   attribute access        { "member" | "public"},
   attribute commenting    { "contributor" | "reviewer" | "public" }?,
   attribute common        { xs:boolean },
   attribute defaultnotify { "daily" | "immediate" | "none" }?,
   attribute defaultnotify { "contributor" | "reviewer" }?,
   attribute description   { text { maxLength = "250"}},
   attribute detailstype   { text { maxLength = "150"}}?,
   attribute editurls      { xs:boolean }?,
   attribute id            { xs:long },
   attribute indexversion  { xs:int }?,
   attribute moderation    { "reviewer" | "email" | "all" }?,
   attribute owner         { text { maxLength = "60"}},
   attribute name          { text { maxLength = "60"}},
   attribute relatedurl    { text { maxLength = "250"}}?,
   attribute registration  { "confirmed" | "moderated" | "normal" }?,
   attribute subgroups     { text },
   attribute template      { text { maxLength = "60"}}?,
   attribute title         { text { maxLength = "100"}}?,
   attribute visibility    { text { maxLength = "60"}}?,
   element message { text }?
}

Compatibility

See also

Created on , last edited on