Contacts Template

Overview

The Contacts Template is a universal "building block" that can be used in many e-business applications. It is used in two main ways:

1. To store and manage authentication information (user names and passwords)

2. To store and manage conventional contact information such as names and addresses(although support for this is limited in the first release)

A straightforward interface allows for comprehensive yet easy manipulation of the contact information stored by the template in the database.

Concepts

The Contact Template data schema is similar to the Whitebeam Catalogue Template schema. The fundamental information stored is associated with individuals. An individual can be a real person (e.g. Joe Bloggs) or, if you wish, some anonymous set of contact information (e.g. Regal Cinema).

Individuals can be arranged into a hierarchy of organisational units or, as they are known throughout the contacts template, as OUs. Each OU can have only one parent OU above them in the hierarchy. The top of the hierarchy for any Client is known as the "root" and has an ID of 0. An individual can appear in exactly one OU An individual is always linked into the hierarchy of OUs somewhere, even if its just the root.

Individuals and OUs are collectively known as entities.

Another key concept is that of communities. A community is simply a group that cuts across any organisational hierarchy (sometimes known as a community of interest, community of commitment or virtual team). An enitity can be linked into any number of communites.

As well as being a convenient way of arranging information, the relationship between individuals, OUs and communities has specific meaning within the Whitebeam system when controlling access to pages.

Controlling Access to Pages

The Presentation Engine reads and interprets special Whitebeam tags put at the top of pattern pages that it uses to determine whether the requestor has permission to access a page. An example access control tag looks like this:

<rb:authenticate domain="MyWebServer" community="groupName";>
   html and server/client JavaScript goes here...
</rb:authenticate>

This tag causes the Presentation Engine to demand a name and password before it will allow access to the page contents. The name and password supplied have to be of an individual who is a member of the group specified by the string "groupName". Unless the password matches the individual's username and the individual is a member of the group the page will not be served.:

IDs and Unique Names

Every individual, OU or community stored in the database is given a unique numeric ID by which it can be identified. These will always be greater than zero for application created objects.

IDs are not very user friendly and so the Contacts template also allows for unique names (uName) to be entered that, as their name implies, are unique strings that correspond 1:1 with the numeric ID.

This allows more meaningful strings to be put in authentication tags such as "engineering test" rather than "203". Note that unique names do not have to be set by the user, the template automatically generates a unique name if none is specified in a create call.

API Overview

For full details see the Contact Template API reference.

Given an ID three methods can return information on OUs, communities and individuals respectively:

rb.contact.OUInfo()
rb.contact.communityInfo()
rb.contact.individualInfo()

Three methods based on ID allow modifications to existing information:

rb.contact.modifyOU()
rb.contact.modifyCommunity()
rb.contact.modifyIndividual()

and three to create new information (returning the ID of the item created):

rb.contact.createOU()
rb.contact.createCommunity()
rb.contact.createIndividual()

There is one delete method that deletes any item based on the ID supplied:

rb.contact.remove()

There are two methods used to link and unlink information together based on types of item and the IDs supplied:

rb.contact.link()
rb.contact.unlink()

There is one method used to find out what groups an entity is a member of and one to find out what entities are in a specific group:

rb.contact.memberOf()
rb.contact.whosIn()

There is one method used to ascertain the number of individuals within a community of OU hierachy based on ID, this is very useful when making a decision on how to display a list of individuals (e.g. on one or more pages):

rb.contact.count()

There is a method used to search for individuals in a community or OU, the community or OU being specified by an ID. Note that this method can be used to find all individuals that are in a specific community or OU as well as those that meet certain search criteria:

rb.contact.get()

Passwords are not set in the same way as other contact data, and they can never be read back once set because they are held in one-way encrypted format within the Whitebeam contact database. Two methods are provided to set and validate passwords:

rb.contact.setPassword()
rb.contact.validate()