Lotus: Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar

THEMES: Lotus\Notes/Domino 8 | Lotus\Composite Appl...
YEAR: 2007
Login Login
User: Anonymous

LABEL: Composite Application | Lotus Notes 8 | Lotus Notes API

Comments/attachments: Close
Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar

Level: Intermediate

Brian Leonard, Lotus Notes Client Developer, IBM

24 Apr 2007

The new architecture of IBM Lotus Notes V8 enables a wide range of new ways to extend and customize the user experience using Eclipse plug-ins. This article describes how to access and how to create Lotus Notes content from within this new model.

In a recent article, "Extending the IBM Lotus Notes V8 sidebar and toolbar," we looked at how to extend the user experience in IBM Lotus Notes V8 by adding components to the sidebar and toolbar of the client. Specifically, we added the SideNote and QuickNote applications, which tackle the problem of storing and managing bits of text. The plug-ins we created are good examples of how to place your own components in those locations.

If you use SideNote and QuickNote, you may think of them as two more silos in a world where your critical information is already spread across several silos. If you use the Lotus Notes journal, in particular, you may not see the value when all your information is within your journal.

If you build your own component, you may meet a similar obstacle. You can do only so much without interacting in some way with the data and systems you already have. Fortunately, the programmability model available in Lotus Notes offers a wide variety of ways to interact with the systems you use. For instance, any system that offers Web services can easily be integrated in almost any way that you require. An application that provides a Java interface or library may be even easier to work with.

IBM Lotus Notes has the Notes.jar library for interacting with Lotus Notes databases and documents. This article explains how to use this library and other techniques to extend the functionality of your new components.


First, you need to install the Lotus Notes V8 software.

Then you need to set up Eclipse, which you can download at no charge. You then need to set up Eclipse to work with the Lotus Notes environment. The following steps assume you installed Notes to the default location of C:\Program Files\IBM\Lotus\Notes and have a data directory of C:\Program Files\IBM\Lotus\Notes\Data. If your environment is slightly different, use your location in each place.

Start the Eclipse IDE, and set the target platform by doing the following:

1. Choose Window - Preferences.
2. Expand Plug-in Development.
3. Select Target Platform.
4. In the Location edit control, type or browse to C:\Program Files\IBM\Lotus\notes\framework\eclipse.
5. Click the Reload button, and then click OK.

Next, you create an additional installed JRE:

1. Choose Window - Preferences.
2. Expand Java.
3. Select Installed JREs.
4. Click Add.
5. For JRE name, enter Notes JRE.
6. Enter or browse to C:\Program Files\IBM\Lotus\notes\framework\rcp\eclipse\plugins\com.ibm.rcp.j2se.win32.<version number> for the JRE Home Directory.
For Lotus Notes Beta 3, this value is: com.ibm.rcp.j2se.win32.x86_1.5.0.SR4-200705170110
(NOTE: This populates JAR files to the lower part of the pop-up box.)

Next, you create a new runtime configuration by following these steps:

1. Choose Run - Run, and then select Eclipse Application.
2. Right-click and choose New.
3. Enter a name (for example, Notes).
4. Under Program to Run, select Run a product, and then select com.ibm.notes.branding.notes.
5. In the Runtime JRE, select Notes JRE.
6. In the Arguments tab, enter the following in the Program arguments text box:
-personality com.ibm.rcp.platform.personality
-product com.ibm.notes.branding.notes

Enter these arguments in the VM arguments text box:

Next, follow these steps to complete the runtime configuration:

1. Click Variables.
2. Click Edit Variables.
3. Click New.
4. Enter notes.install for the name.
5. Enter the path where you installed Notes for the value, and then click OK. This path should not have any spaces in it. For example, if you installed to C:\Program Files\Lotus\Notes, your notes.install value should be:
6. Repeat steps 1 to 3.
7. Enter notes.data for the name.
8. Enter the location of your data directory for the value, and then click OK. For example, use the default:
9. Repeat steps 1 to 3.
10. Enter rcp.base for the name.
11. Enter the version of the folder name for com.ibm.rcp.base plug-in that is installed for the value, and then click OK. To do so, go to the following location: <notes install location>\framework\rcp\eclipse\plugins. There is a folder that looks like com.ibm.rcp.base_6.1.1.<date>.
For example, in Lotus Notes Beta 3, this value will be:
12. Click OK, and then click Cancel to the Select Variable dialog box (if you click OK to select variable, it adds the variable at the insertion point).

To enable Notes security from the IDE, you need to uncomment two lines. In <notes install location>\framework\shared\eclipse\plugins\com.ibm.notes.branding_3.0.0.<version number>\notes_plugin_customization.ini, uncomment the following two lines by removing the leading # character:

Now, select Run/Debug to launch Lotus Notes.

Finally, download the code provided with this article and unzip it to a new folder. To import it into Eclipse, you need to import the existing projects.

1. Choose File - Import.
2. Select General - Existing Projects into Workplace, and then click Next.
3. Browse and select the folder that you unzipped the code to and click OK.
4. Click Finish to complete the import process.


The SideNote application lives in the Lotus Notes sidebar and provides a place to quickly enter and save text. In the previous article, "Extending the IBM Lotus Notes V8 sidebar and toolbar," you saw how menu actions can be added to sidebar components through Eclipse extension points. Specifically, we added the Save as file and Load from file actions to SideNote as shown in figure 1.

Figure 1. SideNote and menu options

Email action

After you have typed text into SideNote, you may want to email the contents. Add a menu item as shown in figure 2 to accomplish this task.

Figure 2. Email It! action

You can accomplish this action through the APIs of the operating system, rather than through Lotus Notes APIs. Specifically, the email action uses the mailto URL protocol to create the new message.

The specification of these links, though, also allows for several other pieces of data to be passed. In particular, the action uses the ability to specify the body of the message. You can also leave off the recipient, so your link looks something like mailto:?body=It+would+be+nice+to+email+from+here.

Because Lotus Notes implements this protocol, a link like this one correctly creates a new email with the given body. All you have to do is launch the link.

As in the previous article, you implement the org.eclipse.ui.viewActions extension point to add new actions to this menu. As shown in figure 3, you include the following fields and values for the viewActions extension point:

* class: com.ibm.lotuslabs.sidenote.email.EmailSideNote
* enablesFor: *
* id: com.ibm.lotuslabs.sidenote.email.EmailSideNote
* label: Email it!
* menubarPath: additions
* tooltip: Email this SideNote

Figure 3. Plugin.xml and extension points

Thus, the com.ibm.lotuslabs.sidenote.email plug-in points to the EmailSideNote class that, according to the contract, must implement the IViewActionDelegate interface. The run method of this class retrieves the text and launches the link to create the message.

Save to Journal action

The other plug-in, com.ibm.lotuslabs.sidenote.journal, adds the action to save the contents of the SideNote to the user’s journal. The new action is shown in figure 4.

Figure 4. Save to Journal action
Save to Journal action

You can see that the same pattern is followed once again. The plugin.xml contributes to the extension point and points to the JournalSideNote class. The run method is shown in listing 1.

Listing 1. JournalSideNote run method

private SideNoteViewPart part;

// save it
public void run(IAction arg0) {
if(part!=null) {
String text = part.getText();
JournalEntry.createJournalEntry(null, text);

As you can see, the class called JournalEntry is doing all the work here. This is a helper class within the com.ibm.lotuslabs.notes.pim plug-in that handles all the interactions with Lotus Notes through the Notes.jar library.

Back to top

Interacting with Lotus Notes data

With the introduction of this new Java environment, the Notes.jar library can play an important role in client data integration. This library has been available for several releases and is now bundled in the com.ibm.notes.java.api plug-in in IBM Lotus Notes V8.

NOTE: This plug-in is not yet officially supported in Lotus Notes V8 beta, but it is available for use as Tech Preview for now.

The plug-in handles many of the complexities of working with this library including security and setting up the system variables. All you have to do is add com.ibm.notes.java.api to the dependencies in your plug-in’s MANIFEST.MF file.

Additionally, com.ibm.notes.java.api provides the NotesJob class to make it even easier to leverage the Notes.jar library. The NotesJob class synchronizes Lotus Notes thread access and is used in a similar way as the UIJob class, which synchronizes display access in Eclipse. The NotesJob class is shown in listing 2.

Listing 2. NotesJob example

NotesJob job = new NotesJob("Job description") {
protected IStatus runInNotesThread(IProgressMonitor mon) {
Session session = NotesPlatform.getInstance().getSession();
// your notes.jar code here
return Status.OK_STATUS;

Once your code is running in the NotesJob.runinNotesThread method, you can use the classes and objects in Notes.jar according to the Lotus Notes documentation and usage guidelines. In general, Notes.jar classes closely mirror those provided by LotusScript. For instance, there are classes to represent databases, views, and documents. Within these components are classes to represent the pieces that constitute them. For example, in documents, you can access field values and individual paragraphs within rich text. More information is provided in the IBM Lotus Domino Designer Help.

The additional step that may be useful is setting the BSAFE_ALLOW_REPARENT=1 variable in your Notes.ini file. With this setting, you can access the backend classes without multiple password prompts. Enabling this setting prevents the default login dialog box from appearing randomly. Normally, access to the Lotus Notes ID file is lazy, and the login prompt does not appear until a function needs access to it. Enabling this setting allows the Lotus Notes V8 Eclipse/Java process and the Lotus Notes workstation process to better coordinate access to the ID file. This prevents the default password prompt from unnecessarily appearing without compromising security.


The com.ibm.lotuslabs.notes.pim plug-in depends upon the com.ibm.notes.java.api to take advantage of the Notes.jar capabilities for working with the mail, calendar, contact, and journal applications and the documents within them.

The Applications class provides the ability to launch and to execute Notes.jar code in these applications. Each application is given an ID statically defined in the class as shown in listing 3.

Listing 3. Application types

public final static int APP_MAIL = 1;
public final static int APP_CALENDAR = 2;
public final static int APP_TODO = 3;
public final static int APP_CONTACTS = 4;
public final static int APP_JOURNAL = 5;

To launch one of these applications for the user, you pass the corresponding ID to the launch method:

This class also provides the ability to execute code in any of these databases using the execute method. You create a new IDatabaseRunnable that defines the code you want to call. This interface provides a single method:
public void run(Session session, Database database);

By using the given session and database and the Notes.jar APIs, this code is executed in a totally encapsulated way. The caller just has to worry about the code and not any of the initialization, dependencies, or NotesJobs mentioned previously. An example is given in listing 4.

Listing 4. Running code in a database

IDatabaseRunnable run = new IDatabaseRunnable() {
public void run(Session session, Database db) throws NotesException {
Document doc = db.createDocument();
// set the fields to make a task
// schedule the creation
Applications.execute(Applications.APP_TODO, "Create task", run);

Journal interactions

In this scheme, the journal is a little more complicated than the other applications because it does not have a known URL. As you can see in the internal DatabaseUtil class, both the user’s mail and contacts have had URLs defined. These are used to launch or to open the database. The journal is different, though, so the first task is to determine which database the user considers his or her journal.

As you may know, you can launch your journal from the Lotus Notes home page as shown in figure 5.

Figure 5. Lotus Notes home page

The first time you click the Personal Journal button, you see the dialog box shown in figure 6. It asks if you have a journal. If you do not, it allows you to create a new one. If you do have an existing journal, you can tell Lotus Notes where it is by clicking the Select Personal Journal button.

Figure 6. Select Personal Journal

The com.ibm.lotuslabs.pim plug-in depends upon this mechanism for locating the user’s journal. Specifically, it knows that this data is stored in the HPSettings profile document in the bookmark.nsf database. Once it finds that document, it knows the journal server and database are saved in the JServer and JDatabase fields, respectively. This lookup is done by the getJournalDatabase method in JournalUtil class the first time you try to access it.

Because of this setup, this method may be unable to find the journal database location; this can be a side effect of trying to execute code in your journal. In this case, the JournalUtil class opens a file browser window in which the user can select the local journal as shown in figure 7.

Figure 7. Select journal database dialog box

The lookup of the database needs to happen in a scheduled NotesJob thread. Because this is a background thread, you cannot launch a file browser. To browse, the executeJournalUI method is called to launch a new UIJob. Assuming the user selects a journal file, the code jumps back into a new NotesJob to update the bookmark's profile document and to run the code the caller wanted to execute. The caller enabled this multi-threaded behavior by passing in an IDatabaseRunnable object instead of asking for a Database object.

After you know the database path, it is easy to open the application to execute the code passed in. You use an IDatabaseRunnable object when you need to launch the journal in the launchJournal method. You do so by asking the given database for its URL and launching that URL; see listing 5.

Listing 5. Launching the journal

public static void launchJournal(final String description, final String append) {
executeJournalThread(description, new IDatabaseRunnable() {
public void run(Session session, Database database) throws NotesException {
String server = database.getServer();
String repId = database.getReplicaID();
if(repId!=null) {
server = "";
String url = "notes://"+server+"/"+repId;
if(append!=null) {
url += append;
DatabaseUtil.launchUrl(url, description);


The JournalEntry class, called by the SideNote action, uses these mechanisms to save the new document. The createJournalEntry method calls the execute method with the required IDatabaseRunnable. The code that gets executed only has to create a new document with all the necessary fields to make it a full-fledged journal document. This code is shown in the createJournalDocument class.

Lotus Notes interaction strategies

You may have noticed some patterns. The Notes.jar library is very good at working with the data inside databases. As you have seen, the com.ibm.lotuslabs.notes.pim plug-in illustrates using this library to read data from documents and to create new documents.

The limitation that still exists in this model, however, involves in-memory operations. Notice that when you want to create a new mail message, you do not call Notes.jar, but rather you launch a URL. This accomplishes the goal - namely, it creates a new document without saving it. Similarly, the JournalEntry class also lets you launch a new entry using the same URL launching mechanisms to show the journal itself. The limitation is that this URL cannot populate the fields of the new journal document.

There are a few ways to work around this issue. The first, if it makes sense in your application, is to create the document using Notes.jar and to save it. You can then ask for its URL and launch that. The downside of this approach is that if the data you are populating automatically is somehow incomplete, you risk leaving unfinished documents in your database.

The second option is very application dependent; it requires your database and forms to work out their own handshake. As an example, you could make it work through a pre-named temporary file. The Java code writes to that file, and then launches a new form. The form knows to look for that temporary file, reads it, populates it as necessary, and deletes the file. You can imagine several versions of this handshake.

The other option is to create your own user interface using SWT, the Standard Widget Toolkit, and to use Notes.jar to load and to save the values to the database. The JournalNote example given in the com.ibm.lotuslabs.notes.pim.ui package looks like the one shown in figure 8.

Figure 8. SWT JournalNote

The code that creates this is shown in listing 6.

Listing 6. Creating a JournalNote

public static void showJournalNote(final Composite parent,
final String url) {
IDatabaseRunnable run = new IDatabaseRunnable() {
public void run(Session session, Database database) throws NotesException {
Document doc = (Document) session.resolve(url);
final Map map = JournalNote.createValueMap(doc);
parent.getShell().getDisplay().asyncExec(new Runnable() {
public void run() {
JournalNote note = new JournalNote(parent,map);

// do it
Applications.execute(Applications.APP_JOURNAL, "Opening journal document", run);

Journal toolbar

You may have noticed that we haven’t used all the methods in the integration code. Most of it was created to support the toolbar for frequent journal users as shown in figure 9. This toolbar, contributed by the com.ibm.lotuslabs.journal.ui plug-in, allows the user to launch the journal, to create a new blank entry in edit mode, and to quickly jot down a new entry.

Figure 9. Journal toolbar

The code behind the launching of the user’s journal is the Applications.launch method that you have already seen. By passing in the ID for the journal, a URL is launched to display the database. In a similar fashion, the New button calls the JournalEntry.launchNewEntry method to show the appropriate form.

The concept of a QuickNote was described in the previous article, "Extending the IBM Lotus Notes V8 sidebar and toolbar." The journal toolbar uses the same code but instead of saving the contents in a text document, it uses the JournalEntry class to create a new journal document. The advantage of this feature is that it allows a user to record something very quickly. The added benefit over QuickNote is that the data does not create a new silo of information.


Integrating Lotus Notes data makes your work more interesting. You’ve applied these techniques to simple actions to date, but they can also be used to create any component you wish. This even includes whole IViewPart instances that can live on their own, within the sidebar, or as part of a composite application.

These simple examples of using the Notes.jar library and other techniques in IBM Lotus Notes V8 should be enough to get you started building your own components.