Server Access Programmer's Guide:
Overview

This topic introduces the eRoom Server Access API and explains conventions used throughout the documentation.

Who should read this guide?

eRoom Server Access API Programmer's Guide is for experienced application developers. It contains basic information about the API's objects and their interfaces. In order to successfully use this API, you should be able to write programs in either C++ or in a scripting language, such as Visual Basic, VBScript or JavaScript.

What is SAAPI?

The eRoom Server Access API (SAAPI) is composed of easily-programmed objects that appear in the eRoom client User interface: Sites, Facilities, Files, Folder Pages, Note Pages, Users, and so on. The Server Access API is an OLE Automation API. This means that clients can be written in any automation-compatible language, such as Visual Basic, VBScript, C++, Java, or JavaScript.

What kinds of things can you do with SAAPI?

With few exceptions, you can use SAAPI to write programs that do anything you can do through the eRoom user interface. SAAPI programs can even do a few things you can't accomplish with the eRoom user interface. While the possibilities are too numerous to list, here are a few ideas to get you thinking:

Create rooms and populate them with data from another source
Copy data from facilities and rooms to another source
Manage the member lists of facilities and rooms
Generate reports on users or rooms
Search for items within facilities or rooms
Automate administrative tasks
Extend eRoom's functionality by developing add-on utilities

COM and the Server Access API

The eRoom Server Access API is a Component Object Model (COM) API. The API is comprised of a set of objects, each made up of one or more interfaces. As with any COM API, there is not necessarily a one-to-one relationship between objects and interfaces:

Some interfaces are specific to the object type. For example, the Facility object implements the IERUFacility interface. This interface contains methods and properties that pertain only to Facilities. Some interfaces are more general-purpose. For example, several objects, such as Files, Folder Pages, and Note Pages, implement the IERUAccessControl interface. This interface contains methods and properties that pertain to the access control lists of all of these objects, not just one particular type. General-purpose interfaces are implemented by several object types.
Some objects implement several interfaces. For example, a File object implements IERUFile, IERUAccessControl, and IERUItem.

Accessing different COM interfaces for a single object

SAAPI is a language-neutral API, accessible from any language compatible with COM automation programming. The capabilities of these languages varies, however. For example, scripting languages such as VBScript do not support typed objects and lack the ability to directly access different interfaces on a single object, as can be done via QueryInterface in C++, or through assignment to a type-specific variable in Visual Basic. To address this limitation, for objects that implement more than one interface, SAAPI defines properties which serve the same purpose by returning as their value a different interface to the same object. These properties are referred to as "interface accessors" in this documentation.

For example, Group objects in SAAPI implement both the IERUMember interface and the IERUGroup interface. The Group property in IERUMember returns an IERUGroup interface pointer for the Group.

General SAAPI Programming Conventions

Array bounds and indexes

Array bounds and collection indexes in SAAPI are generally 1 based. ERoom will accept a safearray with any upper and lower bounds, but will only return 1 based arrays to coincide with 1 based collection indexes. Keep in mind that a when creating new arrays in VB/JS they are generally 0 based.

Use Typed IERU* interfaces rather than Idispatch

For performance and usability, readability, maintainability of your code, it is best to use strongly typed languages when possible. VBScript/JavaScript are untyped (they only have a Variant type; you can’t specify the type of a variable). In this case, you are calling into the object via its IDispatch interface, by name.

Note that the interface accessors that return specific item interfaces are no longer needed as of eRoom V.7. Now all properties from all implemented interfaces can be accessed directly on the object. For example, the Folder object’s Description property is implemented by IERUFolderPage::Description property. In script, you can simply access all properties implemented by the folderpage object directly on that object. See the following examples:

’r;## Accessing properties in UnTyped/Scriping languages (Idispatch)

Dim o

Set o = Room.GetItem(SomeItemID) ’r;## Get item as Idispatch interface

Response.write ”r;Description=”r; + o.Description ’r;## Call IERUFolderPage::Description if is folder or IERUNotePage is note, etc&ldots;

Response.write ”r;URL=”r; + o.URL ’r;## Call IERUPrincipalItem::URL via IDispatch

’r;or&ldots;. Something member related

Dim member

Set member=MemberManager.GetMember(SomeMemberID)

Response.write ”r;DisplayName=” + member.DisplayName ’r;## Call IERUUser::DisplayName via IDispatch

Response.write ”r;IsSiteAdministator=” + member.IsSiteAdministrator ’r;## IERUUser::IsSiteAdminstrator via IDispatch

’r;## Accessing properties using typed interface in a typed language (IERU* interfaces)

dim item as IERUItem

dim principalItem as IERUPrincipalItem

set item = Room.GetItem(SomeItemID) ’r;## Get item as IERUItem interface

set principalItem = item ’r;## QueryInterface for IERUPrincipalItem interface

dim folder as IERUFolderPage

set folder=item ’r;## QueryInterface for IERUFolderPage

Response.write ”r;Description=”r; + folder.Description ’r;## Call IERUFolderPage::Description directly

Response.write ”r;URL=”r; + principalItem.URL ’r;## Call IERUPrincipalItem::URL directly

’r;NOTE: Idispatch can be used in strongly typed languages to generalize access to properties that are common to many types of items but are defined in different interfaces. For example, ::Description is defined in IERUFolderPage, IERUNotePage, IERUInboxPage, IERUProjectTaskPage, etc, therefore you would have to write object type specific code to get the ::Description property from these varied types of objects. You can write more generic code that will access the named property via Idispatch by simply using a variable of type VARIANT or Object to make access the property.

dim o as object

set o = item ’r;## QueryInterface for Idispatch

Response.write ”r;Description=”r; + o.Description ’r;## Get description via Idispatch (object type independent)

’r;or&ldots;. Something member related

Dim member as IERUMember

Dim user as IERUUser

Set member=MemberManager.GetMember(SomeMemberID)

Set user = member ’r;## QueryInterface for IERUUser interface

Response.write ”r;DisplayName=” + user.DisplayName ’r;## Defined in IERUUser

Response.write ”r;IsSiteAdministator=” + user.IsSiteAdministrator ’r;## Defined in IERUUser

Licensing and Login/Impersonation

Note that employing a user via the API (ie. ::LoginUser(), ::ImpersonateUser(), ::CreateAuthenticationSession() methods will consume a license the first time, just as would happen if the user had logged in via a web browser.

Database Performance Tips

The fastest way to get data from a data object is via a DBQuery and the use of the ::GetRowCells() method. Accessing data through the cells collection is much slower and should be avoided unless updates are required or you must access attachments, comments, or Richtext data types.

Simple Encryption Support

The eRoom Authenticator object provides a simple two-way encryption for use in saving cookies. See the IERUAuthenticator::SimpleEncrypt/SimpleDecrypt methods for details. Note that this is not a strong encryption.

Getting Help

When you have a question about SAAPI, you can refer to this Programmer's Guide, or any of these sources:

Reference pages: For detailed descriptions of every object, interface, method and property defined by SAAPI, see the language reference.
Samples: The SAAPI toolkit ships with several programming samples which are intended to help you learn the API. In many cases, you may find that one of the samples tackles a problem similar to the one you are trying to solve, and you can use the sample as a starting point for your work.

Conventions used in the documentation

Convention	Description
variable	In syntax statements, italics indicate placeholders for information you supply.
GetItem	In syntax statements, bold indicates a word you must enter exactly as it appears.
`Clt.GetFacility`	Courier font indicates syntax and examples.
Item, Facility	Object names appear with their first letter in uppercase. You will notice that some terms used in this documentation are capitalized in some contexts and not capitalized in others. Generally, when a term is capitalized (such as User), it is referring to a specific object in the SAAPI programming model. When not capitalized, it is being used in a more general sense, referring to the underlying concept rather than specifically to the programmable object which exposes its functionality.
edit list	In text, a word appears in boldface when it is first introduced.

The term eRoom refers to the product called eRoom. The term room (all lowercase) refers to the concept of an membership-controlled container of items, and the term Room (capitalized) refers to the programmable object that exposes its functionality.

Sample code

The Programmer's Guide contains many code examples that illustrate the concepts discussed in the guide. Unless otherwise specified, all sample code is written in Visual Basic 5.0.

Server Access Programmer's Guide: Overview