Documentum Developer Program

eRoom XML Capabilities Use Case: Program Dashboard

July 2003

1/9

Introduction The Documentum eRoom product includes an interface that allows you to use XML based queries to access and modify eRoom contents. An eRoom, or more broadly, an eRoom site is represented by an XML data model and eRoom XML Query Language (eXQL) statements can be executed against it. Any returned XML reflects the eRoom XML data model. The data model includes all pertinent eRoom data including folders, discussions, data tables, members and files, to name only a few. Supported commands include the getting and setting of values (i.e. getting or setting the due date on a task in a database), creation of objects such as rooms, members and comments, member list management, and object deletion. The uses of these capabilities are numerous. In this article we take a look at the implementation of an eRoom Program Dashboard in which the eRoom XML interface is central.

eRoom Program Dashboard Projects are a common unit of work for most organizations and managers are consistently challenged to make high-stakes decisions, placing strategic bets on how to apply limited resources against only the highest yield projects. An eRoom maps naturally to a project and eRoom templates are used to provide preconfigured digital workplaces for different project types. By preconfiguring eRooms you not only provide users a familiar environment in which they can complete their work tasks in a consistent repeatable fashion, but maintaining a consistent structure allows us to programmatically access information from a number of eRooms for side by side comparison. The eRoom Program Dashboard is designed to provide programmatic visibility across multiple projects, enabling team members, project managers, and executives to track key project information from a personalized dashboard view (see figure 1 below). Users can configure their dashboard to reflect their most relevant eRoom workplaces (see figure 2 below) and the Program Dashboard installation can be configured to the specific eRoom template design. The latter configuration is facilitated through the XML based architecture and implementation.

2/9

Figure 1 – Program Dashboard Interactive Display

3/9

Figure 2 – Program Dashboard User Configuration

Program Dashboard Implementation Architecture The Program Dashboard display is created by issuing an XML query against the eRoom server and then transforming the returned XML, with an XSLT stylesheet, into the HTML display shown above. Configuration of the Program Dashboard is achieved through the editing of configuration files, one XML file and one XSLT stylesheet. Figure 3 below depicts the display process.

Program Dashboard eXQL Query

2

1 XML Content

5

3 4

eRoom Server

Config.xml Rollup.xslt Config.xslt

1. The user requests a Program Dashboard display. Note the above figure does not depict the portal; technically the user will make a request to the portal server and the portal server will make the request to the Program Dashboard. 2. The Program Dashboard application issues an eXQL query against the eRoom server, asking for general eRoom information as well as database and calendar content for each selected eRoom. 3. The eRoom server processes the request and returns the sought after data in an XML format. 4. The Program Dashboard applies the Rollup.xslt stylesheet to the XML content returned in step 3, including the indicated configuration files. (Note that some portal environments provide the capability to apply the XSLT stylesheets on the portal server.) 5. The Program Dashboard returns the resulting HTML to the client.

4/9

This architecture, where the content based functionality implemented through the eRoom XML interface, is separated from the display, has numerous advantages: • The mechanism for specifying the data of interest is completely declarative. That is, there is no need to make low level calls to access the data. A change in desired content requires a change in the eXQL query. • Customized displays are easily created with no effect on the data access code. • Business and other display formatting logic is set through XML files included in the transformation process. Again, the content access code is completely unaffected by formatting changes. • Through the SOAP support of the XML interface, eXQL queries can be dispatched from a remote machine, allowing applications such as the Program Dashboard to be installed on a machine remote from the eRoom server. • The solution is implemented using industry standard techniques such as XML, XPath and XSLT. Configuration and customization then require a developer skill set that is readily on hand. Rather than learning a proprietary API, developers must only understand the eRoom XML data model. This data model very closely reflects the eRoom user’s view of the organization of the eRoom data and, thus, requires little investment to learn. In the remainder of this article we will take a closer look at the eXQL in general, and at eXQL query for the Program Dashboard, as well as the XML that is returned from the query.

eXQL For the purposes of the query language, the entire contents of the eRoom facility (Version 6) or an eRoom site (Version 7) are represented by a single virtual XML document. The format of this XML document is described by an XML schema; those schema are distributed with the eRoom Server product. The facility or site virtual XML document defines a path to every piece of accessible data in the facility or site, so that nodes in the document can be selected using XPath syntax. Element names are fully documented in the XML Query language documentation. Issuing a query against this virtual XML document requires three things. First, the target of a query must be specified. This is a URL to the node in the virtual XML document that is to be the root of XML data that is to be accessed. Second, the user or application must supply valid eRoom credentials with the query. The eRoom security model is entirely adhered to when accessing eRoom through eXQL. And lastly, the eXQL query itself.

5/9

Target URLs A new virtual root (“eRoomXML”) is defined on the server for URLs used as targets in XML queries. The URL format for the eRoomXML virtual root uses the path through the virtual XML document to the element in question. The scope of the virtual root encompasses all of the facilities on the server (for V6; this is updated to reflect the new site architecture in V7), so after the server name and virtual root, the URL starts with the Facilities collection. After the Facilities collection, the facility is, by default, specified by URL Name. For every collection on the path, give the name of the collection and the name of a specific item in the collection. For example, the path to the eRoom with the name "myroom" would be: http://www.server.com/eRoomXML/Facilities/myfacility/Rooms/myroom.

The Query The query then consists of two things. First, the command that is to be executed and second, in the body of the command, the required elements of the specified command. The supported commands are: • getproperties • setproperties • copy and move • addmember and removemember • create • delete The body of each command varies in the required data, and all are covered in the eRoom XML Query Language documentation. The eRoom Program Dashboard uses the “getproperties” command and thus, we will say a bit more about it here. The getproperties command is used to retrieve information about eRoom items. The body of the command is a template of the information to be retrieved, using the same elements and structure as the eRoom virtual XML document. For example, the Facility has a Rooms collection, which is a sequence of Room elements. Each Room element contains child elements for the properties of the eRoom. For a collection, the query is applied to all children of the collection.

6/9

The Program Dashboard Query The following is a portion of the eXQL query that is executed against the eRoom server for the Program Dashboard application. ...

The first thing to note is that the eRoom namespace is specified, as the default namespace in this case, in the command element. The target of this query is an eRoom facility and command is getproperties. Next we see that the query accesses the Rooms collection and then each Room element in the collection. The Room element has an include attribute. The include attribute allows a query to specify, with an XPath expression, that only those items passing certain criteria will be processed and data returned. The Program Dashboard application will replace the string “RoomIDsHere”

7/9

with an XPath expression reflecting the Room IDs of all user selected rooms. For example, the following include with the XPath expression designates two rooms by ID.

The query goes on to specify that for all selected rooms the ID, Display Name, URL and several other properties will be returned. In addition to these simple properties, more complex values, such as the room Contacts and the data in a specific database are also requested. Note that an include attribute is used to limit the data returned for the “Issues Tracker” database to only the Priority and Status columns.

The XML Returned The following is a portion of the data returned from the above shown eXQL query. {93EFFEBB-9501-48E3-BD39-684603B815FD} Visionary Systems http://Oakland/eRoom/eSPM/VisionarySystems We are recovering from recent issues. erTrafficLightColorYellow Ann Silver [email protected] /Issues/Issues Tracker Issues Tracker http://Oakland/eRoom/eSPM/VisionarySystems/0_a11 31 Closed Closed Status 43 Medium Medium Priority

8/9

31 Open Open Status 43 Low Low Priority ... ...

The XML data returned from a getproperties command will always be a proper subset of the virtual XML document. In the Program Dashboard this XML dataset is then transformed, with an XSLT stylesheet, into the display shown above.

Summary The eRoom Program Dashboard is an ideal illustration of the use of the eRoom XML Query Language. eRoom Program Dashboard provides visibility across multiple projects, enabling team members, project managers, and executives to track key information from a personalized program dashboard. Designed to leverage a company’s portal environment, the eRoom Program Dashboard offers a dynamic status view of multiple projects. The eRoom Program Dashboard is available as a Professional Services offering from Documentum Worldwide Consulting. Additional information on the eRoom Program Dashboard is available on the Documentum website: http://www.documentum.com/products/glossary/eroom_program_dashboard.htm.

9/9