Programmer's Guide:
Using Custom Commands

What Are Custom Commands?

Custom commands are server-level custom pages written in ASP that are registered with particular items within an eRoom. A button with the command's name appears in the command bar of any item with which it is registered. When an eRoom user clicks on the custom command button, the custom command's ASP page is invoked. Any eRoom item with an itembox can have up to five custom commands registered against it. Note that custom command buttons are displayed in Detail view mode only.

You can write custom command pages in order to implement specialized behavior in an eRoom. For example, you can write a custom command that tallies a particular column in a database and posts the results in the comments section on the database summary page.

You can also use custom commands to make Documentum functionality available from within the eRoom user interface. In this context, the ExternalSession property is particularly helpful, as it returns an object representing a connection to external storage.

Developing Custom Commands

Developing a custom command on an eRoom server consists of two steps:

• Writing the custom command

• Installing the custom command

These steps are explained in the following sections.

Writing Custom Commands

There is an example of a custom command ASP file in the eRoomServer\Toolkit\Samples\CustomCommands subdirectory. It is called MyCustomCommand.ASP. Use this as a guide when writing your custom commands.

There are two required components of an ASP custom command page. You must include eRoomCustomCommand.asp and you must define a Sub Main() method. This is how eRoom is able to call into the custom command page when the custom command button is clicked. Implement your custom command inside of the Sub Main().

Sub Main() takes a single parameter, which is an IERUCustomContext interface. IERUCustomContext contains information about the item(s) selected for custom command execution.

When your Sub Main() is finished executing, eRoom will automatically redirect to the current eRoom page.

As an example, here is skeletal code for a custom command ASP page:

<%

’r; Skeleton Custom Command File

%>

<!--#include virtual="/eRoomASP/EN/eRoomCustomCommand.asp"-->

 <%

’r; Entry point for the Custom Command. You are provided with an
’r; IERUCustomContext

’r; interface in the Context parameter.

Sub Main(Context)

’r; Implement your custom command code here.

End Sub

%>

If you are displaying information, you can further enhance your custom command by making it look like an eRoom dialog. See the Dialog Toolkit section under Customization in the eRoom help for more details.

Security

While writing your custom command, follow these guidelines to guard against your commands being used for malicious purposes.

• Always use the IERUCustomContext to access eRoom data.

• Always verify that the user identified by the IERUCustomContext has the right to execute your command.

• Always verify that the command can be executed against the selected item(s).

Redirection and Linking to Custom Pages

You can build URLs to execute eRoom custom commands using the ERGetExtensionURL(extensionid, fname) function from SAAPIUtils.asp.  eRoom uses the ”r;Ctxt” and ”r;CmdTarget” querystrings to determine the execution context of the custom command. A custom command must be enabled in the context in which it’s executed. An empty Ctxt querystring is taken as site level so a command must be enabled at site level if Ctxt is missing or empty. To specify a context that contains a specific facility, room, and item, use the following format:
 

”r;Ctxt=.<facilityURLName>.<roomURLName>.<itemID>”

For example:
 

”r;/eRoomASP/Extensions/eRoomSample.MyCustomCommand/ MyCustomCommand.ASP.asp?Ctxt=.Specs.Functional.0_9f”

The above example identifies the ”r;Specs” facility, ”r;Functional” eRoom, and ”r;0_9f” item id. An empty itemID signifies the eRoom’s homepage. eRoom will use Ctxt as the command’s target and by default, will return to this location. By adding ”r;CmdTarget=<targetID>” where <targetID> is the itemid of the command target, you can act on a specified item and eRoom will return to the current item (as defined by Ctxt).

Installing the Custom Command

Once you’ve finished writing your custom command, you must deploy it on the eRoom Server. Follow these procedures in the Configuring Your Server Extension topic.