Publications

Programming with the Domino.Doc API
by Rick Ross

Do you need to interface Domino.Doc and Lotus Notes? Would you like to create Domino.Doc documents from an agent? If so, you need to understand the objects of the Domino.Doc API. Here, I cover installation of the Domino.Doc API and review some of its basic functions. Note that Domino.Doc terminology differs from that of Notes (see "Domino.Doc Hierarchy and Terms," below).

Installation
To install the Domino.Doc API, you need a Lotus Notes client version 4.6 or later installed on the computer where the API is being installed, and you must have access to a Domino.Doc server.

There are two steps to installing the Domino.Doc API. First, download the Domino.Doc Client Software by clicking Library Administration in the Domino.Doc Library within the client. Then click Download Client Software (Figure 1) and the link Download Lotus Domino.Doc Controls software (Figure 2). You'll see the DdbindX.EXE icon. Click this icon and save it to the root directory. After doing this, you can run the DdbindX.EXE and follow the instructions on the screen.

The second installation step is easier. Click the Ddsetup.EXE icon (as shown in Figure 2). Save this and run the install. These two .EXE programs let you use the Domino.Doc API and the Binder objects in the script that you'll use to interface with the Notes database.

An Integration Example
Now we can get into the programming. For this example, we'll import data from a Notes database to Domino.Doc with an agent written in the Filecab.NTF. It's a good practice to always write your agents in the Filecab.NTF and then refresh the design of the file cabinet .NSF where the agent runs. This keeps all your work in one place, from which you can move it to new file cabinets.

Also, when you refresh the design in the file cabinet, remember to do the same in the duplicate database that Domino creates. For example, if you create a new file cabinet named Test, Domino.Doc will create one file cabinet named "Test" and another named "Test 1." You must refresh both of these to run the agent.

The first step in programming the interface is to Dimension (Dim) the Domino.Doc API object and Binder objects in the declaration section as follows:

Dim theAPI as Variant
Dim theLibrary as Variant
Dim theFileCabinet as Variant
Dim theDocs as Variant
Dim theNewDoc as Variant
Dim View as NotesView
Dim Doc as NotesDocumentNote that we also include the Notes View and Document here.

Now that we have used the Dimension action for all the objects that will be used in Domino.Doc, we need to learn how to use them. In the Initialize section, we perform a Do Until loop to pull in all documents from the view in the Notes database (Figure 3). Here, we construct the library URL for Domino.Doc to let the program know the server where Domino.Doc resides and the library name we're going to use. Note: It's a good practice to use this same coding as a standard in every agent you write in Domino.Doc.

Next, we need to pull in some information from the Notes database to know what binder this document goes in. In this example, we use the form name "Test" and save the data into the Binder named "Test." The code for this process appears in Figure 4. Let's break this code down.

Line 2 defines the BinderName to the correct Binder (Test, as referenced above).

Line 3 sets the BinderName equal to the File Cabinet Binders. Note: If the binder doesn't exist, this line will cause an error.

Line 4 sets the Domino.Doc document equal to the Binder documents.

Line 5 sets the New Document to be added to the Binder.

Line 6 sets the File Cabinet's Profile using the Profile that was set up at the time of File Cabinet creation. We need this profile to get the Document Type required to store the Notes data in Domino.Doc.

Now we're ready to create our first document in Domino.Doc. The first step is to set up the Document Profile, which defines the document type that we're using. To do this, we write the code as follows:

Set theNewDoc.Profile =
theFileCabinet.DocumentProfiles("Test")Then we import the Notes form data field by field and save it in the Domino.Doc Document with the following code:

thenewdoc.profile.fields("FieldName").Value
= DOC.FieldName(0)(We've substituted FieldName for the correct field name on both forms. It's a good practice to keep the Notes field name and the Domino.Doc subform field name the same to avoid confusion.)

After you've done this for all the fields you need to import, the next step is to save the document in Domino.Doc. Remember: In Domino.Doc, all documents must be checked in or they'll be locked and unusable by any other user. To save and check-in the document, we use the following code:

Call theNewDoc.Save
Call theNewDoc.CheckIn(1, 1, True,
"Created by Agent")The syntax for the for the check-in method is as follows:

Call theNewDoc.Checkin(revisiontype&,
action&, deleteddrafts, comment$)where

revisontype& = 1 (version) or 2 (draft)
action& = 0 (discard), 1 (replace), or 2 (draft)
deleteddrafts = True (delete the drafts) or False (keep the drafts)
comment$ = a comment about the revision

More to Learn
Domino.Doc is very powerful and can interface with Lotus Notes or any relational database. But like any new software, it has a learning curve. If you're unfamiliar with Domino.Doc or you just want more information, consult the IBM Redbook Creating Customized Solutions with Domino.Doc (SG24-5658). To build on the examples that I've covered in this article, look at the Script Libraries in the Filecab.NTF.

Domino.Doc Hierarchy and Terms
Domino.Doc terminology differs somewhat from that of Lotus Notes, as Figure A shows. For example, in Notes, a Domino.Doc File Cabinet would be a Database, and Binder would be a Folder.

1997-2008 © COPYRIGHT, DATA SYSTEMS ANALYSTS, INC.

SITEMAP