EMC Documentum Business Activity Monitor Version 6.7 Implementation Guide[EMC believes the infomation i this publication accurate as of 2s publication dete, The formation i subject to ange witht “he sfermatio i this public s provide as 6. EMC Corporation males no reeseratons or waranties of ex in wit spect the anfommatn itis publeaton and specially islam amped weraies of mercutabaty or Sess for ‘perulapspose. Use,copyig, and distibtam of any EMC saftvare described this publican request appiebesoforare Tenet Forthe most wp-to due lising of EMC product names, see EMC Cerprstin Tademus on EMC com. All other rademaks used Jaren ae the oper of tex respecte ormers. Copyright 2011 EMC Corporation. Allragis reserved.Table of Contents Chapter 1 Chapter 2 Chapter 3 Overview of Business Activity Monitor Overview of Business Activity Monitor. Understanding the Business Activity Monitor architecture. Understanding BAM dashboards Understanding Process Reporting Services Understanding the event pipe Understanding business data monitoring Understanding the format engine Understanding the aggregation engine Understanding the alert engine Understanding the gap filler job. Quick Start Guide to BAM .. Quick Start Overview. Monitoring a process Designing a Process Execution report Designing a BAM dashboard 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 Updating structured data types with Process Builder Updating package object types with Process Builder Updating monitored business data with TaskSpace Understanding queue monitoring Configuring recovery periods. Configuring data transfer latency Configuring a maximum data transfer idle time. Specifying a maximum data transfer idle time Modifying the dashboard repor time-out parameter. EMC Documentum Business Activity Mentor Version 67 Implementation Guide 32 33 33 34 35 36 36 a7 7Table of Contents Chapter 4 Understanding machine clock synchronization Designing Reports with Process Reporting Services. Overview of Process Reporting Services. Understanding report entities and data sources. Working with activity and process entities Working with activity and process aggregation entities. Working with incomplete execution entities Working with activity performer aggregation entities Working with queue entities Working with business data entities. Working with alert entities. Understanding data sources. Understanding how data source results are generated. Working with entity fields and captions. Understanding data source fittering Understanding simple report types Working with pie charts and bar charts. Working with dial gauges. Working with bar and line charts Working with table charts. Understanding chart type properties, Understanding reports that use aggregation. Understanding server aggregation Understanding business data aggregation Understanding single dril-down reports Understanding multi-dril-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. EMC Documentum Business Activity Mentor Version 67 Implementation GuideTable of Contents Understanding when to use Simple reports and Crystal Reports. 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 mutti-dril-down reports in PRS Configuring mutti-dril- down reports in a dashboard. Configuring Crystal Report dril-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. Chapter5 _ 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. Chapter6 —_ 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. Working with alert entities. Designing alerts with process and activity entities. Designing alerts with incomplete Process and Incomplete Actwvity Execution entities Designing alerts with Process and Activity Aggregation entities Designing alerts with Activity Performer Aggregation entities Working with queue entities Designing alerts with business data entities. Working with alert entities. Custom alert entities. Filtering an alert data source. Writing alert expressions EMC Documentum Business Activity Mentor Version 67 Implementation GuideTable of Contents Chapter 7 Writing alert expressions using autocomplete and the keypad. Purging alert data Configuring email Troubleshooting alert email issues 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. Working with the Alert List dashlet Understanding the Alert Monitor dashboard design and layout. Configuring alert dashboard refresh intervals. Editing alerts. Designing Dashboards. Understanding BAM Dashboards Understanding the report dashiet Understanding the process diagram dashlet. Understanding the alert list dashlet Understanding dashiet fiters 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 mutti-dril-down reports in PRS Configuring mutti-dril- down reports in a dashboard. Adding process diagrams to a dashboard ‘Scheduling refresh periods. Configuring dashlet fers. Printing reports from a dashboard. Modifying dashboards. Removing dashboards. Deleting dashboards. Using dashlet fiters 122 123, 123 124 125 126 128 129 130 131 131 132 132 132 133 140 141 144 145 146 146 447 447 148 148 149 149 150 151 151 152 153 154 155 155 156 156 457 457 457 EMC Documentum Business Activity Mentor Version 67 Implementation GuideTable of Contents Chapter 8 Chapter 9 Understanding single and muiti-search fitters Configuring single and multi-search filters in a dashboard Using single and multi-search fitters. Updating the status of an alert Customizing a dashboard cascading style sheet \Viewing dashboard contents displayed in right to left languages, Working with Precontigured Dashboards. Overview of the Preconfigured Dashboards Understanding the Process Monitor dashboard Understanding the List of Process Instances report Understanding the Count of Started, In-flight, and Completed Processes report Understanding the Count of inflight Processes report Understanding the Count of Processes Started within the Last Month report Understanding the Process Instance Details report Understanding the Process Duration report Understanding the Process Summary dashboard Understanding the Count of Processes per State report Understanding the Count of Activities per State report Understanding the In-flight Process Statistics report Understanding the In-flight Activity Statistics report Understanding the Tasks Completed by Performer within the last 24 Hours report Understanding the Tasks Pending for each Performer report Understanding the Alert Monitor dashboard Understanding the Alert List dashlet Understanding the Alert Resolution report Understanding the Alerts per Activity report Understanding the Alerts per Process report Localizing the preconfigured dashboards. Administrating BAM Deployments Overview of Administrating BAM Deployments. Using Documentum Composer to migrate BAM artifacts Importing BAM artifacts into a Composer project. Instaling BAM artifacts into a repository 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 resutts sets. EMC Documentum Business Activity Mentor Version 67 Implementation Guide 168 168 168 169 169 170 170 im im 173 173 173 173 174 174 174 179 180 181 182 183 184 184 185 186 186 186 187 187Table of Contents Chapter 10 Chapter 11 ‘Appendix A AppendixB Limiting the number of records returned in a results set 198 Purging BAM execution and aggregation tables. 198 Understanding how to schedule BAM database purge jobs. 189 ‘Scheduling BAM database purge jobs 190 Purging the Audit Trail database. 101 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 Creating Custom Aggregation, Report, and Filter Entities. 193 Understanding custom aggregation, report, and fitter 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 fiers. 208 Understanding dashboard fers. 208 Configuring dashboard fitters. 209 Configuring business data fitters. 24 Configuring single and mutt-selection search fiters 212 Understanding dashboard fiter operators. 216 Understanding PRS fitters 216 Configuring PRS fitter entities. 27 Configuring PRS fier tabs 218 Configuring PRS filter token items 219 Defining fiter entity relationships. 219 Creating PRS client fiter tree items, 24 Refreshing the BAM server. 2 Deleting custom report and fter entities 2 Troubleshooting BAM dashboards are not being updated 233 Reports do not generate the expected results 234 Using og files to assess the status of BAM engine jobs 235 Email server dawn 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 Entity Relation Diagrams. Report entities. EMC Documentum Business Activity Mentor Version 67 Implementation GuideTable of Contents Appendix Database Views. Entity Relation Diagrams. Report entities... Database Views EMC Documentum Business Activity Mentor Version 67 Implementation Guide 8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 pracesses 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 fewBAM configuration procedures that are completed in Pracess 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 Documentum’s 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: + Documentun Business Activity Monitor Instaliation Guide + Documentun Business Activity Monitor Release Notes + Documentun Process Builder User Guide + Documentum Composer User Guide + Documentun TaskSpace Configuration Guide + Documentun Administrator User Guide Revision history ‘The following changes have been made to this guide EMC Documentum Business Activity Mentor Version 67 Implementation Guide "Preface Revision Date Description Taly 2011 Upiated the Understanding when to use Simple reports and Gystal Reports section of the Dea gning Reports with Process Reporting Seruces chapter Apu 2011 Initial publication EMC Documentum Business Activity Mentor Version 67 Implementation GuideChapter 1 Overview of Business Activity Monitor This chapter discusses the following + Overview of Business Activity Monitor + Understanding the Business Activity Monitor architecture Overview of Business Activity Monitor 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 isa process instance. Process instances are composed ofa specific set of activity mstances (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 comrect 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 Fora complete set of system requirements, see the Documenton Business Activity Monitoring Release Notes EMC Documentum Business Activity Monitor Version 67 Implementation Guide 8Overview of Business Activity Monitor + A case-based or other process-based application designed. + ABAM administrator defined in Content Server that is assigned the BAM Admin role. This role provides access to the BAM configuration optionsavailable in the Administration tab of TaskSpace. + A.userin Content Server that is assigned the ts_designer role. This role has control over designing reports in PRS and creating dashboards in TaskeSpace 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 storedasa 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 Doctonention 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 Ontop 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 Actrity Monitor Installation Guide for more information on clustering This section describes each component of BAM architecture in more detail 4 EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideOverview of Business Activity Monitor Figure1 Business Activity Monitor technical architecture Reporting Engine pores Understanding BAM dashboards ABAM 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 ofa 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 ofa 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 extemal Crystal Reports editor Report entities are provided wath 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 wath 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 EMC Documentum Business Activity Monitor Version 67 Implementation Guide 6Overview of Business Activity Monitor 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. Ifthe 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 whule 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 defimit 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 Asa 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 areport. A base entity isthe 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, itis 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 22 1° EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideOverview of Business Activity Monitor 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 nuns twa 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 takea 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 + Mazimum 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 + Howly + Daily + Weeldy + Monthly * Quarterly + Yearly ‘This summary information is then inserted into the agaregation tables. Understanding reports that use aggregation, page 57 contains more information about the concept of aggregation. EMC Documentum Business Activity Monitor Version 67 Implementation Guide 7Overview of Business Activity Monitor Understanding the alert engine ‘The alert engine scans execution data to identify when an alert condition is met. Ifan alert condition is, ‘met, email notifications are sent. Every time the alert engine nuns, it receives a list of active alerts (Glerts 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 dowm, 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 retums 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 | 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 8 EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideChapter 2 Quick Start Guide to BAM This chapter discusses the following + 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 tis easier to design more complicated BAM applications In this chapter you leam how to monitor a process, create a process execution report, and design a dashboard that displays your report. Ata 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 Aucit Trail is tumed on, When the Audit Trail Settings is tumed 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: EMC Documentum Business Activity Monitor Version 67 Implementation Guide ®Quick Start Guide to BAM 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 From the Tools menu, select Process Properties. Select the On radio button Click OK seed | om | ater | eittine: —maaeons a Gouoee: Mana Cretan eee Wao attaptecwe Rarely one. ee a TT | cia F Se dmateneteteptag toate Serene = eae re] ene ne 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 asad Berean 4. Inthe Name field enter Process Execution and click Finish. ‘The report is added to the category 2 EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideQuick Start Guide to BAM On the Palette, click the Process report entity category. Click the Process Execution report entity. fas = ‘Then, hover your mouse over the report design area and click your left mouse button. The report entity is added to the design area Click the Refresh button © in the Data Source Preview window Data is displayed in the Data Source Preview window In the State list box, select Published. Publishing makes the report available for use in a dashboard. oe ae —— = Cece ere ps ond |e = 3 —— = ay = a Bee || ‘= Somes See paren EMC Documentum Business Activity Monitor Version 67 Implementation Guide aQuick Start Guide to BAM 10. From the File menu select Save Designing a BAM dashboard ABAM dashboard isa 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 ofat least one, and typically multiple, dashiets. 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. Login to TaskSpace 2. Select the Configuration tab. 3. From the navigation tree, select Dashboards and then click Create res emma aie a genet — ie ‘Eremtstesie 4. Inthe 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 2 EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideQuick Start Guide to BAM ‘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. Clickeand 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, EMC Documentum Business Activity Monitor Version 67 Implementation GuideQuick Start Guide to BAM etna Hae: ae et — so Looe aa es scam ame somata “correcessbran oe eheeninsin seem nara 28 [BMC Documentum Business Activity Montor Version 6.7 Implementation GuideChapter 3 Configuring Business Activity Monitor This chapter discusses the following + 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 (SD Ts 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@ 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 EMC Documentum Business Activity Monitor Version 67 Implementation Guide 2Configuring Business Activity Monitor + 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 Enable processes formontering Process Designer Process Administrator § = ea a [oy loeeens | = & ns W i rnd na ‘Admin Tab, TaskSpace — Update business oe Sata Ba habase When requied (optional) Proooes Buller Uodate business data In BAM catabace Contiaure recovery period ‘Configure data transioesatngs| Adin Tab, TaskSpace Enabling processes for monitoring Processes are enabled for monitoring in Process Builder Monitoring begins when process data is vmitten 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 Docronenttn 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 op tions 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. = EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideConfiguring Business Activity Monitor 2. Opena 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 tun 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 nights first, and assign the privilege to your user. For example, if you want to grant the dinadiin 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. Login to TaskSpace as a user with administrative rights, Click the Administration tab Expand User Management on the tree menu, Select Users. Navigate to and select the user to which the config audit extended privilege is being assigned. Click Properties. Select Config Audit from the Extended Privileges drop-down. Click Ok EMC Documentum Business Activity Monitor Version 67 Implementation Guide aConfiguring Business Activity Monitor 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 attnbute 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: Ifan attribute is selected in the Activity Inspector window but is not selected in the Structured Data Type window, the attnbute 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 bath Process Builder and the Administration tab of TaskeSpace To enable an SDT attribute for monitoring: 1. Log in to Process Builder. 2. Right-cticlea 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 Es EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideConfiguring Business Activity Monitor 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 wath 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: Open a process template Open the Activity Inspector window of an activity. Click the Data tab Select the package to monitor ‘Select the This package can be used to generate reports checkbox Click Ok to close the Activity Inspector window 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: 1. Open a process template 2. Open the Activity Inspector window of an activity, 3. Click the Data tab EMC Documentum Business Activity Monitor Version 67 Implementation Guide 2Configuring Business Activity Monitor 4. Select the process variable to monitor 5. Select the This variable can be used to generate reports checkbox 6. Click Okto close the Activity Inspector window: Logging in to TaskSpace Complete this procedure to log in to TaskSpace. To log in to TaskSpace: 1. Opena supported browser. Fora list of supported browsers, refer to the Documentwn TaskSpace Release Notes. Navigate to the TaskSpace user interface at the following URL’ http:server_name:port_munberideployment_namne?appname=app_nane ‘The following table explains each variable in this URL: Table 2 The TaskSpace URL variables URL variable Explanation Server jame ‘The name of the computer on which TaskSpace is installed. port_muonber ‘The port where the application server listens for connections deployment_name ‘The virtual directory created during installation ayp_name ‘The name of a TaskSpace application Note: Ifyou 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 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. Ey EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideConfiguring Business Activity Monitor Note: Once you are logged in, you can view or delete your saved credentials by clicking Preferences 5. To entera 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 anguage 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. Touseaccessibility 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. Asi your system administrator how you can change your password a Click More Options. b. Click Change Password, 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 selecta role. Also, if your account isa member ofa role that is itselfa member of another role, the inherited role also appears in the list, as longs it has been configured for use in the TaskSpace user interface 11. Ifprompted, 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 EMC Documentum Business Activity Monitor Version 67 Implementation Guide aConfiguring Business Activity Monitor 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. Login 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. Inthe BAM Port field, enter the BAM server port number 6. Click Okat 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 SD Ts/packages + deleting SDTs/pactages + modifying SD T/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. 2 EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideConfiguring Business Activity Monitor 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. TTaskSpace can be used to update a BAM database with any changes to both SDTs and package object types. SDs and package object types can also be updated from within Process Builder, but they are separate operations. To update monitored business data with TaskSpace: 1. Login to TaskSpace EMC Documentum Business Activity Monitor Version 67 Implementation Guide 2Configuring Business Activity Monitor 2. Select the Administration tab 3. From the tree memu 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 SDT. 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 queni is container that holds work items (also Imown as activity instances) until a perjormer 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 mumber 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 ina 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 process, a queue is assigned as the performer ofa manual activity. Queues are uniguely named and have thresholds (the maximum number of work items allowed in the queue), users (@ 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 EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideConfiguring Business Activity Monitor Note: All workcitems in a queue are monitored, even if the process to which the work item belongs is not monitored. Ifthe 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 wnites process execution data to the audit tail 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: 1. Login to TaskSpace 2. Select the Administration tab 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 Okat the bottom of the window. SE grea Recor Pred eon | Prerarasmaner roca sant ee nte Avec ecoery Peed: tontd® toy? S| out Bl coer ts: [recuse EMC Documentum Business Activity Monitor Version 67 Implementation Guide 28Configuring Business Activity Monitor 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, Ina 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: 1. Login to TaskSpace 2. Select the Administration tab 3. From the tree menu select Server Management > Business Activity Monitor > Data Transfer Settings. 4. Entera value in the Data Transfer Latency field ‘The value is expressed in seconds 5. Click Okat the bottom of the window ores | temo) Onl?) Hol Sern ec is P serch Sgn ra ering ct ns BAM tes 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. Ifno 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. Maactrmyn data transfer tile 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 ey EMC Documentum Business Activity Mentor Version 6.7 Implementation GuideConfiguring Business Activity Monitor 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: 1. Login to TaskSpace Select the Administration tab. 2 3. From the left tree menu select Server Management > Business Activity Monitor > Data ‘Transfer Settings Enter a value in the Maximum Data Transfer Idle Time field Click Okat the bottom of the window Serctythe men ote erate DUM ner eck wc: nthe caret tn ne mat dt Modifying the dashboard report time-out parameter BAM dashboard reports time out when they tae 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: Navigate to [TaskSpace] AVEB -INF/classes! Open thinClientContest 2m! with any XML editor Find