Notes on Upgrading to SAAPI Version 7

This topic describes in detail several changes from V. 6 to V. 7 that could affect existing V. 6 SAAPI programs.

New Objects and Cross-Server Interfaces

Facility vs. Community Member Management

Accessing Files in the V.7 eRoom File System

URL Property, Redirection, and Reverse Proxy Issues

Migrating Custom Commands and Custom Viewers from V.6 to V.7

Migrating eRoom extrafiles to Custom Commands

eRoom User Context is Thread-Based &endash; (Must have context to access databases)

eRoomToolkit.ASP &endash; eRoom Dialog and Style Include File

SAAPIUtils.ASP Helpers

IDispatch Unification (renamed properties)

SAAPI Error Handling

New Objects and Cross-Server Interfaces

Several new creatable objects have been added to eRoom V7. The existing ERUSvrManager (”r;eRoom.ServerManager”) object is obsolete. It has been replaced as the top-level object by the ERUApplication (”r;eRoom.Application”) object. The application object allows you to establish a user context, provides access to get the site, and provides access to eRoom facilities.

The following is a complete list of creatable eRoom objects--objects that can be created using CreateObject() script method or created via cocreate in C++.

Each of the above objects implements a default interface whose name can be identified by adding ”r;I” to the beginning of the object name (coclass name). For example, the interface implemented by the ERUApplication object is IERUApplication.

In V.7, eRoom has added the ability to manage multiple eRoom servers. Several new interfaces, such as site and community, have been added to facilitate these new cross-server concepts. These new interfaces also provide limited access to facilities, rooms, and items across servers. Note that any given facility, room, or item can still only be served by a single eRoom server. IERUFacility, IERURoom, and IERUItem are more or less unchanged, and the new IERUSiteFacility, IERUSiteRoom, and IERUSiteItem interfaces are used to represent these existing concepts in a lightweight, read-only, cross-server fashion.

Conceptually, the eRoom site is the top-level object: IERUSite can be acquired via the ApplicationObject::Site property. A site consists of one or more communities. Communities are managed via the IERUCommunityManager, which can be aquired from Site::CommunityManager. You are returned a collection of IERUCommunity interfaces for each community in the site. Each community can contain one or more facilities. Each facility contains one or more eRooms. Rooms and facilities can be enumerated using the IERUCommunity::SiteFacilities and ::SiteRooms properties, which return IERUSiteFacility and IERUSiteRoom interfaces. You can obtain the URL of the server that hosts a facility, room, or item from the IERUSite interface. When running on the eRoom server that hosts a given facility, you can acquire an IERUFacility by calling IERUSiteFacility::GetFacility(); an IERURoom by calling FIERUSiteRoom::GetRoom(); and an IERUItem by calling IERUSiteItem::GetItem().

Member management is performed in V.7 at the community level (rather than at the facility level as in prior versions). Getting the ::MemberManager property from either a community or a facility will return the community's member manager.

ERUCollection is now a creatable object (IERUCollection)

There is now a creatable collection object in eRoom whose default interface is IERUCollection. It can be created via CreateObject(”r;eRoom.Collection”) or in VisualBasic using ’r;new ERUCollection’. Note that VB will suppress the display of IERUCollection in the object browser in favor of the ERUCollection object. VB will change reference from IERUCollection to ERUCollection for you when you type code. Note that you may have to change some variable’s type from IERUCollection to ERUCollection manually.

This should not be an issue for other languages (for example, on C++, VBScript, and Jscript).

Facility vs. Community Member Management

eRoom V.7 adds the concept of a community, which contains facilities. A community can span servers and can contain any number of facilities. A site contains one or more communities. Prior to V.7, members were defined at facility scope. In addition, their rights and settings were stored at facility scope. Several settings that were available at facility level have been moved to the community level. Properties from a facility that have moved to community settings have been hidden on IERUFacility, but will continue to work via the containing community.

GetMember() Method: Differences with facility vs. community

Prior to V.7, member management was performed at facility level. In V.7, communities are used to manage members. When directory connections are added to a community, all the members from that directory are members of a directory group (a group named for the directory connection). Prior to V.7, these members were also members of the facility. This difference means that the GetMembers(flags) method does not include directory members in V.7, thereby producing incompatible results.

Because of this difference, the implementation of the IERUFacility::GetMembers() and IERUMemberManager::GetMembers() methods automatically adds the value "ExpandGroups" to the MemberFlags parameter that is passed in.

Any access of IERUCommunity level member manager will not expand the groups by default.

User Permissions

As previously stated, members are now defined at community scope. Members can also be made guests in other communities. Prior to V.7, IERUUser had several properties to control rights. These properties are now obsolete and return a E_NOTIMPL error. This is because in many cases, this check would be inappropriate since you would be checking rights in the member’s home community rather than the community in which the member is working. Permissions within a community are now determined using the IERUPermissionManager.

Accessing Files in the V.7 eRoom File System

eRoom files are stored on an eRoom site file share that requires Windows rights for access. The eRoom server impersonates a configured file system user when accessing the eRoom file system; This user is configured in Site Administration/MMC utility.

A new IERUFileAccess interface has been added to provide read-only access to eRoom files in the form of a Windows file HANDLE or a Windows file system object named ItestStream. The eRoom file object implements IERUFileAccess to directly access the file in eRoom storage--the file whose path is IERUFile::ServerFilePath. The AddFile_Before and ReplaceFile_Before Synchronous Events implement IERUFileAccess, to provide direct access to the incoming uploaded file in its temporary location in the eRoom file system.

An ExtensionFileAccess (EFA) object is passed to the IERUFileAccess::AccessFile() method, which in turn performs the required Windows OS impersonation to allow access to the eRoom file system. This impersonation is only in effect while your EFA’s ::AccessFileImpl() method is being called. For additional access, you manage impersonation yourself. (Exercise caution--don’t use the Windows API directly; You must ensure that you revert in the case of an exception.)

Do not write to files that reside in the eRoom file system. If your extension must write to the server file system temporary directory or some other location, the eRoom extension is responsible for performing any Windows OS impersonations.

Note: If a "before" event handler writes a new file and provides that path via ::put_FilePath(), the eRoom file system account must have access rights to this file and path.

IERUFile::Get() and IERUFile::Replace() can be used to get a copy of an eRoom file or replace an eRoom file. Note that the eRoom file system user must have rights to the target path for ::Get() and the source directory for ::Replace() file paths. This would generally be the local temporary directory on the eRoom server. (For example, ”r;C:\TEMP\~515123.tmp”)

Warning:  We also recommend that you not run ASP applications, as Windows users that have access rights to the file system or to grant such rights to existing users employed by ASP applications. Don’t use the Win32 API directly to impersonate then revert to self in order to access the file system. You must be careful to ensure that you revert-to-self automatically with an object, so errors or exceptions in your application don’t introduce security problems.

Standalone SAAPI applications can be run under a user that has access to the eRoom file system.

URL Property, Redirection, and Reverse Proxy Issues

Extension Virtual directory has moved

Old bookmarked URLs to custom commands must be changed for V.7. The prior structure was /eRoomASP/Custom/page.asp. The new structure is eRoomASP/Extensions/<extid>/page.asp.

See the eRoom Constants and Helper Functions topic for functions to generate URLs to core and custom pages and data files.

Using <base href> and relative URLs

Existing code that builds extension URLs will have to be updated. Also note that eRoom pages (and those built with eRoomToolkit.ASP) now contain a <base href> URL that references the current eRoom server with any required proxy prefix. This means that all link URLs specified in a page should be made relative to the URL. SAAPIUtils.ASP provides helper functions to generate URLs to extension ASP files, data files, and core data files. These URLs are always returned in a relative form that begins with the virtual root with no leading ”r;/”.

For example, assume you have an eRoom server named ”r;myServer” that is configured to run with a reverse proxy and has a prefix of ”r;/MyProxy”. In this case, eRoom pages would have a <base href> that contains the protocol, server, port, and proxy prefix. For example, ”r;<base href=’https://myServer:8081/MyProxy/’>

Note the trailing ”r;/” character. Any URL you specify will be relative to this <base href> URL. For example, if you insert a link to an image, it would look like: <img href="eRoomData/Busy.gif">"

When redirecting with Response.Redirect, URLs that are in a relative form should be fully qualified with the server URL (see below), or else made relative to the server by adding just the proxy prefix of the URL. For example, given the relative URL to an extension page of ”r;eRoomASP/Extensions/Sample.Extension1/MyPage.ASP” and a server URL of ”r;https://myServer:8081/MyProxy/”, you could either redirect to:

”r;https://myServer:8081/MyProxy/eRoomASP/Extensions/Sample.Extension1/MyPage.ASP”

or to:

 ”r;/MyProxy/eRoomASP/Extensions/Sample.Extension1/MyPage.ASP”

with the same effect.

Determining the eRoom Server URL (<base href>)

Note that you can also choose to fully qualify a URL by adding the server URL to the beginning. For example:

Dim App: Set App=Server.CreateObject(”r;eRoom.Application”)  ’r;## get an application object
Dim BaseURL   ’r;## Base URL with proxy for this eRoom server
Dim URL, QualifiedURL
BaseURL= =App.ThiseRoomServer.eRoomServerSettings.URL + "/"
URL = ”r;eRoomData/Busy.gif”      ’r;## Our relative URL
QualifiedURL = +URL         ’r;## Make it fully qualified
set m_app=server.CreateObject("eRoom.Application") gPrefix=

If you are generating your own pages without using eRoomTookit.ASP, you can add a <base href> youself, as follows:

<HTML>
<HEAD>
<base href=”<%=app.ThiseRoomServer.eRoomServerSettings.URL%>/”>
</HEAD>
&ldots;.
</HTML>

Note that the above server URL prefix will return protocol, port, server and any required proxy prefix.

• Always add the proxy prefix to URLs prior to redirect. For example: ERGenerateUIEventURL(eruiEventMyeRooms, "","","","") will return ”r;eRoom”, which is relative to your <base href=’http://coffee.eroom.com/MyProxy/’>, which is evaluated on the client as ”r;http://coffee.eroom.com/MyProxy/eRoom”. If you are redirecting to the URL, make sure to add either the proxy prefix or the full server URL that contains the proxy prefix (depending on whether you want a URL relative to the server or fully qualified).

• Note that submit and other URLs are relative to the <base href> that is inserted by eRoomToolkit.ASP. URLs are now in the form ”r;eRoomASP/Extensions/<extid>/file.asp?ctxt&ldots;”instead of ”r;/eRoomASP/Custom/page.asp..." Use the ERGetExtensionURL(extid, filename) function to generate URLs to your extension files that are relative to this base href URL. There are also functions to generate eroom data, extension data URLs, etc.

Migrating Custom Commands and Custom Viewers from V.6 to V.7

The old /eRoomASP/en/Custom directory is obsolete. When you upgrade your server to V.7, this directory will be left intact with your V.6 server extensions. All extensions must be updated and re-deployed for V.7. Old command or viewer files can be updated then copied or moved into the site’s ~Extensions directory for redeployment. Existing custom commands and viewers should be usable with eRoom V.7 with little modification.

The following will likely need to be modified:

• If you used eRoomToolkit.ASP, you must remove any declarations from your page that collide with those added to eRoomToolkit.asp in V.7. This shouldn’t be an issue unless you added the declarations because of ’r;Option Explicit’

• The directories that hold ASP extension script and data files have changed. Links and redirect URLs may need to be updated. There are now SAAPIUtils.ASP helper functions for building URLs. URLs in eRoom pages and in pages generated with eRoomToolkit.ASP contain a <base href> that specifies the current eRoom server, complete with any reverse proxy prefix. This means that all relative URLs are now relative to this <base href> and not to the current ASP page.

• Extensions no longer reside in a localized ASP directory. The same extension files are used regardless of what localized versions of eRoom are installed. Extensions that wish to localize themselves can choose to use resource files or to redirect themselves to localized versions.

• In V.7, use MMC and Extension Manager to configure and deploy extensions to the eRoom site.

Migrating eRoom extrafiles to Custom Commands

The now deprecated ’r;eRoom extrafiles’ feature allowed you to copy custom pages for use with a given eRoom. This functionality is replaced by Custom Commands, which are installed at a site level (per server), but can be configured to run in specific eRooms. The primary difference is that with extrafiles, you had a specific version of a page per eRoom.  With custom commands, you are encouraged to develop more general/reusable/data drive/shared commands, rather than building pages for a single eRoom.

To convert an eRoom extrafiles page into an eRoom Custom Command extension, perform the following steps:

1. Include eRoomCustomCommand.ASP file at the beginning of your asp page.
   <!--#include virtual="/eRoomASP/en/eRoomCustomCommand.asp"-->

2. Add the Sub Main() entrypoint that is called by eRoomCustomCommand.asp. Wrap any module level executable code with Sub Main(). (Example or literal.)
   Sub Main (Context)
   End Sub

3. Update your links and form action URLs use custom command URL syntax. For example:
   (Old syntax)
   /eRoomExtraFiles/<FacilityURLName>/<RoomURLName>/Page.ASP
   (New Syntax)
   eRoomASP/Extensions/<ExtensionID>/Page.ASP

For example, using eRoomToolkit.ASP, you would generate the form submit URL as follows:
mySubmitPage= ERGetExtensionURL(Context.ExtensionID, ”r;MyCommandPage.ASP”)
See the eRoom Constants and Helper Functions topic for a complete list of URL helper functions.

4. Redirect back to eRoom where the command was launched from as follows: Response.Redirect Context.ReturnURL  ’r;Back to where we came from.

You can create links to custom commands from within eRoom HTML/Rich Text by using an HREF of ”r;cmd:ExtensionID” in a link. For example: <a href=”cmd:MyCo.MyCommand”>My Link Text</a>

eRoom would display the above link in a web browser in the following form: eRoomASP/CustomCommand.ASP?ID=MyCo.MyCommand?Ctxt=.facility.room.item

ERoom adds the context for the current page. However, eRoom does not allow a custom command to be executed in a context unless that custom command is enabled in that context.

You can add a querystring to these command links, but you must be certain to use an ampersand (&) rather than a question mark after the command ID, since eRoom always adds it’s context with a question mark character. For example, <a href=”cmd:myco.mycommand&SomeQueryString=MyValue”>Click Me</a>

Note that eRoom link items can also be used to execute custom commands, but currently such URLs must be fully qualified.

eRoom User Context is Thread-Based &endash; (Must have context to access databases)

You must establish a user context before you access any API that accesses the site database or any facility database. This includes accessing settings on the site object as well as getting settings from the now-obsolete eRoom.ServerManager object. You must also establish a user context before accessing certain server manager properties.

ERUApplication::LoginUser() method and the ERUUserContext object can be used to establish a user context as any eRoom user. You can impersonate another user when you already have a user context by using the ERUUserContext::ImpersonateUser() method. Note that it should be rare that you have to impersonate a user, and you should use great care when doing so.

Note that when the ERUUserContext object goes out of scope (is destroyed), you return to the previous user context, if any.

Existing code that gets a facility from an ERUSvrManager should be modified to use the ERUApplication object after establishing a user context.

Note: Although the ServerManager object is obsolete, it can still be used under certain conditions for the purposes of compatibility. If you are running a standalone application, eRoom will give the user context specified in IERUSvrManager::GetFacility(facname, username). However, if you already have a user context, you will receive an "incorrect user or password" error.

Site Authenticator &endash; Managing eRoom sessions and validating passwords

Note that in V.7, only the built-in site authenticator user can manage sessions and validate passwords. When using the ERUAuthenticator object (CreateObject(”r;eRoom.Authenticator”), you must first establish a user context as the built-in site authenticator in order to manage sessions or validate passwords.

Note that a login or impersonation is not needed in the case of a UIEvent for a login or a synch. You can use an event handler for login, since you are provided a user context for the site authenticator user. You can verify the current logged-in member at any time by creating an ”r;eRoom.UserContext” object and checking the ::LoggedInMember property.

eRoomToolkit.ASP &endash; eRoom Dialog and Style include file

In previous versions of eRoom, if you used eRoomToolkit.ASP with ’r;Option Explicit’, you had to add the declarations for some variables that you should not have to worry about in V.7. These have now been added to eRoomTookit.ASP itself. This means that you must remove the following declarations from any of your pages that include eRoomToolkit.ASP:

New globals used by V.7 Frame.ASP:

dim gMapBorderGlow, gThinbarStyle, gThinbarOverStyle, gIsFirstbutton, gIsInBar

Existing globals:

dim gMaxLogoHeight, gMaxLogoWidth, gGraphicURL, gDirection, gDefaultLogo

SAAPIUtils.ASP Helpers

Session and Context helper functions that are obsolete but kept for compatability.

Session-related functions have been updated to use the new SAAPI Authenticator object. When called, they now validate that you have a valid session and return an error if the session is invalid. GetUserID(), ERGetFacilityURLName(), etc. are obsolete but kept for backward compatibility. eRoom ASP-based extensions are provided with an IERUCustomContext interface that provides access to all such context information.

eRoom User Context required for use of SAAPIUtils.ASP helpers

eRoom V.7 requires that you establish a user context with appropriate rights before accessing eRoom objects.

When using session- or authentication-related functions, you must first establish a user context as the ’r;eRoom Authenticator’ user. If you already have a user context, you may use ImpersonateUser on a new user context object in order to establish new user context.

For example:

'Establish context as authenticator user (even if there is already a user context established): Make sure you include  SAAPI.ASP or eRoomToolkit.ASP to define the constants erUserSiteAuthenticator and erParamTypeID.

Dim erUserContext, erAuthenticator, bIsValid

set erUserContext=Server.CreateObject("eRoom.UserContext")

set erAuthenticator=Server.CreateObject("eRoom.Authenticator")

erUserContext.ImpersonateUser erUserSiteAuthenticator, erParamTypeID

bIsValid=erAuthenticator.ValidatePassword("login", "password", "someaddress")   'always specify an ip address in case of lockout.

IDispatch Unification (renamed properties)

Several eRoom SAAPI objects implement multiple COM interfaces. (For example, all eRoom Items implement multiple interfaces--Folder Page implements IERUItem, IERUContainer, IERUTopic, IERUPrincipalItem, IERUFolderPage.) When accessing objects via a scripting language, calls are made by name via IDispatch.

As of V.7, every SAAPI object has exactly one IDispatch interface. In the case of objects that implement multiple interfaces, such as FolderPage, the IDispatch interface contains the union of all methods and properties in the implemented interfaces.

This means that scripting languages can access any method or property on an object directly, without using the now-obsolete interface accessor properties (for example, IERUItem::FolderPage returned an IERUFolderPage interface). This is no longer necessary in scripting languages (VBScript/JavaScript or other IDispatch-calling languages), since all properties from the union of all interfaces implemented by an object are accessible directly by name via the single IDispatch interface. Languages that support QueryInterface (for example, VB or C++) should use Queryinterface instead of these obsolete interface accessor properties. (The VB Set statement, when assigning a value to a typed interface, calls QueryInterface.) Each object has its own unique IDispatch interface, whose name is formed as follows: ”r;DERU” + <object name>. In the case of the folderpage item, VBScript TypeName(object) function will return:
”r;DERUFolderPage” rather than ”r;IERUItem” as it did prior to V.7.

Several properties' names had to be distinguished from properties implemented by other interfaces to allow them to be called via Idiapatch in scripting languages. The following have been hidden and a newly-named property added to replace them. Note that for compatibility the old properties still behave as they used to when called via a typed interface. The new names should be used rather than these now-hidden properties.

Note that the facility object no longer implements the IERUMemberManager or IERULicenseManager interfaces directly, so you cannot simply query the interface for them. Instead, you must use the ::MemberManager and ::LicenceManager properties to obtain a Member Manager or License Manager object. This should not affect users of scripting languages. Due to changes in the eRoom member model, facility-level license and member manager objects pass through to the community level.

It is always best to use early binding by employing specifically typed interface variables. (For example, always use IERUItem, IERUContainer, IERUTopic rather than VARIANT or Object.)

For example:

Dim FolderItem

Set FolderItem =SomeRoom.GetItem(sSomeID)

Response.Write FolderPage.Name + ”r; (name)<br>”

Response.Write CSTR(FolderPage.Items.Count) + ”r; container items(s)<br>”

’r;#  New property name is TopicItems to avoid conflict with IERUContainer::Items

Response.Write CSTR(FolderPage.TopicItems.Count) + ”r; topic items(s)<br>”

SAAPI Error Handling

Note that in V.7, all error messages have been localized in SAAPI. The error messages returned in V.7 may be different than those in prior versions. However, the error numbers are unchanged.