Utility for Caching
Metafile Renditions
for Documentum
Cimmetry Systems Inc.
All rights reserved. No part of this publication may
be reproduced, stored in a retrieval system, or transmitted in any form by any
means, electronic, mechanical, photocopying, recording, or otherwise, without
the prior written permission of Cimmetry Systems, Inc.
Cimmetry Systems, Inc. makes no claims with respect
to the adequacy of this documentation, programs, or hardware that it describes
for any particular purpose or respect to the adequacy to produce any particular
result. Information in this document is subject to change without notice. In no
event shall Cimmetry Systems, Inc. be held liable for special, direct, indirect
or consequential damages, losses, costs, charges, claims, demands, or claim for
lost profits, fees, or expenses of any nature or kind.
AutoVue,
AutoVue Professional, AutoVue SolidModel, AutoVue SolidModel Professional,
Panoramic! and Vuelink are trademarks of Cimmetry Systems, Inc. All other company names and
product names mentioned herein are trademarks of their respective companies.
Copyright © 2002-2004 All Rights Reserved
Cimmetry
Systems, Inc.
6700
Côte-de-Liesse,
Table of Content
Supported document formats for Metafile renditions
ii. For 2D Master Drawings with XRefs
Setting Trigger Mechanisms in Documentum
Creating Metafile Type in Documentum
How to obtain the content type for a document
Introduction
This utility uses AutoVue
(Client-Server Edition) as a rendition tool to generate and check in metafiles
into Documentum DMS – Document Management System. Once a metafile
rendition is added to the native document, the next time the file is viewed in AutoVue
Client, AutoVue Server fetches the metafile rendition instead of the native
file.
How it works
Here is a brief description of how the utility handles requests for
creating metafile renditions:
- The client application sends the rendition request to the DMS
server.
The actual
request dispatched by the client depends on the triggering mechanism, which can
be configured on the DMS server side.
Examples of triggering mechanisms include check-in, promotion or
on-demand actions.
- The Server stores the request in a special queue item.
Each queue item
represents a request made by a client to generate a metafile rendition of the
native file.
- The utility polls the queue items from the DMS at predefined
intervals, and retrieves any pending requests.
- The utility then sends relevant information on each request to AutoVue
server to generate the metafile rendition.
- The utility then prompts AutoVue server to check in the metafile
rendition to the DMS.
AutoVue
fro Java server in turn passes the request to the Vuelink to add the metafile
as a rendition to the native document object in the DMS.
What is a metafile?
A metafile is a true replica of the original
file. This lightweight format developed by Cimmetry enhances the performance of
document viewing on the client side.
Supported document formats for Metafile renditions
The utility generates
metafile renditions for all Engineering and Vector formats supported by AutoVue.
Currently, AutoVue supports many file formats, including 2D engineering
drawings and 3D assemblies.
Steps for creating metafiles
i.
For 3D
Assemblies
To create a metafile
for a specific 3D assembly, follow these steps:
- Launch Documentum Desktop Client
application and log on to Documentum.
- Check in all the individual Parts of the assembly into Documentum.
- Check in the Assembly file into
Documentum.
- Create the proper relationship between
each Part and the Assembly.
a. Write down the Object ID for each Part file. (The
Object ID can be obtained from the Advanced
tab in the Document Properties
dialog box.
b. Open the Document
Properties dialog box for the Assembly document.
c. Using the syntax below, list the Object IDs of
the Parts in the Keywords property on the Summary tab.
|
X:nnnnnnnnnnnnnnnn:<filename> |
Or
|
X:nnnnnnnnnnnnnnnn. |
Notes
· X informs
Documentum that you are about to specify a link to an external file.
· nnnnnnnnnnnnnnnn is
the Object ID Documentum associates with the Part document.
(ex.: 090186a180000440)
· <filename> (optional) represents the file name of
the Part document.
· Separate multiple entries
by a comma ‘,’.
· For a detailed description, please refer to the
‘Completing
the Configuration for XRefs’ section in the Vuelink manual.
d. Save the Assembly properties.
- If the On-Demand trigger mechanism
is set up, select the assembly document. Then, from the main menu select Application, csiMetafile, and then Create
Metafile Rendition.
- If the Event-Based trigger
mechanism is set up using the AuditTrail, check out the Assembly and check
it back into Documentum.
ii.
For 2D
Master Drawings with XRefs
To create a metafile
for a 2D Master Drawing that has associated XRefs (External Reference Files),
follow these steps:
- Launch Documentum Desktop Client
application and log on to Documentum.
- Check in all the individual XRefs into Documentum.
- Check in the 2D Master Drawing file into
Documentum.
- Create the proper relationship between
each XRef and the Master Drawing.
a. Write down the Object ID for each XRef. You can
obtain the Object ID from the Advanced
tab in the Document Properties
dialog box.
b. Open the Document Properties dialog box
for the Master Drawing document.
c. Using the syntax below, list the Object IDs of
the XRefs in the Keywords property
under on the Summary tab.
|
X:nnnnnnnnnnnnnnnn:<filename> |
Or
|
X:nnnnnnnnnnnnnnnn |
· X
informs Documentum that you are about to specify a link to an external reference
document.
· nnnnnnnnnnnnnnnn is
the Object ID Documentum associates with the Part document.
(ex.: 090186a180000440)
· <filename> (optional) represents the file name of
the Part document.
· Separate multiple entries
by a comma ‘,’.
· For a detailed description, please refer to the
‘Completing
the Configuration for XRefs’ section in the Vuelink manual.
d. Save the Master Drawing properties.
- If the On-Demand trigger mechanism
is set up, select the Master Drawing document. Then, from the main menu select Application, csiMetafile, and Create
Metafile Rendition.
- If the Event-Based trigger
mechanism is set up using the Audit Trail, check out the Master Drawing
and check it back into Documentum.
Architecture
The utility runs as a java application, polling for queue items from the
DMS.
On the principle that the event-triggering
mechanism is associated with checking in documents, whenever a document is
checked into the DMS, whether it is from the DMS thick client or thin client,
an event is triggered within the DMS. This event creates a queue item
representing a request to create a metafile rendition. On the server side, a
polling application retrieves these queue items from the DMS. Each queue item
holds relevant information about the checked-in document. This information is
sent to the QueueManager, which then adds the queue item to the queue from
where it is retrieved by a different thread (QueueReaderThread). The
QueueReaderThread then interacts with AutoVue server through Vuebean to create
the metafile. Then the QueueReaderThread asks AutoVue server to upload the
metafile to the Vuelink to check into the DMS.
Administrator Guide
System Requirements
The utility itself is
a Java application program and therefore can be run on any platform equipped
with Java Virtual Machine – JVM.
The following software must be already installed on the machine hosting
this utility:
·
Sun’s Java Runtime Environment
(JRE) v1.3.1 or higher
The following software must also be available for the utility to work but may be installed on a different machine than the one hosting the utility:
·
AutoVue Client-Server
Edition v16 or higher
·
Vuelink
for Documentum
·
Documentum
4i v4.x
·
Documentum
RightSite v3.5, 4.x
·
DFC V4.x
Installation
The metafile utility requires AutoVue Server and Vuelink. Before attempting to install Metafile Utility with Documentum, make sure that Documentum, AutoVue, and Vuelink for Documentum are properly installed and configured on your system, according to the manufacturer’s instructions, and are operating correctly.
To install the Utility for caching metafiles
for Documentum, complete the steps outlined under the
following sections:
- Manual Setup
- Setting Trigger Mechanism in Documentum
- Creating Metafile Type in Documentum
- Starting the Utility
Manual Setup
1.
Create
a folder called \cimmetry\metafile_utility.
Example: c:\program files\cimmetry\metafile_utility.
2.
Copy
the content of the folder metafile_utility (found on the distribution CD)
to the folder created in the last step.
3.
Using
any text editor, open the file run.bat
found in the directory \metafile_utility\bin.
4.
Modify
the following settings:
|
JARDIR |
Full path to the
folder that contains metafile.jar along with other JAR files. |
|
PASSWORD |
|
|
DFC |
Note The jar files shipped with the metafile utility are just for the user’s convenience. Since Documentum has multiple versions of DFC, the users may find the shipped DFC library may not be the same as the one they are using. If that is the case, or the user experiences compatibility problems with different versions of DFC, the user can just copy the dfc.jar that the system is using (usually the dfc.jar is within the folder c:\program files\documentum\shared) to this location, and set the parameter DFC point to it. |
Note
By default, csiqcdocumentum.properties file is located under same folder as metafile.jar. If this file is moved to another location, then you need to set the full path to PROPFILE.
|
PROPFILE |
5.
Using
any text editor, open the file csiqcdocumentum.properties found in the directory \metafile_utility\bin.
6.
Modify
the following settings:
|
JVUE_PORT |
The Port Number to which AutoVue Server is listening. By default, this value is 5099. |
|
JVUE_USER |
The user name connecting to AutoVue server. By default, Administrator. |
|
MAX_THREADS |
|
7.
Using
any text editor, open the file csimfdocumentum.properties found in the directory \metafile_utility/bin.
8.
Modify
the following settings:
|
DOCBASE |
|
|
DMS |
URL pointing to Vuelink Servlet http://<APPLICATION-SERVER>/servlet/com.cimmetry.vuelink.documentum.DMS |
|
LASTTIME |
The date from when Audit Trail is
polling. |
|
MINIMUMFILESIZE |
The minimum file size for which a metafile
can be created. Default is 40960. |
|
LOGFILE |
Full path file
name to save log messages. If this entry is not added to the properties file,
all the messages are sent to the console window. |
|
RIGHTSITE_SERVER_NAME |
Name of the
RightSite web server host machine. |
|
RIGHTSITE_SERVER__PORT_NUMBER |
RightSite web
server port number. |
|
USER |
Name of valid Documentum
user. The utility needs to sign into Documentum to access Rendition
Requests. This user ID should have permissions to read and modify Queue
Items. It should also have permissions to send icon mail notifications to
users about the status of their rendition requests. |
Note
The remaining part of this file contains the format list supported by Metafile utilities. If the Utility finds that these types of files have been checked in, it will create a metafile request and notify the AutoVue server to create a rendition Metafile for that object. It also provides flexibility for the DBA.
|
[FileSupported] AutoCAD Drawing=acad AutoCAD Web Format=dwf MicroStation Format=ustn |
For the above entries, the convention is as follows:
Description= content
type
The content type must be consistent with the format recognized by Documentum.
Since some formats are not recorded with Documentum, the entry “Unknown Format=unknown” may be
added to ensure that metafile can be created.
9.
As the desktop client
depends on the dmcl.ini to make links to the Documentum server, the
metafile utility also needs to access the file to retrieve the name of the
server host, called primary docbroker.
Here is an example taken from file dmcl.ini:
|
[DOCBROKER_PRIMARY] host = DMServer |
In order to run Metafile utility properly, the host name should point to the server host which the metafile utility is intended to work on.
10. When a metafile is created, all the recent modifications to a file, either assemblies or parts, should be retrieved from Documentum Server. To ensure this happens, the set the following init parameter for the Vuelink Servlet for Documentum:
|
DisableCache = 1 |
The setting of init parameter method for a servlet may vary for different servlet engines. See the Vuelink for Documentum installation guide for more details.
Starting the Utility
Invoke run.bat from the command line prompt. When prompted for a password, provide one that belongs to a valid Documentum user with administrative privileges.
Configuration
Setting Trigger Mechanisms in Documentum
Metafile Utility for Documentum takes advantage of the event mechanism provided by Documentum. Two kinds of triggering mechanisms are employed with Metafile Utility.
q With the On-Demand (explicit) mechanism, the metafile request is implemented with Desktop client. The user can initiate a metafile request whenever needed. The metafile Utility takes care of the request and creates the metafile.
Note
The On-Demand mechanism is recommended for 3D file formats.
q With the Event-based (implicit) mechanism, the triggering method is involved with registering a particular event such as the check-in with Audit Trail System. The audited event for metafile Utility is dm_checkin. This means that once a document is checked in, an event, which is defined by Documentum, dm_checkin, is fired and the Audit System will record this event with Audit Trail.
Note
The Event-Based mechanism is recommended for 2D file formats.
i. On-Demand Mechanism
The request for creating a metafile for a document can be invoked from within the Desktop-client application. This feature is defined with csiMetaComp DocApp.
Here are the steps to install csiMetaFile DocApp:
1. Make sure that DcDesktopClient DocApp is installed into the Docbase before proceeding. (Refer to DocApp Installer provided by Documentum.)
2. Run the application DocApp Installer.exe from the Start\Program\Documentum program folder.
3. Install csiMetaFile DocApp, located on the distribution CD under \metafile_utility\DocApp\v4.x. (Please see “Vuelink for Documentum” for the detailed explanation on how to install a DocApp).
4. Run Documentum Developer Studio.
5. Log on to the Docbase the csiMetaFile just installed.
6. Open csiMetaFile DocApp from Docbase.
7. To add dm_document object type to csiMetaFile DocApp, select Insert, Object from Docbase, Object Type from the menu.
8.
9. Click the Functionality tab and click Add.
10. Click 'elect Component in the Functionality Description dialog box.
11. Select ACX/AvMetaComp from the list shown in the Application Component dialog box.
12. Click Add and enter AvMetaComp for both the Class Name and Label fields in the Functionality Description dialog box.
13.
Click OK.
The AvMetaComp is added to the DocApp.
14. To check in “csiMetaFile” DocApp into the Docbase, select DocApp/Check In DocApp… from the menu.
15. Keep the same Version – 1.0 à 1.0:
16. Exit ‘Documentum Developer Studio’.
17.
Follow step 17 only if you are customizing Documentum Desktop Client
version 5.2.
Note: If you have not customized your Desktop Client’s menus before, you can simply check in the pre-customized
MenuSystem5.ini located in the distribution disc's directory:
AutoVue_For_Java\dms_customization\server\Documentum5.2\DocApp\AutoVue.
a.
Run Documentum Desktop
Client.
b.
Log on to the DocBase
into which you installed the AutoVue DocApp.
c.
Navigate to the
System/Desktop Client cabinet.
d.
Check out the file
MenuSystem5.ini.
e.
In a text editor such as Notepad, open the file
MenuSystem5.ini.
f.
Search for the text "&Applications".
This section defines your Applications menu.
g.
Increase the "Children" property of the Applications menu by 1.
Example:
An uncustomized Applications menu has
a Children property of 0. If you increase
this property to 1, your Applications menu section will look
something like this:
BEGIN MenuItem
Children=1
CommandStateFlag=DC_CSF_ALWAYS
Label_English=&Applications
Label_French=A&pplications
Label_German=An&wendungen
Label_Italian=&Applicazioni
Label_Japanese=ƒAƒvƒŠƒP[ƒVƒ‡ƒ“(&A)
Label_Korean=ÀÀ¿ë ÇÁ·Î±×·¥(&C)
Label_Spanish=Apli&caciones
END MenuItem
h.
Add
the following lines after END MenuItem pertaining
to the Applications menu (or if you
have already customized your Desktop Client to include the AutoVue menu, you can
add these lines immediately below the lines you previously added for AutoVue):
BEGIN MenuItem
Children=1
CommandStateFlag=DC_CSF_ALWAYS
FunctionalClass=AvMetaComp
Global=True
Label_English=csiMetaFile
END MenuItem
BEGIN
MenuItem
FunctionalClass=AvMetaComp
Label_English=Create
Metafile Rendition
END
MenuItem
If you have already customized your Desktop Client with the
AutoVue menu items, there is a pre-customized copy of MenuSystem5.ini (named MenuSystem5_all_menus.ini)
that includes menu items for both AutoVue and the Metafile Utility. It is
located in the folder \AutoVue_For_Java\metafile_utility\Docapp\v5.2\csiMetafile.
i.
Check back into the Docbase
the file MenuSystem5.ini. Select Check
in from file… and point to the copy of this file that you have edited (or the
pre-customized version of the file if appropriate).
j.
Restart Windows for the
configuration changes to take effect.
18.
With Desktop-client, if a
document is selected, click csiMetafile and
then Create Metafile Rendition from the
Applications menu.
This initiates a metafile request and the metafile utility will create a
metafile for that document.
19.
Start Documentum
Desktop-client and log on to the Docbase where you installed csiMetaFile.
The desktop client lists the added menu item as indicated below:
Registering AVMETALib.dll
Before
Desktop-client can work cooperatively with csiMetaFile DocApp to trigger
a metafile request, the metafile component must be installed and registered.
1. Check the folder \cimmetry\metafile_utility created in Manual Step, to make sure that both AVMETALib.dll and msvbvm69.dll are in the folder <root>\cimmetry\metafile_utility\bin.
2. If these files are not found, copy the files AVMETALib.dll and msvbvm60.dll found on distribution CD under \metafile_utility\bin to the folder created in the last step.
3. To register the component AvMetaComp, run Regsvr32.exe located in the directory <root>\cimmetry\metafile_utility\bin\AVMETALib.dll, where <root> is the root directory where \cimmetry\metafile_utility folder was created in step 1.
Note
The registration of AVMETALib.dll is specific to client machines running MS Windows platforms only.
ii. Event-Based Mechanism
Following is the procedure for registering an event with the Audit Trail System using Documentum Administrator. For further details, please refer to eContent Server Administrator’s Guide.
1. Start Documentum Administrator and
connect to the Docbase.
2. Under Docbase Management, click Audit Trail.
A page for registering events for Auditing is displayed.
3. Click Register events for all objects of a type.
A list of object types is displayed.
4. Select dm_sysobject and click the plus sign next to the item.
All the available selections under dm_sysobject
are displayed.
5. Select dm_document and click OK.
The Audit Registration page is displayed.
6. Select the event dm_checkin and click Add.
The event is listed in the right panel.
7. To complete the registration,
click Done.
Creating Metafile Type in Documentum
In order to save metafiles into
Docbase, a metafile format must be created using the Documentum Administrator application.
1.
Start Documentum Administrator and connect to the Docbase.
2.
Under Docbase Management, click Formats.
A page for Editing/Viewing formats is displayed.
3.
Click New.
A page for creating a new format is displayed.
4.
In the Name field, enter csiMetafile.
5.
In the Description field,
enter Cimmetry Metafile.
6.
To accept the settings, click Create.
The new format is created.
7.
Under Formats, click Edit.
All the formats are listed, including the metafile format just created.
How to obtain the content type for a document
The content type used in csimfdocumentum.properties should be consistent with that defined by Documentum. To find out the content type recorded by Documentum for a checked-in document for Desktop-client, follow the steps below.
1. Select a document and press ctrl.
2. From the Help menu, click
Documentum Help.
The Documentum Interactive Message
Tester window appears.
3. Under Command, enter “getdata,c,dcapp,selected”, and click
Execute.
The object ID of the document is displayed under Results.
4. Under Command, type “get,c,NNNN,a_content_type”, and
click Execute.
(NNNN stands for the object ID
obtained in the last step. In this example, it is “090003e980013547”.)
The content type of the selected document is displayed under Results.
5. Make note of the content type (vsd1 in this example) and input an entry into csimfdocumentum.properties so that the metafile utility can pick up the request and create a metafile for this type of document.
Feedback
Section
Cimmetry System products are designed according to your needs. We
appreciate your feedback, comments and suggestions. Contact us by fax, e-mail
or telephone. We added a Feedback button
to our Web page that activates an easy-to-use feedback form. Let us know what
you think!
Cimmetry Systems, Inc.
General Inquiries
Telephone: +1
514 735-3219
Fax: +1
514 735-6440
E-mail: info@cimmetry.com
Web Site: http://www.cimmetry.com
Sales Inquiries
Telephone: +1
514 735-3219 or 1-800-361-1904
Fax: +1
514 735-6440
E-mail: sales@cimmetry.com
Technical Support
Telephone: +1
514 735-9941
Fax: +1
514 735-6440
E-mail: techsup@cimmetry.com