Tools Guide

Chapter 17   The Lotus Notes Data Connector

The SilverStream Lotus Notes Enterprise Data Connector (EDC) enables you to bind SilverStream forms, pages, and business objects to Lotus Notes forms, views, and selection formulas.

You use a SilverStream wizard to generate a Lotus Notes-specific Data Source Object (DSO). The DSO retrieves and updates the data in the Notes database as requested by the SilverStream application objects that are bound to it.

This document provides the following information about using SilverStream to access Lotus Notes data:

    For information on writing your own DSO, see the chapter on data source business objects in the Programmer's Guide.

How SilverStream integrates with Lotus Notes   Top of page

The SilverStream Application Server acts as a Notes client to the Lotus Notes (Domino) Server as shown in the following diagram.

At design time, you use the SilverStream Lotus Notes Datasource wizard to create a DSO that obtains data from a Lotus Notes form or view. Once you have run the wizard and created a DSO object, you can bind SilverStream application objects to it.

The following table describes the types of operations your SilverStream application can perform based on the type of Notes data to which it is bound.

Notes type

Allowed access

Notes Form

updates, deletes, inserts, documents

Notes View


Notes Selection Formula


About the connection   Top of page

The SilverStream Application Server logs on to Notes as a Lotus Notes Workstation client using the that is configured by the Notes administrator. All SilverStream activity pass through to Lotus Notes as this user. You need to ensure that the has the appropriate level of access to Notes for whatever activities your SilverStream application might require. If a password is required when the SilverStream server accesses Notes, it will pop up a login dialog on the machine running the SilverStream server, not at the client. For this reason you will probably want to set up the Notes client on the SilverStream Server machine so that entry of a password is not required.

You should consider implementing some form of SilverStream login or security to ensure that the application's users are only able to access the information that is appropriate.

    For information on SilverStream security, see the chapter on security in the Administrator's Guide.

Running the Lotus Notes DSO Wizard   Top of page

Once you have installed the software, configured the server and client machines, and are sure these machines can successfully communicate, you can build your Notes DSO.

To build the Notes DSO:

  1. Start the SilverStream Server and Designer.

  2. From the SilverStream Explorer, choose Objects, then choose the New icon

    NOTE   If you the resulting DSO to be part of a specific package, make sure the package is selected before you create the object.

  3. Choose Notes DataSource Object.

    SilverStream launches the Lotus Notes Data Connector Wizard.

  4. Enter the name of the Notes server you want to access, or click the name of the server in the list box, then choose Next>.

    The list of Notes servers that is available depends on Notes that you specified for the SilverStream Application Server as described in the How SilverStream integrates with Lotus Notes.

    The wizard prompts you to choose a Notes database that contains the views, forms, or selection formula that you want to access using SilverStream.

  5. Select a database from the list, then choose Next>.

    The wizard displays all of the Notes databases located in the default data directory (typically C:\Notes\Data) as well as any subfolders. The wizard can only access databases located in the default directory.

    The wizard displays the Lotus Notes views, forms, and selection formula that are available for the specified database.

  6. Choose the View, Form, or Selection Formula, then press Next>.

  7. Specify a name for the DSO that you are creating, then choose Finish>.

    SilverStream constructs the DSO within the current package, then updates the Main Designer to display the names of the business objects that the wizard creates.

About Wizard-generated objects   Top of page

The Notes DSO wizard creates a data source object that SilverStream uses to convert Notes forms, views, and selection formula to data that looks relational (rows and columns).

For each Lotus Notes form, view, or selection formula, SilverStream creates a single DSO which retrieves the data from the target Notes database. The DSO contains generated code in the General Imports section and the invokeQuery event. In most cases, you should not edit the wizard-generated code. However, if you want to access a single record by its Notes document ID, you must make a few minor changes to this code. The changes are described in Working with document queries.

Here's a summary of what the generated code does:

About the agNotes object   Top of page

The m_agNotes object is a custom SilverStream object that is responsible for accessing and updating the Notes database. It implements the AgiDataSource interface and makes the calls through a SilverStream DLL to the Notes API. It manages the connection and data flow between SilverStream and the Notes database, handles the server-side data cache, and manages data retrieval and update requests. The agNotes object resides in the LotusNotesSrv.JAR file that is uploaded to the SilverStream Application Server at installation.

Binding to a Lotus Notes DSO    Top of page

Once you have built the DSO, you can bind SilverStream objects to Lotus Notes columns. You can bind a form or page to a DSO in any of the typical ways that you might bind to any SilverStream data source including:

Working with document queries   Top of page

Sometimes, you might want to access a single Notes record. You do this using Notes Document IDs. The Notes DSO wizard does not let you specify a Document ID, so you need to specify the Document ID in the invokeQuery event, or pass it on the invokeQuery() call from the form or page. To pass it on the invokeQuery() method from a form or page, the method call would look something like this:


Where "8514" is a String that represents the Notes Document ID. You then need to do some processing in the generated DSO's invokeQuery() event to pass the desired value to the agNotes constructor. For example:

  String documentID=(String) evt.getParameter(); 
  agNotes m_agNotes = new agNotes ("local", "notesTest.nsf", 
       documentID, 3); 

This example passes the value "8514" to the agNotes constructor.

Working with selection formulas   Top of page

The following code fragment demonstrates how to query a Notes DSO with a selection formula. The DSO.invokeQuery() method must be called before issuing the dso.query()

      dsoSelectionFormulaData.query("SELECT (@Contains(Status; 
       catch(Exception ex) 

Deploying a Lotus Notes DSO   Top of page

To deploy a Lotus Notes DSO:

  1. Install the Lotus Notes client software on the target server (if not already installed).

  2. Install the Lotus Notes DataConnector on the target server (if not already installed).

  3. Publish your Lotus Notes DSO object(s).

  4. Publish the forms and pages that access the Notes DSO.

Be aware that when you publish an object to another database, the original objects will reference the LotusNotesSrv.JAR that exists in the SilverMaster Database. If SilverMaster is named differently, then each of the Lotus Notes DSOs will need to be modified, otherwise they will not be able to compile.

SilverJRunner, Web pages, and applets require no software installation.

Copyright © 2000, SilverStream Software, Inc. All rights reserved.