Server Extension Programmer's Guide:
Configuring Your Server Extension

Using the eRoom Extension Manager

Through the eRoom API, you can develop programs that extend eRoom’s functionality. For example, you might develop a custom command or a UI event handler. Once you develop one of these programs, you must deploy them and make them available for a site. In addition, you can control whether or not they are enabled for various communities within the site.

Extensions can be configured at various scopes via the UI and the API. For example, UI Events and Synchronous Events can be controlled at site and community levels. Effective Availability must be ”r;on” or ”r;on but&ldots;” at community level for an event to be fired in that scope.

Note that the DBRowChanged event does not fire unless explicitly connected to a database item via IERUDatabase::SynchronousEventHandlerID property. The eRoom UI only allows DB Process items to be connected to DBRowChanged event event though the event can be connected to any database item.

For additional information on developing and configuring server extensions, refer to the topic for the extension type within the Server Extension Programmer’s Guide book.

For extension-specific notes on configuration, see any sections that may apply to your extension below.

Placing Extension Files in the Proper Location

Once you develop an extension, you must place all of the files (ASP pages, data files, DLLs, etc.) in a primary folder. This primary folder must then be placed in the ~Extensions folder within the same eRoom 7 site file server directory that contains facility templates. Once an extension’s primary folder is placed in the ~Extensions folder, it then appears on the Extensions tab of the Extension Manager administration tool. From here, you can configure your extension and update servers so that they have access to the extension.

The primary folder pathname should take the following form: \\<eRoom7SiteFileServer>\~Extensions\<PrimaryFolderName>\

A primary folder contains the following files and directories:

 

File or Directory

Installed Location

Description

.\PrimaryFolderName.XML file

N/A

File identifies the type of extension, ID and extension type-specific settings. This file is required, and it must have the same base filename as the primary folder itself.

.\script directory

eRoomASP/Extensions/<ID>

Contains extension .ASP files

.\data directory

eRoomData/Extensions/<ID>/

Contains all graphics and data.

.\bin directory

<eRoomServerInstallDir>/
Extensions/<ID>/

Contains .dlls and other executables. Note that all .dlls are registered after deployment and   unregistered prior to removal.

.\setup directory

setup.exe or .bat file

uninstall.exe or .bat file

N/A

Contains all extension specific setup/uninstall programs. Setup.exe is run after extension files have been deployed to the eRoom server. Setup fails if setup.exe returns a non-zero exit code.

Configuring and Deploying an Extension

Use the following procedure to configure and deploy an extension.

  1. From the Windows Start menu, choose Programs > eRoom Administration > eRoom Server Administration.

The ERSAdmin window opens.

  1. Right click on the eRoom Folder.

  1. Choose Extension Manager.

The Extensions tab of the eRoom Extension Manager dialog appears.

  1. Select the newly-added extension and click Configure.

The Configure dialog appears.

  1. Enter the information or select the settings to complete the dialog.

  2. If the extension includes an XML configuration file, some or all of the settings may be supplied already.

  3. Click OK.

  4. Using the Windows Control Panel, stop all IIS services.

This is only required if you are updating extensions that contain components that are already installed/loaded on the target eRoom server. Installing or updating of ASP extensions should not require any restart of IIS.

  1. In the Extension Manager dialog, click the Update Server tab (Update Local Server for the Federated version).

  2. Click the Start button.

The newly-configured extension is distributed to the current server. The extensions can now be enabled or disabled for individual communities through the Extensions section of the eRoom Site Settings page.

  1. Using the Windows Control Panel, re-start all IIS services.

  2. Repeat steps 7-9 on all other servers in the site.

Removing an Extension

Use the following procedure to remove an extension:

  1. From the Windows Start menu, choose Programs > eRoom Administration > eRoom Server Administration.

The ERSAdmin window opens.

  1. Right click on the eRoom Folder.

  2. Choose Extension Manager.

The Extensions tab of the eRoom Extension Manager dialog appears.

  1. Select the extension you would like to remove and click Remove.

  2. Confirm the removal.

Setting Extension Availability for Communities and the Entire Site

  1. On the Extensions page of Site Settings, locate the extension you would like to make available.

  2. Specify one of the four Availability modes.

The Always off and Always on modes do not allow community administrators to change an extension for their communities. In contrast, the Off but can be turned on and On but can be turned off modes allow community administrators to determine the extensions availability for their communities.

  1. Click the Choose Communities button and specify the community or communities for which you want the availability setting to apply.

  2. Click OK.

  3. When you are finished setting availability for extensions, click Apply on the Extensions page.

Notes on Configuring Custom Commands

Custom commands can be run in any context in which they are enabled. If a custom command is not enabled for a given community, room, and item, the command will not execute.

Note: To enable a custom command without having it appear in the itembox, thinbars, or bluebars, specify an empty ’r;Display Name’. eRoom will not display a custom command that has a blank (”r;”) name. In the future, a setting will be added to control the display of custom commands.

Item types and Command replaces

The Item types and Command replaces controls on the extension configuration dialog control where custom commands are inserted in the UI. They do not restrict how or where custom command are executed. Custom commands can be configured to replace one or all of the following eRoom commands: Create, Add file, Cut, Paste, and Delete. If a custom command replaces an eRoom command, the custom command button will be displayed in the core button’s location.

Coordinators only

Commands with this option are only accessible by Coordinators or effective coordinators, such as Site and Community Administors.

Notes on Configuring Custom Viewers

File Extensions contain a list of the file extensions that the custom viewer can display. Extensions are specified one per line and must start with a period (as in SAAPI). For example, in the case of the sample text viewers, adding extensions of ”r;.txt” and ”r;.vbs” would be appropriate.

Display Mode controls how the viewer if opened: embedded, standalone and pop-up.

In embedded mode, your viewer’s class file is used to generate the body of the file embedded in the eRoom page. In the case, the viewer class object’s ::GenerateBody(Context) method is called to generate a portion of the eRoom page.

In standalone mode, eRoom redirects to the viewer’s main file to display a complete page. Pop-up mode causes eRoom to open a pop-up window using the URL of the viewer’s main file display a complete page.

Extension Manager Availability: Note that all installed extension class files are included for use by eRoom regardless of the availability of the extension in the extension manager. You must remove an extension from the site to stop its custom viewer class file from being included by eRoom.

Notes on Configuring Synchronous Events

It is critical that all synchronous event handlers be deployed to each eRoom server in a site. If an event handler fails during load or register of events, the eRoom operation that is being performed will be forced to fail. This is imperative to insure the integrity of the eRoom server and its data. For example, if any handler on the eRoom site fails to load or causes an error during registration, no one will be allowed to log into the eRoom server. This is true for any handler that is either on or off but can be turned on.

Notes on Configuring Custom UIs

Now that you can only have a single custom UI extension enabled at a time, Custom UI extensions affect the entire site and cannot be restricted to specific communities.