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> Therefore, while the model for <member> is consistent, there are a number of variations for how the XML is serialized for different contexts such as member listings, group memberships, comments and documents.

The two representations of the element are basic and extended. The extended representation is a superset that includes whether the member is an administrator, their account status and member-specific dates. Due to privacy and security implications, services that support the extended representation are assumed to come from either the actual member 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 immutable.

Note

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.

Note

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 will be present.

@email (security)

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

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 should be confirmed by the member following the email change flow.

Note

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

Warning!

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

Note

It is the responsibility of the application 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 will set 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 will be unique within the set all 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 will bypass the lock. PageSeeder sets this attribute automatically and it cannot 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 may 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 will set 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 use 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 will be the same 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 will be "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 will have 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

See also

Created on , last edited on