EMC Documentum Process Builder Version 6 Installation Guide P/N 300 005 224 EMC Corporation Corporate Headquarters: Hopkinton, MA 01748-9103 1-508-435-1000 www.emc.com
Copyright 2004-2007 EMC Corporation. All rights reserved. Published August 2007 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. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used herein are the property of their respective owners.
Table of Contents Preface... 5 Chapter 1 Preparing for Installation... 7 Supporting software requirements... 7 Content Server and Documentum repositories... 7 Documentum Process Engine... 8 Documentum Foundation Classes (installed with Process Builder)... 8 Connection brokers and the dfc.properties file... 8 Java Runtime Engine (installed with Process Builder)... 9 Documentum Application Installer... 9 Chapter 2 Installing the Forms Builder and Process Builder DocApps... 11 Installing the Forms Builder DocApp... 11 Installing the Process Builder DocApp... 12 Chapter 3 Installing Process Builder... 15 Chapter 4 Post-Installation Tasks... 19 Giving users access to Process Builder... 19 Giving users access to Forms Builder... 20 Configuring the Workflow Publish Events job... 20 Configuring custom email templates... 20 Chapter 5 Uninstalling Process Builder... 23 EMC Documentum Process Builder Version 6 Installation Guide 3
Table of Contents 4 EMC Documentum Process Builder Version 6 Installation Guide
Preface Purpose of this guide This book contains instructions for installing Documentum Process Builder, a software application for creating business process templates. Process templates formalize the steps required to complete a business process, such as an approval process or an insurance claims process, automate the flow of work between the steps, and enable users to repeatedly perform the process. Process Builder extends the functionality of Documentum Workflow Manager. While you can use either tool to create process templates, Process Builder offers enhanced options. For information about using Process Builder, see the Documentum Process Builder Development Guide. Intended audience This book is intended for administrators who are installing Process Builder. The installation process requires installing Documentum DocApps and copying files onto the Content Server machine, so the user must have EMC Documentum superuser or administrator privileges. Once a EMC Documentum repository has been configured, any number of people can install Process Builder on their computers. Revision history This section contains a description of this document s revision history. Revision Date Description August 2007 Release 6.0 Support information EMC Documentums technical support services and policies are available at the EMC Powerlink website (http://powerlink.emc.com). To download the Customer Guide to EMC Software Support Services from Powerlink, select Support > About EMC Customer Service > Software Customer Guide. To order printed documentation or access support information in Powerlink, select Support > About EMC Customer Service > Software Support Offerings. EMC Documentum Process Builder Version 6 Installation Guide 5
Preface Note: You must register online at Powerlink before using it. Related documentation This manual forms part of a documentation suite designed to support those who install, configure, and use Process Builder. In addition to this manual, the documentation set for Process Builder includes: Process Builder Development Guide Process Builder User Guide Process Builder Release Notes Process Builder Localization Guide You can go to the Documentation area of the EMC Powerlink website (http://powerlink.emc.com) to download product documentation. To locate product documentation, select Support > Documentation and White Papers Library, and then select your product. 6 EMC Documentum Process Builder Version 6 Installation Guide
Preparing for Installation Chapter 1 Process Builder is a client application that can be installed on any computer. Each user who needs to create or modify process templates can install the application on his or her local machine. To work properly, Process Builder requires certain files and objects in any EMC Documentum repository to which it connects. Therefore, in addition to installing the Process Builder application on users machines, you must load a Documentum DocApp into each EMC Documentum repository and copy files to each Content Server host machine. Supporting software requirements Process Builder depends on additional supporting software, which must be installed in order for the application to work properly. Note: If you install Process Builder on a computer that has other EMC Documentum products installed on it, most of the required supporting software will be in place. For information on the supported versions, see the Documentum Process Builder Release Notes. Content Server and Documentum repositories Before you install Process Builder, install at least one Content Server and configure at least one EMC Documentum repository. Content Server provides content management services, including check in and check out, versioning, and archiving. All processes and activities created with Process Builder are saved in a EMC Documentum repository. Process Builder and Content Server need not be (and typically are not) on the same host machine. For complete information on installing Content Server, refer to the Documentum Content Server Installation Guide. EMC Documentum Process Builder Version 6 Installation Guide 7
Preparing for Installation Documentum Process Engine Documentum Process Engine consists of the system components involved in running automated business processes. While Content Server includes basic workflow functionality, the Process Engine enables the additional automation features necessary to implement production-ready mission-critical business processes, such as work queue processing, XML data handling, activity timer/deadline management, and audit trail data aggregation for reporting. The software that comprises the Process Engine is installed as part of Content Server. The license key that activates the Process Engine is installed and configured automatically upon installation of the BPM DocApp. Documentum Foundation Classes (installed with Process Builder) Installing Process Builder also installs Documentum Foundation Classes (DFC) on the computer. DFC is an object-oriented application programming interface (API) and framework for accessing, customizing, and extending EMC Documentum functionality, implemented as a set of Java interfaces and implementation classes. For more information on DFC, refer to the Documentum Foundation Classes Development Guide and Documentum Foundation Classes Installation Guide. Connection brokers and the dfc.properties le Connection brokers provide EMC Documentum repository connection information to client applications. EMC Documentum repositories project their connection information to particular connection brokers, and client applications look to a specified connection broker for the available Documentum repositories. Before you install Process Builder, obtain the names of the connection brokers to which the appropriate repositories project and the port numbers on which the connection brokers listen. The name of the connection broker is recorded on the client computer in the dfc.properties file, installed as part of DFC. All Documentum applications installed on a Windows machine share the same dfc.properties file. On all supported Windows operating systems, this file is located in C:\Documentum\config. If a dfc.properties file does not already exist on the machine where you install Process Builder, the installer asks for the name of the connection broker and the port number on which it listens and then creates the dfc.properties file. The default connection broker port is 1489. 8 EMC Documentum Process Builder Version 6 Installation Guide
Preparing for Installation If you need to change the connection broker information after installation, edit the dfc.properties file on the machine where Process Builder is installed. For more information on the dfc.properties file and connection brokers, refer to the Documentum Content Server Administration Guide. Java Runtime Engine (installed with Process Builder) Process Builder is a Java-based application and requires a Java Runtime Engine (JRE) on the computer. The installation program installs the required JRE along with the application. Documentum Application Installer Installing Process Builder also requires installing DocApps in each EMC Documentum repository in which you will use the application. Documentum Application Installer is required for installing DocApps. Documentum Application Installer is part of Documentum Application Builder; if you install Documentum Application Builder, Documentum Application Installer is included, but you can also install it separately. To install a DocApp with Documentum Application Installer, you must log in to the EMC Documentum repository as a user with superuser or administration privileges. EMC Documentum Process Builder Version 6 Installation Guide 9
Preparing for Installation 10 EMC Documentum Process Builder Version 6 Installation Guide
Installing the Forms Builder and Process Builder DocApps Chapter 2 Installing the Forms DocApp and BPM DocApp automatically enables and configures all of the jobs and properties necessary to use Process Builder, Forms Builder, and the work queue functionality available in Webtop and TaskSpace. Both DocApps can be located on EMC s Powerlink website. Installing the Forms Builder DocApp To work properly, Forms Builder requires certain files and objects in any EMC Documentum repository to which it connects. You install these files and objects using a Documentum DocApp, which is an archived collection of Content Server objects. The files and objects required by Documentum Forms are located in the Forms Builder DocApp. Install the DocApp once in each EMC Documentum repository in which any user will run Forms Builder. Install the DocApp from any machine with the latest version of Documentum Application Installer on the local machine. (Documentum Forms Builder Release Notes contains specific version requirements.) If Documentum Application Installer is not installed on the local machine, download and install it before running the procedure below. You must be a superuser or EMC Documentum administrator to install a DocApp using Documentum Application Installer (DAI). To install the Forms Builder DocApp: 1. Download the Forms Builder DocApp from the following location: http://powerlink.emc.com Note: The Powerlink website provides access to https://emc. subscribenet.com/ control/dctm/index where a complete listing of products is available for download. EMC Documentum Process Builder Version 6 Installation Guide 11
Installing the Forms Builder and Process Builder DocApps 2. Unzip the downloaded file Forms_Builder_<version>_DocApp.zip. The files comprising the DocApp are extracted into a subdirectory named Forms. 3. From the Start menu, select Programs > Documentum > Application Installer. The login screen for Documentum Application Installer appears. 4. Select the EMC Documentum repository into which you want to install the DocApp and log in as a superuser or administrator. Documentum Application Installer starts. 5. Click Browse from the DocApp folder selection section and navigate to the Forms directory containing the DocApp files (from step 2 above). 6. In the Installer Log section, type a log filename in the File name box; this step is optional. The default log filename is AppInstallerLog.html. Click Browse to select a directory other than the default to save the log file. You can refer to the log file for any errors that occur during the installation of DocApp. 7. Click OK. A dialog box appears, detailing the DocApp name, target repository, and the installation status. 8. Click Start Installation. The installation process takes a few minutes to complete. This is indicated in the dialog box that appears. 9. Click OK. If users are currently connected to the EMC Documentum repository into which you are installing the DocApp, a dialog box asks whether you want to continue with the installation. Click Yes. Users are not affected by the installation, but they will not see the changes made by the DocApp until they reconnect. 10. Repeat steps 3 through 9 for each EMC Documentum repository in which you plan to use Forms Builder. 11. Click Quit Installer. Installing the Process Builder DocApp To work properly, Process Builder requires certain files and objects in any EMC Documentum repository to which it connects. You install these files and objects using a Documentum DocApp, which is an archived collection of Content Server objects. You must install the Process Builder DocApp before using Process Builder. Install the DocApp once in each EMC Documentum repository in which any user will run Process Builder. 12 EMC Documentum Process Builder Version 6 Installation Guide
Installing the Forms Builder and Process Builder DocApps You can install the DocApp from any machine that has the latest version of Documentum Application Installer on the local machine. (Refer to the Process Builder Release Notes for specific version requirements.) If Documentum Application Installer is not installed on the local machine, download and install it before running the procedure below. Note: For DB2 repositories, you must use the DB2 Control Center to create a user temporary tablespace before installing the BPM DocApp. See the DB2 user documentation for instructions on using the DB2 Control Center. You must be a superuser or EMC Documentum administrator to install a DocApp using Documentum Application Installer. The BPM DocApp installs the following jobs: dm_qmpriorityaging Increments priority of work queue tasks dm_qmprioritynotification Checks the highest priority of work queue tasks against the maximum priority dm_wfreporting Processes workflow audit trails and generates dmc_completed_workflow and dmc_completed_workitem objects dm_qmthresholdnotification Checks the number of work queue tasks against the threshold dm_wfsuspendtimer Resumes activities after the suspension interval expires dm_wfcheckpoint Monitors dm_wfpublishevents job as a heartbeat job dm_wfpublishevents Exports BPM process data to the BAM database Note: All jobs in this list are installed and configured by the DocApp, with the exception of the dm_wfpublishevents job, which must be configured manually. Configuring the Workflow Publish Events job, page 20 provides instructions on configuring this job to enable BAM reporting. To install the Process Builder DocApp: 1. Download the Documentum Process Builder DocApp, Version 6.0 (zip) from the Process Engine product download area on the customer download site: http://powerlink.emc.com Note: The Powerlink site (http://powerlink.emc.com) provides access to https://emc. subscribenet.com/control/dctm/index where a complete listing of products is available for download. 2. Unzip the downloaded file BPM_DocApp_<version>.zip. The files comprising the DocApp are extracted into a subdirectory named BPM. 3. From the Microsoft Windows Start menu, select Programs > Documentum > Application Installer. The login screen for Documentum Application Installer appears. EMC Documentum Process Builder Version 6 Installation Guide 13
Installing the Forms Builder and Process Builder DocApps Note: Documentum Application Installer is not installed as part of Process Builder. You must download and install it separately. 4. Select the EMC Documentum repository into which to install the DocApp and log in as a superuser or administrator. Documentum Application Installer starts. 5. Click Browse from the DocApp folder selection section and navigate to the BPM-Forms directory containing the DocApp files (from step 2 above). 6. In the Installer Log section, type a log file name in the File name box. The default log file name is AppInstallerLog.html. Click Browse to select a directory other than the default to save the log file. You can refer to the log file for any errors that occur during the installation of DocApp. 7. Click OK. A dialog box appears, detailing the DocApp name, Target Repository, and the installation status. 8. Click Start Installation. A dialog box appears stating This will take a few minutes to complete. 9. Click OK. If users are currently connected to the EMC Documentum repository into which you are installing the DocApp, a dialog box asks whether you want to continue with the installation. Click Yes. Users are not affected by the installation, but they will not see the changes made by the DocApp until they reconnect. 10. Click Quit Installer. 11. Repeat steps 2 through 9 for each EMC Documentum repository in which you plan to use Process Builder. 14 EMC Documentum Process Builder Version 6 Installation Guide
Chapter 3 Installing Process Builder If your system meets the requirements listed in Documentum Process Builder Release Notes, and you have installed the supporting software described in Chapters 1 and 2, you are ready to install Process Builder. You install the Process Builder application on the local machine of each user who will be creating or modifying process templates. The installation program also installs a Java Runtime Engine (JRE), Documentum Forms Builder, and Documentum Foundation Classes (DFC), which Process Builder uses to communicate with Content Server. If the machine has no other EMC Documentum software installed on it, the installation program asks you to chose a home directory for EMC Documentum software and to identify a connection broker that will enable the machine to locate Content Server hosts. To install Process Builder: 1. Download the Process Builder software. You should have received instructions through email regarding how to download products from EMC Documentum s download site. The URL below takes you to the download site. Download Site: http://powerlink.emc.com Note: The Powerlink site (http://powerlink.emc.com) provides access to https://emc. subscribenet.com/control/dctm/index where a complete listing of products is available for download. 2. Run the downloaded executable file to expand the compressed archive. 3. Run the installation program from the directory you expanded the files into. For a Microsoft Windows host machine, the installation program is bpmwinsetup.exe. A welcome screen appears, listing the software that will be installed. Process Builder installs Documentum Foundation Classes (DFC), Documentum Forms Builder, and Documentum Forms Services as supporting software. 4. Read the welcome screen, then click Next. EMC Documentum Process Builder Version 6 Installation Guide 15
Installing Process Builder The EMC Documentum software license agreement appears. 5. Read the license agreement. 6. To continue with installation, click I accept the terms of the license agreement and click Next. If you do not accept the license agreement terms, the Next button is grayed out. You cannot continue with the installation. The next screen gives you the option to install the developer documentation and a primary interop assembly for Documentum Foundation Classes (DFC). 7. To install the DFC developer documentation, click the Developer Documentation check box. 8. To request installation of a Microsoft installer package (.msi file) for the DFC primary interop assembly, click the Primary Interop Assembly Installer check box. If you select this option, the Process Builder installation program places the installation package for the DFC primary interop assembly into the setup directory of the DFC program root directory. 9. Click Next. 10. Select the language pack to install for this release and click Next. 11. If the machine doesn t already have the global registry configured, designate the global registry for this installation. a. Enter the name of the repository. b. Enter the login name and password for the repository. c. You can also select the checkbox to test the connection. 12. If the machine has no other EMC Documentum software installed on it, enter basic configuration information for DFC. If the machine already has DFC installed on it, the installation program uses the existing values and does not display a screen asking for configuration information. a. Accept the default DFC program root directory (C:\Program Files\Documentum) or enter a different directory and click Next. b. Accept the default user directory (C:\Documentum) or enter a different directory and click Next. 13. If you are prompted, enter a connection broker host name and port number or accept the default and click Next. 14. Click Next. The installation program starts copying files to the appropriate locations. It also creates a shortcut on the Windows Start menu for starting Process Builder. When the installation is complete, a message screen appears indicating success. 16 EMC Documentum Process Builder Version 6 Installation Guide
Installing Process Builder 15. Click Next, then click Finish. The installation program displays a reminder that you must perform additional installation steps to prepare a EMC Documentum repository for use with Process Builder. See the next two sections for details about these steps. Note: After installing Process Builder, you must install Process Integrator messaging services on the Content Server. This ensures Process Integrator sends out SMTP notifications correctly. Refer to the Documentum Process Integrator Installation Guide for more information about installing messaging services. EMC Documentum Process Builder Version 6 Installation Guide 17
Installing Process Builder 18 EMC Documentum Process Builder Version 6 Installation Guide
Chapter 4 Post-Installation Tasks This chapter describes configuration tasks that you may need to perform after installing Process Builder. The tasks are: Giving users access to Process Builder, page 19 Giving users access to Forms Builder, page 20 Configuring the Workflow Publish Events job, page 20 Configuring custom email templates, page 20 You need to perform these tasks for each EMC Documentum repository in which you plan to use Process Builder. Giving users access to Process Builder When a user starts Process Builder, the first step is to log in to a EMC Documentum repository. To use Process Builder, the user must be a member of the role bpmuser in that repository. You add users to the bpmuser role using Documentum Administrator. To add users to the bpmuser role: 1. Start Documentum Administrator and log in as a user with administrator privileges. 2. Navigate to Administration > User Management > Roles to access the Roles list page. 3. Click the name of the bpmuser role. The list page with members of the role is displayed. 4. To filter the list, select Only Groups, Only Users, or Only Roles from the list. 5. Click File > Add Member(s) to access the Choose a user/group page. 6. Select the names of the users to add to the role. 7. Click the right arrow. EMC Documentum Process Builder Version 6 Installation Guide 19
Post-Installation Tasks The members are moved to the right-hand side of the page. 8. Click OK. Giving users access to Forms Builder To give users access to Forms Builder, see the Documentum Forms Builder Installation Guide. Con guring the Work ow Publish Events job To publish data to the BAM reporting database, you must configure the dm_wfpublishevents job with the connection parameters for the target database. This job publishes data from the Process Builder audit trail to the BAM database where it can be used to create BAM reports. To modify a job: 1. Connect to the repository and navigate to Administration > Job Management > Jobs. The system displays the Jobs list page. 2. Select the job to modify and then select View > Properties > Info. The system displays the Job Properties - Info page. 3. Modify fields on the Job Properties - Info page. 4. Click the tabs to access other pages where you want to change information. 5. Click OK or Cancel to return to the Jobs list page. Con guring custom email templates Process Builder enables you to create custom email notification methods. To use this feature, Content Server must invoke the dm_event_template_sender method to send event notifications using templates. The method is a Java method and is executed by an application server. The application server must reside on the same host as Content Server. You can use the WebLogic server installed with Content Server or an application server that you have installed. Note: When Content Server is configured to use the dm_event_template_sender method, it uses this method rather than the default dm_event_sender method for all email. However, dm_event_template_sender ends up invoking dm_event_sender for all events 20 EMC Documentum Process Builder Version 6 Installation Guide
Post-Installation Tasks that do not have associated email templates. Therefore, any customization you have made to the dm_event_sender method still apply. To enable the use of custom email templates: 1. Start the Java Method Server on the Content Server host machine. On a Windows host machine, start the Documentum Java Method Server service. The service is set to start automatically by default. On a UNIX host machine, run the shell script startmethodserver.sh script located in the $DOCUMENTUM/bea9.2/domains/DctmDomain directory. The Java Method Server is not started by default. 2. Configure Content Server to invoke the dm_event_template_sender method for email messages. Set the mail_method attribute in the server config object (dm_server_config) by following the steps below. By default, the attribute is set to dm_event_sender. To use the email templates for workflow events, you reset the attribute to dm_event_template_sender. a. Connect to the EMC Documentum repository and start an API session. b. Use the Fetch or Checkout method to obtain the server config object from the EMC Documentum repository. fetch,c,server_config_object_id checkout,c,server_config_object_id If you do not know the object ID of the server config object, you can use the Retrieve method to obtain it: retrieve,c,dm_server_config where object_name = server_config_name server_config_name is typically the name of the EMC Documentum repository. c. Use the Set method to update the value of the mail_method attribute. You can use the keyword serverconfig to represent the server config object in the Set syntax: API>set,c,server_config_object_id,mail_method SET>dm_event_template_sender d. To turn on tracing for the dm_event_template_sender method, set trace_level in the method_args attribute. The only supported trace levels are: 0, no tracing 1, informational messages 2, debug messages By default, the tracing information is recorded in the following location. For Windows, look in %DM_HOME%\bea9. 2\domains\DctmDomain\servers\DctmServer_MethodServer_ EMC Documentum Process Builder Version 6 Installation Guide 21
Post-Installation Tasks <hostname>\logs\dctmserver_methodserver_<hostname>. log. For UNIX, check $DOCUMENTUM_SHARED\bea9. 2\domains\DctmDomain\servers\DctmServer_MethodServer_ <hostname>\logs\dctmserver_methodserver_<hostname>.log To change the default, set trace_file in the method_args attribute to the location of your choice. e. On UNIX hosts, set the SMTP server to use for sending email. When the dm_event_template_sender method is invoked on a UNIX host, it uses the SMTP server installed as part of the operating system by default. To use a different SMTP server, set the smtp_server attribute in the server config object to the name of the desired server. On Windows hosts, the smtp_server attribute is set by the user during Documentum repository configuration. f. Use the Save or Checkin method to save your changes. save,c,server_config_object_id checkin,c,server_config_object_id You cannot use the serverconfig keyword in these methods. 22 EMC Documentum Process Builder Version 6 Installation Guide
Chapter 5 Uninstalling Process Builder Process Builder is installed as a standard Microsoft Windows application. If you need to remove the application from a computer, use the Add/Remove Programs option from the Windows Control Panel. Note: The procedure below removes the Process Builder application from a local machine. It does not uninstall the supporting objects from any EMC Documentum repositories to which you applied the Process Builder and Forms Builder DocApps or the Java files copied onto Content Server machines. To uninstall Process Builder: 1. Close Process Builder if it is running. 2. From the Microsoft Windows Start menu, select Settings > Control Panel. The Control Panel appears. 3. Double-click Add/Remove Programs. 4. Select Documentum Process Builder from the list of currently installed programs, and click the Change/Remove button. The uninstallation program starts. A screen appears showing a list of the software to be uninstalled. 5. Click Next > to continue. A screen appears showing the file system location where the uninstallation program found the Process Builder software. 6. Click Next > to remove the application. 7. When the process is complete, click Finish to close the uninstallation program. 8. Close the Control Panel. Note: You must not uninstall Documentum Foundation Classes (DFC) after removing the Process Builder application. EMC Documentum Process Builder Version 6 Installation Guide 23