Skip to main content

 Web service API

How to use PageSeeder's Web service API

<member>

Summary

The <member> element is used as a base for other elements such as <assignedto>, <author> and <modifiedby>. While the <member> model is consistent, the serialization is contextual. Contexts include: list of group members, list of membership in groups, comments and documents.

The two representations of the <member> element are basic and extended. Included in the extended superset is: if the member is an administrator, the status of the account and any member-specific dates.

For privacy and security reasons, services supporting the extended representation are assumed to be initiated by either the account holder or a system administrator.

Usage context

Permitted content<fullname>
Permitted parent<access-token-issue>
<authorization-code-issue>
<client>
<invitations>
<member-account>
<member-activation>
<member-creation>
<member-modification>
<members>
<membership>
<memberships>
<persistent-token>

Attributes

The basic representation includes the following attributes:

NameTypeRequiredDescription
attachmentsbooleannoIf the user receives email attachments.
emailemailnoThe email address of the member (100 chars).
externalidxs:stringnoAn external identifier for the member (100 chars).
idxs:longyesThe ID of the member in PageSeeder.
lockedbooleannoIf the member account is locked.
onvacationbooleannoIf the member email option is set to 'on vacation'.
statusenumyesThe current status of the member.
firstnamexs:stringyesThe first name of the member (50 chars).
surnamexs:stringyesThe surname of the member (50 chars).
usernamexs:stringyesThe username of the member (100 chars).

In addition to all of the basic data, the extended representation includes the following attributes:

NameTypeRequiredDescription
activatedxs:datetimenoWhen the member activated their account.
adminbooleannoIf the user is an administrator.
createdxs:datetimenoWhen a member was created.
lastloginxs:datetimenoWhen a member last logged in.
lastpasswordchangexs:datetimenoWhen a member last changed their password.

@activated (extended)

An optional date and time attribute that reflects when a member account was activated. Only available once the account has been activated and once set, this value is immutable.

Early versions of PageSeeder did not record this information, therefore an account status of “activated”, does not guarantee the date and time is available.

@admin (extended)

An optional attribute indicating that the user has administrator privileges. For security reasons, this attribute is only provided to requests coming directly from a member.

When present, the value of this attribute is always true.

@attachments

Optional attribute for members that want email messages delivered with attachments embedded instead of the message including a link that refers to the attachment as a file being stored on the PageSeeder server.

When present, the value of this attribute is always true.

@created (extended)

An optional date and time attribute that reflects when a member account was created. Once set, this value is immutable.

Early versions of PageSeeder did not record this information, therefore, the presence of an account is not a guarantee that the date and time the account was created is present.

@email (security)

An optional attribute containing an email address that must not exceed 100 characters and be valid according to the IETF RFC 5322 .

Email addresses are unique for each member and although the letter case of addresses are preserved, they are not case-sensitive.

The email can be modified by the member or an administrator, however, to be effective the change needs to be confirmed by the member following the email change flow.

PageSeeder email address rules are stricter than the RFC, so all RFC-conforming address might not be accepted.

This email attribute is only included:
  • If the user making the request is an administrator;
  • AND if the member accepts to disclose their email address;
  • AND if the service allows it.
Look at the documentation for individual services.

@externalid

An optional attribute associating an external identifier with a member. The attribute value can only be set programmatically and can not exceed 100 characters.

It is the responsibility of the app creating the IDs to ensure they are unique and meet the requirements of the implementation.

@firstname

The first name of the member, this attribute is limited to 50 characters.

This value can be modified by the member or an administrator.

Before an account is activated or if it has not been populated, the system sets the value to Member.

@id

Internal PageSeeder database identifier for a member. This attribute is always an immutable positive long value and for any PageSeeder server the value is unique within the set of members.

Client applications can use this value as a key for caching objects associated with a member.

@lastlogin (extended)

An extended attribute providing the date and time the member last logged in successfully to PageSeeder. This attribute is set automatically by PageSeeder and cannot be set by the user or an API.

@lastpasswordchange (extended)

An extended attribute providing the date and time the member last changed its password in PageSeeder. This attribute is set automatically by PageSeeder and cannot be set by the user or an API.

This attribute is designed to assist with security audits or enforcing a password rotation policy.

@locked

An optional attribute indicating that the member account is temporarily locked due to excessive unsuccessful logins. Once an account is locked, not even the correct credentials bypasses the lock. PageSeeder sets this attribute automatically and it cannot be manually changed.

When present, the value of this attribute is always true.

@onvacation

Optional attribute to temporarily stop delivering email to the member account. This value can either be controlled by the member through their email options or set by the system (when it detects Vacation messages being returned from the member email service). 

When present, the value of this attribute is always true.

@status

The activation status of the member.

Values can be one of:

  • activated – the member is currently active,
  • unactivated – the member has not activated their account,
  • set-password – the member has not activated their account AND their password must be set.

Once the status of a member account is activated, it cannot be changed.

@surname

The sur, or last, name of the member, this attribute is limited to 50 characters.

This value can be modified by the member or an administrator.

Before an account is activated or if it has not been populated, the system sets the value to a random integer.

@username

The username attribute is unique and always specified. It must not exceed 100 characters and is case-preserving but not case-sensitive.

Where @username has not been specified, the system uses the same value as the email address.

Client applications that manage accounts in a manner that makes this attribute immutable can use it as a key for caching objects based on members.

Examples

Common basic

An activated member account with a username and an email address.

<member id="123"
        firstname="John"
        surname="Smith"
        username="jsmith"
        email="jsmith@example.org"
        status="activated">
  <fullname>John Smith</fullname>
</member>

Common extended

An activated member account with a username and an email address.

<member id="123"
        firstname="John"
        surname="Smith"
        username="jsmith"
        email="jsmith@example.org"
        created="2016-12-20T12:24:17+11:00"
        activated="2016-12-20T16:17:18+11:00"
        lastlogin="2016-12-22T08:53:15+11:00"
        lastpasswordchange="2016-12-27T15:46:27+11:00"
        status="activated">
  <fullname>John Smith</fullname>
</member>

Member with no email

A member account with no email address. This minimal representation of a member lists the attributes which are always present.

<member id="123"
        firstname="John"
        surname="Smith"
        username="jsmith"
        status="activated">
  <fullname>John Smith</fullname>
</member>

Member with no username

When the member account has supplied no username, the value is the same as the email.

<member id="123"
        firstname="John"
        surname="Smith"
        username="jsmith@example.org"
        email="jsmith@example.org"
        status="activated">
  <fullname>John Smith</fullname>
</member>

Member requires password

When a member has been invited to PageSeeder or an account was created without the password being set, the value of the @status attribute is set-password.

<member id="123"
        firstname="Member"
        surname="777"
        username="jsmith@example.org"
        email="jsmith@example.org"
        created="2016-12-20T12:24:17+11:00"
        status="set-password">
  <fullname>Member 777</fullname>
</member>

Unactivated account

An account where the password was set at creation, but has not yet been activated, has the value of the @status attribute set to unactivated.

<member id="123"
        firstname="John"
        surname="Smith"
        username="jsmith"
        email="jsmith@example.org"
        created="2016-12-20T12:24:17+11:00"
        status="unactivated">
  <fullname>John Smith</fullname>
</member>

Complete

A member account that includes all possible attributes.

<member id="123"
        firstname="John"
        surname="Smith"
        username="jsmith"
        email="jsmith@example.org"
        created="2016-12-20T12:24:17+11:00"
        activated="2016-12-20T16:17:18+11:00"
        lastlogin="2016-12-22T08:53:15+11:00"
        lastpasswordchange="2016-12-27T15:46:27+11:00"
        status="activated"
        attachments="true"
        admin="true"
        onvacation="true"
        locked="true"
        externalid="GDH8-T90D-R84A-13LX">
  <fullname>John Smith</fullname>
</member>

Schema

XML Schema

Basic member

<xs:element name="member" type="member-basic"/>

<xs:complexType name="member-basic">
  <xs:sequence>
    <xs:element name="fullname" type="xs:string"/>
  </xs:sequence>
  <xs:attribute name="attachments" type="boolean"/>
  <xs:attribute name="email" type="member-email"/>
  <xs:attribute name="externalid" type="member-externalid"/>
  <xs:attribute name="firstname" type="member-name" use="required"/>
  <xs:attribute name="id" type="id" use="required"/>
  <xs:attribute name="locked" type="boolean"/>
  <xs:attribute name="onvacation" type="boolean"/>
  <xs:attribute name="status" type="member-status" use="required"/>
  <xs:attribute name="surname" type="member-name" use="required"/>
  <xs:attribute name="username"
                type="member-username"
                use="required"/>
</xs:complexType>

Extended member

<xs:element name="member" type="member-extended"/>

<xs:complexType name="member-extended">
  <xs:complexContent>
    <xs:extension base="member-basic">
      <xs:attribute name="activated" type="xs:dateTime"/>
      <xs:attribute name="admin" type="boolean"/>
      <xs:attribute name="created" type="xs:dateTime"/>
      <xs:attribute name="lastlogin" type="xs:dateTime"/>
      <xs:attribute name="lastpasswordchange" type="xs:dateTime"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

Member types

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

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

<xs:simpleType name="member-name">
  <xs:restriction base="xs:string">
    <xs:maxLength value="50"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="member-status">
  <xs:restriction base="xs:string"> 
    <xs:enumeration value="activated" />
    <xs:enumeration value="set-password" />
    <xs:enumeration value="unactivated" />
  </xs:restriction>
</xs:simpleType>

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

Relax Schema

element member {
   attribute activated          { xs:dateTime }?,
   attribute admin              { xs:boolean }?,
   attribute attachments        { xs:boolean }?,
   attribute created            { xs:dateTime }?,
   attribute email              { text { maxLength = "100"} }?,
   attribute externalid         { text { maxLength = "100"} }?,
   attribute firstname          { text { maxLength = "50"}},
   attribute id                 { xs:long },
   attribute lastlogin          { xs:dateTime }?, 
   attribute lastpasswordchange { xs:dateTime }?, 
   attribute locked             { xs:boolean }?,
   attribute onvacation         { xs:boolean }?,
   attribute status             { "activated" |
                                  "set-password" |
                                  "unactivated" }?,
   attribute surname            { text { maxLength = "50"}},
   attribute username           { text { maxLength = "100"}},
   element fullname             { text }
}

Compatibility

No change since initial API release.

See also

Created on , last edited on