Using the Generic Browser and Symphony Spreadsheet containers in composite applications

In IBM® Lotus Notes® 8.5 and IBM Lotus® Expeditor 6.2, the composite application infrastructure has been enriched with a generic application container framework. It comes with a set of components that allow for creating powerful and flexible applications without the need to write a single line of code. This article describes the generic application container framework and provides a step-by-step tutorial to create a composite application using the browser and spreadsheet container components. Weather data, such as average rainfall, is extracted from and visualized in a chart defined in an IBM Lotus Symphony™ spreadsheet.


Erik Behrends (, Software Engineer, IBM  

From 2007 to 2009, Erik Behrends was a member of the composite application editor team based in the IBM Ireland software lab in Dublin. In March 2009, he joined the IBM Lotus Quickr services for Lotus Domino development team. He holds a PhD in applied computer science obtained from the University of Göttingen, Germany. You can follow Erik on twitter at

14 July 2009

Also available in Chinese Portuguese

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.


Composite applications are an integral part of Lotus Notes since release 8.0. They enable users to assemble loosely coupled components based on Eclipse or NSF views to an application that meets specific business purposes. This powerful technology has been extended with the generic application container framework in Lotus Notes 8.5, which introduces several container components, such as the Generic Browser, Symphony Spreadsheet, Notes View, and Notes PIM containers. Instead of being limited to a single, special-purpose task as regular components are, the container components can be configured in various ways to be used for more complex applications. For example, the Generic Browser container can be used to extract data from specific Web sites or to fill in HTML forms using data provided by other components.

Users are freed from specifying Web Services Description Language (WSDL) files when creating components for the composite application infrastructure. There are container components that leverage Web applications, spreadsheet documents, host-on-demand (HOD), and Lotus Notes views for composite applications.

The generic application container framework allows for creating powerful and flexible applications without the need to write a single line of code. This article gives an introduction to the basic concepts of the generic application container framework and its container components. To illustrate the flexibility of this framework, it is described in a step-by-step way how to assemble a sample application using the Generic Browser and Symphony Spreadsheet container components. This nontrivial sample application can be used to compare climate data for two cities through the visualization of their average rainfall data as graphs in a Lotus Symphony spreadsheet chart.


This article assumes that you are familiar with composite applications in Lotus Notes. The document Composite Applications in Notes – Benefits and Technical Overview gives an introduction and overview to composite applications. You might find it helpful to review "Composite Applications in Notes - Benefits and Technical Overview" in the developerWorks® Lotus Composite Applications wiki.

The generic application container framework

Lotus Notes 8.5 introduces the generic application container framework, which is an extension to its composite application infrastructure that has been part of Lotus Notes since release 8.0. So far, components used in composite applications come with a static WSDL file that defines the component's properties and actions. When components are loosely coupled or wired with each other, they can send data through their properties to the property broker, which facilitates the communication between components. Depending on the connections or wires between components, the property broker then feeds the received data into the appropriate actions of other components. Although components are reusable in various applications, the static WSDL file can be a limitation because it might be desirable to have additional properties and actions in different situations. Also, the design and creation of components are not trivial tasks, and especially the definition of a WSDL file is sometimes perceived as a burden. Thus, in an attempt to solve these issues, the generic application container framework has been introduced.

Container components

By providing container components that implement the generic application container framework, a new set of highly customizable components has been made available for composite applications. In contrast to regular components used in composite applications, a container component doesn't have a static WSDL file that defines its properties and actions. Instead, it features the ability to use any amount of wireable properties that can be used as properties and actions in terms of the composite application infrastructure. Thus, instances of container components can have arbitrary amounts of properties and actions, depending on the situation in which they are used.

Landmarks, events, operations

The main part that configures a container component is the concept of a landmark expression. A landmark can be configured such that it matches certain application states and that the container component to which it belongs can react to these states. For example, the Generic Browser container that displays Web sites can have a specific landmark expression that matches the currently displayed Web site. As Web sites are usually identified by URLs, a landmark could be specified to match Web sites by their URLs. The landmark expression* would match all pages found in the domain.

Landmarks in navigation

The concept of landmarks has been inspired by navigation where landmark buildings, such as office buildings, churches, or castles, are sometimes used for orientation. In terms of container components, landmarks can be used to match a specific state in the component.

When such a state (or Web site in terms of the Generic Browser container) has been matched by the landmark expression, the container component can fire certain events. All containers provide two canonic event types: data change and content complete. In the context of the Generic Browser container, the content complete event is activated when a landmark matches the current Web site and the page finishes loading. When the Document Object Model (DOM) representing the current page changes (for example, if data is entered by a user into an HTML form), the data change event fires. Next, operations can be bound to events, and they are executed when such an event occurs. The two main use cases for operations are these:

  • Receive data from the property broker and manipulate the content of the container (feed data into a HTML form)
  • Extract data from the container to be published to the property broker

Each container type specifies how the data is modified or extracted. The Generic Browser container can address elements in the DOM of a Web page by their IDs, names, or xpath expressions. As the generic application container framework has been designed in an open and extensible way, in addition to the two event and operation types mentioned above, containers can define their own events and operations.

To give an example for illustration, the Generic Browser container could use the landmark expression* to match any page in the domain. Then, it could react on the content complete event (page finished loading) and publish the title of the current page to the property broker. The publish operation could be achieved by pointing to the title element with the xpath expression /html/head/title.

Using the composite application editor (CAE), container components can be added to applications and then be configured entirely using the tooling provided by CAE. No program code or WSDL files need to be written. In the remainder of this article, a step-by-step guide to creating a sample application is given to illustrate how you can assemble a nontrivial application using container components.

Creating the climate data sample application

The following steps describe in detail how to build a sample composite application using container components. Make sure that you have Lotus Notes 8.5 installed including the composite application editor (CAE).

You will now create a composite application step-by-step that consists of two Generic Browser containers and a Symphony Spreadsheet container. The purpose of this application is to compare climate data such as average rainfall for two given locations and to visualize their data as graphs in a chart. In each of the two browser containers, the average rainfall for a location of interest can be queried using the Web site, and a Lotus Symphony spreadsheet chart is displayed in the Symphony Spreadsheet container using the location's data as extracted from

Step 1. Configure Lotus Notes for composite applications in local files and for the installation of plug-ins

You need to enable two useful options in the default installation of Lotus Notes: the ability to create composite applications in simple text files in the local file system and the option to install plug-ins into the Lotus Notes client from Eclipse update sites. To enable these options, proceed as follows. As a user with the appropriate rights (administrator or superuser), locate the file plugin_customization.ini in the framework/rcp directory of the Lotus Notes installation and open it with a text editor. Then, add these two lines of code to the bottom of that file:

Next, save the file and restart the Lotus Notes client.

Step 2. Download and install the Symphony Spreadsheet container from IBM Lotus Greenhouse

Lotus Notes 8.5 comes with only one container component type, the Generic Browser container. Additional container components can be downloaded and installed from IBM Lotus Greenhouse.

NOTE: The Symphony Spreadsheet container is part of Lotus Notes 8.5.1, so if you're using Lotus Notes 8.5.1, you can skip this step.

To download the Symphony Spreadsheet container for Lotus Notes 8.5, you need to register for a Lotus Greenhouse account at (it's free of charge) and navigate to to download the ZIP file that contains an update site for the composite application generic containers and utilities.

To install the Symphony Spreadsheet container, follow these steps:

  1. In Lotus Notes, select File - Application - Install to launch a window that guides you through the process for installing plug-ins into the Lotus Notes client.
  2. On the first pane, select Search for new features to install and click Next.
  3. Click the Add Zip/Jar Location button and navigate to the downloaded ZIP file containing the update site.
  4. Click OK to confirm the default name and URL found in the site.
  5. Click the Finish button.
  6. You are presented with a hierarchical list of possible features to install. For the Symphony Spreadsheet container, select the Symphony Spreadsheet Application Container item as shown in figure 1 and click Next.

    Figure 1. Selecting the Symphony Spreadsheet container feature
    Selecting the Symphony Spreadsheet container feature
  7. Read and accept the license agreement and click Next and then click Finish.
  8. In the confirmation window that displays, select Install this plug-in and click OK. The installation of the Symphony Spreadsheet container plug-in takes place. When you are asked to restart the Lotus Notes client, confirm by clicking Restart Now.

Step 3. Create a local composite application and open it in CAE

You now start to create the actual sample application by following these steps:

  1. Create a blank composite application as a local text file by selecting File - Application - New Composite Application in Lotus Notes.
  2. In the window that displays, enter a suitable name for the new composite application, for example, Climate, and click OK. A blank composite application is created and displayed in Lotus Notes.
  3. Open the new application for editing in the composite application editor by selecting Actions - Edit Application. CAE is launched with the application Climate in edit mode.

Step 4. Add and configure a Generic Browser container

If it is not already selected, on the component palette on the right sidebar in CAE, select the Component Library palette. Drag a Generic Browser container to the blank application panel in the center. The container loads the IBM Web site by default. To configure this component, right-click the component in the Page Navigator on the left sidebar in CAE and select Edit Component Properties as shown in figure 2.

Figure 2. The Edit Component Properties option
The Edit Component Properties option

Now, a window displays that allows you to customize this component. Follow these steps:

  1. Select the Advanced tab and edit the initialURL property by double-clicking its value (currently
  2. Enter and click Enter. This setting forces the Generic Browser container to initially load the Web site.
  3. Add a new property by clicking the Add button, name it location, and click Enter. The value doesn't need to be changed.
  4. Repeat step 3 to add another property called data and to select the two new properties to mark them as wireable.

You later use these properties to connect the Generic Browser container components to the Symphony Spreadsheet container components. After these steps, make sure that the advanced component properties look like those shown in figure 3.

Figure 3. The advanced properties for the Generic Browser container
The advanced properties for the Generic Browser container

Select the Landmarks tab to configure a landmark for this container component. On the Landmarks page, you can define landmark configurations that are patterns that match states in the container component. For instance, landmarks can be used to match a specific Web page currently displayed in the Generic Browser container and then either extract and publish data from that page or receive data through wires from other components that can then be used to populate fields in HTML forms.

Here, in the climate sample, you can define a landmark for the Generic Browser container that matches pages at the site that display weather data for a specific location and then extract the location name and a list of weather data items (for example, 12 numeric values representing the average rainfall per month in a year).

In the Type of Landmark drop-down field, select URL and click the Add Landmark button. Then, enter* in the Landmark field. Any Web page displayed in the Generic Browser container having a URL that starts with is matched by this landmark expression. The climate data for any location hosted at is represented by a URL starting with this pattern.

Next, let's configure the event that should be fired when the landmark matches. Click the Add Event button, and select ContentComplete in the Event drop-down field. Whenever a matching page finishes loading, this event is activated. As mentioned before, you want to extract the location name and its climate data from a matching page. To achieve this step, you have to define appropriate operations that are executed whenever this event is fired. Click the Add Operation button, select data and Publish, and enter xpath:/html/body/h2[1]/a[2] in the empty drop-down field on the right. Then, click the Add Operation button again to add another operation, select location and Publish, and enter xpath:/html/body/pre/table/tbody/tr[2]/td in the empty drop-down box. This sequence means that the data elements defined by the xpath expressions are selected and published to the composite application property broker through the selected wireable properties. In this case, the name of the location and its weather data items displayed in an HTML table are extracted. Make sure that the landmark configuration looks like the screen capture shown in figure 4.

Figure 4. The landmark configuration for the Generic Browser container
The landmark configuration for the Generic Browser container

Finally, to facilitate the reuse of this component, it's helpful to assign a meaningful name to it. Select the Component Settings tab, and enter an appropriate title, for example, WorldClimate1. Then, click OK to save the new component settings.

Step 5: Reuse the Generic Browser container instance

You have configured a Generic Browser container component to extract data from the Web site for a given location. As the sample application consists of two browser container instances configured for, you can now add the component to the CAE palette and thus make it available for reuse in this or other applications. Follow these steps:

  1. To add the component to the palette, right-click it in the page navigator on the left and select the Add Component To The Palette option as shown in figure 5.
  2. Confirm the message that asks you to switch to the appropriate palette.
    Figure 5. The landmark configuration for the Generic Browser container
    The landmark configuration for the Browser container

This preconfigured Generic Browser container component can now be added to the sample application with its landmark configuration that matches Drag a component named WorldClimate1 from the right to the central panel, and drop it on the bottom to the already existing component. You should now see two Generic Browser container components aligned in a vertical way.

Note that in CAE, components can be dragged on the main panel at any time to reorder them as desired. To distinguish the two components, the component added last should be renamed to a different name such as WorldClimate2. You can do the renaming by right-clicking the component in the Page Navigator, selecting Edit Component Properties, adding a new title on the Component Settings page, and confirming by clicking OK.

Step 6: Add and configure a Symphony Spreadsheet container

To add the last component of the sample application, a Symphony Spreadsheet container component, you have to switch back to the Component Library palette on CAE's palette on the right side of CAE. The Symphony Spreadsheet container can be found in the Containers category. To add an instance to the application, drag this component to the right of the two existing browser container components on the application panel.

To configure this component, launch the component properties window by right-clicking the Symphony Spreadsheet container in the page navigator. You want to feed this component with data from the browser containers; more specifically, each browser container publishes the name and the climate data of the location the user queried in the Web site. Thus, each browser container publishes two properties.

You need to create four wireable properties to consume those in the Symphony Spreadsheet container. Follow these steps:

  1. Select the Advanced tab in the component properties window and add properties with the following names: location1, location2, data1, data2. Make sure that they are marked as wireable.
  2. Download the Lotus Symphony spreadsheet file from the Downloads section of this article, and save it to the local file system.
  3. Enter the path to the file as a value for the initialFile preference.

    Thus, the Symphony Spreadsheet container loads and displays this spreadsheet, which consists of a table and a chart. The table is filled with the name and data of the location provided by the browser containers, and the chart visualizes the data. You can open the spreadsheet file with Lotus Symphony or OpenOffice for further inspection. The advanced preferences should now look like those shown in figure 6 (make sure that the initialFile preference points to the spreadsheet file in your file system).

    Figure 6. The advanced properties for the Symphony Spreadsheet container
    The advanced properties for the Symphony Spreadsheet container
  4. Click the Landmarks tab. Here, you need to configure the Symphony Spreadsheet container component so that it receives the appropriate data items from the composite application property broker.
  5. For Type of Landmark, select Spreadsheet from the drop-down list. This option is the only available type for this container type.
  6. Click the Add Landmark button. Because you do not need to distinguish different spreadsheet files, you can use the wildcard here, so enter an asterisk (*). In other words, this landmark configuration ensures that the events are fired in any case.
  7. Click the Add Event button, and select Data Change as the event type, indicating that whenever the data from the property broker changes, the operations are executed.

Because you want to receive that data sent by the browser containers, you need to create four operations using the type Receive. Create these four operations, select a different wireable property for each of them (location1, location2, data1, data2 as created in the previous step), and select Receive for all of them. Then, add the appropriate values for these operations as shown in table 1.

Table 1. Operations for the Symphony Spreadsheet container's landmark
Wireable propertyTypeValue
location2 Receive Sheet3!$A3
data1Receive Sheet3!$B2:$N2
data2Receive Sheet3!$B3:$N3

These values denote which cells in the spreadsheet should be populated with the data received through the wireable properties from the composite application framework's property broker. For example, the value Sheet3!$A2 specifies the second cell in the first row of the spreadsheet and is populated with the location's name; Sheet3!$B2:$N2 defines a range of cells that are filled with the locations' weather data (values representing the average rainfall in the 12 months of a year).

The landmark configuration should look like the screen capture depicted in figure 7.

Figure 7. The landmark configuration for the Symphony Spreadsheet container
The landmark configuration for the Symphony Spreadsheet container

If you like, you can rename this component on the Component Settings page. Click OK to close the component properties window and to save the component's settings.

Step 7: Wire the components

Now that all three components have been configured properly, the appropriate wires between them can be created to enable communication between them. The data being extracted from the Generic Browser containers is displayed in the Symphony Spreadsheet container; thus, wires need to be created from the browser containers to the spreadsheet container. Follow these steps:

  1. Right-click the browser container named WorldClimate1 in the page navigator on the left and select Wiring. The wiring window opens in a new tab in the CAE window.
  2. To create wires, drag a source property from the browser container to its corresponding target action in the Symphony Spreadsheet container. The mapping of the source properties and target actions should conform to the mapping given in table 1.
  3. Right-click the component named WorldClimate2, click Select as wire source, and create the equivalent wires using data2 and location2 in the Symphony Spreadsheet container.
Table 2. Mapping used for creating the wires
Source componentSource property Target componentTarget action
WorldClimate1 dataSymphony Spreadsheet containerSet data1
WorldClimate1location Symphony Spreadsheet containerSet location1
WorldClimate2 dataSymphony Spreadsheet containerSet data2
WorldClimate2location Symphony Spreadsheet containerSet location2
  1. Select File - Save and Close, and click Yes in the confirmation window to save the application and quit CAE.

The sample application has now been fully assembled and configured and displays its content in the main window of Lotus Notes.

Step 8: Test the application

Enter a city name of your choice in the search field of the upper browser, and click the Search button. You are presented with a list of matching places in which you can click an appropriate link. On the next page, if available, click one of the links named Average Rainfall to access the data for that location. When that page finishes loading, you see the data displayed in red in the spreadsheet chart of the Symphony Spreadsheet container. Repeat this procedure for another place of interest in the lower browser container, and you can see an additional graph in green. Figure 8 shows the visualized data of the average rainfall for the Dublin (Ireland) and Vancouver (BC, Canada) international airports.

Figure 8. Comparing average rainfall for Dublin and Vancouver
Comparing average rainfall for Dublin and Vancouver

If you want to compare more than two locations with each other, you need to add preconfigured browser containers to the application, adapt the landmark configuration of the Symphony Spreadsheet container, wire the browser components to the spreadsheet container, and modify the chart in the spreadsheet to process more data.


This article gave you a brief introduction into the new generic application container framework of Lotus Notes release 8.5. By walking through a step-by-step description, the article showed how to create a sample application using the Generic Browser and Symphony Spreadsheet containers that can compare climate data for two locations. No single line of code needed to be written; instead all the necessary assembly and configuration steps could be undertaken in the composite application editor.


Code sampleweather.ods---



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks

ArticleTitle=Using the Generic Browser and Symphony Spreadsheet containers in composite applications