Copying IBM Lotus Domino TeamRoom documents into an IBM Lotus Quickr library

IBM Lotus Quickr is team collaboration software that helps you share content, collaborate, and work faster online with your teams. TeamRoom is an IBM Lotus Domino application that gives you a powerful and flexible tool for efficient information sharing and collaboration. This article describes a programming example of how you can copy documents from a TeamRoom into a Lotus Quickr library.

Lotus Domino TeamRoom documents are created from forms that users define with Lotus Domino Designer. Lotus Domino forms are very flexible and can contain fields that collect or display information; they can also contain graphics, actions, formulas, and more. As a developer, you can access these documents by programming in :Lotus Domino Designer. In this article, we use LotusScript® as our programming language. LotusScript is an embedded, BASIC scripting language with a powerful set of language extensions that enable object-oriented application development within and across Lotus software applications.

Lotus Quickr content libraries help you easily organize and share documents for your projects and teams. You can easily manage all kinds of documents and rich media files using Lotus Quickr. Lotus Quickr Content Services make it possible to create, manage, update, search, query, and delete Lotus Quickr content. These services enable developers to access and manipulate content in Lotus Quickr, using REST and SOAP-based protocols.

This article introduces a solution for leveraging LotusScript and Lotus Quickr Content Services to transfer documents from a Lotus Domino TeamRoom to a Lotus Quickr document library. On the TeamRoom side, we use LotusScript and agent technologies; on the Lotus Quickr side, we use the Web services and REST services that Lotus Quickr provides.

Prerequisites

To get the most out of this article, you should have the following:

• A basic understanding of Lotus Domino TeamRoom and Lotus Quickr
• Solid Javaâ„¢ programming skills
• A basic understanding of LotusScript and Lotus Notes® agents
• A basic understanding of Web services and REST programming methods, including Web Service Description Language (WSDL), Simple Object Access Protocol (SOAP), HTTP, and XML-related technologies

For an introduction to Lotus Quickr Web services and REST services, refer to the developerWorks® articles, "Introducing IBM Lotus Quickr Web services," and "Introducing IBM Lotus Quickr REST services."

The sample code for this article (see attachments.zip) works with Lotus Quickr 8.0 services for IBM WebSphere Portal or later and Lotus Domino 7.0.2 or later. To understand the sample code, you need a basic understanding of the Apache Axis toolkit and the Apache Abdera client toolkit.

Back to top

TeamRoom agent to transfer documents into Lotus Quickr for Java Platform, Enterprise Edition

The example is implemented using a Lotus Domino agent. Figure 1 shows a simple, high-level architecture of the agent. The agent acts as a bridge between TeamRoom and Lotus Quickr to transfer TeamRoom documents into a Lotus Quickr library. On the TeamRoom side, the agent uses selected documents and a property-mapping XML file as input; on the Lotus Quickr side, the agent invokes Java code to use Lotus Quickr content Web services and REST services to work with the Lotus Quickr document library.

In the following scenario, steps 1-3 prepare Lotus Domino and Lotus Quickr, and the other steps execute the solution:

1. Prepare data in Lotus Quickr server.
2. Deploy the agent in the TeamRoom.
3. Create property-mapping XML file.
4. Select one or two documents in a TeamRoom.
5. Launch the agent.
6. Input the Lotus Quickr server URL, username, password, and documentType name.
7. Click OK to transfer the selected document into the Lotus Quickr library.

After the agent runs, the following tasks are completed:

• Lotus Notes document is saved as a rich text format (rtf) file.
• All the attachments included in the source document are detached and saved in a separate folder.
• Properties defined in the XML file are transferred as document metadata in the PropertySheet associated with the Lotus Quickr document.

A difference between Lotus Notes documents and Lotus Quickr documents involves how they store what we think of as file content (for example, the content of a Microsoft® Word document). In Lotus Notes, this content is stored as an attachment to the form containing the document metadata. A Lotus Notes document can contain several such attachments. In a Lotus Quickr document, the file content is stored in the document itself, along with the property sheets containing the document metadata.

Back to top

Prepare the data on the Lotus Quickr server

Before you move documents from the TeamRoom into Lotus Quickr, you need to prepare the target Lotus Quickr library. For the example in this article, you follow these steps:

1. Using the Lotus Quickr home page, create a Lotus Quickr place containing a document library, which is the document library into which the documents are written. Make a note of the unique ID of the document library, which is a system-generated string with 32 characters. To find the document library ID, open the library properties from the Lotus Quickr page as shown in figure 2.
   
   
   Figure 2. How to get the Library ID
   
   
   
2. Set up the place membership and access rights in the Lotus Quickr place. The user running the Lotus Domino agent should have at least the contributor role in the target Lotus Quickr place.
3. Create a new local Lotus Quickr document type with the name DocFromNotes.
4. Create two new Lotus Quickr property sheets with the names NotesDocInfor and NotesDbInfor and add properties listed in tables 1 and 2. Use the newly created property sheets to store property values from TeamRoom documents. You can order the properties as you like. The property mapping between TeamRoom document properties and Lotus Quickr document properties is documented in PropertyMapping.xml.

5. Associate the property sheet types created in step 4 with the document type created in step 3.

Back to top

Deploy the new agent in the TeamRoom

A Lotus Notes agent is a stand-alone program that performs a specific task in one or more databases. In our example, we use a Lotus Notes agent that runs on the Lotus Domino server to implement exporting a Lotus Notes document and parsing the property-mapping XML file. In this example, we also create a Java library to allow the agent to call into Java, using the LS2J (LotusScript to Java) interface.

Follow these steps to create a new TeamRoom and to deploy the Lotus Notes agent and the Java library in the TeamRoom. We assume that you’ve installed the Lotus Domino server and Lotus Notes client on your systems and that you have made sure that they work correctly.

1. Open the Lotus Domino server document, and navigate to the Security tab. In the Programmability Restrictions area, add the name of your Lotus Domino administrator to the field “Who can run unrestricted methods and operations.”Save the change, and restart the Lotus Domino server.
2. Open the Lotus Notes client and log in as the Lotus Domino administrator. Then select File - Application - New.
3. Enter the name of your Lotus Domino server, the TeamRoom title, and the file name. In the Specify Template area, enter the Lotus Domino server name, and select TeamRoom (8) as the template. (In Lotus Domino 7, select TeamRoom (7)). Click OK to create the TeamRoom. See figure 3.
   
   
   Figure 3. New Application window
   
   
   
4. Open the newly created TeamRoom database in Lotus Domino Designer.
5. Save the TeamRoomDemo.nsf file in the Download section of this article in your Lotus Notes/data directory and open it in Lotus Domino Designer.
6. Navigate to Shared Code - Agents. Copy the Copy to Lotus Quickr agent from TeamRoomDemo.nsf to your TeamRoom database.
7. Navigate to Shared Code - Agents. Copy the BackendAgent agent from TeamRoomDemo.nsf to your TeamRoom database.
8. Navigate to Script Libraries. Copy the Java library QMapping_Java from TeamRoomDemo.nsf to your TeamRoom database.
9. Navigate to Forms. Copy the QuickrMappingStep2 form from TeamRoomDemo.nsf to your TeamRoom database.
10. Sign these new added elements using Lotus Notes.

The Lotus Notes native document format is composite data (CD). Rich-text format (RTF) is one of the native document formats of Microsoft Office. Lotus Notes provides some export/import application programming interfaces (APIs) (in the dynamic link library’s nirtf.dll and nxrtf.dll) that include transforms for converting CD to RTF format. Therefore, we include an API function, ExportRTF (in nxrtf.dll), in the Lotus Notes agent to export the composite data of a Lotus Notes document to an RTF file and to detach the attachment of this Lotus Notes document to the same temporary folder.

The Copy to Lotus Quickr agent is used to display the Lotus Notes document, which you choose to copy, and to show the Quickr Connection Information window.

The BackendAgent agent can export the Lotus Notes document to an RTF document, detach attachments, and parse the property-mapping XML file.

You also need to acquire the connection information from the action executor, so use the QuickrMappingStep2 form to get this information. This form includes the server URL, the library UNID, username, and password.

The QMapping_Java Java library is used to handle the connection information and to call corresponding back-end Java APIs.

Back to top

Prepare the property-mapping XML file

The mapping between Lotus Notes document properties and Lotus Quickr document properties is stored in an XML file named PropertyMapping.xml. This file is located in the folder C:\Notes2Quickr\. (Note that C:\Notes2Quickr\ is the absolute path in which the PropertyMapping.xml file needs to be placed because this location is where the example code is expecting to find it.) You can modify the file to meet your mapping requirements. In this article, we show only how the document properties are transferred. Other attributes such as access control and conflict detection are not covered in this article.

When you create a new document in Lotus Quickr, you need to specify a document type; otherwise, the default document type of the target library is used. A Lotus Quickr document type is a combination of the following information: DocumentTemplate, one or more PropertySheetTypes, and a workflow for approval and version settings. We use the newly created document type DocFromNotes for the target document in Lotus Quickr and the PropertySheetType during the document transfer process.

Note how we organize the target DocumentType and PropertySheet values from Propertymapping.xml , which is the XML file we used for the example. Change these values to meet the requirements in your scenario. On the Lotus Notes side, the property values are transformed into a string, then passed into Java code from LotusScript; on the Lotus Quickr side, the property types can support String, Long, Boolean, Date, and so on. This example, shown in listing 1, illustrates only how the property type works for String.

<?xml version="1.0" encoding="UTF-8"?>
<PropertyMapping QuickrDocumentTypeName = "DocFromNotes">
<MappingGroup QuickrPropertySheetType="NotesDbInfor" >
<MappingPair>
<QuickrPropertyName>NotesDocUrl</QuickrPropertyName>
<QuickrPropertyType>String</QuickrPropertyType>
<NotesPropertyName>NotesDocUrl</NotesPropertyName>
</MappingPair>
<MappingPair>
<QuickrPropertyName>NotesDbUrl</QuickrPropertyName>
<QuickrPropertyType>String</QuickrPropertyType>
<NotesPropertyName>NotesDbUrl</NotesPropertyName>
</MappingPair>
</MappingGroup>

<MappingGroup QuickrPropertySheetType=" NotesDocInfor">
<MappingPair>
<QuickrPropertyName>DocCreator</QuickrPropertyName>
<QuickrPropertyType>String</QuickrPropertyType>
<NotesPropertyName>DocCreator</NotesPropertyName>
</MappingPair>
</MappingGroup>
</PropertyMapping>

Back to top

Launch the agent to transfer the document

This section shows you how the agent is launched to execute the transfer process. We introduce key functions and code samples.

To launch the agent, follow these steps:

1. Select one or more documents in TeamRoom.
2. From the menu, select Tools - Copy to Lotus Quickr. The window shown in figure 4 displays. Here you can enter the following information:
   
   • Lotus Quickr server URL
   • Lotus Quickr server username/password
   • Lotus Quickr library ID

Enter the necessary information, and then click OK. The transfer process then transfers documents from the Lotus Notes TeamRoom to the target Lotus Quickr library.

Back to top

Save the Lotus Notes documents as RTF files using LotusScript

The Lotus Notes document is exported to an RTF file, and the attachments are detached to a different folder. For example, if the exported document name is TransferedDoc.rtf, the attachments are detached to a folder named TransferedDoc.rtf _Attachments.

FollowThe Exporter class contains three important functions:

1. In its constructor, the Exporter class creates a temporary document and renders the document as a rich-text field of this temporary document.
2. It uses a Lotus Notes C API function MailGetMessageBodyComposite to write the composite data of this rich-text field to a binary file.
3. It uses a Lotus Notes Export API function ExportRTF to export the binary file to an RTF file as shown in listing 2.

'Write a field to a file in CD format.
Declare Function MailGetMessageBodyComposite Lib "NNOTES" Alias 
"MailGetMessageBodyComposite" ( Byval hNT As Long, Byval N As String, 
Byval D As String, nD As Long) As Integer

'Export Notes document to RTF.
Declare Function ExportRTF Lib "nxrtf" Alias "ExportRTF" (Byval sTempFile As 
String, Byval flags As Long, hmod As Long, Byval altlibrary As String, 
Byval sRTFFile As String) As Integer

Public Class Exporter
	Private Document As NotesDocument
	Private FieldName As String
	
	'Render the document to a Notes Rich Text Item.
	Sub New(notesDoc As NotesDocument)
		Dim tmpFld As NotesRichTextItem
		Dim success As Variant
		tmpDir = ROOT_DIR
		fld = "DocRenderFld"
		Set doc = notesDoc.ParentDatabase.CreateDocument
		Set tmpFld = New NotesRichTextItem(doc, fld)
		success = notesDoc.RenderToRTItem(tmpFld)
	End Sub
	
	'Export the Rich Text Item to a CD format file first, then convert it to RTF
	Sub RTF(rtfFileName As String)
		Dim fileSize As Long 		
		Dim cdFile As String
		'Create a temporary file name
		cdFile = GenerateTempFileName()
		'Export the Rich Text Item to a CD format file
		Call MailGetMessageBodyComposite(doc.handle, fld, cdFile, fileSize)
		'Convert the CD format file to a RTF file
		Call ExportRTF(cdFile, 0, 0, "", rtfFileName)
		Kill cdFile
	End Sub
	......
End Class

The code shown in listing 3 is used to export a Lotus Notes document to an RTF file. It creates an instance of the Exporter class first, and then it uses an RTF subroutine to export the document as a file.

Dim doc_exporter As New Exporter(doc)
Dim docPath As String
docPath = folderTmpFolder & "\" & doc.Subject(0) & ".rtf" 
doc_exporter.RTF docPath

The code shown in listing 4 is used to detach the attachments from the Lotus Notes document; you need to save these attachments in Lotus Quickr.

Set body = doc.GetFirstItem("Body")
Set rtnav = body.CreateNavigator
If rtnav.FindFirstElement(RTELEM_TYPE_FILEATTACHMENT) Then
	Mkdir(attachFolderPath)		
	Do
		Set att = rtnav.GetElement()
		filepath$ = attachFolderPath & "\" & att.Source
		Call att.ExtractFile(filepath$)
		Print filepath$ & " extracted"
	Loop While rtnav.FindNextElement()
End If

Back to top

Move the saved files into a Lotus Quickr library through Lotus Quickr Content Services

In the previous step, you saved the Lotus Notes document in the file system. The document body was saved as one file, and the Lotus Notes document attachments were saved as separate files in a folder. The next step is to transfer this content into Lotus Quickr.

You can transfer the documents into Lotus Quickr using a combination of REST and Web services. You can create the Lotus Quickr documents and update the document metadata by using REST services, whereas you can transfer the binary content of Lotus Quickr documents by using Web services. To simplify the use of the REST services, you can use the Apache Abdera client toolkit.

Listing 5 shows the code used to transfer a document through the Lotus Quickr REST services. You can find the source in AtomUtil.java in the attachments to this article. (AutomUtil.java is contained in the Notes2Quickr_source.jar file, in this subfolder: com/ibm/clb/notes2quickr.)

public String createDocument(DocumentService_PortType documentService, 
String documentPath, String mediaType, String docTypeUUID, 
String targetFolderURI) throws Exception
{
    releaseResponse();  
    //Open http request options.
RequestOptions options = new RequestOptions();

    //Set document name
    if(documentPath.lastIndexOf('/') !=-1)
    	options.setHeader("Slug", 
    	documentPath.substring(documentPath.lastIndexOf('/')+1));
    else
    	options.setHeader("Slug", documentPath);
    
    //Set mediaType
    if(mediaType == null|| "".equals(mediaType)) 	
    	options.setContentType("unknown/unknown");
    else
    	options.setContentType(mediaType);
    
    //Set target folder URI
    String uri = null;
    if(docTypeUUID ==null || "".equals(docTypeUUID))
    	uri = targetFolderURI;
    else
    	uri = targetFolderURI+"?doctype="+docTypeUUID;
   
    //Get payload of the document
    BufferedInputStream is = new BufferedInputStream(new 
    FileInputStream(documentPath));
    InputStreamRequestEntity entity = new InputStreamRequestEntity(is);
    
    //Create document by POST;
    response = client.post(uri, entity, options);
    
    is.close();
    IRI location = response.getLocation();
    String documentUUID = getIDFromLocation(location.toASCIIString());
    releaseResponse();
    return documentUUID;
 }
 

Back to top

Parse the XML file and retrieve the properties

Before you transfer the Lotus Notes document to Lotus Quickr, you need to know how to map the Lotus Notes document fields into Lotus Quickr document properties. This mapping is defined in the property-mapping XML file. In TeamRoomDemo.nsf we use a subroutine that is written by LotusScript to parse the XML file by using this function-calling process:

1. Invoke the ParseMappingXML subroutine directly in the agent.
2. Use the NotesDOMParser class to process the input XML into a standard Document Object Model (DOM) tree structure; the Subroutine is implemented in ParseMappingXML.
3. Go through the entire node tree, and select the data from the DOM:
   
   • If the node type is DOMNODETYPE_DOCUMENT_NODE, which means root node, call the WalkTree subroutine recursively to process the child nodes.
   • All other node types are DOMNODETYPE_ELEMENT_NODE, so all of them go into this case and are handled one by one.
   • If the element name is PropertyMapping, call the setDocTypeName function of the Qmapping class, which is defined in QMapping in the Java library to set the document type, and then call the createPropertySheetsMapping function to map the document properties.
   • For each MappingPair element, call the addPropertyMapping function to pass the property sheet data to Lotus Quickr as shown in listing 6.

Sub WalkTree ( node As notesdomnode)
	......
	If Not node.IsNull Then  
		Select Case node.NodeType
		Case DOMNODETYPE_DOCUMENT_NODE:    ' If it is a Document node
			......
		Case DOMNODETYPE_ELEMENT_NODE:     ' Most nodes are Elements
			......
			If node.NodeName = PROPERTY_MAPPING Then
				Set a = attrs.GetItem(1)
				docType = a.AttributeValue
				Call mapping.setDocTypeName(docType)
				Call mapping.createPropertySheetsMapping()
			End If
			......
			numChildren =  elt.NumberOfChildNodes
			Set child = elt.FirstChild     ' Get child
			While numChildren > 0
				Call walkTree(child)				
				Set child = child.NextSibling   ' Get next child
				numChildren = numChildren - 1
			Wend
			If node.NodeName = MAPPING_PAIR Then
		Call mapping.addPropertyMapping(propSheet , quickrPropName , 
		notesPropName , notesPropValue)
			End If
		End Select  'node.NodeType
	End If  'Not node.IsNull
End Sub

Back to top

Update properties according to the mapping

In the Lotus Notes TeamRoom, a document is stored as a form, and its document properties are stored as a field. In Lotus Quickr, this metadata is stored in property sheets as shown in figure 5.

Figure 5 illustrates how Lotus Quickr manages document properties. A ClbDocument object represents one document, and the attributes are categorized in two parts: basic document attributes and advanced document attributes.

Basic document attributes contain the standard document properties including title, description, and author. Of these attributes, some are updatable (for example, description); some are system managed (for example, last modified date) and so cannot be updated. We do not cover these attributes in detail here; for more information see the WSDL file, which can be retrieved from the URL of a Lotus Quickr server:

http://<server url>:<port>/dm/services/ContentService?wsdl

Advanced document attributes include ClbDocumentType, ClbPropertySheet, and ClbPropertySheetType. ClbDocumentType is a combination of user-defined properties, version informatioon, document templates, and document approval workflow. User-defined properties are stored under ClbPropertySheets; each ClbPropertySheet is an instance of a ClbPropertySheetType, and each ClbPropertySheet has a set of dynamic values. These dynamic values are stored in different arrays according to the different kind of value type such as String, Long, or Boolean values.

Document attributes can be updated using Lotus Quickr Web services. You can update the basic document attributes such as title and description, simply by calling a set operation. For a user-defined property, the update process is a little more complicated, as you need to find the mapping between the property name and the property label first. For instance, a user creates a property with the name year while in the repository, a system-generated key is used to identify the unique name, such as clb:p_1190. In the returned ClbDocument object, the property key is used instead of the property label as shown in figure 6.

Figure 6 shows how the mapping between the key and label can update a user-defined value. The entry point for this function is the method updatePropertySheet in WsUtil.java. The three main steps to update the value for a user-defined property of a document are as follows:

• Retrieve propertySheetType by using the propertySheetType title. In this example, we created two PropertySheetTypes: NotesDbInfor and NotesDocInfor. The function is implemented in the following method:
  private ClbPropertySheetType getPropertySheetType(ClbDraft draft, String propertySheetTypeTitle ) throws Exception;
  
• Retrieve the propertySheetType XML file, parse the XML file, and find the mapping between propertyName (for example, clb:p_1190) and propertyLabel (for example, Author). Note that the PropertySheetType reference in the ClbDraft Object does not contain the template XML. (In Lotus Quickr 8.0, the ClbDocument object cannot be updated directly; you need to update to a ClbDraft object instead of a ClbDocument object. A ClbDraft object is derived from a ClbDocument object when the document is checked out of the library.) The propertySheetType template XML can be retrieved only by the API DocumentService.getPropertySheetType(String docTypeUUID).
  
  propertyLabel is an attribute in the template XML, which maps to the property name in the Web UI. In this example, we use a DOM tree and navigate the tree to retrieve the propertyName.
  
  The function to retrieve and parse the propertySheetType Template XML to get the mapping is implemented in the following method:
  private String getPropertyNameFromLabel(ClbPropertySheetType propertySheetType, String propertyLabel) throws Exception;
  
• Retrieve propertySheet, and update the dynamic value according to propertyName (clb:p_1190). In the object ClbDynamicValue, propertyName is called key. The function is implemented in the following method:
  private ClbDynamicStringValue updateDynamicStringValue(ClbDynamicStringValue dynamicStringValue, String propertyName, ClbPropertySheet propertySheet, String newValue) throws Exception;

Back to top

Conclusion

Lotus Quickr Content Services provide a way to publish documents in Lotus Quickr document libraries. In this example, we showed you how to publish Lotus Domino TeamRoom documents to Lotus Quickr using Lotus Quickr Content Services in a simple and easy way. Even though the example described in this article is not a complete, production-ready application, it describes a pattern that you can apply to address your specific requirements to import content into Lotus Quickr from Lotus Domino or other familiar document repositories. It also provides a good illustration of how Lotus Quickr Content Services can be used.

Note that IBM also offers a product called Lotus Quickr Content Integrator that provides a complete solution for publishing TeamRoom documents into Lotus Quickr services for Lotus Domino.

Back to top

Download

Information about download methods

Resources

Learn

• Read the developerWorks Lotus article, "Introducing IBM Lotus Quickr REST services."
  
  
• Read the developerWorks Lotus article, "Introducing IBM Lotus Quickr Web services."
  
  
• Read the developerWorks Lotus article, "Getting to know the Atom Publishing Protocol, Part 3: Introducing the Apache Abdera project."
  
  
• Read the developerWorks Lotus wiki describing Lotus Quickr Content Services.
  
  
• Read the IBM Lotus Quickr Information Center.
  
  
• Read the IBM Lotus Notes and Domino V8 Reviewer's Guide.
  
  
• Read more about IBM Lotus Notes and Domino 8.
  
  
• Read more about Lotus Quickr Content Integrator.
  
  
• The Apache Axis project site provides information on various aspects of the project.
  
  
• Read more about Apache Abdera Project Web site: Develop Atom-enabled Java applications.
  
  

Get products and technologies

• Download Apache Axis 1.4.
  
  
• Download Apache Abdera.
  
  

Discuss

• Participate in the discussion forum.
  
  

About the authors

Comments

Back to top

Trademarks

Table of contents

• Prerequisites
• TeamRoom agent to transfer documents into Lotus Quickr for Java Platform, Enterprise Edition
• Prepare the data on the Lotus Quickr server
• Deploy the new agent in the TeamRoom
• Prepare the property-mapping XML file
• Launch the agent to transfer the document
• Save the Lotus Notes documents as RTF files using LotusScript
• Move the saved files into a Lotus Quickr library through Lotus Quickr Content Services
• Parse the XML file and retrieve the properties
• Update properties according to the mapping
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Lotus Domino
• Demo: Lotus Notes 8 composite applications
• Webcast: A Smart Approach to Core Banking Renovation in a Tough Economic Climate
• Briefing: IBM community tools
• Buy: Lotus Domino

My developerWorks community

Dig deeper into Lotus on developerWorks

We want to know you!

Update your My developerWorks profile and start connecting with others

Special offers