eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide

eRoom Enterprise 7.2 eDK for Workflow
Toolkit Guide
Documentum, Inc., a division of EMC
6801 Koll Center Parkway, Pleasanton, CA 94566
(925) 600-6800
COPYRIGHT
Copyright © 1997-2004
Documentum, Inc., a division of EMC
6801 Koll Center Parkway, Pleasanton, CA 94566
(925) 600-6800
Trademarks
Documentum® Documentum RightSite®, Documentum Server®, Docbasic®, Documentum DocPage
Server®, Now You Know®, Documentum WorkSpace®, Documentum SmartSpace®, Documentum
ViewSpace®, AutoRender Pro™, Docbase™, DocInput™, Docobject™, DocPage Builder™, Documentum
4i™, Documentum Administrator™, Documentum CADLink™, Documentum Commerce Server
Integrators™, Documentum Application Server Integrators™, Documentum Content Authentication
Services™, Documentum Content Personalization Services™, Documentum ContentCaster™, Documentum
Corrective Action Manager™, Documentum Desktop Client™, Documentum Developer Studio™,
Documentum DocControl Manager™, Documentum DocLoader™, Documentum DocViewer™, Documentum
Dynamic Content Assembler™, Documentum eConnector for CAD™, Documentum eConnector™ for IBM
WebSphere® (IBM and WebSphere are trademarks of IBM) Documentum eConnector for SAP™ (SAP is a
trademark of SAP AG), Documentum eConnector™, Documentum eConnector™ for BEA Weblogic® (BEA
is a registered trademark of BEA Systems Inc) Documentum eConnector™ for JDBC, Documentum
eConnector™ for ATG Dynamo® (ATG and Dynamo are registered trademarks of Art Technology Group),
Documentum eConnector™ for Lotus Notes® (Lotus Notes is a registered trademark of Lotus
Development Corporation) Documentum eContent Server™, Documentum Engagement Services™,
Document Engagement Server™, Documentum ftpIntegrator™, Documentum Intranet Client™,
Documentum iTeam™, Documentum Reporting Gateway™, Documentum Site Delivery Services™,
Documentum Web Development Kit™, Documentum Web Gear™, Documentum WebCache™,
Documentum Web Publisher™, GMPharma™, GXPharma™, GDPharma™, GSPharma™, Momentum™, Virtual
Document Manager™ (VDM), Documentum Selfrepair™, and eRoom are trademarks or registered
trademarks of Documentum, Inc. in the United States and throughout the world. All other company and
product names are used for identification purposes only and may be trademarks of their respective
owners.
eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide | i
What is the Documentum eDK for Workflow? .............................................................. 1
Additional Resources .................................................................................... 1
Requirements............................................................................................. 2
Installing the eDK for Workflow ................................................................................. 2
Pre-Installation Requirements ......................................................................... 2
eRoom Server............................................................................................. 2
Content Server ........................................................................................... 3
Documentum DocApp .................................................................................... 3
Register Business Object ................................................................................ 4
The New Product Development Sample Application ..................................................... 4
Action Descriptions and Usage .................................................................................. 5
Add members to an eRoom ............................................................................. 6
Check a file out from Content Server to an eRoom ................................................ 6
Check a file into Content Server from an eRoom ................................................... 6
Create an eRoom ......................................................................................... 7
Create a database row .................................................................................. 7
Create a folder ........................................................................................... 7
Create a content link in an eRoom.................................................................... 7
Troubleshooting ...................................................................................................... 7
eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide | 1
What is the Documentum eDK for Workflow?
What is the Documentum eDK for Workflow?
The Documentum eDK for Workflow is a toolkit and sample application that enables you to
develop scripts that can be launched from within Documentum Workflows, but perform
tasks on the eRoom server. In particular, the toolkit provides resources for logging into and
remotely executing the following tasks on the eRoom server.
•
Creating an eRoom
•
Adding members
•
Creating an eRoom item (folder, discussion topic, or database row)
•
Creating a link
•
Checking a file out from Content Server to an eRoom
•
Checking a file in to Content Server from an eRoom
The eDK for Workflow consists of several Java classes, which you can edit for your
purposes. In addition, there is a service-based business object used to invoke the eRoom
requests. Under normal circumstances the business object remains unchanged. Finally,
there is a simple New Product Development (NPD) sample application to provide an incontext example of how you might use the eDK. The Java classes that you edit
communicate with the service-based business object, which in turn communicate with the
eRoom server to perform the desired collaboration actions within a workflow.
To install and configure the eDK for Workflow, a file or files must be placed in each of three
locations:
•
The eRoom 7 server
•
The Content server
Additional Resources
The eDK for Workflow is part of a larger configuration of Documentum’s Content Server,
Workflows, eRoom 7, etc. Consequently, you will most likely need to refer to other
documentation resources in order to use eDK for Workflow effectively. The following list
suggests some of the primary sources you may need.
•
For information on the Java classes included with eDK for Workflow, see the Javadoc
included with eDK files.
•
For information on Documentum workflows, refer to the Workflow Manager User Guide.
•
For information on managing workflows by means of the application programming interface, see Documentum Content Server Fundamentals.
•
For information on workflow method execution, see the Content Server Administrator’s
Guide.
•
For information on Documentum DocApps, see the Documentum Application Builder
User Guide.
eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide | 1
Installing the eDK for Workflow
Requirements
eRoom requirements for scripts created with the Actions Toolkit are the same as they are
for eRoom Enterprise 7.2, plus you must have the eRoom Workflow Extensions installed. In
addition, you must have Content Server 5.1 or later and WDK Web Server 5.2 or later.
Installing the eDK for Workflow
The eDK for Workflow Extensions are packaged in a single .zip file containing three smaller
.zip files:
•
Eroomserver.zip
•
Contentserver.zip
•
eDKDocapp.zip
Pre-Installation Requirements
The following requirements must be met before you install the eDK for Workflow
Extensions:
•
You must have already installed and configured eRoom Enterprise, including the ECM
Extensions. Refer to the eRoom 7 Installation and Configuration Guide or the eRoom 7
Upgrade and Configuration Guide for instructions on installing eRoom 7 and eRoom
Enterprise. Refer to the eRoom Enterprise 7.2 ECM Extensions Workflow Integration
Guide for information on installing the ECM Extensions.
•
The logins and passwords for eRoom accounts and Content Server accounts must be synchronized.
•
The following three Documentum applications must be installed: Application Installer,
Application Builder, and Workflow Manager.
eRoom Server
Perform the following procedure on the eRoom server in order to properly place an ASP file
into an IIS Virtual Directory.
1. In the IIS Management Console, expand the server tree and right-click on Default Web
Site.
2. Choose New, then Virtual Directory. A creation wizard is launched.
3. In the creation wizard, specify the following:
ƒ
Virtual Directory Alias: eRoomWFActions
ƒ
Web Site Content Directory: Any valid path (preferably outside the eRoom
installation, so it won’t be overwritten by an upgrade). For example, c:\eRoom
Workflows.
ƒ
Access Permissions: Allow Read and Run Scripts.
4. When the wizard is completed, right click on the new virtual directory and choose Properties.
5. On the Virtual Directory tab, set the Application Protection to Low.
2 | eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide
Installing the eDK for Workflow
6. On the Directory Security tab, make sure that anonymous access is allowed.
7. Extract the ERWFactions.asp file from the eroomserver.zip file into the virtual directory
filepath location.
8. Extract the eRoomCS.dll file from the eroomserver.zip file into a location where you
normally place .dll files and execute the following from a Windows command prompt:
regsvr32 eroomCS.dll
Content Server
Perform the following configuration procedures on the Documentum Content Server
machine:
1. Log in to the Content Server machine as the account owner of the Documentum Installation. (This is the account that was used to install Content Server and owns all the files
and directores.)
2. The contentserver.zip file contains two .zip files: javaclasses.zip and javasource.zip.
Extract the contents of javaclasses.zip to the %DOCUMENTUM%\dba\java_methods directory. Extract the contents of javasource.zip to an appropriately-named directory of your
choosing.
The files in javaclasses.zip are compiled files that are necessary to run applications built
with the eDK. The files in javasource.zip are Java source files that you will customize.
(The javasoure.zip file also contains a directory with Javadoc files--HTML pages
describing the classes, interfaces, constructors, methods, and fields of the Java files.)
After you customize and compile the Java files, you should place the resulting class files
in the %DOCUMENTUM%\dba\java_methods directory.
3. Set the JAVA_HOME environment variable to the root directory for the Java Developer’s
Kit. For example, C:\Program Files\Documentum\jdk\131_04.
4. Add the %JAVA_HOME%\bin directory to the PATH environment variable. For example, set
PATH = %PATH%;%JAVA_HOME%\bin.
5. Make sure the following paths are prepended to the CLASSPATH environment variable:
C:\Program Files\Documentum\Shared\dctm.jar
C:\Program Files\Documentum\Shared\dfc.jar
C:\Program Files\Documentum\Shared\xercesImpl.jar
C:\Program Files\Documentum\Shared\xml-apis.jar
C:\Documentum\dba\java_methods
C:\Documentum\config
Documentum DocApp
The DocApp consists of workflow templates and method objects. Use the following
procedure to install the DocApp.
eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide | 3
The New Product Development Sample Application
1. Extract the contents of the eDKDocApp.zip file to a temporary directory. This will create
a subdirectory named eDKforWorkflows.
2. Log in to the Documentum Application Installer.
3. Select the eDkforWorkflows folder that you extracted in Step 1.
4. Select a location for the installer log and follow the instructions for installing the
DocApp.
When you are finished, the newly-installed application is named eDkforWorkflows and
appears in the /System/Applications subdirectory.
Register Business Object
eDK for Workflow contains one business object, named ERItemCreator. Use the following
procedure to register this business object:
1. Download the DfDborManage utility from the following location on the Documentum
developer site:
http://customernet.documentum.com/developer/componentexchange.htm
2. Extract the utility and install it according to the included instructions.
3. Use the following command to register the business object:
java com.documentum.fc.tools.DfDborManage register IERItemCreator service
ERItemCreator 1.0
The New Product Development Sample Application
In order to provide an illustrative context for the eDK Toolkit, we have provided a New
Product Development (NPD) sample application. This workflow involves a product
requirements document that needs to undergo an internal Engineering review. After that, it
must be reviewed by an external supplier. If the engineers find problems with the
document, they will collaborate with the product team to make revisions.
Once Engineering approves the document, the external supplier of the components reviews
it to ensure that they can meet the requirements. While this occurs, the document is
locked within Content Manager, checked out, and placed into another eRoom, which is
accessible to the external manufacturing partner. The manufacturer then adds content to
the document and returns it, with the approval of a designated gatekeeper. Once the
document is approved by the gatekeeper, it is automatically checked back into its Content
Manager. This gatekeeper-based approach illustrates only one of several options for
triggering checkin activity. Other options include the use of Business Process Services (BPS)
or the use of an eRoom Custom Command.
The following illustration shows the layout of the NPD Sample Application as it appears in
the Documentum Workflow Manager.
4 | eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide
Action Descriptions and Usage
The user initiating the workflow must provide three items of information:
•
a database location in an internal eRoom (for resolution of Engineering review comments)
•
a folder location in an external eRoom (for comments from the manufacturing partner)
•
a draft of the product requirements document, which is stored in Content Manager
If Enginnering decides that the document needs further revisions, then two items, a
database row and a link, are created automatically. Once enginneering approves the
document, then it is checked out of Content Manager and placed in a folder in the external
eRoom for review by the manufacturing partner.
Action Descriptions and Usage
There are several Java classes that perform Workflow actions. You need to customize the
source file for each of these classes in specific ways to fit your situation. Within each
source file, you will find sections with the header comment: [***** Customize Here *****].
To customize, locate these headers and read the commented explanation for an
explanation of how to customize a particular section of the source file. In general, these
classes work at runtime as follows:
eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide | 5
Action Descriptions and Usage
•
The Java classes are launched as a Workflow method. (The run_as_server attribute is set
to TRUE.)
•
Using passed-in credentials, the Java class establishes a Documentum Foundation
Classes (DFC) session and retrieves the appropriate work item and package.
•
The Java class invokes a Documentum service-based business object, which fulfills the
request.
The passed-in credentials do not need to be explicitly set, since they are established at
runtime by Content Server. The credentials are the same for each Workflow action, as
follows:
•
docbase--The name of the docbase repository from which to check the file out.
•
username--The name of the user invoking the work item.
•
package_id--The package ID of the workflow.
•
login_ticket--The login ticket used to establish a DFC session.
The following sections describe the actions you can perform, and the unique aspects of
each of the customizable Java classes.
Add members to an eRoom
Called when the ERAddMember Workflow method is invoked, this class adds members to an
eRoom. The members to be added are obtained by querying for a list of all performers
within the Workflow. The members being added must already have an eRoom membership
profile with exactly the same username in the eRoom server as in the Docbase repository.
•
Source file name: AddMemberWFM.java
•
Class name: AddMemberWFM.class
Check a file out from Content Server to an eRoom
Called when CheckOutToERoom method is invoked, this class automates the checkout of
Docbase content to an eRoom location. When the request is completed, the file is checked
out of the docbase and locked, and a copy is placed in the designated eRoom location.
•
Source file name: CheckoutToEroomWFM.java
•
Class name: CheckoutToEroomWFM.class
Check a file into Content Server from an eRoom
Called when CheckInFromERoom method is invoked, this class automates the checkin of
Docbase content from a file that is stored in eRoom. When the request is completed, the
file is checked in and a reference to the file is returned.
•
Source file name: CheckinToEroomWFM.java
•
Class name: CheckinToEroomWFM.class
6 | eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide
Troubleshooting
Create an eRoom
Called when the ERCreateERoom Workflow method is invoked, this class creates an eRoom.
When the request is completed, the newly-created eRoom is added to the package, and the
content object used to define the parameters for the eRoom creation is removed.
•
Source file name: CreateERoomWFM.java
•
Class name: CreateERoomWFM.class
Create a database row
Called when the ERCreateDBRow Workflow method is invoked, this class creates an eRoom
database row. When the request is completed, the newly-created database row is added to
the package, and the content object used to define the parameters for the database row
creation is removed.
•
Source file name: CreateDBRowWFM.java
•
Class name: CreateDBRowWFM.class
Create a folder
Called when the ERCreateFolder Workflow method is invoked, this class creates an eRoom
folder. When the request is completed, the newly-created folder is added to the package,
and the content object used to define the parameters for the folder creation is removed.
•
Source file name: CreateFolderWFM.java
•
Class name: CreateFolderWFM.class
Create a content link in an eRoom
Called when the CreateLink Workflow method is invoked, this class creates a content link in
a designated eRoom container. When the request is completed, the newly-created content
link is made available to subsequent workflow activities.
•
Source file name: CreateLinkWFM.java
•
Class name: CreateLinkWFM.class
Troubleshooting
This section contains a brief list of things to double-check if you are having trouble with
eDK applications.
eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide | 7
Troubleshooting
`
•
Make sure the DocApp is installed correctly. To determine this, review install log to
make sure the install completed successfully.
•
Make sure the NPD sample application is installed and validated. To do this, go to DAB
(Documentum Application Builder) and open the DocApp named “eDK for Workflows.”
You should see the eDK Workflow methods (for example, ERCreateRoom). Double click
on the NPD sample application; this launches WFM (Workflow Manager). The WFM must
be validated and installed if it has not been already.
•
Make sure your modified Java source files compile into Java classes.
•
Make sure the NPD sample application runs. If the NPD sample application runs, it validates the environment.
•
View the Content Server log in the Documentum Server Manager for a clue to the problem. See Content Server Administrator’s Guide.
Note: We have set the trace_launch property to true on the Workflow methods, so messages get written into the Content Server log. The source Java files contain print statements
that are written to the Content Server log, so you can use these for debugging purposes, if
necessary.
8 | eRoom Enterprise 7.2 eDK for Workflow Toolkit Guide
© 2011 - 2013 EMC Corporation. All Rights Reserved.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change
without
notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO
REPRESENTATIONS OR
WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND
SPECIFICALLY
DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
EMC2, EMC, and the EMC logo are registered trademarks or trademarks of EMC Corporation in the United State and other
countries.
All other trademarks used herein are the property of their respective owners.