emc documentum reporting services - data storage ... · pdf fileemc documentum reporting...

EMC Documentum Reporting Services

A Detailed Review

Abstract

This white paper provides an overview of EMC® Documentum® Reporting Services, establishing a basis for a functional understanding of the product. This information includes the primary architecture, installation, troubleshooting, and usage of the product.

September 2010

EMC Documentum Reporting Services A Detailed Review 2

Copyright © 2010 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.

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.

Part Number h8051


Table of Contents

Executive summary ............................................................................................ 4

Introduction ......................................................................................................... 4

Audience ...................................................................................................................................... 4

DRS architecture ................................................................................................. 5

Setting up Documentum Reporting Services ................................................... 7

Deploying DRS on a WDK web application ................................................................................. 7

Deploying a DRS web application ............................................................................................ 7 Integrating Webtop or a WDK application ................................................................................ 8

Deploying DRS on a Java Method Server environment .............................................................. 8

Setting up or upgrading Crystal Reports Designer for designing reports .................................... 9

Consuming Documentum Reporting Services ............................................... 10

Managing reports manually using a WDK application ............................................................... 12

Creating a report in the repository .......................................................................................... 12 Running a report in the repository .......................................................................................... 13 Editing a report in the repository ............................................................................................ 13 Importing a report into the repository ..................................................................................... 13 Deleting a report from the repository ...................................................................................... 14

Running reports periodically using DRS .................................................................................... 14

Creating a job ......................................................................................................................... 14 Locating a method for a job .................................................................................................... 16 Changing a job schedule ........................................................................................................ 19 Running a job ......................................................................................................................... 20 Viewing a job report ................................................................................................................ 20 Setting the trace level for a job ............................................................................................... 21

Improving report performance......................................................................... 21

Optimizing the report query ........................................................................................................ 21

Using report parameters and filters ........................................................................................... 21

Using predicates ........................................................................................................................ 22

Troubleshooting ................................................................................................ 23

‘Database logon failed’ error occurs when a report is run on Webtop ....................................... 23

Deployment of DRS on WAS fails ............................................................................................. 23

‘Failed to open the connection. JDBC driver not found’ error occurs in Crystal Reports Designer ........................................................................................................... 24

‘Failed to open the connection’ error occurs in Crystal Reports Designer ............................. 24 ‘No suitable driver’ error occurs in Crystal Reports Designer ................................................ 25 ‘No DocBrokers are configured’ error occurs in the Crystal Reports Designer ...................... 26 ‘Failed to process the report’ error might occur when DRS is deployed in a UNIX-based environment ............................................................................................................................ 26 An error occurs when scheduling a DRS job ......................................................................... 26 ‘Error’ occurs when running a DRS report ............................................................................. 27 ‘Access Violation’ error occurs in the RSA single sign-on environment................................. 27

Conclusion ........................................................................................................ 28

Benefits of using Documentum Reporting Services .................................................................. 28

References ........................................................................................................ 28


Executive summary EMC® Documentum® Reporting Services (DRS) is a reporting solution for Documentum objects that helps users access Documentum metadata through the Documentum JDBC (DJDBC) interface. Using DRS, administrators and business users can create, view, run, and edit out-of-the-box (OOTB) reports in the repository and import existing reports into the repository.

Documentum JDBC is an interface that allows you to access a Documentum repository from JDBC API supported client applications. Documentum JDBC enables you to connect to a Documentum repository to perform DQL queries or access the repository or metadata of the repository. The Documentum JDBC driver provides support for most standard JDBC APIs.

You can integrate DRS with Documentum Webtop, Documentum Administrator (DA), DAMtop, or any Web Development Kit (WDK) web application for running or managing the reports. The WDK custom component invokes the DRS web application. In the DRS web application, Crystal runtime engine APIs use the DJDBC driver to run reports.

DRS can also be integrated with Documentum Java Method Server (JMS). Using Documentum JMS, you can configure jobs to periodically run DRS reports and save the output in various formats in the repository.

Introduction This white paper provides an overview of Documentum Reporting Services and helps the reader develop a deeper functional understanding of the product. This white paper includes the following sections:

“DRS architecture” on page 5 “Setting up Documentum Reporting Services” on page 7 “Consuming Documentum Reporting Services” on page 10 “Improving report performance” on page 21 “Troubleshooting” on page 23

Audience This white paper is intended for corporate management, developers, consultants, quality engineers, business analysts, technical support executives, and business users.


DRS architecture The following figures depict the high-level architecture of DRS.

Figure 1. DRS on a WDK web application environment


Figure 2. DRS on a Documentum Java Method Server environment

Documentum Reporting Services comprises the following components:

DRS Web component DRS Scheduler DRS Design-time

DRS Web component The DRS Web component comprises the following:

DRS WDK Integration component DRS Web application DRS Crystal Reports (CR) handler Crystal Java Reporting Component (JRC) Documentum JDBC for data access Documentum Foundation Classes (DFC)

When you run a report through the browser using a WDK application, the application sends the request to the DRS WDK Integration component. The DRS WDK Integration component invokes the DRS Web application, which then runs the selected report and renders the report using the Crystal JRC, DJDBC, and DFC components.

DRS Scheduler component The DRS Scheduler component comprises the following:


DRS Java Method implementation class, Java classes and properties file Crystal JRC Documentum JDBC for data access

Agent Exec selects DRS jobs and runs as per the job schedule. The Agent Exec invokes the DRS method to run on the Java Method Server. The DRS method uses JRC, DJDBC, and DFC to run a report and save the report output in the repository.

DRS Design-time component The DRS Design-time component comprises the following:

Crystal Designer Documentum JDBC for data access DFC

You can design reports on the docbase data using Crystal Reports (CR) Designer. The Crystal Reports Designer uses DJDBC and DFC to fetch the docbase metadata for designing reports and executing SQL for running reports.

Setting up Documentum Reporting Services This section describes the requirements you need to fulfill before installing or upgrading Documentum Reporting Services on a host computer. This section also provides information that will assist you in planning a Documentum Reporting Services installation. You can set up DRS on:

A WDK web application Documentum Java Method Server for scheduling DRS reports Crystal Reports Designer for designing new reports or editing existing reports

Deploying DRS on a WDK web application You can deploy DRS on Webtop or any WDK web application. To deploy DRS on a WDK application:

Deploy the DRS web application. Integrate the WDK application with DRS. Set up DRS on Content Server. Install the DRS DAR file on the repository where reporting

functionality is required. Set up Crystal Reports Designer on the client machine for creating/editing the reports using a WDK

web application.

Deploying a DRS web application

To deploy a DRS WAR file, perform the following steps:

1. Unzip the DRS WAR file.

2. Edit the <DRS_WAR_UNPACK_DIR>/WEB-INF/classes/dfc.properties file to point the DRS application to the correct docbase, where the DRS DAR files have been installed.

3. Repackage the DRS WAR file.

4. Deploy the DRS WAR file.


Integrating Webtop or a WDK application

This section describes how to integrate Webtop or any WDK application with DRS. To integrate Webtop or any WDK application with DRS:

1. Unzip the DRS zip file into a <DRS_UNZIP_DIR> directory on your machine.

2. Back up the following files and directories (required):

<product_name_INSTALL_DIR>/WEB-INF <product_name_INSTALL_DIR>/help <product_name_INSTALL_DIR>/custom

Note: product_name represents Webtop, TaskSpace, Documentum Administrator, or a WDK-based Documentum client application.

3. To revert to the <product_name> deployment that existed before you deployed DRS, copy the files and directories that you backed up in step 2 to the same location.

4. Copy all the files and directories from <DRS_UNZIP_DIR>/WEB-INF to the <product_name>/WEB-INF directory or to the WAR file located in the same directory structure. In the Confirm Folder/File

Replace window, click Yes.

Note: If the DRS webapp context root specified during the deployment of the drs_cr.war file is not drs_cr, replace the drs_webapp value in <product_name_ROOT_DIR>/WEB-INF/classes/drs.properties with the appropriate value.

5. Perform the following:

Copy the <DRS_UNZIP_DIR>/custom/reports directory into <product_name_ROOT_DIR>/custom or to the WAR file in the same directory structure.

Copy the <DRS_UNZIP_DIR>/custom/config/report_view_action.xml file to the <Product_Name_ROOT_DIR>/custom/config/ directory.

Copy the <DRS_UNZIP_DIR>/custom/config/report_view_component.xml file to the <Product_Name_ROOT_DIR>/custom/config/ directory. In the Confirm Folder

Replace window, click Yes.

6. If DRS is being deployed on Webtop, copy <DRS_UNZIP_DIR>/custom/config/help_component.xml to <Webtop_ROOT_DIR>/custom/config/, and copy all files from the <DRS_UNZIP_DIR>/help/en/Webtop directory to the <Webtop_ROOT_DIR>/help/en

directory. In the Confirm Folder/File Replace window, click Yes.

Note: If you have customized your help component, redo the customizing.

In a UNIX-based environment for any application server, set the Java Virtual Machine parameter -Djava.awt.headless=true in the start-up script of the application server. See the “Troubleshooting” section for more information.

With version DRS 6.5 SP3 onward, the report connection is automatically pointed to the current docbase when you run a report through the browser. You need not edit the reports to change the connection details.

Deploying DRS on a Java Method Server environment This section describes how to deploy DRS on a Java Method Server environment. To deploy DRS on Java Method Server, perform the following:


1. Unjar the drs_cr.war file into a temporary folder.

2. Stop the JBoss server.

3. Back up the directory DOCUMENTUM_HOME_DIR\jboss\server\ DctmServer_MethodServer\deploy\ServerApps.ear\DmMethods.war\WEB-

INF\lib to revert to the previous DRS deployment. This step is required.

4. Copy all jar files, other than log4j.jar, dfc.jar, aspectjrt.jar, certjFIPS.jar, and jsafeFIPS.jar, from the <DRS_CR_WAR_UNZIP_DIR>/WEB-INF/lib directory to the DOCUMENTUM_HOME_DIR\jboss\server\DctmServer_MethodServer\deploy\Serv

erApps.ear\DmMethods.war\WEB-INF\lib directory. Click No when you are prompted to overwrite files.

5. Copy the <DRS_CR_WAR_UNZIP_DIR>/crystalreportviewers directory to the DOCUMENTUM_HOME_DIR\jboss\server\DctmServer_MethodServer\deploy\Serv

erApps.ear\DmMethods.war\WEB-INF directory.

6. Copy drs.properties and dmjdbc.properties files from the <DRS_CR_WAR_UNZIP_DIR >/WEB-INF/classes directory to the DOCUMENTUM_HOME_DIR\jboss\server\DctmServer_MethodServer\deploy\Serv

erApps.ear\DmMethods.war\WEB-INF\classes directory.

7. Clear the JBoss cache, and restart the server.

8. Install the DRS DAR file on the repository where reporting functionality is required to set up DRS on Content Server.

9. Install Documentum Administrator.

Setting up or upgrading Crystal Reports Designer for designing reports This section describes how to set up or upgrade Crystal Reports Designer for designing reports. To deploy DRS on Java Method Server, perform the following:

1. Install or upgrade to Crystal Reports Designer on your local machine to design a new report or edit an existing report.

2. Install or upgrade to Sun JDK 1.5.

3. Install or upgrade the DFC.

4. Edit <BUSINESSOBJECTS_INSTALL_DIR>\common\3.5\java\CRConfig.xml as follows:

Point JavaDir to the java 1.5 bin folder. Specify the Documentum dctm.jar file as the first entry in the classpath tag.

For example, if the Documentum directory is placed in C:/Program Files, specify C:\Program Files\Documentum\dctm.jar as the first entry in the <Classpath> tag as follows: <Classpath>C:\Program Files\Documentum\dctm.jar;C:\Program

Files\BusinessObjects\Common\3.5\java/lib/crlovmanifest.jar;C:\Pro

gramFiles\BusinessObjects\Common\3.5\java/lib/CRLOVExternal.jar;……

..;${CLASSPATH}</Classpath>


5. Unjar the drs_cr.war file into a temporary folder.

6. From the <DRS_CR_WAR_UNZIP_DIR>/WEB-INF/lib directory, copy the dmjdbc.jar file to your machine, and specify the location of the jar file along with the filename, in the <Classpath> tag of the CRConfig.xml file.

7. From the <DRS_CR_WAR_UNZIP_DIR>/WEB-INF/Classes folder, copy the dmjdbc.properties file to your machine and specify the location of the dmjdbc.properties file in the <Classpath> tag of CRConfig.xml.

Note: You must not specify the dmjdbc.properties filename in the <Classpath> tag.

Consuming Documentum Reporting Services When you have Documentum Reporting Services installed on your Documentum Webtop, DA, or a WDK-based Documentum client application similar to Webtop, you can create, run, and edit new and existing reports in the repository. When you install Crystal Reports Designer on the client machine you can import reports into the repository. You can also run and edit out-of-the-box (OOTB) reports. Currently, DRS only supports report formats created through Crystal Reports.

You can use DRS to perform the following tasks:

Design reports Manage reports manually using a WDK web application Run reports periodically by using DRS Scheduler on Documentum Java Method Server Design and edit DRS reports using Crystal Reports Designer. To design a report, you must set up the

CR Designer. Set up Crystal Reports Designer for designing reports Create/design reports on docbase objects Create a report on docbase objects

This section describes how to create a simple report using the Crystal Reports Designer.

Using Add Command

You can generate a report by performing DQL queries to get data from multiple tables by using the Add

Command option. You can also use the Add Command option when working with:

Multiple Documentum types in a single report Multiple registered tables in a single report


To use the Add Command option, perform the following steps:

1. Start the Crystal Reports application.

2. Select File > New > Standard Report. Or, click Standard Report from the main page. The Standard Report Creation wizard is displayed.

3. Click Create New Connection.

4. Select JDBC (JNDI) as the data source from the list under Create New Connection. If there is no JDBC/JNDI option under Create New Connection, perform the following:

Under Create New Connection, select the More Data Sources option. Select JDBC (JNDI) under the More Data Sources option.

This installs JDBC/JNDI. You need to either restart your machine or the Crystal Reports application. When you restart the Crystal Reports application, you will see the JDBC (JNDI) data source option under Create New Connection.

5. Type the connection URL, and the driver name for the JDBC connection in the pop-up window. The Connection URL for Documentum JDBC Driver (Reporting) is jdbc:documentum:oca:docbaseext@<REPOSITORY_NAME>

Database ClassName com.documentum.oca.jdbc.jdbc20.ext.DjdbcDriverExt

6. Click Next.

7. Type the Username and Password to connect to the repository. You are now connected to the repository.

Note: Alternatively, you can also enter the URL, driver class, and user ID in the respective elements in the CRconfig.xml file in the Crystal Reports.

8. Expand the JDBC connection node to view the list of Documentum types of the repository.

9. Double-click Add Command. The Add Command to report dialog box opens. It prompts you to write the DQL query.

10. Click Next to view the fields from the DQL string in the fields screen.

11. Select the fields to be displayed in the report.

12. Click Next to go to the grouping screen. The grouping screen enables you to group fields by attributes. Using this, you can group the information in the report.

13. Click Next to go to the Record Selection screen. In the Record Selection screen, you can set the record selection criteria based on the filter fields.

14. Select the filter fields from the available fields that are listed.

15. Click Next to go to the template screen.

16. Select the appropriate template from the list in the template screen.

17. Click Finish to generate the report. You can view the report in the report viewer.


18. Click Save. This saves the report in the .rpt file format in the file system. You must uncheck the File > Save data with report menu and then save the report. You can open the saved report using the Open file option from the File menu.

Registering an external table

To work with external tables, it is important to register these external tables into the repository.

For example, if an external table dm_employee has the following details:

dm_employee (name varchar2(20), empid number, deptid number)

Then use the following command to register an external table in the repository:

register table <TABLE_OWNER_NAME>."`dm_employee"

("name" char(20), "empid" integer, "deptid" integer)

Managing reports manually using a WDK application You can manage DRS reports manually using any WDK application. You can use WDK application to:

Create a report in the repository Run a report in the repository Edit a report in the repository Import a custom report into the repository Export a report from repository into the local machine Delete a report from the repository

Creating a report in the repository

Perform the following steps to create a new report in the repository:

1. Log in to Documentum client applications such as Documentum Administrator, Documentum Webtop, or a WDK-based Documentum client application similar to Webtop.

2. Select File > New > Document.

3. Specify the name of the report.

4. Select drs_report from the Type drop-down list. By default, the Format drop-down list displays Crystal Report and the Template drop-down list displays CrystalReportTemplate.rpt.

5. Click Next. Crystal Reports Designer opens the new report. You can now design your new report.

6. Once you have finished designing your report, save it.

7. Close the Crystal Reports Designer window.

8. Click Next.

9. Click Finish. Now, the new report is checked out from the repository.

10. Select File > Checkin to check the report into the repository.


Running a report in the repository

Perform the following steps to run a report in the repository:

1. Select the report that you want to run.

2. Select File > View (Read Only) or Open (Read Only).

If the selected report depends on parameters to run, you will see a pop-up window that requests your input. In order to view this window, you have to disable the pop-up blocker in your browser. Crystal Reports then executes the report and you can view the report output page.

Once you arrive at the report output page, you can perform the following operations:

You can print the report in the same format that is displayed on the screen. You can export to different file formats. You can export the result output to various formats that

Crystal Reports supports. You can save the file to the disk, zoom, and search functionality with the page navigation tool.

Editing a report in the repository

Perform the following steps to edit a report in the repository:

1. Select the report that you want to edit.

2. Select File > Edit. The report is checked out from the repository when you open a report for editing. Crystal Reports Designer opens the report for editing.

3. Edit the changes that are required in the report.

4. Save the report.

5. Select File > Checkin to check the report into the repository.

Importing a report into the repository

Note: You can export reports from the repository into your local machine by using the export functionality of the WDK application.

Perform the following steps to import a report into the repository:

1. Select the cabinet or folder where you want to import the report.

2. Select File > Import.

3. Click Add Files.

4. Browse and select the report that you want to import.

5. Click Next.

6. Select drs_report from the Type drop-down list.

7. Select Crystal Report from the Format drop-down list.

8. Click Next.


9. Click Finish.

Deleting a report from the repository

Perform the following steps to delete a report from the repository:

1. Select a report that you want to delete.

2. Select File > Delete.

3. Click OK.

Running reports periodically using DRS To run reports periodically using DRS Scheduler on Documentum Java Method Server, perform the following:

Verify that the Documentum Java Method Server is running. Deploy DRS on Java Method Server. Create jobs using Documentum Administrator. Configure DRS jobs to run a single report or multiple reports, or send email notifications. Save report output in various formats in the repository.

Note: When you install a DRS DAR file on a repository, a set of DRS OOTB jobs is created in the repository. You can configure the OOTB jobs to run both DRS OOTB and custom reports.

Creating a job

This section provides information on how to use Documentum Administrator to create a job for report generation. This section contains the following subsections:

Locating a method for a job Passing job arguments

To create a job:

1. Navigate to Administration > Job Management > Jobs. The system displays the Jobs list page.

2. Select File > New > Job. The system displays the New Job - Info page.

3. Specify the following information on the New Job - Info page:

a. Name: Specify the job name.

b. Job Type: Optionally, type the job type. The job type is displayed on the Jobs list page and can be used to sort jobs.

c. Trace Level: Select a trace level. Trace levels range from 0 (no tracing) to 10 (a debugging level of tracing).

d. Designated Server: Select a server to run the job. The drop-down list displays all servers running on the repository.

e. State: Select Active or Inactive to create the job in the active or inactive state.


f. Deactivate on Failure: Select to deactivate the job after the execution fails.

g. Run after Update: Select to run the job immediately after you save it.

h. Save if Invalid: Select to save the job, even if it is invalid.

i. Click Next to access the New Job - Schedule page.

4. Enter information on the New Job - Schedule page:

a. Start Date and Time: Designate a start date and time for the job. The default is the current date and time.

b. Determine how often and at what interval the job runs.

Repeat: Select a unit of time. Frequency: Specify how often you want to invoke the job. For example, if Repeat is set to

weeks and Frequency is set to 1, the job repeats once each week. If Repeat is set to weeks and Frequency is set to 3, the job repeats every three weeks.

c. End Date and Time: Determine an end date and time for the job or indicate the number of invocations after which the job becomes inactive. The default end date is 10 years from the current date and time.

d. Click Next to access the New Job - Method page.

5. Enter information on the New Job - Method page:

a. In the Method Name option, click Select Method. The Choose a method page appears.

In the Choose a method page, select drs_RunReportMethod. See the section “Locating a method for a job” for instructions to locate a method.

Click OK to return to the New Job - Method page.

b. Click Edit to access the Method Arguments page to modify the arguments passed to the method by this job:

Type a new argument in the Enter new value textbox, and then click Add. See the section “Passing job arguments” for more details.

To remove an argument, select the argument, and click Remove. To change the order in which arguments are passed, click the argument and click Move Up or

Move Down. Click OK to save the changes or Cancel to abandon the changes. The system displays the

New Job - Method page.

c. Select Pass standard arguments to pass the standard arguments for the method.

Note: The DRS method will fail if you do not select this field when you try to run the job.

d. Click Next to access the New Job - SysObject Info page.

6. Enter information on the New Job - SysObject Info page:


a. Title: Type the title.

b. Subject: Type the subject.

c. Keywords: Click Edit to access the Keywords page:

Type a new keyword in the Enter new value textbox and click Add. To remove a keyword, select the keyword and click Remove. To change the order in which keywords are listed, select the keyword, and click Move Up or

Move Down. Click OK to save the changes or Cancel to nullify the changes. The system displays the New Job - SysObject Info page.

d. Authors: Click Edit to access the Authors page:

Type a new author in the Enter new value textbox and click Add. To remove an author, select the name and click Remove. To change the order in which authors are listed, select the name and click Move Up or Move

Down. Click OK to save the changes or Cancel to abandon the changes. The system displays the

New Job - SysObject Info page.

e. Owner Name: Click Edit to access the Choose a user page:

Select an owner. Click OK. The system displays the New Job - SysObject Info page.

f. To view more sysobject properties of the job, click See More.

7. Click Finish.

The system saves the job and displays the Jobs list page.

Note: Although you can configure a job to run multiple reports, Documentum recommends configuring a job to run one report only.

Locating a method for a job

On the Choose a method page, select the method that you want the job to execute.

To locate a method for a job:

1. To locate the method by name, type the first few letters in the Starts with textbox, and click Go.

2. To view additional pages of methods, click the forward or back button.

3. To view a different number of methods, select a different number from the Show Items drop-down list.

4. To sort the items, select Show All or Show System Methods from the drop-down list.

5. When you locate the correct method, select it, and click OK.

Passing job arguments This section describes how to specify job parameters and pass an argument in the Methods Argument page.


Specifying job parameters

Report output file format — The format in which the report output file is saved. The report output file can be in any format including pdf, rtf, rpt, doc, xls, or csv:

-report_output_file_format

-roff

Example: Providing a report output file format.

-roff pdf

Report output docbase folder path — The full path of the docbase folder where the report output files are saved. You need to specify the report output docbase folder path in one of the following formats:

-report_output_docbase_path

-rodp

Example: Providing a report output docbase folder path.

-rodp /Reports/output/pdf

Note: The report parameters, -roff and -rodp, can be specified for a job as well as a report. The report parameters specified for a report override the report parameters specified for a job.

Report user name (Optional) — The Username against which the report is run. If you do not specify the report_user_name parameter, then the installation owner user details are used to run the report. You must specify the report user name parameter in the -report_user_name tuser1 format.

Specifying a report parameter name and report parameter value

To specify a report parameter name and report parameter value, follow these guidelines: Use | to replace the spaces in the argument value such as report parameter name, report parameter

value, and so on. Do not include spaces in the argument name.

Passing multiple parameters for a <—reportN_parameter> argument

If a job runs multiple reports, the nth report is designated as report<N>, where N is a unique whole number. When -report is followed by a whole number, it is an argument for a report.

-report<N> REPORT_PATH>/<REPORT_NAME>

Example: In order to run abc.rpt and [n]Largest Documents by Document Name.rpt reports that are in the reports cabinet, specify arguments as follows:

-report0 /Reports/[n]Largest|Documents|by|Document|Name.rpt

-report1 /Reports/abc.rpt

In this example,

-report0 is an argument to specify the first report to be run, and /Reports/[n]Largest|Documents|by|Document|Name.rpt is the argument value that specifies the report name along with the path.

-report1 is an argument to specify the second report to be run, and /Reports/abc.rpt is the argument value that specifies the report name along with the path.

Note: You can pass multiple parameters for the <—reportN_parameter> argument only.

When you pass multiple arguments for the <—reportN_parameter> argument: Use a , (comma) as the separator character for separating different parameters. Use a :: (double colon) as the separator string for providing multiple values for a parameter.


Use an = (equal sign) as the separator character for separating the parameter name and parameter value.

Example: Passing multiple parameters for the <—report0_parameter>.

-report0_parameter workflow | States = Dormant :: Acquired :: Finished

:: Paused :: Dpaused :: Apaused, show|chart = 1

In this example, “workflow states” is the parameter. The space in workflow states is replaced by |. Dormant, Acquired, Finished, Paused, Dpaused, and Apaused are multiple values for the work states parameter, and hence, each of these values is separated from each other by “::”. The workflow states parameter is separated from its values by =. Similarly, show chart is another parameter and its value is 1.

Example: Providing range values for an integer parameter.

5 :: 7 :: 8 :: 13

This means the following range of values are provided for the integer parameter 5 to 7 and 8 to 13.

Example: Providing range values for a date parameter.

Date (2007-6-22) :: Date (2008-1-20)

This indicates that the date ranges from 22-6-2007 to 1-20-2008.

Passing an argument for email notification

To pass an argument for email notification, you should enter an argument in one of the following formats:

-email_notification Email_ID1, Email_ID2

-en Email_ID1, Email_ID2

Example: Passing an argument for email notification.

If you want email notifications to be sent to [email protected] and [email protected], specify an argument in one of the following formats:

-en Thomas_Susan, Jack_Hugo or -email_notification Thomas_Susan, Jack_Hugo

Passing an argument for inbox notification

To pass an argument for inbox notification, specify an argument in one of the following formats:

-inbox_notification Username1, Username2 or -ibn Username1, Username2

Passing an argument for the purge limit

To define the purge limit for the reports saved in the docbase, pass an argument in the purge_limit format:

Example: Passing an argument for purge limit.

-purge_limit 5

This indicates that the purge limit is five. When the sixth report output file for a report template X is generated, the first report output file is deleted from the docbase.

Example: Creating a job for an external crystal report file.

Let us consider a scenario where you want to create a job for [n] Largest Documents by Document

Name.rpt, which is an external Crystal Reports file. You want the job to run periodically with the following parameters:

Report save location: Reports/output/pdf Report output file format: pdf


Save number of outputs: 5 Report user name: tuser1 Document name filter: Design Document Top N records: 25 Show chart: Top

The following procedure describes how to create a job for the [n] Largest Documents by Document

Name.rpt report:

1. Log in to DA.

2. Navigate to the cabinet or folder into which you want to import the report file.

3. Import the report into the Documentum repository as drs_report and in the Crystal Reports format.

4. Create a job. See the section “Creating a job for more details.”

5. Specify the following arguments in the Enter new value textbox of the Method Arguments page while creating a job:

-report_output_file_format pdf

-report_output_docbase_path /Reports/output/pdf

-purge_limit 5

-report_user_name tuser1

-report0 [n]Largest|Documents|by|Document|Name.rpt

-report0_parameter

Document|Name=Design|Document,Top|N|Records=25,Show|Chart=1

6. Click Add.

Changing a job schedule

This section describes how to modify a job schedule. To change a job schedule:

1. Connect to the repository and navigate to Job Management > Jobs. The system displays the Jobs list page.

2. Locate the job whose schedule you want to change.


3. Select the job and then select View > Properties > Info. The system displays the Job Properties - Info page.

4. Click the Schedule tab. The system displays the Job Properties - Schedule page.

5. Assign a start date and time for the job. The default setting is the current date and time.

6. Determine how often and at what interval you want the job to run.

The Repeat drop-down list specifies a unit of time. The Frequency textbox specifies how often the job is invoked. For example, if Repeat is set to

weeks, and Frequency is set to 1, the job repeats once each week. If Repeat is set to weeks, and Frequency is set to 3, the job repeats every three weeks.

7. Assign an end date and time for the job or indicate a number of invocations after which the job becomes inactive. The default end date is 10 years from the current date and time.

8. Click OK. The system displays the Jobs list page.

Running a job

Jobs typically run at predetermined intervals. Jobs that exist in all repositories have default schedules when they are created. See the section “Changing a job schedule” for instructions on modifying a job‟s schedule. Most jobs pass standard arguments to the method executed by the job. The arguments are set on the method tab for each job, and can be modified in most cases.

To run a job manually (at a time other than the scheduled run time):

1. Select the job you want to run.

2. Click Tools > Run. When the agent exec process next polls the repository, the job will run.

3. To view the status of a running job after you start it, click View > Refresh. When the list page refreshes, the Status column for the job is updated. You may need to click View > Refresh several times because the job does not run immediately after you click Tools > Run.

4. To view the job report, select the job and click View > Report.

5. To view the trace log for the job, select the job and click View > Trace. The tracing level for the job must be set high enough to generate a trace log, or you will not be able to find a trace log.

Viewing a job report

When a job runs, it generates a report that summarizes the results of the job. You can view reports for one or more jobs for more information about the jobs.

To view job reports:

1. Connect to the repository and navigate to Administration > Job Management > Jobs. The system displays the Jobs list page.

2. Select the jobs whose reports you want to view.

3. Select View > Report. You can also right-click, and select View Job Report from the context menu. The system displays the job report.

4. If you selected multiple jobs, click Next to view the next report.


5. After you have finished viewing the last report, click OK or Cancel to return to the Jobs list page.

Setting the trace level for a job

Trace logs contain status information logged by a job. The trace level set for a job determines the amount of information logged. The default trace level for a job is 1 (minimal trace information), with a maximum level of 10 (debug-level tracing). A trace level of 4 through 6 provides a medium level of debugging.

To set the trace level for 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 and then select View > Properties > Info. The system displays the Job Properties -

Info page.

3. Select a trace level from the Trace Level drop-down list.

4. Click OK. The system displays the jobs list page.

Improving report performance The performance of reports designed using Crystal Reports Designer depend on various factors such as:

Complexity of the report query Usage of joins Usage of parameters Usage of filters to restrict the records displayed Definition of the report layout specifying the number of columns and the sections to be displayed

This section describes a few methods that can be used to improve the performance of a report.

Optimizing the report query To optimize a report query: Create a report with a single command object

Documentum recommends creating a report query with a single command object because multiple command objects slow down performance of the report when you run the report using a Crystal Reports engine on DRS. Thus, if a report contains two queries, ensure that you combine both queries. The EMC Documentum Content Server DQL Reference Manual provides information on combining queries.

Display only the required fields

You must not use „select * from table_name‟ more often than required because when you fetch all of the records from the table, the performance of the report will be drastically reduced.

Using report parameters and filters You must use filters and parameters in reports to narrow down the report results. You can add DQL hints such as RETURN_TOP <N> and OPTIMIZE_TOP <N> to limit the number of records fetched.

Examples:

select user_name from dm_user ENABLE (RETURN_TOP 10)

This query retrieves the top 10 users from the table.


select user_name from dm_user ENABLE (OPTIMIZE_TOP 5)

This query retrieves the top five records faster than all other records that are fetched at normal speed. select user_name from dm_user ENABLE (RETURN_TOP 5, OPTIMIZE_TOP 5)

This query retrieves only top five records quickly.

Note:

You must use all DQL hints with the ENABLE keyword.

OPTIMIZE_TOP hint is ignored in Oracle and is not available in Sybase.

Select Expert (wizard), in the Crystal Reports Designer, can also be used to add filters and restrict the records displayed. To use Select Expert:

1. Click Report > Select Expert.

2. Click the New tab, select the required field, and add conditions to limit the number of records fetched.

Using predicates Predicates are used in WHERE clauses to limit the objects returned by a query. The sysobject predicates such as FOLDER, TYPE, and CABINET can be used for simplicity.

Examples:

Select object_name from dm_document WHERE TYPE (‘legal_doc’)

Select object_name from dm_document WHERE FOLDER (‘/Folder1’)

Select object_name from dm_document WHERE CABINET (‘/Temp’, DESCEND)

These queries fetch documents from the legal_doc type, folder1 folder, and all cabinets and folders in the Temp cabinet, respectively.

Performance optimization tips:

Delete any unused objects from a report. This includes deleting database tables, formulas, parameters and running total formulas. Even though these objects are not used in the report, the report engine evaluates the objects as well, thereby degrading performance.

Delete unnecessary report sections. Even though a report section is not used, the report engine evaluates the section as well, thereby degrading performance.

Disable the Printer option in reports. To disable the Printer option in reports:

1. Open the report in Crystal Reports Designer and select File > Page Setup. The Page Setup dialog box opens.

2. Select the No Printer (optimize of screen display) checkbox in the Printer Options, and save the report.

Avoid using sub-reports if possible. Inappropriate use of sub-reports is often the main reason why a report takes a long time to process.


Troubleshooting

‘Database logon failed’ error occurs when a report is run on Webtop

In versions prior to DRS 6.5 SP3, the “Database logon failed” error occurs when a report is designed for one repository and run against a different repository on Webtop.

Solution:

Update the connection details for each report to point to the current repository. Follow the procedure below:

1. Before you change the report connection details, ensure DFC is configured for the appropriate docbroker.

2. To configure DFC, edit DOCUMENTUM_HOME\config\dfc.properties and add your docbroker details.

3. To change the connection details to the current repository from Webtop, select each report and select File > Edit from the context menu. The report is checked out from the repository and is opened in the Crystal Reports Designer.

4. Specify the current repository connection details in the Connection Details window.

5. Specify the correct docbase name in the Connection URL field under JDBC Connection field after refreshing the report.

6. Check the report into the repository on Webtop.

Note: When you change the report connection details in the Crystal Reports Designer, the Save button or File > Save option is not enabled. If you want to enable it, double-click File > Save Data with Report.

Deployment of DRS on WAS fails When you deploy DRS on WAS, and specify the dfc.keystore file in dfc.properties, the deployment fails and a blank browser window is displayed instead of the message “deployment successful”.

Solution:

Comment or remove the following line from the dfc.properties of the DRS web application:

dfc.security.keystore.file=C\:/Documentum/config/dfc.keystore

Also, remove any other line pertaining to “security” and “keystore” from the dfc.properties file of the DRS application.


‘Failed to open the connection. JDBC driver not found’ error occurs in Crystal Reports Designer

Solution:

Edit the <BUSINESSOBJECTS_INSTALL_DIR>\common\3.5\java\CRConfig.xml file as follows:

Unjar the file into a temporary folder. From the <DRS_CR_WAR_UNZIP_DIR>/WEB-INF/lib directory, copy the dmjdbc.jar file to your

machine and specify the location of the jar file along with the filename in the <Classpath> tag of the CRConfig.xml file.

From the <DRS_CR_WAR_UNZIP_DIR>/WEB-INF/Classes folder, copy the dmjdbc.properties file to your machine, and specify the location of the dmjdbc.properties file.

Note: You must not specify the dmjdbc.properties filename in the <Classpath> tag. Instead, save the CRConfig.xml file and restart the Crystal Reports Designer.

‘Failed to open the connection’ error occurs in Crystal Reports Designer


Solution:

Edit the <BUSINESSOBJECTS_INSTALL_DIR>\common\3.5\java\CRConfig.xml file as follows:

Point <JavaDir> to the java 1.5 bin folder. Specify the Documentum dctm.jar file as the first entry in the classpath tag.

For example:

If the Documentum directory is located in C:/Program Files, specify C:\Program Files\Documentum\dctm.jar as the first entry in the <Classpath> tag as follows:

<Classpath>C:\Program Files\Documentum\dctm.jar;C:\Program

Files\BusinessObjects\Common\3.5\java/lib/crlovmanifest.jar;C:\Program

Files\BusinessObjects\Common\3.5\java/lib/CRLOVExternal.jar;……..;${CLAS

SPATH}</Classpath>

‘No suitable driver’ error occurs in Crystal Reports Designer

Solution:

Check the report connection details to have the following values for the JDBC driver URL and class name.

URL – jdbc:documentum:oca:docbaseext@<REPOSITORY_NAME>

Class name – com.documentum.oca.jdbc.jdbc20.ext.DjdbcDriverExt

<REPOSITORY_NAME> – name of the Docbase

If you are unable to connect to the Documentum Server when the Crystal Reports Designer automatically picks the server, perform the following:

Navigate to the path <BUSINESS OBJECTS INSTALL DIR>\

common\3.5\java\CRConfig.xml.

In the JDBCURL tag, include the jdbc:documentum:oca:docbaseext@name of the docbase, which is the same as Connection URL in the JDBC (JNDI) window of the Crystal Reports Designer used to specify the connection details.

In the JDBCClassName tag, include com.documentum.oca.jdbc.jdbc20.ext.DjdbcDriverExt, which is the same as Database Classname in the JDBC (JNDI) window of the Crystal Reports Designer used to specify the connection details.

Remove the contents of the “LogonStyle” tag. Save the CRConfig.xml file and restart Crystal Reports Designer.


‘No DocBrokers are configured’ error occurs in the Crystal Reports Designer

This error occurs if the dfc.properties file is not found in the classpath.

Solution:

Check if the folder containing the dfc.properties file is added to the “classpath” tag in the CRConfig.xml file. If you make any changes in the CRConfig.xml file, save it and restart the Crystal Reports Designer.

‘Failed to process the report’ error might occur when DRS is deployed in a UNIX-based environment

09:16:45,323 ERROR [http-32843-Processor23]

com.documentum.drs.webcomponent.ReportHandler - Failed to process the

report /opt/apps/documentum/apache-tomcat-

5.5.28/logs/documentum/local/process26042.tmp/8/060f42a08006de6d.rpt

com.crystaldecisions.sdk.occa.report.lib.ReportSDKClientDocException:

The document has not been opened.---- Error code:-2147215349 Error code

name:docNotReady

This error might occur on systems that do not have the XWindows library installed.

Solution:

In a UNIX-based environment for any application server, set the Java Virtual Machine parameter -Djava.awt.headless=true in the start-up script of the application server:

In Tomcat or JBoss, add set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true

In WebLogic, add JAVA_OPTIONS="${JAVA_OPTIONS}${JAVA_PROPERTIES} -

Djava.awt.headless=true

export JAVA_OPTIONS

In WebSphere, from the Administrative console, go to Servers > Application servers > servername > Java and Process Management > Process Definition > Java Virtual Machine. In the Generic JVM Arguments property, add -Djava.awt.headless=true and click Apply.

An error occurs when scheduling a DRS job

A “DoMethod threw Exception” occurs if the dfc.jar is copied into the directory <Documentum_Method_server_Dir>/jboss4.2.0/server/DctmServer_MethodServer

/deploy/ServerApps.ear/DmMethods.war/WEB-INF/lib.


Solution:

Delete dfc.jar, log4j.jar, jsafeFIPS.jar, aspectjrt.jar, and certjFIPS.jar from the directory Documentum_Method_server_Dir>/jboss4.2.0/server/DctmServer_MethodServer/

deploy/ServerApps.ear/DmMethods.war/WEB-INF/lib and restart the Method Server.

‘Error’ occurs when running a DRS report

While running a DRS report, you may encounter an error message. If this error is displayed, check the application server logs for the DM_DOCBROKER_E_NO_SERVERS_FOR_DOCBASE error.

This error occurs if the docbroker details of the docbase (that is logged in through Webtop) are not available in the dfc.properties of the DRS web application.

Solution:

Include the docbroker details of the docbase (logged in through Webtop) in the dfc.properties located in <DRS_WEB_APPLICATION drs_cr>/WEB-INF/classes.

Clear the cache, and restart the application server.

‘Access Violation’ error occurs in the RSA single sign-on environment

This error occurs if you have deployed DRS on Webtop or any WDK application that is configured using RSA SSO and have not added entitlement to the user.

Solution:

1. Log in to RSA Access Manager.

2. Add entitlement to the user as follows:

a. Select Manage Users > Users & Administrators > Manage Existing from the menu.

b. Choose the user created for this SSO (also created in the directory server).

c. Click Add New. The list of all available applications is displayed.

d. Select an application and click Add Entitlements.

e. Select the checkbox corresponding to the resource you want to add to the user.

f. Click Done. You must add the selected resources.


Conclusion

Benefits of using Documentum Reporting Services DRS can be configured to run reports dynamically using DRS. Reports designed for one docbase can

be run against another docbase. DRS lets you export report output to various formats like rpt, xls, doc, rtf, csv, and pdf. DRS supports a single sign-on (SSO) authentication mechanism and has been tested to work with CA

SiteMinder and Kerberos. DRS reports can be easily designed using Crystal Reports Designer. DRS jobs can be configured to automatically run reports and save report output in a repository.

References For more information, refer the following product documentation on http://powerlink.emc.com: EMC Documentum Reporting Services User Guide

EMC Documentum Reporting Services Development Guide

EMC Documentum Reporting Services Installation Guide

EMC Documentum Reporting Services Release Notes