Integrating IBM Lotus Quickr 8.5 for Domino with IBM Enterprise Content Management: Configuration and best practices

The ability to integrate with IBM® Enterprise Content Management was introduced in IBM Lotus® Quickr® 8.5 for Domino®. In this article we discuss how it works and how to configure and use related features. It's assumed that you're familiar with Lotus Quickr and that you've already installed Lotus Quickr 8.5 for Domino.

Share:

Albert Wang, Software Architect, IBM China

Albert Wang is a Software Architect based at the IBM China Development Lab in Beijing, where he serves as the Lotus Quickr Domino Architect and Tech Leader. He has written five Chinese books on computer programming and has published more than 30 papers on computer technology for international conferences and academic journals. You can reach him at wangxu@cn.ibm.com.



Zheng Fei Guo, Software Engineer, IBM China

Zheng Fei Guo is a Software Engineer at the IBM China Development Lab in Beijing, where he has worked on Lotus Quickr for Domino for the past several years. He has extensive experience with Web 2.0 applications and collaboration software. You can reach him at guozf@cn.ibm.com.



Jie Ma, Staff Software Engineer, IBM China

Jie Ma is a Staff Software Engineer, Functional Verification Test lead, and PM/Scrummaster of the Lotus Quickr Enterprise Content Management Integration team at the IBM China Development Lab in Beijing. He's also experienced in Agile software development. You can reach him at majie@cn.ibm.com.



Zheng Wei Wang, Software Engineer, IBM China

Zheng Wei Wang is a Software Engineer in the IBM China Development Lab in Beijing, working on Lotus Quickr for Domino 8.5 development. You can reach him at zwwang@cn.ibm.com.



06 June 2011 (First published 08 September 2010)

Also available in Chinese Russian Portuguese

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

IBM Enterprise Content Management Services for Lotus Quickr uses Lotus Quickr technologies to provide integration between your desktop applications and Enterprise Content Management repositories. IBM Enterprise Content Management Services include IBM Content Manager Services for Lotus Quickr and IBM FileNet Services for Lotus Quickr.

In this article, we define Lotus Quickr 8.5 for Domino and Enterprise Content Management integration as a set of four features:

  • Enterprise Content Management Document link
  • Customer Library
  • Enterprise Content Management Document Publish
  • Enterprise Content Management Document Search

Preconfiguration

Lotus Quickr for Domino uses an XML file, qpconfig.xml, for server configuration. A sample file (qpconfig_sample.xml) is located in the server's data directory that you can use as a template.

Enterprise Content Management integration features in qpconfig.xml are enabled as follows:

<ecm_integration enabled="true">

Before working with Enterprise Content Management features, you must also enable multiple servers single sign-on (SSO, which is recommended) or single server session authentication for the Lotus Domino server. In addition, you need to configure an IBM iNotes® proxy because it's used as the Ajax proxy in Lotus Quickr 8.5 for Domino to access the Enterprise Content Management server.


Configuring SSO

Follow these steps to configure SSO with IBM WebSphere® Application Server (Enterprise Content Management server):

  1. Export the Lightweight Third Party Authentication (LTPA) key from the WebSphere Application Server with which you want to set up SSO.
  2. Optional: Add the following setting to the Notes.ini file of each Lotus Quickr server to be enabled for SSO:

    NoWebFileSystemACLs=0

    This step prevents anonymous access to files in the Lotus Domino html directory.

  3. Create or edit the web SSO configuration document for the domain, enabling multiserver session-based authentication in the server document for each Lotus Quickr server that you want to enable for SSO:

    1. Open the Lotus Domino directory (Names.nsf), using the IBM Lotus Notes or IBM Lotus Domino Administration client.
    2. Select Configuration – Servers – All Server Documents.
    3. Select the server document for the server and click Edit Server.
    4. Select Ports – Internet Ports – Web, and enable name-and-password authentication for the web (HTTP or HTTPS) port.
    5. Select Internet Protocols and click the Domino Web Engine tab.
    6. For the Session authentication field, select Multiple Servers (SSO).
  4. Now configure web SSO:

    1. Click the Create Web button at the top of the window, and select SSO Configuration.
    2. Click Keys at the top of the window, and select Import WebSphere LTPA keys. Enter the path to the key and password.

    Figure 1 shows a sample configuration.

    Figure 1. Sample configuration
    Sample configuration
  5. In the Web SSO Configuration field, select LtpaToken from the list of keywords (see figure 2); click Save and Close.

    Figure 2. Select Web SSO configuration
    Select Web SSO configuration
  6. Create the Lotus Domino Web Server Configuration database (domcfg.nsf), if it does not exist:

    1. In the Lotus Domino administration client, select File – Application – New.
    2. At the top of the New Application window (see figure 3), for the Server field, select the server on which Lotus Quickr runs.
    3. In the Title field, enter a descriptive title, for example, “Web Server Configuration.”
    4. In the File field, enter domcfg.nsf. (This is the required file name.)
    5. In the Server field under the “Specify Template” section, select any server and select (by placing a check mark) the Show advanced templates option.
    6. For Template, select Domino Web Server Configuration (domcfg5.ntf); click OK.
    Figure 3. Create Domino Web Server Configuration database
    Create Domino Web Server Configuration database
  7. Create a mapping form in the Lotus Domino Web Server Configuration database to enable SSO to work with Lotus Quickr:

    1. Open the Web Server Configuration database (domcfg.nsf), and click Add Mapping.
    2. In the Applies To field, select All Web Sites/Entire Server (the default) or Specific Web Site/Virtual Server. If you select Specific Web Site/Virtual Server, a new field displays in which you specify the IP addresses of the website documents or virtual servers.
    3. For the target database, enter LotusQuickr/resources.nsf, replacing the default entry. The path is case sensitive on UNIX®. operating systems. If you upgraded from an earlier release and did not change the root directory name, enter QuickPlace/resources.nsf.
    4. For the target form, enter QuickPlaceLoginForm, and click Save and Close.
    5. Replicate the database to all the Lotus Quickr servers that use SSO.
  8. Enable and update the LDAP setting section of qpconfig.xml to synchronize with the configuration of the external LDAP server defined in the Lotus Domino SSO configuration document, using the code shown in listing 1.

    Listing 1. Code for the LDAP settings section
    <user_directory>
      <user_photo_source local="false">
        <directory>
           <url>
              <![CDATA[
                http://server.ibm.com/photo?EMAIL={email}
              ]]>
    		        </url>
          </directory>
        </user_photo_source>
        <ldap>
          <base_dn>
          <!--   <group>ou=groups,o=ibm</group>  -->
          </base_dn>
          <schema>
            <object_class>objectClass</object_class>
            <user>
                <object_class_value>person</object_class_value>
                <common_name>cn</common_name>
                <display_name>cn</display_name>
                <first_name>givenname</first_name>
                <last_name>sn</last_name>
                <email>mail</email>
                <phone>telephoneNumber</phone>
    	           <user_defined_field>manager</user_defined_field>
            </user>
            <group>
                <object_class_value>groupOfuniqueNames</object_class_value>
                <common_name>cn</common_name>
                <display_name>cn</display_name>
                <member>Uniquemember</member>
            </group>
            <dn_delimiter robust_compare="true"/>
            <dn_incoming_is_native enabled="true"/>
            <secondary_cn_component enabled="true"/>
            <maintain_escape_character enabled="false"/>
            <ldap_is_active_directory enabled="false"/>
          </schema>
          <search_filters>
            <authentication>
              <![CDATA[
                      (|(cn={0})(uid={0})(shortname={0}))
              ]]>
            </authentication>
            <user_lookup>
              <![CDATA[
                      (&(objectclass=person)(sn={0})(givenname={1}))
              ]]>
            </user_lookup>
            <group_lookup>
              <![CDATA[
                      (&(objectclass=groupOfUniqueNames)(cn={0}))
              ]]>
                </group_lookup>
                <group_membership>
                   <![CDATA[
                      (&(objectclass=groupOfUniqueNames)(Uniquemember={0}))
                   ]]>
                </group_membership>
            </search_filters>
            <member_lookup_ui>
              <column_name>
                   <person>sn, givenname</person>
              </column_name>
              <column_disambiguate>
                <person>dn</person>
              </column_disambiguate>
    		        <display_max_num_names>50</display_max_num_names>
            </member_lookup_ui>
            <search_ui_hint>
                <![CDATA[
                   ( enter <B>last name, first name</B>)
                ]]>
            </search_ui_hint>
            <search_ui_index>sn</search_ui_index>
            <ssl protocol="3" accept_expired_certs="true" verify_servername="true"/>
          </ldap>
       </user_directory>
  9. After the Lotus Domino Web Server Configuration database has replicated, at the server console of each server, restart it, using the restart server command. If you see the Successfully loaded Web SSO Configuration message on the console, you have successfully configured SSO for the Lotus Quickr for Lotus Domino server.
  10. Log in to Lotus Quickr for Domino as administrator, and set the external LDAP server to be the same as that for the SSO configuration document (see figure 4). SSO with WebSphere Application Server is now ready to use.

    Figure 4. Change User Directory window of the Lotus Quickr for Domino server
    Change User Directory window of the Lotus Quickr for Domino server

Single Server session authentication

To configure Single Server session authentication, you don't need to export or import a key (so steps 1 and 6 are not needed). You need only to select Single Server for the Session authentication field in Step 3.

Now, you won't see the Successfully loaded Web SSO Configuration message when restarting the Lotus Domino server (as in step 9). Also, when changing the user directory (step 10), select Domino Server for the user directory Type field.

Again, even though Enterprise Content Management features can work with SSO or single server session authentication, SSO is the better method.


Configuring the iNotes proxy

Perform these steps to configure the iNotes proxy:

  1. Open the Names.nsf database, select Policies from the left navigation pane, and click the Add Policy button at the top, to create a Policy document.
  2. Enter */* or * in the Policy name field, select Organizational for the Policy type field, and click the New button on the right side of the Security field (see figure 5).

    Figure 5. Policy document
    Policy document
  3. In the new Security Settings document click the Proxies tab (see figure 6) and then click the Edit list button.
    Figure 6. Security Settings document
    Security Settings document
  4. Add your Enterprise Content Management servers into the “White-list rule to add or modify” window, and click OK (see figure 7):

    policy0.url=http://ecmserver01.cn.ibm.com:9080/
    policy0.context=/xsp/proxy/BasicProxy/
    policy0.actions=GET,POST,HEAD,PUT,DELETE
    policy0.cookies=*
    policy0.headers=*
    policy0.mime-types=*


    policy1.url=http://ecmserver2.cn.ibm.com:9080/
    policy1.context=/xsp/proxy/BasicProxy/
    policy1.actions=GET,POST,HEAD,PUT,DELETE
    policy1.cookies=*
    policy1.headers=*
    policy1.mime-types=*
    Figure 7. Modify white-list rule window
    Modify white-list rule window
  5. Set the Security field of the Policy document to security (the newly created Security document).
  6. Save all and restart the server.

Enterprise Content Management integration features

Let's now discuss the integration features.

Creating the Enterprise Content Management document link

You can create a link to a document in the Enterprise Content Management repository by creating a link page (see figure 8).

Figure 8. Create New Link Page window
Create New Link Page window

As you can see in figure 8, two options display when you click the Insert Link button, File Download and Summary Page. If you select File Download, a link to the document download is created; if you select Summary Page, then a link to the Enterprise Content Management web UI of the document is inserted.

You can also create a link to a document in the Enterprise Content Management repository by clicking the URL icon and selecting Insert Link to External Document in the rich text editor when creating or editing pages.

In the Enterprise Content Management web UI, you can see the basic information of the document, including title, author, and date created; however, the Enterprise Content Management web UI must be supported on the Enterprise Content Management server side.

For FileNet, there is always a default application running to support the Enterprise Content Management web UI after it is installed.

For Content Manager Services, you should install an additional application such as IBM WEB Interface (WEBi); otherwise, when you select Summary Page, it also inserts a link to the document download.

Enterprise Content search

You can search documents stored in an Enterprise Content Management repository by using Enterprise search. To do this task, follow these steps:

  1. Enable it by setting the target Enterprise Content Management repository in qpconfig.xml as follows: <ECM_Search_Target name="lwptsthink02" url="http://ecmserver1.cn.ibm.com:9080"/>
  2. Select Enterprise Content from the drop-down menu of the search input box and enter the keyword that you want to search; the Enterprise Content Search window displays (see figure 9).

    Figure 9. Enterprise Content Search window
    Enterprise Content Search window

There are four search parameters for advanced search:

  • Search scopes
  • Document type
  • Date
  • User

If you click the user name in the search result, it searches by that user name, and you can combine any of these four search parameters to perform an advanced search.

You can also do the following:

  • Search in All Enterprise Documents, My Enterprise Documents, and My Checked out Documents
  • Search documents that are created from a specific document type
  • Select a start date and end date to search the documents whose last modified date falls in that range

Document publish

You can publish a document or page from Lotus Quickr to the Enterprise Content Management server. The default Publish web UI (also called the Publish Wizard) has two Publish to External Location windows. The first, Select Location, is used to select the publish target location (see figure 10).

Figure 10. Select Location window
Select Location window

Using the second window, Select Publish Option, you can select how to deal with the published document or page (see figure 11). If metadata (properties) mapping is configured, you also see a Metadata Mapping window with which you can edit the value of metadata.

Figure 11. Select Publish Option window
Select Publish Option window

Using qpconfig.xml, you can also customize the Publish web UI, as shown in table 1.

Table 1. Document Publish configuration elements in qpconfig.xml
ElementDescription
<targetHost>http://lwptsthink47.cn.ibm.com:9080 /targetHost>URL of default Enterprise Content Management server.
<targetLibrary> /QuickrRoot/ QKSmokeApplication/QKSmokeLibrary </targetLibrary> Path of default library in default Enterprise Content Management server.
<targetFolder> /Test/</targetFolder> Default doc publish target folder in default Enterprise Content Management server.
<setDefaultOperation>link </setDefaultOperation>Default publish action (copy, move, link).
<allowHostEdit enabled ="true"> </allowHostEdit> If the value of the enabled attribute is false, then users cannot type the server URL in the publish wizard. The Server field only is read, and its value is the URL of the default Enterprise Content Management server (targetHost ):

Select Publish Option window
<forceDefaultPublishLocation enabled ="false"> </forceDefaultPublishLocation >If the value of the enabled attribute is true, then the Select Location window is skipped. Documents are published to the default folder (targetFolder) in the default library (targetLibrary) of the default Enterprise Content Management server (targetHost).
<forceDefaultOperation enabled = "false"> </forceDefaultOperation>If the value of the enabled attribute is true, then the Select Publish Option window is skipped. Document publish gets the default, the publish action (setDefaultOperation), as its parameter.

Select Publish Option window

The forceDefaultPublishLocation and forceDefaultOperation parameters can be combined to achieve different Publish web UIs, as shown in table 2.

Table 2. Combined elements and their output
Element name: forceDefaultPublishLocationElement name: forceDefaultOperationOutput
TrueTrueThe Publish wizard never displays. When you click Publish To from the context menu of a document, a preconfigured default publish location and default operation are used for the publish operation.
TrueFalseThe Publish wizard does display, but the Select Location window is skipped. The Required Properties window displays, followed by the Publish Options window, in which the publish operation is set by the value of the setDefaultOperation parameter.
FalseTrueThe Publish wizard does display, but the Publish Options window is skipped. Thus the wizard starts with the Select Location window, and the user specifies the target server and the target folder, enters any required properties in the next window, and is presented with a Publish button instead of a Next button, with the value of setDefaultOperation determining the publish option to be used.
FalseFalseThe Publish wizard displays and exhibits its default behavior. The user can enter any location and select any publish option, although the value of setDefaultOperation determines which publish option is the default publish operation.

Configure metadata mapping

In Lotus Quickr for Domino, you can customize a form to include some fields. Here a form is treated as a document type, and you can then create a document from that customized form.

Metadata mapping between Lotus Quickr and Enterprise Content Management is illustrated in figure 12, in which we map a form to a document type, where F is field, PST is property sheet type, and P is property. Then, when you publish a Lotus Quickr document created from that form, Lotus Quickr uses the mapped document type to create an Enterprise Content Management document, and the property's value is the mapped field's value.

Figure 12. Lotus Quickr form mapped to Enterprise Content Management document type
Lotus Quickr form mapped to Enterprise Content Management document type

There are two kinds of documents in Lotus Quickr for Domino: Page and Document. Before working with metadata mapping, you should understand the difference between them: When a document has a Single Attachment field but no Rich Text field, it is a Document; otherwise, it is a Page.

When customizing a form (see figure 13), after you add the Single Attachment field but no Rich Text field, the document created from that form is a Document. Let's call this form a "Document Form" and the other form a "Page Form."

Figure 13. Customize form window
Customize form window

In the Lotus Quickr 8.5 for Domino web UI, when you upload or import a file, it is a Document; whereas others like page, link, Forum Topic and response, comments, list items and so on are all Pages.

On the Enterprise Content Management server side, you can create a Page from some, but not all, document types in the Enterprise Content Management repository. Not all document types support Pages, but all document types supporting Pages also support Documents.

It's acceptable to map a Document Form to a document type supporting a Page, but if you try to map a Page Form to a document type that doesn't support Page, it fails.

Table 3 lists the metadata mapping types that are supported in Lotus Quickr for Domino.

Table 3. Mapping types and their descriptions
Mapping typesDescription
Explicit mappingConfigures which form is mapping to which document type on the Enterprise Content Management server side, and which field is mapping to which property implicitly.
Semi-implicit mappingConfigures which form is mapping to which document type on the Enterprise Content Management server side explicitly, but does not configure which field is mapping to which property. If one field's name in Lotus Quickr matches one property's name, then they are mapped implicitly.
N fields to One property mappingMore than one field is mapping to only one property (this is a subcategory of explicit mapping). The fields' names should be separated by a blank space.

Perform the following steps to use metadata mapping:

  1. Customize a DemoForm in Lotus Quickr, adding a Plain Text field, a Date Pop-up field, and an Attachments field.
  2. Configure qpconfig.xml to apply one of these three mapping types. You can run qptool to help to generate the mapping table:

    load qptool execute -i input.xml -o output.xml where the content of input.xml is shown in listing 2.

    Listing 2. Code for input.xml
    <?xml version="1.0"?>
    <service>
    <servers>
    <server>
    <hostname>QDServer.cn.ibm.com</hostname>
    <places>
    <place action="getMetadataCfg">
    <name>demomapping</name>
    </place>
    </places>
    </server>
    </servers>
    </service>
  3. Change hostname to your actual Lotus Quickr server's hostname, and change name to your place name. The draft mapping is generated in output.xml (see listing 3).

    Listing 3. Draft mapping
    <form_60F44D802AC79D72482576F9002C5D11 formName="DemoForm">
    <mappingInfo docType=""><mapping field="c_DemoText" property="" 
    propertySheetType=""/><mapping field="c_DemoDate" property="" 
    propertySheetType=
    ""/></mappingInfo></form_60F44D802AC79D72482576F9002C5D11>
  4. Copy and paste the draft mapping into qpconfig.xml. You can then change it to set the different mapping types, as shown in listings 4-6:

    Listing 4. Explicit mapping
    <form_60F44D802AC79D72482576F9002C5D11 formName="DemoForm">
    <mappingInfo docType="DemoECMDocType"><mapping field="c_DemoText" 
    property="SSName" propertySheetType="PST1"/><mapping field="c_DemoDate" 
    property="Date" propertySheetType="PST2"/></mappingInfo>
    </form_60F44D802AC79D72482576F9002C5D11>
    Listing 5. Semi-implicit mapping
    <form_60F44D802AC79D72482576F9002C5D11 
    formName="DemoForm"><mappingInfo 
    docType="DemoECMDocType"></form_60F44D802AC79D72482576F9002C5D11>
    Listing 6. N fields to One property mapping
    <form_60F44D802AC79D72482576F9002C5D11 formName="DemoForm">
    <mappingInfo docType="DemoECMDocType">
    <mapping field="c_DemoText c_DemoDate" property="Summary" 
    propertySheetType="PST1"/></mappingInfo>
    </form_60F44D802AC79D72482576F9002C5D11>

    NOTE: When mapping N fields to One property, the property can only be the String type.

  5. Create a page from DemoForm, and select Publish to in its context menu or page view. In the Publish wizard you can now see the Edit Document Properties view. Complete those properties and publish it to the Enterprise Content Management repository.

Custom Library

Custom Library is used to directly connect you to the Enterprise Content Management server. You can access and manipulate content in the Enterprise Content Management repository the same as in your Lotus Quickr library. You can also view, upload, check out, check in, and update documents on the Enterprise Content Management server in your Lotus Quickr web UI.

Follow these steps to use Custom Library:

  1. Create a Custom Library page by selecting Place Actions – New page – Custom Library, or Library – New – Custom Library. Custom Library has the same attributes as Document, including Name, Description, access control setting, and location (see figure 14).

    Figure 14. New Custom Library window
    New Custom Library window
  2. Open the newly created custom library page, click the Configure link, or select More Actions – Configure, to configure the custom library.
  3. In the Connect to a Library or Folder tab, enter the Enterprise Content Management server URL in the Server field, select the Log in with my current credentials field, and then select a folder or subfolder of the Enterprise Content Management server as the root of your Custom Library.

    If you want to log in to the Enterprise Content Management server using another account, just clear the Log in with my current credentials check box and enter that account's user name and password.

  4. Click the Configure Default View tab of the Custom Library, to configure how many columns to display. Click OK to save your configuration.

Now you can see the contents in the Enterprise Content Management server and, just as in your Lotus Quickr Library, you can do the following:

  • View the Custom Library in either detailed or compact mode
  • Upload files with default or customized document type
  • Create, rename, or delete documents
  • View, replace, edit properties, check out, check in, delete, and download documents
  • Create, rename, and delete folders
  • Switch views that are provided by the Enterprise Content Management server

Conclusion

You should now have a detailed understanding of the features of Lotus Quickr for Domino Enterprise Content Management integration. We've introduced you to all its major components, how they function, and how you can use them. We hope that you can use this article to take full advantage of the powerful functionality of Lotus Quickr for Domino Enterprise Content Management integration to make your job easier.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, Information Management
ArticleID=517189
ArticleTitle=Integrating IBM Lotus Quickr 8.5 for Domino with IBM Enterprise Content Management: Configuration and best practices
publish-date=06062011