Designing composite applications: IBM Lotus Notes components

This article shows how to build IBM® Lotus® Notes® components, providing some tips and techniques for using your existing Lotus Notes applications in composite applications. Learn how to use the power of composite applications to provide a context that combines information from multiple components and leverages that context when performing tasks.


Craig Wolpert (, Senior Software Engineer, IBM

Craig Wolpert is a Senior Software Engineer for the IBM Lotus Software ISV Technical Enablement program.

Jo Grant (, Senior Software Engineer, IBM

Jo Grant is a Senior Software Engineer for IBM Lotus, specializing in Eclipse-based technology.

27 June 2008 (First published 15 April 2008)

Also available in Chinese

Editor's note: This article is the sixth in a series of articles on composite applications being published on developerWorks® Lotus. See the previous developerWorks articles,"The Lead Manager application in IBM Lotus Notes V8: An Overview," "Designing composite applications: Component design," "Designing composite applications: Design patterns," "Designing composite applications: Unit testing," and "Designing composite applications: Writing an Eclipse component for IBM Lotus Notes."

About this article series

Composite applications are a key element in a Service-Oriented Architecture (SOA) and contextual collaboration strategy. They support business flexibility for companies and organizations that must rapidly respond to changing demands in today's competitive markets. Composite applications are aggregations of user interface (UI) components that are loosely coupled to support intercomponent communication.

Components can be reused in multiple composite applications. The ability to combine multiple technologies into a single application provides significant business value. It enables companies to protect and extend their existing assets with increasing degrees of flexibility, and it allows them to respond quickly and cost-effectively to their emerging business requirements with applications that are significantly easier to create than in multiple application development environments.

This loose coupling of the composite application architecture also enables diverse groups in different locations to leverage each others' efforts and to interoperate with each other. For example, one department might be working on the accounting application for a company, while another group is working on a sales lead tracking application. The composite application vision is to add to the accounting application some components from the sales lead tracking application to give pertinent views of assets in an accounting context. Similarly, the sales lead tracking application could incorporate components from the accounting application to give accounting information within an asset context. As your company develops more and more composite applications, the potential for integration increases exponentially. The goal is that the whole is greater than the sum of the parts.

IBM WebSphere® Portal developers are already familiar with the composition application model. This approach has been extended to Lotus Notes 8, enabling Lotus Notes developers to surface their Lotus Notes applications as one or more components in a composite application. IBM Lotus Domino® Designer has been extended to leverage the property broker and to provide a more intuitive user environment. Lotus Notes 8 also supports the inclusion of Eclipse components. A composite application can have any combination of Lotus Notes and Eclipse components. These components can be presented together in the same user interface (UI) for on-the-glass integration, or if extended to use the property broker, they can fully interoperate. You can define composite applications using the composite application editor or the WebSphere Portal application template editor.


The Lotus Domino Designer 8 Help discusses how to build Lotus Notes components in the section "Composite Applications - Design and Management. " The section discusses the APIs used, including an example that walks you through the creation of a simple composite application based on Lotus Notes components, and it instructs you in how to create basic components from scratch.

This article builds on that information, providing some tips and techniques for using your existing Lotus Notes applications in composite applications. We explore some of the components in the Lead Manager composite application sample for IBM Lotus Notes 8 posted on Lotus Sandbox, using our example of an existing Lotus Notes application.


This article assumes that you are familiar with composite applications in Lotus Notes, so it can be useful for you to review the introduction to the composite application section in the IBM Lotus Domino Designer Help.

You should then review the first four articles in this series, cited previously, which cover component design from a high level. They discuss domain-centric components and contextual domain components, which are meta-patterns in and of themselves.

Architectural decisions

When you approach Lotus Notes application development, you normally think in terms of forms, views, framesets, and other components. It is tempting when reconsidering your Lotus Notes application as a composite application just to take these existing building blocks and build components for each one of them.

When you look at low-level design constructs such as forms and views, you might often use one, or a number of these, to represent a single logical unit. For example, you might have several views that show a selection of data in different ways. Components for a composite application are best designed around the logical units that form an application and not the Lotus Notes design constructs that happen to be used to articulate them.

Higher-level aggregating constructs, such as framesets, pages, or outlines, are used for building up a specific user interface. These constructs are usually designed for presenting the application optimally in the Lotus Notes client or in a browser. The goal of good component application design is to design UI elements that can be used in a variety of ways, both in applications which focus on the information represented as well as in applications that might use the information only as a way to highlight information from other components. Although these two goals are not opposites, they are sometimes difficult to reconcile.

The simplest approach to componentizing your Lotus Notes application is to go back to its original abstract design. Almost every Lotus Notes application is based on one or more data element types. A data element type is a unit of information, represented in a Lotus Notes document with a collection of values. The business logic of the application defines the life cycle of these documents, how the values in them are constructed, and how the documents relate to other documents. Forms present the data to the user in specific ways. Views show collections of documents in various ways that are meaningful to the user and the workflow.

For example, the basic data element in a discussion database is an individual's contribution in the form of a document. At the document level, the data values can be the subject, the body of the document, and a number of other values, such as the author or the date composed. The business logic of the database arranges these documents into discussion threads, with a child-parent hierarchal structure. Forms show these data based on three basic types of relationships defined by the business logic: main topic, response, and response to response. There are a number of views that display these documents based on this hierarchal structure, sorted into categories, and indexed by author, by date, and by others.

There are a number of abstract ways that we can look at these elements as components:

  • Detailed information. This component displays most of the information of a single data element with the verbosity appropriate for when it is the center of attention.
  • Summary information. This component displays some of the information of a single data element with the verbosity appropriate for when it is on the periphery of attention.
  • Edit mode. This component provides a user interface for altering the content of the information of a single data element.
  • List. This component displays a collection of data elements.
  • Constrained list. This component displays a subset of data elements constrained by some factor.

This list is not exhaustive. Depending on the complexity of your application, other abstract types can arise. Similarly, some of these types lend themselves to several different implementations. If your Lotus Notes application has several data elements, you might have one or more of these abstract types of components for each data element.

This list is presented as a starting point for thinking about how you might present your Lotus Notes application as a collection of components. We now look at each of these component types in detail and discuss methods of implementation.

General component patterns

One of the challenges of creating components is to design for unplanned situations. The best components are those that are usable in the widest variety of areas; however, it is hard to be all things for all people. At the highest, most general level, we can look at how collections of components are deployed to get some guidance for our design. Two patterns, in particular, seem to occur more frequently than others: narrow and wide columns, and focus and periphery.

Narrow and wide columns

Many page layout environments let you choose among several styles. These styles often come down to adding a fixed number of narrow columns or wide columns. Because this metaphor is fairly common, it makes sense to target components for use in narrow or wide columns. This approach allows you to better gauge the UI for its target environment. For example, if the target environment is a wide column, you might use field labels to prefix fields in the same row; if the environment calls for targeting a narrow column, you might adjust it so that the prefix labels are vertically above the target fields.

In our lead manager application, on the Sales Leads page, we have three narrow column components and one wide column component. Summary information components (for example, Lead Details and Company Information) contain less information and are displayed in a compact form suitable for display in a narrow column. Similarly, if you want to display a view in a narrow column, you might choose a small number of pertinent columns of information to display. In our lead manager application, the Sales Leads Browser on the left side of figure 1 is a good example. In contrast, the Pending Leads and Closed Leads constrained tabbed views contain many columns and are suitable for display in a wide column.

Figure 1. Narrow and wide columns examples
Narrow and wide columns examples

Focus and periphery

This layout technique uses a dashboard metaphor. One central component is the focus of attention. Arranged around the edges in the peripheral vision are other components that give additional information related to the focus component. For component design, this concept lets you consider whether to design your component to be the center of attention or optimize it to add supplementary information to another central component.

In our lead manager application example, some of the large-screen-real-estate components such as Company Details (in the center of figure 2) or edit mode components are good candidates for being designed as the center of attention. Others, such as summary information or constrained list (on the bottom of figure 2), are best suited for ancillary placement because they depend on other context-setting values for their display.

Figure 2. Focus and periphery examples
Focus and periphery examples

Choosing component properties

Because each of the component types discussed here is covered in relation to a data element type, it shares a common set of properties that are exposed. Typical exposed properties are most of the fields in the data element. You should strike a balance between exposing every possible field (computed or otherwise) and only the minimum needed. The best components are reusable in areas beyond their original conception. The more properties you expose, the greater the chance for reuse and the fewer changes you need to make later.

Keep in mind, though, that too many properties can clutter the wiring UI. As a minimum, start with the properties necessary to complete the immediate task at hand. Then, add all those for which you can develop a use case. Last, document the rest of the properties in your development notes as possible future ones to expose. In this article, we call these our data model properties. In the Lead Manager Core database (lm_core_8.nsf) we select the company, contact, categories, and body fields as our data model properties.

Choosing component actions

With the exception of the edit mode component, actions are typically used to search and select a data element type. This action is common to many of the components discussed. On the simplest level, candidate actions are the Lotus Notes definitions that can uniquely specify a document: UNIDs and Lotus Notes URLs. They are the next-highest-level identifiers that an application defines that can also be used to identify a document. These identifiers are usually fields containing information such as customer names or account IDs. For speed of access, these identifiers are typically related to indexes on views. They should not, in general, be values that can return multiple documents.

If you are implementing searches that are nontrivial, it's a good practice to promote the code for doing this task into a shared library. That way, the actions in your detailed information component and all your summary information components can use the same code. There is less risk of typing errors, and the shared library provides a single point to update for changes and bug fixes.

Choosing data types

Each property or action exposed must have a data type associated with it. Forr two components to communicate with each other, the two wired elements need to be of the same data type. It's a best practice to identify a process for maintaining consistency in declared data types for use by all the developers in an organization who build composite applications.

Each element in our data model properties needs a data type assigned to it. First, check the data types defined by Notes. If your field directly corresponds to one listed there, use that one. Second, check in your own organization's registry. The greater the number of common data types that are defined across the organization, the better components interoperate. If you don't find an appropriate data type in either place, then consider defining a data type to reflect its value. If you do so, you should register it so that other developers can write components to communicate with yours.

Alternatively, if you have a field that is truly notational only, consider assigning it a generic string type. If such a field is so generally defined, then you probably don't need to publish or consume it. For example, a category is a common property that might be published by many components. Defining a category data type is a good convention for all components using a category.

Detailed information component

The detailed information component style provides full details on the referred data element. It is suitable for display in a wide column or in the center-of-attention position (see figure 3). It is typically the document rendered using the default form.

Figure 3. Detailed information component highlighted in red
Detailed Information component highlighted in red

The options for this component are as follows:

  • Properties. This option is the typical case for component properties, and those in the data model properties should be used.
  • Actions. As with properties, this option is the typical case, and the actions in the data model properties should be used.
  • Implementation. Although you can create a Lotus Notes URL that points directly to a form and use that to create a component, this action results in an empty form on top of a new document. We want to be able to bring up a specific document with that form, so we need a different approach. The solution is to create a frameset that has an almost invisible left frame and a placeholder right frame. In the left frame, we load a document that we create just to house our recipient actions. These documents accept values, do a lookup, and, if a document is found, use a combination of SetTargetFrame and EditDocument on a NotesUIWorkspace object to bring up the document in the adjacent panel.

NOTE: After the discovered document is loaded and displayed, we should also publish all the values of it to the properties we have defined. This step triggers further actions in any wires that have been connected to it.

In the Lead Manager Core database, examine the frameset called CompanyDetail to see how the frameset was put together. To review the frame properties of the almost invisible left frame, you must first make it visible. To do this, display the infobox for the right frame, and on the second tab enable Allow Resizing and on the third tab increase the Border width to a value larger than zero. Examine the action setCompanyID on the form called CompanyDetailActionPanel to see how the form that does the lookup and switch was developed.

Edit mode component

In a typical Lotus Notes application, when you want to edit a document, you place the form for the document in edit mode, displayed in full screen. In a composite application, you can improve on this by bringing up an edit mode component for the data element in a focus and periphery style page. Instead of the normal method whereby a user switches tabs or applications to cut and paste data into the document being composed, we can arrange components in the periphery of the page that have data that can be added and transmitted through wires.

In some implementations, your edit mode component is just a variant of your detailed information component. This similarity can be advantageous because you have fewer components to manage, but it can make the individual component more complex for creation, maintenance, and use. Consider the options, and decide which constraints are important for your application.

The options for this component are as follows:

  • Properties. Choose the properties to expose based on those identified in your original analysis. Unlike either the detailed information component or the summary information component, we not only want to broadcast their values when we load the component, but we also want to broadcast them as they change. You want connected components to update based on values that you are composing.
  • Actions. Return again to your analysis, and decide the best selection of actions to expose. Additionally, there should be actions corresponding to most edit fields in the form. When these actions are triggered, they update the form's value with the incoming value. For example, a purchase order form might have a cost center field. One of your periphery components could allow you to browse your company's cost centers and select one. This selected value would then update the cost center field in your purchase order. Exposing these fields as actions lets you implement this scenario. This pattern of components is discussed in more detail in the third article in this series, "Designing composite applications: Design patterns."
  • Implementation. Instead of creating a new component, you can extend the implementation of the detailed information component (see figure 3) with the edit mode component. The component parses the ID and checks for a specific mode value to signify whether the document should be opened in edit mode.

Next, you must implement the field exchange. On each edit field, you can hook the Exiting LotusScript® event. Add code there to get the new value of that field and to publish it to the property broker. For the actions, add an action for each incoming field. Get its value, and set it into the field in the form. Note that when you have several edit forms, as in the Lead Manager Core database (lm_core_8.nsf), you need to do this in each form. Common code is best stored in libraries to make things easier.

Summary information component

This component provides a selection of details on the referred data element. It's suitable for display in a narrow column or as a peripheral component. There can be several different summary components, each one giving a subset of information relevant to a particular information domain.

Figure 4. Summary information component highlighted in red
Summary information component highlighted in red

The options for this component are as follows:

  • Properties. Although only a subset of the data element's properties is displayed, there can be other components that need programmatic access to the other values. Because property publication is done at a code level, the fields are accessible even though they are not displayed. The best practice is to publish all the data model properties. This approach lets other application assemblers use a summary component to get at the extra information exposed, instead of needing to use a detailed component.
  • Actions. In general, it is a good idea to expose all the actions in the data model properties; however, it might not be necessary to implement actions relating to keys that are not displayed.
  • Implementation. The form name used to display a Lotus Notes document is stored in the form field in the document. In this case, we want to display the document in a different way than the form it is encoded to use. We cannot use the technique we used for the detailed information component. Instead, we create a specialized form that displays the subset of information we want, called a facade form. At no point are we actually going to store a document created with this form in our database. We are going to use it only to display values from another document. A very simple way to do this form is to create a copy of the original form and then delete all the fields in which we are not interested. This approach preserves as much of the UI look and feel as possible. Reuse can be possible by using subforms if the data layout is conducive to it.

We add appropriate recipient actions to this form to accept the search values and to find the appropriate document. After we have a target document, we can read the values that we want to display from it. We cannot write the values directly into the fields; instead, we make these fields computed, and we link their value to the original corresponding fields. We then mark all the original fields as hidden, allowing us to display the values without confusing the users with the underlying data.

A simple way to do this approach is to cut and paste all the fields in the form. When fields are pasted in Lotus Notes in this manner, a "_1" suffix is automatically added. Each of these new fields should be adjusted as noted previously. In our action code, we update all the original fields and direct the NotesUIDocument to refresh, to do the update.

To see how we did this for the Lead Manager Core database, examine the form called CompanySummary and LeadSummary (see figure 4) in the sample. The action properties setCompanyID and setLeadID, respectively, perform this work.

List component

This component is for listing a type of data element in a variety of ways. It is suitable for wide-column use or as a center-of-attention component (see figure 5). Most simply, it corresponds to a Lotus Notes view. Lotus Notes applications frequently include navigators that list views of multiple data-element types broken out into major sections. The most flexible strategy for designing components is to create components that relate to a single data-element type. That way, the application assembler who is interested in only one data-element type can restrict the list to that type. If more data types are needed, tabbed views can be used.

Figure 5. List component highlighted in red
List component highlighted in red

The options for this component are as follows:

  • Properties. The primary property that you want to expose from this component is the currently selected document. You can do this task by broadcasting all the properties identified in your analysis. Alternatively, you can limit it to the fields corresponding to the input search keys defined in your analysis of appropriate general actions.
  • Actions. This component should consume all the general actions. If a successful match occurs, the selection state is changed to reflect the new document. Additionally, when the new selection is made, the properties should be broadcast, reflecting the new data.
  • Implementation. Each view that is to participate in the component must be enhanced. It is common to handle two user gestures: single click and double click. The Onselect LotusScript event is a good place from which to promote the current selection (for example, single click), and the Queryopendocument LotusScript event is a good place from which to promote the open document gesture (double click). When invoked, the current selection can be derived, the document retrieved, and the properties published. Note that, because views can contain hierarchal construction elements such as twisties that refer to a category and not an actual document, you should always check to ensure that the current selection is an actual document.

    Similar to other components, actions can be created on the view to consume the defined actions and change the selection appropriately. In the case in which you have just one view for the component, you can document the URL for that view and use it to add the component to the palette in the composite application editor. When you have multiple views, you must construct a frameset. In one frame, place a selection mechanism, which can be an outline or a special form with buttons that replace the other frame with the appropriate view. The URL for the document is then the URL for the frameset.

    In the Lead Manager Core database, examine the frameset called CompanyFrameset, which has two frames: the CompanyOutline page in the left frame, which is the navigator, and a frame on the right side for the views Company By Name, Company by Revenue, and Company By Type. We decided to support only double click in these views because the CompanyFrameset component is on a page without other components. In most cases, the single-click property affects components on the page, and the double-click property would navigate to another page (maybe using a cross-page wire).

  • Debugging. An Onselect event is triggered for every focus change. The interactive LotusScript debugger picks up on the first event that occurs. Depending on your application architecture, other events might be triggered, and you might not necessarily get the Onselect event. For debugging, consider creating a manually triggered action that invokes your code for broadcasting a selection change. After the code is working to your satisfaction, you can copy it into the Onselect method for final testing and production release. Unit testing is another good approach for minimizing the number of simultaneous LotusScript events. This topic is covered in the fourth article in this series, "Designing composite applications: Unit testing."

Constrained list component

This component is similar to the list component, except that what is listed is constrained to a specific domain (see figure 6). For example, you might display data elements belonging to only a certain category, revenue range, or author. It can be designed for either wide or narrow column use. Like the summary information component, you can have several of this type constrained to different information domains. Constraints can be simple single values, or they can be a compound value or multiple types. An example of multiple types is a view constrained by category and subcategory.

Figure 6. Constrained list component highlighted in red
Constrained list component highlighted in red

An alternative method would be to have fixed constraints. You might want to have a display that shows documents only in a certain state. Purchase orders that have been closed are an example of documents in a certain state.

You can even mix and match types. For example, a constrained list component can list sales leads by status and owner, in which the state is fixed to closed, but the author is open to being wired.

The options for this component are as follows:

  • Properties. This component exposes all the same properties as the list component. Note that you should also have a well-defined value for that which you are using to nominate the currently selected record, in case no record is selected. If constraints are imposed that result in no matches, you need to be able to broadcast the fact that nothing is selected.
  • Actions. This component exposes all the same actions as the list component, but you also need to expose actions to consume the different constraints.
  • Implementation. Unlike the list component, in this case we are dealing with only a single view. Lotus Notes 8 contains built-in actions for views that make it easy to develop constrained list components. One such built-in action is FilterCurrentUIViewViaCategory. In Lotus Notes 8.0, you enable this action by defining it in the component WSDL file, but in Lotus Notes 8.x it was improved so that you enable it by setting the composite application page and component properties in the composite application editor. For more information on this feature, refer to the Lotus Notes 8.0.1 Release Notes. Because the lead manager application was originally developed for Lotus Notes 8.0, the WSDL file was updated.

In the sample, examine the views called LeadByCompanyPending and LeadByCompanyClosed to see how we did this application for the Lead Manager Core database. We discussed the built-in action previously. The single- and double-click gestures are handled in the Onselect and Queryopendocument LotusScript event, respectively. You could also add actions to the view to react to property broker actions, to read the values, and to set the selection for the view.

The component referenced in the Lead Manager application is actually a doubly constrained list implemented using a frameset, the details of which are outside the scope of this article. Instead, refer to the LeadListByCompanyByClosed and LeadListByCompanyByPending views themselves for exact examples.

Putting everything together

The components described previously were used to develop the Lead Manager sample composite application. The sample download includes a document (Lead Manager - Notes 8.pdf) describing each component, page layout, and wiring. The detailed information and edit mode components are used on the Lead and Company pages, the summary information and constrained list components are used on the Sales Leads page, and the list component is used on the Company List page.

What have we achieved?

On the surface, it seems as if we have taken the Lead Manager Core database described in the first article in this series, "The Lead Manager application in IBM Lotus Notes V8: An overview," broken it down into components, and then reassembled it from components. If the resulting functionality is the same as what we started with, what have we achieved?

In terms of raw functionality of a Lotus Notes application, we have made no steps forward. We have, however, gained the ability to arrange components in different ways to provide a context and to have different components as the center of attention. As described previously, the Sales Leads, Company List, Lead, and Company pages each have a different center of attention. A key advantage of a composite application architecture is integration with other applications, both Lotus Notes applications and other applications. For simplicity, we have discussed just one application, the Lead Manager Core database. In the real world, however, there would likely be other applications that we could leverage. Consider the following scenarios:

  • Scenario 1. The Lead Manager overview article describes how four separate Lotus Notes applications, including a discussion database, document library database, and directory, were used to develop the Lead Manager sample composite application. This new application provides on-the-glass integration of multiple applications and lets the user set context in one component, thus exposing the appropriate information in other components.
  • Scenario 2. The first scenario describes a five-page composite application combining multiple databases. As an initial step, the developers for ZetaBank, a fictional enterprise, might realize that the discussion and document library databases use the same terms for categorization as the constrained list component; that is, LeadByCompanyPending and LeadByCompanyClosed. They could create a more simple composite application leveraging consistent categorization and showing discussions and contracts with the views from the Lead Manager Core database.
  • Scenario 3. The ZetaBank fictional enterprise has a back-end system for tracking customer calls. This information is quite useful but has never been available to other applications. The developers projected this system as a series of Eclipse components and surfaced it in the Lead Manager composite application to show customer calls associated with Sales Leads and Companies.


This article has charted the steps for extending an existing Lotus Notes application into components suitable for constructing a composite application. It has also outlined some ways these components can be used, exemplified in the Lead Manager sample composite application posted on Lotus Sandbox. The included code can be used off-the-shelf for that application and can serve as the basis for making your own applications.

After you understand how to extend a Lotus Notes application to include components, the next step is to use this process on an application that includes multiple Lotus Notes databases. The power of composite applications is the ability to provide a context that combines information from multiple components and leverages that context when performing tasks. The scenarios outlined here provide some examples of composite applications integrating multiple components from multiple Lotus Notes databases and external applications.



Get products and technologies



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=Designing composite applications: IBM Lotus Notes components