This article explains a sample DB2 CommonStore for Lotus Domino (CSLD) customization of a R6.5 mail template when accessing it from the Notes Client. This article focuses on minimizing the necessary user intervention for retrieval (retrieve on open) for the typical office user who works most of the time at his desk. The user typically works on the server replica of the mail box. Since the user is connected all the time, there is no issue accessing a central archive. Therefore, retrieval of the archived messages can be done directly from the central archive.
The implementation of the following functionality is described in detail in this article:
- User can archive messages (based on
Memoform) from his server mail replica
- User can automatically retrieve from the central archive on opening the message when working on his server mail replica
The modifications described in this article are done in Notes/Domino 6.5.3, Content Manager 8.3, and CSLD 8.3 Microsoft® Windows® environment. The sample mail template, together with the CSLD 8.3 configuration database, is attached in the download section and can be used as a starting point for your individual customization. It is provided on an as-is basis, without further support, similar to the sample mail template shipped with the actual product.
During the archiving and retrieval process, the CSLD task modifies the Notes document. The mail body or file attachments are changed, and there are some hidden fields added or modified during archiving and retrieval.
There are three fields that are relevant for our customization:
- Archive and retrieve status field (in our example, this is $ContentIcon)
The CSNDArchiveID property contains the unique identifier of the archived item in the backend repository. To view the hidden fields, select a document, click on the right mouse button, and select Document Properties. On the second tab (with the triangle), you get a list of the fields of the specific document, as shown in Figure 1.
Figure 1. Unique identifier of the archived item
The archive status field can be configured in the archive task profile of the CSLD configuration database, as shown in Figure 2. It is particularly useful to display the archiving status to the user in folders and view. In order to avoid a customization of folder and views in the mail database, use the $ContentIcon field that is already part of the column formula in the standard folders and views. After a successful archiving, the CSLD archiving task is configured to set its value to 48, corresponding to a CD icon. A failed archiving results in a red cross (38 as a value). Figure 2 shows the archive task profile settings.
Figure 2. Configuration of the archiving status field
Whenever the archiving task stubs a document archived as entire message, it adds the Notes property CSLDIsStub. Retrieving a document modifies the three fields listed above as follows:
The CSNDArchiveID field is preserved, whereas the CSLDIsStub field is removed since the message is no longer stubbed after restoring the entire message. In our example, the CSLD retrieval task is configured so that a successful retrieval sets $ContentIcon to 99. If the retrieval fails, the CD icon (with value of 48) is preserved. The subsequent step in the life cycle of the message is the restubbing of the message. After a pre-defined time period, the CSLD archiving task removes the mail body in Domino without archiving the same content a second time, if the CSLD job parameter
Check archive integrity is set to yes. A successful restubbing recreates the CSLDIsStub field and sets the $ContentIcon to the CD icon. (If you prefer different visual indicators, go to the Domino Designer Help, where you'll find the table showing all icons and related numbers.)
Figure 3 gives an overview of the status of the relevant document properties during archiving, retrieval, and restubbing.
Figure 3. Notes field updates during archiving, retrieval, and restubbing
In this example, we will customize a mail database that is based on the standard R6.5 mail template (mail6.ntf, template name "Mail (R6)"). The customizations are done in Domino Designer. As a first step, you need to copy two CSLD script libraries (
CreateCSNJobs) from the sample mail template shipping with CSLD (CSLDStdMail.ntf in the CSLD\data subdirectory) into your mail database, as shown in Figure 4:
Figure 4. CSLD Lotus script libraries
The purpose of these script libraries is to make the creation of CSLD jobs (archiving, retrieval, for example) as easy as possible. Instead of creating a Notes document with the necessary items for a valid job, the script library takes care that all values in the job document are set correctly. In order to do so, the
CreateCSNJobs library must be customized to contain information on the name and location of the CSLD job database. Whereas the job database is usually hardcoded in the public function
JobDatabaseName (like in the example CSLDJobs.nsf), the server name is determined by some Lotus script coding. Figure 5 shows an example where the CSLD job database is located on the same server as the mail database. Note that the code assumes that the mail database is located on a server. It would not work for a local mail replica.
Figure 5. JobDatabaseServer function in CSLD script library
In an environment with multiple Domino servers, it is a frequent design to put one CSLD job database on each Domino server. This guarantees that mail users depend only on their own server when trying to retrieve or archive a document and not on other Domino servers since the CSLD jobs are created directly on their mail server.
In order to give the user the option to archive a message manually, an action has to be added to the
Memo form. First, make the
CSNJobSamples script library available in the
Memo form so that the action can make calls to the functions in the script library. You can do so with a simple use statement, as depicted in Figure 6.
Figure 6. Make the CSLD script libraries available
Now add an archive action with the Lotus script code depicted in Listing 1:
Listing 1. Archive action
' Archive entire messages (with stubbing) ' Only available when message is not yet archived ' and the server replica is accessed ' Reinhold Engelbrecht ' October 2005 Sub Click(Source As Button) Dim session As New Notessession Dim ws As New NotesUIWorkspace Dim db As Notesdatabase Dim wsdoc As NotesUIDocument Dim doc As NotesDocument Set db = session.currentDatabase Set wsdoc = ws.currentDocument Set doc = wsdoc.document ' Parameters in 8.3: archivingType, archivingFormat, ' deleteJob, deleteOriginal, deleteAttachments, ' createDocumentStub, workbasketName, rasterOption, useCheckArchiveIntegrity Call archiveDocument(CSN_ARCHTYPE_ENTIRE, CSN_ARCHFORMAT_CSN, _ False, False, False,True, "", 0, True) Call ws.CurrentDocument.Close() End Sub End Sub
archiveDocument is a sub in the
CSNJobSamples script library that creates an archive job based on the classes and methods defined in
CreateCSNJobs . Note that clicking the archive button closes the document at the same time for ease of use. As a matter of fact, this action is not only triggering archiving, but can also be used for re-stubbing the e-mail. This means that the action should be available when the message has either not yet been archived by CSLD or already retrieved. In addition, it should only be displayed when the user works on the server replica. This is equivalent to hiding the action when the message is archived (field CSNDArchiveID is available) and not yet retrieved (field CSLDIsStub is available) or the database is local. Figure 7 shows the hide formula.
Figure 7. Hiding the archive button
Furthermore, the button has been configured to dynamically change the label from "Archive" before archiving to "Restub" after retrieval by means of the formula
@If(@IsAvailable(CSNDArchiveID); "Restub"; "Archive"). In order to test the archive action, just click the button and verify if the correct archiving request is created in the CSLD job database.
In the sample mail template shipping with CSLD, the retrieve action is implemented similar to the archive action. It requires that the user clicks on the button, closes the document, and re-opens it again. This particular design allows the user to continue his other work in Notes while the restore takes place in the background in an asynchronous mode. This is a great advantage in case of a slow retrieval, like it is the case from tape.
Some users, however, might prefer waiting for the retrieval. This means that the retrieval is perceived as interactive process in the foreground and should present the restored document directly. In our customization example, we combine these two approaches in such a way that the retrieval is a foreground process for up to 15 seconds. If it takes longer, the user receives a short notification and is no longer blocked from his work.
In addition, an automatic retrieval upon opening makes using CSLD easier since the user does not have to care about clicking a retrieval button. Combined with the foreground retrieval process, the CommonStore archive would be completely transparent to the user. No matter whether the message is archived or not, simply opening the message provides its content to the user. If the content is still in Domino, it is a simple Notes document retrieve. If the content has already been archived, the content is retrieved by CSLD to Domino and subsequently presented to the user.
Let's take a close look at how this retrieve-on-open functionality has been implemented in the example. In order to trigger an automatic retrieval upon opening, make use of the
PostOpen event that occurs after the current document is opened, but before the user has input focus. On first look, opening a document should simply trigger the automatic creation of a CSLD retrieval job.
This event is also active when non-archived or already retrieved documents are opened. This is why it is necessary to specify exactly when a CSLD retrieval job should be automatically created:
- The user works on the server replica
- The user opens the document properly, not just in the preview panel
- The document has been archived and has not been retrieved
- The last retrieval job creation has occurred more than 2 minutes ago
The first two conditions can be implemented with standard Notes properties. The third condition requires that the document has a CSNDArchiveID and CSLDIsStub item, as described before.
The fourth condition, however, is rather tricky. On first sight, it is not obvious why we would need such a condition at all. The reason for adding it relates to documents that are retrieved from tape and need more time. In this scenario, a user might re-open the same document several times to check if the document has already been restored from tape. Without this condition, each opening of the message would create another automatic CSLD retrieval request, always for the same document. CSLD would have to retrieve the same document several times, without additional benefit. This unnecessary load also has a negative impact on overall CSLD archiving and retrieval performance.
In order to avoid multiple automatic retrievals, we have added two features to this sample mail database. The first feature is a visual indicator to the user that the retrieval for a specific document is continuing in the background, but has not yet finished. This is done by setting the $ContentIcon to 107 (dark green arrow icon). As soon as the retrieval is successfully finished, the CSLD retrieval task sets its value to 99 (green diamond icon).
The second feature makes use of the CSLDLastRetrieve item. This is a timestamp that is set by the Lotus script code to the current date and time whenever the conditions above apply and an automatic CSLD retrieval job is created. A successful retrieval removes this property since the document in the archive replaces the stubbed document in the Notes database.
If a document is opened and the retrieval is still ongoing, the CSLDLastRetrieve item is used to check how many seconds have passed since the last retrieval. In the particular example shown in Listing 2, the Lotus script code permits that another job can be created after 120 seconds (or two minutes). If this is the case, the CSLDLastRetrieve item is updated with the timestamp of the latest retrieval attempt. Note that the specific value of two minutes is just an example and can be set differently.
Listing 2. Conditions for automatic retrieval
' Automatic retrieval should only be triggered if ' the document is accessed on the server, ' the document is opened properly (not just in preview), ' document has been archived, but not yet retrieved and ' the last open retrieval job is more than 2 minutes ago ' Reinhold Engelbrecht ' October 2005 Dim doc As NotesDocument Dim db As NotesDatabase Dim newitem As NotesItem Dim dateTime As New NotesDateTime( "" ) Dim retrieveInterval As Integer Set doc = source.document Set db=doc.ParentDatabase Call dateTime.SetNow retrieveInterval=120 'in seconds If (db.Server <> "" And Not source.InPreviewPane And _ doc.HasItem("CSNDArchiveID") And doc.hasitem("CSLDIsStub"))Then If doc.HasItem("CSLDLastRetrieve") Then If (dateTime.TimeDifference(doc.GetItemValueDateTimeArray _ ("CSLDLastRetrieve")(0)) > retrieveInterval) Then ' The existing CSLDLastRetrieve item is updated. Set newItem = doc.ReplaceItemValue("CSLDLastRetrieve", DateTime) Set newitem = doc.ReplaceItemValue("$ContentIcon", 107) Call doc.save(True,True) Call retrieveDocumenttoDoc Call ReloadPage() End If Else ' Since there is not yet a CSLDLastRetrieve item, it must be created. Set newItem = doc.AppendItemValue("CSLDLastRetrieve", dateTime) Set newitem = doc.ReplaceItemValue("$ContentIcon", 107) Call doc.save(True,True) Call retrieveDocumenttoDoc Call ReloadPage() End If End If
In the Lotus script code listing above, the subs
ReloadPage are called as well. Whereas
retrieveDocumenttoDoc is part of the
CSNJobSamples script library, the
ReloadPage sub is a new named procedure whose purpose is to close and re-open the current document as soon as the retrieval is finished. We need to add it since there are two types of documents in Notes: The UI document (the front-end document that is displayed) and the back-end document. If the content of the back-end document changes, there is no method available that refreshes the content of the UI document.
Listing 3. Automatic refresh
' Closes and re-opens current document so that ' retrieved content is displayed in front-end document ' Original design and coding by Ch. Desforges and ' J. Perrault, ISSL ' Enhancements by Reinhold Engelbrecht ' October 2005 Sub ReloadPage Dim workspace As New NotesUIWorkspace Dim uidoc As NotesUIDocument Dim doc As NotesDocument Dim dwNoteId As String ' Get a handle on the open document Set uidoc = workspace.CurrentDocument Set doc = uidoc.Document ' Determine the NoteID of the current document dwNoteId = doc.NoteID Delete doc Call uidoc.Close Delete uidoc ' Create new space Dim session As New NotesSession Dim db_New As NotesDatabase Dim doc_New As NotesDocument Dim uidoc_New As NotesUIDocument Set db_New = session.CurrentDatabase Call WaitRetrieval (45,dwNoteId) Set doc_New = db_New.GetDocumentByID (dwNoteID) 'Refresh document if retrieval has been successful If Not (doc_New.Hasitem("CSLDIsStub")) Then Set uidoc_New = workspace.EditDocument (False, doc_New,,,,True) End If End Sub
ReloadPage sub itself calls the
WaitRetrieval sub to do the actually looping and checking if the retrieval has already been finished. The waiting period is passed as argument to
WaitRetrieval. In this case, the wait period is set to 45 seconds. During the waiting, the user cannot do any other work in Notes. He is also informed in the message bar (with an additional dot in each cycle) about the ongoing retrieval, as depicted in Figure 8.
Figure 8. Retrieval progress in message bar
In order to check on the retrieval status, the sub retrieves the back-end document periodically. If the CSLDIsStub item is removed, CSLD has restored the document successfully. In this case, the sub does not continue the looping and exits immediately. If the retrieval is not finished at the end of the waiting period, a pop-up window, as shown in Figure 9, informs the user that the retrieval is continued in the background. Listing 4 shows the Lotus script code for the periodic check on the retrieval status.
Figure 9. User information in case of delayed retrieval
Listing 4. Automatic refresh
' Periodic check if back-end document has already ' been restored ' Original design and coding by Ch. Desforges and ' J. Perrault, ISSL ' Enhancements by Reinhold Engelbrecht ' October 2005 Sub WaitRetrieval (iLengthofPause As Single, noteID As String) Dim session As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument Dim barMessage As String Dim i As Integer Dim multiLiner As String Set db = session.CurrentDatabase barMessage="Retrieving document ." ' As soon as the CSLDIsStub disappears, exit this sub For i = 1 To iLengthofPause barMessage=barMessage+" ." Print barMessage Sleep(1) Set doc=Nothing Set doc = db.GetDocumentByID (noteID) If Not (doc Is Nothing) Then If Not (doc. Hasitem("CSLDIsStub")) Then Print "Retrieve successfully finished!" Exit Sub End If End If Next 'If the retrieval cannot be finished in the specified time interval, 'display a pop-up window multiLiner = |The retrieval from tape is processed in the background. You can do your other work in the meantime. Re-open the document later to access the retrieved e-mail. Messagebox multiLiner, MB_OK, "Retrieval status" End Sub
In order to make the template changes explained above work, you need to add first the
WaitRetrieval and second the
ReloadPage subs to the (Globals) definition in the
Memo form, as shown in Figure 10. As a last step, you need to modify the
Figure 10. Additional subs in (Globals) of Memo form
Find below a complete list of the items that have been customized in our example:
CreateCSNJobsto reflect the CSLD database name and location
Memo form (and
Reply form) :
CSNJobSamplesscript library use to (Globals) options
- Add Archive action
WaitRetrievalsub to the (Globals) definition
ReloadPagesub to the (Globals) definition
Note that no view or folder has been customized in the mail template. Since we make use of these template changes to provide functionality to the user, no Client code has to be installed on the user work stations.
Figure 11 shows the Inbox folder with documents in different status:
- Unarchived (no $ContentIcon, but paperclip due to attachment in message)
- Archived and stubbed (or restubbed after retrieval, CD icon)
- Marked for retrieval, retrieval process not yet finished (dark green arrow icon)
- Retrieved (light green diamond icon)
Figure 11 also depicts the content of a stubbed message in the preview pane. Note that the preview is usually the only way to see the actual body of a stubbed message since opening the message itself triggers an automatic and synchronous restore of the message.
Figure 11. Notes folder with various archiving and retrieval status
Figure 12 shows the unarchived document with the CSLD Archive button. A simple click by the user triggers archiving.
Figure 12. Unarchived document with CSLD Archive button
Figure 13 shows the document with the subject “Marked for retrieval". Since it cannot be retrieved in the specified waiting period, a pop-up window informs the user about the background processing. The user needs to click OK, which will also close the stubbed document.
Figure 13. Delayed retrieval with background processing
|R6.5 mail template with enhanced CSLD retrieval||sample_template.zip||3,517KB||FTP | HTTP|
|CSLD 8.3 configuration DB used in this article||sample_CSLD83Config.zip||379KB||FTP | HTTP|
"Explore the IBM Mail Management and Compliance Solution" (developerWorks, September 2005): Explore the value of the IBM mail archiving solution, the extensibility of the infrastructure to support records management/compliance, and how IBM weaves together content management, storage management, and records management into a powerful enterprise solution.
"DB2 CommonStore and its Backend Archive Options" (developerWorks, November 2003): Gain a greater insight into the backend archive options of the DB2 CommonStore product family.
DB2 CommonStore for Lotus Domino homepage: Learn more about DB2 CommonStore for Lotus Domino. Find technical documentation, how-to articles, education, downloads, product information, and more.
developerWorks DB2 Content Managment technical resource center: Learn more about DB2 Content Managment products. Find technical articles, tutorials, downloads, related links, product information, and more.
developerWorks DB2 zone: Learn more about DB2. Find technical documentation, how-to articles, education, downloads, product information, and more.
Join the ibm.software.content-manager newsgroup and discuss DB2 Content Manager.
blogs: Get involved in the developerWorks community.
Dr. Reinhold Engelbrecht is a technical sales specialist and consultant in the area of e-mail and SAP archiving. He joined IBM in 1993 and has worked in the field of Content Management since 1997. Today, he provides worldwide sales support and technical enablement for IBM's Enterprise Content Management portfolio with a special focus on CommonStore, the CM for Message Monitoring and Retention (MMR) solution, and DB2 Records Manager. He holds a bachelor's degree in Mechanical Engineering (Diplom-Ingenieur) and a doctorate from the Technical University of Vienna, Austria, as well as a master's from Purdue University, USA.