Web service API

How to use PageSeeder's Web service API

<membership>

Summary

The group XML output is used to represent PageSeeder group membership associating a member with a group or project.

A group membership always involves both a member and a group or project and this is reflected in the model with <member>, <group> or <project> and optional <details> as child elements:

<!-- single membership with member and group -->
<membership>
   <member/>
   <group/>
   <details/>
</membership>

However, in cases when we list the memberships for a single member or a single group, we don't repeat the same element. In the example below, the member is indicated once and is the same for all memberships below:

<!-- list of memberships for a single member -->
<memberships>
   <!-- member for whom memberships below are listed -->
   <member/>
   <membership>
      <group/>
   </membership>
   <membership>
      <group/>
   </membership>
   ...
</memberships>

Usage context

Permitted content

<member>

<group>

<details>

Permitted parent<invitations>
<memberships>
<membership-creation>
<membership-modification>
<unsubscribe>

Attributes

This element includes the following attributes.

NameTypeRequiredDescription
createdxs:dateTimenoWhen the member joined or was invited to the group
deletedxs:booleannoIf the member was removed from the group
email-listedxs:booleanyesWhether the member discloses its email address
idxs:longnoThe ID of the membership in PageSeeder
notification enumyesNotification preference for the member
overridelistnoWhich attributes from subgroups are overridden (i.e not inherited).
roleenumnoThe role of the member in the group or project
statusenumyesThe status of the membership
subgroupsxs:stringnoComma-separated list of subgroups

@email-listed

This boolean attribute indicates whether the member agrees to disclose his email address to other group members.

@deleted

An optional boolean attributes set to "true" when a member has been removed from a group.

@id

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 memberships.

Warning!

Memberships acquired through a subgroup do not have a membership ID. When you parse <membership> elements that may include such memberships, that your code can cope without an ID.

While membership identifiers are immutable, if members join and leave a group several times, they may have the different membership identifier so they may not be the best key for cached objects based on memberships. Consider using the member and group identifiers or names instead.

@notification

The notification settings for the member in the group. One of:

  • "none"
  • "daily"
  • "immediate"

@override

This attribute lists which attributes of the membership from subgroups are overridden (i.e. not inherited from the subgroup or subgroups). The value is a comma separated list of the following:

  • "listed"
  • "notification"
  • "role"

For example override="listed,notification". It only appears if the membership is acquired through a subgroup (i.e. the @subgroup attribute must have a value).

Warning!

By default, members inherit the @email-listed, @notification, and @role  values from the subgroup, but this attribute is only specified when it is not the case.

@role

The role of the member in the group. One of:

  • "guest"
  • "reviewer"
  • "contributor"
  • "manager"
  • "moderator"
  • "approver"
  • "moderator-and-approver"

@status

The status of the membership. One of:

  • "normal"
  • "invited"
  • "self_invited"
  • "moderated"
  • "disabled"
  • "unknown"

@subgroups

This attribute returns a comma-separated list of subgroups through which the member is part of the group.

This attribute is only specified if the member is a member by virtue of belonging to a subgroup. If this attribute is specified, the @inherit-* attributes may also be specified to indicate which attributes of the membership are inherited from the subgroup(s).

Note

The value is a comma-separated list to cater for the rare case when the member obtains membership to a group through multiple subgroups.

Examples

Group membership with details

<membership id="123" email-listed="true" notification="immediate" status="normal" role="manager">
   <member id="123" firstname="Joan" surname="Smith" username="jsmith" status="activated">
      <fullname>Joan Smith</fullname>
   </member>
   <group id="4" name="acme-asia" description="Demo group for Asia" />
   <details>
      <field position="1" name="organisation" title="Organisation" editable="true">ACME Asia</field>
      <field position="2" name="telephone"    title="Telephone"    editable="true">12345678</field>
      <field position="3" name="notes"        title="Notes"        editable="true">Follow up</field>
   </details>
</membership>

Schema

XML Schema

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

<xs:complexType name="membership">
  <xs:all>
    <xs:element name="member"   type="member-basic" minOccurs="0"/>
    <xs:element name="group"    type="group-basic"  minOccurs="0"/>
    <xs:element name="details"  type="details"      minOccurs="0"/>
  </xs:all>
  <xs:attribute name="created"          type="xs:dateTime"/>
  <xs:attribute name="deleted"          type="boolean"/>
  <xs:attribute name="email-listed"     type="boolean" use="required"/>
  <xs:attribute name="id"               type="id"/>
  <xs:attribute name="notification"     type="notification"/>
  <xs:attribute name="override"         type="membership-override"/>
  <xs:attribute name="role"             type="membership-role"/>
  <xs:attribute name="status"           type="membership-status" use="required"/>
  <xs:attribute name="subgroups"        type="xs:string"/>
</xs:complexType>
Membership attribute types
<xs:simpleType name="membership-override">
  <xs:restriction base="xs:string">
    <xs:enumeration value="listed" />
    <xs:enumeration value="notification" />
    <xs:enumeration value="role" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="membership-role">
  <xs:restriction base="xs:string">
    <xs:enumeration value="guest" />
    <xs:enumeration value="reviewer" />
    <xs:enumeration value="contributor" />
    <xs:enumeration value="manager" />
    <xs:enumeration value="moderator" />
    <xs:enumeration value="approver" />
    <xs:enumeration value="moderator-and-approver" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="membership-status">
  <xs:restriction base="xs:string">
    <xs:enumeration value="normal" />
    <xs:enumeration value="invited" />
    <xs:enumeration value="self-invited" />
    <xs:enumeration value="moderated" />
    <xs:enumeration value="disabled" />
    <xs:enumeration value="unknown" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="notification">
  <xs:restriction base="xs:string"> 
    <xs:enumeration value="daily" />
    <xs:enumeration value="essential" />
    <xs:enumeration value="immediate" />
    <xs:enumeration value="none" />
    <xs:enumeration value="weekly" />
  </xs:restriction>
</xs:simpleType>

Relax Schema

element membership {
   attribute created       { xs:dateTime }?,
   attribute email-listed  { xs:boolean },
   attribute id            { xs:long }?,
   attribute notification  { "none" | "daily" | "immediate" },
   attribute override      { xs:string }?,
   attribute role          { "guest" | "reviewer" | "contributor"
                           | "manager" | "moderator" | "approver"
                           | "moderator-and-approver" }?,
   attribute status        { "normal" | "invited" | "self-invited"
                           | "moderated" | "disabled" | "unknown" },
   attribute subgroups    { text }?
   element group?,
   element member?
}

Compatibility

See also

Created on , last edited on