<group>

Summary

XML output to represent many contexts of a group including memberships, comments and documents.

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

The <group> element has three representations:

minimal – includes only @id and @name attributes. It is used only for comment/group elements.
basic – see table following.
extended – includes all basic attributes plus additional attributes that further describe the group. It also includes the welcome message if one exists. 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

The Basic Representation of <group> includes the following attributes:

Name	Type	Required	Description
access	`enum`	yes	Who has access to the group
common	`xs:boolean`	yes	If it is a common group (deprecated)
description	`xs:string`	yes	A short description of the group (250)
id	`xs:long`	yes*	The ID of the group in PageSeeder
owner	`xs:string`	yes	The owner of the group (100)
name	`xs:string`	yes*	The full name of the group (60)
relatedurl	`URL`	no	URL to a related Website (250)
subgroups	`xs:string`	no	Some services add this comma-separated list of subgroups to show that the current member belongs to this group through these
title	`xs:string`	no	The title for the group (100)

* the minimal representation only includes these attributes.

The Extended Representation of <group> exposes more advanced configuration options of the group through the following attributes:

Name	Type	Required	Description
commenting	`enum`	yes^*	Who can post comments on group
defaultnotify	`enum`	yes^*	Default notification for new group members
defaultrole	`enum`	yes^*	Default role for new group members
detailstype	`xs:string`	no	Type of membership details (150)
editurls	`xs:boolean`	yes^*	Where URL core attributes can be edited
indexversion	`xs:integer`	no	Version of the current group index
moderation	`enum`	yes^*	What is moderated in the group
registration	`enum`	yes^*	What kind of registration is available
template	`xs:string`	no	The project template in use (60)
visibility	`xs:string`	no	Who can self-register (60)

* these attributes are always included in the extended representation.

Unless specified otherwise, the @attribute values of <group> change only when the group configuration is changed – only a manager of the group or an administrator can make such a change.

`@access`

This corresponds to the level of access to the content of the group, valid values for @access are the following:

member – where groups are only accessible by members; or
public – for groups accessible by people that are not members (see public group).

`@commenting` ^{(extended representation)}

This indicates who can post comments to the group, valid attribute values are the following:

contributor – where posting comments is limited to members with a role of contributor, or higher.
reviewer – where posting comments is limited to members with a role of reviewer, or higher; or
public – where comments can be posted by someone that is not a member of the group.

Note that “public” in PageSeeder does not necessarily mean the same thing as the conventional term “public” or “general public”.

To minimize disruptions due to spam or abuse, consider using moderation for groups that allow public comments.

`@common`(deprecated)

Indicates whether the group is a Common group (obsolete).

`@defaultnotify` ^{(extended representation)}

Is the default notification setting assigned to new members of the group unless they specify otherwise. The default value changes if the group properties are updated.

Possible values are daily, immediate or none.

`@defaultrole` ^{(extended representation)}

Is the default role assigned to new members of the group. Possible values are contributor or reviewer.

`@description`

A plain text description of the group created through the group configuration. The content of this field cannot exceed 250 characters.

`@detailstype` ^{(extended representation)}

Provides the type of membership details attached to 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 representation)}

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

Since URLs are defined system-wide, when the value of this attribute is set to true, edits can affect the content of other groups.

`@id` ^{(minimal representation)}

The PageSeeder database identifier for the group.

Always immutable, the ID is a positive long value that is unique within the set of all groups and projects on any PageSeeder server.

Client applications can use this value as a key for caching objects based on groups and projects.

`@indexversion` ^{(extended representation)}

A generated value identifying the index version for a group. After a server has been updated, this value is used to check whether the group requires re-indexing or whether index fields on older content might be missing.

`@moderation` ^{(extended representation)}

Flags which comments are moderated, the possible values are the following:

none – no comments are moderated (this is only when the group has no moderator).
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 comments posted by the moderator.

`@owner`

Provides the name of the owner of the group. Groups with the same owner can share membership details under some conditions.

The value of this attribute cannot exceed 60 characters.

`@name` ^{(minimal representation)}

The canonical name of the group. It is unique for each PageSeeder server and includes the name of its parent project.

Once in production, any change to the group name affects document URLs, group email addresses, and the content of the index. So, although it is not immutable, the stability of the group name means this value can be used as an easily recognised key for caching objects based on groups or projects.

`@relatedurl`

Identifies the base URL of a website related to the group in some manner. The value cannot exceed 250 characters.

`@registration` ^{(extended representation)}

Indicates whether self-registration is available for this group. If it is, the options for a member to join the group are as follows:

confirmed – a request to join the group must be confirmed by email.
moderated – a request to join the group must be confirmed by the moderator.
normal – a request to join the group is processed immediately.

`@subgroups` ^(special)

An optional attribute only provided in the context of a hierarchical representation of groups and projects and only applies to the <group> element. It is a comma-separated list of subgroups showing that the current member belongs to this group through these subgroups.

`@template` ^{(extended representation)}

This attribute indicates where 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 representation)}

This attribute is the name of a group that a member must belong to so they are able 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

Minimal representation

A group with minimal attributes.

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

Basic representation

A group with basic attributes.

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

Extended representation

A group with extended attributes.

<group id="123"
       name="dev-example"
       description="The example development group" 
       owner="Example Corp"
       access="member"
       common="false" (deprecated)
       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

No change since initial API release.

Created on 6 January 2017, last edited on 23 September 2024 at 11:41

API elements

<group>

Summary

Usage context

Attributes

@access

@commenting (extended representation)

@common(deprecated)

@defaultnotify (extended representation)

@defaultrole (extended representation)

@description

@detailstype (extended representation)

@editurls (extended representation)

@id (minimal representation)

@indexversion (extended representation)

@moderation (extended representation)

@owner

@name (minimal representation)

@relatedurl

@registration (extended representation)

@subgroups (special)

@template (extended representation)

@title

@visibility (extended representation)