Introduction

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 Memo form) 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.

Back to top

How the CSLD task modifies a Notes document

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:

• CSNDArchiveID
• Archive and retrieve status field (in our example, this is $ContentIcon)
• CSLDIsStub

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.

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.

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.

Back to top

Initial preparation of the mail template

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 (CSNJobSamples and 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:

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.

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.

Back to top

Adding an archive button to the Memo form

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.

Now add an archive action with the Lotus script code depicted in Listing 1:

				
' 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.

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.

Back to top

Adding automatic retrieval to the Memo form

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.

				
' 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 retrieveDocumenttoDoc and 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.

				
' 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

The 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.

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.

				
' 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 PostOpen event.

Back to top

Summary of template customizations and sample screenshots

Find below a complete list of the items that have been customized in our example:

Script libraries:

• Add CreateCSNJobs
• Customize CreateCSNJobs to reflect the CSLD database name and location
• Add CSNJobSamples

Memo form (and Reply form) :

• Add CSNJobSamples script library use to (Globals) options
• Add Archive action
• Add WaitRetrieval sub to the (Globals) definition
• Add ReloadPage sub to the (Globals) definition
• Modify PostOpen event

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 12 shows the unarchived document with the CSLD Archive button. A simple click by the user triggers archiving.

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.

Back to top

Downloads

Description	Name	Size	Download method
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

Information about download methods

Resources

Learn

• "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.
  
  

Discuss

• Join the ibm.software.content-manager newsgroup and discuss DB2 Content Manager.
  
  
• developerWorks blogs: Get involved in the developerWorks community.
  
  

About the author

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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• How the CSLD task modifies a Notes document
• Initial preparation of the mail template
• Adding an archive button to the Memo form
• Adding automatic retrieval to the Memo form
• Summary of template customizations and sample screenshots
• Downloads
• Resources
• About the author
• Comments

Next steps from IBM

• Try: DB2 Enterprise
• Demo: Create an electronic form solution with DB2 pureXML and Lotus Forms
• Community: DB2
• Buy: DB2 Enterprise

Dig deeper into Information Management on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers