The Contacts Template is a universal "building block"
that can be used in many e-business applications. It is used in two main ways:
To store and manage authentication information (user names and passwords)
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.
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
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";>
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.:
groupName is an individual
groupName is an OU
groupName is a community
username and password supplied have to be that of the individual
the individual has to be a member of the OU or beneath the OU in the
the individual has to be linked into the community directly or indirectly
through the OU hierarchy (i.e.the individual belongs to an OU that is
in the community or to an OU beneath the OU belonging to the community
in the OU hierarchy).
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.
For full details see the Contact Template API reference.
Given an ID three methods can return information on OUs,
communities and individuals respectively:
Three methods based on ID allow modifications to existing information:
and three to create new information (returning the ID of the item created):
There is one delete method that deletes any item based on the ID supplied:
There are two methods used to link and unlink information together based on types
of item and the IDs supplied:
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:
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):
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
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: