Skip to main content

 Element reference

Service API elements from <alias> to <workflow>

<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 following example, the member is indicated once and is the same for all the following memberships:

<!-- list of memberships for a single member -->
<memberships>
  <!-- member for whom the following memberships 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

@deleted

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

@email-listed

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

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

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

While membership identifiers are immutable, if members join and leave a group several times, they might have a different membership identifier, so they are not 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. Use one of the following:

  • immediate (also displayed as “Normal”)
  • essential
  • daily
  • weekly
  • none (also displayed as “Announcements only”)

@override

This attribute lists which attributes of the membership from subgroups are overridden (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 (the @subgroup attribute must have a value).

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. Use one of the following:

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

@status

The status of the membership. Use one of the following:

  • 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 @override attribute can also be specified.

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="organization"
               title="Organization"
               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:pattern value="((listed|notification|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

No change since initial API release.

Created on , last edited on