Getting started with DB2 Document Manager, Part 2: Set up Integration and Properties Exchange

Using Microsoft Word

This tutorial builds on an earlier tutorial (Getting started with DB2 Document Manager, Part 1: Build a simple client application in DB2 Document Manager) and illustrates a valuable feature of the product. In this step-by-step tutorial, learn how to improve productivity and end-user performance in a client application. Learn to set up Application Integration with Microsoft Word and map properties in your Word documents to properties in the content repository. This tutorial demonstrates how you can add Document Manager menus and commands to an application like Microsoft® Word®, and how to use native properties in your documents for search and retrieval once the documents are stored in the content repository. Also, learn about hierarchical-Controlled Vocabulary Lists (CVLs).

Share:

Paul R. Welka (welkapr@us.ibm.com), Senior Software Engineer, IBM

Paul R. WelkaPaul Welka is a senior software engineer at IBM with more than 12 years of experience in user centered design.



16 November 2006

Before you start

In this section, learn what to expect from this tutorial and how to get the most out of it.

About this tutorial

This tutorial describes the steps necessary to implement DB2® Document Manager Application Integration and Properties Exchange with Microsoft Word. Build a simple client application with which:

  • You are able open a letter in Microsoft Word containing fields (To, Street, City, State, and Zip) that are mapped to Microsoft Word document properties.
  • You are able to modify those fields.
  • If you close the document, you are automatically prompted to save the document to Document Manager.
  • If you choose the Letters class when you save the document, a dialog appears in which the fields (To, Street, City, State, and Zip) are automatically populated.
  • If you select a different State, a drop-down list of Cities within the new state is automatically generated.
  • You can use the Apply button to save the document in Document Manager.
  • You can use a Search Template to find the document you just added.

Objectives

The objective of this tutorial is to provide a step-by-step procedure for enabling Application Integration and Properties Exchange with Microsoft Word in DB2 Document Manager. This tutorial uses the Document Manager Designer tool to build a simple application. During this process, discover the purpose of various Document Manager configuration objects and how they fit together.

Prerequisites

This tutorial is written for anyone who needs to learn the basics of DB2 Document Manager application design, and whose skills are at a beginner to intermediate level. No programming knowledge is required for this tutorial.

System requirements

To follow the steps in this tutorial, you need a functioning DB2 Document Manager system with DB2 Content Manager as the underlying repository. You need access to Document Manager Designer (the configuration user interface), Document Manager Service Manager (the user interface that starts and stops the Document Manager services), and the Document Manager Desktop (the end-user GUI) with Application Integration installed. This tutorial is based on DB2 Document Manager 8.3 with Fix Pack 3.


Overall steps

These are the steps necessary for building the user interface with the Document Manager Designer tool (step-by-step instructions are provided later in this tutorial):

  1. Create the attributes that you want your documents to contain. For example:
    • To
    • Street
    • City
    • State
    • Zip
  2. Create an item type.
  3. Create a document class.
  4. Create CVLs for the Cities and States.
  5. Create CVL links.
  6. Create an Add dialog.
  7. Associate the Add dialog with the document class.
  8. Associate a user with the Add dialog.
  9. Associate the CVL links with the Add dialog.
  10. Create menus. For example:
    • Document Menu
    • Desktop Menu Bar
    • Word Toolbar
  11. Create a Search dialog.
  12. Associate the CVL links with the Search dialog.
  13. Create a View.
  14. Create a Properties Exchange.
  15. Create an Application Integration Object and associate the Properties Exchange with it.
  16. Create a Desktop Template and associate a user with it.

In addition to these steps, you must create a Microsoft Word document that contains the To, Street, City, State, and Zip document properties (detailed instructions are provided later in this tutorial).


Step-by-step instructions

These step-by-step instructions include several screen snapshots. This tutorial does not attempt to explain every option on every screen. To learn more about all of the available options, and how to tailor Document Manager to your needs, refer to the Administration Guide (available on the Document Manager support Web site) in the Resources section of this document.

Step 1: Attributes

Create the attributes that you want within your documents. This tutorial uses a letter document as an example. You want your letters to have five attributes:

  • To
  • Street
  • City
  • State
  • Zip

In the Document Manager Designer tree, navigate to Global > Library Properties, then click New on the toolbar. Define the To property, using the following screen snapshot for reference, then click OK.

Define the To Property
Defining the To property

In the Designer tree, navigate to Global > Library Properties, then click New on the toolbar. Define the Street property, using the following screen snapshot for reference, then click OK.

Define the Street Property
Defining the Street property

In the Designer tree, navigate to Global > Library Properties, then click New on the toolbar. Define the City property, using the following screen snapshot for reference, then click OK.

Define the City Property
Define the City property

In the Designer tree, navigate to Global > Library Properties, then click New on the toolbar. Define the State property, using the following screen snapshot for reference, then click OK.

Define the State Property
Define the State property

In the Designer tree, navigate to Global > Library Properties, then click New on the toolbar. Define the Zip property, using the following screen snapshot as reference, then click OK.

Define the Zip Property
Defining the Zip property

Step 2: Item type

The next step is to create an item type. When you design a document management solution, it is sometimes useful to think of an item type as a broad grouping of documents that have similar storage and access control requirements. This tutorial uses a single item type for all correspondence (for example, letters, memos, and so on).

In the Designer tree, navigate to Global > Desktop > Item Types, then click New on the toolbar. Define the new item type, using the following screen snapshots for reference, then click OK.

Define an Item Type - General
Defining the Item Type - General
Define an Item Type - Access Control
Defining the Item Type - Access Control

Class, State, and Properties


In your item type, you must specify the attributes to use for Class, State, and Properties. Document Manager uses these attributes to store document class information, lifecycle status, icons, and other objects. In the example, DM Class, DM State, and DM Properties are used. However, you may need to use attributes that are unique to your system. To determine which attributes to use for Class, State, and Properties, navigate to Global > Desktop > Library Configuration in the Designer tree, and view your Library Configuration. Use the Class, State, and Properties attributes in your item type as the ones you find in your library configuration.

Define an Item Type - Attributes
Defining the Item Type - Attributes

Step 3: Document classes

A document class is a grouping of documents that all have similar management requirements. For example, within the Correspondence item type, you could have a class for memos (documents that are controlled through a change and approval process) and a separate class for letters (documents that are not controlled). In this tutorial, within the Correspondence item type, you must create a document class for letters. In the Document Manager Designer tree, navigate to Global > Desktop > Item Types > Correspondence > Classes, then click New on the toolbar. Define the non-controlled document class, using the following screen snapshot for reference, then click OK.

Define the Letters Document Class
Defining the Letters Document Class

Step 4: Controlled Vocabulary Lists

A CVL is a list of valid values. In this tutorial, you create CVLs for the following:

  • California Cities
  • New York Cities
  • U.S. States

In the Document Manager Designer tree, navigate to Global > Desktop > CVLs > Lists, then click New on the toolbar. Define the CVLs for CA Cities, NY Cities, and U.S. States, using the following screen snapshots for reference, then click OK.

Define the CA Cities CVL
Defining the CA Cities CVL
Define the NY Cities CVL
Defining the NY Cities CVL
Define the States CVL
Defining the States CVL

Step 5: Create CVL links

When you link a CVL to a Library property, you can control the set of valid values for that property. For example, if the CVL for States contains CA and NY, and you link the States CVL to the State property, the user is only able to choose CA or NY for the State property. In this step, you link the States CVL to the State property. Then, you create a more complex, hierarchical link for the City property.

In the Document Manager Designer tree, navigate to Global > Desktop > CVLs > Links, then click New on the toolbar. Create the States CVL Link using the following screen snapshot for reference.

Create the States CVL Link
Creating the States CVL Link

A hierarchical link is needed for the City property. You want the valid values for the City property to depend on which U.S. state is chosen. Therefore, you need a CVL link that specifies the following:

  • The library property to which you are linking is City.
  • The parent property is State (the list of valid values for the City property depends on the State property assigned).
  • If the State is CA, use the CA Cities CVL.
  • If the State is NY, use the NY Cities CVL.

In the Document Manager Designer tree, navigate to Global > Desktop > CVLs > Links, then click New on the toolbar. Create the Cities CVL link, using the following screen snapshot for reference.

Create the Cities CVL link
Creating the Cities CVL Link

Step 6: Create an Add dialog and associate a user with it

When a user adds a letter to the Document Manager, an Add Letter dialog is displayed. Create the Add dialog using the following screen snapshots for reference:

Create the Add Dialog - General
Creating the Add Dialog - General
Create the Add Dialog - Top section
Creating the Add Dialog - Top Section

Step 9: Associate the Add dialog with the document class

Earlier you created a document class called Letters. When the end user chooses this class (when they add a document to Document Manager), you want the Add Letter dialog to be displayed. Therefore, you need to associate the Add Letter dialog with the Letters document class. In the Document Manager Designer tree, using drag and drop, drag the Add Letter dialog you created earlier to the Letters document class.

Step 10: Associate a user with the Add dialog

You must associate a user with the Add Letter dialog (in order for that end user to be able to use the dialog). In the Designer tree, Navigate to Global > Desktop > Item Types > Correspondence > Classes > Letters > Actions and Dialogs > Add Letter and right-click on the Users folder. Choose New, select a user, and click OK to associate that user with the Add Letter dialog.

Step 11: Associate the CVL links with the Add dialog

On the Add Letter dialog, the end user can choose a City and State. Because you want to control the set of valid values for those properties, you need to associate the Cities and States CVL links with the Add Letter dialog. Drag and drop the Cities CVL link you created earlier to the Add Letters dialog. Then, drag the States CVL link you created earlier to the Add Letters dialog.

Step 12: Create menus

Menus can display commands and sub-menus to the end user. You can display a menu as a menu bar, a sub-menu, a toolbar, a right-click menu, a double-click menu, or an application menu (a Document Manager menu that is displayed within an application such as Microsoft Word). In this tutorial, you create three menus (a menu bar with one sub-menu, plus a toolbar for Microsoft Word).

First, create the Document Menu. Navigate to Global > Desktop > Menus and click the New button on the toolbar. Create the menu using the following screen snapshots for reference, then click OK.

Define the Document Menu - General
Defining the Document Menu - General
Define the Document Menu - Properties
Defining the Document Menu - Properties

Next, create the Desktop Menu Bar. Navigate to Global > Desktop > Menus and click the New button on the toolbar. Create the menu bar, using the following screen snapshots for reference, then click OK.

Define the Desktop Menu Bar - General
Defining the Desktop Menu Bar - General
Define the Desktop Menu Bar - Properties
Defining the Desktop Menu Bar - Properties

Finally, create a toolbar for Microsoft Word. This toolbar should have a single button that enables the Word user to check a document within the content repository. Navigate to Global > Desktop > Menus and click the New button on the toolbar. Create the new toolbar, using the following screen snapshots for reference, then click OK.

Define the Word Toolbar - General
Defining the Word Toolbar - General
Define the Word Toolbar - Properties
Defining the Word Toolbar - Properties

Step 13: Create a Search dialog

Search dialogs enable users to search by properties to retrieve documents from the content repository. Navigate to Global > Desktop > Searches and click the New button on the toolbar. Create a Search dialog that end users can use to search for letters, using the following screen snapshots for reference, then click OK.

Define a Search Dialog - General
Defining a Search Dialog - General
Define a Search Dialog - Properties
Defining a Search Dialog - Properties

Step 14: Associate the CVL links with the Search dialog

In the search dialog, the end user can specify several properties, including the City and State, when searching for a letter. Since you want to control the set of valid values for the City and State, you need to associate the Cities and States CVL links with the Letter Search dialog. Drag and drop the Cities CVL link you created earlier to the Letter Search dialog. Then, drag the States CVL link you created earlier to the Letter Search dialog.

Step 15: Create a view

Views determine the columns that are displayed, document sort order, and the number of documents returned as the result of a search in the end-user GUI. Multiple views can be provided (for different users or for different types of documents). In this tutorial, you are creating a single view (for letters). Navigate to Global > Desktop > Views and click New. Create a view using the following screen snapshots for reference, then click OK.

Define the View - General
Defining the view - General
Define the View - Display
Defining the view - Display

Step 16: Create a Properties Exchange

In this tutorial, you are mapping properties of your Microsoft Word documents to corresponding properties in your content repository. Navigate to Global > Desktop > Property Exchanges and click New. Create a Properties Exchange, using the following screen for reference, then click OK.

Create a Properties Exchange
Creating a Properties Exchange

Step 17: Create an Application Integration object

An Application Integration object is a profile that specifies how Document Manager should integrate with an application. In this tutorial, you create an Application Integration object for Microsoft Word. This object causes two Document Manager toolbars to be added to Microsoft Word (toolbars that are useful when you edit a document):

  • A top toolbar with these two choices:
    • Embed a document from the content repository
    • Link to a document in the content repository
  • A bottom toolbar with one choice:
    • Check in a document to the content repository

The choices in the top toolbar use Object Linking and Embedding (OLE), the compound document standard developed by the Microsoft Corporation.

Navigate to Global > Desktop > Application Integrations and click New. Create an Application Integration object, using the following screen snapshot for reference, then click OK.

Create the Application Integration Object - General
Creating the Application Integration Object - General
Create the Application Integration Object - Add-Ons
Creating the Application Integration Object - Add-Ons
Create the Application Integration Object - Menu
Creating the Application Integration Object - Menu

Step 18: Associate the Properties Exchange and the Application Integration object

To successfully exchange the properties of your Microsoft Word documents with the corresponding properties in your content repository, you must associate the Properties Exchange you created earlier with the Application Integration object. In the Designer tree, drag and drop the Letters Properties Exchange to the Word Application Integration object.

Step 19: Create a Desktop Template

The final steps in building your Document Manager client application consist of defining a Desktop Template and associating a user with it. The Desktop Template configures the DB2 Document Manager Desktop for end users. It pulls together menus, views, searches, and other objects that comprise the end-user GUI. In this tutorial, you create a Desktop Template called "Letter Demo". In the Designer tree, navigate to Global > Desktop > Desktop Templates and click New. Create the Desktop Template, using the ten screen snapshots that follow, then click OK.

Define the Desktop Template - Template name
Defining the Desktop Template - Template Name
Define the Desktop Template - Menu interface
Defining the Desktop Template - Menu Interface
Define the Desktop Template - View templates
Defining the Desktop Template - View Templates
Define the Desktop Template - Search templates
Defining the Desktop Template - Search Templates
Define the Desktop Template - Application Integration
Defining the Desktop Template - Application Integration
Define the Desktop Template - User options
Defining the Desktop Template - User Options
Define the Desktop Template - Item delivery
Defining the Desktop Template - Item Delivery
Define the Desktop Template - Language
Defining the Desktop Template - Language
Define the Desktop Template - Data lists
Defining the Desktop Template - Data Lists
Define the Desktop Template - Desktop applications
Defining the Desktop Template - Desktop Applications

Step 20: Associate a user with the Desktop Template

You must associate a user with the Desktop Template in order for that end user to use that Desktop Template. In the Designer tree, navigate to Global > Desktop > Desktop Templates > Letter Demo and right-click on the Users folder. Choose New, select a user (the same user you associated with the Add dialog earlier), and click OK.


Create a Microsoft Word document for this tutorial

To test the client application you created in the Document Manager Designer, you must create a Microsoft Word document with the To, Street, City, State, and Zip document properties. Open a blank document in Microsoft Word, navigate to File > Properties, and click the Custom tab. Add new text properties for To, Street, City, State, and Zip, as shown in the following screen snapshot:

Create Custom Document Properties in Word
Creating Custom Document Properties in Word

In your blank document, create a template for letters. Use the following screen snapshot as a guide. Ensure that this template includes the To, Street, City, State, and Zip properties.

Create the Letter Template in Word
Creating the Letter Template in Word

Finally, in Word, you must specify that To, Street, City, State, and Zip are fields which are mapped to document properties. First, select the word "To" and click Insert > Field on the Word menu bar. Use this screen snapshot as a guide to map this field to the To document property you created earlier:

Create the To Field
Creating the To Field

Repeat this process for the To, Street, City, State, and Zip fields. For each one, select the word in the document, and click Insert > Field on the Word menu bar, create the field and click OK.

Finally, save the letter document.


Test the application

When you complete the steps in this tutorial, you can "cache-out" your configuration changes and try the application. Perform these steps to test the application:

  1. Open Document Manager's Service Manager GUI. Start the Cache Manager and Lifecycle Services.
  2. Open the Desktop user interface you created. Be sure to sign in with the user ID you associated with the Add dialog and the Desktop Template.
  3. Open the letter template you created using Microsoft Word (be sure to click Yes if you are prompted to start Document Manager). Notice the custom toolbars that Document Manager adds.
  4. In Word, under File > Properties, modify the custom properties (To, Street, City, State, and Zip).
  5. Select all of the custom properties and click Refresh (F9) to refresh the corresponding fields in the document.
  6. Close the document, and you are automatically prompted to save the document to Document Manager.
  7. Choose the Letters class when saving the document. A dialog appears in which the fields (To, Street, City, State, and Zip) are automatically populated.
  8. If you select a different State, the drop-down list of applicable Cities is automatically generated (limited to Cities within that State).
  9. Click Apply to save the document in Document Manager.
  10. On the Document Manager Desktop, use the Letter Search to find the document you just added.

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.

Discuss

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 Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management, Industries
ArticleID=175139
ArticleTitle=Getting started with DB2 Document Manager, Part 2: Set up Integration and Properties Exchange
publish-date=11162006