Notes 4.6: Managing documents with the MS Office Library template

Level: Beginner
Works with: Notes 4.6
Updated: 01-Sep-97

With the release of Lotus Notes 4.0, Lotus introduced the Microsoft Office Library template. The database created from this template gives Notes users the ability to seamlessly create and save documents using Microsoft Word, Excel, PowerPoint or Paintbrush, without leaving Notes. In addition, the library serves as an electronic filing cabinet for these documents, making it easy for all members of a workgroup to locate, update, and print desired documents. Besides being a repository and point of interaction for documents created with Microsoft application software, the document library includes other important document management features. These features include archiving and review cycle capabilities.

Document Archiving moves selected documents from the Microsoft Office Library into another database. Documents can be archived based on their expiration date and/or on the length of inactivity associated with a document. By archiving these types of documents, the database remains current, making it easier to find documents containing relevant information. Most of the Archiving activity takes place in a special view in the database -- the Archiving view:

Each document author also has the option of setting up a review cycle for documents s/he creates. Review cycles can be set up as sequential -- one reviewer after another, or as parallel -- multiple reviewers at the same time. In total, there are four different review cycle styles. Each review style contains a mechanism for version control. In some cases, file locking is used to ensure the document is only edited by one reviewer at a time. In other cases, Reviewer's edits are saved in the library as response documents to the original. In all cases, a clean copy of the original is maintained. Other review cycle features include specifying allotted time for review and review completion notification. You will see the following dialog box when setting up a review cycle:

Taking a closer look at the Microsoft Office Library

The heart of the Microsoft Office Library is its use of OLE/ActiveX to embed and launch objects created with Microsoft Word, Excel, PowerPoint and Paintbrush from within a Notes document. OLE/ActiveX is a set of standards that when used in software development, allow applications to interoperate more effectively. This means that users can embed Excel worksheets or Microsoft Word documents, as well as any other objects that are OLE compliant, in their Notes documents. When you launch an embedded OLE object, the application that created the object starts and the contents of the object are loaded. On your screen you would see both the object's host application and Lotus Notes. This capability makes it easier to bring objects together in a Notes document and manage data that by its nature needs to be created and maintained in disparate applications software. OLE/ActiveX standards take this concept even further. OLE/ActiveX based applications support in-place activation and blend together the interfaces of the application used to create and edit the object with the application of the document in which the object is embedded.

Changes to the Microsoft Office Library 4.6 template

The main changes to the 4.6 template fall into these two categories:

Using ActiveX technology, Notes launches Microsoft Office applications in-place, active instead of in a separate window.
Notes creates the OLE object via LotusScript instead of through form properties.

Note:

The Microsoft Office Library (4.6) template should only be used to create new applications. Upgrading existing Document Library applications with this template is not supported.

OLE/ActiveX Features
So what does this mean in terms of the Microsoft Office Library? It means that what you see when editing a document in the library is a hybrid of the Microsoft application used to create the object embedded in that document and Lotus Notes. When you open, edit, or create one of the Microsoft documents in the library, you will no longer see a window containing Notes and a window containing the Microsoft application and its file. The Microsoft application will be contained in the Lotus Notes window and the file being created or edited will be displayed in place of the Notes document. With the exception of the File and Window menus, the rest of the menu choices will be those belonging to the object's application (Word, Excel, and so on). The File and Window menus along with the status bar will be that of Notes, and while the Notes action bar will be displayed in its usual place, the toolbar will belong to that of the object's application. The following is an example of a Word document being edited in the Microsoft Office Library:

Example Word document

Notice that the options in the File menu belong to Notes. The other menu choices: Edit, View, Insert, Format, Tools, and Table pull down to reveal Microsoft Word options. The choices that appear on the Help menu will vary with the object embedded in the Notes document. This occurs because some applications now support a merged Help menu. A merged Help menu contains help choices for both the embedded object and the host application. If only one application supports this feature, the Help menu will offer help for the object. In the Microsoft Office Library you will see a merged help menu for Word, Excel, and PowerPoint when using Office '97. Paintbrush does not support this feature; therefore, the help menu will only display help for Paintbrush. Also notice that the buttons below the Word toolbar labeled Save and Close, Mark Private, Setup Review Cycle, and Properties comprise the Notes action bar for all documents contained in the library.

Review cycles
In the course of a workday, you may produce several work-related documents. Some will be reports, others memos, and still others will be documents requiring input from several members of your workgroup. These documents could be business plans, product specifications, marketing plans, or product documentation. As the person responsible for producing a document, you will probably want to create the document and then give it to several people to review and comment on. With this document library, the review process can be accomplished electronically.

As the author of a document, you have the option to set up a review cycle for the document. Documents can be reviewed serially or in parallel. There are two types of serial reviews. The first is simply called Serial Review, the second is called Serial Review (keep all revisions). During each serial review, documents are routed to each user (sequentially) in the order specified by the document's author. If the review is a simple serial review, each reviewer makes edits to the same document. In addition, an unedited copy of the original document is also saved. When the review style selected is Serial Review (keep all revisions), all edits are accumulated into one document and at the same time, each reviewer's version is preserved as a response document.

There are also two types of parallel reviews: Document Reservations and Response Review. In a parallel review, all reviewers receive the document to be reviewed at the same time. However, they cannot necessarily all edit the document at the same time. If the review style Document Reservations is selected, a lock is enabled when a reviewer opens the document so that other reviewers will not try to edit the document at the same time. A Response Review is a true parallel review. There is no file locking and all reviewers can edit the document at the same time.

Okay, so you want to send your new product specification to five colleagues using the Serial Review style. In the past you sent out a review copy with a routing slip on it and a due date and hoped it would be passed along in a timely manner. If someone was on vacation the document either sat in their in box until you fished it out and passed it to the next reviewer, or waited there until the person returned. So what happens now? If you can get your documents reviewed electronically, can you also "nag" your colleagues and bypass absentee reviewers via computer? Absolutely! In addition to being able to select a review cycle style, you can specify a time allotment for the review. If time is not a factor, you can set the allotted time to no time limit. You can also specify the number of days to wait until moving the document to the next reviewer. Should all opinions be critical and time be of the essence, you can have reminders sent after a specified number of days.

Once you have set up a review cycle and submitted the document for review, you can keep track of its status either passively with the Review Status View, or you can ask to be notified as the document moves through the review cycle. For the specific steps for setting up a review cycle, see Getting started with the Microsoft Office Library later in this article.

Document archiving
As documents become less relevant and fall into disuse, you may want to archive them rather than permanently discard them. The Microsoft Office Library has the ability to archive documents based on your specifications. Documents can be archived because they have expired or because they have been inactive for a period of time. You can archive documents on an as-needed basis or set up an archive schedule. If you choose to archive documents on a schedule, the Periodic Archive agent will review the Archive Profile you create and move documents meeting the specified criteria into the archive database. The agent runs automatically on the server. The template sets the Periodic Archive agent to run weekly on Sunday at 2AM, but can be reset by the database manager/designer.

For your eyes only -- keeping documents private
You are the director of Human Resources and you want to create some new employee policies. Rather then working on them somewhere else and moving them to Notes when they are finished, you can work directly in the document library. To keep works-in-progress from being viewed by others, you can mark them as private. When a document is Mark(ed) Private, only the document's author can see it. Once the document is complete and ready for review you can make it public. This feature is implemented through two action buttons: Mark Private and Mark Public.

Lotus Notes documents
In addition to creating and editing documents with Microsoft applications, you can also create standard Lotus Notes discussion documents. The library contains forms found in a basic Notes discussion database. They can be used instead of a review cycle to gather feedback from document reviewers. They can be used to store existing Microsoft objects. They can also be used to store project-related, non-Microsoft objects. As with the Microsoft specific documents, these Notes documents can be private or public, submitted for review, and scheduled for archiving.

Getting started with the Microsoft Office Library
Follow these steps to learn how to use the Microsoft Office Library, create and edit documents, send documents out for review, and archive documents. Then, you'll learn how you can customize the library.

Creating and editing documents
From the Create menu of the Microsoft Office Library you can compose Notes documents: Document, Response, and Response to response. You can also select one of the Microsoft documents from the cascading MS Office submenu.

To create a document containing a Microsoft object:

Choose Create - MS Office, and select one of these choices: Excel Worksheet, Paintbrush Picture, PowerPoint Presentation, Word Document.
After choosing one of the Microsoft documents, the application will appear in the window and a new (blank) document will be created.
Create your document as you would had you launched the application outside of Notes.
Click Properties on the action bar to specify a title and category for the document.
When you are done, click "Save and Close" on the action bar.
Click Yes when prompted to save the document.

To edit a document containing a Microsoft object:

Locate the document in one of the library's views.
Double-click the title of the document to be edited. The Notes document will be opened, the Microsoft application that created the document will be launched, and the file containing the document will be loaded.
Make the desired changes and save the document by clicking "Save and Close" on the action bar.
Save the Notes document.

Setting up a review cycle

To set up a review cycle you must be the originator of the document and follow these steps:

Open in edit mode, the document you want to have reviewed.
Click "Setup Review Cycle" on the action bar to display the Review Cycle dialog box.
Select a Review style.
Select an Allotted time.
Select a notification method from the Notification list box.
If you would like to save these settings to be used again, select the "Save choices for next time" box.
Click OK.
In the Review Options dialog box, click the Reviewers keyword button to bring up the Name & Address book.
Select the names of the people you want to review the document and then click OK.

Your review cycle settings are now saved with the document. If you need to change them prior to submitting the document for review, you can click "Setup Review Cycle" again to display and change the existing settings, or you can clear all settings and start anew.

Clearing a review cycle

Only the originator of a document can clear an existing review cycle. To clear your existing review cycle, open the document and click "Clear Review Cycle" on the action bar. A message will be displayed telling you the settings have been cleared. If the document was never submitted for review, nothing else happens. If the document was already submitted for review, the settings will be cleared, existing reviews will be preserved, and reviewers still scheduled to review the document will be notified that they no longer need to perform the review.

Submitting a document for review

Once you have set up a review cycle, you can submit the document for review. This is done by opening the document in edit mode and clicking "Submit for Review". The first reviewer will be notified and the status of the document will change. If the first reviewer cannot be notified, you will receive a message from the Document Library.

Archiving Documents

The first step in the archiving process is to set up an Archive Profile. To do this, go to the Archiving view and click "Setup Archive." Doing so will display the Archive Profile shown below.

Fill out the profile as follows:

Select "Archive Expired documents," if appropriate.
If choosing to archive expired documents, enter the number of days after expiration that archival should occur.
Select "Archive documents which have no activity," if desired. Indicate the number of days to wait before inactive documents are archived.
You can maintain a record of the documents archived by selecting to generate an archive log. You can also include links to the archived documents in the log.

You also need to specify where the archived documents should be placed. To do so:

Click "Specify Archive Location."
Indicate whether the documents should be stored locally or on the server.
If you have chosen to locate the archived document on the server, you will be prompted to select an available server.
Finally, enter the name of the database that will hold the archived documents.
Click OK.

The archive database will be created, and the profile will be updated to show the name and location of the database used for archiving purposes.

By default, the Archive Profile's editor is the person who authors the profile. However, other names can be added by placing your cursor at the end of the field and typing them in.

Now, save the profile by clicking "Save Profile." Then, click Close to close the profile and return to the Archiving view.

Activating Archiving

Document archiving can be activated manually or on a schedule.

To activate archiving on an ad hoc basis, simply go to the Archiving view and click Archive Now. The action checks the profile for the location of the archive database and then runs the Periodic Archive agent. If you would like to setup an Archive schedule follow these steps:

Go to the Archiving view.
Click the Enable Scheduled Archiving action button.

The action will verify that an Archive Profile exists and then run the Periodic Archive agent. If you have not already set up a profile you will be prompted for the information needed to archive the selected documents. The archive schedule can be disabled at any time by returning to the Archiving view and clicking the Disable Scheduled Archiving action button.

Document Expiration

If you would like to archive documents that have expired, they will first need to be marked as such. To mark documents as expired:

Select the documents whose topics have expired.
Choose Actions - Mark/Unmark Document as Expired.

Notes documents (non-Microsoft documents) are edited to indicate that the main document and its responses were marked as expired. The date and time they expired are also indicated. All documents marked as expired are displayed in the views with a clock icon to the left of the title.

Marking Documents Private/Public

All documents are Public unless they are explicitly marked as private. To mark a document as private and display the lock icon next to the title, follow these steps:

Open the document to be marked in edit mode.
Click Mark Private on the action bar.
Save the document.

To make the document public once again:

Open the document to be made public in edit mode.
Click Mark Public on the action bar.
Save the document.

Customizing the Library

There are a number a ways in which the Microsoft Office Library can be customized. They include:

Creating a full text index
Creating product-specific views that work off of the value of _ViewIcon
Incorporating non-Microsoft OLE applications into the library
Setting a view icon for attached files in the Notes documents

When considering other customizations to this database, keep in mind that all of the forms used to create documents (non-response) contain the DocumentWorkflow subform. This subform not only contains fields, but the action bar and LotusScript that controls each document's work flow. Caution should be exercised when adding actions and events to individual forms. As the first two suggested customizations are standard Notes features and well documented in the Notes online help, I will not address them here. I will show you how to make the last two enhancements suggested above.

Customizing the Microsoft Office Library to work with other OLE and ActiveX applications

In order to customize this library to work with objects created by other application software, the applications in question must support OLE/ActiveX and be server applications. The Microsoft Office Library contains one form for each type of document to be created. Each form contains four fields that identify the object to be embedded in the document. These fields are: $OLEObjProgID, $OLEObjField, $OLEObjRichTextField, and _ViewIcon. The _ViewIcon field is a numeric field that identifies the column icon to be displayed in views next to the document's title. The $OLE fields are text fields that identify the object and the properties to be enabled when it is launched.

$OLEObjProgID tells Notes which object to launch when the document is opened. You specify the object by entering its class name as the default value for the field. For Microsoft Word, the value for this field is Word.Document. To find the values for other objects, look in your Registry under HKEY_CLASSES_ROOT. There are likely to be several entries for each object. The object should also be registered as Insertable. If the object supports ActiveX, there will be a DocObject entry in the registry as well. Caution should be exercised when reading the registry and when trying the values found in the library's forms. You should also experiment with a local copy of the database and save all work before creating a document that embeds an object based on a registry value.

The value you place in $OLEObjProjID is referenced in the LotusScript routine that actually creates the object when the document is created. This routine is stored in the Script Library named OLERoutines. The name of the subroutine called when the document is created is GetOrCreateOLEObject. The line of code that creates the object is:

Call uidoc.CreateObject("OLEObject",note.~$OLEObjProgID(0),"")

OLEObject is the reference name for the object being created, while note.~$OLEOjProgID(0) represents the type of the object that will be created.

The fields $OLEObjField and $OLEObjRichTextField contain the values "OLEBody" and "Body" respectively. These fields are used internally by Notes to set the properties of the OLE object. $OLEObjField is the name of the field where the OLE object is stored, and it tells Notes to size the object to fit the window when the object is launched. $OLEObjRichTextField is the name of the field where the Notes rich text representation of the object is stored when the document is saved. By doing this, users who don't have the OLE application used to create the object can still read the document.

You can also use this technique to customize this library to work with most OLE objects. SmartSuite '97 users can create a SmartSuite Document Library even though Word Pro is the only OLE application in the suite that supports DocObject. When documents containing Word Pro are opened, Word Pro will activate in the Notes window, share its menus, but look and act as though WordPro is running as a stand-alone application. When documents containing Approach, or Freelance are opened, the respective applications will be launched in a separate window. The following list shows the values you can use for the $OLEObjProgID and _ViewIcon fields, respectively, if you would like to customize this template to work with SmartSuite.

WordPro
WordPro.Document
1711
1-2-3
Lotus123.Workbook
135
Freelance
Freelance.Document
137
Approach
ApproachApplication
138

Note that both in the Microsoft Office Library template and the examples given for SmartSuite, the class name referenced is generic, or nonversion specific. In the case of 1-2-3, I use the registry value Lotus 123.Workbook instead of Lotus.123.Workbook.97. This makes the library work for users using SmartSuite 96, as well as SmartSuite 97 and Word 6 (versus Word 7). However, the way the library works with each version will vary if the OLE support in each version is different.

Customizing the Lotus Notes document

If you choose to use the Notes document to embed existing document objects, you may want to mark it so that a corresponding view icon will appear next to the title. The easiest way to do this is to place a formula in the Querysave event of the form named Document. Because the formula displays a dialog box for the document author to interact with, you will need to create a form to hold the contents of the dialog box. In this example, the form is named "Attachment", and looks like this:

and displays this dialog box for the document author to respond to:

Next you need to place three hidden fields in the Form named Document. Let's call these fields Attachment, AttachType, and _ViewIcon. Attachment and AttachType are both text fields. _ViewIcon is a numeric field already found in other forms in the library. These fields are left blank by default. Then in the Querysave event in the Document form enter this formula:

form := "Attachment";
NumAttach := @Attachments;
@If(
NumAttach > 0;
@If(
Attachment = "No" | Attachment = "";
@Do(
@SetField("Attachment"; "Yes");
@DialogBox( form ; [AutoHorzFit] : [AutoVertFit] : [NoCancel] : [NoNewFields] ; title );
@If(
AttachType = "Bitmap";
@SetField("_ViewIcon"; 121);
AttachType = "Corel Draw";
@SetField("_ViewIcon"; 122);
"");
"" );
""
);
NumAttach = 0;
@Do(
@SetField("_ViewIcon"; 0);
@SetField("Attachment"; "No")
);
"")

When the document is saved, this formula first checks to see if the document contains any attachments. If no attachments are found, _ViewIcon is set to zero and Attachment is set to "No". This is important because an existing attachment may be removed from a document at some point in time, and the fields that control the appearance of the dialog box need to reflect the true state of the document. If _ViewIcon and Attachment were not reset and a new attachment was then added to the document, the author would not be able to specify the attachment type.

If attachments are found and the Attachment field is blank (this is a new document) or set to "No", the document has never been saved with this attachment and the author needs to specify the attachment type. A dialog box is presented so the document author can select an attachment type. To transfer the selection from the dialog box to the document, the two must share a field name. The list element in the dialog box is named AttachType to match the field in the form used to create the document. Once the author makes a selection in the dialog box, the selected value is transferred to the document, and based on the value of AttachType, the value of _ViewIcon is set.

[go to Interview: Managing documents with the MS Office Library template]