BAM 6.7 Implementation PDF

EMC Documentum
Business Activity Monitor
Version 6.7
Implementation Guide
EMC Corporation
Corporate Headquarters:
Hopkinton, MA 017489103
15084351000
www.EMC.com
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.
Copyright 2011 EMC Corporation. All rights reserved.
Table of Contents
Chapter 1
Overview of Business Activity Monitor ..........................................................13

Overview of Business Activity Monitor................................................................13
Understanding the Business Activity Monitor architecture....................................14
Understanding BAM dashboards....................................................................15
Understanding Process Reporting Services ....................................................15
Understanding the event pipe ........................................................................15
Understanding business data monitoring ........................................................16
Understanding the format engine ...................................................................17
Understanding the aggregation engine ...........................................................17
Understanding the alert engine ......................................................................18
Understanding the gap filler job......................................................................18
Chapter 2
Quick Start Guide to BAM ..............................................................................19

Quick Start Overview ........................................................................................19
Monitoring a process ........................................................................................19
Designing a Process Execution report ...............................................................20
Designing a BAM dashboard.............................................................................22
Chapter 3
Configuring Business Activity Monitor ..........................................................25

Overview of Configuring Business Activity Monitor..............................................25
Enabling processes for monitoring.....................................................................26
Assigning Audit Trail permissions ......................................................................27
Enabling structured data type attributes for monitoring ........................................28
Enabling package object types for monitoring.....................................................29
Enabling simple process variables for monitoring ...............................................29
Logging in to TaskSpace ...................................................................................30
Configuring connection settings.........................................................................32
Synchronizing SDT and package object type changes with the BAM
database .........................................................................................................32
Updating structured data types with Process Builder .......................................33
Updating package object types with Process Builder .......................................33
Updating monitored business data with TaskSpace .........................................33
Understanding queue monitoring.......................................................................34
Configuring recovery periods.............................................................................35
Configuring data transfer latency .......................................................................36
Configuring a maximum data transfer idle time ...................................................36
Specifying a maximum data transfer idle time .................................................37
Modifying the dashboard report time-out parameter ............................................37
EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide
Table of Contents
Understanding machine clock synchronization ...................................................38

Chapter 4
Designing Reports with Process Reporting Services.....................................39

Overview of Process Reporting Services............................................................40
Understanding report entities and data sources ..................................................41
Working with activity and process entities .......................................................42
Working with activity and process aggregation entities.....................................42
Working with incomplete execution entities .....................................................43
Working with activity performer aggregation entities ........................................43
Working with queue entities ...........................................................................43
Working with business data entities ................................................................44
Working with alert entities ..............................................................................45
Understanding data sources ..........................................................................45
Understanding how data source results are generated........................................46
Working with entity fields and captions...............................................................47
Understanding data source filtering ...................................................................48
Understanding simple report types ....................................................................51
Working with pie charts and bar charts ...........................................................51
Working with dial gauges ...............................................................................52
Working with bar and line charts ....................................................................54
Working with table charts...............................................................................55
Understanding chart type properties ...............................................................55
Understanding reports that use aggregation .......................................................57
Understanding server aggregation .................................................................58
Understanding business data aggregation ......................................................60
Understanding single drill-down reports .............................................................61
Understanding multi-drill-down reports ...............................................................63
Logging in to Process Reporting Services ..........................................................64
Navigating Process Reporting Services .............................................................65
Creating a report category ................................................................................65
Designing a simple report .................................................................................66
Sorting report columns......................................................................................68
Modifying bar chart labels .................................................................................69
Choosing bar and pie chart colors .....................................................................69
Aggregating report data ....................................................................................70
Removing report aggregation ............................................................................71
Understanding reports that include computed columns .......................................72
Designing reports with computed columns .........................................................73
Adding a computed column...............................................................................75
Editing or deleting a computed column ..............................................................75
Previewing a data source..................................................................................76
Filtering report entities ......................................................................................76
Working with report security ..............................................................................77
Designing a Crystal Report ...............................................................................80
Editing Crystal Reports .....................................................................................82
Table of Contents
Understanding when to use Simple reports and Crystal Reports..........................82

Creating a report based on an existing data source ............................................83
Understanding how changes to SDTs and packages impact reports.....................83
Publishing reports ............................................................................................84
Auto refreshing reports .....................................................................................84
Configuring single drill-down reports ..................................................................84
Configuring multi-drill-down reports in PRS ........................................................86
Configuring multi-drill-down reports in a dashboard.............................................86
Configuring Crystal Report drill-downs ...............................................................87
Editing Simple reports.......................................................................................88
Deleting reports................................................................................................88
Exporting reports from PRS ..............................................................................88
Importing reports in to PRS ...............................................................................89
Editing entity field captions................................................................................89
Using the data source undo and redo feature .....................................................90
Configuring business data aggregation ..............................................................90
Deleting business data aggregation ...................................................................91
Displaying BAM reports in an enterprise portal ...................................................92
Exporting reports from the BAM server ..............................................................93
Exporting Crystal Reports from a TaskSpace application.....................................94
Chapter 5
Process Reporting Services Examples ..........................................................97

Designing a New Account Openings report ........................................................97
Designing a Total Deposits per City report..........................................................99
Calculating inter-activity duration ..................................................................... 101
Designing reports with continuous aggregation................................................. 104
Chapter 6
Designing Alerts with Process ..................................................................... 107

Overview of Designing Alerts with Process Reporting Services ......................... 107
Understanding the technical components of alerting ......................................... 108
Understanding alerting roles and responsibilities .............................................. 109
Generating alerts from aggregated data........................................................... 110
Overview of implementing alerts...................................................................... 111
Working with alert entities ............................................................................ 112
Designing alerts with process and activity entities ...................................... 112
Designing alerts with Incomplete Process and Incomplete Activity
Execution entities .................................................................................... 113
Designing alerts with Process and Activity Aggregation entities .................. 114
Designing alerts with Activity Performer Aggregation entities ...................... 115
Working with queue entities...................................................................... 116
Designing alerts with business data entities............................................... 117
Working with alert entities......................................................................... 118
Custom alert entities ................................................................................ 119
Filtering an alert data source........................................................................ 119
Writing alert expressions ............................................................................. 120
Table of Contents
Writing alert expressions using autocomplete and the keypad..................... 122

Purging alert data........................................................................................ 123
Configuring email ........................................................................................... 123
Troubleshooting alert email issues ............................................................... 124
Creating alert categories ................................................................................. 125
Designing alerts ............................................................................................. 126
Understanding alerts designed with SDTs and packages................................... 128
Designing alerts that include SDTs or packages ............................................... 129
Designing service level agreement duration alerts ............................................ 130
Configuring invoked processes to handle exceptions ........................................ 131
Validating and testing alerts ............................................................................ 131
Publishing alerts............................................................................................. 132
Overview of Working with alerts in a dashboard................................................ 132
Working with the Alert List dashlet................................................................ 132
Understanding the Alert Monitor dashboard design and layout ....................... 133
Configuring alert dashboard refresh intervals ................................................ 140
Editing alerts .................................................................................................. 141
Chapter 7
Designing Dashboards ................................................................................. 143

Understanding BAM Dashboards .................................................................... 144
Understanding the report dashlet..................................................................... 145
Understanding the process diagram dashlet..................................................... 146
Understanding the alert list dashlet .................................................................. 146
Understanding dashlet filters ........................................................................... 147
Understanding dashboard permissions ............................................................ 147
Understanding the dashboard interface............................................................ 148
Creating sub-processes in Process Builder ...................................................... 148
Creating a dashboard application .................................................................... 149
Designing a dashboard ................................................................................... 149
Adding a dashboard to an application .............................................................. 150
Adding a dashboard tab.................................................................................. 151
Assigning dashboard tabs to roles ................................................................... 151
Configuring multi-drill-down reports in PRS ...................................................... 152
Configuring multi-drill-down reports in a dashboard........................................... 153
Adding process diagrams to a dashboard ........................................................ 154
Scheduling refresh periods.............................................................................. 155
Configuring dashlet filters................................................................................ 155
Printing reports from a dashboard.................................................................... 156
Modifying dashboards..................................................................................... 156
Removing dashboards.................................................................................... 157
Deleting dashboards....................................................................................... 157
Using dashlet filters ........................................................................................ 157
Table of Contents
Understanding single and multi-search filters ................................................... 158

Configuring single and multi-search filters in a dashboard ................................. 159
Using single and multi-search filters................................................................. 160
Updating the status of an alert......................................................................... 162
Customizing a dashboard cascading style sheet............................................... 162
Viewing dashboard contents displayed in right to left languages ........................ 163
Chapter 8
Working with Preconfigured Dashboards..................................................... 165

Overview of the Preconfigured Dashboards ..................................................... 165
Understanding the Process Monitor dashboard ................................................ 166
Understanding the List of Process Instances report ....................................... 166
Understanding the Count of Started, In-flight, and Completed Processes
report ......................................................................................................... 167
Understanding the Count of In-flight Processes report ................................... 167
Understanding the Count of Processes Started within the Last Month
report ......................................................................................................... 168
Understanding the Process Instance Details report ....................................... 168
Understanding the Process Duration report .................................................. 168
Understanding the Process Summary dashboard ............................................. 169
Understanding the Count of Processes per State report ................................ 169
Understanding the Count of Activities per State report ................................... 170
Understanding the In-flight Process Statistics report ...................................... 170
Understanding the In-flight Activity Statistics report ....................................... 171
Understanding the Tasks Completed by Performer within the last 24 Hours
report ......................................................................................................... 171
Understanding the Tasks Pending for each Performer report.......................... 173
Understanding the Alert Monitor dashboard ..................................................... 173
Understanding the Alert List dashlet ............................................................. 173
Understanding the Alert Resolution report..................................................... 173
Understanding the Alerts per Activity report .................................................. 174
Understanding the Alerts per Process report................................................. 174
Localizing the preconfigured dashboards ......................................................... 174
Chapter 9
Administrating BAM Deployments ............................................................... 179

Overview of Administrating BAM Deployments ................................................. 179
Using Documentum Composer to migrate BAM artifacts ................................... 180
Importing BAM artifacts into a Composer project ........................................... 181
Installing BAM artifacts into a repository ....................................................... 182
Manually migrating custom entities designed with SDTs .................................... 183
Optimizing reports .......................................................................................... 184
Adjusting data transfer latencies in high load environments............................... 184
Using business data and custom aggregation to enhance report
performance .................................................................................................. 185
Increasing the gap filler step size..................................................................... 186
Monitoring BAM database table space ............................................................. 186
Increasing the BAM server step size................................................................ 186
Clearing cache contents when running Crystal Reports..................................... 187
Reducing Simple report results sets................................................................. 187
Table of Contents
Limiting the number of records returned in a results set .................................... 188

Purging BAM execution and aggregation tables................................................ 188
Understanding how to schedule BAM database purge jobs ............................... 189
Scheduling BAM database purge jobs ............................................................. 190
Purging the Audit Trail database...................................................................... 191
Purging simple process variable and SDT reporting data from a
repository....................................................................................................... 191
Saving historical data when process changes .................................................. 192
Understanding how scheduled jobs are impacted by Daylight Savings
Time .............................................................................................................. 192
Chapter 10
Creating Custom Aggregation, Report, and Filter Entities ........................... 193

Understanding custom aggregation, report, and filter entities............................. 193
Configuring custom aggregation ...................................................................... 194
Overview of creating custom report entities ...................................................... 197
Understanding report entity tables................................................................ 197
Creating custom report entities .................................................................... 199
Creating relationships between two entities .................................................. 202
Adding a field to a report entity..................................................................... 205
Adding a field to a report entity using a database function.............................. 206
Configuring custom filters................................................................................ 208
Understanding dashboard filters................................................................... 208
Configuring dashboard filters .................................................................... 209
Configuring business data filters ............................................................... 211
Configuring single and multi-selection search filters ................................... 212
Understanding dashboard filter operators .................................................. 216
Understanding PRS filters ........................................................................... 216
Configuring PRS filter entities ................................................................... 217
Configuring PRS filter tabs ....................................................................... 218
Configuring PRS filter token items ............................................................ 219
Defining filter entity relationships............................................................... 219
Creating PRS client filter tree items........................................................... 221
Refreshing the BAM server ............................................................................. 227
Deleting custom report and filter entities .......................................................... 227
Chapter 11
Troubleshooting ........................................................................................... 233

BAM dashboards are not being updated .......................................................... 233
Reports do not generate the expected results .................................................. 234
Using log files to assess the status of BAM engine jobs .................................... 235
Email server down and need to view pending jobs............................................ 236
Do not know host name of SMTP server, owner email address, or recipient
email address ................................................................................................ 236
Increasing email timeout parameter when network performance slow ................ 237
Recovering alert email messages sent incorrectly............................................. 237
Appendix A
Entity Relation Diagrams.............................................................................. 239
Appendix B
Report entities.............................................................................................. 243
Table of Contents
Appendix C
Database Views ............................................................................................ 245
Entity Relation Diagrams ..................................................................................................... 239

Report entities ..................................................................................................................... 243
Database Views ................................................................................................................... 245
Preface
This document describes how to configure, deploy, and maintain a process monitoring solution with
Business Activity Monitor (BAM). BAM gives business users insight into processes executing in
Documentum Process Engine. It provides the ability to generate alerts in real time and creates a
dashboard view that shows process status and performance statistics.
Intended audience
The intended audience for this document includes all roles involved with implementing a Business
Activity Monitor solution, including:
Process Designers This persona uses Process Builder to design processes. Designing
processes with Process Builder is out of scope for the document, however, there are a few BAM
configuration procedures that are completed in Process Builder.
Process Administrator This persona uses a specific set of functions available in the
Administration tab of TaskSpace to configure BAM.
Report Designers This persona uses Process Reporting Services to design reports and alerts.
Dashboard Designers This persona uses the dashboard component within TaskSpace to design
dashboards.
Database Administrator This persona is responsible for creating custom report and filter
entities, if required.
Support information
EMC Documentums technical support services and policies are available at the EMC Powerlink
website (http://Powerlink.EMC.com).
Note: You must register online at Powerlink before using it.
Related documentation
Download product documentation from Powerlink at http://Powerlink.EMC.com. Related
documents include:
Documentum Business Activity Monitor Installation Guide
Documentum Business Activity Monitor Release Notes
Documentum Process Builder User Guide
Documentum Composer User Guide
Documentum TaskSpace Configuration Guide
Documentum Administrator User Guide
Revision history
The following changes have been made to this guide.
11
Preface
Revision Date
Description
July 2011
Updated the Understanding when to use Simple reports and Crystal Reports
section of the Designing Reports with Process Reporting Services chapter
April 2011
Initial publication
12
Chapter 1
Overview of Business Activity Monitor
This chapter discusses the following:
Understanding the Business Activity Monitor architecture

xCelerated Composition Platform (xCP) enables IT organizations to build and deploy case-based
business applications rapidly. xCP refers to a set of solutions and technologies used to design, execute,
and monitor case-based applications and processes. xCP is comprised of the following products:
Process Builder
Process Engine
Forms Builder
TaskSpace
BAM
Each product has its own installation and documentation set.
Process Builder is a graphical tool used by process designers to develop business processes. The
Process Engine executes process templates designed in Process Builder. Forms Builder is used to
create and modify form-based templates. TaskSpace is used for task processing and document retrieval.
Each process that executes in Process Engine is a process instance. Process instances are composed
of a specific set of activity instances (also called work items) completed by users. BAM collects
and stores process execution data, prepares it for reporting, and provides a real-time dashboard
display environment. Process Reporting Services (PRS) is used to design BAM reports and alerts.
BAM reports are displayed in dashboards designed in TaskSpace. BAM enables organizations to
detect problem conditions that exist in executing processes, to diagnose these problems to determine
their root cause, and to correct them. It also provides valuable historical information about process
execution to enable long-term process improvement.
To begin designing a BAM solution you must have:
Content Server, the BAM database, BAM server, TaskSpace, and Process Reporting Services
deployed.
Note: BAM deployment and PRS installation are addressed in Documentum Business Activity
Monitor Installation Guide.
For a complete set of system requirements, see the Documentum Business Activity Monitoring
Release Notes.
13
A case-based or other process-based application designed.

A BAM administrator defined in Content Server that is assigned the BAM Admin role. This role
provides access to the BAM configuration options available in the Administration tab of TaskSpace.
A user in Content Server that is assigned the ts_designer role. This role has control over designing
reports in PRS and creating dashboards in TaskSpace.
Understanding the Business Activity Monitor

architecture
Process execution data is stored in three types of Content Server tables. SDT object type tables hold
business data entered by users. Queue object type tables contain information about work tasks and
performers. The Audit Trail tables contain information about processes, activities, and package object
types. All of this information in inserted into the BAM database. An event pipe is the mechanism by
which data is transferred from Content Server to a BAM database.
SDT object type and queue object type data is piped directly to corresponding execution tables in
the BAM database. Process, activity, and package object type data is not inserted directly into the
execution table. In the Audit Trail tables, information about the execution of one process instance is
stored as a single row of data. The format engine takes this data, transforms it into a relational data
model, and inserts the process information into the BAM database. The integration tables of the BAM
database are a copy of the process data as it is stored in the Audit Trail tables.
The execution tables store process instance data. From here, this data is aggregated and inserted
into aggregation tables. Aggregating execution data means that process instances are collapsed into
groups for which one or more arithmetic functions apply. For example, aggregation allows users to
calculate the average duration for processes that began within the last hour, week, or year. The BAM
database schema is created when BAM is deployed. BAM deployment is addressed in Documentum
Business Activity Monitor Installation Guide.
The gap filler is another component of the BAM server. Should the BAM server be down for any
reason, a gap filler quickly processes data that has continued to be written to Content Server. Users
configure a gap filler recovery period.
On top of the BAM server runs a reporting engine that manages all report related services. The alert
engine is used to evaluate report data sets against alert expressions. Alert expressions are written using
JEP. Reports and alerts are designed in PRS. The reporting engine is also responsible for making
reports and alerts available to BAM dashboards.
Clustering is supported. See the Business Activity Monitor Installation Guide for more information on
clustering.
This section describes each component of BAM architecture in more detail.
14
Figure 1
Business Activity Monitor technical architecture
Understanding BAM dashboards

A BAM dashboard is a display environment for monitoring executing processes in real time. A
dashboard is an application created within TaskSpace that contains dashlets. Dashlets display the
contents of a specific report, diagram, or alert. Dashboard designers use a drag-and-drop interface to
configure dashboards. Dashboard designers can also schedule dashboard refresh periods and configure
dashlet filtering. Dashboard users interact with a dashboard to monitor processes. These users are
granted permissions to view the content of a specific dashboard and can respond to alerts. Dashboard
design is addressed in a separate chapter. For more information see Designing Dashboards, page 144.
BAM is also shipped with three preconfigured dashboards that are already assembled. Each
preconfigured dashboard contains a set of reports defined in PRS. For more information see Working
with Preconfigured Dashboards, page 165.
Understanding Process Reporting Services

Process Reporting Services (PRS) is the component of BAM used for creating reports and alerts on
monitored processes. Reports are formatted either in PRS or in an external Crystal Reports editor.
Report entities are provided with the BAM software, although custom report entities can be created.
Alerts are also defined in PRS.
Three chapters are dedicated to PRS, beginning with Designing Reports with Process Reporting
Services, page 40.
Understanding the event pipe

As business processes execute in the Process Engine, event data is written to Content Server. Every 5
seconds the BAM server queries Content Server and extracts events. The event pipe is the BAM server
job that inserts data into the integration and execution tables of the BAM database. Events are inserted
into the BAM database every 5 seconds with a default latency of 30 seconds. Events that occurred 30
seconds prior are inserted into the BAM database every 5 seconds. The latency interval compensates
15
for late arriving events. The latency interval can be configured. Configuring data transfer latency,
page 36 describes latency settings in more detail.
The BAM server controls the operation of the event pipe. If the BAM server is down for any reason, the
event pipe cannot operate and events are not inserted into the BAM database. A gap develops between
events inserted into the BAM database and events that are not yet extracted from Content Server.
A special process called gap filling is used to address these situations. The gap filler allows the BAM
server to catch up on its work, quickly extracting the events that it missed while it was down. For
more information on the gap filler see Understanding the gap filler job, page 18 and Configuring
recovery periods, page 35.
Understanding business data monitoring

In addition to process and queue data, BAM supports the monitoring of three forms of business
data: Structured Data Types (SDTs), package object types, and (simple) process variables. Without
business data monitoring, the data collected during process execution is constrained to default process
data. Default process data is the set of data automatically captured while a process executes. Process
names, process IDs, activity durations, and information about performers are all examples of default
process data. Business data adds to this information by monitoring attribute values associated with a
process instance. Report designers use this data to generate sophisticated reports. Business data is
also used in alerts. For example, an SDT is used to design an alert that triggers when the number of
company shares traded exceeds a certain value.
SDTs and package object types are considered complex process variables comprised of multiple
attributes. Process variables can also be simple in structure, with only a single attribute. As a result,
there are some differences in monitoring of SDT and package object types as opposed to simple
process variables. First, SDT, and package object type reporting entities can be used as base entities in
a report. A base entity is the first entity used to define a report in PRS. A simple process variable report
entity is, in contrast, always nested under the Process Execution report entity. Designing alerts with
business data entities, page 117 describes business data reporting entities.
In addition, SDTs and package object types can be aggregated. Aggregation is not available for simple
process variables. Business data aggregation is configured in PRS. Understanding the aggregation
engine, page 17 describes the concept of aggregation. Configuring business data aggregation, page
90 outlines the aggregation procedure in PRS.
And finally, SDTs and package object types can be updated with the BAM database when there are
changes. The update operation is not required for simple process variables. Synchronizing SDT and
package object type changes with the BAM database, page 32 explains how to use the update feature.
All business data monitoring configuration options are available in Process Builder. Therefore, it is
usually the process designer that specifies which attributes to monitor. Once configured, data is written
to the BAM database.
For more information on configuring business data monitoring, see Enabling structured data type
attributes for monitoring, page 28, Enabling package object types for monitoring, page 29, and
Enabling simple process variables for monitoring, page 29.
16
Understanding the format engine

The event pipe inserts process execution data into the integration table of the BAM database. Each row
of the integration table contains data about one process instance, including activities, and performers.
The format engine transforms the data into a relational data model, and inserts it into the execution
tables of the BAM database. The format engine runs two jobs: a process formatter job and an activity
formatter job. Formatting is complete when the data is inserted into execution tables. In the next
step data is aggregated.
Understanding the aggregation engine

The execution tables of the BAM database eventually contain thousands of rows of data. In high
volume environments, BAM reports take a long time to run. The aggregation engine creates summaries
of execution data so that these reports can run against summary data, with much better performance.
For process, activity, and performer entities the aggregation engine calculates the following metrics:
Average duration (milliseconds and seconds)
Count of completed instances
Count of failed instances
Count of ongoing instances
Count of started instances
Maximum duration
Minimum duration
Note: Aggregation entities can also be created for business data objects.
The following calculations are made for a series of time intervals:
5 minutes
15 minutes
30 minutes
Hourly
Daily
Weekly
Monthly
Quarterly
Yearly
This summary information is then inserted into the aggregation tables. Understanding reports that use
aggregation, page 57 contains more information about the concept of aggregation.
17
Understanding the alert engine

The alert engine scans execution data to identify when an alert condition is met. If an alert condition is
met, email notifications are sent. Every time the alert engine runs, it receives a list of active alerts
(alerts can be inactive, too) from PRS. Alerts scan either instance or aggregated data. The report engine
executes the alert and receives a result. For each row, the alert engine evaluates the alert expression. If
the alert expression is True for a row, then the process instance is added to the alert instance table of
the database. A positive evaluation also generates an email that is sent to all designated recipients. If
configured, the alert engine can invoke a new process within Process Engine.
The alert engine also provides services utilized by the BAM dashboard. Alerted processes are
displayed in a diagram dashlet and alert icons are placed on the diagram indicating those activities
that require attention. In addition, an alert dashlet displays all alert instances. The alert status is
updated in the alert dashlet by a user.
For more information about designing alert, see Designing Alerts with Process Reporting Services,
page 107.
Understanding the gap filler job

A gap filler job runs whenever the BAM server is down, but events are still being written to Content
Server. Without the BAM server up and running, this data is not formatted or aggregated. A gap filler
job recovery period can be configured. Once the server is started, the gap filler job begins its work
formatting data within the recovery period. For example, if the BAM server is down for one month, a
user can specify to have only events from the last ten days piped to the BAM database. Once the gap
filler job is completed, the BAM server catches up and returns to normal operation. The gap filler job
recovery period is specified in the Administration tab of TaskSpace. By default the gap filler interval
is two hours. Check the I_BAM_SERVER_CONFIG table to monitor the status of a gap filler job. For
more information on configuring the gap filler, see Configuring recovery periods, page 35.
18
Chapter 2
Quick Start Guide to BAM
Quick Start Overview
Monitoring a process
Designing a Process Execution report
Designing a BAM dashboard
Quick Start Overview

The Business Activity Monitor (BAM) is a product of EMC Documentum that gives business users
insight into processes executing in the Documentum Process Engine. It provides the ability to generate
alerts in real time and creates a dashboard view that shows process status and performance statistics.
BAM allows you to develop sophisticated and custom monitoring solutions, but is easy to get up and
running quickly. Even the most complex monitoring solutions are derived from four basic procedures.
Once you are familiar with the fundamentals it is easier to design more complicated BAM applications.
In this chapter you learn how to monitor a process, create a process execution report, and design a
dashboard that displays your report.
At a minimum, you must have:
Process Builder installed
A process designed in Process Builder that is not yet validated or installed
TaskSpace installed
BAM installed, including Process Reporting Services
Monitoring a process
Processes are monitored when the Audit Trail is turned on. When the Audit Trail Settings is turned
on, data is written to the Audit Trail and then processed by the BAM server. The Audit Trail feature is
available in the Process Properties dialog box of Process Builder.
CAUTION: The user responsible for turning the Audit Trail on and off must have the
Config Audit extended privilege assigned to them. Otherwise, these options are grayed
out. Assigning Audit Trail permissions, page 27 provides guidance in assigning the config
audit extended privilege to a user.
To turn on the Audit Trail:
19
1. Open the process you want to monitor.

The Process Properties window opens.
Note: The process must be uninstalled for the Audit Trail Settings to be modified.
2. From the Tools menu, select Process Properties.
3. Select the On radio button.
4. Click OK.
5. Save, validate, and install the process.
Designing a Process Execution report

In this procedure, you design a basic report that includes the Process Execution report entity.
To design a Process Execution Report:
1. Within PRS, select the Reports tab, if not already selected.
2. From the navigation tree select Report Categories.
3. From the File menu, select New > Simple Report.
The New Simple Report dialogue appears.
4. In the Name field enter Process Execution and click Finish.

The report is added to the category.
20
5. On the Palette, click the Process report entity category.

6. Click the Process Execution report entity.
7. Then, hover your mouse over the report design area and click your left mouse button. The report
entity is added to the design area.
8. Click the Refresh button
in the Data Source Preview window.
Data is displayed in the Data Source Preview window.

9. In the State list box, select Published. Publishing makes the report available for use in a
dashboard.
21
10. From the File menu select Save.
Designing a BAM dashboard

A BAM dashboard is a display environment for monitoring executing processes in real time. The
primary purpose of a dashboard is to provide line-of-business and IT personnel a tool for monitoring,
understanding, and resolving process issues as they occur. Dashboards are designed in TaskSpace
and consist of at least one, and typically multiple, dashlets. Dashlets display the contents of specific
reports, process diagrams, or alerts. In this section, you design the Quick Start Dashboard that
includes just the Process Execution report.
Dashboard designers and dashboard viewers are two separate roles in TaskSpace. In the following
procedure, you are using the ts_designer role.
To design a BAM dashboard:
1. Log in to TaskSpace.
2. Select the Configuration tab.
3. From the navigation tree, select Dashboards and then click Create.
4. In the Name field, enter Quick_Start_Dashboard and in the Label field, enter Quick Start
Dashboard. The label appears as the name of the dashboard.
5. Click Next.
22
The dashboard design canvas is displayed.

6. From the navigation tree click the plus sign (+) next to Report Categories. The Process
Execution report appears.
7. Click and drag the Process Execution report from the list and place it on the dashboard design
palette. This report takes up the entire dashboard. Additional reports can be added to the left
or right of this first report.
8. Click Save.
23
24
Chapter 3
Configuring Business Activity Monitor
Overview of Configuring Business Activity Monitor
Enabling processes for monitoring
Assigning Audit Trail permissions
Enabling structured data type attributes for monitoring
Enabling package object types for monitoring
Enabling simple process variables for monitoring
Logging in to TaskSpace
Configuring connection settings
Synchronizing SDT and package object type changes with the BAM database
Understanding queue monitoring
Configuring recovery periods
Configuring data transfer latency
Configuring a maximum data transfer idle time
Modifying the dashboard report time-out parameter
Understanding machine clock synchronization
Overview of Configuring Business Activity

Monitor
BAM configuration refers to a set of features that enable process execution data to be collected,
formatted, and aggregated by the BAM server. BAM configuration involves two personas and
is divided into four phases:
First, process designers enable processes and business data (SDTs and package object types) to be
monitored in Process Builder.Note: BAM currently does not monitor task assignments. BAM
records when a process or activity starts, but does not record which tasks are assigned to users
until the tasks have been completed. This is a limitation of the system that will be corrected in
a future release.
Once enabled, the structure of the business data must then be updated in the BAM database.
25
Within the Administration tab of TaskSpace, process administrators must make sure that a
connection with the BAM server is established. Without proper configuration, process data does not
populate the BAM database.
As processes are monitored, the process administrator fine-tunes BAM.
Figure 2
Actor, BAM configuration interaction diagram
Enabling processes for monitoring

Processes are enabled for monitoring in Process Builder. Monitoring begins when process data is
written to the Audit Trail. The process designer enables monitoring in the Process Properties
dialog box.
For more information, see the Documentum Process Builder User Guide.
For more information about auditing in Documentum software, see the Documentum Content Server
API Reference Manual.
CAUTION: The user responsible for enabling auditing and BAM reporting must be assigned
the Config Audit extended privilege. Without the proper permissions, these options are grayed
out. Assigning Audit Trail permissions, page 27 provides guidance in assigning the config audit
extended privilege to a user.
To enable a process for monitoring:
1. Log in to Process Builder.
26
2. Open a process template.

3. Select Process Properties from the Tools menu or click the Template Properties icon on the
toolbar.
4. Select the General tab. Basic template information appears as read-only text at the top of the
template.
5. To monitor events required for BAM reports and alerts, select Only BAM Events.
6. To create the full set of audit events, including BAM events, select All Events.
7. Click Ok.
The Process Properties dialog box closes.
Assigning Audit Trail permissions

Users that turn the Audit Trail on and off must be granted the Config Audit extended privilege. This
privilege is granted in the User Properties dialog in TaskSpace. This privilege cannot be granted to
oneself. Log in as another user with administrative rights first, and assign the privilege to your user.
For example, if you want to grant the dmadmin user this privilege, you would first have to log in to
TaskSpace as any other administrative user and then assign this extended privilege to dmadmin.
To assign the Config Audit extended privilege:
1. Log in to TaskSpace as a user with administrative rights.
2. Click the Administration tab.
3. Expand User Management on the tree menu.
4. Select Users.
5. Navigate to and select the user to which the config audit extended privilege is being assigned.
6. Click Properties.
7. Select Config Audit from the Extended Privileges drop-down.
8. Click Ok.
27
Enabling structured data type attributes for

monitoring
Structured data type attributes are one form of business data that are monitored. Configuring an SDT
attribute to be monitored involves both the Structured Data Type window and the Activity Inspector
window. Selecting an SDT attribute to be monitored in the Structured Data Type window only gives
the attribute the potential to be monitored. It does not fully enable the attribute to be monitored. The
attribute must also be selected in the Activity Inspector window.
Note: If an attribute is selected in the Activity Inspector window but is not selected in the Structured
Data Type window, the attribute is not monitored.
Once an attribute is enabled for monitoring, the process designer must update the attribute with
the BAM database. Updating prompts BAM to create execution tables in the BAM database, and
corresponding report and filter entities. Synchronizing SDT and package object type changes with
the BAM database, page 32 addresses how to perform the update operations within both Process
Builder and the Administration tab of TaskSpace.
To enable an SDT attribute for monitoring:
1. Log in to Process Builder.
2. Right-click a data type within the Structured Data Type selection panel.
3. Select View Detail... from the menu.
The Structured Data Types dialog box appears and displays the details of the structured data type.
4. Locate the attribute to monitor.
5. Select the Reportable checkbox for each attribute you want monitored.
28
6. To update the SDT with the BAM database, select the Update BAM Database tables based on
this SDT definition checkbox. The BAM database is updated with the attribute definition.
Note: The update operation applies to all attributes and not just the selected attribute.
7. Click Ok to close the Structured Data Type window.
8. Open the Activity Inspector window for each monitored activity.
9. Click the Data tab.
10. Select the Report checkbox for each monitored attribute.
11. Click Ok to close the Activity Inspector window.
Enabling package object types for monitoring

Package object types are one form of business data that BAM monitors. Monitoring package object
type data requires a separate configuration than is required for structured data types. Once a package
object type is enabled for monitoring, the process designer updates the attribute in the BAM database.
Updating prompts BAM to create execution tables in the BAM database, and corresponding report
and filter entities.
Synchronizing SDT and package object type changes with the BAM database, page 32 addresses
how to perform the update operations within both Process Builder and the Administration tab of
TaskSpace.
To enable a package for monitoring:
2. Open the Activity Inspector window of an activity.
4. Select the package to monitor.
5. Select the This package can be used to generate reports checkbox.
Enabling simple process variables for

monitoring
Simple process variables are one form of business data that BAM monitors. Monitoring this data
requires a separate configuration than is required for structured data types and packages.
Note: Unlike SDTs and packages, simple process variables are not manually updated in the BAM
database. The update happens automatically.
To enable simple process variables to be monitored:
2. Open the Activity Inspector window of an activity.
29
4. Select the process variable to monitor.

5. Select the This variable can be used to generate reports checkbox.
Logging in to TaskSpace
Complete this procedure to log in to TaskSpace.
To log in to TaskSpace:
1. Open a supported browser. For a list of supported browsers, refer to the Documentum TaskSpace
Release Notes.
2. Navigate to the TaskSpace user interface at the following URL:
http://server_name:port_number/deployment_name?appname=app_name
The following table explains each variable in this URL:
Table 2
The TaskSpace URL variables
URL variable
Explanation
server_name
The name of the computer on which TaskSpace is installed.
port_number
The port where the application server listens for connections.
deployment_name
The virtual directory created during installation.
app_name
The name of a TaskSpace application.
Note: If you are not sure what URL to use, ask your system administrator.If you are accessing the
TaskSpace user interface for the first time, omit the question mark and everything that follows.
The login page appears.
3. On the TaskSpace login page, select a repository and enter your login name and password.
4. To have the login page automatically recall this information, select the Remember my credentials
option.
30
Note: Once you are logged in, you can view or delete your saved credentials by clicking
Preferences.
5. To enter a Microsoft Windows NT domain name, click More Options and enter the domain.
6. To select the language for text in the TaskSpace user interface, click More Options and select the
language.
7. To connect to the repository using a particular server, click More Options and select that server
from the Server list box. The default is Any Running Server.
8. To use accessibility features, click More Options and check Additional Accessibility Options.
The accessibility mode provides linear navigation, tab navigation, lists instead of menus, and
additional descriptive text.
9. To change your password, complete the following steps:
Note: If your organization uses Lightweight Directory Access Protocol (LDAP), you cannot
change your password from the TaskSpace login page. Ask your system administrator how you
can change your password.
a. Click More Options.

b. Click Change Password.
c. Type your current password and new password.
d. Click Apply.
10. Click Login. The TaskSpace software determines the role membership of your user account, and
determines which of these roles have been configured for use in the TaskSpace user interface.
If your login account is a member of only one role, the TaskSpace user interface appears. The
interface elements available to you depend on your role.
If your login account is a member of multiple roles, you are prompted to select a role. Also, if
your account is a member of a role that is itself a member of another role, the inherited role also
appears in the list, as long as it has been configured for use in the TaskSpace user interface.
11. If prompted, select a role and click Select.

The TaskSpace user interface appears. The interface elements available to you depend on the
role you selected.
Note: After login, you can switch to a different role by selecting it from the list box in the top bar.
The interface changes to reflect the new role.
31
Configuring connection settings

The BAM server interacts with TaskSpace, the dashboard, and Process Builder. Dashboards request
reports from the BAM server. Process Builder communicates to the BAM server when business data is
monitored. Each of these clients connects with the BAM server. To help with this connection, the
BAM server publishes its address to a specific Content Server object. Each client application reads the
object and connects to the BAM server.
Configuring connection settings involves entering BAM host and port numbers.
To configure connection settings:
1. Log in to Taskspace.
2. Select the Administration tab.
3. From the tree menu select Server Management > Business Activity Monitoring > Data
Transfer Settings.
4. Within the Connection region on the form, enter the BAM Host URL. This URL is the machine
on which the BAM server is deployed.
5. In the BAM Port field, enter the BAM server port number.
6. Click Ok at the bottom of the form.
Synchronizing SDT and package object type

changes with the BAM database
Over time, and especially in cases where BAM is deployed, configured, and tested in a development
environment, the structure of an SDT or package changes. These changes include:
adding SDTs/packages
deleting SDTs/packages
modifying SDT/package names
adding attributes
deleting attributes
modifying attribute names
All changes to monitored SDTs and packages must be reflected in the BAM database in order for
reporting to function correctly. The update operation is performed either in Process Builder or within
the Update BAM Data Definitions page in the Administration tab of your TaskSpace application.
TaskSpace can also be used to disable business data monitoring completely. Disabling removes
corresponding report entities, filter entities, and deletes execution data from the business data tables
in the BAM database.
This section addresses each method of updating the BAM database.
Note: The update operation requires many system resources and takes time. This demand on system
resources is because BAM database tables and report entities are either created or modified.
32
CAUTION: For reports designed before synchronization, an inconsistency can develop between
entities and fields used in the report and the structure of the BAM database tables. For example,
a report designed with a Purchase_Order entity provides a total dollar amount of orders for
each day of the week. Then, in Process Builder the Purchase_Order SDT is deleted in favor of
customer_PO. The synchronization operation drops the auto-generated tables associated with
Purchase_Order and creates tables used to store customer_PO data. However, the original
report still uses an old reporting entity (Purchase_Order) that is no longer valid. When report
entities and database tables are inconsistent, a dialog box displays the entities and fields that
must be removed or deselected. The dialog displays during the following actions:
open report
preview report
save report
Updating structured data types with Process Builder

Structured Data Type definitions must be consistent between Content Server and a BAM database.
SDT definitions in the BAM database can be updated from within Process Builder.
To update structured data types from Process Builder:
1. Select Update BAM Data Definitions from the Tools menu.
2. Select the checkbox for each SDT to update and click the Update button.
3. To update all SDTs select the Select All checkbox and click the Update button.
4. Click Close.
Updating package object types with Process Builder

Package object type definitions must be consistent between Content Server and a BAM database.
Package object type definitions are updated in the BAM database from within Process Builder.
To update package object types from Process Builder:
1. Select Update BAM Data Definitions from the Tools menu.
2. Click the Update button within the Object Types region of the window.
3. Click Close.
Updating monitored business data with TaskSpace

SDT and package object type definitions must be the same in Content Server and a BAM database.
TaskSpace can be used to update a BAM database with any changes to both SDTs and package object
types. SDTs and package object types can also be updated from within Process Builder, but they are
separate operations.
To update monitored business data with TaskSpace:
33

3. From the tree menu select Server Management > Business Activity Monitor > Update BAM
Data Definitions.
4. Select one of the following options:
Update BAM tables based on SDT definition allows the user to select a single SDT from the
pull-down list.Note: This option only includes SDTs. It does include package object types.
To update package object types, use the Update all BAM tables based on SDT and object
type definitions option.
Update all BAM tables based on SDT and object type definitions allows for a mass update to
all SDT and package object types.
Delete BAM tables for the selected type when both of the following conditions are true:
you do not want to monitor the selected business data object anymore.
data for the monitored business data object can be permanently deleted from the BAM
database.
This operation deletes all corresponding execution data that has been collected. This data
cannot be retrieved.
5. Click Ok.
Understanding queue monitoring

BAM supports queue management. A queue is a container that holds work items (also known as
activity instances) until a performer completes them. Performers are individuals responsible for
completing specific steps within a process. Sometimes processes route work items to a specific
performer. Other times, any number of performers can complete a work item. Instead of automatically
routing work to a specific performer within a process, work items are routed to a queue where they are
selected and completed. Work items within a queue are processed in a first in, first out order. However,
there are other factors (like the priority and age of the work item) that impact this order.
Within the flow of a process, a queue is assigned as the performer of a manual activity. Queues are
uniquely named and have thresholds (the maximum number of work items allowed in the queue), users
(a list of performers that can claim work items within the queue), and policies (rules that govern how
the queue operates). Work items exist in a number of different states, called events:
Started
Completed
Aborted
Acquired
Unacquired
Delegate
Suspend
Unsuspended
Queue monitoring does not require any additional configuration.
34
Note: All work items in a queue are monitored, even if the process to which the work item belongs is
not monitored. If the parent process of the work item is not monitored, then you cannot report on the
relationship between the work item and the process.
For more information about queue reporting entities, see Working with queue entities, page 116.
Configuring recovery periods

Content Server writes process execution data to the audit trail database, which in turn is transferred to
the BAM server over an event pipe. Without the BAM server up and running this data is not formatted
or aggregated, and ultimately not reportable. A gap filler recovery period is configured to send the
BAM server back in time to catch up on data that was missed. The default value is seven days of data,
but the user can change this value. There are three types of gap filler:
Process Gap Filler retrieves data related to process execution such as start and stop times, and
triggers.
Activity Gap Filler retrieves data related to activity execution such as activity start and completion
data, and delegation.
Business Data Gap Filler retrieves structured data type and package information.
Once the BAM application server is restarted the gap filler begins its work formatting data within the
time period specified. For more information on gap fillers see Understanding the gap filler job, page 18.
To configure recovery periods:
3. From the tree menu select Server Management > Business Activity Monitor > Data Transfer
Settings.
4. Use the fields to specify the Recovery Period in months, days, and hours.
5. Choose the gap fillers to which the period applies by selecting the Processes, Activities, or
Business Data check boxes.
6. Click Ok at the bottom of the window.
35
Configuring data transfer latency

Every 5 seconds the BAM server queries the Audit Trail and inserts events into integration tables of the
BAM database. But the BAM server is not processing the most recent events, it is processing events
that occurred 30 seconds in the past. The term for this 30 seconds offset is data transfer latency which
is configured so that the BAM server collects late arriving events.
In a typical BAM implementation, the default data transfer latency of 30 seconds suffices. This
parameter should be set to several minutes in high load environments. Adjusting data transfer latencies
in high load environments, page 184 provides more information on data transfer latencies in high
volume environments.
To configure data transfer latency:
3. From the tree menu select Server Management > Business Activity Monitor > Data Transfer
Settings.
4. Enter a value in the Data Transfer Latency field.
The value is expressed in seconds.
Configuring a maximum data transfer idle time

The concept of time for the BAM server is derived from execution time, and in particular, the time of
specific events within a process. This type of configuration prevents data from being lost when two
different machine clocks (the Content Server and BAM server) are not synchronized. This type of
configuration also has one important side-affect. Every 5 seconds the BAM server checks for events
in the audit trail database. If no events are found, the BAM server remains idle until the next check.
When no events are found, the BAM server clock does not advance. This means that the aggregation
and alert engines do not run, which can lead to inaccurate reports.
Maximum data transfer idle time is defined as the amount of time (in seconds) after which the BAM
server clock advances when no events are detected. The default idle time is 600 seconds. After the
BAM server clock advances, it performs a final sweep of the Audit Trail. Late-arriving events are
captured and inserted into the BAM database. There are at least three reasons for late-arriving events:
1. The Content Server has been down and processes resume on startup.
2. There is latency in the performance of the network.
36
3. There are multiple content servers inserting data into the audit trail database.
If data is found, the BAM server clock adjusts to the new time and data is formatted and aggregated.
Maximum data transfer latency

The last event inserted into the Audit Trail database occurred at 1:00 PM. Every 5 seconds the BAM
server sweeps data from the audit trail database. After 10 minutes no events are detected, but the clock
of the BAM server still reads 1:00 PM. When the maximum data transfer idle time is 600 seconds,
the BAM server clock advances to 1:10 PM and performs one final sweep. The final sweep time
interval is also 10 minutes.
Specifying a maximum data transfer idle time

The maximum data transfer idle time is configured in TaskSpace.
To configure maximum data transfer idle time:
3. From the left tree menu select Server Management > Business Activity Monitor > Data
Transfer Settings.
4. Enter a value in the Maximum Data Transfer Idle Time field.
Modifying the dashboard report time-out

parameter
BAM dashboard reports time out when they take longer than 1 minute to run. Increase the timing for
this parameter when your dashboard reports experience a time-out.
Note: The timeout property value is entered in milliseconds.
To modify a dashboard report time-out parameter:
1. Navigate to [TaskSpace]/WEB-INF/classes/ .
2. Open thinClientContext.xml with any XML editor.
3. Find <property name="timeout".
4. Enter a new timeout value in milliseconds.
5. Save your changes.
37
6. Restart the TaskSpace application server.
Understanding machine clock synchronization

The Content Server, BAM application server, and BAM database server clocks must be synchronized
to within 5 seconds with an outer limit of 30 seconds. In clustered environments, the clocks between
each Content Server within the cluster must be synchronized. Lack of synchronization can result is loss
of BAM data. If it is not possible to synchronize machine clocks then adjust the data transfer latency
upwards. In high load environments where more than 100 workflow events are generated concurrently,
the Content Server may experience a latency when inserting records into the Audit Trail. When a delay
occurs, the data transfer latency must be adjusted upwards to 5 minutes or more. Configuring data
transfer latency, page 36 describes how to adjust the data transfer latency.
38
Chapter 4
Designing Reports with Process
Reporting Services
Overview of Process Reporting Services
Understanding report entities and data sources
Understanding how data source results are generated
Working with entity fields and captions
Understanding data source filtering
Understanding simple report types
Understanding reports that use aggregation
Understanding single drill-down reports
Understanding multi-drill-down reports
Logging in to Process Reporting Services
Navigating Process Reporting Services
Creating a report category
Designing a simple report
Sorting report columns
Modifying bar chart labels
Choosing bar and pie chart colors
Aggregating report data
Removing report aggregation
Understanding reports that include computed columns
Designing reports with computed columns
Adding a computed column
Editing or deleting a computed column
Previewing a data source
Filtering report entities
Working with report security
Designing a Crystal Report
Editing Crystal Reports
Understanding when to use Simple reports and Crystal Reports
39
Designing Reports with Process Reporting Services
Creating a report based on an existing data source
Understanding how changes to SDTs and packages impact reports
Publishing reports
Auto refreshing reports
Configuring single drill-down reports
Configuring multi-drill-down reports in PRS
Configuring multi-drill-down reports in a dashboard
Configuring Crystal Report drill-downs
Editing Simple reports
Deleting reports
Exporting reports from PRS
Importing reports in to PRS
Editing entity field captions
Using the data source undo and redo feature
Configuring business data aggregation
Deleting business data aggregation
Displaying BAM reports in an enterprise portal
Exporting reports from the BAM server
Exporting Crystal Reports from a TaskSpace application
Overview of Process Reporting Services

Process Reporting Services (PRS) is a BAM tool used for creating reports and alerts on monitored
processes. Reporting itself extends beyond PRS and involves a few other BAM components, as
displayed in the following figure. The backbone of any report or alert is a data source. A data source is
a query that runs against the BAM database (by way of the BAM server) and is defined with report
entities and fields. All BAM report entities and fields are stored in the repository and are made
available to PRS through the BAM server. Queries can be run against execution tables or any of
the aggregation tables of the BAM database. Once data is returned to PRS, the report can either be
formatted as a simple Flash-based chart, or made available to Crystal Reports for advanced formatting.
Reports formatted in Crystal Reports are synchronized back into PRS where they, along with simple
reports, are published to a BAM dashboard.
Note: Flash Player version 9 or higher is required to run PRS. If Flash Player is not installed, the user
is prompted to install it. Once installed, PRS must be restarted.
40
Figure 3
BAM reporting components
Two personas are involved in designing BAM reports. A report designer uses PRS to design simple
reports, and define Crystal Report data source. Crystal Reports are taken out of PRS for formatting
by a Crystal Reports designer, which is then synchronized back into PRS by a report designer. Both
simple reports and Crystal Reports are published, which makes them available to use in a dashboard.
Report designers also configure a special type of report, called drill-down reports. The drill-down
feature within PRS applies only to simple reports. Drill-down reports can also be defined for Crystal
Reports, but this configuration is completed in the Crystal Reports software.
Figure 4
Report designer interaction diagram
Understanding report entities and data sources

Process Reporting Services is a visual tool that allows users to drag and drop report entities onto a
canvas, create relationships, and select fields. Report entities provide a view of the data stored in the
41
execution and aggregation tables of the BAM database. The column of each table is exposed to PRS as
an entity field. Report entities operate as queries against the BAM database that returns a result. All
BAM report entities are provided with the software and are stored in a repository. If necessary, you
can also create your own, custom report entities.
Report entities are displayed within the palette in PRS. Report designers must select an entity category
(for example, Activity) and then select a specific entity. For a complete list of report entities for
each category, see BAM report entities, page 241.
Figure 5
PRS palette
Working with activity and process entities

There are two report entities belonging to the process and activity report entity categories: process
execution and activity execution, and process events and activity events. These entities are used
when reporting on instance-level execution data. The Process Execution and Activity Execution
report entities are used when reporting on processes and activities that have completed. The Activity
Events entity enables users to report on activities and work queue data. The Process Events entity
is appropriate in cases where event and performer data is of interest. Performers are defined as
individuals that complete specific steps within a process.
Working with activity and process aggregation

entities
Aggregation entities are a special kind of BAM reporting entity that group process instance data into
specific time intervals. There are nine time intervals for both activities and processes. The time
intervals are 5 minutes, 15 minutes, 30 minutes, hourly, daily, weekly, monthly, quarterly, and yearly.
The incomplete execution entities have only three types of aggregation: 5 minutes, daily, and hourly.
Aggregated report entities provide two benefits. First, they provide report designers an easy way
to design aggregation reports. And second, overall system performance is enhanced. Instead of
aggregating instance level data while the report is running, aggregated execution data is stored in
special tables in BAM for fast retrieval. Querying this data is much faster than having BAM perform
these calculations. For more information on aggregation see Understanding the aggregation engine,
page 17.
42
Working with incomplete execution entities

The Incomplete Process Execution and Incomplete Activity Execution report entities are used to
report on processes and activities that have not yet completed. These processes are said to be in-flight
where Ongoing Duration can be monitored in seconds, minutes, hours, and days. These time values
are selected as entity fields. It is also possible to report on in-flight processes or activities by using
the process or activity execution reporting entity and defining an ongoing filter. Incomplete process
execution and three corresponding aggregation entities are available under the Process category.
Incomplete activity execution and three corresponding aggregation entities are available under the
Activity category.
Working with activity performer aggregation entities

BAM supports the monitoring of human activities, completed by performers. BAM captures the name
of each performer and their ID, both of which can be used in reports and alerts. Performer name and
performer ID can be selected as entity fields within each of the Activity Performer entities. All
performer entities are aggregated, which allows users to assess the performance of an individual over
specific time intervals. These time intervals are: 5 minutes, 15 minutes, 30 minutes, hourly, daily,
weekly, monthly, quarterly, and yearly. In addition to performer name, these entities allow users to
include activity names, the average duration it takes for a performer to complete the activity, and
whether the activity is completed or not (failed).
Working with queue entities

Process Builder and Process Engine supports queue management. Processes can be comprised of
activities and queues. A queue holds work items (activities) until they are claimed and completed by a
user. Sometimes it is necessary for a process to route work to specific performers. However, there
may be times when any number of performers can complete a specific activity. This is where queues
become useful. Instead of automatically routing work to a specific performer within a process, work
items are routed to a queue where they can be selected and completed by any number of performers.
Tasks are usually processed in a first in, first out order.
A queue is defined in TaskSpace and assigned as the performer of a manual activity. Each queue is
uniquely named and is characterized by thresholds (the maximum number of work items allowed in
the queue), users (a list of performers that can claim work items within the queue), and policies (rules
that govern how the queue operates). Queue work items are selected by performers for completion.
Work items can exist in a number of different states, called events:
Started the number of work items that have started
Completed the number of work items that have completed
Assigned the total number of assigned tasks in the queue (including suspended tasks)
Assigned (Suspended) the number of assigned tasks have been suspended
Unassigned the total number of unassigned tasks in the queue (including suspended tasks)
Unassigned (Suspended) the number of assigned tasks have been suspended
The Documentum TaskSpace Configuration Guide addresses queueing in greater detail.
43
In PRS there are two queue report entities: Work Queue and Work Queue Events. The Work Queue
report entity provides information on the queues themselves, including the name, the capacity (Policy
Task Count), the number of active users, works items assigned, and work items unassigned. The
Work Queue Events report entity provides a process context and includes the name of the activity
and performer, and information about the event.
Note: All work items in a queue are monitored, even if the process to which the work item belongs is
not monitored. If the process is not monitored, then you cannot report on the relationship between a
queue work item and its parent process.
Working with business data entities

Business data refers to any kind of information captured by fields on an electronic form as a process
executes. Business data consist of Structured Data Types (SDTs), package object types, and simple
process variables. Each of these structures is defined in Process Builder. All business data values can
be reported on with a special set of reporting entities that are created. All reporting entities discussed
until now are included with the BAM software. SDT and package report entities, on the other hand, are
created once they are defined and enabled for reporting in Process Builder. Enabling for reporting
also creates the corresponding execution tables in the BAM database. These tables store attribute
values that are populated as a process executes. For example, if a customer completes an online order
form, the actual values entered in the product name and quantity fields (there are many other fields,
too) are stored in the BAM database.
SDT and package report entities can be selected as the base entity in a report.
Note: A business data report entity must be the base entity in a report if you want to use any of
the attributes in a dashboard filter. For example, if you want a dashboard user to filter a report by
attribute values like Applicant Name, Funding Reason, or State, then you must select the business
data reporting entity first. To include process information you can then select Process Execution
or Activity Execution.
If it is not possible to use the business data reporting entity as the base entity of the report, then
you must create a custom filter. Understanding dashboard filters, page 208 describes how to create
custom business data filters.
Business data entities are also available as children of both the Activity Execution and Process
Execution report entities. Unlike other report entities, aggregated business data report entities are
not automatically provided. These must be configured within PRS. For more information on creating
aggregated business data report entities see Configuring business data aggregation, page 90. Once
created these aggregation entities are listed in the Business Data Aggregation category on the palette.
Simple process variables are handled differently than SDTs and package object types. While they must
be enabled for monitoring, there is only a single reporting entity called Process Variable that is listed
as a child of only the process execution entity. This reporting entity displays each process variable as
an entity field. Creating aggregated report entities for process variables is not supported.
Note: Although the name of business data entities can be greater than 25 characters in Process Builder,
the name of business data reporting entities in PRS is limited to 25 characters. This allows for other
entities to be added to the report without visually overlapping each other. The full name of a business
data report entity can be viewed by way of a tooltip.
44
CAUTION: SDT/package column names within the table of the BAM database can change
when moving an xCP application between Documentum environments. For example, from
Development to Testing, or from Testing to Production. If you have created custom filters on
SDT/package objects, you must adjust the filter definitions to match the new column names.
Working with alert entities

The alert entity category consists of the Alert report entity and the Alert History report entity. The
alert report entity allows users to report on new and unresolved alerts. Once resolved, an alert is moved
to an archive table in the BAM database. From this table users can generate reports using the alert
history report entity. Reports can include alert severity, status, date triggered, and date resolved.
Understanding data sources

Typically, reports are defined with more than one entity. The data source of a report starts with a parent
entity and then subsequent entities are added by selecting from the palette in PRS. Each entity added is
said to be related to the entity just to the left. The entities you choose and their relationships to other
entities are defined in the BAM software. When Work Queue is selected, the only child that can be
added is Work Queue Events. When Work Queue Events is selected the only children that can
added are Activity Execution and Process Execution. The Process Execution entity has its own set of
entities that are considered children, and so on with each reporting entity.
Reports that contain parent-child relationships contain all of the data from the parent entity, and
only the subset of data from the child entity that is related to the parent. For example, when Process
Execution is the parent and Activity Execution is the child, then for each Process Execution instance,
the report will show the related Activity Execution instances. If a certain process instance is not
included (perhaps because of a filter), then its related activity instances are also not included in the
report. From a technical perspective, parent-child relationships represent a left-outer join between
the parent and the child entity tables.
Note: The greater the amount of data each query returns, the greater report response time is negatively
impacted. Long response times are the result of the BAM report engine retrieving the full results set
into memory. It is your responsibility to determine whether the response time of a report is appropriate.
If your report returns a few thousand records and the response time is not acceptable, then you should
optimize your report by limiting the number of report entities. Installing the BAM server on a 64bit
machine also enhances report performance.
Other methods of optimizing reports include:
Configuring business data aggregation, page 90
Configuring custom aggregation, page 194
Creating custom report entities, page 199
Configuring PRS filter entities, page 217
45
Figure 6
Data source with multiple report entities
Understanding how data source results are

generated
Each report consists of a data source and a number of formatting options. The data source includes one
or more report entities. For data sources built with multiple entities, it is important to understand the
relationships between entities, and how data source result sets are produced. The data source figure
illustrates three entities, and two parent-child relationships: Process Execution/Activity Execution
and Activity Execution/Business Data entity. This section explains how data source queries are
executed against the BAM database and how result sets are produced.
Figure 7
Data source example
Each reporting entity is a database query. For example, the query for Process Execution query is:
Select * from V_EXEC_PROCESS_INSTANCE;
46
When a query is run against the BAM database, a result set is displayed in the Data Source Preview
window. Interpreting the result set for a report with only one entity is straightforward. More complex
reports contain multiple entities with their own individual queries run against the database. The final
data source represents a left outer join. The result of a left outer join for table A and B always contains
all records for table A (the left table), even if no matching records are found in table B (the right table).
If no records are found in table B, the join still returns a row in the result but with NULL in each
column from B. If the left table returns one row and the right table returns more than one matching
row, the values in the left table are repeated for each distinct row on the right table.
The data source architecture figure describes how parent and child result sets are joined to form a
single result set.
1. The select query for the parent entity of the report is run. The parent entity is the first entity in
the report.
2. The result set of the parent entity query is stored in memory; a set of parent entity IDs is stored
in a temporary table.
3. The select query for the child entity is run and joined with the temporary table; the result set
is stored in memory.
4. A final join between the parent and child result set is performed in memory.
Figure 8
Data source architecture
Working with entity fields and captions

Each report entity provides a view of a BAM database table. Each database table stores process
execution data in rows and columns. Entity fields represent columnar data that can be added to any
report. Once placed on the report canvas, the list of entity fields is displayed within the report entity. A
check mark for an entity field adds it to the data source. Each report entity has its own set of fields.
The caption of each entity field can be changed by using the caption editor.
Entity field names must be unique within a data source. For instance, if the Duration (hours)
field is selected for both the Process Execution and the Activity Execution report entities, then .AE
is automatically added to the duration (hours) field of Activity Execution. The suffix .AE is an
47
abbreviation of the report entity to which the field belongs in this case, Activity Execution. If three or
more duplicate fields are added, then a number is added to the second suffix. For example, Duration
(hours), Duration (hours).AE, and Duration (hours).AE1. For Process Execution, this suffix is .PE.
For more information on editing captions see Editing entity field captions, page 89.
Figure 9
Entity fields
Understanding data source filtering

A BAM database contains a great deal of process execution data. Without filtering, a report query
returns all results. The result set could be thousands and thousands of data rows. Usually, this amount
of data is not desired. Filtering reduces the results into a subset of data. Filtering is achieved by
defining constraints on one or more entities within a report. A filter consists of a filter expression
written by selecting filter entities and entering values. Filter entities and values are selected with a
series of filter tabs available within a Filter window, as shown in the PRS filter figure.
Figure 10
48
PRS filter window
A filter expression is divided into four distinct segments:

<Filter Tab Short Name>.<Filter Item Name><Operator><Value>
Filter Tab Short Name Each tab within the Filter window has a three character name that is
automatically added to the beginning of the filter expression. This three character name is the
filter category.
Filter Item Name Within each tab is a tree menu listing the filter entities.
Operator Users can select from a number of operators, including =, <, >, and Matches.
Note: Except for date type filters, equals (=) is the only operator available in dashboards by default.
Greater than (>) and less than (<) operators are supported, but must be created. Configuring
dashboard filters, page 209 provides an example of how to create a dashboard filter. A description of
how to create greater than (>) and less than (<) operators follows the example.
Value Values are selected from the tree menu or entered manually by the user.
Note: A single apostrophe () surrounds string values.
Compound expressions are written by adding AND, OR. The Query button is used to view the SQL.
If an error message appears then the filter expression is not valid.
Filter expression
The following filter expression constricts the data source to all process instances with the name
ProcessLoan that were completed during the last day:
PRO.Process-Name = LoanProcess AND MSC.Finished-During-Last-Day = True
Note: The operator can be entered by using the keyboard or selected from the keypad.
Understanding filter tabs

The filter tabs available for each report entity differ among entities. For instance, the work
queue entity and the process execution entity have different sets of filter options. The report
entity table summarizes the choices available. See Filtering report entities, page 76 for
step-by-step instructions. A subset of these filters is also available within dashboards.
Table 3
Report entity filters
Filter tab name
Used for
Applicable report entities
Standard (STD)
Defining filters based on a calendar, duration
All report entities
(if applicable), and performer data.

Automation (AUT)
Allows users to filter activities to include

only those that are either Manual or
Automatic.
Activity Execution
All Activity Aggregation
entities
All Activity Performer
Aggregation entities
49
Filter tab name
Used for
Processes and Activities
Allows users to create filters for specific
Activity Execution
(PRO and ACT)
processes and/activities.
All Activity Aggregation

entities
Process Execution
All Process Aggregation
entities
All Activity Performer
Aggregation entities
All business data report
entities
Miscellaneous (MSC)
Contains options for filtering based on

the status of an activity, its relative finish
date, and whether the activity or process is
Activity Execution
Process Execution
currently ongoing. Ongoing process are also

said to be in-flight.
Queue (QUE)
Allows users to filter queues by their name

and/or ID.
BAM-SDT (BSD)
Allows users to filter activity and process
Work Queue Events

Work Queue
Activity Execution
data by SDTs/packages.
Process Execution
Note: Business data filters are static
and not dynamic. As a result, only
All business data
business data fields are available as filter
reporting entities
entities (for example, Customer_Name),
rather than field values (for example,
Customer_Name=Robert Long). This
means that report designers must
manually enter field values between the
single quotes () of the filter expression.
Note: SDT/package column names
within the table of the BAM database can
change when moving an xCP application
between Documentum environments.
For example, from Development to
Testing, or from Testing to Production.
If you have created custom filters on
SDT/package objects, you must adjust
50
Filter tab name
Used for
the filter definitions to match the new
column names.
Alarm (ALM)
Allows report designers to create filters
Alerts
based on alert name, alert status, severity,

entity type, and entity name.
Understanding simple report types

Simple reports use a Flash component that renders data driven animated charts. A multistep wizard
helps create the report. The wizard is located in the center of the user interface. It holds four tabs (Data
Source, Chart Type, Chart Data, and Chart Properties) that represent each step in the report creation
process. Users navigate through the report wizard by clicking either Next/Back or by selecting a tab
(Chart Type, Chart Data, etc.) at the bottom of the editor. In Chart Type, users select the basic format
of the report. For example, a report can be represented as a pie chart or bar chart. Within the Chart
Data tab users label one or more data series. In the Chart Properties step, users can change the font, add
a legend to the report, and work with other advanced properties. All properties have default values that
can be changed. All configuration options are available in the Properties window located to the right
of the wizard. A Preview window is located below the wizard and displays the result of the data source.
The entity fields of a report are represented as columns. Making a column visible in a report and its
relative order in the report are specified in the Chart Data tab. Even though an entity is selected in
the data source, it can be hidden from the report by selecting No in the Visible field for a specific
column. Order is determined by specifying the column of data (the entity field) for Category (X-axis)
and one or more Value (Y-axis). Each chart type generates its report based on the order of the columns
and on the format of the data included in the report. This section describes the relationship between
chart data and chart types for each report type available.
Working with pie charts and bar charts

Pie and bar charts take data from the first and second columns in the report. These charts include a
category (X-axis) and a single value (Y-axis). Any column included in the data source can be selected
as either the category or value.
Note: For pie and bar charts, the value (Y-axis) must be numeric.
The process duration figure displays the duration in hours (value) for each process instance (category).
51
Figure 11
Process duration bar chart
Working with dial gauges

A dial gauge takes numeric data captured during process execution and represents this data as a single
value that lies in one of four zones. The single value represents either instance data, or aggregated
data. The four zones are green, blue, yellow, and red. Report designers configure zone ranges. The
following example calculates the average duration (in hours) it is taking for running processes to
complete. The data source for this report includes the Incomplete Process Execution entity and the
Ongoing Duration (hours) column.
Figure 12
Dial Gauge data source
Report aggregation is then used to calculate a singe duration value from multiple process instances.
Note: The result set displayed in the Data Source Preview window can only contain one row. If
multiple rows are returned, an error message is displayed. It is helpful to use filtering to reduce the
result set.
52
Figure 13
Dial Gauge aggregation
The average duration calculated falls within one of four zones. Zone ranges are configured in the
Chart Properties tab as follows:
Range-1: Extends from the Gauge Start value to the Range-1 End Value
Range-2: Extends from the End Value of Range-1 to the End Value of Range-2
The color of each range is intended to provide meaning to the dashboard user. In this example, an
average duration in the green zone means that processes are executing smoothly and more quickly
than anticipated. An average duration in the blue zone means that processes are executing in a normal
fashion, with little to no problems. An average duration in the yellow zone means caution and
indicates that problems exist with the running processes. An average duration in the red zone indicates
that executing processes are encountering substantial delays and require attention immediately. The
default colors can be changed by using the Color property within each range.
By default, there are four ranges represented in a dial gauge. A range is hidden by configuring the
End Value of two or more ranges to be the same value. For example, if the Range-2 End Value is the
same as the Range-3 End Value, then Range-3 is hidden. If the End Value of Range-1 and Range-2
are the same, then Range-2 is hidden from view. The following rules apply to all range values when
the Start Value is changed:
The Start Value cannot be less than 0.
If the Start Value is greater than the Range-1 End Value, the Range-1.End Value becomes equal to
the Start Value.
If the Start Value is greater than the Range-2 End Value, the Range-2 End Value becomes equal to
the Start Value.
If the Start Value is greater than the Range-3 End Value, the Range-3 End Value becomes equal to
the Start Value.
If the Start Value is greater than the Range-4 End Value, then all range End Values becomes
equal to the Start Value.
The following rules apply when the Range-1 End Value is changed:
If the Range-1 End Value is less than the Start Value, then the Start Value becomes equal to the
Range-1 End Value.
If the Range-1 End Value is greater than the Range-2 End Value, then the Range-2 End Value
becomes equal to the Range-1 End Value.
If the Range-1 End Value is greater than the Range-3 End Value, then the Range-2 and Range-3
End Values become equal to the Range-1 End Value.
53
If the Range-1 End Value is greater than the Range-4 End Value, then the Range-1, Range-2, and
Range-3 End Values become equal to the Range-1 End Value.
Figure 14
Process duration dial gauge
Working with bar and line charts

Bar + Line charts include a single category (X-axis) and multiple values (Y-axis), called Series.
Having multiple series allows users to include two or more dimensions of data with the same category
in a bar chart. Each series is configured in the Type field of the Chart Data tab as either a line or a bar.
Note: For bar with line charts, the series (Y-axis) must be numeric.
This figure displays a process duration report where duration is measured in both hours and seconds.
The hours series is represented as a bar. The seconds series is represented as a line.
54
Figure 15
Bar with line report
Working with table charts

Reports formatted as a Table are the simplest to generate. These reports contain one or more columns.
The data type of the column is not relevant in table charts. The order specified in the Chart Data tab
controls the order in which columns are displayed.
Table charts are not recommended when your report contains a large number of records. Table charts
consist of multiple pages, and all pages of the report are stored in the memory of your browser. This
compromises report performance. Instead, use Crystal Reports to design table charts containing a large
number of records. Crystal Reports stores only one page of the report in the memory of your browser
at a time, which decreases the demand on system resources.
Figure 16
Table charts
Understanding chart type properties

Each chart type has a number of properties that can be configured. This section lists the visual
properties available for each chart type.
55
Table 4
Chart types and properties
Chart type
Properties
Pie
Animation (Yes/No)
Background color
Color Palette
Font
Format Numbers (Yes/No)
Labels
Subtitle
Title
Values
Bar, Bar + Line
Animation (Yes/No)
Axes
Background color
Font
Format Numbers (Yes/No)
Labels
Legend
Show Grid Background (Yes/No)
SLA (used to specify a service level agreement value), shown as a
horizontal line
Subtitle
Title
Values
Gauge
Animation (Yes/No)
Background Color
Dial Lower Limit
Dial Upper Limit
Font
Ranges (includes color, max and min values)
Show Dial Value (Yes/No)
Subtitle
Title
Alternate Color
56
Chart type
Properties
Table
Chart Title
Font
Header
Understanding reports that use aggregation

Process Reporting Services supports the notion of aggregation. Aggregation allows summary level
reports to be designed, rather than reports that contain only instance data. In the report aggregation
figure, both the name of the process and its duration are displayed in the report. In fact, the Data
Source Preview window shows a duration value for each instance of a process. The Simple Process,
for example, has had two instances run; one that took 144 seconds and the other took 173 seconds.
Figure 17
Report aggregation
Aggregation allows report designers to calculate an average duration for each process. Aggregation is
based on two principles: function and group-by. There are five basic arithmetic functions available:
sum, count, average, max, and min. Aggregation requires each field in the data source to have a
function according to the following rules:
1. Date fields only have Max and Min available, with Max as the default.
2. String fields only have Count available, which is also the default.
3. Numeric fields have all five functions available, with Count as the default.
First, the data source of the report must be defined. Fields within the data source can then be
aggregated. Once aggregation is defined, a field can still be added to the data source. When a field is
added to the aggregation, it is assigned the default aggregation based on its field type.
The other principle of aggregation is grouping. Any field in the data source can be selected as a
Group. Grouping indicates the data source field over which the function applies. There must be at
least one group-by field selected. More than one group-by field can be selected. A group-by field
cannot be assigned a function.
57
In the aggregation figure, process is selected as the group field. Together with the sum function, this
report calculates the average duration (in seconds) for each process. Bear in mind, each process
contains multiple process instances. Grouping takes individual process instances and collapses them
so there is one row for each unique group-by field. Grouping makes the most sense when used on
process name and ID and performer name and ID.
Figure 18
Aggregation function and group-by
When your aggregation settings are in place, you can refresh the Data Source Preview to see the
aggregated data. From here, the rest of the report can be designed, including selecting a chart type
and configuring chart data.
The same principles apply to reports that contain business data (SDTs or package object types) where
business data fields can be aggregated. For example, a report can be designed to calculate the total
amount of purchase orders (by using the SUM function on the field amount) for each state (where the
field state is specified as the group).
Aggregating report data, page 70 contains the report aggregation step-by-step procedure.
CAUTION: Report aggregation is an excellent approach to use when prototype dashboard
reports are being designed and tested. It provides flexibility to test different designs, and
compare the report output with desired results. Report aggregation is also a viable approach
in a production environment that has limited process execution data. If high volumes of data
are anticipated then server aggregation (including business data aggregation) and custom
aggregation should be used.
Note: For BAM installed on a 32-bit machines, reports that consist of 20,000 records is considered
high volume.For BAM installed on 64-bit machines, reports that consist of 100,000 records is
considered high volume.
Note: Computed columns can be used to perform calculations on aggregated data. You cannot
aggregate computed columns. Computed columns do not appear in the Report Aggregation dialog box.
Understanding server aggregation

Aggregating large amounts of instance data is taxing the BAM and negatively affects system
performance. To improve system performance, use aggregation reporting entities. As described in
Understanding the aggregation engine, page 17, every 5 minutes the aggregation engine runs a job that
automatically aggregates process instance data . The data is stored in special aggregation tables within
the BAM database. Because the aggregation job is automatic and scheduled, it is considered server
58
aggregation. There are nine aggregation tables each for process, activity, and performer entities that
group instance level data into nine time periods (5 Minutes, 15 Minutes, etc.).
5 Minute process aggregation

Three process instances are started between 1:00 1:05 PM. The first one completed in 2
minutes, the second completed in 10 minutes, and the third completed in 9 minutes. The
average duration is (2+10+9)/3 = 7 minutes. The following information would therefore be
inserted into the 5-minute aggregation table:
Table 5
5 Minute Aggregation
Process Start Interval
Average Process Duration
1:00 1:05
1:05 1:10
23
1:10 1:15
15
Understanding aggregation calculations

The 5-minute aggregation continues to be updated every 5 minutes. Each of the other eight aggregation
tables are derived from the 5-minute aggregation data. The 15 Minute aggregation table holds data that
calculates average duration based on the 5-minute data rather basing this calculation on the instance
data. That is, the 15-minute aggregation job aggregates 5-minute data, and not instance level data. The
30-minute aggregation performs calculations on the 15-minute tables. The hourly aggregation data is
calculated from the 30-minute data. The daily aggregation data is calculated from the hourly data.
This pattern continues for each of the nine aggregation intervals.
This method of aggregation is important because reports display results only after the aggregation
time period is over. For example, reports that use the Process Execution Monthly entity do not display
results until a month has passed.
There is process, activity, and activity performer aggregation entities. Each report entity contains
fields. The Process Execution 5 Minutes entity includes the following fields:
Average Duration (milliseconds) calculates the average process duration in milliseconds.
Average Duration (seconds) calculates the average process duration in seconds.
Count of Completed Instances the number of process instances that completed within the time period.
Count of Failed Instances the number of process instances that failed within the time period.
Count of Ongoing Instances the number of process instances that were currently ongoing within
the time period.
Count of Started Instances the number of process instances that started within the time period.
Finished Date and Time the end of the aggregation time period, for example, April 22, 2010 12:10.
Maximum Duration (milliseconds) the duration of the process instance within the time period
that took the most time to complete.
Minimum Duration (milliseconds) the duration of the process instance within the time period
that took the least time to complete.
59
Process the name of the process provides a context for all calculations.
Process ID the process ID provides a context for all calculations.
Start Date and Time the beginning of the aggregation time period, for example, April 22, 2010 12:05.
Version Number the version number of the process.
There is a great deal of overlap in the fields available for each report entity. For example, the Process
Execution Monthly report entity has the same fields as Process Execution 5 Minutes. In addition, the
only difference between the activity and performer entities is that activity aggregation entities contain
fields like Activity and Activity ID, rather than Process and Process ID, or Performer Name and
Performer ID. All of the average, count, max, and min calculations are the same for all entities.
Reporting with aggregated data enhances system performance because the aggregation calculations
have already been made. To develop a report that displays process trends, a report designer uses the
Process Execution 30 Minute report entity. This aggregate report runs against no more than 48 rows,
since there are 48 half hour segments in a day. However, if the user had created a report that included
instances, the report could run against hundreds or even thousands of rows.
Understanding business data aggregation

Aggregation entities can be made available for business data entities. In some cases, processes capture
much business data while running. For this reason, aggregation tables and report entities are not
automatically created for SDTs and package object types. If business data aggregation entities were
created automatically, the BAM database would quickly become full of data. Instead, BAM provides
the tools for report designers to create their own aggregations. Once configured, nine business data
reporting entities are created beginning with the 5-minutes entity and continuing on to the Yearly entity.
Configuring business data aggregation is based on the same principles as report aggregation.
Business data aggregation

In this example, nine loan origination processes started within a seven-minute interval. For
each process, the value of the loan amount and the state are captured. The following table
represents how this instance data is stored in the database tables.
Table 6
Time
Loan Amount
State
1:00
200,000
NY
1:01
300,000
NJ
1:02
250,000
NY
1:02
100,000
NJ
1:04
300,000
NY
1:05
250,000
NJ
1:06
200,000
NY
60
Time
Loan Amount
State
1:07
300,000
NJ
1:07
250,000
NY
Understanding business data aggregation calculations

Report aggregation calculates the total loan amount for each state. At first, the report as designed
worked well, but as time went on, BAM performance began to suffer. So, business data aggregation
entities were created and used. In the Business Data Aggregation window report designer selects
function and group-by fields.
Figure 19
The following table illustrates how BAM aggregates the data. For each five-minute interval, the
total loan amount is calculated for each state.
Table 7
Business data aggregation calculations
Time Interval
Total Loan Amount
State
1:00 1:05
750,000
NY
1:00 1:05
650,000
NJ
1:05 1:10
450,000
NY
1:05 1:10
300,000
NJ
This operation creates each of nine aggregation entities that include each of the selected fields, plus:
Activity ID this field provides a context for the business data.
Finished Date and Time the end of the aggregation time period, for example, April 22, 2010 12:10.
Instances count a count of processes instances for the time period.
Start Date and Time the beginning of the aggregation time period, for example, April 22, 2010 12:05.
Configuring business data aggregation, page 90 provides a step-by-step procedure.
Understanding single drill-down reports

A BAM dashboard supports two varieties of drill-down reports: single drill-down reports and
multi-drill-down reports. Single drill-down reports are defined when a base report is linked with
another published report, called a target. Once configured, single drill-down reports allow dashboard
61
users to select a hyperlink. Selecting a hyperlink changes the content of the base report to display
the content of the target report. In addition, a trail of bread crumbs is displayed within the dashlet
allowing users to navigate to the original, base report. Target reports can also serve as a base report for
another target. There is no limit to the number of drill-down layers used. Single drill-down reports
can also open a URL in a new browser window. The URL must be absolute and specify the location
of a web page in full. For example: http://www.siteaddress.com.
Single drill-down reports are fully configured in PRS. Report designer can select to have the hyperlink
open a report, or a URL. The hyperlink within the base report corresponds to the data source of a
report, and in particular X-axis and Y-axes data. For instance, if a table report contains five columns,
then drill-downs can be configured for each column. A hand icon is displayed when the dashboard
user scrolls over a hyperlink. Configuring single drill-down reports, page 84 addresses how to
configure a single drill-down report.
A filter expression can also be defined once a target report is selected. The filter expression is applied
to the first entity in the report.
Note: Drill-down reports are not available for gauge reports.
Single drill-down: base report

In this example, a report that includes information about executing processes is used as a base report
that is linked to an activity report. The drill-down relationship is defined for the Process Instance ID
column which appears as a hyperlink to dashboard users. Once selected, the contents of the dashlet
are populated with the activity report. The activity report displays only the activities for the selected
process instance. This drill-down capability is achieved by defining a dynamic filter expression.
Figure 20
Base report in a single drill-down report
Single drill-down: target report

Once a drill-down report is invoked, a trail of bread crumbs is displayed above the target report.
The trail of bread crumbs allows dashboard users to navigate back to the original, base report.
62
Figure 21
Target report in a single drill-down report
Understanding the importance of filtering

Filtering is an important topic, especially when it comes to defining single drill-down reports. Most of
the time the purpose of a single drill-down report is to navigate from level of information to more
detailed information. If a filter is not defined in the example discussed, the dashboard user sees all
activities for every process instance instead of just the activities for the selected process instance. In
this example, a dynamic filter expression has been defined. A dynamic filter expression means that
the actual filter value is not fixed (static). Rather, the BAM system uses a value based on the actions
of the dashboard user.
Dynamic filter for single drill-down report

Continuing with the example, a dynamic filter expression has been defined by clicking the Filter
button in the Drilldown window in PRS. Any field included in the data source can be used in the
filter expression. Dynamic filter values are selected by pressing Ctrl and spacebar on the keyboard,
and then double-clicking the value.
Figure 22
Dynamic filter expression
Understanding multi-drill-down reports

Like single drill-down reports, multi-drill-down reports are defined by linking a base report with
other reports. Unlike single drill-down reports however, invoking a multi-drill-down report updates
the reports displayed in surrounding dashlets rather than the contents of the base report. Configuring
multi-drill-down reports in PRS, page 86 addresses how to configure a multi-drill-down report.
Configuration involves both PRS and a dashboard.
Multi-drill-down report
Process Instance List is the base report in this example. Its data source consists of the
following fields: Start Date and Time, Finished Date and Time, Process, Process
Instance ID, Version Number, and Duration. The process column in this table is used in a
multi-drill-down report. When a user clicks a specific loan from within the table, the Process
Details, Process Duration, and Process Diagram dashlets are updated with information about
the selected process instance.
63
Figure 23
Multi-drill-down report in a dashboard
Logging in to Process Reporting Services

This section includes the procedure for logging in to Process Reporting Services. Report designers
must be assigned the ts_designer role in the Documentum repository. When you first log in, the
following message may be displayed in the Report Information Update dialog box:
This message means that the BAM server is in the process of updating data in the BAM database,
during which time reports cannot be run. This synchronization operation takes more time to complete
when the BAM server is first started. The Report Information Update dialog box automatically
closes when the synchronization is complete. You can also click Close & Exit to close the Report
Information Update and PRS Login windows.
Note: The synchronization operation continues even if these windows are closed.
Note: PRS requires that Flash Player version 9 or higher is installed on the user machine. If Flash
Player is not installed, the user is prompted to install it. Once installed, the user must restart PRS.
To log in to Process Reporting Services:
1. Double-click PRS.exe. The location of the program depends on your particular installation of
Process Reporting Services.
64
A Login window appears.

2. Select a repository from the pull-down list.
3. Enter a user name and password.
4. Click Ok.
Note: If no repositories are listed it means that:
the repository is not visible to the BAM server, or
the URL connecting the BAM server to the docbase is not configured properly
5. To configure the URL click the Connect button and enter the URL. The address should be
provided to you by your administrator.
6. Once the host URL is entered, click Ok. PRS validates the URL and returns the report designer to
the login window of the server where the user name and password are entered.
Navigating Process Reporting Services

The user interface of Process Reporting Services is divided into the following sections:
Reports and Alerts Manager The reports and alerts manager displays a folder tree view of report
or alert categories. Categories contain individual reports and alerts. Reports and alerts must be
saved within a category. Simple reports and Crystal Reports have different icons. Data sources
are displayed beneath each report.
Palette Reports and alerts are defined by selecting entities from the palette and placing them on
the design canvas to the right.
Design canvas Reports and alerts are designed on the canvas, located to the right of the palette.
Entities expand to display entity fields. The relationship between entities is displayed with an arrow.
Outline Outline provides a high-level overview of a data source. If the data source contains many
entities, click and drag within the outline image to navigate.
Data Source Preview After a data source is saved users can click the refresh button to view
the results.
Properties There are four steps to creating a simple report: defining a data source, selecting a
chart type, formatting chart data, and selecting chart properties. The Properties tab presents users
with all available configuration options available for each step. This tab is also used to display
general information, such as the object ID of the report or category.
Creating a report category

Report categories hold reports or other report categories. PRS is shipped with a report category called
Preconfigured Dashboard located under the Report Categories folder. This category holds all
report definitions used in each preconfigured dashboard. For more information on the preconfigured
65
dashboard see Working with Preconfigured Dashboards, page 165. Report categories can be added to
either folder.
To create a report category:
1. Log in to PRS.
2. Select the Reports tab.
3. To add a report category to the root, select Report Categories.
4. To add a report category anywhere else, select the appropriate report category.
Note: A report category can only be added to another report category.
5. Select File > New > Category.
Users can also select New > Category from the report category right-click pop-up menu.
6. To select a Parent Category click the Browse.... The default parent category was selected
in Step 4.
7. Enter a category name. The name must be unique within a parent category.
8. Click Finish.
Designing a simple report

A simple report is created in four steps. First, a data source is defined. Then a chart type is selected
and data formatted. Finally, additional report properties are configured. Once a chart type is selected,
the design canvas graphically displays the report. As each configuration option is updated, the report
is updated. It is important for you to understand the relationship between chart types and chart data
configuration. This topic is addressed in Understanding simple report types, page 51. In addition, it is
important for you to understand chart properties. This topic is addressed in Understanding chart type
properties, page 55.
To design a simple report:
1. Log in to PRS.
3. Select a report category.
4. From the File menu select New > Simple Report.
5. To select a different parent category click Browse.
6. Enter a report name. The name must be unique within a category.
CAUTION: Report names must be less than 150 characters.
7. Click Finish. An empty data source is created as a child of the report. In addition, a simple
report icon appears next to the report name.
66
8. Within the data source builder select a report entity from the palette and then click once on the
design canvas. Or, you can drag and drop entities. The entity and all entity fields are displayed. For
more information on report entities, see Understanding report entities and data sources, page 41.
Note: Once the report entity is added to the drawing area, the palette changes to include only those
entities that are children of the added entity.
9. Place a check mark next to each entity field you want to add to the data source. The entity field is
added as a column in the data source preview. For more information on entity fields and captions,
see Working with entity fields and captions, page 47 and Editing entity field captions, page 89.
Note: Entity field names must be unique within a data source.
10. From the palette, click, and drag a child entity and place it anywhere in the drawing area. An arrow
is automatically drawn between the parent entity and the child entity.
11. Continue adding report entities and selecting entity fields as required.
12. Click the Refresh button to preview the data source.
Note: Report designers can limit the number of rows displayed in the preview by selecting the
Limit Rows checkbox and entering a value
67
13. Click either Next or the Chart Type tab located at the bottom of the report design canvas.
14. Select a chart type in the Properties window.
15. Click either Next or the Chart Data tab.
16. Configure the chart data within the Properties window. For more information about chart types
and chart data options, see Understanding simple report types, page 51.
17. Click either Next or the Chart Properties tab.

18. Configure the chart properties in the Properties window. For more information regarding chart
visual properties, see Understanding chart type properties, page 55.
19. From the File menu select Save.
Sorting report columns

Reports can be sorted by a single column. Sorting is supported in all report types except for gauge
reports. The sort feature allows users to select a single sort column and a direction, both of which are
configured in the Chart Data tab. Any selected data source field can be used as the sort column. The
data within a column can be sorted in either ascending or descending order.
To sort report columns:
1. Define the data source of the report and select the Chart Data tab.
2. Expand the Sort property.
3. Select a sort Column.
4. Select a sort Direction.
5. Click the Refresh button in the Data Source Preview window.
68
Modifying bar chart labels

Bar chart labels can be constrained to a specific number of characters. The Labels > Limit Characters
property allows users to select how many characters of the label are displayed (up to 29). A limit of
0 displays all characters. The Direction property indicates whether the beginning of the label is
truncated or the end of the label truncated. For example, if the process name is Process Sales Order
and the label limit is 8, then es Order appears when left is selected as the direction, and Process
appears when right is selected as the direction.
To modify the length of bar chart labels:
1. Create a Bar or Bar+Line chart.
2. Select the Chart Properties tab.
3. Open the Labels property.
4. Open the Limit Characters property.
5. Enter a label limit.
6. Select a direction.
7. Click the Refresh button in the Data Source Preview window.
Choosing bar and pie chart colors

Report designers can choose the color of each bar in a bar chart and each slice in a pie chart. The color
of only the first ten bars or slices can be changed.
To choose bar and pie chart colors:
1. Design either a bar chart or a pie chart.
2. Click the Chart Properties tab.
3. Click the browse button to the right of the color palette field.
The Color Palette dialog box opens.
4. Each bar or slice has a corresponding color. Select the desired color from the drop-down list.
5. Click Ok in the Color Palette window. The new color is automatically applied to the bar or
pie chart.
69
Aggregating report data

Report aggregation provides summary level reports and is configured by using the fields included in
the data source. Aggregation involves selecting a function for one or more fields, and selecting a
group-by field. There are five basic arithmetic functions available: sum, count, average, max, and min.
The field type determines the arithmetic functions available. For example, for date fields only the Max
and Min functions can be selected. Grouping indicates the data source field over which the function
applies. At least one group-by field must be selected. Understanding reports that use aggregation, page
57 describes report aggregation in more detail.
To aggregate report data:
1. Define the data source of a report.
Note: Aggregation requires the report to be open and selected on the tree menu.
2. Click the Report Aggregation button
The Aggregation window opens and all selected fields are displayed for each report entity.
Note: Each field has a default function selected. The default function can be changed. In addition,
a default group-by field is also selected.
3. Select the appropriate aggregation function for each field.
4. Select the group-by field.
5. Click Ok. The Aggregation window closes and you are brought back to the data source editor.
70
Note: The group-by field and the aggregation function are marked next to the field for each report
entity. Scrolling over the aggregation displays its type.
Note: Aggregation applies to the data displayed in the Data Source Preview window. Click the
Data Source Preview window. Click the Refresh button to see the aggregated data.
Note: If a new field is selected, the default aggregation is automatically applied based on its field
type. In addition, you must have at least one group-by field. Additional group-by fields can be
removed from the data source.
6. Save the report.
Removing report aggregation

Report aggregation is removed in the Aggregation window. Once removed, data source fields no
longer have arithmetic functions applied to them.
To remove report aggregation:
71
1. Open the report and make sure that it is selected on the tree menu.
2. Click the Report Aggregation button
The Aggregation window appears.

3. Click Remove Aggregation.
4. Click Ok. You are brought back to the Data Source Preview window. The aggregation icons
have been removed from the report entities.
5. Save the report.
6. Click the Refresh button in the Data Source Preview window to update the preview.
Understanding reports that include computed

columns
BAM supports computed columns. As a data source is defined, users can create additional fields that
represent a function of one or more fields. The most obvious example of a computed column takes field
values and either adds, subtracts, multiplies, or divides it by a constant value. For example, a computed
column expression can be defined that takes duration (minutes) and converts it to duration (hours):
${Duration (minutes)}/60
In another example, Field1 and Field2 are added. The computed column expression is:
${Field1} + ${Field2}
The syntax of the function is a JEP expression where fields in the data source are referred to by their
name delimited by ${}. Users can access help with writing JEP expressions by clicking the Help icon.
The primary purpose of a computed field is formatting. Formatting means that the user has control over
the contents of the new column. The following example does not involve a computation. BAM reports
can include performer name. However, the name of a performer is its technical name (for example,
acct_processor) rather a business-oriented name (for example, Account Processor). The computed
columns feature allows you to take all instances of acct_processor, and rename it to be Account
Processor. The following logical if...else expression:
Takes all instances of the aa performer name and changes them to Account Processor.
Takes all instances of the sales_processor performer name and changes them to Sales Processor.
Takes all other performer names and changes them to Other Processor.
if (${Performer Name}=="aa", "Account Processor",
(if (${Performer Name}=="sales_processor",
"Sales Processor", "Other Processor")))
The figure depicts the Data Source Preview window after it is refreshed.
72
Figure 24
Computed columns
Other uses of computed columns

Computed columns can also be used to format date fields, comparing one value to another,
and appending a suffix to a certain field.
Table 8
Uses of computed columns
Use
Syntax
Description
Format date fields as MM/dd/yy
formatDate(${Start
Date and Time},
"MM/dd/yy")
All start date and times are converted to the

MM/dd/yy format. Example: Apr 22, 2010
9:05 AM is formatted as 04/22/10.
Format date fields as Mon, Tue,

Wed, etc.
formatDate(${dateField}, Converts dates to days of the week. Varying

the number of Es provides either a short or
"EEE")
longer representation (for example, W, Wed,
or Wednesday).
Compare one value to another
if (${cost} >
55, "Approved",
"Rejected")
In this example, if a value in the cost column

exceeds 55, then display the word Approved.
Otherwise, display Rejected.
Append a suffix to values
str(${Duration
(seconds)} * 60) "
minutes"
In this example a new column is created that

both converts duration into minutes, and adds
the word minutes to the right of the value
(example, 43 minutes).
Designing reports with computed columns

The name of the computed column must be unique within the data source. The system validates
computed column expressions. If an expression is not valid, the Ok button remains grayed out. Only
one computed column can be created at a time. Once added to the canvas, the Computed Columns
entity is added to the data source, but does not have relationships with other entities. In addition, no
child entities are available on the palette.
Note: Computed columns can be used to perform calculations on aggregated data. You cannot,
however, aggregate computed columns. As a result, computed column fields do not appear in the
Report Aggregation dialog box.
Note: You cannot divide by zero. An error is displayed in PRS.
To generate a report with computed columns:
1. Define a data source, adding entities and entity fields.
2. Click the Add Computed Column button. The Computed Column dialog opens.
73
3. Enter a name for the computed column. The name must be unique within the data source.
4. Enter a computed column expression:
a. Place your cursor in the Expression field.

b. Press the Ctrl key and the spacebar on your keyboard simultaneously. A list of fields that
can be used in the expressed is displayed.
c. Double-click the first field used in the expression.

d. Use the keypad to select a JEP operator or enter an operator manually (for example, *, /, +,
and - are supported).
e. Enter a value after the operator.

f. Click Ok.
Note: The system automatically validates the expression. If an expression is not valid, the
Ok button is grayed out.
Notice that the computed column report entity has been added to the report design. In addition,
the computed column has been added to the Data Source Preview window. Click the Refresh
button in the Data Source Preview window.
74
Adding a computed column

Computed columns are made visible in the data source by deselecting (or selecting) the check box to
the left of the column.
To add a computed column:
1. Select the computed column entity. The entity title turns orange.
2. Click the Add Computed Columns button. The Computed Columns dialog box opens where
you can define a new computed column.
Editing or deleting a computed column

Computed columns can be edited or deleted. When Edit is selected from the right-click menu, the
Computed Columns dialog opens and changes can be made to the column name and expression.
Computed columns can be deleted in three ways: removing the Computed Columns entity from the
canvas (this approach deletes all computed columns in one step), through the right-click menu (outlined
in this procedure), or by removing any entity field in the data source is used in a computed column
expression. When entity fields are removed, the user is shown a list of the columns that are also deleted.
To edit or delete a computed column:
1. Select the Computed Column entity. The entity title turns orange.
2. Right-click the column you want to edit or delete and then select Edit or Delete.
75
Note: All computed columns can be deleted from a data source by right-clicking the computed
columns entity, selecting Delete, and pressing Yes on the confirmation dialog box.
Previewing a data source

Previewing a data source is a step in creating both a simple report or a Crystal Report. Previewing a
data source is useful in determining if there is execution data in the BAM database. All report entity
filters are applied to the data source preview. Report designers can enter the number of rows to preview
by entering a value in the Limit Rows field. Alternatively, all rows are returned when the Limit Rows
checkbox is deselected.
To preview a data source:
1. Build a data source with entities and entity fields.
2. Click the Refresh button.
You can choose the number of rows returned by entering a value in
The first 100 rows of report data are displayed.
Filtering report entities

Filter expressions are written by navigating a series of filter tabs, selecting a filter entity and entering a
filter value. Each report entity has its own set of filters. For more information regarding filtering, see
Understanding data source filtering, page 48.
To filter a report entity:
1. Right-click a report entity and select Filter.
2. Select the appropriate filter tab. Each tab contains a number of filter values.
3. Navigate the tree and double-click a filter value. The value is added to the Filter Expression field.
Note: The default operator is an equal sign (=). You can change operator manually by removing
the equal sign in the expression, and then choosing a new operator from the keypad.
4. To define a compound filter expression, click either the And or Or button and continuing adding
values.
5. Click Ok when you have completed defining the filter.
76
Working with report security

Providing security for BAM dashboard reports is important in BAM production environments. In BAM
production environments, there is no single type of user that consumes BAM run time reports. BAM
reports provide line of business and executive level personnel with different views of the same process
data. In addition, many reports contain sensitive data meant for only a small subset of dashboard users.
Therefore, strategies for securing reports should be considered. For Content Server, access control lists
(ACLs) are the mechanism by which users are assigned permission to access Content Server objects.
ACLs are also known as permission sets. Because Content Server and BAM are separate repositories,
ACLs do not translate to BAM dashboard reports. Report security is achieved with a combination of
techniques available in TaskSpace and PRS. The purpose of this section is to describe how to:
1. Limit report access to users in a role.
2. Filter the results displayed in a report based on user and group permissions.
Limiting report access to users in a role

Each BAM dashboard is represented as a tab in TaskSpace. TaskSpace tabs are assigned
to roles, and roles are assigned to one or more TaskSpace users. Dashboard tabs must be
assigned to roles in order for users to view reports. When reports are added to a dashboard,
only the users that belong to the role are able to see the reports. Adding a dashboard tab, page
151 and Assigning dashboard tabs to roles, page 151 provide detailed instructions.
77
Role-based security
In this example, the mail_processor role is assigned access to the ProcessMonitor tab, which
contains the Process Monitor dashboard. All users assigned the mail_processor role have
access to the reports displayed in the Process Monitor dashboard (second figure).
Figure 25
Assigning dashboard tab to a role
Once logged in, each user with the mail_processor role can select the Process Monitor
dashboard tab. Role-based security in TaskSpace is used to restrict one or more reports to
groups of individuals. In the most restrictive case, this approach is used to limit access to a
single report to a single user. This case involves:
1. Designing a dashboard that contains only one report.
2. Assigning the dashboard tab to a role that consists of only one user.
Figure 26
78
Role-based access to dashboards
Limiting report results by user and group permissions

Another type of report security uses filtering in PRS to limit the report results displayed by a user or
group. Users are individuals; groups are sets of individuals or groups. User and group data is used to
filter reports during runtime. This type of security is appropriate when you want multiple users access to
a report, while needing to filter out inappropriate data from being seen. In PRS, a filter variable is used
to limit the data displayed in dashboard reports to the data owned by specific dashboard users. Filter
variables are not the hard-coded values typical of most filter expressions. Instead, they are resolved
during runtime, when the variable value replaced with the actual value of the user and the group of the
user. Filter variables work with any report where the user name or default group is captured.
The names of the filter variables are @user@ and @default-group@. Filter variables work
as follows:
1. User name and default group data must be captured while a process is running. This data can
be captured in:
a package attribute or SDT (the label of these attributes does not matter)
a performer name
a custom reporting entity that has user name as one of its fields
2. The objects that capture user name and default group data must be monitored at the beginning
of the process.
3. An apostrophe and @ symbol must surround the user and default group variables in the filter
expression.
Figure 27
Filter expression with filter variable
Assigning ACLs to dynamic custom filters

Filtering provides dashboard users a way of easily analyzing report data. Dashboard filters consist of
filter items and filter values. The values available to dashboard users are derived either dynamically, or
are static. Dynamic filters use queries run against Content Server to display filter values to dashboard
79
users. Static filter values are not returned by a query, but are specified explicitly when the static filter is
created. The primary difference between these filter types is that dynamic filters have corresponding
object types in Content Server. Once created, ACLs are assigned to the object type from which the
dynamic filter is derived. Dynamic filters that use ACLs must be configured as a mandatory filter, so
that users are automatically presented with a limited set of filter values from which to choose. Users
without the appropriate permissions are also prompted to select a filter, but the list of filter values is
empty and the report does not run. Users without permissions are able to cancel the report. Creating
dynamic and static filters, page 223 provides information on designing custom dashboard filters.
Designing a Crystal Report

Process Reporting Services works with Business Objects Crystal Reports 2008 application to generate
advanced reports. A data source can be exported from PRS to Crystal Reports where a user can
format it. The external Crystal Reports application automatically starts. If it is not installed on the
local machine of the user, then an error message appears. Once the formatting is complete the report
is imported back into PRS (there is a synchronization function) where it can be published to the
dashboard.
Note: The synchronization function assumes that the report is imported from the same directory to
which it was exported.
Specific Crystal Reports procedures are not in scope for this documentation. Please refer to the Crystal
Reports user guide for specific procedures.
Note: Advanced search within a Crystal Report displayed in a dashboard is not supported. Only
reporting features supported by Crystal Reports Java Runtime Component version 2008 are available
in BAM.
CAUTION: Reports with thousands of rows of data that are aggregated in Crystal Reports
(rather than PRS) lead to high CPU usage in TaskSpace when viewed in a dashboard. High CPU
usage leads to slow response times. As a work-around, it is recommended that the data source be
aggregated in PRS first, and then formatted in Crystal Reports.
To design a Crystal Report:
1. Log in to PRS.
3. Select a report category.
4. From the File menu select New > Crystal Report.
5. To select a different parent category click Browse.
6. Enter a report name. The name must be unique within a category.
Note: Report names must be less than 150 characters.
7. Click Finish. An empty data source is created as a child of the report. In addition, a Crystal
Report icon appears next to the report name.
80
8. Within the data source builder select a report entity from the palette and then click once on the
design canvas. Or, you can drag and drop entities. The entity and all entity fields are displayed. For
more information on report entities, see Understanding report entities and data sources, page 41.
Note: Once the report entity is added to the drawing area, the palette changes to include only those
entities that are children of the added entity.
9. Place a check mark next to each entity field you want to add to the data source. The entity field is
added as a column in the data source preview. For more information on entity fields and captions,
see Working with entity fields and captions, page 47 and Editing entity field captions, page 89.
10. To add a child entity, click, and drag a report entity from the palette and place it anywhere in the
drawing area. An arrow is automatically drawn between the parent entity and the child entity.
11. Continue adding report entities and selecting entity fields as required.
12. Click the Refresh button located in the Preview Data Source window.
Note: Report designers can limit the number of rows displayed in the preview by selecting the
Limit Rows checkbox and entering a value
13. Click the
button. The Crystal Reports editor automatically opens.
14. Format the report with Crystal Reports Designer.

15. From within Crystal Reports, save the report using the Save function.
Note: Do not use Save As.... The report must be saved to the same directory in which it was
created.
16. Within PRS, right-click the report in the Reports tab and select Synchronize. The updated report
is brought back into PRS.
81
17. Click the View tab to preview the report.
The report can now be published to the BAM dashboard.

CAUTION: Data cannot be refreshed from PRS into Crystal Reports by using the refresh menu
option in Crystal Reports.
Editing Crystal Reports

The data source for a Crystal Report can be edited in PRS after the Crystal Report file is created and
formatted. After report entities, fields, or computed columns are added to the data source, report
designers are prompted with a message guiding them to:
1. Add the fields manually in the Crystal Reports Designer.
2. Close the report in the Crystal Report Designer.
3. Open PRS and synchronize the report definition with Crystal Reports. Synchronization is addressed
in Designing a Crystal Report, page 80.
Report designers are promoted with a message whenever the following edits are made to a Crystal
Report data source:
remove a report entity
remove a field
remove a computed column
edit a computed column
edit a field caption using the Caption Editor
CAUTION: Report captions cannot be changed once a Crystal Report is synchronized into PRS.
Note: Editing a Crystal Report also includes renaming it in PRS. Do not synchronize the report if it is
renamed. The format of the report may be damaged when the report is renamed and then synchronized
again. To restore a damaged report you must give it the original name and then synchronize. In
general, synchronize the report only after it was edited in Crystal Reports Designer.
Understanding when to use Simple reports and

Crystal Reports
There are two approaches to designing BAM dashboard reports: simple reports and Crystal Reports.
Simple reports are designed exclusively in PRS while Crystal Reports are designed first in PRS, and
then opened in the Crystal Report software where report design continues. The decision to use one
approach over the other is made based on the following considerations:
1. Dashboard design. Use Simple Reports when your dashboard contains multiple dashlets.
2. Ease of design. Simple Reports are easier to design than Crystal Reports. Simple drill-down reports
are easier to configure than Crystal Reports drill-down reports.
3. Amount of data in your grid report. If you implement large grid reports with greater than 1,000
records, use Crystal Reports to improve performance. Use simple reports for smaller grid reports.
82
4. Report formatting. While simple reports offer some formatting options, Crystal Reports offers
more, including the use of report headers, watermarks, a greater selection of chart types, and a
richer syntax for writing computed column formulas. If you require a high degree of control over
the look and feel of a report, then Crystal Reports is the best option.
5. Online versus printed. Simple Reports are only used for dashboard dashlets and not for managerial
or business reports that are required in hardcopy format.
6. Exporting data. With Crystal Reports, you can export report data to various formats.
Creating a report based on an existing data

source
A data source for one report can be used as the data source in another report. Reusing a data source
involves copying and pasting the existing data source into the data source of the new report. This
procedure completely overwrites the existing data source of the new report, and replaces it with the
copied data source.
To create a report based on an existing data source:
1. Create and save a new report.
2. From the list of reports on the left, click the plus sign (+) of the report containing the data source
you want to copy.
3. Right-click the data source and select Copy.
4. Right-click the report containing the data source you want to replace and select Paste.
5. Click Ok at the prompt.
Understanding how changes to SDTs and

packages impact reports
Over time, and especially in cases where BAM is deployed, configured, and tested in a development
environment, the structure of an SDT or package changes. These changes include:
adding SDTs/packages
deleting SDTs/packages
modifying SDT/package names
adding attributes
deleting attributes
modifying attribute names
All changes to monitored SDTs and packages must be synchronized in the BAM database, page 32
in order for reporting to function correctly. The synchronization operation is performed either in
Process Builder or your Taskspace application. The synchronization operation, however, can make
reports invalid due to inconsistencies between entities/fields used in the report and the structure of
the BAM database tables. For example, a report designed with a Purchase_Order entity provides a
83
total dollar amount of orders for each day of the week. Then, in Process Builder the Purchase_Order
SDT is deleted in favor of customer_PO. The synchronization operation drops the auto-generated
tables associated with Purchase_Order and creates tables used to store customer_PO data. However,
the original report still uses an old reporting entity (Purchase_Order) that is no longer valid. When
there is an inconsistency between report entities and database tables, a dialog box describes the entities
and fields to remove or deselect. The dialog displays during the following actions:
open the report
preview the report
save the report
In each case, the report designer must remove the invalid fields or report entities and save the report.
Publishing reports
All reports begin as a draft report. Draft reports are works in progress and cannot be displayed in the
dashboard until they are published. Publishing makes a report available on the dashboard design
palette. From here, a dashboard designer can use the report in one or more dashboards.
To publish a report:
1. Select the report from the Reports tab.
2. Select Published from the State pull-down list. This setting makes the report available to the
dashboard.
3. Save the report.
Auto refreshing reports

The auto-refresh feature automatically saves and reformats a report as a report designer moves through
the Chart Type, Chart Data, and Chart Properties tabs. This feature is helpful for dashboard users
who get immediate feedback on the look and feel of a report. Auto refresh is not available for the Data
Source tab.
To auto refresh reports:
1. Create a new or update an existing report in the Report Editor.
2. Select the Auto Refresh check box.
Configuring single drill-down reports

Single drill-down reports are configured in PRS where report designers first select a data source
series or column and then work in the Chart Data tab to select a report and filter or enter a URL.
Understanding single drill-down reports, page 61 provides an overview of the single drill-down
feature. Both published and draft reports can be configured as a source or target report.
To configure a single drill-down report:
84
1. Define a simple report.

2. Select either Pie, Bar, or Table as the chart type.
3. Within the Chart Data tab, locate the series or column for which you are defining a drill-down
report.
4. Click
in the Drilldown field.
5. To define a drill-down to another report:
a.
b.
c.
d.
Select the Report radio button.

Browse to and select a target report.
Click the Filter button to define a filter expression.
Select a filter tab and filter tree item and move it to the Filter Expression field by
double-clicking.
e. Place your cursor within the single quotes and press the Ctrl and spacebar keys on your
keyboard simultaneously. A list of dynamic filter values is displayed.
f. Double-click a dynamic filter value and click Ok to close the Filter window.
6. To define a drill-down to a URL, select the URL radio button and enter a URL in the field provided.
Note: The URL must be absolute and specify the location of a web page in full. For example:
http://www.siteaddress.com.
7. Click Ok.
85

Multi-drill-down reports are configured in two phases. First, as with single drill-down reports, the
hyperlink is configured in PRS. Then, the group of dashlets that are updated once the hyperlink is
selected is configured in the dashboard by a dashboard designer. This section outlines the procedure
for configuring multi-drill-down reports in PRS, and then configuring multi-drill-down reports
in a dashboard. Understanding multi-drill-down reports, page 63 provides an overview of the
multi-drill-down feature.
To configure a multi-drill-down report in PRS:
1. Define a data source. The data source must include one or more of the following entity fields:
Process ID, Process Instance ID, Activity ID, or Activity Instance ID.
Note: Entity fields, even if not visible in the report as configured in the Chart Data tab, are
used as parameters that are passed to each of the surrounding dashlets. Without this data, the
multi-drill-down report does not work.
2. Select the column or series for which the drilldown is defined. Currently, four dashboard events are
supported: process, process instance, activity, and activity instance. A dashboard event is defined
as a change in either a process ID, process instance ID, activity ID, or activity instance ID value.
CAUTION: The selected dashboard event must also be selected as an entity field in the data
source, even if the entity field is hidden from being displayed in the report. In this example, each
time a process is selected in the table, the surrounding dashlets are updated to display process
instance data. Therefore, Process Instance ID is selected as an entity field in the data source and
Process Instance is selected from the Dashboard Event pull-down list.
Configuring multi-drill-down reports in a

dashboard
The second part of a multi-drill-down report is configured within a dashboard. Within the Multi-Drill
tab, three columns are displayed: Event, Dashlet, and Target. The event column contains of a list of
all dashboard events, and each dashboard event is repeated for each dashlet included in the dashboard.
The dashlet column displays the name of each base report shown within the dashlet. The target column
86
is configured to display a report when an event is triggered. Continuing with the example, each time
a process is selected in the Process Instance List report, the System processes status bars report
changes to display process instance data in the Process Details report. The same logic applies to the
started processes statistics and Process Diagram dashlets.
To configure a multi-drill-down report in a dashboard:
1. Create a dashboard and add the desired dashlets.
2. Select the Multi-Drill tab.
3. Select the checkbox corresponding to the dashboard event and dashlet combination for which the
multi-drill is being defined.
4. Click the
button within Target to select a target report. The Content Chooser window opens.
5. Select a report and click Ok.
Configuring Crystal Report drill-downs

Configuring a drill-down report for a crystal report is performed exclusively in the Crystal Reports
software application. This configuration involves selecting a column in the report and formatting a
hyperlink. The hyperlink type must be website on the Internet and the URL must follow a particular
convention. The URL begins by referencing the report servlet name directly, and then continues with
the report type, report name, and path. The URL uses the following convention:
dashboardreports?drType=drilldown_type&reportType=1&reportName=<Report Name>
&reportPath=<Report Path>&filterExpression=<Filter Expression>
drType=drilldown_type
reportType=1 - this value is the Crystal Reports type. Simple reports are type=0.
reportName - the name of the report as it is entered in PRS.
reportPath - the full path to the report.
filterExpression filter expressions are optional.
In addition, a formula can be used when a value from the source report is used as part of the filter to
the target report. If you are using a formula, insert the URL in quotes. If you are referencing a field
value from the report, add it outside the quotes.
Crystal Report drill-down report URL

dashboardreports?drType=drilldown_type&reportPath=/System/BAM/Report Categories
/Crystal&reportName=Process Duration by Region&reportType=1&filterExpression=
ACT.Activity-Name = " + {dataSource.ActivityActivity Execution1} + ""
87
For more information on the URL convention see Displaying BAM reports in an enterprise portal,
page 92.
Editing Simple reports

A simple report can be opened and edited. All aspects of a simple report can be updated, including its
data source, chart type, chart data, and other properties. Editing a data source involves adding new
report entities, updating entity fields, and adding or editing filters. Crystal Reports can also be edited.
For instructions on editing Crystal Reports, see Editing Crystal Reports, page 82.
Note: The Next/Back navigation buttons used when creating a report are not available when editing a
report. Navigate the report by using the Chart Type, Chart Data, and Chart Properties tabs.
To edit a Simple report:
1. Locate the report in the Reports tab.
2. Right-click the report and select Open.
A report can also be opened by double-clicking it.
3. Edit either data source, the chart type, chart data, or chart properties.
4. Select File > Save.
Deleting reports
Reports can be deleted from within PRS. If the report is used in a dashboard, the dashboard user
receives the following error message: "This report cannot be displayed. Please contact your System
Administrator". Any report designer can delete any report.
To delete a report:
1. Navigate the list of reports.
2. Select the report to delete.
3. Select Edit > Delete from the menu. You can also right-click the report and select Delete.
4. Click Ok at the prompt.
Exporting reports from PRS

Users export reports when they want to use them in another repository. Both the data source and all
report properties are contained in an XML file that is imported back into PRS.
Note: This feature is deprecated for Business Activity Monitor Version 6.7 and will be removed in
future releases. Documentum Composer is the product to use for report backup, archiving, and moving
reports between repositories.
To export a report from PRS (not recommended):
88
1. Navigate the list of reports.

2. Select the report to export.
3. Select File > Export from the menu. You can also right-click the report and select Export.
4. Select a directory and save the report.
Importing reports in to PRS

Reports can be shared between repositories. Reports are exported from one repository and imported
into another repository.
Note: This feature is deprecated for Business Activity Monitor Version 6.7 and will be removed in
future releases. Documentum Composer is the product to use for moving reports between repositories.
To import a report in to PRS (not recommended):
1. Navigate the Report Builder.
2. Select the category into which the report is imported.
3. Select File > Import from the menu.
4. Select a report and import it.
Editing entity field captions

Changing the label of an entity field is an optional step taken when a report is defined. Entity field
captions are changed in the Caption Editor window that is opened by right-clicking any report
entity in the data source. Users can also click the caption editor button. The Caption Editor window
displays only those data source fields that have been selected for all report entities. The second column
of the window displays the name of the report entity to which the entity field belongs. Any of the entity
field captions can be changed within the Caption Editor window, even if they do not belong to the
selected report entity. Entity field captions can be changed within the Caption Editor window, even if
they do not belong to the selected report entity.
CAUTION: Report captions cannot be changed once a Crystal Report is synchronized into PRS.
89
To edit the caption of an entity field:

1. Right-click a report entity and select Caption Editor. Or, click the caption editor button.
2. Change the label in the caption column.
The caption can be any length.
3. Click Ok. The name of the column in the data source preview window is updated.
Using the data source undo and redo feature

An undo/redo feature is available in the data source builder. It is not available for any other step in the
report creation process. Within the data source builder this operation applies to adding and removing
report entities, selecting entity fields, and defining filters, and editing a caption.
Note: A save operation resets the undo/redo operations that can be performed.
To undo/redo an action:
1. To undo an action, select Undo from the Edit menu.
2. To redo an action, select Redo from the Edit menu.
Configuring business data aggregation

Business data aggregation entities are created at the discretion of the report designer. Unlike
aggregation entities for process, activity, and performer types, objects containing business data do
not automatically have aggregation entities defined. These objects are often times large (containing
many attributes) and complicated, with the capacity to capture and monitor much data. If business data
aggregation entities were automatically created, there is the potential that much of that data is of no
interest to the organization, and storing this data wastes space and eventually compromises system
performance. See Using business data and custom aggregation to enhance report performance, page
185 to determine whether business data aggregation is beneficial for your reporting. Once the report
designer identifies that they are needed, business data aggregation entities are configured by selecting
fields (columns), their functions, and a group-by column. Understanding reports that use aggregation,
page 57 contains detailed information on aggregation. Understanding the aggregation engine, page 17
describes the work of the aggregation engine.
Once the user clicks OK at the end of the procedure, BAM runs a SQL insert statement against the
database which creates nine different business data aggregation tables, one for each aggregation time
interval. Data is then calculated and inserted into those tables according to the time interval. Only
one aggregation can be defined for each SDT or package object type. An indicator is placed next to
business data objects for which an aggregation is already defined. Once aggregation tables are defined
and populated with data, the definition of the aggregation can only be updated by adding fields. In an
aggregation, fields cannot be removed and the method of aggregation and the group-by field cannot be
changed. These configuration options can only be changed if there is no data in the aggregation table.
Similarly, an aggregation can only be deleted when there is no data stored in the aggregation table.
90
For more information on deleting aggregation tables that contain data, see Synchronizing SDT and
package object type changes with the BAM database, page 32.
Note: The width of the Business Data Aggregation dialog box is fixed and cannot be changed. The
name of the business data entity in the list box can be a maximum of 60 characters. A tooltip displays
the full name of the business data entity.
To configure business data aggregation:
1. Log in to PRS.
2. Select Configuration > Business Data Aggregation.
3. Select a business data object from the pull-down list. A check mark next to the name indicates
that an aggregation is already defined for the selected object.
4. Select a field from the list of available fields.
5. Click the selection arrow to move the field to the list of selected fields on the right. The selected
field is removed from the list of available fields.
6. Select an arithmetic function from the Aggregation pull-down list.
7. To specify a grouping entity, select the Group checkbox.
Note: The same field cannot be both aggregated and grouped.
8. Click OK. All the required tables in the BAM database and all report entities in PRS are created.
9. Close and reopen PRS to view the new report entities located under the Business Data
Aggregation report entity category located on the palette.
Deleting business data aggregation

Within PRS, business data aggregation can only be deleted if business data is not already captured
and stored in the aggregation tables. For more information on deleting business data aggregation
tables that contain data, see Synchronizing SDT and package object type changes with the BAM
database, page 32.
CAUTION: This action cannot be reversed. In addition, all reports that use the business data
aggregation entity are deleted.
To delete business data aggregation:
91
1. Log in to PRS.
2. Select Configuration > Business Data Aggregation.
3. Select a business data object from the pull-down list.
4. Click Delete Aggregation.
5. Click Ok.
6. Click Yes on the confirmation dialog.
Displaying BAM reports in an enterprise portal

Displaying a report is not confined to a BAM dashboard. Reports can also be displayed in a web
application. A servlet called dashboardreports supports both simple and Crystal Reports.
There are two methods for accessing a report by way of a URL. The first approach uses the object Id of
the report. The second approach is based on the name of the report and the path to its location. Each
approach also supports adding a filter expression and maximum rows returned parameter to the URL.
Note: Some reports contain filters defined in PRS. Filters specified within the URL are applied to the
report after the PRS filter is applied.
Option 1: Using a report ID

With this option, the URL must conform to the following convention:
http://<Host>:<Port>/bam-server/dashboardreports?reportId=<ReportId>
Host The IP address of the BAM server

Port The listen port of the BAM server
Report Id The Docbase Id of the report
Option 2: Using the path to the report

With this option, the URL must conform to the following convention:
http://<Host>:<Port>/bam-server/dashboardreports?reportPath=
<Path_to_Report>&reportName=<Report_Name>
Host The IP address of the BAM server

Port The listen port of the BAM server
Path to Report The directory path to the report. Paths always begin with /System/BAM/Report
Categories and then followed by the user category (e.g. MyCategory).
Report Name The name of the report as entered in PRS
Filter and maximum row parameters

The sample URL contains a filter and a maximum row parameter. These parameters can be used with
either the report ID approach or with the path and name of the report approach.
http://<Host>:<Port>/bam-server/dashboardreports?reportID=<ReportID>
&filterExpression=<Filter_Expression>&maxRows=<Value>
92
Filter Expression A filter expression entered by the user. For more information about filter
expressions see Understanding data source filtering, page 48.
Value The number of rows to return in the report results set.
Report with filter

This URL displays the Customer Details report (report ID 0893762c80015172) that only includes the
Acme, Inc. customer. In addition, the maximum rows returned parameter is 10.
http://server:8080/bam-server/dashboardreports?reportID=0893762c80015172&
filterExpression=STD.ACustomer Name=Acme, Inc.&maxRows=10
Exporting reports from the BAM server

Simple Reports can be exported from the BAM server to CSV format. Crystal Reports can be exported
from the BAM server to CSV and PDF. Exporting Crystal Reports from a TaskSpace application, page
94 is an alternative approach to exporting Crystal Reports.
A report servlet called dashboardreports? is the mechanism by which reports are exported. To export
a Simple or Crystal Report from the BAM server you must point your browser to a URL that follows
the convention:
http://<Server>:<port>/bam-server/dashboardreports?reportId=<ID
number assigned in
Repository>&filterExpression=<filter expression>&export=<export format>
The elements of the URL include:

IP address of the BAM server
port number
the word bam-server
report servlet dashboardreports?
the report ID
A report ID is assigned to each report in the RepositoryNote: It is also possible to use the path
to the report and the report name as a way to specify the report to export. Exporting Crystal
Reports from a TaskSpace application, page 94 describes how to use the report path and report
name parameters.
filter expression (optional)
export format
For Crystal Reports, the export format can be either csv or pdf. For Simple Reports, the export
format can only be csv.
A BAM server login page is displayed when the URL is accessed. Users must log in with their
TaskSpace or Process Reporting Services credentials. Users either save or open the report after
logging in.
Note: It is possible to schedule reports to run automatically by using a custom program that sends a
request to the servlet.
93
Crystal Reports exported to PDF

This example exports a Crystal Report to PDF. The report is filtered to include only the Loan
Origination process.
http://10.290.67.120:8080/bam-server/dashboardreports?reportId=0802de6a80032364
&filterExpression=( PRO.Process-Name= Loan Origination )&export=PDF
Exporting Crystal Reports from a TaskSpace

application
Crystal Reports can be exported from a TaskSpace application to the following formats:
PDF
CSV: Comma Separated Value/Excel format. This format does not support paging.
RPT: Crystal Report format
RRTF: Read only Rich Text Format
ERTF: Editable Rich Text Format. This format does not support paging.
Note: Exporting Simple Reports from a TaskSpace application is not supported.
A report servlet called dashboardreports? is the mechanism by which reports are exported. To export
a Crystal Report to any format you must point your browser to a URL that includes:
IP address of the TaskSpace server
port number
the word taskspace
report servlet dashboardreports?
path to the report
the path to the report always begins with /System/BAM/Report Categories/ followed by the
subcategory (or subcategories) that contains the report
report name
filter expression (optional)
report type
the report type is always 2
export format
the export format must be either pdf, csv, rpt, rrtf, or ertf
page numbers of the report to export (optional)Note: Paging is not available in CSV and ERTF
formats
The URL follows the convention:
http://<Server>:<port>/taskspace/dashboardreports?reportPath=/System/BAM/Report
Categories/<report subcategory>&reportName=<report name>&filterExpression=
<filter expression>&reportType=2
94
&export=<export format>&from=<page number>&to=<page number>
Export Crystal Report from TaskSpace URL

This URL exports the first 25 pages of the Daily Revenue by State report to PDF format. The report is
filtered to include only the Loan Origination process.
http://10.137.16.201:8080/taskspace/dashboardreports?reportPath=
/System/BAM/Report Categories/Financial Reports/Revenue Reports&reportName=
Daily Revenue by State&filterExpression=( PRO.Process-Name= Loan Origination )
&reportType=2&export=pdf&from=1&to=25
95
96
Chapter 5
Process Reporting Services Examples
Designing a New Account Openings report
Designing a Total Deposits per City report
Calculating inter-activity duration
Designing reports with continuous aggregation
Designing a New Account Openings report

This section provides an example of how to design a simple report that includes both business data and
aggregation. This report is based on a new bank account application process where individuals can
make a deposit to open either a checking account or a savings account. The purpose of this report is to
count the number of checking accounts and saving accounts that have been opened. More specifically,
this report counts the number of individual process instances that have been completed for each type of
account. The count function is selected for the process ID field, since each process ID is unique. The
account type attribute is selected as the group-by. This report is formatted as a bar chart.
To design a New Account Openings report:
1. Right-click a report category, select New > Simple Report, and name the report.
2. Place the process execution entity on the report design canvas and deselect all fields except for
Process Instance ID. In this example, you count the number of process instances that open either
a savings or checking account.
3. Select Business Data on the palette. Then, place the New_Account_Application entity on the
canvas and deselect all fields except for AccountType. You are going to use report aggregation to
count the number of process instances for each account type. Account type is selected as the group.
Note: If you click the Refresh button in the Data Source Preview window, process instance data
is displayed. This view changes after you apply aggregation.
97
4. Click the Report Aggregation button on the data source toolbar. Then select the Group check box
for the AccountType field and select Count for the Process Instance ID field. Then, click Ok.
Note: If you click the Refresh button again in the Data Source Preview window, the number of
process instances are now counted for each account type.
5. Click the Chart Type tab.

6. Select Bar in the Properties window.
7. Click the Chart Data tab.

98
8. Select AccountType as the category and select Process Instance ID as the Y-axis. From here, you
can configure a number of visual properties by clicking the Chart Properties tab.
Designing a Total Deposits per City report

This section provides an example of how to design a simple report that includes both business data and
aggregation. This report is based on a new bank account application process where individuals can
make a deposit to open either a checking account or a savings account. The purpose of this report is to
calculate the total number of deposits (both checking and savings) for the city in which the deposit is
made. Since multiple deposits can be made in each city, the city field is selected as the group and the
amount values are added. This report is formatted as a pie chart.
To design a Total Deposits per City report:
1. Right-click a report category, select New > Simple Report, and name the report.
2. Select Business Data on the palette. Then, place the New_Account_Application entity on the
canvas and deselect all fields except for Amount and City. You are going to sum the amount
field and group-by city.
Note: If you click the Refresh button in the Data Source Preview window, process instance data
is displayed. This view changes after you apply aggregation.
99
3. Click the Report Aggregation button on the lower toolbar. Then select the Group check box for
the City field and select Sum for the Amount field. Then, click Ok.
Note: If you click the Refresh button again in the Data Source Preview window, the total deposit
amount is calculated for each city.
4. Click the Chart Type tab.

5. Select Pie in the Properties window.
6. Click the Chart Data tab.

7. Select City as the X-axis and select Amount as the Y-axis. From here, you can configure a number
of visual properties by clicking the Chart Properties tab.
100
Calculating inter-activity duration

BAM measures the duration of a single activity or the duration of an entire process, from start to finish.
Sometimes it is useful to measure the time it takes to complete a subset of connected activities. This
section provides an example of how to calculate inter-activity duration. Consider the simple process
where the time between the start of Activity-1 and the end of Activity-2 is measured. This time also
happens to be equivalent to the duration of the entire process.
To calculate inter-activity duration:

1. Create a simple report with a data source that includes Activity Execution, Process Execution,
and Activity Execution. Select the data source fields.Designing a simple report, page 66 addresses
how to define a data source.
2. Right-click the first Activity Execution report entity and select Filter. The Filter dialog opens.
Select the first activity for which the inter-activity duration is measured. Filtering report entities,
page 76 provides guidelines in defining a filter expression.
101
3. Then, open the Filter dialog for the second Activity Execution entity and select the final activity
for which the inter-activity duration is measured.
4. Once the report is saved, click the Refresh button in the Data Source Preview window. The
report results are displayed.
102
5. The Computed Columns feature is used to calculate the difference in duration between two
timestamps. Begin by clicking the Computed Columns icon. Understanding reports that include
computed columns, page 72 provides more information on computed columns.
6. Enter a name for the computed column, place your cursor in the Expression field, and enter
dateDiff(.
7. Then, press the Ctrl and spacebar keys on your keyboard simultaneously and select ${Finished
Date and Time} from the list.
8. Enter a comma (,) and then select ${Start Date and TIme} from the autocomplete list.
9. After ${Start Date and TIme}, enter )/1000.
10. After saving the report, the Data Source Preview window displays the inter-activity duration.
103
Designing reports with continuous aggregation

Process Reporting Services provides nine report entities that aggregate instance-level process data into
various time intervals. But, the aggregated data is only available after the time interval is over. For
instance, the Process Execution Daily report entity displays data after a day has passed. Likewise, wait
a month before data appears in a report designed with the Process Execution Monthly report entity.
But what if you are interested in aggregating data on a continuous or rolling basis? For example, how
would you generate a report that provides hourly trend data during each day that is updated every 5
minutes? This report relies on a fairly complex computed columns expression that is only possible in
Crystal Reports.
To design a report with continuous aggregation:
1. Design the report with the Process Execution 5 Minutes report entity.
2. Open the report in Crystal Reports and create a computed column that converts the Start Date
and Time field into hourly segments.
104
3. Use the computed column feature in Crystal Reports to aggregate the five-minute time intervals (in
this example, the Count of Started Instances is summed) and then grouped by hour.
105
106
Chapter 6
Designing Alerts with Process
Overview of Designing Alerts with Process Reporting Services
Understanding the technical components of alerting
Understanding alerting roles and responsibilities
Generating alerts from aggregated data
Overview of implementing alerts
Configuring email
Creating alert categories
Designing alerts
Understanding alerts designed with SDTs and packages
Designing alerts that include SDTs or packages
Designing service level agreement duration alerts
Configuring invoked processes to handle exceptions
Validating and testing alerts
Publishing alerts
Overview of Working with alerts in a dashboard
Editing alerts
Overview of Designing Alerts with Process

Reporting Services
Process Reporting Services contains an alert builder that is used to design process alerts in BAM. In
an ideal world, processes (and activities) are always completed on time. In an ideal world, performers
have enough work to keep them busy, but not so much work that they cause a bottleneck in the process.
In an ideal world, the capacities of work queues are not exceeded and all work tasks are completed in
a timely manner. But this ideal world does not exist. Running processes can vary quite a bit from
each other on many dimensions. Alerts are meant to notify you of situations when any aspect of a
process (performer, queue, SDT/package) meets or exceeds a threshold. Alerts are valuable because
they notify you of exceptions within business processes before they become problems. Specifically,
alerts are used to:
Identify processes where a Service Level Agreement (SLA) has not been met. For example, a
contract between a service provider and customer specifies that all Tier 1 help desk tickets be
107
resolved within 24 hours. An alert can be designed to trigger whenever a process instance (which
represents a single Tier 1 ticket) takes longer than 24 hours to complete.
Identify when Key Performance Indicators (KPIs) are at risk for not being met. For example, it the
goal of an insurance company to maximize new customers while minimizing customer attrition.
An alert can be designed to trigger whenever a certain number of lost customers exceeds a certain
number each day, week, or month.
Identify when milestones are not met. For example, a long-running process can be divided into five
milestones, each milestone represented as a date. Alerts can be designed to trigger when a process
has not reached a milestone by a specific date. This information is important so that a corrective
action can be taken to get the process back on schedule.
Identify processes or activities have exceeded a specific duration.
Escalate issues and notify business performers. For example, alert emails can be sent to responsible
parties notifying them when grant requests for greater than $200,000 are submitted.
Resolve bottlenecks by rerouting running processes. For example, if a review task is not completed
within a specific duration, the task is automatically forwarded to another performer with a note. The
note indicates that the task was not completed within the allotted time.
Perform root cause analysis by tying alerts and single and multi-drill-down reports together. For
example, an alert is designed to trigger when any item in a purchase order exceeds $50,000. Once
triggered, the alert is displayed in a dashboard where users can view additional information. This
information includes the details of the purchase order and the name of the performer that approved
the order. Additional drill-down reports can be designed to display the workload for each performer,
average performer durations, and information about queues. This data is used to understand
where process-related problems are occurring and how to resolve them. Understanding the Alert
Monitor dashboard design and layout, page 133 provides an example that brings alerts, single, and
multi-drill-down reports together into a single dashboard.
Alerts:
Can not be triggered on process execution data that has occurred in the past.
Can not be designed to trigger when another alert is not resolved. For example, you can not design
an alert to trigger when ten or more alerts with the highest severity are triggered. The Alert and
Alert History entities are only used to generate reports about alerts.
Understanding the technical components of

alerting
A number of technologies are involved with designing and deploying alerts. The purpose of this
section is to describe the technical components of an alert. Alerts involve the following technologies:
Process Reporting Services Alerts are designed in PRS. Alerts are comprised of a data source and
alert expression. Although other alert properties can be configured (email, severity, etc.) the data
source and expression are important because they determine when an alert is triggered.
Report Engine and BAM Database The report engine takes an alert data source and runs it against
the BAM database. A results set is generated, which the alert engine evaluates.
Alert Engine The results set is evaluated every 15 seconds by an alert engine on the BAM
server. Every time the alert engine runs, it receives a list of active alerts from PRS. During an
108
evaluation, the results set of the alert are compared against an alert expression. An alert expression
is a boolean-logic statement that is evaluated against the result set of a data source. The alert engine
only retrieves data that was added since the last evaluation. Alerts are also triggered on process
execution data that is inserted into the BAM database during the gap filling operation.
BAM Database If the alert expression is True for a row, then the following information is
entered into the BAM database:
alert name
process name
activity name
process instance ID
activity instance ID
date/time the alert was raised
Email System: If an alert is triggered, an email is sent to one or more individuals notifying them of a
problem. From within the body of an email, an alert recipient can open a dashboard to investigate
and resolve the alert.
Dashboard (in TaskSpace): The alert engine also provides services utilized by a BAM dashboard. A
triggered alert updates the alert list dashlet in a dashboard with the details of the alert. Dashboard
users update the alert status within the alert dashlet. Surrounding reports provide the information
necessary to determine the root cause of an alert, and take corrective action.
Figure 28
Alert technical architecture
Understanding alerting roles and

responsibilities
A number of people are involved with designing and deploying alerts. The purpose of this section is to
describe the actors involved with alerts. Alerts involve the following roles and responsibilities:
Alert Designer Alert designers are responsible for defining alerts in PRS. This person must be
familiar with the process for which they are defining an alert. Alerts are made operational when
109
they are published. When an alert is triggered, an alert email can be sent to one or more individuals
informing them of a problem.
Alert Email Recipient Emails can be sent notifying individuals that an alert has been triggered. A
link within the body of the email brings the recipient to a dashboard where reports can be used to
diagnose the root cause of the problem. The email recipient could have the authority to modify the
work of a performer.
Dashboard Use Dashboard users also see alerts in a dashboard. Dashboard users do not
necessarily receive alert emails. They could simply be viewing a dashboard and notice that an alert
is triggered in the alert list dashlet.
Performer Alert email recipients or dashboard users contact performers to make corrections
in their work, if necessary.
Figure 29
Alerts persona interaction diagram
Generating alerts from aggregated data

Alerts can be designed with aggregation entities that are available on the palette. Designing alerts on
aggregated entities is made possible by the alert engine that scans both instance and aggregation tables
in the BAM database. In a manner like reports, it is important to understand that aggregated alerts are
triggered only after the aggregation interval is complete. For example, the alert in the following figure
is designed to trigger when the average daily duration of a process exceeds two hours.
Aggregation as a topic is addressed in detail throughout this document:
Designing alerts with process and activity entities, page 112
110
Understanding server aggregation, page 58

Understanding the aggregation engine, page 17
Figure 30
Alert designed with aggregation entity
Figure 31
Expression in aggregated alert
Overview of implementing alerts

The purpose of this section is to describe factors to consider when implementing alerts. Alerts are
designed with one or more alert entities. The data source of an alert is designed by selecting alert
entities and columns. This section begins with a discussion of the variety of alert entities that are
available, and how they are used. A second important aspect of implementing alerts is writing alert
expressions. The alert expression defines the conditions under which an alert is triggered. This section
includes an in-depth discussion of how to write alert expression using JEP. This section also includes
other factors affecting alert implementation, including data source filtering, designing alerts for events
that have already occurred, and purging alerts.
This section is divided as follows:
Working with alert entities, page 112
Filtering an alert data source, page 119
Writing alert expressions, page 120
Purging alert data, page 123
111

All Process Reporting Services report entities are also used as alert entities. Alert entities provide a
view of process data stored in BAM database tables. And as with reporting, alert entities are dragged
from the Palette and placed on the design canvas.
Alert entities can be combined to form a data source. The data source includes the columns of data
(alert entity fields) used to configure the alert. Writing an alert expression is part of configuring an
alert. The alert expression defines the logic of the alert, that is, the condition under which an alert
is triggered. Alert expressions are written from the columns included in the data source. In general,
there are eight types of alert entities:
Process and Activity Execution
Process and Activity Aggregation
Incomplete Process and Incomplete Activity Execution
Activity Performer Aggregation
Queue
Business data entities
Custom entities
Designing alerts with process and activity entities

The Process category on the Palette contains three alert entities: Process Execution, Process Events,
and Incomplete Process Execution. The Activity category on the Palette contains three similar alert
entities: Activity Execution, Activity Events, and Incomplete Activity Execution. The incomplete
execution entities are different enough that they are addressed in the next section. The difference is
that Process Execution and Activity Execution entities are used when you want to be notified of
completed processes or activities that exceeded a specific duration. The incomplete entities measure
inflight durations. Use the Finished Date and Time column to design an alert to trigger when a process
or activity is completed after a certain date.
When the Process Execution entity is the first entity used in the alert, the Process, Process ID, and
Process Instance ID columns are always selected. When the Activity Execution entity is the first entity
used in the alert, the Activity, Activity ID, and Activity Instance ID columns are always selected.
These parameters are used in configuring drill-downs. When a process instance is selected in a table
report, the Alert List dashlet changes to display all alerts for the selected process or activity instance.
112
Table 9
Process Execution and Activity Execution entity columns
Column
Type
Duration (hh:mm:ss)
Numeric
Duration (hours)
Numeric
Duration (minutes)
Numeric
Duration (seconds)
Numeric
Finished Date and Time
Date
Process
String
Process ID
Numeric
Process Instance ID
Numeric
Start Date and Time
Date
Status
String
Version Number
Numeric
Table 10
Process and activity events columns
Column
Type
Entity ID
Numeric
Event Time
Date
Event Type
String
Performer ID
Numeric
Performer Name
String
Process Instance ID
Numeric
Process Name
String
Designing alerts with Incomplete Process and Incomplete

Activity Execution entities
The Incomplete Process Execution and Incomplete Activity Execution entities are used when you
want to be notified of inflight processes or activities that exceed a certain duration. Processes and
activities that have completed are not included in any of the ongoing duration calculations. There are
five different measures of ongoing duration. The Incomplete Process Execution entity is located
under Process on the palette. The Incomplete Activity Execution entity is located under Activity on
the palette.
When the Incomplete Process Execution entity is the first entity used in the alert, the Process, Process
ID, and Process Instance ID columns are always selected. When the Incomplete Activity Execution
entity is the first entity used in the alert, the Activity, Activity ID, and Activity Instance ID columns are
always selected. These parameters are used in configuring drill-downs. When a process instance is
selected in a table report, the Alert List dashlet changes to display all alerts for the selected process or
activity instance.
113
Table 11
Incomplete Process and Incomplete Activity Execution columns
Column
Type
Ongoing Duration (days)
Numeric
Ongoing Duration (hh:mm:ss)
Numeric
Ongoing Duration (hours)
Numeric
Ongoing Duration (minutes)
Numeric
Ongoing Duration (seconds)
Date
Process
String
Process ID
Numeric
Process Instance ID
Numeric
Start Date and Time
Date
Version Number
Numeric
Designing alerts with Process and Activity Aggregation

entities
Process and activity data is aggregated and stored in the BAM database. Reports can be designed with
process and activity aggregation entities. Alerts can also be designed with aggregation entities. For
nine different time intervals (5 minutes, 15 minutes, 30 minutes, hourly, daily, weekly, monthly,
quarterly, and yearly) BAM calculates average duration and provides a count of process (or activity)
instances that have started, completed, are ongoing, or failed.
Note: Include the Start Date and Time column so you can see the time interval for each row.
Aggregated alert entities are useful when you want to:
Be notified if average process duration exceeds a threshold you have defined for a specific time
interval. An alert could be designed to notify users when average process duration is greater than
two hours.
Be notified if the number of failed tasks (or started, completed, or ongoing tasks) exceeds a certain
value within a specific time period.
The process entities are available under Process Aggregation on the palette. The activity entities
are available under Activity Aggregation on the palette. The label of each aggregation entity
reflects its time interval. For example, Process Execution 5 Minutes, Process Execution 15 Minutes,
Process Execution 30 Minutes, etc.
Alerts designed with any of the Process Execution and Activity Execution aggregation entities
analyzes processes and activities that have completed. To generate aggregation alerts for processes
and activities that are ongoing, use either the Incomplete Process Execution 5 Minutes,
Incomplete Process Execution Hourly, or Incomplete Process Execution Daily alert entities.
The following columns are available for each aggregation entity.
Table 12
Process and Activity Aggregation columns
Column
Type
Average Duration (milliseconds)
Numeric
114
Column
Type
Average Duration (seconds)
Numeric
Count of Completed Instances
Numeric
Count of Failed Instances
Numeric
Count of Ongoing Instances
Numeric
Count of Started Instances
Numeric
Date
Maximum Duration (milliseconds)
Numeric
Minimum Duration (milliseconds)
Numeric
Process
String
Process ID
Numeric
Start Date and Time
Date
Version Number
Numeric
Designing alerts with Activity Performer Aggregation

entities
Performers complete activities within a process. Information about activities is collected, including
duration data and information about whether an activity is started, completed, is going, or has
failed. Performer name is also captured. This data is aggregated into nine time intervals, each with
a corresponding alert entity: 5 minutes, 15 minutes, 30 minutes, hourly, daily, weekly, monthly,
quarterly, and yearly. Each of the nine time intervals provides duration calculations and counts of
activities that have started, completed, failed, etc.
Performer aggregation entities are useful when:
You want to be notified if the average activity duration for a specific time period (5 minutes, 15
minutes, etc.) exceeds a certain value.
You want to be notified if the number of failed tasks (or started, completed, or ongoing tasks) for
any performer exceeds a certain value within a specific time period.
In this alert entity, the Activity and Activity ID column are always selected.
Table 13
Activity Performer Aggregation columns
Column
Type
Activity
String
Activity ID
Numeric
Average Duration (milliseconds)
Numeric
Average Duration (seconds)
Numeric
Count of Completed Instances
Numeric
Count of Failed Instances
Numeric
Count of Ongoing Instances
Numeric
115
Column
Type
Count of Started Instances
Numeric
Date
Maximum Duration (milliseconds)
Numeric
Minimum Duration (milliseconds)
Numeric
Performer ID
Numeric
Performer Name
String
Start Date and Time
Date
Working with queue entities

Process Builder and Process Engine supports queue management. Processes can be comprised of
activities and queues. A queue holds work items (activities) until a user claims and completes it.
Sometimes it is necessary for a process to route work to specific performers. However, there are times
when any number of performers can complete a specific activity. Instead of automatically routing work
to a specific performer within a process, work items are routed to a queue. Performers access the queue
and select and complete works items. Tasks are processed in a first in, first out order.
A queue is defined in TaskSpace and assigned as the performer of a manual activity. Each queue is
uniquely named and has thresholds (the maximum number of work items allowed in the queue), users
(a list of performers that can claim work items within the queue), and policies (rules that govern
how the queue operates). Performers select and complete queue work items. Work items exist in a
number of different states, called events:
Started The number of work items that have started
Completed The number of work items that have completed
Assigned The total number of assigned tasks in the queue (including suspended tasks)
Assigned (Suspended) The number of assigned tasks have been suspended
Unassigned The total number of unassigned tasks in the queue (including suspended tasks)
Unassigned (Suspended) The number of assigned tasks have been suspended
The Documentum TaskSpace Configuration Guide addresses queuing in greater detail.
In PRS, there are two queue entities: Work Queue and Work Queue Events. The Work Queue
report entity provides information on the queues themselves, including the name, the capacity (Policy
Task Count), the number of active users, works items assigned, and work items unassigned. The
Work Queue Events report entity provides a process context and includes the name of the activity
and performer, and information about the event.
Alerts designed with the queue entities are used primarily for work queue administration. For example,
an alert can be designed to trigger when the number of tasks within a work queue exceeds a certain
number. Or, alerts can be designed to trigger when the amount of time any pending task exceeds
a specific duration. Queue entities are also used to design alerts that incorporate performers, for
example, when a performer has not taken items from a queue in over six hours.
116
Table 14
Work Queue columns
Column
Type
Active Users
Numeric
Assigned
Numeric
Assigned (Suspended)
Numeric
Highest Task Priority
Numeric
Policy Priority
Numeric
Policy Task Count
Numeric
Queue Category
String
Queue ID
Numeric
Queue Name
String
Task Count
Numeric
Unassigned
Numeric
Unassigned (Suspended)
Numeric
Table 15
Work Queue columns
Column
Type
Activity Instance ID
Numeric
Activity Name
String
Additional Performer
String
Event ID
Numeric
Event Time
Date
Event Type
String
Performer ID
Numeric
Performer Name
String
Queue ID
Numeric
Queue Name
String
Designing alerts with business data entities

Business data refers to any information captured by fields on an electronic form as a process executes.
Structured Data Types (SDTs), package object types, and simple process variables capture business
data. These data structures are defined in Process Builder and have corresponding report entities in
PRS. Alerts use these entities, too. As with reporting, business data entities can be added to the data
source of an alert. Any column selected in the data source can be used in the alert expression.
Business data alert entities can be used alone, or in combination with other reporting entities. To
understand an alert within the context of its process, add either the Process Execution or Incomplete
Process Execution entity before adding the business data entity.
The figure displays an alert data source with a single business data entity.
117
Figure 32
Alert data source with business data entity only
The following figure displays an alert data source that includes the Incomplete Process Execution
and Activity Execution entities in addition to the grant_request entity. In this example, the
funding_amount field is the only column used in writing the alert expression. The Incomplete Process
Execution entity is used because alerts are issued for processes that are ongoing (in-process). The
Incomplete Process Execution entity includes columns that are used not for the writing the alert
expression, but for other aspects of configuring this alert. In this example, an alert is triggered
when ${funding_amount}>200000. The other information collected about the processes are used in
configuring a drill-down. For this reason, the Process, Process ID, and Process Instance ID columns
are always selected.
Figure 33
Alert data source with process and business data entity

The alert entity category consists of the Alert report entity and the Alert History report entity. The
alert report entity allows users to report on new and unresolved alerts. Once resolved, an alert is moved
to an archive table in the BAM database. This table provides the data for reports that use the alert
history report entity. Reports can include alert severity, status, date triggered, and date resolved. The
Grants Exceeded Funding report in Understanding the Alert Monitor dashboard design and layout,
page 133 provides an example of a report designed with the Alert entity.
Note: The Alert and Alert History entities cannot be used in an alert. For example, you cannot design
an alert to trigger when ten or more alerts with the highest severity are triggered. The Alert and Alert
History entity are only used to generate reports about alerts.
118
Custom alert entities

Alerts cannot be designed with custom entities in this release of the software.
Filtering an alert data source

As with reporting, the alert entities of a data source can be filtered. There is one important thing to
understand about alert data source filters. The alert engine does not use data source filters when
comparing data source result sets against the alert expression. If you want an alert to trigger when
a threshold is exceeded for a specific process or activity, then the alert expression must include the
name of the process or activity. As a result, the process and activity name columns must be included in
the data source.
For example, the alert expression ${funding_amount}>200000 triggers an alert whenever the funding
of a grant exceeds $200,000, regardless of where it occurs in a process. To constrain the alert to a
specific activity, include the name of the process and activity in the alert expression. For example,
${Process} == "Grant Request Status Monitoring Process" && ${Activity} == "Submitted" &&
${funding_amount}>200000 means that any request submitted for greater than $200,000 triggers an
alert. This alert is triggered at the beginning of the process when the application is first submitted.
Although there could be other activities in the process where funding amount exceeds $200,000, it is
not necessary to be alerted each time.
Alert data source filtering is useful for testing the validity of an alert. Once an alert is designed it can
be tested against historical data. An alert is tested by clicking the Refresh button in the Data Source
Preview window. Rows displayed in bold have exceeded the alert threshold. Validating and testing
alerts, page 131 addresses how to test alerts.
Note: While alerts are tested against historical data, alerts that are triggered do not appear in the
dashboard and do not send alert emails.
Data source filters are important because they reduce the results set against which alerts are being
tested. In the following figure, the alert is designed to trigger when the funding amount during the
Submitted activity of the Grant Request Status Monitoring Process exceeds $200,000. The data source
filter limits the result set to include just the Submitted activity. The filter expression must also be
written to constrain the alert to the Submitted activity. The second figure displays the corresponding
alert expression.
119
Figure 34
window
Data source filters applied to results displayed in Data Source Preview
Figure 35
Process and activity included in filter expression
Writing alert expressions

The alert builder in PRS is used to design process alerts in BAM. The alert engine evaluates the data
source of an alert. For each evaluation, the results of the data source are compared against an alert
expression. An alert expression is a boolean-logic statement that is evaluated against the columns of
the data source. This evaluation occurs periodically, at a scheduled interval by the alert engine on
the BAM server. Alert expressions are comprised of columns, operators, and constants and can be
simple or complex. Simple alert expressions are defined with one or two conditions, while complex
alert expressions can contain many conditions. Evaluations occur every 15 seconds, and if there is a
120
match, the contents of the alert list dashlet displayed in a dashboard are updated. In addition, email
notifications are sent to selected individuals who can then respond to and resolve the alert. The alert
engine only retrieves data that was added since the last evaluation. Email recipients and the body of
the alert email message are configured when the alert is defined.
Alerts are organized into categories. There can be several alerts within a category, and there can also
be several subcategories within a category. An alert can be opened, renamed, copied, and deleted.
Simple alert expression

In the example below an alert is triggered each time a loan origination process takes more than 24
hours to complete.
${Process} == "Loan Origination"
&& ${Duration (hours)} > 24
Complex alert expression

In this example an alert is triggered based on insurance claim amount, claimant age, and address.
${Ongoing Duration
&&
(
(Customer Age > 20
Customer Residence
||
(Customer Age < 20
||
(Customer Age > 30
)
(Hours)} > 1
&& Customer Age < 30 && (Customer Residence == "NY" ||
== "NJ") && Claim Amount > 500000)
&& Customer Residence == "NY" && Claim Amount > 1000000)
&& Customer Residence == "MA" && Claim Amount > 2000000)
JEP Operators
Alert designers enter filter expressions by selecting from a list of available columns and entering
Boolean operators and values. Expressions are represented as a string and then evaluated using
a Java Expression Parser (JEP). JEP is a Java library for parsing and evaluating mathematical
expressions. String expressions are parsed and represented as a tree structure that is evaluated.
An expression is automatically validated as it is typed. For more information on JEP, see
http://www.singularsys.com/jep/doc/html/index.html. The following JEP operators are supported:
Table 16
JEP operators
Name
Symbol
Modulus
%
/
Division
Multiplication
Addition, Subtraction
+,
Less or Equal, More or Equal
<=, >=
Less Than, Greater Than
<, >
Not Equal, Equal
!=, ==
121
Name
Symbol
Boolean And
&&
Boolean Or
||
Writing alert expressions using autocomplete and the

keypad
Alert expressions are written with the aid of an autocomplete feature. As mentioned earlier, expressions
are comprised of columns, operators, and constants. The autocomplete feature is used to select the
columns used in the expression. There are a few important points point about autocomplete:
a list of columns is displayed when you press Ctrl-spacebar on your keyboard.
only the columns selected in the data source are available.
double-click a column to select it.
The following figure displays an example of autocomplete columns.
Figure 36
Initiating the autocomplete drop down list
Note: PRS validates the alert expression as it is written. An Invalid Expression message appears until
your expression is written with the correct syntax.
Once a column is selected you can use the keypad to select a Boolean operator. After the operator,
manually enter a constant. String values must be encapsulated in double quotation marks. Date and
numeric columns do not need the double quotation marks. For complex expressions, continue using
the keypad and autocomplete features.
Table 17
Data types and formats
Data Type
Format
Example
STRING
Double quotation marks must surround

the constant
${Process} == "Grant Request Status

Monitoring Process"
NUMERIC
Quotation marks are not required
${funding_amount}>200000
DATE
Quotation marks are not required
${Start Date and Time} > 11/16/2009 12:00:00
122
Figure 37
Keypad operator and constants
Purging alert data

The following information is inserted into the BAM database each time an alert is triggered:
alert name
process name
activity name
process instance ID
activity instance ID
date/time the alert was raised
This information can be used for auditing and analysis purposes. Once no longer needed alerts can be
purged from the BAM database in just the same way as other process data. Purging BAM execution
and aggregation tables, page 188 describes how to purge data from the BAM database.
Configuring email
BAM relies on the mail parameters available in the repository. These parameters include SMTP host,
owner address, and recipient addresses. Correct configuration enables emails to be sent to one or more
people notifying them that an alert has been triggered. Selecting the alert recipients occurs after the
alert expression is defined. The email alert notification feature is optional. The email environment
must be configured as follows:
SMTP Server BAM relies on an SMTP server for sending email. It is the responsibility of
the customer to configure the SMTP server to work with xCP applications. The SMTP server is
configured before the installation of the repository. As the repository is installed, the user is asked
to specify the SMTP host.
Owner Email Address Emails are sent from the owner of the Documentum repository. The
email address of the repository owner populates the From field in the email. The address of the
repository owner must be configured properly. During the installation of Documentum, the user is
asked to provide an administrator email address. See Troubleshooting, page 236 for instructions on
changing the owner email address.
Recipient Email Address The recipient email address populates the To field in the email. Within
PRS email recipients are selected during alert configuration. A single or multiple recipients can
be selected. The list of recipients in PRS are roles to which individual users are associated. Users
123
have email captured for them. It is important to understand that selecting a recipient in PRS could
mean that multiple individuals receive an email alert. User email addresses are entered when a
user is created in TaskSpace or by way of DQL.
CAUTION: These email parameters are used globally by all xCP applications. Any change in
these parameters impacts all other applications that rely on email.
Troubleshooting alert email issues

This section outlines four techniques to use if you are unable to send or receive alert emails.
Tracking email status

BAM uses email only for alerting. Email is sent asynchronously which means that an email message is
not necessarily sent immediately. First it is marked as ready to send, and then a background job on
the BAM server sends the email. This asynchronous mechanism allows alerts to be raised even if the
email system is down. If your email server is down for any reason, then you can track all pending
email jobs by looking at the BAM_EMAIL_TASK table in the BAM database. Use the following
SQL query to look at all pending email jobs:
select ID, CREATION_TIME, LAST_UPDATED, EMAIL_CONTENT from BAM_EMAIL_TASK
Troubleshooting email environment problems

This section addresses email environment issues.
SMTP server
To look up the host name of the BAM SMTP server, then run the following DQL
command:select smtp_server from dm_server_configThe result of this query is the
host name of the SMTP server.
To change the host name of the SMTP server, run the following DQL command:update
dm_server_config objects set smtp_server=<SMTP Host>In this command,
<SMTP Host> is replaced with the real value.
Owner email address
To look up the owner of an email address, run the following command:select user_address
from dm_user u, dm_server_config cfg where
u.user_name=cfg.owner_name
To change the owner of the email address, then run the following command:update dm_user
objects set user_address=<Valid Address> where user_name
in (select user_name from dm_user u, dm_server_config cfg where
u.user_name=cfg.owner_name)In this command, <Valid Address> must be replaced with the
real value.
Recipient email address
To look up a recipient email address, run the following command:select user_address
from dm_user where user_name=<User Name>In this command, <User Name> must be
replaced with the real value
124
To change a recipient email address, run the following command:update dm_user objects
set user_address=<Valid Address> where user_name=<User Name>In this
command, both <User Name> and <Valid Address> must be replaced with the real values.
Troubleshooting network performance issues

If your network is performing slowly, it is possible to modify the mail SMTP I/O by changing a value
in the env-config.xml file that is located in: <BAM Installation Directory>/WEB-INF/classes/config.
<email smtpTimeout="600000"></email>
The email tag is located within the app-config preference. The default time is set to 60 seconds.
Note: Do not modify this value unless it is needed.
Recovering messages sent incorrectly

If an incorrect SMTP host is configured, then emails are not sent until the SMTP host location is
corrected and the BAM application server is restarted. If either the owner or recipient email address is
invalid, then you either delete the incorrect messages or modify the From and To values of the email.
If not corrected, the email system tries to resend the emails.
1. Copy the values returned after you execute the following query:
select EMAIL_CONTENT from BAM_EMAIL_TASK where ID=<ID of incorrect message>
2. Edit the email content with the correct values.

3. Update the corresponding database record by running the following command:
update BAM_EMAIL_TASK set EMAIL_CONTENT=<Fixes message content> where
ID=<ID of incorrect message>
Creating alert categories

Alert categories are listed in the Alerts tab. Alert categories can contain subcategories.
To create an alert category:
1. Log in to PRS. For more information on logging in, see Logging in to Process Reporting Services,
page 64.
2. Select the Alerts tab.
3. Select Alert Categories or a subcategory and then from the File menu select New > Category.
You can also right-click a category and select New > Category.
4. Enter a category name and click Finish.
5. From the File menu, select Save. You are now ready to add alerts to the category.
125
Designing alerts
This section includes a procedure for designing alerts in PRS. Alerts consist of:
a data source (required)
an alert expression (required)
a severity and state (required)
email configuration (optional)
an invoked process (optional)
Note: Alerts can only be triggered for events that occur after an alert is designed and published. It is
not possible to trigger alerts on events that occurred before an alert is published.
Note: Duration alerts require special consideration. If you want to be made aware of a process or
activity that is exceeding a duration threshold as it is still being executed, then use the Incomplete
Process Execution or Incomplete Activity Execution report entities, respectively. If you want to be
made aware of processes or activities that have exceeded a duration threshold after the process or
activity is completed, then use the Process Execution or Activity Execution report entity.
To design an alert:
1. Log in to PRS and select the Alerts tab.
2. Select an alert category and from the File menu, select New > Alert. You can also right-click the
alert category and select New > Alert.
3. In the New Alert name field, enter a name and click Finish. The alert is added to the category in
the Alerts tab and the Data Source tab opens. A data source can now be defined.
Note: Alert names must be less than 150 characters.
4. Build the alert data source by clicking, dragging, and placing objects from the palette onto the
canvas.
5. Each object contains entity fields. To select an entity field, place a check mark to the left of
the field name.
Note: Only selected fields can be used in an alert expression.
6. Click the Alert tab located above the Data Source Preview window.
126
7. From the Severity list box, select either Low, Medium, or High.
The severity level corresponds to the color of the alert icon displayed in the dashboard:
Low = yellow
Medium = orange
High = red
8. From the State list box, select Published. Published alerts are made available to the alert engine
for evaluation.
9. Place your cursor in the Expression field and use the autocomplete feature to write an alert
expression. Writing alert expressions, page 120 contains more information related to JEP
expressions and operators, and using autocomplete.
10. From the Sent to: list box, select an email recipient. Use the Ctrl or Shift keys to select multiple
recipients.
127
11. Emails are sent from the owner of the Documentum repository. The address of the owner of the
repository must be configured properly in order to send email.
12. Enter a Message. The message forms the body of the alert email.
13. To invoke a process in response to the alert, enter a value in the Process Parameters field.
14. From the File menu, select Save. The alert is now operational.
Understanding alerts designed with SDTs and

packages
Alerts can be designed with process entities shipped with the product (Process Execution, Activity
Execution, etc.) or business data entities dynamically created from the structure of your SDTs and
packages. This capability dramatically extends alerting beyond duration and count data to include
business data values captured during process execution. For example, during a trade settlement process
the company symbol and number shares traded are captured during a transaction. An alert can be
designed to trigger when 500,000 or more shares are traded for a company with the symbol RNC. Or, a
grants management process captures the requested funding amount for each grant. An alert can be
designed to trigger when the requested funding amount exceeds $200,000.
SDT and package alert entities are located in the Business Data category on the Palette. For each
SDT and package, there are two entities: one entity contains the user-defined attributes (for example,
grant_request). These entities contain the columns that are of most interest to you. The other alert
entity contains repeating attributes (for example, grant_request Repeating Attributes) that can also
be used in designing alerts.
Figure 38
128
Business Data Palette
Designing alerts that include SDTs or packages

This section includes a procedure for designing an alert that includes an SDT. This example is based on
a grants management application that processes grant funding requests. The review process requires
that grant requests submitted for greater than $200,000 go through a separate review. The data source
is designed with the Incomplete Process Execution because the alert is triggered while the process is
running, and not when it is completed. The Activity Execution entity is included because the alert
expression is constrained to the Submitted activity of the Grant Request Status Monitoring Process.
The grant_request entity is included because it contains the funding_amount column that holds the
amount requested data.
To design alerts that include SDTs/packages:
1. Log in to PRS and create an alert.
2. Design the data source of the alert by selecting alert entities and fields. Alerts can consist of
a single entity, or multiple entities.
3. After the data source is defined, click the Alert tab.

4. From the Severity list box, select either High, Medium, or Low.
5. From the State list box, select Published. Publishing makes the alert operational in a dashboard.
129
6. Place your cursor in the Expression field and press Ctrl-Space. A list of columns is displayed.
7. Build the filter expression by double-clicking a column, selecting an operator from the keypad, and
entering a constant.
Note: Columns that contain STRING data must have the constant value surrounded by double
quotations. Columns that contain NUMERIC and DATE data do not need quotation marks.
8. Select an email recipient and from the File menu select Save.
Designing service level agreement duration

alerts
A service level agreement (SLA) records a common understanding about services, priorities,
responsibilities, and guarantees between a customer and a service provider. SLAs that include the
average and total durations it takes for a process or task to execute is a common use of SLAs. This
section includes a description of how to design an alert to trigger when a single process exceeds
a specified duration.
In this example, an SLA of two days exists between a bank and loan applicants. The bank agrees to
notify applicants of either the approval or denial of a loan within two business days. This alert is
designed with the Incomplete Process Execution entity. This entity is used because the bank wants
the alert to trigger while processes are still running, and not when they are completed. In addition, the
Ongoing Duration (days) column is selected.
Figure 39
Service level agreement alert data source
Then, the alert expression is written for the alert to trigger when any loan origination process
(${Process} == "Loan Origination" ) exceeds two days in duration (${Ongoing Duration (days)} > 2).
Figure 40
130
Service level agreement alert expression
Configuring invoked processes to handle

exceptions
Alerts can be configured to trigger another process automatically in response to an exception. For
example, a process that exceeds a duration threshold can invoke another process that routes the work to
another individual. This individual completes the work in a timely manner. Automatically invoking
another process can also be used in situation where a date milestone is missed, or a SDT/package
attribute value exceeds a certain value. Invoked processes must be designed to listen on an HTTP port.
It is the responsibility of the alert designer to enter the process parameters manually. The Documentum
Process Builder User Guide provides more information on configuring the HTTP inbound activity
template. Once configured in PRS, the invoked process must be entered in the Process Parameters field
when the alert is configured in PRS.
The following procedure assumes that you know how to design an alert, including the data source and
writing the alert expression.
To configure an invoked process to handle exceptions:
1. Design the data source of the alert.
2. Write the alert expression.
3. In the Process Parameters field, enter the name of the process to invoke when the alert is triggered.
4. From the File menu, select Save.
Validating and testing alerts

Writing an alert expression is the most challenging aspect to designing an alert. The challenge is that
users must be familiar with using JEP, the syntax used to write alert expressions. PRS automatically
checks the validity of the expression as it is being written. An Invalid Expression message is
displayed to the user until the expression is alert expression is valid. This automatic validation makes
sure that the expression is logical; it does not mean that the alert works as desired. It is recommended
that you test alerts before publishing them to a dashboard. This procedure guides you in testing an
alert against real process execution data. Data Source Preview window rows displayed in bold
are the processes that have triggered an alert.
Note: If the data source of an alert is filtered, then filtered data is displayed in the Data Source
Preview window.
To test an alert using PRS:
1. Define an alert in PRS.
2. Run a test transaction through the system so that it exceeds the threshold of the alert.
Note: You may need to wait up to 20 seconds for the alert to display in PRS.
131
3. Click the Refresh button in the Data Source Preview window. The rows that match the alert
expression are displayed in bold.
Publishing alerts
An alert must be published before it can be used in a dashboard. Publishing makes the alert operational.
Unpublished alerts are not active and are not triggered even if the threshold is exceeded. Typically, an
alert is published as it is being designed.
To publish an alert:
1. Log in to PRS and click the Alert tab.
2. Right-click the alert and select Open. The data source of the alert opens.
4. From the State list box, select Published.
Overview of Working with alerts in a dashboard

Alerts are designed in PRS and once published, are made operational in a dashboard. Operational
means that when an alert is triggered, certain information about the alert is displayed to dashboard
users by way of the Alert List dashlet. For each alert that is triggered, eight columns of data are
displayed in the Alert List dashlet. Columns cannot be added to or removed from the Alert List
dashlet. Rarely is the Alert List the only dashlet included in a dashboard. This section includes an
in-depth discussion and example of an Alert Monitor dashboard that ties a single drill-down report,
the Alert List dashlet, and the Process Diagram dashlet together to provide dashboard users a way of
gathering more information so that the alert can eventually be resolved and closed. Configuring alert
dashboard refresh intervals is also addressed.
This section addresses the following topics:
Working with the Alert List dashlet, page 132
Understanding the Alert Monitor dashboard design and layout, page 133
Configuring alert dashboard refresh intervals, page 140
Working with the Alert List dashlet

A BAM dashboard can consist of three different types of dashlets: report, Process Diagram, and Alert
List. The purpose of the Alert List dashlet is to display the details of an alert that has been triggered,
including its status, name, and description. The default status for each alert is New, which can be
changed to either Acknowledged or Closed by a dashboard user. The status is updated in the Edit
132
window where a dashboard user is also required to enter a note. This procedure guides you in changing
the status of an alert.
To acknowledge or close an alert:
1. From the Alert List dashlet, select an alert you want to acknowledge or close.
2. Click Edit.
The Edit window opens.
3. From the Status list box, select either Acknowledged or Closed.

4. Enter a note and then click Add Note.
5. Click OK.
The Edit window closes and the Status is updated in the Alert List dashlet.
Understanding the Alert Monitor dashboard design

and layout
This section describes how alerts are used within an Alert Monitor dashboard. The Alert Monitor
dashboard provides users with information about triggered alerts, reports, and diagrams. This
particular dashboard is built with three reports, the Alert List dashlet, and a Process Diagram dashlet.
A multi-drill dashboard event is configured that connects a report, the Alert List dashlet, and the
Process Diagram dashlet together.
133
The Grants Exceeded Funding report displays a list of process instances that have triggered an alert.
In this particular report, an alert is used as a data source filter. In addition, the Process Instance ID
column of the Grants Exceeded Funding report is configured as a dashboard event so that when
an instance ID is selected:
The Alert List dashlet provides a filtered list of alerts that have been triggered for the selected
process. Without selecting an instance ID, the Alert List dashlet displays a list of all alerts that are
triggered.
The Average Process Duration report switches to display the Grant Requests report.
The Process Diagram dashlet displays a process flow diagram of the selected process instance.
This section provides an overview of how each report in the Alert Monitor dashboard was designed.
Figure 41
134
Example Alert Monitor dashboard
Figure 42
Alert Monitor dashboard drill-down
1. Design an alert. In this example, an alert is designed to trigger when grants requests exceed
$200,000.
a.
The data source for this alert starts with the Incomplete Process Execution entity. This means
that the alert is triggered while processes are still running, and not when they are completed.
The Process column is included because the alert expression constrains the alert to the Grant
Request Status Monitoring Process (${Process}= = "Grant Request Status Monitoring
Process").Note: The Process ID and Process Instance ID columns are included by default and
cannot be deselected. These columns allow Process and Process Instance dashboard events to
be used in multi-drill-down configurations.
b.
The Activity column in Activity Execution is also included because it is used in the alert
expression. This alert is further constrained to the Submitted activity within the Grant
Request Status Monitoring Process (${Activity}= = "Submitted"). This activity is selected
because Grant Administrators want to know when high dollar funding requests are submitted,
and not further down the process (for example, during the In Review or Approved activities).
The grant_request entity is included because it contains the funding_amount attribute that is
used to complete the alert expression: ${funding_amount}>200000.
c.
Use the auto-complete feature and JEP operators to write an alert expression. Only columns
selected in the data source can be used in an alert expression.
135
2. The first report to design is the source of a multi-drill-down configuration. In this example, the
Grants Exceeded Funding report contains a list of process instances that have triggered an alert.
One particular column, Process Instance ID, is configured as a multi-drill-down event. When a
Process Instance is selected:
the Alert List dashlet is filtered to include only those alerts associated with the selected process.
the Process Diagram dashlet updates to indicate the progress of the selected process.
the Average Process Duration report is updated to display additional information about the
selected process in the Grant Requests report.
136
a.
The Grants Exceeded Funding report is designed with the Alert entity. This entity contains
important information about triggered alerts, including the name, severity, and status. The
Process Execution entity is included because it holds the Process Instance ID column, which
is used to configure the multi-drill-down.
b.
Within the data source, a filter is written to include those processes in the report that have
triggered the Funding Greater than 200K alert. All other processes are excluded from the
report.
c.
Next, Process Instance is selected as the Dashboard Event for the Process Instance ID
column. Once configuration is complete in the BAM dashboard, selecting a Process Instance
ID in the Grants Exceeded Funding report updates the contents of the Alert List dashlet, the
Process Diagram dashlet, and the Average Process Duration report.
3. In addition to the Grants Exceeded Funding report, this dashboard contains a dial gauge report
that calculates the average hourly duration of in-flight processes. The Grant Requests report
replaces the Grants Exceeded Funding report when a Process Instance ID is selected in the
Grants Exceeded Funding report.
a.
The data source for this report is designed with the Incomplete Process Execution entity so
that hourly duration can be calculated for running processes only. Completed processes are
omitted from this report. Report aggregation is used to calculate the average ongoing duration,
grouped by process. Process is included so that a filter can be written that constrains the report
to the Grant Request Status Monitoring Process.
b.
The Category (X) axis must be numeric. Therefore, Ongoing Duration (hours) is selected.
c.
Gauge ranges must be adjusted appropriately on the Chart Properties window, if the default
values are not sufficient.
137
4. Behind the Average Process Duration report, is the Grant Requests report. The purpose of this
report is to display more information about the process (and associated business data) selected in
the Grants Exceeded Funding report.
a.
The data source of this report begins with the Process Execution entity and the Process, the
Process ID, and Process Instance ID columns. The Process column is displayed in the report
and used in a filter; the latter two columns are required for the multi-drill-down configuration.
b.
A filter on the Process Execution entity is written to constrain the report results to Grant
Request Status Monitor Processes where funding_amounts are greater than $200,000:
PRO.Process-Name = Grant Request Status Monitoring Process AND
BSD.GRANTREQUEST-funding_amount > 200000
c.
138
This report is further constrained to include only funding amounts available during the
Submitted activity:
ACT.Activity-Name = Submitted AND ACT.Process-Name = Grant Request

Status Monitoring Process
5. Design the dashboard and configure the multi-drill-down report.

a.
Once the reports are designed, the work shifts to the Dashboard Design tool available in
TaskSpace. Begin by creating a dashboard and adding content. In this example, the Grants
Exceeded Funding report is added first, followed by the Alert List dashlet and then the
Process Diagram dashlet. The Alert List dashlet displays details of the alert triggered by the
process selected in the Grants Exceeded Funding report. This dashlet provides users with the
ability to acknowledge and close alerts, and add remarks. The Process Diagram dashlet is
included because it displays a workflow diagram of the selected process. The diagram displays
the status of each activity in the workflow as either completed, running, or not started.
139
b.
Multi-drill configuration can take place once the dashlets are arranged on the dashboard. When
a Process Instance ID is selected in the Grants Exceeded Funding report, the Average Process
Diagram report switches to display the Grant Requests report. For this configuration, you must:
i.
Click the Multi-Drill tab.
ii. In the Event column, select the Process Instance checkbox that corresponds to the
Average Process Duration dashlet.
iii. Select Grant Requests as the target report for the Average Process Duration dashlet.
Configuring alert dashboard refresh intervals

You can configure a dashboard to refresh at specific time intervals. By default, dashboards are
configured not to refresh at all (the refresh interval is set to 0 minutes). The time interval is changed in
the Auto Refresh tab of the dashboard editor. Dashboard refresh intervals are configured in minutes.
To configure alert dashboard refresh intervals:
1. Within the dashboard editor, click the Auto Refresh tab.
2. Use the up and down arrows to select another time intervals. You can also place your cursor in the
Refresh Time (minutes) field and enter a value.
3. Click either Save (to continue working) or Finish to save and exit the dashboard editor.
140
Editing alerts
All aspects of an alert can be edited, including its data source and properties. Published alerts must be
set to draft before changes are made. Once an alert is edited it must be saved.
To edit an alert:
1. Log in to PRS and click the Alert tab.
2. Right-click the alert and select Open. The data source of the alert opens.
4. From the State list box, select Draft.
5. Edit the alert.
6. Once the changes have been made, select Published from the State list box.
141
142
Chapter 7
Designing Dashboards
Understanding BAM Dashboards
Understanding the report dashlet
Understanding the process diagram dashlet
Understanding the alert list dashlet
Understanding dashlet filters
Understanding dashboard permissions
Understanding the dashboard interface
Creating sub-processes in Process Builder
Creating a dashboard application
Designing a dashboard
Adding a dashboard to an application
Adding a dashboard tab
Assigning dashboard tabs to roles
Configuring multi-drill-down reports in a dashboard
Adding process diagrams to a dashboard
Scheduling refresh periods
Configuring dashlet filters
Printing reports from a dashboard
Modifying dashboards
Removing dashboards
Deleting dashboards
Using dashlet filters
Understanding single and multi-search filters
Configuring single and multi-search filters in a dashboard
Using single and multi-search filters
Updating the status of an alert
Customizing a dashboard cascading style sheet
143
Viewing dashboard contents displayed in right to left languages
Understanding BAM Dashboards

A BAM dashboard is a display environment for monitoring executing processes in real-time. The
primary purpose of a dashboard is to provide line of business and IT personnel a tool for monitoring,
understanding, and resolving process issues as they occur.
Dashboards are configured by dashboard designers who use a drag-and-drop user interface to arrange
dashlets on a dashboard. A dashlet displays the content of a specific report, process diagram, or alert.
The data displayed in a dashlet is provided by the BAM server, Process Engine, and Process Builder
by way of report services. Dashboards are applications developed within TaskSpace and displayed
to dashboard users through a web browser. The dashboard is packaged as an EAR file that contains
the set of predefined dashlets.
Note: BAM dashboards include Internationalization support of right-to-left characters. However, the
user interface of the dashboard is still left aligned.
Note: Dashboards require that Flash Player version 9 or higher be installed on the machine of the
user. SVG Viewer 3.x must also be installed if Internet Explorer is used. SVG is natively supported by
Firefox and other browsers.
Figure 43
BAM dashboard architecture
The first step in designing a BAM dashboard is to prepare the process diagram for display in Process
Builder. From here dashboard designers use TaskSpace to create a new dashboard within a dashboard
application. Dashboards are comprised of dashlets. Role-based access to individual dashboards is also
specified in TaskSpace by the dashboard designer. Dashboard users interact with dashboards displayed
in TaskSpace to filter report results and resolve alerts.
144
Figure 44
Dashboard designer and dashboard user interaction diagram
Understanding the report dashlet

All reports defined in Process Reporting Services including Crystal Reports that are synchronized
back into PRS can be displayed in a dashboard. There are 5 simple report types: pie charts, bar
charts, bar + line charts, gauge reports, and table reports. For more information on simple report types
see Understanding simple report types, page 51. As a dashboard is created dashboard designers can
select from a list of published reports organized by category. The list is available on the tree menu.
Note: Only published reports can be added to a dashboard.
Dashboard users can interact with a report dashlet in one of two ways. First, dashboard users have
the option of filtering report results. Once the filtering feature is activated, dashboard users will be
able to select from a set of preconfigured dashlet filters. And second, if a report is configured as a
drill-down report, then users will be able to open another report within the same dashlet. Drill-down
reports are configured by report designers in PRS. When the base report is added to a dashboard
then all linked drill-down reports are also added.
Figure 45
Report dashlet
Note: Advanced search within a Crystal Report displayed in a dashboard is not supported. Only
reporting features which are supported by Crystal Reports Java Runtime Component version 2008
are exposed to BAM.
145
Understanding the process diagram dashlet

The process diagram dashlet provides a graphical representation of an executing process instance. The
image displayed in the process diagram dashlet is taken from Process Engine. It represents the process
just as it is designed in Process Builder, with some additional information. Activities within a process
that have been completed are annotated with a gear icon and green check mark. Activities that are
currently being executed are displayed with a blue gear icon. Activities that have not been completed
are gray. In addition, an alert icon is placed to the left of activities that trigger an alert. The color of the
alert icon indicates severity, with red being the highest. The alert icon could also be orange or yellow.
In some processes an activity could be performed multiple times, for example, if it is part of a loop. If
this happens then a number is displayed in the upper left hand corner of each activity indicating the
number of times each activity has been performed in the process instance. The numbers are displayed
only when activities are performed more than once.
Figure 46
Process diagram dashlet
Understanding the alert list dashlet

Data in the BAM execution tables and aggregation tables is periodically monitored by the alert engine.
The alert engine is component of the BAM server that compares alert results against alert conditions.
For more information about the alert engine, see Understanding the alert engine, page 18.
Alerts themselves are defined in PRS. When an alert is triggered the alert list dashlet is updated to
include the name of the alerted entity (for example, the name of the process), the name of the alert (as
entered in PRS) together with relevant information, like severity level, date, and status. Alerts also
trigger emails that are automatically generated and sent to one or more people. From within the body
of the email, dashboard users can click a link, log in to TaskSpace, and update the status of an alert.
Alerts statuses are updated by clicking the Edit button.
For more information on working with an alert, see Updating the status of an alert, page 162.
In addition to updating the status, the alert dashlet has the following features:
Group By Users can see the list of alerts grouped by Status, Severity, and Name.
Sorting The table can be sorted by clicking the column headers. For example, clicking the Date
header sorts the rows by date. Clicking the Status header sorts the table according to whether the
alert is new, closed, or acknowledged.
146
CAUTION: When defining either process or activity alerts that include duration, the Process
Instance ID and Process ID or Activity Instance ID and Activity ID entity fields must be selected
in the data source.
Figure 47 Alert dashlet
Understanding dashlet filters

Dashlet filtering is the mechanism by which report results are reduced to display a subset of data.
Dashlet filters are configured by a dashboard designer who defines a list of filters on behalf of
dashboard users. Dashboard users can then select which filters to apply when working with a dashlet.
Configuring dashlet filters, page 155 addresses dashlet filter configuration.
CAUTION: For some reports, filters may have already been applied within PRS, by a report
designer. In this case a dashlet filter is applied after the report filter.
Dashlet filters can be defined for base reports and associated drill-down reports, if any exist. This is
required because a dashlet may actually contain multiple reports. Once a dashlet and report are selected,
the dashboard designer selects one or more filters and chooses those filters that are initial filters and
those that are mandatory. Initial filters are applied automatically as a dashlet loads for a dashboard
user. Mandatory filters must be selected by dashboard users first, before report results are displayed.
Note: Dashlet filters are applied only to the first entity in a report. To configure a dashlet filter for
an SDT or package attribute, you must design the report with the business data reporting entity first.
Then, if you are interested in adding process information you can add the Process Execution report
entity.If it is not possible to use the business data reporting entity as the base entity of the report, then
List of values for business data filters can become quite long. Configuring single and multi-search
filters in a dashboard, page 159 describes how to add search capabilities to business data filters.
Understanding dashboard permissions

Dashboard permissions are inherited from the underlying DocBase permission system. Dashboards are
assigned to a TaskSpace tab, and it is for tabs that user permissions are assigned. A user may only
view dashboard tabs that were assigned to its role. Permissions are only available for dashboards and
do not apply to specific reports, diagrams, or alerts within a dashboard. As a result, only dashboard
designers are able to add content to a dashboard.
147
For more information on assigning permissions to a dashboard see Assigning dashboard tabs to roles,
page 151.
Understanding the dashboard interface

A dashboard is displayed as a single page that is divided into rows. A page contains as many rows as
needed. Rows are divided into dashlets that contain reports, diagrams, and alerts. A row can contain as
many dashlets as needed. The width of a dashboard is fixed; there is no horizontal scrollbar. The height
of a dashboard is not fixed. A vertical scroll bar is available. Dashlets can be re-sized by dragging the
divider located between dashlets. When re-sized, other dashlets in the row are automatically re-sized.
Note: The display of simple reports re-sizes proportionally to the size of the dashlet. This is not true
for Crystal Reports. When Crystal Report dashlets are re-sized, the content displayed in the report does
not re-size proportionally. The size of these reports is specified in Crystal Reports.
The default width of a dashlet is dependent on the number of dashlets in the row. Scrollbars are
displayed within a dashlet when the content of the report or diagram exceeds the space provided.
Dashlets do not have a minimum size. Dashlets can be refreshed (both manual and scheduled), filtered,
maximized, and configured as the target of a multi-drill-down report.
Creating sub-processes in Process Builder

Process Engine provides the BAM server with an image of each process instance, and data about
the executing process. These images, called process diagrams, are displayed to dashboard users.
The exact placement of each activity in the process is controlled within Process Builder. The image
displayed in Process Builder and the process diagram displayed in a dashboard is the same. So, you
may want to make adjustments to process diagrams in Process Builder.
One element you can introduce into a process diagram is a sub-process. Oftentimes, a large or
complicated process can become difficult to organize visually when there are many activities. To
simplify the layout of a process, you may want to group related activities into sub-processes that
represent related steps or functions in the process. Activities do not have be part of a sub-process.
Subprocess, together with individual activities, are displayed in process flow diagram viewable in a
dashboard.
Sub-processes can be created using either top down modeling or bottom-up modeling. Top down
modeling is addressed in the Documentum Process Builder User Guide. Bottom-up modeling is
addressed in this procedure because it is assumed that the process designer is first concerned with
developing the process, and then organizing its layout.
To create a sub-process in Process Builder:
1. Select the activities to include in the sub-process.
You can select multiple activities by using the mouse to drag a rectangle around the activities you
want to include in the sub-process or by holding down the Shift key and clicking the activities
individually.
The selected activities are surrounded with a green, dashed line.
2. Select Tools > Sub-Process > Add to Sub-Process.
148
The grouped activities appear in a colored rectangle that is labeled Sub-Process.

3. Right-click the sub-process and select Sub-Process Inspector to set the properties that are shared
for all activities within the sub-process.
For more information on setting properties, please see the Documentum Process Builder User
Guide.
4. Enter a name for the sub-process.
5. Click Ok.
You can click the new sub-process and drag it to the intended position in the window.
Creating a dashboard application

TaskSpace provides capabilities for designing user interfaces for process-based software applications.
A BAM dashboard is a specific type of application. Each dashboard application can hold multiple
dashboards. Dashboards, in turn, hold dashlets that display a specific report, process diagram, or
alert list.
First a dashboard application must be created. Then, a dashboard is designed and added to the
dashboard application.
To create a dashboard application:
3. Click the New Application button located in the lower right corner of the window.
4. Enter a name in the field provided. This is the name of the application displayed in the URL. Do
not use spaces.
5. Enter a title. The title is displayed in the user interface.
6. Click Ok. A URL is assigned to the new application.
7. Copy and paste the URL into a browser window.
You are now ready to design a dashboard.
Designing a dashboard
A BAM dashboard is comprised of a series of dashlets arranged in rows and columns. Designers
add a dashlet to the dashboard by selecting components from the tree view and placing it onto the
dashboard canvas. As the component is dragged to the canvas its title is displayed with the appropriate
icon. Dashlets can be added to an existing row or to a new row. Once placed on the canvas the dashlet
outline is displayed as a red, dashed line. The same dashlet can be added multiple times.
Dashboard designers can select from any of the available report dashlets, the alert list dashlet, the
process diagram dashlet, or the process simluation dashlet. In addition, filter can be configured for any
dashlet added to a dashboard.
To design a dashboard:
149
1. Launch a browser session and open the URL of the application to which the dashboard is being
added.
4. Select the Dashboards node from the left tree menu.
5. Click the Create button located at the bottom right of the window.
6. Enter a Name and a Label. The label appears as the name of dashboard in the user interface.
7. Click Next. This opens the dashboard design canvas.
8. To add a report:
a. Click
to expand the Reports left tree menu.
b. Continue expanding report categories until you locate the desired report.
c. Click and drag a report to the dashboard design canvas.
Note: You do not need to decide where to place the first dashlet, it is merely added to a blank
canvas. From here forward you must decide where each dashlet should be positioned. Dashlets
can be positioned to the right, left, top, or bottom of an existing dashlet by hovering the
selected report over the divider bar, and releasing.
9. To add an alert list dashlet, click and drag Alert List to the dashboard design canvas.
10. To add a process diagram dashlet, click and drag Process Diagram to the dashboard design canvas.
11. To preview the dashboard as a dashboard user would see it, click the Configuration button. Click
the Configuration button again to continue designing the dashboard.
12. To save your work and continue working, click Save.
13. To save the dashboard and go back to the component list page, click Finish.
Adding a dashboard to an application

A dashboard must be added to a dashboard application. Dashboards can be added to multiple
dashboard applications.
To add a dashboard to an application:
1. Launch a browser session and open the URL of the application with which you are working.
5. Click Add. A list of dashboards is displayed.
6. Select a dashboard from the list on the left and move it to the right with a selection arrow.
7. Click Ok.
150
Adding a dashboard tab

Dashboards are displayed within a tab in TaskSpace. This procedures creates a new tab in TaskSpace
and adds a dashboard to it.
To add a dashboard tab:
4. Select Tabs from the left tree menu. A list of tabs is displayed.
5. Click Create.
6. Select Dashboard from the Select Tab Type pull-down list.
7. Click Next.
8. Enter a name in the field provided. Do not use spaces.
9. Enter a Label. The label appears as the name of tab in the user interface.
10. Select a dashboard from the Dashboard Component pull-down list.
11. Click Finish.
Assigning dashboard tabs to roles

Dashboards are displayed within a tab. Roles are assigned access to TaskSpace tabs. This procedure
has the user assigning a tab to a TaskSpace role. This procedure assumes that the role exists.
To assign dashboard permissions:
4. Select Roles from the left tree menu. A list of roles is displayed.
5. To assign permissions to a role that has already been added to the dashboard application:
a.
b.
c.
d.
Select the role.

Click the Edit button.
Click the Manage button.
Select a tab from the list of Available Tabs and move it to the list of Assigned Tabs by
clicking the Add arrow.
e. Continue adding tabs as necessary.

f. Click Ok.
6. To assign permissions to a role that has not yet been added to the dashboard application:
a. Click the Add button.

b. Select a role from the pull-down list.
151
c. Click Next.
d. Select a tab from the list of Available Tabs and move it to the list of Assigned Tabs by
clicking the Add arrow.
Continue adding tabs as necessary.
e. Click Next.
f. Configure the Global Search and click Next.
g. Configure the Component Mappings and click Next.
h. Configure the Menus and click Finish.

Multi-drill-down reports are configured in two phases. First, as with single drill-down reports, the
hyperlink is configured in PRS. Then, the group of dashlets that are updated once the hyperlink is
selected is configured in the dashboard by a dashboard designer. This section outlines the procedure
for configuring multi-drill-down reports in PRS, and then configuring multi-drill-down reports
in a dashboard. Understanding multi-drill-down reports, page 63 provides an overview of the
multi-drill-down feature.
To configure a multi-drill-down report in PRS:
1. Define a data source. The data source must include one or more of the following entity fields:
Process ID, Process Instance ID, Activity ID, or Activity Instance ID.
Note: Entity fields, even if not visible in the report as configured in the Chart Data tab, are
used as parameters that are passed to each of the surrounding dashlets. Without this data, the
multi-drill-down report does not work.
2. Select the column or series for which the drilldown is defined. Currently, four dashboard events are
supported: process, process instance, activity, and activity instance. A dashboard event is defined
as a change in either a process ID, process instance ID, activity ID, or activity instance ID value.
152
CAUTION: The selected dashboard event must also be selected as an entity field in the data
source, even if the entity field is hidden from being displayed in the report. In this example, each
time a process is selected in the table, the surrounding dashlets are updated to display process
instance data. Therefore, Process Instance ID is selected as an entity field in the data source and
Process Instance is selected from the Dashboard Event pull-down list.
Configuring multi-drill-down reports in a

dashboard
The second part of a multi-drill-down report is configured within a dashboard. Within the Multi-Drill
tab, three columns are displayed: Event, Dashlet, and Target. The event column contains of a list of
all dashboard events, and each dashboard event is repeated for each dashlet included in the dashboard.
The dashlet column displays the name of each base report shown within the dashlet. The target column
is configured to display a report when an event is triggered. Continuing with the example, each time
a process is selected in the Process Instance List report, the System processes status bars report
changes to display process instance data in the Process Details report. The same logic applies to the
started processes statistics and Process Diagram dashlets.
To configure a multi-drill-down report in a dashboard:
1. Create a dashboard and add the desired dashlets.
2. Select the Multi-Drill tab.
3. Select the checkbox corresponding to the dashboard event and dashlet combination for which the
multi-drill is being defined.
4. Click the
button within Target to select a target report. The Content Chooser window opens.
5. Select a report and click Ok.
153
Adding process diagrams to a dashboard

Process flow diagrams can be added to any dashboard. This procedure makes use of the multi-drill
feature. Configuration begins in PRS and continues within the dashboard. Understanding
multi-drill-down reports, page 63 addresses the underlying concepts of the multi-drill feature.
To add process diagrams to a dashboard:
1. Define a report in PRS with a data source that includes the Process Instance ID column.
2. Within the Chart Data tab define a drill-down and select the Dashboard Event radio button.
3. Select Process Instance from the pull-down list and then click Ok to close the Drilldown window.
4. Within a dashboard, place the report containing the drill-down definition on the dashboard design
canvas. The example below shows that the Process Instance Duration report has been added.
5. Somewhere within the same dashboard, place the Process Diagram dashlet on the dashboard
design canvas.
CAUTION: You will not see anything in the process diagram dashlet when it is first added to a
dashboard. Users must click the hyperlink defined in the base report. In this example, a process
diagram is displayed when a process instance ID (displayed as a hyperlink) is selected in the
Process Instance Duration report.
154
Scheduling refresh periods

Refreshing provides a dashboard the most up-to-date monitoring data. Individual dashlets can be
manually refreshed by a dashboard user by clicking the Refresh icon located on the menu bar of each
dashlet. All dashlets within a dashboard can also be refreshed according to a schedule. The refresh
time interval is restricted to 1 minute intervals.
To schedule a refresh period:
1. Open a dashboard for editing.
2. Select the Scheduler tab.
3. Enter a Refresh Time in 1 minute intervals.
4. Click Save.
Configuring dashlet filters

Dashboard users can filter data displayed in report. The choices from which they can select are
configured by the dashboard designer. Dashboard designers are presented with a list of possible filters
within the Dashlet Filter tab. This list of possible filters represents a subset of filters available for the
base report entity in PRS. For instance, a report based on the Process Execution report entity has a
different set of filters than a report built with the Activity Execution report entity.
Note: Dashlet filters are applied only to the first entity in a report. To configure a dashlet filter for
an SDT or package attribute, you must design the report with the business data reporting entity first.
Then, if you are interested in adding process information you can add the Process Execution report
entity.If it is not possible to use the business data reporting entity as the base entity of the report, then
Note: Once a filter is defined it can be made available to the user. The dashboard designer decides
which filters are initial filters and those that are mandatory. Initial filters are applied automatically
as the dashboard loads the dashlet. Dashlets containing mandatory filters display a message to the
dashboard user informing them to apply a filter. Using dashlet filters, page 157 provides instructions
on how to select a filter. Once a filter is selected the report is loaded.
To configure dashlet filters:
1. Open a dashboard.
2. Click the Dashlet Filter tab.
3. Select a dashlet from the Dashlets pull-down list.
4. Select a report from the pull-down list.
Note: Because of single drill-down reports, each dashlet can have multiple reports associated with
it.
5. Place a check mark next to the filters you want to make available to a dashboard user.
6. To select an initial filter:
155
a. Select the Edit Dashlet Initial Filter link.

b. Select the filter value(s) in the Initial Filter window.
c. Click Ok.
7. To make a filter mandatory, select Yes from the mandatory pull-down list.
8. Click Save.
Printing reports from a dashboard

Simple reports and Crystal Reports can be printed directly from a dashboard. A printed simple report
does not include headers, footers, logos, the date, and page numbers. This type of advanced formatting
is available in Crystal Reports.
To print a simple report from a dashboard:
1. Log into a dashboard and locate the report you want to print.
2. Click the Print button on the dashlet toolbar.
3. Select a printer and click Print.
Modifying dashboards
All aspects of a dashboard can be edited including adding new dashlets, removing dashlets, and
modifying filters, groups, and scheduling configurations. This procedure is for dashboard designers
who need to edit pre-existing dashboards.
To modify a dashboard:
1. Launch a browser session and open the URL of the application containing the dashboard to be
modified.
5. Select a dashboard from the list and click Edit.
6. To change the label, enter a new Label and click Next. Otherwise, accept the current label by
clicking Next. This opens the dashboard design canvas.
7. To add content to the dashboard click and drag a dashlet from the left tree menu and place it on the
dashboard design canvas.
8. To remove a dashlet click the Close button. The close button is the x in the upper right corner of
a dashlet.
9. To modify multi-drill-down reports click the Multi-Drill tab.
10. To modify the dashlet refresh period, click the Scheduler tab.
11. To save your work and continue working, click Save.
12. To save the dashboard and go back to the component list page, click Finish.
156
Note: Dashboard users will see the changes once they refresh their browser.
Removing dashboards
Dashboards can be removed from a dashboard application. This operation only removes the dashboard
from the current application, it does not delete the dashboard from the repository. The dashboard can
be added to other applications.
To remove a dashboard from an application:
1. Open a dashboard application.
2. Click the Configuration tab.
3. Click the Dashboards node from the left tree menu.
4. Select a dashboard.
5. Click the Remove button located in the lower right corner of the window.
6. Click Yes in the confirmation window.
Deleting dashboards
Dashboards can be deleted from the repository, and by extension, all dashboard applications to which
it has been added.
CAUTION: Once a dashboard is deleted it cannot be restored.If another application is using the
dashboard when it is deleted, the contents of the dashboard will no longer display.
To delete a dashboard:
1. Open a dashboard application.
2. Click the Configuration tab.
3. Click the Dashboards node from the left tree menu.
4. Select a dashboard.
5. Click the Delete button located in the lower right corner of the window.
6. Click Yes in the confirmation window.
Using dashlet filters

Filtering is a way of reducing a large set of process execution data into a subset of data. The filter
options presented to dashboard users are configured by dashboard designers. A dashboard designer
may have also configured initial filters and mandatory filters. Initial filters are applied automatically as
the report loads. Mandatory filters must be selected first before the report is displayed.
To apply dashlet filters:
157
1. Click the Filter button
A list of filters is displayed.

2. Select a filter.
3. Select a filter value.
4. Click Ok.
The dashlet is refreshed to display the filtered data.
Understanding single and multi-search filters

Business Activity Monitor is capable of monitoring and reporting on vast amounts of process execution
and business data. Business data especially can become quite voluminous. This presents a challenge
when business data filters are configured for dashboard users. When a business data reporting entity
is used as the first entity in a report, then any of the fields can be used in a dashboard filter. Filters
are extremely useful to dashboard users who may be required to reduce large report data sets into
a smaller number of records. However, the list of possible filter values can grow to be very long.
Dashboard users need a way of quickly finding and selecting filter values. Single and multi-search
filters are configured so that a dashboard user enters a string of text into a field, which then reduces
the list of values. Then, a dashboard user selects one or more values. Single and multi-search filters
are also useful to dashboard users who are unsure of the spelling of a filter value. Without single and
multi-search filter dashboard users must enter a filter value exactly as it is in the BAM database.
Note: Single and multi-search filters are case sensitive. Wildcard searches (%) are not supported.
Single and multi-search filters are configured by entering either SINGLE_SELECTION_SEARCH or
MULTI_SELECTION_SEARCH in the data type column when the filter object is created. Once the
filter object is created in the BAM database, it is configured by a dashboard designer in TaskSpace.
Configuring single and multi-selection search filters, page 212 explains how to create single and
multi-search filters objects. Configuring single and multi-search filters in a dashboard, page 159
explains how to configure single and multi-search filters in a dashboard. Using single and multi-search
filters, page 160 explains how to use single and multi-search filters.
Figure 48
158
Invoice reporting entity
Figure 49
Single search dashboard filter
Figure 50
Multi-search dashboard filter
Configuring single and multi-search filters in

a dashboard
Dashboard designers are responsible for enabling single and multi-search filters once these objects are
created in the BAM database. These filters are configured in the Dashlet Filter tab.
159
To configure single and multi-search filters:

1. Select the report for which you are configuring a single or multi-search filter.
2. Select the Dashlet Filter tab.
3. Select the checkbox next to the single or multi-search filter.
4. Click Save.
Using single and multi-search filters

Single and multi-search filters are designed to help dashboard users reduce long lists of filter values.
These filters work by entering part of the search text which reduces an entire list of values to a subset
of values. This task guides dashboard users in using single and multi-search filters in a dashboard.
To apply single and multi-search filters:
1. Within a dashboard report, click the filter button. The Edit Report Filter dialog opens.
2. To use a single search filter:
a. Enter a value in the field.

b. Click the Search button.
c. Select a filter value from the list box.
d. Click OK.
160
The filtered report is displayed.

3. To use a multi-search filter:
a. Enter a value in the field.

b. Click the Search button. A list of available values is displayed.
c. Select values from the list of available values. Each value chosen is displayed in the selected
list of values.
d. Click OK.
The filtered report is displayed.
161
Updating the status of an alert

An alert list dashlet presents dashboard users with a list of triggered alerts. Dashboard users can
interact with this dashlet to select an alert status and enter a note.
For a list of additional features available in the alert list dashlet see Understanding the alert list dashlet,
page 146.
To respond to an alert:
1. Click the alert link provided in the notification email.
3. Locate the alert list dashlet.
4. Select a row corresponding to an alert you want to update.
5. Click the Edit button.
6. Select and alert status and enter a note.
7. Click Ok.
Customizing a dashboard cascading style sheet

The look and feel of a BAM dashboard can be customized. This is especially useful if you have
customized the look and feel of TaskSpace, and want to apply similar styles to your dashboard. The
dashboard cascading style sheet (.css) can be modified with the Dashboard Style Utility available on
the EMC Download Center. The following procedure provides instructions in how to use the utility, it
does not provide a comprehensive list of all styles that can and cant (shouldnt) be modified.
CAUTION: Not all styles can be modified. It is very important that you understand how to
work with cascading style sheets.
To customize a dashboard cascading style sheet:
1. Download the dashboard style utility zip file from the EMC Download Center.
2. Extracts the contents of the style utility zip file.
The ZIP file contains the following:
flex-sdk3 these files form the foundation of Flex, and provide the core Flex compilers, the
component library, and debugger.
output This directory is empty at first, and will hold main.swf once the .css is compiled.
src This directory holds the main.css file and source files related to the style and dashboard
images copied from the TaskSpace .war in steps 3 and 4. At download time this directory
is empty.
3. Copy main.css and all action script files (files with an .as extension) located under
<TaskSpace.war>\taskspace\library\dashboard\swf\css\ to the dashboard_css\src\css directory
of the style utility.
4. Copy the entire images directory located under <TaskSpace.war>\taskspace\library\dashboard
to the dashboard_css\src\css\assets directory of the style utility.
5. Modify main.css. It is the responsibility of the user to understand how to make changes to a .css.
162
6. Double-click build-css.bat located under Dashboard Style Utility to run the utility. This compiles
the modified main.css into main.swf that is placed in the output directory of the style utility.
Note: The compilation is successful when there are no errors, and the utility displays
output\main.swf. If there are errors, you must go back to the .css file, make the corrections, and
run the style utility again.
7. Copy the newly compiled main.swf file from the output directory of the customization utility
back into <TaskSpace.war>\taskspace\library\dashboard\swf\css\.
8. Copy the updated main.css source file from dashboard_css\src\css back to
<TaskSpace.war>\taskspace\library\dashboard\swf\css\.
9. Copy the images directory from dashboard_css\src\css\assets back to
<TaskSpace.war>\taskspace\library\dashboard. This step is only required when
there are changes to any of the dashboard images.
Viewing dashboard contents displayed in right

to left languages
Dashboard users select a language when logging in to TaskSpace. Two of the languages, Hebrew and
Arabic, are written and read in a right to left direction. When BAM dashboards contain reports and
diagrams displayed in right to left languages, then dashboard designers and users must select a right to
left language when logging in to TaskSpace. If a right to left language is not selected, then right to left
reports and diagrams fail to load in the dashboard.
If right to left reports and diagrams must be viewed or edited by users in a left to right locale (English,
Spanish, French), then a right to left correction utility must be used. The correction utility is initiated
when the LanguageDirection parameter is set to rtl. The LanguageDirection parameter is located in
the dashboardProperties.xml file.
To initiate the right to left correction utility:
1. Navigate to /taskspace.war/taskspace/config/dashboard.
2. Open dashboardProperties.xml for editing.
3. In the LanguageDirection parameter enter rtl.
5. Restart the TaskSpace application server.
163
164
Chapter 8
Working with Preconfigured
Dashboards
Overview of the Preconfigured Dashboards
Understanding the Process Monitor dashboard
Understanding the Process Summary dashboard
Understanding the Alert Monitor dashboard
Localizing the preconfigured dashboards
Overview of the Preconfigured Dashboards

BAM is shipped with three preconfigured BAM dashboards. The primary purpose of the preconfigured
dashboards is to provide you with a starting point for designing your own dashboards, and are not
to be used as-is in a production environment.
Preconfigured dashboard installation instructions are available in the Documentum Business Activity
Monitor Installation Guide.
There is a Process Monitor dashboard that displays information about process instances executing in
Process Engine. The Process Summary dashboard provides aggregated views of processes, spanning
longer time intervals. The Alert Monitor dashboard helps dashboard user manage and report on
process and activity alerts.
Working with preconfigured dashboards requires:
that the preconfigured dashboards be installed (please see the Documentum Business Activity
Monitor Installation Guide for more information)
a process to be developed in Process Builder
monitored settings to be configured in Process Builder and TaskSpace
so there is data to display, a number of processes must be run once BAM is configured
Note: Most reports displayed in the preconfigured dashboards are defined with aggregated report
entities. It will take several minutes for results to initially be displayed in the dashboards.
Dashboard designers may want to modify a dashboard by adding reports that are of particular value to
their business. Reports that contain SDT or object type data, for example, should be added. This is
because the preconfigured dashboards only contain reports defined with common data data that is
available across all implementations of BAM. Start date, duration (minutes), and process name are all
examples of common data.
165
Working with Preconfigured Dashboards
This documentation addresses each preconfigured dashboard with a description of each dashboard
report and its relationships to other dashlets, if they exist.
Note: All of the simple reports used in the Process Monitor and Process Summary dashboards can be
modified. Crystal Reports should not be modified. Modifications involve changes to the data source,
the chart type setting, chart data configuration, and chart properties. Therefore it is crucial that you
understand the principles of reporting. The Designing Reports with Process Reporting Services , page
40 chapter is dedicated to reporting.
CAUTION: You cannot change the name of reports used in any of the preconfigured dashboards.
This creates an inconsistency in the dashboard and report results will not be displayed.
Note: It is recommended that you have each preconfigured dashboard and PRS open while you read
through this documentation.
Understanding the Process Monitor dashboard

The Process Monitor dashboard provides flow diagrams for each process that is executing as well as a
number of reports that focus on the details of each process. Some of the reports also provide summary
level information as it relates to all executing processes. This section provides a detailed description of
each portlet and outlines specific changes that can be made.
Understanding the List of Process Instances report

List of Process Instances is a simple table report that lists all processes executing in the system, start
and finish date/time information, duration, and version number. The Process column in this table is
configured as a multi-drill-down report that updates:
the Count of Started, In-flight, and Completed Processes report to display the Process Instance
Details report
the Count of Processes Started within the Last Month report to display the Process Duration
report.
the Process Diagram dashlet to display a process flow diagram for the selected process.
Understanding multi-drill-down reports, page 63 provides an overview of multi-drill-down reports.
Configuring multi-drill-down reports in PRS, page 152 and Configuring multi-drill-down reports in a
dashboard, page 153 provide procedures for configuring multi-drill-down reports.
The List of Process Instances report can be modified in PRS to include business data. Either an SDT or
an object type can be added to this report by selecting the Business Data report entity category on the
palette and moving business data object to the report design canvas.
166
Figure 51
Add business data report entity
Understanding the Count of Started, In-flight, and

Completed Processes report
This is a simple Bar+Line report built on the Process Execution 5 Minutes report entity. Counting,
as a arithmetic function, is only available in report entities that aggregate data. The data source for
this report includes entity fields that count the number of processes that have started, are in-flight, and
completed. Each series that is counted is formatted as a bar within the Chart Data tab of PRS. This
particular report entity is used because it provides near real-time data, with a count of processes
updated every five minutes. In addition, this report entity is filtered to include only those processes
that have started, are in-flight, or have completed since the last time the data was aggregated. Since
the aggregation engine runs every five minutes, this report provides a count of processes that have
either started, are in-flight, or completed within the last five minutes. This report provides a snapshot
of data as processes move through various states.
Count of Started, In-flight, and Completed Processes report interpretation

At 1:02 PM a single Loan Application process (a process instance) is started. The aggregation engine
runs at 1:05 PM and within the report this instance is shown as both started and in-flight. At 1:10 PM
the aggregation engine runs again, and while this process instance is still considered in-flight, it is not
counted as started because it began at 1:02 PM, outside of the aggregation engines five minute time
interval. At 1:11 PM, the process instance is completed, but the instance is still considered in-flight
because the aggregation engine has not run again. At 1:15 PM, the aggregation engine runs and this
process instance is now considered completed.
Understanding the Count of In-flight Processes

report
This is a simple report formatted as a pie chart that counts the number process instances currently
running for each process version. This report is built with the Process Execution 5 Minutes report
entity. Counting, as a arithmetic function, is only available in report entities that aggregate data.
167
The data source for this report includes entity fields that count the number of processes that are
in-flight. This particular report entity is used because it provides near real-time data, with a count of
in-flight processes updated every five minutes. This report entity is filtered to include only those
processes that are in-flight (MSC.On-Going-Instances > 0) since the last time the data was aggregated
(STD.Latest-Aggregation = True). Since the aggregation engine runs every five minutes, this report
provides a count of processes that are in-flight within the last five minutes.
Understanding the Count of Processes Started

within the Last Month report
This is a simple report formatted as a pie chart that counts the number of processes that have started
within the last month. The term last month is defined as the last 30 days. The data source for this
report uses the Process Execution Last Month Aggregation report entity and includes the Name,
Version and Started entity fields. This particular report entity is an example of a custom report entity.
It was created because the Process Execution Monthly reporting entity that comes with BAM is not
sufficient as it only provides report results after BAM collects data for one month. All custom report
entities are listed in the Uncategorized report entity category of PRS. Creating custom report entities
requires an understanding of the BAM data model and DQL.
The following figure provides a small sample of the DQL required to create this report entity. Creating
Custom Aggregation, Report, and Filter Entities, page 193 provides a complete set of instructions.
Sample DQL
Understanding the Process Instance Details report

This is a simple report formatted as a table that includes activity and work queue details for specific
processes selected in the List of Process Instances report. The Process Instance Details report is
configured as a target in a multi-drill-down report. Understanding multi-drill-down reports, page 63
provides an overview of multi-drill-down reports. Configuring multi-drill-down reports in PRS, page
152 and Configuring multi-drill-down reports in a dashboard, page 153 provides procedures for
configuring multi-drill-down reports.
Understanding the Process Duration report

This report is formatted as a dial gauge that points to the duration (in minutes) of the process selected
in the List of Process Instances report. The Process Duration report is configured as a target in a
multi-drill-down report.
Note: The dial gauge ranges configured in the Chart Properties tab of PRS should be changed. By
default, range 1 extends from zero to 40, range 2 extends from 40 to 70, and range 3 extends from 70
168
to 100. These settings may not be sufficient for your processes. Understanding simple report types,
page 51 provides an overview of gauge reports.
Understanding the Process Summary

dashboard
The primary purpose of the Process Summary dashboard is provide dashboard users with a view of
their processes, and then the ability to drill-down to activities. This dashboard in particular features
two single drill-down reports that count the number of processes and activities for each workflow
state (started, in-flight, completed) and duration statistics for processes and activities. There are also
two Crystal Reports featured in this dashboard that focus on the number of work tasks pending and
completed for each performer.
Understanding the Count of Processes per State

report
This is a simple Bar+Line report, that for each process, calculates:
the number of process instances that have started during the last month
the number of process instances that are in-flight at the moment of aggregation
the number of process instances that have completed during the last month
the duration (in minutes) of the process instance that has taken the longest to complete (maximum
duration) during that last month
Note: Month is defined as 30 days.
Count of Processes per State report interpretation

If a single Loan Application process (a process instance) starts on July 1st, 2008, a report generated on
July 2nd counts this process instance as being both started and in-flight. Suppose the loan process is
completed on July 15th. A report generated on July 16th counts this process instance as being both
started and completed but no longer in-flight. On August 1st, this process instance is no longer
included in the number of instances started calculation, because the process began more than one
month ago but, it is still included in the number of instances completed calculation because it was
completed within the last 30 days. On August 30th, this process instance is no longer included in
any of the calculations for this report.
The report entity used in the data source of this report is the Process Execution Last Month
Aggregation custom report entity discussed earlier in this chapter, page 168. This report is configured
as the base for a single drill-down report that opens the Count of Activities per State report when a
dashboard user selects the Count of Started Instances column.
169
Understanding the Count of Activities per State

report
This is a simple Bar+Line report, that for each activity, calculates:
the number of activity instances that have started during the last month
the number of activity instances that are in-flight at the moment of aggregation
the number of activity instances that have completed during the last month
the duration (in minutes) of the activity instance that has taken the longest to complete (maximum
duration) during that last month
Note: Month is defined as 30 days.
Similar to the Count of Processes per State base report, the data source for this target is defined with a
custom report entity. Creating Custom Aggregation, Report, and Filter Entities, page 193 addresses
how these types of report entities are created. This report is displayed when a dashboard user clicks
any of the Count of Started Instances columns in the Count of Processes per State report. This same
logic used in interpreting the process report can be applied to this report.
Understanding the In-flight Process Statistics report

This is a simple Bar+Line report built with the Incomplete Process Execution 5 Minutes report
entity. For each process, this report:
counts the number of instances that are running
provides the average duration (in minutes) process instances have been running
provides the duration (in minutes) of the longest running process instance (maximum duration)
These calculations are only available in report entities that aggregate data. The Incomplete Process
Execution 5 Minutes report entity is used because it provides near real-time data, with calculations
updated every five minutes. In addition, this report entity is filtered to include only those processes
that are in-flight since the last time the data was aggregated. The aggregation engine runs every
five minutes.
The Count of Ongoing Instances column is configured as a single drill-down report that opens the
In-flight Activity Statistics report when selected by a dashboard user.
In-flight Process Statistics report interpretation

At 1:02 PM a single Loan Application process (a process instance) is started. The aggregation engine
runs at 1:05 PM and this instance is now included in the reports in-flight calculation. At 1:10 PM the
aggregation engine runs again, and this process instance is still counted as being in-flight because it has
not yet completed. At 1:11 PM, the process instance is completed, but the instance is still considered
in-flight because the aggregation engine has not run again. At 1:15 PM, the aggregation engine runs
and this process instance is no longer included in the reports in-flight calculation.
170
Understanding the In-flight Activity Statistics report

The In-flight Activity Statistics report is configured as a single drill-down target report opened when
a dashboard user clicks the Count of Ongoing Instances column in the In-flight Process Statistics
report. This activity report is very similar to the process report. While the process report focuses on
aggregated processes, the activity report focuses on aggregated activities. This means that each group
of bars in the chart relate to aggregated activities, rather than specific activity instances.
For each activity, this report calculates:
the number of activity instances that are running for the selected process
the average duration (in minutes) activities within the selected process have been running
the duration (in minutes) of the longest running activity instance (this is the maximum duration)
TheIn-flight Activity Statistics report is a simple Bar+Line report built with the Incomplete Activity
Execution 5 Minutes report entity. This particular report entity is used because it provides near
real-time data, with calculations updated every five minutes. In addition, this report entity is filtered
to include only those activities that are in-flight since the last time the data was aggregated. The
aggregation engine runs every five minutes. This same logic used in interpreting the process report
can be applied to this report.
Understanding the Tasks Completed by Performer

within the last 24 Hours report
This is a Crystal Report that provides a count of work tasks completed by each performer within the
last 24 hour time period. Crystal Reports is required to calculate the total number of tasks completed
for each performer. Calculations are not available with simple reports. The report is based on the
Activity Performer 5 Minutes report entity where the Performer Name and Completed entity fields
are selected. The data source is filtered so that the result set displays rows for only those processes that
have completed (MSC.Completed-Instances > 0) during the last day (STD.Ended-During-Last-Day =
True). After the data source was defined, the report was opened in Crystal Reports. The following
graphic displays the raw data as it is first seen in Crystal Reports.
The next step in Crystal Reports was to configure a group-by function on the Performer Name field
and a sum function on the Completed field.
171
After the summary was configured, we see one row of data for each performer.
In the final step, the Chart Expert in Crystal Reports was used to format the data as a bar chart.
After the report was synchronized back into PRS, it was displayed by clicking the View tab.
172
Understanding the Tasks Pending for each Performer

report
This is a Crystal Report that calculates the total number of work tasks in each performers inbox.
This type of calculation is only available in Crystal Reports. The number of pending work items is
calculated by counting the number of activity instances that are in-flight for each performer. This
calculation is made possible by using the Activity Performer 5 Minutes report entity where the
On Going Instances and Performer entity fields are selected. This particular report entity is used
because it provides near real-time data, with calculations updated every five minutes. In addition, this
report entity is filtered to include only those activities that are in-flight (MSC.On-Going-Instances >
0) since the last time the data was aggregated (STD.Latest-Aggregation = True). The aggregation
engine runs every five minutes.
Within Crystal Reports a sum function is applied to the ongoing column and a group-by function is
applied to the performer column. Then, the report is formatted as a bar chart and synchronized back
into PRS.
Understanding the Alert Monitor dashboard

The primary purpose of the Alert Monitor dashboard is to provide detailed information about
processes and/or activities that have triggered alerts.
Note: This preconfigured dashboard does not have corresponding alerts defined for it in PRS. It only
contains reports about alerts. You must define alerts first, in PRS, and once triggered, the Alert
Monitor dashboard is populated with data.
All reports in this dashboard have been formatted in Crystal Reports. A description of how each report
is formatted in Crystal Reports is provided, however, detailed instructions are not provided. Please see
the Crystal Report documentation for more information.
Understanding the Alert List dashlet

The Alert List dashlet displays a list of all processes and/or activities for which an alert has been
triggered. Alerts are defined in the Alerts window of PRS. Once an alert is triggered, it populates
the Alert List dashlet with the name of the process or activity, its status, the date of the alert, the
name of the alert, the entity name (either a process name or an activity name), and the entity type.
Overview of Designing Alerts with Process Reporting Services, page 107 provides guidelines for
defining alerts in PRS.
Dashboard users can interact with this dashlet to edit the status of an alert that has been triggered.
Updating the status of an alert, page 162 describes how to work with the alert list dashlet.
Understanding the Alert Resolution report

When alerts are generated dashboard users have the option of selecting a status within the alert list
dashlet. To update the status the user must click the Edit button for a specific process or activity.
Within the edit window the dashboard user enters a note and selects a status. There are three statuses:
173
New, Acknowledged, and Closed. The Alert Resolution report counts the number of each type of
status and presents it in a bar chart. This report is defined as a Crystal Report that includes the Alert
report entity and Status entity field in the data source. In Crystal Reports the report was formatted to
count the number of alerts for each status.
Understanding the Alerts per Activity report

The Alerts per Activity report is a Crystal Report that counts the number of alert statuses for each
process. This means that each activity has a total of three bars in the report, with each bar representing
a count of alerts that are New, Acknowledged, and Closed. This report relies on aggregation. Within
Crystal Reports a sum function is applied to each status column, and then a group-by function is
applied to the activity column. Crystal Reports is used because of the unique stacked bar formatting.
This type of formatting is not available for simple reports.
Figure 52
Alerts per Activity report
Understanding the Alerts per Process report

The Alerts per Process report is a Crystal Report that counts the number of alert statuses for each
process. This means that each process has a total of three bars in the report, with each bar representing
the number of alerts that are New, Acknowledged, and Closed. This report relies on aggregation.
Within Crystal Reports a sum function is applied to each status column, and then a group-by function
is applied to the process column. Crystal Reports is used because of the unique stacked bar formatting.
This type of formatting is not available for simple reports.
Localizing the preconfigured dashboards

Installing a localized version of BAM does not automatically localize the preconfigured dashboards
shipped with the product. This is because the dashlets displayed in a dashboard are based on the reports
as defined in PRS, which are labeled in English. Localizing a preconfigured dashboard involves
changing the names of each report in PRS and then rebuilding the dashboard in TaskSpace. This
procedure assumes that you are familiar with:
Process Reporting Services
174
the BAM dashboard design tool

Crystal Reports
To localize the preconfigured dashboards:

1. Log into PRS and open the Preconfigured Dashboard report category. All preconfigured
dashboard reports are saved in their own category.
2. Make a copy of each report by right-clicking the report and selecting Copy. Then, right-click on
the report category to which it belongs and select Paste.
3. Right-click each copied report and select Rename.
4. Enter a new name for the report.
5. To localize simple report entity field captions, right-click the report entity within the Data Source
window and select Caption Editor. Then, change the name of each selected entity field caption.
6. To localize Crystal Reports entity field captions, open each report in the Crystal Reports
application. This is where captions must be modified. Then, the report must be saved and
synchronized back into PRS.
7. Single drill-down reports must be redefined in PRS:
a. Begin by opening the localized version of the In-flight Process Statistics report.
b. Select the Chart Data tab.
c. Configure the localized version of the Processes in Flight column to drill-down to the localized
version of the In-flight Activity Statistics report.
d. Open the localized version of the Count of Processes per State report.
e. Select the Chart Data tab.
f. Configure the localized version of the Count of Started Instances column to drill-down to the
localized version of the Count of Activities per State report.
8. Within TaskSpace, create three new dashboards. These should be localized versions of Process
Monitor, Process Summary, and Alert Monitor.
9. Add the dashlets to each dashboard.
Note: For a guide to laying out the report and diagram dashlets, please refer to the structure of
each original preconfigured dashboard.
10. Configure the multi-drill-down reports for the localized version of the Process Monitor dashboard
by selecting the Multi-Drill tab.
11. Then, configure the multi-drill-down reports as shown below.
Note: The figure below shows the original reports. These are changed to the new, localized reports.
175
12. Select the Dashlet Filter tab and configure the filter for the List of Process Instances report
as shown below.
Note: Your Dashlet Filter window will look different as it displays localized versions of the filters.
13. Open the Process Summary dashboard and configure the dashlet filters as follows.
Note: Your Dashlet Filter window will look different as it displays localized versions of the filters.
a. Select the Processes filter for the Count of Processes per State report.
b. Select the Processes filter for the In-flight Process Statistics report.
c. Select the Performer Name filter for the Tasks Completed by Performer report.
176
d. Select the Performer Name filter for the Tasks Pending for Each Performer report.
Once all changes have been made in the dashboard design tool, you must create new tabs within
TaskSpace and then add each dashboard to a tab. Tabs must be assigned to dashboard users.
177
178
Chapter 9
Administrating BAM Deployments
Overview of Administrating BAM Deployments
Using Documentum Composer to migrate BAM artifacts
Manually migrating custom entities designed with SDTs
Optimizing reports
Adjusting data transfer latencies in high load environments
Using business data and custom aggregation to enhance report performance
Increasing the gap filler step size
Monitoring BAM database table space
Increasing the BAM server step size
Clearing cache contents when running Crystal Reports
Reducing Simple report results sets
Limiting the number of records returned in a results set
Purging BAM execution and aggregation tables
Understanding how to schedule BAM database purge jobs
Scheduling BAM database purge jobs
Purging the Audit Trail database
Purging simple process variable and SDT reporting data from a repository
Saving historical data when process changes
Understanding how scheduled jobs are impacted by Daylight Savings Time
Overview of Administrating BAM Deployments

BAM, like many technology solutions and business applications, is usually deployed in phases. The
first phase of an implementation makes use of a BAM development environment. This is a technical
environment used for designing and configuring processes for monitoring, and designing dashboards.
Once development is complete the solution can be deployed to a BAM production environment.
Production environments are comprised of processes executing and being monitored in the real world,
with real performers and data. The production environment may already exist, or may be newly
created. Both approaches migrate objects from the BAM development repositories.
179
Process data is much more voluminous once BAM is operational in a production environment. As
a result, the size of the BAM database needs monitoring and adjusting periodically. Allocating the
appropriate space to a BAM database is very important. This topic is addressed in the Business
Activity Monitor Installation Guide. In some cases it may be necessary to purge old data from the
BAM database. Purge jobs can be scheduled to work against any of the execution database tables.
Using Documentum Composer to migrate BAM

artifacts
BAM application artifacts can be moved between Documentum environments. This is the case,
for example, when BAM artifacts are migrated from a development environment to a production
environment. BAM application artifacts are comprised of:
configuration settings
report definitions
dashboards
Documentum Composer is the product used to move BAM artifacts between environments. BAM
aritifacts are first imported into a BAM project. This results in the creation of a DAR file. Then, the
DAR file is installed on to a target environment. The DAR file is installed with either Composer or the
DAR Installer. This section addresses installing a DAR with Documentum Composer. For information
on the DAR installer see the Documentum Composer User Guide.
Composer is used to:
import BAM dashboards and report definitions as part of importing a TaskSpace application
Note: Composer automatically imports all dashboards and report definitions as part of importing a
TaskSpace application. In addition, for Simple reports only, Composer projects automatically
include single and multi-drill-down relationships with other reports. Once the DAR is installed
into the target environment all Simple report drill-down relationships are restored and no manual
intervention is necessary. For Crystal Reports, all drill-down target reports must be imported
individually into the DAR.
install BAM dashboards and report definitions as part of installing a TaskSpace application
import and install a single report definition
Note: This option should be used only when you need to add drill-down Crystal Reports or when
updating or adding specific reports to a target environment. When moving a complete dashboard
you must import and install a TaskSpace application.
import BAM configuration settings from one repository and install them on to another repository
Composer does not:
Create the BAM database. It is assumed that the Data Loader utility has been used to create the
database.
Create BAM objects. BAM objects are created with other client tools like Process Reporting
Services or Process Builder.
180
Importing BAM artifacts into a Composer project

Composer projects for BAM are comprised of BAM configuration settings, reports, and dashboards.
Dashboards and reports are both included in your DAR when you are migrating a TaskSpace
application. BAM configuration settings are always migrated separately. This procedure assumes you
are familiar with Composer. See the Documentum Composer User Guide for additional information on
using Composer.
To import BAM artifacts into Composer project:
1. Shut down the BAM server.
2. Log into Composer and create a new Documentum project.
3. Right-click anywhere in the left tree menu and select Import.
4. Select Artifacts From Repository and click Next.
5. Select (or enter) the project into which the BAM artifacts are being imported.
6. Select (or enter) the repository containing the artifacts being imported.
7. Enter the user name and password of the selected repository and click Login. This authenticates
the user makes the Next button active.
8. Click Next.
181
9. Select an artifact type from the pull-down list based on the following:
BAM Configuration this option imports all files used in the configuration of BAM.
TaskSpace Application this option imports BAM dashboards including all reports used
in a dashboard.
Report This option should be used only when you need to add drill-down Crystal Reports or
when updating or adding specific reports to a target environment. When moving a complete
dashboard you must import and install a TaskSpace application. All reports are listed whether
or not they are used in dashboards.
10. Each artifact type selected generates a list of individual artifacts. Select one or more artifacts from
the Choose From Available Artifacts field and click Add. This moves the artifact(s) to the
Selected Summary field.
11. Click Finish.
The BAM project is built and the DAR file is created.
Installing BAM artifacts into a repository

The import procedure creates a DAR file. Composer is then used to install the DAR file on to a target
environment. BAM artifacts can be installed into a new repository or into an existing repository.
Updating a repository overwrites all objects and adds objects that are new.
See the Documentum Composer User Guide for additional information on using Composer.
To install BAM artifacts into a new repository:
1. Shut down the BAM application server.
2. Log in to Composer.
3. Right-click anywhere in the left tree menu and select Install Documentum Project....
182
4. Select (or enter) the repository into which the BAM artifacts are being installed.
5. Enter the user name and password of the selected repository and click Login. This authenticates
the user.
6. Select Overwrite from the Install Option pull-down list.
7. Click Finish.
8. Restart the BAM application server.
Manually migrating custom entities designed

with SDTs
Database column names may change when moving a BAM application to a new repository. This has
direct impact on custom report entities and custom filter entities that include SDTs. When column
names change, all custom report and filter entities fail. To mitigate this problem you must create a
database view and manually migrate SDT custom entities.
To manually migrate SDT custom entities:
1. Use Documentum Composer to install the BAM application into a new repository.
183
2. Start the BAM server. This activates the SDT synchronization operation, which creates the
reporting and filter entities in the new environment. These must be in place before custom
entities are created.
3. In the BAM database look up the DEF_SDT_FIELDS table.
4. Locate the FIELD_COLUMN_NAME column. FIELD_COLUMN_NAME provides the
correct table names.
5. In the BAM database create a view on top of the SDT generated tables. The view creation syntax
must use the values from DEF_SDT_FIELDS to map column names using select statement aliases.
6. If you have saved the entity creation scripts used in the original environment, then update these
scripts to refer to the view you created rather than the original SDT table.
7. Run the custom report and filter entity creation scripts in the new repository. This creates the
custom report and filter entities.
Optimizing reports
In PRS, each report entity represents a query that is run against the BAM database and returns a result
set. Results for reports designed with multiple entities are generated using a logic equivalent to a
left outer join where the result sets of parent-child entities are combined in memory. The result of
a left outer join for table A and B always contains all records for table A (the left table), even if no
matching records are found in table B (the right table). See Understanding how data source results
are generated, page 46 for more information.
Note: BAM runs a left outer join in memory. BAM does not run a left outer join query on the database.
The greater the amount of data each query returns, the more memory is used for generating a report.
If your report returns up to a few hundred records then it is possible to use more entities, up to a
maximum of 20 levels. However, if your report returns a few thousand records then you should
optimize your report by limiting the number of report entities to approximately five, maximum.
Report performance is also impacted by the number of columns selected in each entity. The more
columns selected, the fewer report entities should be used. These are general guidelines since system
performance depends on a number of factors, including the size of the records retrieved and the size of
each report entity query. The number of report entities used should be adjusted for your deployment.
Other methods of optimizing reports include:
Configuring business data aggregation, page 90
Configuring custom aggregation, page 194
Creating custom report entities, page 199
Configuring PRS filter entities, page 217
Adjusting data transfer latencies in high load

environments
For audited activities BAM relies on Content Server to write events to the Audit Trail database.
Typically, these Content Server transactions take only a few seconds to complete. But in high load
184
environments where Process Engine handles large volumes of workflows simultaneously Content
Server transactions can take much longer to complete. . When this happens the data transfer latency
should be increased. By default, the data transfer latency is set to 30 seconds. This means that every
five seconds the BAM server collects events from the Audit Trail database that occurred 30 seconds in
the past. This 30 second offset is called the data transfer latency.
In high load environments where Documentum application system performance is slow, there is a
chance that transactions are not completed for up to a few minutes. In this case you must increase
the data transfer latency to five minutes or more. Documentum application system performance
metrics can help you establish a latency interval. Configuring data transfer latency, page 36 explains
how to adjust the data transfer latency.
Using business data and custom aggregation

to enhance report performance
Report aggregation is an excellent approach to use when prototype dashboard reports are being
designed and tested. It provides flexibility to test different designs, and compare the report output with
desired results. Report aggregation is also a viable approach in a production environment that has
limited process execution data. If high volumes of data are anticipated then business data aggregation
and custom aggregation should be used.
Note: For BAM installed on a 32-bit machines, reports that consist of 20,000 records is considered
high volume.For BAM installed on 64-bit machines, reports that consist of 100,000 records is
considered high volume.
Report aggregation on large volumes of data compromises BAM system performance. This is because
the BAM server uses system resources to perform the calculations and stores result sets in memory.
Business data and custom aggregation works differently by performing the calculations ahead of
time, and storing the result set in database tables rather than memory. This frees up memory. As a
result, the response time for displaying a report to a dashboard user is shorter when business data and
custom aggregation is used.
The aggregation job for business data and custom entities is the same mechanism used by server
aggregation, page 58. The aggregation tables are created once the business data and custom
aggregation procedures are completed. Improved report performance is the primary benefit of using
business data and custom aggregation.
Report performance is also impacted by:
the size of the report record
the number of concurrent users running reports
the number of report entities used in a reports data source
For more information, see Configuring business data aggregation, page 90 and Configuring custom
aggregation, page 194.
185
Increasing the gap filler step size

Events continue to be inserted into the Audit Trail database even when the BAM server is offline for
any reason. The gap filler allows the BAM server to quickly catch up on missed events. During gap
filling, the BAM server retrieves events from the Audit Trail database in five minute time intervals.
Each five minute time interval of data is collapsed into a single transaction. This time interval is called
the gap filler step, and can be increased by running an update against the BAM database. The default
step size is five minutes, but this can be adjusted. Increasing the step size results in fewer, but larger
transactions, and improved system performance. The size of gap filler transactions, which correspond
to the number of records retrieved, must also be considered. This is because the size of gap filler
transactions is limited by free memory on the BAM server.
To increase the gap filler step:
2. Run the following update against the BAM database:
update i_bam_server_config set GAP_FILLER_STEP = <Enter gap filler
step in minutes> WHERE servername = DCTMServer
Monitoring BAM database table space

During installation, BAM databases should be sized to meet anticipated volumes of process data. The
initial size of the database can be calculated using the BAM Database Sizing Calculator available on
the EMC Download Center. In production environments the BAM database table space needs to be
monitored and adjusted periodically. This should be done by a database administrator with tools
provided by the database vendor. If required, BAM database tables can be purged. Scheduling BAM
database purge jobs, page 190 outlines a purging procedure.
Increasing the BAM server step size

Every five seconds the BAM server runs the event pipe job that extracts data from the Audit Trail
database and inserts it into the BAM database. This five second time interval is the step size, and can
be adjusted in high volume environments. Although there is no absolute definition, 500 events or more
per minute is generally considered high volume. Increasing the step size enhances performance in
two ways:
1. Although the BAM server runs the event pipe job less frequently, the job runs longer and more
efficiently.
2. Since the job is running less frequently, the size of each transaction is larger than for a step size of
five seconds. Larger transaction sizes also make the BAM server operate more efficiently.
The BAM server step size can adjusted to any time period by substituting a value for 60 in the query
below. The following procedure increases the BAM server step size to one minute.
To increase the BAM server step size:
186

2. Run the following query on the BAM database:
I_BAM_SERVER_CONFIG SET SCHEDULEPERIOD = 60 WHERE SERVERNAME = DCTMServer
Clearing cache contents when running Crystal

Reports
An administrator should periodically clear the contents of the Crystal Reports cache folder in order to
improve report performance. This is only necessary when thousands of dashboard users view Crystal
Reports. The _CrystalTempCachedReports folder is located under the application server domain.
The administrator must reserve enough disk space for this cache.
Use the following guidelines to calculate the amount of disk space to reserve:
Reserve 1.5 MB of disk space for one report with 2000 rows of data.
If 1000 users are running a single report with 2000 rows of data, then reserve 1.5 GB of disk space.
If 10,000 users are running a single report with 2000 rows of data, then reserve 15 GB of disk space.
Reducing Simple report results sets

Simple table reports that contain hundreds or thousands of rows do not display correctly in a
dashboard. To remedy this problem, a limit is placed on the number of rows returned for a results set.
The number of rows returned in a results set is controlled by a maxTableReportRows parameter in
the dashboardProperties.xml file. By default, the number of rows returned is 15000. A value of 1
returns all rows. If a report results set exceeds the maximum number of rows, a message is displayed
to a dashboard user informing them to either:
Filter the report to reduce the results set.
Call a system administrator. A system administrator has the authority to modify the
maxTableReportRows parameter.
To modify the maxTableReportRows parameter:
1. Navigate to ...\taskspace\config\dashboard.
2. Open the dashboardProperties.xml file.
3. Enter a value in the maxTableReportRows parameter.
5. Restart the TaskSpace server.
187
Limiting the number of records returned in a

results set
The number of records returned for a report can be increased or decreased by modifying the maxRows
parameter in the jdbc-config.xml configuration file. Controlling the number of records retrieved is
especially important for reporting, since large results sets can negatively impact system performance
and may lead to an out-of-memory error. The number of records retrieved is specified in the maxRows
element of an .XML file. If no value is entered the BAM server returns 1,000 rows by default.
Note: This parameter can be set to zero (0). This sets the maximum number of rows returned to be a
function of the JDBC driver.
To limit the number of records returned in a results set:
1. Open the bam-server.war or the bam-server.ear archive file.
2. Navigate to WEB-INF\classes\config\.
3. Open the jdbc-config.xml file.
4. Update the value entered in the <maxRows> element.
Purging BAM execution and aggregation tables

A BAM database can quickly be filled with thousands of records. Therefore, the amount of space
allocated to a BAM database during installation is very important. Calculating the size of a BAM
database is addressed in the Business Activity Monitor Installation Guide. Once a BAM database nears
its capacity, purging becomes important. There are two methods available:
Purging all execution and aggregation data from the BAM database immediately, or
Scheduling purge jobs to run periodically against a subset of BAM tables (addressed in Scheduling
BAM database purge jobs, page 190).
This section addresses how to run a cleanup script that purges all execution and aggregation data
from the BAM database.
Note: The purge operation only deletes execution data. It does not delete the database tables.
To completely purge a BAM database:
1. From the installation files you downloaded from the EMC Download Center, navigate to <BAM
Data Loader>\bin.
2. To purge a BAM database installed on a Windows platform, run cleanup-db-execution-data.cmd.
3. To purge a BAM database installed on a Linux/Unix platform, run cleanup-db-execution-data.sh.
188
Understanding how to schedule BAM database

purge jobs
Scheduling purge jobs to run on a periodic basis is the second method available for deleting data from
a BAM database. Purge jobs can be scheduled for both instance and aggregation tables. The BAM
server uses Quartz to schedule purge jobs. A Basic schedule is configured using radio buttons and
pull-down lists. Advanced schedules are configured by way of a cron expression. A cron expression
is a string of text divided into 7 sections, with each section representing a different dimension of a
schedule. These dimensions are:
seconds
minutes
hours
day of month
month
day of week
year (optional)
Each section has a defined set of allowed values and characters. For more information on defining
cron expressions please refer to: http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html
and http://www.opensymphony.com/quartz/wikidocs/TutorialLesson6.html.
The following table provides a number cron expressions and their meaning.
Table 18
Example Cron Expression
Cron expression
Meaning
0 0 12 * * ?
Purge at 12 pm every day
0 15 10 ? * *
Purge at 10:15 am every day
0 15 10 * * ? 2005
Purge at 10:15 am every day during the year 2005
0 * 14 * * ?
Purge every minute starting at 2 pm and ending at 2:59 pm, every day
0 0/5 14 * * ?
Purge every 5 minutes starting at 2 pm and ending at 2:55 pm, every

day
0 0/5 14,18 * * ?
Purge every 5 minutes starting at 2 pm and ending at 2:55 pm, AND

fire every 5 minutes starting at 6 pm and ending at 6:55 pm, every day
0 0-5 14 * * ?
Purge every minute starting at 2 pm and ending at 2:05 pm, every day
0 10,44 14 ? 3 WED
Purge at 2:10 pm and at 2:44 pm every Wednesday in the month of

March.
0 15 10 ? * MON-FRI
Purge at 10:15 am every Monday, Tuesday, Wednesday, Thursday

and Friday
0 15 10 15 * ?
Purge at 10:15 am on the 15th day of every month
0 15 10 L * ?
Purge at 10:15 am on the last day of every month
0 15 10 ? * 6L
Purge at 10:15 am on the last Friday of every month
189
Cron expression
Meaning
0 15 10 ? * 6L 2002-2005
Purge at 10:15 am on every last Friday of every month during the

years 2002, 2003, 2004 and 2005
0 15 10 ? * 6#3
Purge at 10:15 am on the third Friday of every month
Both types of purge schedules (basic and advanced) include an interval buffer. An interval buffer is
the amount of data to which the purge job does not apply. It provides a safety net in case data is
mistakenly purged. For example, if the integration table is scheduled to purge every Wednesday at
12 noon with a 4 hour interval buffer, then the purge job would delete all data except that captured
between 8 am and 12 noon on Wednesday.
Note: There are several automatic purgers used for aggregated data. These purgers run on a daily basis
at 11:00 PM and leave one week while deleting all other aggregated data. The table below summarizes
the aggregation time period and type of data purged:
Table 19
Automatic purgers
Time interval
Aggregation tables
5 minutes
Activity, process, performer, incomplete activity, incomplete process
15 minutes
30 minutes
Activity, process, performer
1 hour
Scheduling BAM database purge jobs

This procedure guides you in scheduling BAM database purge jobs.
To schedule purging:
3. From the left tree menu select Server Management > Business Activity Monitoring > Clean
History Data.
4. Select a BAM table.
5. Click the Edit button located at the bottom of the form. This opens a scheduler window.
6. To create a basic schedule:
a.
b.
c.
d.
e.
Select the Basic radio button.

Select either the Weekly, Monthly, or Yearly radio button.
Use the pull-down lists to select a scheduling time interval.
Use the radio buttons and pull-down lists to select an interval buffer.
Click Ok.
7. To create an advanced schedule with a cron expression:
a. Select the Advanced radio button.

190
b. Enter a cron expression in the field provided.

c. Use the radio buttons and pull-down lists to select an interval buffer.
d. Click Ok.
Purging the Audit Trail database

Business Activity Monitor formats and aggregates process data written to the Documentum Audit Trail
database. Over time, audit trail entries take up a lot of space in your repository, which compromises
system performance. Once audit trail data is formatted and aggregated, it is no longer needed.
Therefore, you should periodically purge these entries out of the database.
You should purge records from the Audit Trail database only up to the last time the FormatGeneric
job is run by the BAM server. This prevents loss of data by purging records that have been formatted
by the BAM server and inserted into the BAM database and leaving those records that have not yet
been formatted.
Run the following query against the BAM database to determine when the FormatGeneric job was
last run:
select LAST_PIPE_RUN from I_BAM_SERVER_CONFIG where SERVERNAME =
FormatGeneric
Refer to the Audit management (dm_AuditMgt) and Modifying jobs sections of the Documentum
Administrator User Guide for guidance in configuring a purge audit job.
Purging simple process variable and SDT

reporting data from a repository
Over time, simple process variable and SDT reporting entries take up a lot of space in your repository,
which compromises system performance. Once this data is piped to the BAM database, it is no longer
needed. Therefore, you should periodically purge these reporting entries from your repository.
Runtime data is collected and stored in simple process variable and SDT object types that are created
as an extension of the dmc_wfsdrp_parent object type. When the purge command is run, all simple
process variable and SDT reporting entries are deleted.
Runtime data is purged from a repository by executing a DQL command. The DQL command contains
a cutoff_date value and a buffer value. These values work together. The cutoff date establishes a date
before which the runtime data is purged. For example, a cutoff date of November 19, 2010 means that
data up to and including November 18, 2010 is purged. Do not delete runtime data until it is piped to the
BAM database. Query the i_bam_server_config table to understand when the piping process last ran:
select last_pipe_run from i_bam_server_config where
servername = DCTMServer
Do not delete records that occur later than the date returned by the query.
The buffer value is added to the cutoff date to establishes a new range for purging. A buffer is the
number of days before the cutoff date to which the purging applies. For example, if the cutoff date
is November 19, 2010 and the buffer is 4 days, then only process variable data up collected through
November 14th is purged.
191
The DQL command to purge process variable data N days earlier than the cutoff date is:
DQL>delete dmc_wfsdrp_parent objects where DATEDIFF(day,
time_stamp_utc, cutoff_date) > N
Purge process variable data DQL command

The DQL command to purge process variable data four days earlier than 11/19/2010 12:00:00 AM is:
DQL>delete dmc_wfsdrp_parent objects where DATEDIFF(day,
time_stamp_utc, date(11/19/2010 12:00:00 AM)) > 4
Saving historical data when process changes

Once a process is monitored, any change to the process, or any of the SDT or package attributes
requires that BAM recreate the database tables used in reporting. This means that data already held in
these tables is sometimes lost. If this data is important to you for any reason, you should back up the
BAM database before making any change to the process.
Understanding how scheduled jobs are

impacted by Daylight Savings Time
The BAM server aggregates process data into nine time intervals. Understanding server aggregation,
page 58 provides more information about aggregation. If the machine on which the BAM server
is installed is located in a time zone that observes Daylight Savings Time (DST), then the daily
aggregation time interval is automatically adjusted to compensate for these events. Within the
bam-server.war file there is an env-config.xml file that holds a DST offset flag. By default this flag is
set to true. The offset flag explicitly adjusts the time for the aggregation job on the day on which the
DST event takes place. The offset shifts the daily aggregation period by one hour (+1 or -1), which
ensures that the daily aggregation is calculated on data gathered between 12:00 AM and 12:00 AM.
The env-config.xml file is found in ...\<bam-server.war>\WEB-INF\classes\config. The DST offset
flag is set to true, but can be changed to false: <adjustDstOffset>true</adjustDstOffset>
The BAM application server must be restarted if the DST offset flag is changed.
192
Chapter 10
Creating Custom Aggregation, Report,
and Filter Entities
Understanding custom aggregation, report, and filter entities
Configuring custom aggregation
Overview of creating custom report entities
Configuring custom filters
Refreshing the BAM server
Deleting custom report and filter entities
Understanding custom aggregation, report, and

filter entities
PRS is used to design reports and alerts on data stored in the BAM database. PRS includes many
report and filter entities that expose data in various ways. Although the report and filter entities
shipped with BAM offer many reporting options, there are times when they are not sufficient for your
implementation. In these cases you must create custom aggregation, custom report, and custom
filter entities. If you want to aggregate data in a manner not supported out-of-the-box, then custom
aggregation tables must be created. Custom report entities are created to report on data stored in
custom aggregation tables. There are times when the filters available with the product are not
sufficient. In this case custom filters also designed.
The purpose of this chapter is to explain the concepts and procedures involved in creating custom
aggregation tables, custom report entities, and custom filter entities. The intended audience for this
chapter includes database administrators or database SQL developers with extensive knowledge in
SQL.
Note: Creating custom entities requires executing SQL statements and formulating DQL queries.
Therefore, it is highly recommended that you save the statements in a file. Saving the statements in a
file makes the transition from a development environment to a production environment easier, since all
entities are recreated for each new deployment.
The scenario presented in this chapter is based on an order fulfillment process. An order fulfillment
process captures the details of each customer and the customer order. The business data is modeled
in Process Builder as an SDT with the name ORDER_FORM. For this exercise, the SDT contains a
single field with the name US_STATE. The report designer in this scenario wants a report to show, for
a given time period, the trend of new orders fulfilled from a particular state. The report must aggregate
order fulfillment data on a daily basis. The Process Execution Daily report entity is not sufficient for
193
Creating Custom Aggregation, Report, and Filter Entities
this report, because it does not make a state-by-state distinction. To report on the custom aggregation
data, custom report entities and filter entities are also created.
Configuring custom aggregation

Aggregation provides summary level reports of process instance data. There are two basic types of
aggregation: report aggregation and server aggregation. Report aggregation aggregates report results
in memory, when a report is requested from a dashboard. Because it relies on system memory, report
aggregation is appropriate for reports with fewer rows. By contrast, server aggregation inserts results
sets into the BAM database, rather than storing them in memory. Server aggregation works in advance
of a report being requested from a dashboard. This approach to aggregation is appropriate for large
reports. Understanding reports that use aggregation, page 57 describes the concept of aggregation.
Custom aggregation is one type of server aggregation. Custom aggregation is required when users
want to use server aggregation, but the aggregation dimension and measurement combination is not
available with the standard aggregation entities (process aggregation, activity aggregation, business
data aggregation).
Custom aggregation jobs are configured to occur on a periodic basis, collapsing data into one or
more of the following time intervals:
5 minutes
15 minutes
30 minutes
Hourly
Daily
Weekly
Monthly
Quarterly
Yearly
Not all time intervals are required. Custom aggregation allows for specific time intervals to be
selected. It is possible to schedule a custom aggregation job for the one hour time interval, but not
for the five minute time interval. The time interval is specified in a DQL script that creates the
custom aggregation objects.
To configure custom aggregation:
1. Create a custom aggregation table in the BAM database by running a SQL script against the BAM
database. The custom table stores the custom aggregation query results. The name of this table
is used in the DQL script that creates the aggregation object.
Use the following template to create the aggregation table:
CREATE TABLE [Custom Aggregation Table Name](
[Dimension Field definition 1],,
[Dimension Field definition N]
START_JAVATIME NUMBER,
START_DATETIME TIMESTAMP,
194
END_DATETIME TIMESTAMP,
[Measurement column definition 1 ],,
[Measurement column definition N ]);
Note: The aggregation table must contain the START_JAVATIME, START_DATETIME, and
END_DATETIME columns. These columns must be type in upper case letters.
Note: Use the following data types:
Oracle
Character string values: VARCHAR2(size)
START_JAVATIME: NUMBER(38) NOT NULL
Date Time values: TIMESTAMP
Integer values: NUMBER(precision)
Boolean: VARCHAR2(size)
Float: NUMBER(precision)
SQL Server:
Character string values: NVARCHAR(size)
START_JAVATIME: NUMERIC(38) NOT NULL
Date Time values: DATETIME
Integer values: BIGINT or INT
Boolean: NVARCHAR(size)
Float: NUMERIC(precision)
DB2
Character string values: VARCHAR (size)
START_JAVATIME: NUMERIC(31) NOT NULL
Date Time values: TIMESTAMP
Integer values: BIGINT or INT
Boolean: VARCHAR (size)
Float: NUMERIC(precision)
2. Run a DQL script that defines a custom aggregation job. To define a custom aggregation job:
a.
Define a custom SQL insert statement. The custom query is stored in the aggregation table,
and specifies the columns included in the aggregation. Store the query in a text file (.txt) in a
location accessible to the repository, according to the DQL SETFILE command specification
(for instance, c:\query.txt).
Use the following template to define the SQL insert statement:
INSERT INTO [Custom Aggregation Table Name]
([Dimension Field definition 1],,
[Dimension Field definition N]
[Measurement column definition 1 ],,
195
[Measurement column definition N ])

SELECT [Group By Colum 1],, [Group By Colum N],
:JAVATIME, :FROMDATE, :TODATE,
[Aggregation Function 1],,[Aggregation Function N]
FROM [From Clause]
WHERE [Condition to limit query aggregation period between :FROMDATE
and TODATE timestamp values]
AND [Other conditions]
[Group by clause]
Note: This script must contain three parameters: FROMDATE, TODATE, and JAVATIME.
b.
Add an aggregation job by creating a bam_custom_aggr object.

Use the following template to define the aggregation job:
CREATE bam_custom_aggr object
set object_name = [Aggregation time range],
setfile [Custom Aggregation SQL script file] with content_format=text;
Valid aggregation time ranges are listed in the following table.

Table 20
Custom aggregation object names
Type
Meaning
AggrCustom5m
5 minutes
AggrCustomQH
15 minutes
AggrCustomHH
30 minutes
AggrCustomH
Hourly
AggrCustomD
Daily
AggrCustomW
Weekly
AggrCustomM
Monthly
AggrCustomQ
Quarterly
AggrCustomY
Yearly
Note: To create more than one custom aggregation for the same time interval, then both
aggregations have the same object_name. For development purposes, save the object_id returned
by the CREATE bam_custom_aggr statement.
Custom aggregation example

In this example, a daily aggregation counts the number of orders submitted for each state. The first
step is to create a custom table called ORDERS_BY_STATE_D.
CREATE TABLE ORDERS_BY_STATE_D(
STATE VARCHAR2(256),
ORDER_COUNT NUMBER(38));
196
A custom query is written to run every day and count the number of customer orders for each US
state. This script is saved in the repository and must contain three parameters: FROMDATE,
TODATE, and JAVATIME. In addition, ATTR0 is a column that corresponds to the STATE field
in the ORDERS_BY_STATE database table. The relationship between the column name and the
field name is found in the def_sdt_field table. The table name for this particular SDT is found in the
def_sdt_tables table.
The second part of this query creates the custom aggregation object.
INSERT INTO ORDERS_BY_STATE_D(STATE, START_JAVATIME, START_DATETIME,
END_DATETIME, ORDER_COUNT)
SELECT SDT.ATTR0, :JAVATIME, :FROMDATE, :TODATE,
COUNT(EXEC_PROCESS_INSTANCE.ID)
FROM EXEC_PROCESS_INSTANCE, EB_ORDERSBYSTATE SDT
WHERE END_DATETIME >= :FROMDATE
AND END_DATETIME < :TODATE
AND EXEC_PROCESS_INSTANCE.INSTANCEID = SDT.INSTANCEID
GROUP BY SDT.ATTR0
create bam_custom_aggr object set object_name =AggrCustomD,
setfile c:\query.txt with content_format=text;
go
To debug the aggregation runtime query, refer to the bam-engine.log file available with the log folder
of the application server directory.
To run reports against the aggregation table you must create reporting and filter entities in the BAM
database. For more information see Creating custom report entities, page 199 and Configuring PRS
filter entities, page 217.
Overview of creating custom report entities

This section addresses how to create report entities and relationships, add entity fields to an existing
report entity, and create an entity from a database function.
Understanding report entity tables

Business Activity Monitor report entities are virtual views built on top of an existing table space. In
their simplest form, report entities are mapped in a one-to-one relationship to a table or view. In
more complex cases, report entities have one-to-many relationships with several tables or views. For
these complex cases, it is recommended that a database view be created to represent the data for the
report entity, and then map the view to the report entity. Report entity tables are comprised of two
types of tables: entity definition tables (mandatory) and entity relation tables (optional). The following
text describes each of the entity definition tables.
197
bami_rg_entity: An entry into this table declares a new report entity.

entity_type: Entity_type is a unique name given to the report entity. This name is also used
for creating custom filters.
gui_display_name: The display name is the same value as entity_type.
is_base_entity: This column defines whether the entity can be used as the root of a report, or is
only available as a child of another report entity.
entity_where_clause: If the report entity represents a one-to-one relationship
between the report entity and the table or view, then the entity_where_clause
value is 1=1. If the report entity represents a one-to-many relationship, the
entity_where_clause uses a join expression to correlate the tables or views. For example,
EntityTable0.CUSTOMER_ID=EntityTable1.CUSTOMER_ID.
bami_rg_entity_table: An entry into this table adds a table reference to the report entity. For
example, if your report entity selects from table A, then table A must be defined in this object type.
table_name: A table or view name from which the report entity queries data.
table_index: The table index is a unique number assigned to a table. Once the select statement is
generated, the table_name is referenced as EntityTable+table_index.
entity_id: This column contains the id reference to the bami_rg_entity entry created for the report
entity. Within the DQL script the entity_id has a value similar to: set entity_id=(select r_object_id
from bami_rg_entity where gui_display_data = %name of the report entity% ))
bami_rg_entity_field: An entry into this table adds a field to the report entity.
entity_table_id: This column contains the id of the bami_rg_table entry for the corresponding
table. Within the DQL script the entity_table_id has a value similar to: select r_object_id from
198
bami_rg_entity_table t,bami_rg_entity e where t.entity_id=e.r_object_id and e.gui_display_data

= %name of the report entity% and t.table_index= table_index).
field_index: This column contains a unique index number for each field. The field_index value
must be unique for each report entity.
field_db_name (oracle, mssql, db2): This represents the actual column name within the
corresponding table. This value must be provided for each supported database.
field_gui_name: The field_gui_name is the name of the field displayed in PRS.
field_type: Enter the type of field that is created. For:
String enter 0
Numeric enter 1
Date enter 2
If the field type is not entered, it is automatically set to 0 (String).
bami_rg_entity_key: An entry into this table represents the primary key for the report entity.
entity_table_id: This column references a foreign key to a bami_rg_entity_table entry.
Within the DQL script it the entity_table_id has a value similar to: select r_object_id from
bami_rg_entity_table et,bami_rg_entity e where et.entity_id=e.r_object_id and e.gui_display_data
=%name of the report entity% and et.table_index= table_index).
key_index: Each entity key must have a unique index number within the context of the report
entity.
field_name: Field_name contains the column name of the key selected from the entry in the
bami_rg_entity_table.
Creating custom report entities

Custom report entities can be created once database tables and/or views are available in the BAM
schema. Custom report entities can also be created directly against the external tables through database
links. Custom report entities provide the PRS report designer with objects with which to define the
data source of a report. The report entity contains entity fields that map to columns in the database.
The procedure below builds on the example in the previous section. The result is a report entity for the
ORDERS_BY_STATE_D table, calculating the number of customer orders received on a given date,
for each state. At this point, the new entity is not related to other entities and does not have any filters
defined. The example illustrates the minimum required data for a reporting entity to be operational.
Table 21
Segments of report entity query
Segment
Meaning
Entity Type
The process entity by which the report entity can be

filtered. This affects the list of filters available for the
report entity. Multiple report entities can have the
same entity type, so that filters can be shared.
Is Base Entity
Enter True if the report entity can be used as the first

entity in a report. This is also called a base entity.
199
Segment
Meaning
Entity Where (clause)
The where clause for this entity, based on the tables

selected. Always use the alias Entity Table[N].column
name, where N is the index of the entity table.
GUI Display Data
A unique name for the entity. This name is displayed

to the report designer.
CAUTION: When reporting on external data it is recommended that you not create the report
entity on a database view that is based on a database link. Instead it is recommended that you
create new tables based on external data and update regularly. You should create the report
entity on the aggregation entity.
To create a custom report entity:
2. Launch IDQL 32. It can be found on the system where Content Server is installed, under the
%DM_HOME%\bin directory.
3. Execute the create object DQL statement below. This step creates the Orders By State Daily
report entity.
create bami_rg_entity object
set entity_type=Orders By State Daily,
set is_base=True,
append entity_where=1=1,
set gui_display_data=Orders By State Daily,
set acl_name=BAM Admin ACL,
set acl_domain=dm_dbo,
link /System/BAM/Custom Entities
go
4. Execute the create object DQL statement below. This statement defines a relationship between a
report entity and a custom defined table/view. This relationship is based on the report entity
created in Step 3. The table/view must have already been created. In this example the new report
entity will display data from a single table: ORDERS_BY_STATE_D (table_index=0).
create bami_rg_entity_table object
set entity_id=(select r_object_id from bami_rg_entity where gui_display_data
=Orders By State Daily),
set table_index=0,
set table_name=ORDERS_BY_STATE_D,
go
5. Execute the create object DQL statement below. This statement defines a key for the Orders By
State Daily report entity which is used when applying filters to the report entity.
create bami_rg_entity_key object
set entity_table_id=(select et.r_object_id from bami_rg_entity_table
et,bami_rg_entity
e where et.entity_id=e.r_object_id and e.gui_display_data =Orders
200
By State Daily
and et.table_index=0),
set key_index=0,
set field_name=STATE,
go
6. Execute the create object statements below. This step defines the columns from each table that
are exposed to the report designer as entity fields. If these statements are not executed, then
no entity fields will be available. In this example, the Started Date and Time, Ended Date
and Time, State, and Number of Orders entity fields are populated with data taken from the
ORDERS_BY_STATE_D table. The relationship between the entity field name and the tables
is defined by way of an index. The entity field can be selected by default within the report
entity. This is specified in set select_as_default (True or False). The example also includes the
convention for each supported database.
This script adds the Start Date and Time field.
create bami_rg_entity_field object
set entity_table_id=(select t.r_object_id from bami_rg_entity_table t,
bami_rg_entity e where t.entity_id=e.r_object_id and e.gui_display_data =
Orders By State Daily and t.table_index=0),
set field_index=0,
append field_db_name=START_DATETIME,
append field_db_name_oracle=START_DATETIME,
append field_db_name_mssql=START_DATETIME,
append field_db_name_db2=START_DATETIME,
set field_gui_name=Start Date and Time,
set field_type=2,
set select_as_default=True,
set select_rep_values_default=False,
go
This script adds the End Date and Time field.
set field_index=1,
append field_db_name=END_DATETIME,
append field_db_name_oracle=END_DATETIME,
append field_db_name_mssql=END_DATETIME,
append field_db_name_db2=END_DATETIME,
set field_gui_name=End Date and Time,
set field_type=2,
201
go
This script adds the State field.
set field_index=2,
append field_db_name=STATE,
append field_db_name_oracle=STATE,
append field_db_name_mssql=STATE,
append field_db_name_db2=STATE,
set field_gui_name=State,
set field_type=0,
go
This script adds the Number of Orders field.
set field_index=3,
append field_db_name=ORDER_COUNT,
append field_db_name_oracle=ORDER_COUNT,
append field_db_name_mssql=ORDER_COUNT,
append field_db_name_db2=ORDER_COUNT,
set field_gui_name=Number of Orders,
set field_type=1,
go
7. Restart the BAM application server for changes to take effect. The new report entity will be
available in PRS.
Creating relationships between two entities

More complex reports are designed with multiple report entities arranged in parent-child relationships.
For example, the Activity Execution entity is a child of Process Execution. These relationships are
displayed in the report design palette in PRS. Custom report entities, too, can be defined to have
parent-child relationships. It is possible to define relationships with other custom report entities, or
with existing entities. Creating a relationship between two report entities requires that you know
the parent entity id and the child entity id values. Entity id values are the r_object_id fields of the
bami_rg_entity table.
202
Use the following DQL statement to find the parent entity id and child entity id values:
Select r_object_id, gui_display_data from bami_rg_entity
go
r_object_id is the entity identification number

gui_display_data is the name of the report entity as it is displayed in PRS
Table 22
Segments of entity relations query
Segment
Meaning
Parent Entity Id
The process entity by which the report entity can be filtered. This affects
the list of filters available for the report entity. Multiple report entities can
have the same entity type, so that filters can be shared.
Where Clause
The SQL Where Clause to relate the parent entity to the child entity.
When referring to a Parent entity, you can only use Keys of the entity. To
relate to any parent key value, you must use the following convention:
parent_entity.ID[Key Index]. You can use any value from the Child entity.
To relate to a child entity table, you should use the EntityTable[table
index] alias. The Parent Keys and Child Keys lists are available while
writing the Relation where clause.
In the following example, a parent-child relationship is defined between two entities. The parent
entity is Orders By State Daily, which was defined in the previous procedure. The child entity
will be a new table that provides more details for every state in the United States. Assume that this
tables structure is the following:
CREATE TABLE US_STATES (
STATE_ABBREVIATION VARCHAR(256), STATE_FULLNAME VARCHAR2(256))
To create a relationship between two report entities:

1. Execute the create object statements below. These statement creates the report and field entities
for the US_STATES table.
This script creates a US States report entity.
create bami_rg_entity object
set entity_type=US States,
set is_base=True,
append entity_where=1=1,
set gui_display_data=US States,
go
This script defines a relationship between the report entity and a table/view.
create bami_rg_entity_table object
set entity_id=(select r_object_id from bami_rg_entity where gui_display_data
=US States),
set table_index=0,
set table_name=US_STATES,
203
go
This script adds the State Abbrevation field.
US States and t.table_index=0),
set field_index=0,
append field_db_name=STATE_ABBREVIATION,
append field_db_name_oracle=STATE_ABBREVIATION,
append field_db_name_mssql=STATE_ABBREVIATION,
append field_db_name_db2=STATE_ABBREVIATION,
set field_gui_name=State Abbreviation,
set field_type=0,
go
This script add the State Full Name field.
US States and t.table_index=0),
set field_index=1,
append field_db_name=STATE_FULLNAME,
append field_db_name_oracle=STATE_FULLNAME,
append field_db_name_mssql=STATE_FULLNAME,
append field_db_name_db2=STATE_FULLNAME,
set field_gui_name=State Full Name,
set field_type=0,
go
2. Then, a relationship between US States and the Orders By State Daily report entity is defined.
The following DQL statement first creates a new entity key object that is used in defining the
relationship between the two report entities. The entity key object is used in the where clause
in Step 3.
create bami_rg_entity_key object
set entity_table_id=(select et.r_object_id from bami_rg_entity_table et,
bami_rg_entity e where et.entity_id=e.r_object_id and e.gui_display_data =
US States and et.table_index=0),
set key_index=0,
set field_name=STATE_ABBREVIATION,
204

go
3. Execute the create object statement below. This statement defines a relationship between the
US States report entity and Orders By State Daily report entity. The where clause uses the
entity key object created in Step 2.
create bami_rg_relation object
set parent_entity_id=(select r_object_id from bami_rg_entity where
gui_display_data=Orders By State Daily),
set child_entity_id=(select r_object_id from bami_rg_entity where
gui_display_data=US States),
append where_clause=parent_entity.ID0=EntityTable0.STATE_ABBREVIATION,
set distinct_relation=False,
set description_code=,
go
Adding a field to a report entity

There are times when an existing report entity does not contain an entity field that is required. In the
procedure below the Sum of Order Amounts field is added to the Orders By State Daily report
entity. The field index value is set to 4 because it is the next identification value available for the
report entity. The entity id value comes from the report entity to which the field is being added. The
table index value comes from the table that contains the entity field you are adding. The GUI name
is displayed as the name of the entity field and caption. The example also includes the convention
for each supported database.
Note: It is assumed that a database table column named ORDER_SUM exists in
ORDERS_BY_STATE_D table, which was not part of the previous examples.
Note: The BAM server must be shut down before running scripts against the database.
set field_index=4,
append field_db_name=ORDER_SUM,
append field_db_name_oracle=ORDER_SUM,
append field_db_name_mssql=ORDER_SUM,
append field_db_name_db2=ORDER_SUM,
set field_gui_name=Sum of order amounts,
set field_type=1,
set select_as_default=False,
go
205
Adding a field to a report entity using a database

function
Entity fields can be used to retrieve a value from a database function. To call a database function with
an entity field, encapsulate the column name from the entity table with a special string notation. The
notation to use is: <@[Entity table/view column name]@>. To specify the field value in your
DQL insert statement, use: SET field_db_name_[RDBMS] = [function name] (<@[Entity
table/view column name]@>)
Note: Entity fields can be used to call standard database functions or custom database functions. The
function must accept at least one input parameter.
Adding a field to a custom report entity

In the following example, the Formatted Sum of Orders column is added to the Orders By State Daily
report entity. This column returns the Total Order Summary with a dollar sign ($).
Note: It is assumed that a database table column named ORDER_SUM exists in
ORDERS_BY_STATE_D table.
set field_index=5,
append field_db_name=$ || CHAR(<@ORDER_SUM@>),
append field_db_name_oracle=$ || TO_CHAR(<@ORDER_SUM@>),
append field_db_name_mssql=$ + CONVERT(VARCHAR(20),<@ORDER_SUM@>),
append field_db_name_db2=$ || TO_CHAR(<@ORDER_SUM@>),
set field_gui_name=Formatted Sum of Orders,
set field_type=0,
go
Using a database function to calculate a Now field

In this example, a Now field is added to the Process Execution report entity. Calculating a Now field is
useful in cases where an SDT captures the due date within a process. Loan processes, for example,
capture due date. Once a Now field is calculated, reports can be generated that compare the due date
value with Now. This comparison uses a dateDiff function. Alerts can also be configured to use a
Now field.
When calling a database function from a report entity, the Function must include at least one input
parameter. For example, using the sysdate Oracle function is not valid. For this reason the example
below uses a proprietary Now function.Note: The BAM server must be shut down before running
scripts against the database.
206
1. Create a GET_NOW database function. The Now field you create is based on the GET_NOW
function. The query below creates a GET_NOW function in Oracle.
create or replace FUNCTION GET_NOW (START_DATETIME IN TIMESTAMP)
RETURN DATE
AS
v_date DATE;
BEGIN
select SYSDATE INTO v_date from dual;
RETURN v_date;
END GET_NOW;
2. Entity field objects are created by running a DQL script against the BAM database. The create
script:
Includes the report entity to which the field is being added. In this example, the field is added to
the Process Execution report entity.
Assigns a field_index value to the new field. Index values must be unique. In this example, the
index value is 40. Run this script against the BAM database to determine the next available
index value.
Specifies the name of the field as it appears in the user interface. In this example, the field name
is Now. The first two bullet points above are true for any field added to an entity.
set entity_table_id=(select t.r_object_id from
bami_rg_entity_table t,
bami_rg_entity e where t.entity_id=e.r_object_id and
e.gui_display_data =
Process Execution and t.table_index=0),
set field_index=40,
append field_db_name=,
append field_db_name_oracle=GET_NOW(<@START_DATETIME@>),
append field_db_name_mssql=,
append field_db_name_db2=,
set field_gui_name=Now,
set field_type=2,
go
3. Start the BAM server.

4. Log in to PRS and select the report entity.
207
Determining a field index value

Each report entity field has a unique index value. The DQL script that creates a custom a field
contains a set field_index parameter. If you are unsure of what index value to use, run a query
that returns the highest index value in use. It is safe to use an index value higher than the
returned value. In this example, the select statement returned a value of 35. To be safe, a field
index value of 40 is used to create the Now field.
select max(field_index)
from bami_rg_entity_field
where entity_table_id=(select t.r_object_id from
bami_rg_entity_table t,
bami_rg_entity e where t.entity_id=e.r_object_id and
e.gui_display_data =
Process Execution and t.table_index=0)
Configuring custom filters

A BAM database contains a great deal of process execution data. Without filtering, a report query
returns all results. The result set could be thousands and thousands of data rows. Usually, this amount
of data is not desired. Report filters provide users a way of easily analyzing process data by reducing
the data displayed in reports. BAM ships with a number of standard filter options. Understanding data
source filtering, page 48 explains all of the filtering options available within PRS. When the standard
filter entities shipped with BAM are not sufficient, custom filter entities must be created. Custom filters
can be created for both PRS and dashboards. Because they are more widely used, custom dashboard
filters are discussed first, followed by a discussion of PRS filters.
Understanding dashboard filters

Custom filters can be configured to be used with a dashboard. Dashboard filters are only available on
the root item of a report. If you are required to create a dashboard filter on any other report entity,
the filter should be created on the parent entity and include an Entity Key From Clause and an Entity
Key Where Clause to relate it to the sub-entity.
208
Note: Using custom filters may require that you optimize the BAM database by creating indexes on
SDT/package tables and custom tables.
The following diagram describes the different Documentum objects required to define a dashboard
filter.
This section describes the user interface component of defining dashboard filters. As a result, only
configuration values in the bami_filter_tree_item type are discussed. You can re-use existing PRS
filter entities. If the PRS filter entities are not available, they must be created and then linked to the
user interface component of the dashboard filter. For instructions on creating PRS filter entities, see
Understanding PRS filters, page 216.
Configuring dashboard filters

Dashboard filters have two levels. The first level is the root item that defines the filter item name. The
second level is a dynamic list (DQL query) that displays a list box or check boxes to a dashboard user.
The information in the following table refers to the bami_filter_tree_item type.
Table 23
DQL segments
Column name
Definition
object_name
Enter a label for the filter item. If this is a static filter, this will be the value
of the filter tree item.
209
Column name
Definition
filter_id
r_object_id of the bami_filter_definition object.
internal_code
This is an identifier for internal use only. It should be unique for each filter. A
unique internal code is obtained by getting the maximum internal_code value
from the existing filters, and adding 1 to the result.
tree_item_last_level
This value specifies whether the tree item is the lowest level on the tree (leaf).
Enter 1 if the tree item is the last level of the tree. Otherwise, enter 0.
tree_item_type_select
Enter N if the filter values are static. Enter Y when the filter values should be
retrieved by querying the repository. For example, when a filter displays a list
of performers or activities from which to choose, it is considered a dynamic
(and not static) filter.
data_type
The data_type column is used in one of two different ways. First, it is used to
specify that the field is either:
String
Boolean
Date
Note: These are the only values that are supported.

The data_type column is also used to configure specific fields to be used in
either multi- or single selection search filters. When used in this manner, it is
assumed that the data type is String.
for_web
Enter either 0, 1 and 2, where:

0 The filter is displayed in PRS only, and not within a dashboard.
1 The filter is displayed in PRS and dashboards.
2 The filter item is displayed only in a dashboard.
expression
The expression is displayed when the tree item is selected in PRS. The
expression listed here is a template, with several variables to be substituted for
real values during runtime.
A generic expression can be described as follows:
:FilterTokenName.[Filter Item Name] :Operator :ItemValue
:FilterTokenName is the name of the filter definition tab
[Filter Item Name] must correspond to an existing filter item. During
runtime, the filter engine uses the upper case representation of the filter item
from the expression.
:Operator represents an operator value selected by the user.
:ItemValue is the node value selected from the filter tree. When Type
Select=Y, the software uses the actual value from the select statement rather
than the hard coded item value in the bami_filter_tree_item type. Type
Select can also be set to N.
Note: When creating new filter entities, all custom objects should be linked to the
/System/BAM/Custom Entities folder and all objects should have BAM Admin ACL as the ACL
name.
210
Create a dashboard filter

In this example a dashboard filter with the name State Name is created. For this root item a drop-down
list of all state names is also created. In order to see this filter in a dashboard only, 2 must be entered
as the value in the for_web attribute.
create bami_filter_tree_item object
set object_name=State Name,
set filter_id=(select r_object_id from bami_filter_definition where
object_name=State Filter Tab),
set internal_code=20,
set tree_item_last_level=0,
set tree_item_type_select=N,
set data_type=String,
set for_web=2,
go
set tree_item_parent_id=(select fti.r_object_id from
bami_filter_definition
fd,bami_filter_tree_item fti where fd.object_name=State Filter Tab and
fd.r_object_id=fti.filter_id and fti.internal_code=20),
set tree_item_type_select=Y,
set tree_item_data[0]=select state_name from state_definition,
set for_web=2,
set expression[0]=:FilterTokenName.State-Full-Name :Operator
:ItemValue,
go
Configuring business data filters

This section describes how to create the user interface and picklists for business data filters. Business
data filters must be related to a PRS filter entity.
The following example includes a DQL template to create each aspect of a dashboard filter. In this
case, the Product field that belongs to the Applicant SDT is added to the dashboard. The filter
contains a dynamic list of field values that can be selected by a dashboard user.
Create business data filter

The following create object statement adds the word Product as the filter label.
211

set object_name=Product,
object_name=Monitored Data Filter Tab),
set internal_code=130
set for_web=1,
go
Create dynamic drop-down list

The following insert statement creates a dynamic pull-down list that displays all values for the Product
field.
object_name=Monitored Data Filter Tab),
set tree_item_parent_id=(select fti.r_object_id from bami_filter_definition fd,
bami_filter_tree_item fti where fd.object_name=Monitored Data Filter Tab and
set tree_item_data[0]=select object_name from products,
set for_web=1,
set expression[0]=:FilterTokenName.APPLICANTATTR0 :Operator :ItemValue,
go
Note: You do not have to create the bami_flt_filter_token_items object, because it was already created.
The name can be found by selecting the bami_filter_tree_item type.
select r_object_id,object_name,expression
from bami_filter_tree_item
where filter_id=(select r_object_id from bami_filter_definition
where object_name=Monitored Data Filter Tab)
and any expression is not null
and object_name= Product
go
Configuring single and multi-selection search filters

Single and multi-selection search filters allow dashboard users to search and select from long lists
of filter values. Search filters are a special type of business data custom filter created by way of
212
DQL scripts. The DQL script is divided into two parts. The first part of the DQL script creates the
list of values that appears when a dashboard user enters filter text and clicks Search. The second
part of the DQL script creates the search filter object that appears in the Dashlet Filter tab of a
dashboard. The name of the search filter object is entered in the set object_name= column. The
data_type column is used to specify whether the filter is SINGLE_SELECTION_SEARCH or
MULTI_SELECTION_SEARCH.
The following diagram describes the different Documentum objects required to define dashboard
search filters.
This section describes the user interface component of defining single and multi-select search filters.
As a result, only configuration values in the bami_filter_tree_item type are discussed. You can re-use
existing PRS filter entities. If the PRS filter entities are not available, they must be created and then
linked to the user interface component of the search filter. For instructions on creating PRS filter
entities, see Understanding PRS filters, page 216.
The following DQL examples were used to create the search filter object and list of values in the
example shown in Understanding single and multi-search filters, page 158. For configuring and
using search filters, see Configuring single and multi-search filters in a dashboard, page 159 and
Using single and multi-search filters, page 160.
Search filter list of values DQL

This sample DQL creates the list of filter values.
213
CREATE TYPE states(state_name char(255),description char(255) REPEATING)

WITH SUPERTYPE dm_sysobject
go
CREATE states object
Set object_name=CA,
Set state_name=CA,
Set description=CA
go
Set object_name=MN,
Set state_name=MN,
Set description=MN
go
Set object_name=NC,
Set state_name=NC,
Set description=NC
go
Set object_name=NJ,
Set state_name=NJ,
Set description=NJ
go
Set object_name=NY,
Set state_name=NY,
Set description=NY
go
Set object_name=TX,
Set state_name=TX,
Set description=TX
go
Single search filter DQL

This sample DQL creates a single search filter for State.
set object_name=Single Selection of State,
object_name=Invoice),
set data_type=SINGLE_SELECTION_SEARCH,
214
set for_web=1,
link /System/BAM/Internal
go
set tree_item_parent_id=(select fti.r_object_id from bami_filter_definition
fd,bami_filter_tree_item fti where fd.object_name=Invoice and
set tree_item_data[0]=select object_name from states where object_name
like ${user input}% enable(return_top ${display limit}),
set for_web=2,
set expression[0]=STD.State :Operator :ItemValue,
go
Multi-search filter DQL

This sample DQL creates a multi-search filter for State.
set object_name=Multi Selection of States,
set data_type=MULTI_SELECTION_SEARCH,
set for_web=1,
go
set tree_item_parent_id=(select fti.r_object_id from bami_filter_definition
fd,bami_filter_tree_item fti where fd.object_name=Invoice and
set tree_item_data[0]=select object_name from states where object_name
like ${user input}% enable(return_top ${display limit}),
215
set for_web=2,
set expression[0]=STD.State :Operator :ItemValue,
go
Understanding dashboard filter operators

Dashboard filters support five operators: =, >, <, >=, and <=. The operator is specified in the DQL
statement as part of expression [0]. If left as is, the :Operator value is replaced by the equal sign (=)
at runtime. If you require a different operator, you must explicitly enter the operator. For example:
set expression[0] = :FilterTokenName.Employee-Salary > :ItemValue
Understanding PRS filters

Data set filters are applied to data set entities. A data set filter is a constraint on one or more entities.
The purpose of data set filters is to reduce the results sets of reports. Without filtering, data set queries
return all results. A data set filter consists of a filter expression. Filter expressions include filter items,
operators, and filter values.
Creating a new filter entity can be divided into two parts:
1. The functional definition which contains the SQL predicates that are appended to the query of
the report entity.
2. The visual definition which gives the filter its name and location in the filter tree.
The functional definition involves creating filter entities. The visual definition involves:
creating PRS filter tree items
creating tree item expressions
creating filter token items
defining filter entity relationships
Each entity has one or more filters to which it relates. When relating a filter to an entity, you are
defining its placement within the user interface and the SQL query. In PRS, each filter is displayed
within a tab on the Filter window.
Note: It is helpful to have PRS open when filters are defined. In this way it is possible to test changes
made to your filter in runtime. After you have made a change you can refresh the filter by reopening
the Filter window. While PRS can remain open, the BAM application server must be restarted for the
new filter definition to be available.
This graphic shows the various parts of a BAM filter in PRS:
216
Configuring PRS filter entities

Filter entities are stored in the bami_flt_entity object type. Each filter entity contains the query that
is used by the filter engine during runtime. The table below summarizes each segment of a filter
entity query.
Table 24
Filter entity segment descriptions
Segment
Meaning
Entity Type
The name of the related report entity. When constructing a filter for a
particular report entity, the entity type of the filter should be the same as
that of the report entity.
Entity Key From Clause
The from clause of the entity. The tables referenced by this clause should
refer to one or more of the bami_rg_entity_table objects that are part of the
definition of the report entity.
Entity Key Columns
The entity key column is used to join the entity and the filter.
Entity Key Where Clause
The where clause of the base entity. This typically is non-constricting (where
1=1). The primary use of the Where Clause is to connect the filter query to
the base query.
Symbol Entity Type
This is used for internal filters. Leave this empty for new entities.
Built-In
Always enter a 0 when defining a new entity, or leave blank. The value 1 is
reserved for internal entities, and should not be used.
Note: When creating new filter entities, all custom objects should be linked to the
/System/BAM/Custom Entities folder and all objects should have BAM Admin ACL as the ACL
name.
217
Create entity filter

This example illustrates how a new filter entity with the name Orders By State Daily is created.
create bami_flt_entity object
set entity_key_columns=e.STATE,
set entity_key_from_clause=ORDERS_BY_STATE_D e,
set entity_key_where_clause=where EntityTable0.START_DATETIME=e.START_DATETIME ,
set built_in=0
go
Note: EntityTable0, which is reference in the where clause, is the alias of the ORDERS_BY_STATE_D
table in the Orders by State Daily report entity.
Configuring PRS filter tabs

A tree item is contained in a single filter tab. The filter tab is a visual component of the filter tree,
and is also used as a qualifier to the filter expression. For example, if the filter Activity-Name is
in the STD tab, then the expression of the filter is STD.Activity-Name. Tabs are defined in the
bami_filter_definition Documentum type. The bami_filter_definition type is a stub object that binds
together several filter definitions. The object name of the bami_filter_defnition type should be unique
because it is later referenced by the bami_filter_tree_item type, where the filter_id attribute is equal to
r_object_id in the bami_filter_definition.
The bami_filter_definition type is comprised of the following columns:
Table 25
Filter entity segment descriptions
Column name
Definition
object_name
A unique identifier for the filter tab. This object name should be unique
within the entire BAM system. It will be referenced by the DQL scripts for
creation of the tree items. A new filter may reference an existing filter tab.
Usually, there is no need to create a new tab definition.
Create a filter definition object

This script creates a State Filter Tab filter entity.
create bami_filter_definition object
set object_name=State Filter Tab,
go
218
Configuring PRS filter token items

Filter token items are the fields used in constructing a filter expression. A unique object_name and filter
item expression name (typed in UPPER CASE) must be entered. The values must be unique within
the context of this filter definition. Filter token items are stored in the bami_flt_filter_token_items
object type. Filter token items define the relationship between the tree item and the SQL queries that
are executed on BAM server.
Filter token items are used for internal purposes only. You cannot see them on the user interface. Once
defined, filter token items are used in defining the filter entity relationship.
The bami_flt_filter_token_items type is comprised of the following columns:
Table 26
Filter token item columns
Column name
Definition
Object_name
This is a unique identifier for this filter. It could be equal to the filter item
expression name (in case it is unique for the filter definition).
Filter_id
r_object_id of the bami_flt_filter_definition object.
filter_item_expr_name
The name of the item as it will be seen in the filter expression.
Note: The filter item expression name must be capitalized and written
without spaces.
Create filter token item

This example creates filter token items according to State Name and State Full Name.
create bami_flt_filter_token_items object
set object_name=1,
set filter_item_expr_name=STATE-NAME,
go
create bami_flt_filter_token_items object
set object_name=2,
set filter_item_expr_name=STATE-FULL-NAME,
go
Defining filter entity relationships

Filter entity relationships are defined in the bami_flt_filter_entity type. The bami_flt_filter_entity type
is comprised of the following columns:
219
Table 27
Filter entity type columns
Column name
Definition
entity_type
Select the entity to which the filter relates. Refer to the

bami_flt_entity type.
filter_id
Select the filter to be attached to the selected entity. Refer to the

bami_filter_tree_item type.
filter_item_id
The filter item ID represents the token item unique identifier. Refer
to the bami_flt_filter_token_items type.
filter_entity_from_clause
This is the from clause of the filter expression. It defines the table
names that are part of the query.
flt_sql_column_name_oracle
Column name is used to represent conditions defined by users.
flt_sql_column_name_mssql
flt_sql_column_name_db2
flt_sql_column_name_sybase
flt_sql_column_name_oracle
flt_sql_column_name_mssql
This is the where clause of the filter expression. It defines the filter
condition. There is one field for each database dialect.
flt_sql_column_name_db2
flt_sql_column_name_sybase
filter_entity_token_name
This column represents the alias name assigned when the filter is
used in a filter expression. This value replaces :FilterTokenName
from the filter tree item expressions list.
filentity_token_long_name
This field is shown in the label of the filter tab within PRS.
filter_entity_order_by
This represents the order in which the filter tab is displayed in the list
of tabs for this entity. All items must have the same value per filter.
Note: At runtime, the SQL query generated for each filter item is structured as follows:
[Report Entity Select Statement] AND Entity-Id IN
(Select Entity-Id
FROM [FILTENT_FROM_CLAUSE]
WHERE [FILTENT_WHERE_CLAUSE]
AND [FILTERITEM_SQL_COLUMNNAME] [Selected Operator] [Selected Value])
Create filter entity relationship

This example creates filters by state name and state full name on the Orders By State Daily entity.
This script creates the filter entity for filtering by state
create bami_flt_filter_entity object
set filter_item_id=(select fti.r_object_id from bami_flt_filter_token_items
fti,bami_filter_definition fd where fti.filter_id=fd.r_object_id and
fd.object_name=State Filter Tab and fti.object_name=1),
set filter_entity_token_name=STT,
220
set filter_entity_from_clause=ORDERS_BY_STATE_D e,
append flt_where_clause_oracle=1=1,
append flt_where_clause_mssql=1=1,
append flt_where_clause_db2=1=1,
append flt_where_clause_sybase=1=1,
set flt_sql_column_name_oracle=e.STATE,
set flt_sql_column_name_mssql=e.STATE,
set flt_sql_column_name_db2=e.STATE,
set flt_sql_column_name_sybase=e.STATE,
set filentity_token_long_name=State,
set filter_entity_order_by=20,
go
This script creates the filter entity for filtering by the full name of the state.
create bami_flt_filter_entity object
set filter_item_id=(select fti.r_object_id from bami_flt_filter_token_items
fti,bami_filter_definition fd where fti.filter_id=fd.r_object_id and
fd.object_name=State Filter Tab and fti.object_name=2),
set filter_entity_token_name=STT,
set filter_entity_from_clause=ORDERS_BY_STATE_D e, US_STATES st,
append flt_where_clause_oracle=e.STATE=st.STATE_ABBREVIATION,
append flt_where_clause_mssql=e.STATE=st.STATE_ABBREVIATION,
append flt_where_clause_db2=e.STATE=st.STATE_ABBREVIATION,
append flt_where_clause_sybase=e.STATE=st.STATE_ABBREVIATION,
set flt_sql_column_name_oracle=st.STATE_FULLNAME,
set flt_sql_column_name_mssql=st.STATE_FULLNAME,
set flt_sql_column_name_db2=st.STATE_FULLNAME,
set flt_sql_column_name_sybase=st.STATE_FULLNAME,
set filentity_token_long_name=State,
set filter_entity_order_by=20,
go
Creating PRS client filter tree items

Filters within the PRS client are displayed in a tree-like structure. The structure of the tree is defined
in the bami_filter_tree_item Documentum type. Dashboard filters are also defined as part of this
type, either as a subset of the PRS filters or in addition to them. The bami_filter_tree_item type is
comprised of the following columns:
221
Table 28
Filter tree item columns
Column name
Definition
filter_id
r_object_id of the bami_filter_definition object.
Internal_code
Identifier for internal use only. It should be unique for each filter tab. A unique
internal code can be obtained by getting the maximum internal_code value
from the existing filters, and adding 1 to the result.
tree_item_parent_id
The r_object_id of the parent item identifier of this item in the tree structure.
This field should be left blank if the filter is a top-level item in the tree.
tree_item_type_select
Enter N if the filter values are static. Enter Y when the filter values should be
retrieved by querying the repository. For example, when a filter displays a list
of performers or activities from which to choose, it is considered a dynamic
filter.
object_name
Enter a label for the filter item. If this is a static filter, this will be the value
of the filter tree item.
tree_item_data
If this is a dynamic filter, tree_item_data is the DQL statement that returns the
dynamic filter values.
tree_item_last_level
This value specifies whether the tree item is the lowest level on the tree (leaf).
Enter 1 if the tree item is the last level of the tree. Otherwise, enter 0.
for_web
Enter either 0, 1 and 2, where:

0 The filter is displayed in PRS only and not within a dashboard.
1 The filter item is displayed in PRS and a dashboard.
2 The filter item is displayed only in a dashboard.
data_type
The data_type column is used in one of two different ways. First, it is used to
specify that the field is either:
String
Boolean
Date
Note: These are the only values that are supported.

The data_type column is also used to configure specific fields to be used in
either multi- or single selection search filter. When used in this manner, it is
assumed that the data type is String.
expression
The expression is displayed when the tree item is selected in PRS. The
expression listed here is a template, with several variables to be substituted for
real values during runtime.
A generic expression can be described as follows:
:FilterTokenName.[Filter Item Name] :Operator :ItemValue
:FilterTokenName is the name of the filter definition tab
[Filter Item Name] must correspond to an existing filter item. During
runtime, the filter engine uses the upper case representation of the filter item
from the expression.
:Operator represents an operator value selected by the user.
222
Column name
Definition
:ItemValue is the node value selected from the filter tree. When Type
Select=Y, the software uses the actual value from the select statement rather
than the hard coded item value in the bami_filter_tree_item type. Type
Select can also be set to N.
Creating dynamic and static filters

If you are creating a filter whose values are taken from objects in the repository, then a DQL statement
must be added to the tree_item_data field of the bami_filter_tree_item type. The result from executing
the statement will be substituted for variables that are part of the expression.
The convention of the DQL statement for dynamic filters stipulates that the first columns of the
result set should always be alphanumeric either char or varchar. If, for example, the first three
columns are alphanumeric, then the values would be substituted for the :ItemValue, :ItemValue2, and
:ItemValue3 variables, respectively.
The columns that follow the alphanumeric columns should be of the Object ID type. These columns
are used when the dynamic tree item has child tree items, and the child tree items DQL must reference
the IDs retrieved from the parent. In this case, the children DQL should use a question mark (?) as a
placeholder for all ID values. The filter engine substitutes the placeholder with the IDs of the parent
in the same order that they appear in the result.
The figure displays the filter items available for the Activity Execution report entity.
The Processes root level tree item contains the following query:
select object_name,r_object_id from dm_process where r_has_events=1
The following query relates the second entity to the root level:
select r_act_name from dm_process where r_has_events=1 and r_object_id=?
The values returned by the query should not be null. In the example above the r_act_name attribute in
the DQL select statement should not contain null values.
Create a static state filter item

This example adds a state filter that does not contain any children.
set object_name=State,
223
set for_web=0,
set expression[0]=:FilterTokenName.State-Name :Operator ,
go
Note: Filter items can be made available within a dashboard. Configuring dashboard filters, page 209
and Configuring business data filters, page 211 provide instructions.
Create a static, second level of a tree

In this example five static children are created for the State static filter. The children values are: CA,
NY, MI, NJ, and NC.
set object_name=CA,
bami_filter_tree_item fti where fd.object_name=State Filter Tab and
set for_web=0,
set expression[0]=:FilterTokenName.State-Name :Operator :ItemValue,
go
set object_name=NY,
set for_web=0,
go
224

set object_name=MI,
set for_web=0,
go
set object_name=NJ,
set for_web=0,
go
set object_name=NC,
set for_web=0,
go
225
Create dynamic filter items

Dynamic filters can be used instead of static filters. Dynamic filters provide dashboard users with lists
of filter values generated directly from the database. For this to occur, all state names must be saved
in a Documentum type. In this example the state_definition type is used. The script used to create
and populate the type is shown next.
This script creates the state definition type.
CREATE TYPE state_definition
(
state_name char(255),
description char(255) REPEATING
) WITH SUPERTYPE dm_sysobject
Go
create state_definition object
Set object_name=CA,
Set state_name=California,
Set description=State of California
Go
Set object_name=NY,
Set state_name=New York,
Set description=State of New York
Go
Set object_name=MI,
Set state_name=Michigan,
Set description=State of Michigan
Go
Set object_name=NJ,
Set state_name=New Jersey,
Set description=State of New Jersey
Go
Set object_name=NC
Set state_name=North Carolina
Set description=State of North Carolina
Go
This script creates the dynamic filter. This filter will select state
names from the state_definition object.
226

set tree_item_data[0]=select object_name from state_definition,
set for_web=0,
go
Note: Filter items can be made available within a dashboard. Configuring dashboard filters, page 209
and Configuring business data filters, page 211 provide instructions.
Refreshing the BAM server

The BAM server cache must be refreshed after custom report and filter entities are created or
modified. The cache is refreshed by either rebooting the BAM server and PRS (if required) or
by triggering a RefreshEntities job. A RefreshEntities job is a quicker approach to refreshing the
cache, but is only available in BAM Version 6.6 and higher. The RefreshEntities job is stored in
the I_BAM_SERVER_CONFIG table of the BAM database. A SQL command is run against the
I_BAM_SERVER_CONFIG table that updates the block indicator to 0. Once the command is
committed, wait for approximately 1 minute. As the RefreshEntities job runs, the flag is set to 1.
When the job completes, the report and filter entities are refreshed and the flag is set to 2. Another
way of verifying that the job is completed is to check bam-engine.log. A Completed refresh
of dynamic entities log message is written to bam-engine.log confirming that the RefreshEntities
job was executed.
The refresh job is triggered by running the following SQL command against the BAM database:
Update I_BAM_SERVER_CONFIG set BLOCK=0 WHERE SERVERNAME=
RefreshEntities
Note: Make sure to COMMIT after running the command and close your session to avoid locking the
I_BAM_SERVER_CONFIG table.
Deleting custom report and filter entities

Custom report and filter entities are deleted by running scripts against the BAM database. Each script
is provided in this section, along with a description of how to use it.
There are five use cases:
Deleting custom report entities
Deleting custom report entity fields
Deleting filter tree items
227
Deleting filter tabs

Deleting filter entities and relations
Deleting custom report entities

Use the following DQL statement to delete a custom report entity. This DQL statement deletes the
report entity definition, but not the filters related to the report entity.
To use this DQL statement:
1. Replace [GUI DISPLAY DATA] with the report entity GUI display data. The report entity GUI
display data is found in the gui_display_data attribute of the bami_rg_entity type.
delete bami_rg_entity_key objects
where entity_table_id in (select et.r_object_id
from bami_rg_entity_table et,bami_rg_entity e
where et.entity_id=e.r_object_id
and e.gui_display_data =[GUI DISPLAY DATA])
and folder(/System/BAM/Custom Entities)
go
delete bami_rg_relation_table objects
where relation_id in (select r_object_id
from bami_rg_relation
where parent_entity_id in (select r_object_id from
bami_rg_entity where gui_display_data =[GUI DISPLAY DATA])
or child_entity_id in (select r_object_id from
bami_rg_entity where gui_display_data =[GUI DISPLAY DATA]))
go
delete bami_rg_relation objects
where (parent_entity_id in (select r_object_id
from bami_rg_entity where
gui_display_data =[GUI DISPLAY DATA])
or child_entity_id in (select r_object_id from
bami_rg_entity where gui_display_data =[GUI DISPLAY DATA]))
go
# The following DQL deletes all report entity fields of a
custom report entity
delete bami_rg_entity_field objects
where entity_table_id in (select t.r_object_id
from bami_rg_entity_table t,bami_rg_entity e
where t.entity_id=e.r_object_id
and e.gui_display_data =[GUI DISPLAY DATA])
go
delete bami_rg_entity_table objects
where entity_id in (select r_object_id
from bami_rg_entity
where gui_display_data =[GUI DISPLAY DATA])
go
228
delete bami_rg_entity objects

where gui_display_data =[GUI DISPLAY DATA]
go
Deleting custom report entity fields

Use the following DQL statement to delete individual report entity fields from a custom report entity.
1. Replace [GUI DISPLAY DATA] with the report entity GUI display data. The report entity GUI
display data is found in the gui_display_data attribute of the bami_rg_entity type.
2. Replace [TABLE INDEX] with the report entity table index. The report entity table index is found
in the table_index attribute of the bami_rg_entity_table type.
3. Replace [FIELD INDEX] with the report entity field index. The report entity field index is found in
the field_index attribute of the bami_rg_entity_field type.
delete bami_rg_entity_field objects
where entity_table_id in (select t.r_object_id
from bami_rg_entity_table t,bami_rg_entity e
where t.entity_id=e.r_object_id
and e.gui_display_data =[GUI DISPLAY DATA]
and t.table_index=[TABLE INDEX])
and field_index=[FIELD INDEX]
go
Deleting filter tree items

Use the following DQL statement to delete a custom tree item from an existing filter tab. The script
deletes filter tree items, filter token items, and the relationship between filter tree items and filter
entities.
1. Replace [CUSTOM FILTER TAB] with the name of the custom filter tab. The name of the custom
filter tab is found in the object_name attribute of the bami_filter_definition type.
2. Replace [CUSTOM TOKEN ITEM NAME] with the name of the token item. The token item name
is found in the filter_item_expr_name attribute of the bami_flt_filter_token_items type.
3. Replace [LABEL OF TREE ITEM] with the label of the filter tree item. The filter tree item label is
found in the object_name attribute of the bami_filter_tree_item type.
#delete relations between a tree item and a filter entity
delete bami_flt_filter_entity objects
where filter_id = (select r_object_id from bami_filter_definition
where object_name=[CUSTOM FILTER TAB])and filter_item_id =
(select r_object_id
from bami_flt_filter_token_items fti,
bami_filter_definition fd
where fd.r_object_id=fti.filter_id
229
and fd.object_name=[CUSTOM FILTER TAB]

and fti.filter_item_expr_name=[CUSTOM TOKEN ITEM NAME])
go
#delete children filter tree items of the filter tree item
delete bami_filter_tree_item objects
where tree_item_parent_id in (select r_object_id
from bami_filter_tree_item fti,
bami_filter_definition fd
where fti.filter_id = fd.r_object_id
and fd.object_name=[CUSTOM FILTER TAB]
and fti.object_name=[LABEL OF TREE ITEM])
go
#delete the filter tree item of the filter tab
where object_name=[CUSTOM FILTER TAB])and object_name=
[LABEL OF TREE ITEM]and folder(/System/BAM/Custom Entities)
go
#delete filter token items of the the filter tree item
delete bami_flt_filter_token_items objects
where object_name=[CUSTOM FILTER TAB])and filter_item_expr_name=
[CUSTOM TOKEN ITEM NAME]and folder(/System/BAM/Custom Entities)
go
Deleting filter tabs and associated filter tree items

Use the following DQL statement to delete a filter tab and all filter tree items. The DQL statement
deletes custom filter tab definitions, filter tree items, filter token items, and the relationship between
filter tree items and filter entities.
1. Replace [CUSTOM FILTER TAB] with the name of the custom filter tab. The name of the custom
filter tab is found in the object_name attribute of the bami_filter_definition type.
#delete relations between a custom filter tab and a filter entity
where filter_id = (select r_object_id from bami_filter_definition where
object_name=[CUSTOM FILTER TAB])and folder(/System/BAM/Custom Entities)
go
#delete filter tree items of the custom filter tab
go
230
#delete filter token items of the custom filter tab

delete bami_flt_filter_token_items objects
go
#delete the custom filter tab definition
delete bami_filter_definition objects
where object_name=[CUSTOM FILTER TAB]
go
Deleting filter entities and relations

Use the following DQL statement to delete the relationship between filter tree items and filter entities.
This DQL statement also deletes filter entity definitions, but does not delete the filter tab.
1. Replace [CUSTOM ENTITY TYPE] with the name of the custom filter entity type. The name of
the custom filter entity type is found in the entity_type attribute of the bami_flt_entity type.
where entity_type=[CUSTOM ENTITY TYPE]
go
delete bami_flt_entity objects
where entity_type=[CUSTOM ENTITY TYPE]
go
231
232
Chapter 11
Troubleshooting
BAM dashboards are not being updated
Reports do not generate the expected results
Using log files to assess the status of BAM engine jobs
Email server down and need to view pending jobs
Do not know host name of SMTP server, owner email address, or recipient email address
Increasing email timeout parameter when network performance slow
Recovering alert email messages sent incorrectly
BAM dashboards are not being updated

Business data monitored by BAM is configured by way of Process Builder. For each activity, specific
fields from packages or process variables can be audited and monitored by BAM. Once a manual
activity is acquired, the user may update process variables, form fields, or package attributes without
completing the activity. The updated values are not inserted in to the BAM database until the activity
is complete. Without this understanding dashboard users may become confused and wonder why
report data is not updated.
For example, a TaskSpace user acquires a Review Contract task. During the review the user updates the
amount field of the contract, but decides to do more research giving final approval. The new value for
amount is not reflected in BAM reports until the user is done with the research and completes the task.
Task completion is the trigger the monitored field to be updated in the BAM database. Out of the box
there is no way to insert the updated value into the BAM database without the activity being completed.
The following actions may help:
1. In your end-user training, explain that BAM reports are designed to include business data values
after activities are completed. Explain to the users which actions commit the transaction to the
database.
2. Design your reports knowing that when filtering on an activity, the monitored business data is
updated upon completion of the activity.
3. If you must be able to report on the value during the time the user is still working on the manual
activity, consider breaking this into two activities: one to update the value(s) and a second to
continue the review.
233
Troubleshooting
Reports do not generate the expected results

This section describes how to troubleshoot BAM reports that do not generate expected results. If a
BAM report fails to generate the results you expect, then you should:
1. Check the data source of the report and make sure you understand what report results to expect.
Understanding how data source results are generated, page 46 is an important first step in
troubleshooting reports.
2. Check any data source filters you may have written. For compound filters you should:
Check that the appropriate operator is used (AND versus OR) in the filter.
Run reports that test each segment of the filter expression to make sure you get the desired results.
Run reports that test combinations of filter segments to make sure you get the desired results.
Copy and paste the filters SQL query into any SQL utility and run it against the database. The
problem with the filter should be immediately obvious.
Note: If there is no SQL query for a filter then the filter entity model is not properly defined.
Double-check the filter entity model and make sure that filter objects and relationships are defined
correctly. For more information on filter entity objects and relationships, see BAM database tables,
page 240.
3. For reports that use custom report entities, check that a single entity provides the desired results.
Then add report entities one-by-one and test again. If the report results are not generated as
expected, then copy and paste the report entitys SQL query into any SQL utility and run it against
the database. The problem with the report entity should be immediately obvious.
234
Troubleshooting
Using log files to assess the status of BAM

engine jobs
Log file messages provide valuable information when you need to debug and troubleshoot BAM engine
jobs (including aggregation), reports, and dashboards. If there are problems with any BAM operation,
BAM logs helpful messages in the bam-engine.log file and the bam.log file. The default location of
each log file is the home path of the application server. Check the log4j.properties file if you are unsure
of the location of these log files. The log4j.properties file specifies the location of each log file.
On BEA Weblogic Server 9.2 MP2 the log4j.properties file is available in one of the following paths
where you unpacked the EAR file during installation:
Windows: [Temporary EAR location]\bam-server.ear\APP-INF\classes\
UNIX/Linux: [Temporary EAR location]/bam-server.ear/APP-INF/classes/
On BEA Weblogic Server 10 MP1 the log4j.properties file is available in one of the following paths
where you unpacked the EAR file during installation:
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes\
UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes/
For all other application servers the log4j.properties file is available in one of the following paths:
235
Troubleshooting
Windows: [Temporary WAR location]\bam-server.war\WEB-INF\classes

UNIX/Linux: [Temporary WAR location]/bam-server.war/WEB-INF/classes
Once the log files are located you should:
1. Frequently review the bam-engine.log file for errors and warnings. The bam-engine.log file is the
primary source for run-time information. It contains information about all BAM engine jobs,
including the event piping process and the formatting and aggregation jobs.
2. Review the bam.log file for reporting and dashboard operations. When reports fail, a message is
written to this log file.
3. Review log files associated with your database. In particular, review the growth rate of the database.
4. Review log files associated with the application server, if they are available. These log files
contains information about reporting operations.
To review the status and last processed record for each of the BAM engine jobs, run the following
query against the BAM database:
select SERVERNAME,LAST_PIPR_RUN From I_BMA_SERVER_CONFIG where
SERVERNAME like DCTM%
The output from this query display information about the four different BAM server jobs. The four jobs
include the piping process which is responsible for transferring audit trail data into the BAM database,
and each of three formatting jobs (process, activity, and data). For each job the LAST_PIPE_RUN
value displays the timestamp of the last processed record.
Email server down and need to view pending

jobs
BAM uses email only for alerting. Email is sent asynchronously which means that an email message is
not necessarily sent immediately. First it is marked as ready to send, and then a background job on
the BAM server sends the email. This asynchronous mechanism allows alerts to be raised even if the
email system is down. If your email server is down for any reason, then you can track all pending
email jobs by looking at the BAM_EMAIL_TASK table in the BAM database. Use the following
SQL query to look at all pending email jobs:
select ID, CREATION_TIME, LAST_UPDATED, EMAIL_CONTENT from BAM_EMAIL_TASK
Do not know host name of SMTP server, owner

email address, or recipient email address
This section addresses email environment issues.
SMTP server
To look up the host name of the BAM SMTP server, then run the following DQL command:
select smtp_server from dm_server_config
236
Troubleshooting
The result of this query is the host name of the SMTP server.
To change the host name of the SMTP server, run the following DQL command: update
dm_server_config objects set smtp_server=<SMTP Host>
In this command, <SMTP Host> must replaced with the real value.
Owner email address
To look up the owner of an email address, run the following command: select user_address
from dm_user u, dm_server_config cfg where u.user_name=cfg.owner_name
To change the owner of the email address, then run the following command: update
dm_user objects set user_address=<Valid Address> where user_name
in (select user_name from dm_user u, dm_server_config cfg where
u.user_name=cfg.owner_name)
In this command, <Valid Address> must be replaced with the real value.
Recipients email address
To look up a recipients email address, run the following command: select user_address
from dm_user where user_name=<User Name>
In this command, <User Name> must be replaced with the real value.
To change a recipients email address, run the following command: update dm_user objects
set user_address=<Valid Address> where user_name=<User Name>
In this command, both <User Name> and <Valid Address> must be replaced with the real values.
Increasing email timeout parameter when

network performance slow
If your network is performing slowly, it is possible to modify the mail SMTP I/O by changing a value
in the env-config.xml file that is located in: <BAM Installation Directory>/WEB-INF/classes/config.
<email smtpTimeout="600000"></email>
The email tag is located within the app-config preference. The default time is set to 60 seconds.
CAUTION: You should not modify this value unless it is needed.
Recovering alert email messages sent

incorrectly
If an incorrect SMTP host is configured, then emails are not sent until the SMTP host location is
corrected and BAM is restarted. If either the owners or recipients email address is invalid, then you
either delete the incorrect messages or modify the From and To values of the email. If not corrected,
the email system tries to re-send the emails.
1. Copy the values returned after you execute the following query: select EMAIL_CONTENT from
BAM_EMAIL_TASK where ID=<ID of incorrect message>
2. Edit the email content with the correct values.

237
Troubleshooting
3. Update the corresponding database record by running the following command: update
BAM_EMAIL_TASK set EMAIL_CONTENT=<Fixes message content> where ID=<ID
of incorrect message>
238
Appendix A
Entity Relation Diagrams
This appendix contains the following:
BAM database tables
BAM report entities
239
BAM database tables
BAM database tables
240
Entity Relation Diagrams
BAM report entities
241
Appendix B
Report entities
Report entities
Report entities
This appendix contains a list of all report entities available in Process Reporting Services.
Note: Please contact EMC directly for a list of report entities for languages other than English.
Table B.29
Report entities
Type
Entities
Activity
Activity Execution
Activity Events
Incomplete Activity Execution
Process
Process Execution
Process Events
Incomplete Process Execution
Queue
Work Queue
Work Queue Events
Alert
Alert
Activity Aggregation
Activity Execution 5 Minutes

Activity Execution Hourly
Activity Execution Daily
Activity Execution Weekly
Activity Execution Monthly
Activity Execution Quarterly
Activity Execution Yearly
Incomplete Activity Execution 5 Minutes
243
Report entities
Type
Entities
Incomplete Activity Execution Daily
Incomplete Activity Execution Hourly
Process Aggregation
Process Execution 5 Minutes

Process Execution Hourly
Process Execution Daily
Process Execution Weekly
Process Execution Monthly
Process Execution Quarterly
Process Execution Yearly
Incomplete Process Execution 5 Minutes
Incomplete Process Execution Daily
Incomplete Process Execution Hourly
Performer Aggregation
Activity Performer 5 Minutes

Activity Performer Hourly
Activity Performer Daily
Activity Performer Weekly
Activity Performer Monthly
Activity Performer Quarterly
Activity Performer Yearly
244
Appendix C
Database Views
Database Views
Database Views
This view is used in the Activity Events report entity.
Table C.30
EXEC_ACTIVITY_EVENTS_VIEW
Columns
EVENT_TYPE
QUEUE_NAME
QUEUE_ID
ACTIVITY_NAME
PERFORMER_ID
PERFORMER_NAME
EVENT_TYPE
ID
INSTANCEID
ACTIVITY_ID
This view is used to filter the Work Queue reporting entity according to end date and time.
Table C.31
V_FLT_QUEUE_END
Columns
QUEUE_ID
EVENT_TIME
This view is used to filter the Work Queue reporting entity according to end date and time.
245
V_FLT_QUEUE_START
Table C.32
V_FLT_QUEUE_START
Columns
QUEUE_ID
EVENT_TIME
This view is used in the Work Queue reporting entity.

Table C.33
EXEC_QUEUE_MANAGEMENT_VIEW
Columns
QUEUE_ID
QUEUE_NAME
WORK_ITEMS_IN_QUEUE
QUEUE_THRESHOLD
CAPACITY
ACQUIRED
SUSPENDED
DELEGATED
USERS_ASSIGNED_TO_QUEUE
This view is used in the Activity Execution reporting entity.

Table C.34
EXEC_ACTIVITY_INSTANCE
Columns
ID
INSTANCEID
ACTIVITY_ID
START_DATETIME
END_DATETIME
NAME
DURATION
DURATION_MIN
PROCESS_EVENT_ID
PERFORMER_NAME
PERFORMER_ID
QUEUE_ID
RESOURCE_PROC_INSTANCE_ID
ACTIVITY_TYPE
246
Database Views
This view is used in the Process Events reporting entity.

Table C.35
EXEC_PROCESS_EVENTS_VIEW
Columns
EVENT_TYPE
NAME
PERFORMER_ID
PERFORMER_NAME
EVENT_TIME
ID
INSTANCEID
VERSION_NUMBER
This view is used in the Work Queue Events reporting entity.

Table C.36
EXEC_QUEUE_EVENTS_VIEW
Columns
EVENT_TYPE
QUEUE_NAME
QUEUE_ID
ACTIVITY_NAME
PERFORMER_ID
PERFORMER_NAME
EVENT_TIME
ID
INSTANCEID
ACTIVITY_ID
This view is used in the Process Execution reporting entity.

Table C.37
V_EXEC_PROCESS_INSTANCE
Columns
ID
NAME
INSTANCEID
START_DATETIME
END_DATETIME
DURATION
247
V_INC_ACTIVITY_INSTANCE
Columns
DURATION_MIN
PERFORMER_ID
STATUS
VERSION_NUMBER
This view is used in the Activity Execution reporting entity.

Table C.38
V_INC_ACTIVITY_INSTANCE
Columns
ID
INSTANCEID
ACTIVITY_ID
START_DATETIME
END_DATETIME
DURATION
NAME
PERFORMER_NAME
PERFORMER_ID
This view is used in the Incomplete Activity Instance reporting entity.

Table C.39
V_ACT_EXECUTION
Columns
ID
INSTANCEID
ACTIVITY_ID
START_DATETIME
END_DATETIME
NAME
DURATION
DURATION_MIN
PROCESS_EVENT_ID
PERFORMER_NAME
PERFORMER_ID
QUEUE_ID
248
Database Views
Columns
RESOURCE_PROC_INSTANCE_ID
ACTIVITY_TYPE
249
Index
A
Aggregation
aggregation engine, 14
business data aggregation, 57, 90
Daylight Savings Time, 192
example report, 97, 99
process aggregation, 57
report aggregation, 57, 70
Alert dashboards
alert list dashlet, 132
design, 133
refresh interval configuration, 140
Alerts
activity performer aggregation entities, 115
alert engine, 18
alert entities, 112
alert list dashlet, 146, 173
architecture, 108
business data entities, 117
category creation, 125
data source filtering, 119
design, 126
designed for service level agreement, 130
designed to invoke other processes, 131
designed with SDTs or packages, 128129
designing alerts for aggregated data, 110
editing, 141
email configuration, 123
incomplete process and activity entities, 113
overview, 107
process and activity aggregation entities, 114
process and activity entities, 112
publishing, 132
purging alerts, 123
queue entities, 116
report example, 173174
roles and responsibilities, 109
testing, 131
updating in dashboard, 146, 162
writing alert expressions, 120
Audit trail
configuration, 26
permissions, 27
purge, 191
B
BAM administration
aggregation and system performance, 185
backing up data, 192
complete purge, 188
custom entity migration, 183
data transfer latency configuration, 36
Daylight Savings Time, 192
high volume environments, 184
maximum data transfer latency idle time,
3637
purge Audit Trail database, 191
purge scheduling, 189

update monitored data, 32
BAM Server
aggregation engine, 14, 90
alert engine, 14
connecting to, 32
data transfer latency configuration, 36
event pipe, 14
format engine, 14
gap filler, 14
maximum data transfer latency idle time
configuration, 3637
Business Activity Monitor
architecture, 14
database, 186, 188189
development vs. production modes, 179180
C
Composer
moving to production, 180
Computed columns
add to report, 72, 75
delete, 75
edit, 75
Crystal Reports
create, 80
delete, 88
drill-down reports, 87
edit, 82
example, 171, 173
export from TaskSpace application, 94
export to another repository, 88
export to CSV or PDF, 93
filter report entities, 76
import, 89
preview, 76
print, 156
publish, 84
synchronize, 80
when to use, 82
Custom entities
filter, 208
search filters, 212
D
Dashboard
add tab, 151
add to dashboard application, 150
alert list dashlet, 146, 149, 162, 173
architecture, 144
create application, 149
dashlet filtering, 147, 155, 157
delete, 157
design, 149
development to production, 180
251
Index
edit, 156
export Crystal Report, 94
multi-drill-down report configuration, 86, 152
permissions, 147, 151
preconfigured dashboard overview, 165
printing, 156
process diagram dashlet, 149, 154
published reports, 84
refresh period scheduling, 155
remove, 157
report dashlet, 145, 149
right to left content, 163
search filter configuration, 159
search filter creation, 212
search filter overview, 158
search filter use, 160
style sheet customization, 162
user interface overview, 148
users, 144
Data source
generating results, 46
preview, 76
records returned configuration, 188
reuse, 83
undo/redo, 90
Drill-down reports
in Crystal Reports, 87
multi-drill-down report overview, 63
single drill-down configuration, 84
single drill-down report overview, 61
E
Excel
export Simple Report, 93
F
Filtering
creating business data filters, 211
custom entities, 208
dashlet, 147, 155, 157
overview, 48
report entities, 76
single drill-down reports, 63
Filters
search filter configuration, 159
search filter creation, 212
search filter use, 160
search filters, 158
G
Gap filler
overview, 14
252
recovery period configuration, 35
M
Monitoring
audit trail configuration, 26
package types, 29
process variables, 29
structured data types, 28
P
Package object types
configure aggregation, 9091
creating custom filters, 211
modify when used in reports, 83
monitoring configuration, 29
update data definitions, 32
PDF
Permissions
Audit Trail, 27
dashboard, 147, 151
Preconfigured dashboard
alert monitor, 173
alert report examples, 173174
bar+line report examples, 167, 169171
Crystal Report example, 171, 173
gauge report example, 168
overview, 165
pie, bar chart example, 167168
Process monitor, 166
process summary, 169
table chart example, 168
Process Builder
audit trail configuration, 26
create sub-processes, 148
package type monitoring, 29
process variable monitoring, 29
structured data type monitoring, 28
update monitored data, 32
Process diagram
add to dashboard, 154
Process Reporting Services
architecture, 40
business data aggregation, 9091
calculating inter-activity duration, 101
display in enterprise portal, 92
filtering, 48
logging in, 64
multi-drill-down report overview, 63
palette, 41
personas, 40
report aggregation example, 97, 99
reporting entities, 41
simple reports, 51
single drill-down report configuration, 84
Index
single drill-down report overview, 61

user interface navigation, 65
Process variables
Production environment
complete purge, 188
database, 186
migrate from development, 180
records returned configuration, 188
Q
Queue monitoring, 34
Quick Start
designing a dashboard, 22
designing a report, 20
enabling audit trail, 19
overview, 19
R
Report manager
creating categories, 65
deleting reports, 88
editing reports, 88
exporting reports, 88
importing reports, 89
Reporting entities
activity and process, 41
aggregated entities, 41, 57
alert, 41
business data, 41
edit field captions, 89
entity field captions, 47
entity fields, 47
filtering, 48
incomplete execution, 41
reports
calculating inter-activity duration, 101
continuous aggregation, 104
generating data source results, 46
modify report time-out parameter, 37
modify SDTs and packages, 83
performance, 55
security, 77
computed columns, 72
creating, 66
delete, 88
dial gauge reports, 52
edit, 88
export to another repository, 88
export to CSV, 93
gauge reports, 168
import, 89
modify chart labels, 69
multi-drill-down configuration, 86, 152
overview, 51
pie and bar charts, 51, 167168
preview, 76
print, 156
publish, 84
single drill-down configuration, 84
sort columns, 68
table charts, 55, 166, 168
when to use, 82
Structured data types
configure aggregation, 9091
creating custom filters, 211
modify when used in reports, 83
update data definitions, 32
used in reports, 97, 99
system performance
aggregation, 185
data transfer latency, 184
generating data source results, 46
T
TaskSpace
add dashboard to application, 150
add tab, 151
create dashboard application, 149
delete dashboard, 157
design dashboard, 149
edit dashboard, 156
logging in, 30
remove dashboard, 157
Troubleshooting
S
Security
reports, 77
Simple reports
aggregation, 57, 70
auto-refresh, 84
bar+line charts, 54, 167, 169171
chart properties, 55
color palette, 69
253

BAM 6.7 Implementation PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

BAM 6.7 Implementation PDF

Uploaded by

Copyright:

Available Formats

EMC Documentum

Business Activity Monitor

Overview of Business Activity Monitor ..........................................................13

Quick Start Guide to BAM ..............................................................................19

Configuring Business Activity Monitor ..........................................................25

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Understanding machine clock synchronization ...................................................38

Designing Reports with Process Reporting Services.....................................39

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Understanding when to use Simple reports and Crystal Reports..........................82

Process Reporting Services Examples ..........................................................97

Designing Alerts with Process ..................................................................... 107

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Writing alert expressions using autocomplete and the keypad..................... 122

Designing Dashboards ................................................................................. 143

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Understanding single and multi-search filters ................................................... 158

Working with Preconfigured Dashboards..................................................... 165

Administrating BAM Deployments ............................................................... 179

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Limiting the number of records returned in a results set .................................... 188

Creating Custom Aggregation, Report, and Filter Entities ........................... 193

Troubleshooting ........................................................................................... 233

Entity Relation Diagrams.............................................................................. 239

Report entities.............................................................................................. 243

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Database Views ............................................................................................ 245

Entity Relation Diagrams ..................................................................................................... 239

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Overview of Business Activity Monitor

Understanding the Business Activity Monitor architecture

Overview of Business Activity Monitor

Overview of Business Activity Monitor

A case-based or other process-based application designed.

Understanding the Business Activity Monitor

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Overview of Business Activity Monitor

Business Activity Monitor technical architecture

Understanding BAM dashboards

Understanding Process Reporting Services

Understanding the event pipe

Overview of Business Activity Monitor

Understanding business data monitoring

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Overview of Business Activity Monitor

Understanding the format engine

Understanding the aggregation engine

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Overview of Business Activity Monitor

Understanding the alert engine

Understanding the gap filler job

EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide

Quick Start Overview

Designing a Process Execution report

Designing a BAM dashboard

Quick Start Overview

Quick Start Guide to BAM

1. Open the process you want to monitor.

5. Save, validate, and install the process.

Designing a Process Execution report

4. In the Name field enter Process Execution and click Finish.