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

Transcription

1 Integrating IBM Lotus Quickr 8.5 for Domino with IBM Enterprise Content Management: Configuration and best practices Albert Wang, Software Architect, IBM Software Group, China Zheng Fei Guo, Software Engineer, IBM Software Group, China Jie Ma, Staff Software Engineer, IBM Software Group, China Zheng Wei Wang, Software Engineer, IBM Software Group, China Summary: The ability to integrate with IBM Enterprise Content Management (ECM) was introduced in IBM Lotus Quickr TM for Domino 8.5. 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 you've already installed Lotus Quickr for Domino 8.5. Table of Contents Introduction... 1 Pre-configuration... 1 Configuring SSO... 2 Configuring the inotes proxy ECM Integration features Conclusion Resources About the authors Introduction IBM ECM Services for Lotus Quickr leverages Lotus Quickr technologies to provide integration between your desktop applications and ECM repositories. IBM ECM Services include IBM Content Manager Services for Lotus Quickr and IBM FileNet Services for Lotus Quickr. In this article, we define Quickr Domino 8.5 ECM integration as a set of features: ECM Document link Customer Library ECM Document Publish

2 ECM Document Search Pre-configuration Quickr 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. You can enable ECM integration features in qpconfig.xml as follows: <ecm_integration enabled="true"> Before working with ECM features, you must also enable Multiple Servers single sign-on (SSO, which is recommended) or Single Server session authentication for the Domino server. In addition, you need to configure an inotes TM proxy because it's used as the Asynchronous JavaScript TM + XML (Ajax) proxy in Quickr Domino 8.5 to access the ECM server. Configuring SSO Follow these steps to configure SSO with WebSphere Application Server (ECM server): 1.Export the Lightweight Third-Party Authentication (LTPA) key from the WAS 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=1 This step prevents anonymous access to files in the Domino html directory. 3.Create or edit the Web SSO Configuration document for the domain, enabling multi-server session-based authentication in the Server document for each Lotus Quickr server that you want to enable for SSO: a) Open the Domino Directory (Names.nsf), using the Notes or Domino Administration client. b) Select Configuration Servers All Server Documents. c) Select the Server document for the server and click Edit Server. d) Select Ports Internet Ports Web, and enable Name-and-password authentication for the Web (HTTP or HTTPS) port. e) Select Internet Protocols and click the Domino Web Engine tab. f) For the Session authentication field, select Multiple Servers (SSO). 4. Now configure Web SSO: a) Click the Create Web button and select SSO Configuration (see figure 1). Figure 1. Create Web SSO Configuration

3 b) Click Keys Import WebSphere LTPA keys (see figure 2), and enter the path to the key and password. Figure 2. Import WAS LTPA Key's Figure 3 shows a sample configuration. Figure 3. Sample configuration

4 NOTE: Be sure to add a \ before the port number of the external common LDAP server. 5.In the Web SSO Configuration field, select LtpaToken (see figure 4); click Save and Close. Figure 4. Select Web SSO configuration 6.Create the Domino Web Server Configuration database (domcfg.nsf), if it does not exist: a) In the Domino Administration Client, select File Application New. b) At the top of the New Application window (see figure 5), for the Server field, select the

5 server on which Lotus Quickr runs. c) In the Title field, enter a descriptive title, for example, Web Server Configuration. d) In the File field, enter domcfg.nsf. (This is the required file name.) e) In the Server field under the Specify Template... section, select any server and click Show advanced templates. f) For Template, select Domino Web Server Configuration (domcfg5.ntf); click OK. Figure 5. Create Domino Web Server Configuration database 7.Create a mapping form in the Domino Web Server Configuration database to enable SSO to work with Lotus Quickr: a) Open the Web Server Configuration database (domcfg.nsf) and click Add Mapping. b) In the Applies To field, select All Web Sites/Entire Server (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 Web Site documents or Virtual Servers. c) For Target Database, enter LotusQuickr/resources.nsf, replacing the default entry. The path is case sensitive on UNIX. If you upgraded from an earlier release and did not change the root directory name, enter QuickPlace/resources.nsf. d) For Target Form, enter QuickPlaceLoginForm, and click Save & Close. e) Replicate the database to all the Lotus Quickr servers that will 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 Domino SSO configuration document, using the code in listing 1.

6 Listing 1. Code for the LDAP settings section <user_directory> <user_photo_source local="false"> <directory> <url> <![CDATA[ ]]> </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> < >mail</ > <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}))

7 ]]> </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 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 Quickr Domino Server. 10.Log in to Quickr Domino as administrator and set the external LDAP server to be the same as that for the SSO configuration document (see figure 6). SSO with WebSphere Application Server is now ready to use. Figure 6. Change User Directory window of Quickr Domino server

8 Single Server session authentication To configure Single Server session authentication, you don't need to export or import any key (so Steps 1 and 6 above are not needed). You need only to select Single Server for the Session authentication field in Step 3, as shown in figure 7.<--Please verify all references to step numbers are correct. I re-numbered some of them> Figure 7. Single Server option for session authentication

9 Now, you won't see the "Successfully loaded Web SSO Configuration" message when restarting the Domino server (as in Step 9). And when changing the user directory (Step 10), you should select Domino Server for the user directory Type (see figure 8). Figure 8. Change user directory type to Domino Server

10 Again, although ECM features can work with SSO or Single Server session authentication, SSO is the recommended method. Configuring the inotes proxy Perform these steps to configure the inotes proxy: 1.Open the Names.nsf database, select Policies from the left-hand Navigation pane, and click the Add Policy button at the top, to create a Policies document. Enter "*/*" or * in the Policy name field, and select Organizational for the Police type field (see figure 9). Figure 9. Set up policy

11 Create a nnew a security document and click the Proxies tab (see figure 10). Click the Edit list button. <edited this step for clarity; is it correct?> Figure 10. Security Settings window Add your ECM servers into the white-list rule; click OK (figure 11). Figure 11. Add ECM server into white-list rule a. policy0.url= policy0.context=/xsp/proxy/basicproxy/

12 policy0.actions=get,post,head,put,delete policy0.cookies=* policy0.headers=* policy0.mime-types=* b. policy1.url= policy1.context=/xsp/proxy/basicproxy/ policy1.actions=get,post,head,put,delete policy1.cookies=* policy1.headers=* policy1.mime-types=* 5.Set the Security field of the Policy document to security (the newly created Security document from above; see figure 12). Figure 12. Choose security document

13 6. Save all and restart the server. ECM Integration features Creating the ECM Document Link You can create a link to a document in the ECM repository by creating a link page (see figure 13). Figure 13. Create New Link Page window

14 <edited the two paragraphs below for clarity; are they correct?> As you can see in the figure, two options display when you click the Insert Link button, File Download and Summary Page. If you select File Download, then a link to the document download will be created; if you select Summary Page, then a link to the ECM Web UI of the document will be inserted. You can also create a link to a document in the ECM repository by inserting a link to External Document in the RichText Editor when creating or editing pages. <--what is CKEditor? please define> (see figure 14). Figure 14. Insert Link to External Document in CKEditor

15 In the ECM Web UI, you can see the basic information of the document, including title, author, and date created; however, the ECM Web UI must be supported on the ECM server side.for FileNet, there is always a default application running to support the ECM 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 will also insert a link to the document download. Enterprise Content search You can search over documents stored in an ECM repository by using Enterprise search. To do this, you must enable it and set the target ECM repository in qpconfig.xml as follows: <ECM_Search_Target name="lwptsthink02" url=" Then select Enterprise Content from the drop-down menu of the search input box, and enter the key word you want to search; the Enterprise search page displays (see figure 15). Figure 15. Enterprise Content search page

16 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 will search by that user name; and you can combine any of these four search parameters to perform a advanced search. You can also: 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 fall in that range. Document Publish You can publish a document or page from Quickr to the ECM server. The default Publish Web UI (we call it the publish wizard) has two windows. The first, Publish to External Location, is used to choose the publish target location (see figure 16). Figure 16. Publish to External Location window

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

18 Using qpconfig.xml, you can also customize the Publish Web UI, as shown in table 1. Table 1. Document Publish configuration in qpconfig.xml. qpconfig.xml parameters and their description <is this caption correct?> Element <targethost> targethost> <targetlibrary> /QuickrRoot/QKSmokeApplication/ QKSmokeLibrary </targetlibrary> <targetfolder> /Test/</targetFolder> <setdefaultoperation>link Description URL of default ECM server. Path of default library in default ECM server. Default doc publish target folder in default ECM server. Default publish action (copy, move, link).

19 </setdefaultoperation> <allowhostedit enabled ="true"> </allowhostedit> If the value of the attribute enabled is false, then users cannot type the server URL in the publish wizard. The Server field will be read only, and its value is the URL of the default ECM server (targethost ): <forcedefaultpublishlocation enabled ="false"> </forcedefaultpublishlocation > <forcedefaultoperation enabled = "false"> </forcedefaultoperation> If the value of the attribute enabled is true, then the Select Location window will be skipped. Documents will be published to the default folder (targetfolder) in the default library (targetlibrary) of the default ECM server (targethost). If the value of the attribute enabled is true, then the Select Publish Option window will be skipped. Document publish will get default the publish action (setdefaultoperation) as its parameter. The forcedefaultpublishlocation and forcedefaultoperation parameters can be combined to achieve different Publish Web UIs, as shown in table 2. Table 2. Element Name forcedefaultpublishlocation forcedefaultoperation Output true true The 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. true false The Publish Wizard does display, but the Select Location window is

20 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. false true The Publish Wizard does display, but the Publish Options window is skipped. Thus the wizard starts with the Select Location window, 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. false false The Publish Wizard displays and exhibits its default behavior. The user can enter any location and choose any publish option, although the value of setdefaultoperation determines which publish option is the default publish operation. Configure metadata mapping In Quickr for Domino, you can customize a form to include some fields. Here a form is treated as a kind of document type, and you can then create a document from that customized form. Metadata mapping between Quickr and ECM is illustrated in figure 18, in which we map a form to a document type, and F is field, PST is property sheet type, and P is property. Then, when you publish a Quickr document created from that form, Lotus Quickr uses the mapped document type to create an ECM document, and the property's value will be the mapped field's value. Figure 18. Quickr form mapped to ECM document type <please replace QD with Quickr and remove the F: Field...P: Property line in this figure>

21 In Quickr for Domino, there are two kinds of documents, Page and Document, and 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. So, when customizing a form (see figure 19), once you add the Single Attachment field but no Rich Text field, the document created from that form is a Document. Let's call this kind of form a "Document Form" and the other kind of form a "Page Form". Figure 19. Customize form window In the Quickr for Domino 8.5 Web UI, when you upload or import a file, it is a Document, others like page, link, Forum Topic and response, comments, list items and so on are all pages. <-- what others?> are Pages.

22 On the ECM server side, you can create a Page from some but not all document types in the ECM repository. Not all document types support Pages, but all document types supporting Pages also support Documents. So, it's OK 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 will fail. Table 3 lists the metadata mapping types that are supported in Quickr for Domino. Table 3. Mapping types and their descriptions Mapping Types Explicit mapping Semi-implicit mapping N fields to One property mapping Description Configures which form is mapping to which document type on the ECM server side, and which field is mapping to which property implicitly. Configures which form is mapping to which document type on the ECM server side explicitly, but does not configure which field is mapping to which property. If one field's name in Quickr matches one property's name, then they are mapped implicitly. More 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>

23 </servers> </service> 3.Change hostname to your actual Quickr server's hostname, and change name to your place name. The draft mapping is generated in output.xml: <form_60f44d802ac79d f9002c5d11 formname="demoform"> <mappinginfo doctype=""> <mapping field="c_demotext" property="" propertysheettype=""/> <mapping field="c_demodate" property="" propertysheettype=""/></mappinginfo> </form_60f44d802ac79d f9002c5d11> 4.Copy and paste the draft mapping into qpconfig.xml. You can then change it to set the different mapping types, as follows: Explicit mapping <form_60f44d802ac79d f9002c5d11 formname="demoform"> <mappinginfo doctype="demoecmdoctype"> <mapping field="c_demotext" property="ssname" propertysheettype="pst1"/> <mapping field="c_demodate" property="date" propertysheettype="pst2"/></mappinginfo> </form_60f44d802ac79d f9002c5d11> Semi-implicit mapping <form_60f44d802ac79d f9002c5d11 formname="demoform"> <mappinginfo doctype="demoecmdoctype"> </form_60f44d802ac79d f9002c5d11> N fields to One property mapping <form_60f44d802ac79d f9002c5d11 formname="demoform"> <mappinginfo doctype="demoecmdoctype"> <mapping field="c_demotext c_demodate" property="summary" propertysheettype="pst1"/> </mappinginfo> </form_60f44d802ac79d f9002c5d11> 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. Fill in those properties and publish it to ECM repository. Custom Library Custom Library is used to directly connect you to the ECM server. You can access and manipulate contents in the ECM repository the same as in your Quickr library. You can also view, upload, check out, check in, and update documents on the ECM server in your Quickr

24 Web UI. Follow these steps to use Custom Library: 1. Create a Custom Library page by choosing Place Actions -- New page Custom Library, or Library New Custom Library. Custom Library has the same attributes as Document, such as Name, Description, access control setting, and location (see figure 20). Figure 20. New Custom Library window 2.To connect to the ECM server, you must configure the custom library. From the Quickr ConfigureOpen the newly created custom library page, click the Configure link or select More Actions Configure, in the Action bar. to configure the custom library(see figure 21). Figure 21. Configure Custom Library

25 3.In the connect to a Library of Folder tab, Eenter the ECM server URL in the Server field, enable (check mark) the Log in with my current credentials field, and then choose a folder or subfolder of the ECM server as root of your Custom Library (see figure 21). If you want to log in to the ECM server using another account, just un-check the Log in with my current credentials checkbox and input that account's user name and password. <Figures are not legible; please replace them all with clearer versions or delete> Figure 21. Connect to a Library or Folder tab 4.Click the Configure Default View tab of the Custom Library, to configure how many columns to display (see figure 22). Click OK to save your configuration. Figure 22. <please add a caption here> Now you can see the contents in the ECM server and, just like in your Quickr Library, you can: 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 ECM server

26 Figure 23. <please add a caption here> Figure 24. <please add a caption here> Figure 25. <please add a caption here> Conclusion You should now have a detailed understanding of the features of Quickr for Domino ECM integration. We've introduced you to all its major components, how they function, and how you can use them. Hopefully you can use this article to take full advantage of the powerful functionality of Quickr for Domino ECM integration to make your job easier. Resources Lotus Quickr and Enterprise Content Management: Lotus Quickr integration with IBM ECM: Lotus Quickr wiki: Content Manager Enterprise Edition, Integration with Lotus Quickr: About the authors Albert Wang is a Software Architect based at IBM's China Development Lab (CDL) in Beijing, where he serves as the Quickr Domino Architect and Tech Leader. He's been an author of five Chinese books on computer programming; He's published 30+ papers on computer technolegygers in international conferences or Chinese magazinesacademic Journals.<sentence not clear; please rewrite> You can reach him at wangxu@cn.ibm.com.<please add your Internet address here> Zheng Fei Guo is a Software Engineer at IBM's CDL, working on Lotus Quickr for Domino for

27 the past several years. He has extensive experience with Web 2.0 applications and collaboration software. You can reach him at Jie Ma is a Staff Software Engineer, Functional Verification Test lead, and PM/Scrummaster of the Lotus Quickr ECM Integration team. He's also experienced in Agile software development. You can reach him at majie@cn.ibm.com. Zheng Wei Wang is a Software Engineer in IBM's CDL, working on Lotus Quickr for Domino 8.5 development. You can reach him at zwwang@cn.ibm.com.