Designing processes - EMC Community Network
Designing processes - EMC Community Network
Designing processes - EMC Community Network
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
<strong>EMC</strong> ® Documentum ®<br />
xCelerated Composition<br />
Platform<br />
Version 1.6<br />
Best Practices Guide<br />
<strong>EMC</strong> Corporation<br />
Corporate Headquarters:<br />
Hopkinton, MA 01748–9103<br />
1–508–435–1000<br />
www.<strong>EMC</strong>.com
<strong>EMC</strong> believes the information in this publication is accurate as of its publication date. The information is subject to change without<br />
notice.<br />
The information in this publication is provided as is. <strong>EMC</strong> Corporation makes no representations or warranties of any kind with<br />
respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a<br />
particular purpose. Use, copying, and distribution of any <strong>EMC</strong> software described in this publication requires an applicable software<br />
license.<br />
For the most up-to-date listing of <strong>EMC</strong> product names, see <strong>EMC</strong> Corporation Trademarks on <strong>EMC</strong>.com. All other trademarks used<br />
herein are the property of their respective owners.<br />
© Copyright 2011 <strong>EMC</strong> Corporation. All rights reserved.
Table of Contents<br />
Chapter 1 Overview ..........................................................................................................9<br />
Chapter 2<br />
Introduction........................................................................................................9<br />
Advantages of using an automated system ..........................................................9<br />
Recommended approach to solution construction...............................................10<br />
An example: a Grants Management application .................................................10<br />
Technology Considerations ............................................................................... 11<br />
Product Overview...........................................................................................13<br />
Documentum products......................................................................................13<br />
Documentum ECM platform ..............................................................................14<br />
Service-oriented architecture .........................................................................14<br />
Content management and repository services.................................................14<br />
Business process management.........................................................................14<br />
Chapter 3 Planning and <strong>Designing</strong> the Application ........................................................17<br />
Planning and designing the application overview ................................................17<br />
Project preparation ...........................................................................................18<br />
Business requirements phase ...........................................................................19<br />
Interpreting the intentions of the client ............................................................19<br />
Customization...............................................................................................20<br />
Roles and permissions .....................................................................................20<br />
Setting up the Development Environment ..........................................................20<br />
System Design and Prototyping Phase ..............................................................20<br />
Prototyping and Workshops ...........................................................................21<br />
Planning the Deployment ..................................................................................28<br />
Design Review .................................................................................................28<br />
Chapter 4 Creating the Data Model .................................................................................29<br />
Understanding the data model...........................................................................29<br />
Understanding process variables ...................................................................29<br />
Understanding packages ...............................................................................30<br />
Package attributes versus SDTs.....................................................................30<br />
Understanding process parameters................................................................31<br />
Changing process elements...........................................................................31<br />
Selecting SDTs and package attributes for monitoring.........................................31<br />
Chapter 5 <strong>Designing</strong> the Process ...................................................................................33<br />
<strong>Designing</strong> the process overview ........................................................................33<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 3
Table of Contents<br />
Chapter 6<br />
<strong>Designing</strong> activities...........................................................................................33<br />
Defining activity triggers ................................................................................34<br />
Creating wait activities...................................................................................34<br />
Sending tasks to a temporary set of users ......................................................34<br />
<strong>Designing</strong> <strong>processes</strong> ........................................................................................35<br />
Creating complex conditional routing with a decision split ................................35<br />
Using sub-<strong>processes</strong>.....................................................................................36<br />
Understanding message correlation ...............................................................36<br />
Using the data mapper .....................................................................................37<br />
Mapping repeating attributes..........................................................................37<br />
Setting the context for repeating attributes ......................................................38<br />
Adding multi-valued attributes ........................................................................41<br />
XML and other data formats...........................................................................42<br />
Setting custom object types for attachments ...................................................42<br />
Looping ...........................................................................................................42<br />
Inter-process communication ............................................................................50<br />
Using the process debugger .............................................................................55<br />
Debugging custom methods with the process debugger ..................................56<br />
Process design and Business Activity Monitor (BAM)..........................................57<br />
Enabling reporting for BAM............................................................................58<br />
Reporting on data in an external database to BAM..........................................59<br />
Process design and performance ......................................................................59<br />
Choose one automatic performer ...................................................................59<br />
Performance and stability of executing automated workflow activities ...............60<br />
Large SDTs and performance ........................................................................60<br />
Deployment considerations ...............................................................................60<br />
Migrating or upgrading Process Builder ..........................................................61<br />
Process versioning........................................................................................61<br />
Accessing structured data types from a custom application .................................61<br />
Creating the User Interface.............................................................................63<br />
Creating form templates in Forms Builder ..........................................................63<br />
General tips for user interface design .............................................................63<br />
Multiple ways to start a process .....................................................................64<br />
Options for when a process starts ..................................................................69<br />
Options to design a task view ........................................................................70<br />
Process and form template version links.........................................................73<br />
Custom error messages ................................................................................74<br />
Data adaptors...............................................................................................75<br />
Using one data source adaptor to populate multiple fields................................77<br />
Performance.................................................................................................84<br />
Implementing TaskSpace applications ...............................................................85<br />
Iterative rollout of a TaskSpace application .....................................................85<br />
Working with task templates ..........................................................................86<br />
Setting the height of the metadata pane in a folder view ..................................86<br />
Working with configurable actions ..................................................................87<br />
Chapter 7 Monitoring Business Activity .........................................................................89<br />
System requirements........................................................................................89<br />
Reporting requirements ....................................................................................89<br />
Dashboard design considerations......................................................................90<br />
Crystal Reports versus Simple Reports..............................................................91<br />
4 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Table of Contents<br />
Chapter 8<br />
Cleaning production environments.....................................................................92<br />
Custom aggregation .........................................................................................92<br />
Leveraging the Preconfigured Dashboards.........................................................93<br />
Dashboard refresh intervals ..............................................................................93<br />
<strong>Designing</strong> drill-down reports..............................................................................93<br />
Formatting reports to be more readable .............................................................93<br />
Computed Column dates and sorting.................................................................94<br />
Performance and Scalability...........................................................................95<br />
General approach to performance .....................................................................95<br />
System configuration guidelines ........................................................................96<br />
Small configurations......................................................................................96<br />
Medium configurations ..................................................................................96<br />
Large configurations......................................................................................97<br />
Configuration best practices...........................................................................97<br />
Factors that affect performance and scalability ...................................................98<br />
Automatic activities .......................................................................................98<br />
Search forms ................................................................................................98<br />
Task lists ......................................................................................................99<br />
Preconditions................................................................................................99<br />
Skill-set matching........................................................................................ 100<br />
Logins ........................................................................................................ 100<br />
Recommended application server settings ....................................................... 100<br />
Recommended Content Server settings........................................................... 101<br />
Disabling full-text indexing ........................................................................... 103<br />
Purging existing full-text events.................................................................... 104<br />
Recommended database server settings ......................................................... 105<br />
Tuning and troubleshooting performance problems........................................... 105<br />
Chapter 9 Deploying the Application ............................................................................ 107<br />
Deploying the application overview.................................................................. 107<br />
The deployment process................................................................................. 107<br />
Deployment best practices.............................................................................. 108<br />
Chapter 10 Archiving the Application............................................................................. 111<br />
Manually Archiving TaskSpace Applications ..................................................... 111<br />
Best practices before and after archiving ...................................................... 111<br />
Archiving in Documentum releases 6.6 and higher ........................................ 112<br />
Testing the Archived Application................................................................... 116<br />
Troubleshooting the Archived Application ..................................................... 118<br />
Appendix A Prototyping Business Activity Monitor dashboards..................................... 121<br />
Prototyping Business Activity Monitor dashboards ............................................................ 121<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 5
Preface<br />
This guide is intended to help <strong>EMC</strong> partners and practitioners use the Documentum xCelerated<br />
Composition Platform (xCP) products to build repeatable business solutions. It focuses on the<br />
best practices for using these products by covering topics such as planning, implementation,<br />
performance, and deployment.<br />
This guide addresses process-based applications and makes recommendations on how to integrate<br />
these products to produce an end-to-end solution. These processed-based applications can be broken<br />
down into a series of steps, in which an individual or software system performs each step. Examples<br />
of process-based applications are ordering a book over the Internet, applying for a checking account,<br />
placing a trip reservation, making an insurance claim, and applying for a loan.<br />
Note:<br />
• This guide should be used in addition to, and not a replacement for, the user guides that come<br />
with the individual products. This guide also assumes that you are familiar with xCP products.<br />
• We refer to the recommendations in this guide as best practices. However, most of the<br />
recommendations are really good practices that work under most conditions. Each client is<br />
different in both goals and environment, and not all recommendations work in all situations.<br />
As you design a solution, consider the trade-offs between usability, performance, and time to<br />
market, and make an assessment based on that information. For example, this guide provides<br />
several suggestions on improving performance, these suggestions could be relaxed for small<br />
implementations with just a handful of users. You may determine that it is best to deviate from<br />
some of these best practices based on your trade-off analysis.<br />
Intended Audience<br />
The audience for this guide is the project team that is creating business solutions. In particular,<br />
the primary audience includes Application Development Managers, Partner Project Architects,<br />
and Project Managers.<br />
Revision History<br />
The following changes have been made to this document.<br />
Revision Date<br />
April 2011<br />
August 2011<br />
Description<br />
Initial publication<br />
BAM topic updated: Crystal Reports versus Simple Reports.<br />
Archiving the Application section added.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 7
Preface<br />
8 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 1<br />
Overview<br />
This chapter discusses the following:<br />
• Introduction<br />
• Advantages of using an automated system<br />
• Recommended approach to solution construction<br />
• An example: a Grants Management application<br />
• Technology Considerations<br />
Introduction<br />
Business <strong>processes</strong> occur in many contexts: government, law, health-care, insurance, retail,<br />
telecommunications, and other domains. A process orchestrates a combination of human and<br />
automated activities that produce and deliver information. This information can be in the form of<br />
structured data or unstructured content, and the process must be able to manage both types easily and<br />
seamlessly. During the course of the process, users add documents and enter business data. The<br />
process uses this information to route the process to the correct people. The people working in the<br />
process use this process information to make the correct decisions.<br />
One example of process-based solution is case management. The case launches one or more <strong>processes</strong><br />
to perform its work. The best practices described in this document apply to both case management<br />
solutions and to process-based applications in general. See the xCelerated Composition Platform (xCP)<br />
Grants Management Sample Application and its documentation (xCelerated Composition Platform<br />
Grants Management Sample Application Technical Reference Guide) for an in-depth discussion of<br />
case management concepts and practices.<br />
Advantages of using an automated system<br />
Using an automated system to manage a business process improves efficiency and effectiveness and<br />
provides better service to the client. Using an automated system provides these benefits:<br />
• Eliminates the need for time-consuming and error-prone paper-based systems to compile and<br />
manage process data<br />
• Improves processing time by eliminating the need to locate and physically transport information<br />
stored in file cabinets<br />
• Enables ongoing monitoring and control of the process through a real-time dashboard<br />
• Allows process participants to interact, giving their inputs and participating in discussion threads<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 9
Overview<br />
• Provides security and information rights management to keep personal information secure<br />
• Uses a secure repository to meet government requirements for secure records management<br />
Recommended approach to solution<br />
construction<br />
The approach to solution construction that is being recommended in this document is based on the<br />
configuration of pre-built templates and components. This represents a significant departure from<br />
the conventional approach of writing custom code. This is important to the business stakeholders<br />
for these reasons:<br />
• Cost - Programming resources, such as Java programmers, are expensive. Any solution that<br />
minimizes custom development also reduces cost.<br />
• Risk - Working from components and design patterns that have been proven in many client solutions<br />
minimizes technical risk.<br />
• Adaptability - Solutions constructed through configuration are much easier to modify as needs<br />
evolve.<br />
• Time to market - The time required to design, implement, and debug custom code is significant.<br />
Configuration of reusable components is dramatically faster than custom coding.<br />
An example: a Grants Management application<br />
The following scenario describes the process of applying for grant funding. This process is divided<br />
into a series of activities.<br />
1. A grant applicant fills out a grant application form and submits it by email.<br />
2. The grantor agency receives the application, which initiates the grants management process.<br />
3. An automated activity performs a quick validation of the application and assigns a priority level<br />
to it.<br />
4. The grants management process automatically sends a notification of receipt to the grant applicant<br />
and creates a case folder. This folder contains all information related to the case, including the<br />
application data, supporting documents, emails about the case, and so on.<br />
5. A Grants Manager receives a task to work on the grant application.<br />
6. If the Grants Manager does not think the documents supplied by the grant applicant are sufficient,<br />
the Grants Manager can ask for additional supporting documentation.<br />
7. The Grants Manager selects a team of experts to review the application.<br />
8. The Grants Reviewers can add comments to informal discussion groups. After the reviewers<br />
make a final determination, they recommend to approve or deny the application and provide a<br />
justification for their recommendation.<br />
9. The Grants Manager makes a final decision based on the recommendations from the Grants<br />
Reviewers. The system automatically sends an email notification to the grants applicant advising<br />
the applicant whether the request for funding was approved or denied.<br />
10 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Overview<br />
This scenario is an example of a case management application. It triggers several <strong>processes</strong> to<br />
manage the progress of the grant application. You can apply the best practices in this guide to all<br />
process-based applications.<br />
Technology Considerations<br />
Process-based applications blend the human element with the software system element. The human<br />
element is the part that calls for making judgment calls and decisions. The software systems that<br />
manage the information and the process support these decisions.<br />
The solution is based on three technology foundations:<br />
• Business Process Management - to define and orchestrate the series of activities to be performed<br />
• Enterprise Content Management - to manage documents, images, and associated metadata<br />
• Collaboration - to provide the ability for involved parties to interact, share information, and make<br />
joint decisions<br />
In addition, the following <strong>EMC</strong> products provide vital services to a process-based application solution:<br />
• Captiva: The product family for transforming business-critical paper, fax, and electronic data<br />
sources into business-ready content suitable for processing by enterprise applications.<br />
• Process Builder: Allows for the creation of process templates. A process template captures the<br />
definition of a business process, enabling users to perform the process repeatedly.<br />
• Forms Builder: An interactive tool used to create and modify form-based templates and store them<br />
in a repository. Forms Builder enables users to design user interface templates for searching, viewing<br />
documents and folders, process initiation, task lists, tasks, and basic forms within Documentum xCP.<br />
• Process Engine/Process Integrator: The server components that orchestrate <strong>processes</strong> and<br />
integrate with external systems and data.<br />
• TaskSpace: The easy to configure user interface that can be used for task processing and document<br />
retrieval in the business process. TaskSpace offers integrated document viewing with annotations<br />
and enables the management of work queues. TaskSpace is the user interface for the application.<br />
• Business Activity Monitor (BAM): Provides a performance dashboard for monitoring and<br />
analyzing process-based applications. In real time, BAM tracks defined key performance indicators<br />
(KPIs), reporting on process performance and providing alerts for conditions that fall outside of<br />
designated thresholds. With BAM, the manager can assess the overall performance level of the<br />
application and focus on problems in a specific case.<br />
• Records Management: Provides the means to ensure compliance with legal and regulatory<br />
requirements. The agency can set rules for retention policies to preserve case files for a specified<br />
time. The process automatically triggers this capability.<br />
• Documentum Collaborative Services: Enables teams to work securely and collaboratively within<br />
web applications.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 11
Overview<br />
12 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 2<br />
Product Overview<br />
This chapter discusses the following:<br />
• Documentum products<br />
• Documentum ECM platform<br />
• Business process management<br />
Documentum products<br />
The Documentum enterprise content management (ECM) and business process management (BPM)<br />
products provide a single platform with a complete, fully integrated set of technologies that interact to<br />
build comprehensive business solutions.<br />
The following figure illustrates the core Documentum ECM and BPM products as they are typically<br />
deployed to support business solutions:<br />
Figure 1<br />
Documentum ECM and BPM products<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 13
Product Overview<br />
Documentum ECM platform<br />
The Documentum ECM platform provides a unified environment for capturing, storing, accessing,<br />
organizing, controlling, retrieving, delivering, and archiving any type of unstructured information<br />
across an extended enterprise. With support for Web 2.0 information requirements and high-volume<br />
transaction and archive environments, the Documentum content management platform can support<br />
global enterprise deployments.<br />
Based on an extensible, open, scalable, secure, and service-oriented architecture, Documentum<br />
comprises a set of integrated products and services that work together to provide comprehensive<br />
content-enabled solutions.<br />
Service-oriented architecture<br />
Service-oriented architecture (SOA) looks at IT assets as service components, establishing a software<br />
architectural approach to building business applications. The SOA approach is based on creating<br />
standalone, task-specific reusable software components that function and are made available as<br />
services.<br />
Content management and repository services<br />
The Documentum Content Server and Repository manage information and content with<br />
enterprise-grade security, scalability, and reliability, and a common set of policies for all content assets<br />
across an organization. Additionally, the Documentum Repository manages the application definition<br />
artifacts, configurations, and supporting models.<br />
Business process management<br />
Documentum xCP provides business process management capabilities and integrates fully with the<br />
ECM platform. Using a model-driven approach, combined with services orchestration capabilities,<br />
Documentum xCP provides the ability to configure applications without coding requirements. xCP<br />
also provides a complete range of tools for process and task modeling, data and content modeling,<br />
presentation modeling, and business-logic modeling. Changes to business solutions can be made<br />
declaratively in the appropriate model, without writing or modifying software code, providing a flexible<br />
and agile framework for building as well as maintaining and improving business solutions over time.<br />
The service-oriented architecture also allows for easy integration with existing line of business systems,<br />
applications, and external systems to gain additional value and leverage from those investments. As a<br />
composition platform, xCP provides reusable components, model-based configuration, a configurable<br />
user interface and dashboard tools, and reference applications to enable developers and IT architects to<br />
compose and maintain applications using graphical tools.<br />
Documentum xCP includes the following capabilities and products:<br />
14 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Product Overview<br />
Application<br />
presentation and<br />
composition<br />
Business process<br />
design and workflow<br />
configuration<br />
Application GUI<br />
design<br />
Reports<br />
Team collaboration<br />
Documentum TaskSpace provides a highly configurable user interface<br />
that unites process, content, and monitoring into a single user experience<br />
for transactional business applications. TaskSpace is deployed as a web<br />
application into a Java Application server.<br />
Process Builder is a business process design tool that allows<br />
non-programmers to configure how services, manual activities, and<br />
information are combined and orchestrated to accomplish specific business<br />
actions and logic. Process Builder allows the designer to configure<br />
process activities such as simple manual tasks, high-volume work<br />
queues, automated content management actions, and sophisticated system<br />
integration logic through easy-to-use visual design techniques. In addition,<br />
Process Builder supports the defining of process rules, priorities, and<br />
exception handling. Deployment of standard activity templates enables<br />
enterprises to maximize both productivity and standardization through<br />
reuse across multiple applications. The process models defined by<br />
Process Builder are deployed into Documentum repositories through the<br />
Documentum Content Server. The runtime execution of the process models<br />
is carried out by the Process Engine.<br />
Forms Builder is used to create web-based graphical user interfaces<br />
available through TaskSpace. Forms Builder also serves as the design tool<br />
for producing high-fidelity, paper-like electronic forms for data capture and<br />
presentation. Forms Builder produces XForms models that are stored in<br />
the Documentum Repository. At runtime, web-based user interfaces are<br />
generated by an embedded forms engine that interprets the XForms models<br />
and produces HTML. The forms engine deploys as part of TaskSpace in<br />
the same web application.<br />
Documentum Business Activity Monitor (BAM) and Process Reporting<br />
Services (PRS) provide detailed reporting and monitoring of solutions.<br />
BAM deploys in two parts, as a server-side engine (BAM Server) and<br />
as a TaskSpace component. The BAM Server continuously formats and<br />
aggregates events and data as the application runs. This engine deploys into<br />
any Java application server. The BAM TaskSpace component deploys<br />
as part of TaskSpace and generates the graphical dashboards that contain<br />
the reports around the data and events managed by the BAM Server.<br />
BAM typically uses a separate database from the Documentum Repository<br />
for managing its reporting data, although in some cases, it can share<br />
the same database instance using different tablespaces. The BAM data<br />
definitions (including both structured data types and content metadata)<br />
are synchronized by Process Builder through the BAM Server. PRS is a<br />
reports builder tool that enables users to configure graphical reports against<br />
the data in the BAM database. The reports are presented in the TaskSpace<br />
dashboards.<br />
Documentum Collaborative Services (DCS) provide team collaboration<br />
around artifacts and information. DCS is a set of services and objects<br />
supporting team collaboration exposed in the TaskSpace application<br />
environment. The primary capability includes ad-hoc discussion threads<br />
available on any item in TaskSpace.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 15
Product Overview<br />
Process automation,<br />
services orchestration,<br />
human task<br />
management<br />
Data and content<br />
integration<br />
The Documentum Process Engine carries out the automation of all business<br />
<strong>processes</strong> defined by Process Builder in the applications. Process Engine<br />
deploys into the embedded JBoss application server that is provided as part<br />
of the Documentum Server. Certain aspects of the Process Engine also<br />
execute in the Documentum Content Server, specifically process runtime<br />
state management, which uses the Documentum Repository for state<br />
persistence.<br />
Process Integrator manages both inbound and outbound integration of data<br />
and content for the applications and provides mapping and transformation<br />
capabilities for both data and content integration. The integration<br />
configuration, including connector end-point definition and correlation<br />
mapping, is carried out with Process Builder. Process Integrator deploys<br />
its outbound integration services, data/content mapping, and correlation<br />
capabilities in the embedded JBoss application server. Inbound protocol<br />
connectors can be deployed into any Java application server, including the<br />
embedded JBoss application server.<br />
The following products are optionally available and provide additional integrated capabilities to<br />
Documentum xCP:<br />
Compliance<br />
Information capture<br />
and input<br />
Dynamic<br />
correspondence<br />
generation<br />
Retention Policy Services and Records Manager automate the entire content<br />
lifecycle to mitigate risk of non-compliance and leverage full audit control<br />
for retention policy management and records management.<br />
Captiva InputAccel provides intelligent capture for paper, fax, and<br />
electronic data sources<br />
Document Sciences xPression automatically generates and distributes<br />
customer communications via customer-preferred formats and channels<br />
(e-mail, web, print, and mobile).<br />
16 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 3<br />
Planning and <strong>Designing</strong> the Application<br />
This chapter discusses the following:<br />
• Planning and designing the application overview<br />
• Project preparation<br />
• Business requirements phase<br />
• Roles and permissions<br />
• Setting up the Development Environment<br />
• System Design and Prototyping Phase<br />
• Planning the Deployment<br />
• Design Review<br />
Planning and designing the application<br />
overview<br />
Case management projects, like other xCP applications, are created in a series of phases. The following<br />
diagram illustrates a typical phase structure:<br />
Thorough planning and testing is important for process-based applications and can make a difference<br />
in whether a project succeeds or fails. What makes this possible is the extensive use of templates for<br />
creating <strong>processes</strong>, forms, reports, and user interfaces. Anticipating risks, aligning on requirements,<br />
and designing the solution carefully are critical to success.<br />
Another best practice recommendation is to use an agile methodology. Break up the full application<br />
into smaller modules and establish frequent cycles of design, implementation, and testing, as illustrated<br />
in the above diagram. This approach is considered a more successful alternative to the classic waterfall<br />
approach.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 17
Planning and <strong>Designing</strong> the Application<br />
The goal of the xCP platform is to enable solution construction with little or no custom coding. Use<br />
templates to create <strong>processes</strong>, forms, and user interface screens. For planning, xCP applications can<br />
require more time dedicated to requirements gathering and solution prototyping.<br />
This chapter addresses business requirements, solution design, and prototyping. It offers suggestions<br />
for planning and designing solutions that are directly relevant to <strong>EMC</strong> products.<br />
Project preparation<br />
To prepare the project, do the following:<br />
• Read the documentation<br />
• Define project roles<br />
• Take training<br />
• Create a project plan<br />
Read the documentation<br />
The delivery team must understand the intended purposes of <strong>EMC</strong> products. Members of the project<br />
team must read and understand the product documentation. The best place to start is with the <strong>EMC</strong><br />
Documentum xCelerated Composition Platform Sample Application Tutorial. The tutorial takes the<br />
reader through the development of a simple process-based application and describes how to create<br />
reports and a BAM dashboard. In addition, each product ships with documentation that introduces<br />
and explains the product functions and provides guidance on how to use them correctly. Reading the<br />
documentation helps to avoid misunderstandings, plan your project, and save development time.<br />
Define project roles<br />
The following is a list of key roles that are needed in a process-based project. (This is not a complete<br />
list of roles.)<br />
• <strong>EMC</strong> Project Manager<br />
• Client Project Manager, to assist with internal project coordination<br />
• Business Users, to define and clarify functional requirements<br />
• Information Architect, responsible for creating the data model<br />
• Process Architect, responsible for designing the process in Process Builder<br />
• User Interface Architect, responsible for designing Forms and TaskSpace screens<br />
• BAM Architect, responsible for designing the reports and dashboard<br />
• Client System Administrator, <strong>Network</strong> Administrator, and Information Security, and Database<br />
Administrator (DBA) to support the implementation and enable account creation<br />
A single person or several people can play these roles, depending on the size and staffing of the project.<br />
The architects must work closely together to ensure consistency of approach.<br />
Take Training<br />
Training is important for project architects to understand the product architecture and current features<br />
of <strong>EMC</strong> Documentum products. Training can be carried out in formal training classes, in targeted<br />
meetings with engineering, or in <strong>EMC</strong> MyLearn web-based classes.<br />
18 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Planning and <strong>Designing</strong> the Application<br />
Create a Project Plan<br />
Create a Project Plan to outline the basic set of tasks required to implement a solution. This plan can<br />
assume an out-of-the-box solution without any customization. If customization becomes necessary,<br />
add it to the project plan as a separate module. For each customization module, the project manager<br />
can estimate the impact on cost and schedule.<br />
Include a Project Roadmap in the Project Plan that lays out the major phases of the project in the form<br />
of a flow diagram and specifies the inputs and outputs of each phase. The inputs are templates that<br />
define the minimum information that must be gathered to perform the phase. Include information or<br />
participation needed from the client. The outputs are the deliverables produced by the phase. Negotiate<br />
the level of participation by the client with the project sponsor in the planning phase.<br />
Business requirements phase<br />
Request that the client provide the following information for the Business Requirements phase:<br />
• Current technical environment<br />
• High-level business requirements<br />
• Numbers and roles of system users<br />
• Estimated transaction volumes<br />
• Descriptions of ingestion mechanisms (such as email, scanners, and EDI) and equipment used to<br />
capture the data<br />
• Samples of the content that the system will ingest<br />
• Relationships between data and user roles (required to define security roles)<br />
• Existing business process diagrams<br />
The project team can prepare templates for this data so that the client clearly understands, in advance<br />
of the engagement, what is needed and how to gather and format the information. Design these<br />
templates so that the delivery team can use the information to configure the system.<br />
Negotiate the project roadmap with the project sponsor. Consider a solution that takes into account<br />
both the needs of the client and the capabilities of the product. Both views are critical for success.<br />
Interpreting the intentions of the client<br />
An engagement often begins when the client provides functional specifications. Think of the functional<br />
specifications as a starting point for the design discussion. If you follow the requirements too literally,<br />
you run the risk of not being able to use <strong>EMC</strong> products as they are intended to be used. This can lead<br />
to expensive customization, which can lead to support issues and an unsatisfied client.<br />
Translate the functional requirements into business requirements. Ask questions so that you can<br />
reveal the requirements behind the requirements. For example, a specification might state that the<br />
system should limit a user’s ability to work on multiple cases. If the requirement does not look right,<br />
it probably is not right. A business requirement can often be implemented in different ways. For<br />
example, calculate sales tax is a business requirement. One functional requirement can state that the<br />
system must populate a database lookup table with date, item type, and the tax to be charged. Or,<br />
the business requirement could be met by a second, alternative functional requirement. Articulate to<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 19
Planning and <strong>Designing</strong> the Application<br />
the client the ways in which xCP addresses these alternatives. Define the client requirements clearly<br />
before implementing xCP projects.<br />
Customization<br />
Try to avoid customization. Following client specifications exactly can require costly and<br />
time-consuming customization. It is more efficient to work within the functionality of the tools.<br />
Customization prolongs the time to solution and creates a challenge with future upgrades. xCP<br />
projects are high volume. If there are numerous customizations, the upgrade process can be risky and<br />
expensive. The client may need to rebuild each application customization from scratch, driving up<br />
the total cost of ownership and increases risk. There may be some cases when you need to write<br />
custom code, but keep it to the absolute minimum.<br />
Roles and permissions<br />
During the planning stage of your project, identify the roles of the performers involved in the process.<br />
For each role, identify the permissions that each performer must have to access the data required to<br />
complete assigned tasks. Include permissions for data that is read-only and for data that the performer<br />
enters or modifies.<br />
Configure permissions as follows:<br />
• Give the user who will be starting workflow instances RELATE permissions and START<br />
PROCEDURE extended permissions.<br />
• Set the access control list (ACL) of the process variables to allow performers to edit the process<br />
variables in a manual task.<br />
• Set the ACL of the package object to allow performers to read or edit the package fields based on<br />
the business requirements.<br />
Setting up the Development Environment<br />
We recommend using WMware images to manage the development environment. This approach<br />
offers several advantages. It allows the delivery team the ability to control its own infrastructure,<br />
which is preferable to relying on the client to manage the development environment for the team. It<br />
can also speed up the delivery cycle and facilitate the testing cycle by providing a clean environment<br />
for validating the solution. Eliminating the peculiarities and idiosyncrasies of a client environment<br />
saves time.<br />
System Design and Prototyping Phase<br />
In the design phase, identify detailed requirements and create the design for:<br />
• Process Definition<br />
• Task Processing User Interface<br />
• BAM Reporting<br />
20 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Planning and <strong>Designing</strong> the Application<br />
• The Data Model<br />
Do not think of these areas as being independent from one another. For example, requirements for<br />
BAM reports can suggest data fields to incorporate into the data model. In turn, these fields will be<br />
entered into forms by task processors (or captured in automated activities). One corollary of this<br />
observation is that the user interface architect must communicate frequently with the information<br />
architect to ensure consistency and completeness.<br />
The delivery team must understand the interdependence of the Process Definition, UI, BAM, and Data<br />
Model so they can properly advise the client. Ideally, the project team creates templates to facilitate the<br />
client’s understanding of the interdependencies. If the client wants to change the model, then the client<br />
understands the corresponding impact on cost. This also helps the client to understand the importance<br />
of the information the client provides to the delivery team.<br />
The guiding principle of this phase is Iterative Design. This means that a solution cannot be designed<br />
in a single step, but you need a series of workshops to reveal the design. It is not a linear path and<br />
the design can change several times, which is relatively easy to do in the planning phase. After the<br />
data model is finalized and development begins, fundamental changes can be disruptive. For example,<br />
changing the field definitions in the data model causes forms to break (since forms link to data through<br />
xpath). Complete the data model in the design phase and then lock it down.<br />
Prototyping and Workshops<br />
Dedicate one-quarter to one-third of the project to functional prototyping and client workshops. It is<br />
easy to prototype and make changes in designs within xCP during the prototyping stage. Do not move<br />
into the development phase in your project until the design is stable.<br />
Combine prototyping with workshops in which you present the design to the client and solicit<br />
feedback. These workshops should have a consistent structure and format. Use a set of predefined<br />
templates to present the information and collect feedback. These workshops can ensure that the design<br />
meets the true needs of the client and that the client understands and agrees to the solution. Initially,<br />
these workshops can be done in a storyboard manner using a whiteboard with hand-drawn screens. As<br />
you progress in the design, conduct the workshops using real screens in TaskSpace or BAM.<br />
At the beginning of the project, it is important to convince the project sponsor to make client resources<br />
available for workshops. Negotiating this agreement ensures that clients take the time from their<br />
schedule to meet with you, understand the design, and provide input.<br />
Example: Process Builder<br />
Articulate that the application is based on a process. Sometimes clients have a Visio diagram that<br />
shows the process exactly as they want it. Other times, the desired process is not well defined. In the<br />
latter case, map the process first at the business level; that is, the process shows only the activities that<br />
are significant in a business sense, dispensing with technical steps like process data mapping. One tool<br />
that is useful for this purpose is the Process Analyzer. In a series of interviews with the client business<br />
users, the process can be defined to the appropriate level of detail. This process can take a few days to<br />
complete, assuming that you have access to the subject matter experts. The following is a swim-lane<br />
process diagram in Process Analyzer depicting the hand-offs between two roles in a process.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 21
Planning and <strong>Designing</strong> the Application<br />
After the client business team agrees with the structure and flow of the process, it can be transferred to<br />
Process Builder to add the technical detail. As you refine the process in Process Builder, continue<br />
to review the process flow with the client. One effective way to review the process flow is to use<br />
the Process Debugger.<br />
The Process Debugger allows you to execute the process one step at a time with real data. This can be<br />
done even if the user interface has not yet been designed. This is an effective way to show the client,<br />
while still in the design stage, how the process will work. In some cases, the client may be familiar<br />
with how the process should work, while in other cases, the client may still be learning the process. In<br />
general, the message is to use the Process Debugger early and use it often.<br />
22 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Planning and <strong>Designing</strong> the Application<br />
Example: TaskSpace<br />
Creating the user interface is one of the biggest challenges in solution development. TaskSpace,<br />
because it is composed of forms, provides flexibility in user interface design. The following is an<br />
example of a TaskSpace screen showing a view of a case folder:<br />
Work with the client to define a consistent approach to style. We recommend writing a Style Guide<br />
that specifies standards for colors, skins, columns, labels, search criteria, sort order, and any items<br />
pertaining to the UI. A detailed specification takes time to write, but it saves time during the<br />
implementation phase of the project. Keep it simple and do not over-engineer.<br />
Note: Design the Style Guide as a structured template to ensure that you are gathering the appropriate<br />
information. Also use this template to show the client how things will be implemented and to track any<br />
configuration changes. The result is to create a consistent look and feel for the application.<br />
Example: BAM<br />
With BAM, the first step in the planning is to identify the users; that is, the roles of the individuals who<br />
need access to the dashboards. For example, one role can be the operational manager who watches<br />
each case or process instance to ensure that it meets the Key Performance Indicators (KPIs) for<br />
process timing and quality. Another role can be the Line of Business (LOB) executive who tracks<br />
process performance against aggregate business goals. These two roles require different dashboards<br />
that contain different reports.<br />
Following is an example of a template for capturing this information:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 23
Planning and <strong>Designing</strong> the Application<br />
Dashboard User Summary<br />
Role 1: Operational Manager<br />
Examples: Wayne Tyson, Shirley Rosen, and Roxanne Plaskow<br />
Responsibility: Identify <strong>processes</strong> that violate Service Level Agreements and take immediate action.<br />
Frequency of Access: Every 15 minutes<br />
Role 2: Line of Business Executive<br />
Examples: Henrietta van Kampen<br />
Responsibility: Ensure that the process meets business metrics for revenue and quality.<br />
Frequency of Access: Twice a day<br />
The next step is to focus on each role and identify the report required. Write a reports summary<br />
specification, which can be based on the following template:<br />
01-RPT-07 - Revenue by Type (report number and name)<br />
Report Purpose<br />
Summarize why this report is needed.<br />
Report Details<br />
Report Type<br />
Describe the structure, information contained in the report and any drill-down behavior.<br />
Audience<br />
The audience for this report includes:<br />
Role 1<br />
Role 2...<br />
Frequency and Timing<br />
How often will the data in this report be changed How often should the report be refreshed<br />
Report Sample (mockup)<br />
24 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Planning and <strong>Designing</strong> the Application<br />
Filters<br />
Describe filters that the user needs<br />
Drilldowns<br />
Is there a need to drill this report down If so, on what field will the drill-down occur and what is the<br />
drill-down report<br />
Avoid burdening the user with too much information in the dashboard. If more detail is needed,<br />
then the report designer can create drilldowns.<br />
For example, you have a process that is a new account opening. The executive user has requested<br />
to see three things in the dashboard:<br />
• The number of new accounts that were opened in each country (this week)<br />
• The distribution of new accounts by customer type<br />
• The average time to complete the new accounts opening process<br />
The first report is a bar chart, the second report is a pie chart, and the third report is a dial-gauge. In the<br />
client workshops, the BAM architect can present the following reports to the client in rough form:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 25
Planning and <strong>Designing</strong> the Application<br />
Figure 2<br />
Number of new accounts by country<br />
Figure 3<br />
Number of new accounts by customer type<br />
26 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Planning and <strong>Designing</strong> the Application<br />
Figure 4<br />
Average Process Duration (in hours)<br />
These reports can be created in Excel, PowerPoint, or drawn by hand. The dashboard can be mocked<br />
up by copying and pasting these reports.<br />
The general approach is to do simple things first to ensure that everyone agrees on the report<br />
prototypes. The report can be polished or enhanced at a later date. The goal is to confirm early and<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 27
Planning and <strong>Designing</strong> the Application<br />
then refine to avoid creating something that the client does not want. After the client is comfortable<br />
with the rough dashboard prototype, progress to more polished reports that were created in Process<br />
Reporting Services:<br />
Over time, the number of reports will grow and drill-downs and multi-drill-downs will be defined. You<br />
can create additional dashboard pages. Some reports can be moved from one page to another. This<br />
process is the normal, iterative process of designing BAM dashboards.<br />
Planning the Deployment<br />
During the planning phase, make note of any aspects of the system that can change when the<br />
application is transferred from the development environment to production. For example, databases<br />
used by the application generally change when moving to the production environment. Users assigned<br />
to specific activities can also be different in the production environment. It is important to compile a<br />
complete inventory of these items to use during deployment.<br />
Design Review<br />
At the end of the design phase, the project manager can schedule a design review to validate the<br />
design. This meeting can include architects and system experts who are not members of the solution<br />
project in addition to <strong>EMC</strong> engineers to ensure the technical feasibility of the proposed solution. The<br />
information gathered in the templates can be used as supporting materials to the solution design<br />
presented to the client for signature. This process reinforces the design direction the team has taken<br />
and justifies decisions made on the design. Following a successful design review with client sign-off,<br />
the project can move into the implementation/development phase.<br />
28 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 4<br />
Creating the Data Model<br />
This chapter discusses the following:<br />
• Understanding the data model<br />
• Selecting SDTs and package attributes for monitoring<br />
Understanding the data model<br />
The data model represents the data that is created or modified in a process. It is a key foundation for<br />
the solution. A flawed data model leads to rework, which consumes valuable time. Therefore, the data<br />
model must be established as early in the implementation phase as possible.<br />
Process data refers to the different types of data that flow through the process. Process data consists of:<br />
• Packages, which capture metadata associated with Documentum objects such as documents<br />
or folders.<br />
• Process variables, such as part numbers or customer addresses. Process variables can be simple<br />
data types (like String or Int) or structured data types (SDTs).<br />
• Process parameters, which enable administrators to modify and control all instances of a given<br />
workflow template.<br />
Process data can be used in transition conditions (where the next activity executing is dependent on the<br />
data values), conditional performers (in which the performer for a manual activity is selected based on<br />
a data value), and in creating service-specific messages (for instance, the creation of a SOAP message<br />
to invoke a web service). The process data model can contain transient data (modeled using process<br />
variables) as well as persistent data (modeled as packages). Define your data model early in the<br />
design process before you begin creating the process within Process Builder. Also consider the data<br />
requirements of the entire application, including the process, forms, and user interface (TaskSpace).<br />
Understanding process variables<br />
Process variables can be simple or complex. Simple process variables are based on a single attribute,<br />
such as String or Boolean. Complex process variables are based on an SDT, which is composed<br />
of a hierarchy of attributes.<br />
SDTs are composed of several attributes, organized in a hierarchical order. SDTs are used to group<br />
logically related business data. These can be created in Process Builder by importing XML schemas or<br />
by manually creating the type and then adding individual attributes to it. For example, elements of an<br />
appropriation request can be organized into the group Request with the attributes submitter_name,<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 29
Creating the Data Model<br />
submitter_address, and equipment_type. Within each SDT, you can also organize attributes into related<br />
groups that give visual structure to the data type. For example, within the customer SDT, you can<br />
have an address group that contains the attributes for city and state.<br />
SDT definitions are global and can be used by any process. An SDT used by an installed process<br />
cannot be deleted nor should any of its attributes be modified or deleted. However, it is possible<br />
to add new attributes to an SDT that is in use.<br />
Process variables store transient data; that is, data that is not needed after the workflow terminates.<br />
Typically, this data is fetched from a non-Documentum system of record (another database, for<br />
example) or is used for an internal calculation. The Process Engine manages the lifecycle of a<br />
process instantiating the process variables when the workflow is started and destroying them when the<br />
workflow terminates.<br />
Creating an SDT for each object in your workflow can help to simplify your data model. However,<br />
you should organize your SDTs in a logical manner, corresponding to business entities. If you have<br />
too many SDTs, you can end up with performance problems with the TaskSpace task list. If that<br />
occurs, then you need to consolidate the SDTs.<br />
Understanding packages<br />
A package is associated with a Documentum object, such as documents or image files, which is<br />
passed between activities in an executing process.<br />
To act on a document in any way, it must be attached to the process as a package or it must be held in a<br />
case folder. When documents are held in a case folder, you can attach the folder as a package, but<br />
you may want to consider attaching other key documents as separate packages. This enables users to<br />
act on the documents separately, so that you can perform operations such as conducting conditional<br />
routing based on the package metadata itself.<br />
Package data is persistent. However, package data is not shown in TaskSpace task lists or task forms.<br />
To enable package attributes to appear in TaskSpace, you first map the attributes to process variables by<br />
using a Process Data Mapping activity template. After you map these attributes to process variables,<br />
you can base decisions on the package attributes, such as transitioning to the next activity. Conversely,<br />
process variables are not persistent and must be mapped so that you can base decisions on the package<br />
attributes, such as routing the process to the next activity back to package attributes if you want the<br />
data to persist beyond the life of the process.<br />
Package attributes versus SDTs<br />
During the design phase, decide when you will be using packages and when you will be using process<br />
variables. The decision is important and is a key part of successful design and implementation:<br />
• If the customer wants to store and search data in the task list template, use SDTs.<br />
• If the customer wants to persist data beyond the process instance, use package attributes.<br />
• If you want both, you must initially use SDTs and then map them to package attributes at the end<br />
of the process.<br />
Some additional considerations include:<br />
30 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the Data Model<br />
• To search on SDTs in the user interface, use a task list template for the search.<br />
• If you delete or change the name of an SDT after implementing it, you will break the data binding in<br />
Forms Builder. You must delete the dangling control or rebind it to the renamed SDT.<br />
• SDTs are more lightweight than object attributes and are better for performance and scalability.<br />
Understanding process parameters<br />
Process parameters provide agility and control by allowing an application administrator to intervene,<br />
overriding the normal process execution. Process parameter values provide administrators with a high<br />
level of control over a process. Specifically, process parameters are used in place of fixed values within<br />
a process such as escalation roles, transition conditions, performer conditions, dynamic performer<br />
assignments, task name, and task instructions. Administrators can change process parameters<br />
without uninstalling the process. When an administrator changes the values of the parameter from<br />
the Administration tab in TaskSpace, the value is used in all process instances started after the<br />
change is made.<br />
Changing process elements<br />
When you decide to alter a process, use caution as you make your changes. You can add elements to<br />
the process, but avoid deleting process variables, Java methods, or structured data types. Create a data<br />
field and use it in the process, but do not delete the old field. Just avoid using it. Deleting a process<br />
variable or package from a process template can cause the process to become unstable.<br />
If you must update process data in Process Builder, ensure that you update the process data in Forms<br />
Builder, as well. Changing the name of a field in Process Builder invalidates the binding to the form<br />
template. Open the templates in Forms Builder and save them to restore the binding. Any changes to<br />
the data model (for example, adding a new SDT) require that you uninstall, save, and reinstall the<br />
form templates and <strong>processes</strong>.<br />
Changing activity names<br />
When you change the name of an activity, it is equivalent to deleting it and creating an activity in its<br />
place. All the associated information is logically deleted. Thus, it is a best practice not to change<br />
activity names after the process has been deployed.<br />
Selecting SDTs and package attributes for<br />
monitoring<br />
When you create an SDT you must mark it as reportable if you want to create BAM reports on this<br />
data. You also have to choose the activities in which to collect this data. Even though it is technically<br />
feasible to monitor every attribute of every SDT and package, do not do that. It is a best practice to<br />
understand thoroughly your reporting requirements. For reports based on SDT/package attributes,<br />
you must precisely identify which attributes to monitor and the location in the process this monitoring<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 31
Creating the Data Model<br />
should occur. You also have to choose the activities in which to collect this data. Consider the<br />
following when determining which SDT and package attributes to monitor:<br />
1. If an attribute’s value does not change from one activity to another, then only monitor the attribute<br />
once rather than for each step in the process. If you monitor this attribute in several locations,<br />
then you are capturing meaningless rows of data that are needlessly filling up the audit trail and<br />
BAM database.<br />
2. Do not collect process data unless you absolutely must and if you need process data only once, you<br />
may want to collect it at the end of the process.<br />
3. If attribute values change during a process and you want to monitor this change, then select to<br />
monitor the attributes within the activities that generate the change. However, reports that rely on<br />
business data aggregation may be inaccurate. For example, if the order is entered for three widgets<br />
in Activity A but is later changed to nine widgets in Activity B, then the correct number is nine.<br />
But if you record both numbers, then you will compute six as an average value, which is incorrect.<br />
32 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 5<br />
<strong>Designing</strong> the Process<br />
This chapter discusses the following:<br />
• <strong>Designing</strong> the process overview<br />
• <strong>Designing</strong> activities<br />
• <strong>Designing</strong> <strong>processes</strong><br />
• Using the data mapper<br />
• Looping<br />
• Waiting for invoked process instances to complete<br />
• Inter-process communication<br />
• Using the process debugger<br />
• Process design and Business Activity Monitor (BAM)<br />
• Process design and performance<br />
• Deployment considerations<br />
• Accessing structured data types from a custom application<br />
<strong>Designing</strong> the process overview<br />
Process Builder is the tool used to design and implement the process. It enables you to create the<br />
process by dragging and dropping activity templates. See the Process Builder User Guide for details<br />
on product features and functions. This chapter describes several best practices for designing the<br />
process by using Process Builder.<br />
<strong>Designing</strong> activities<br />
Consider the following when designing activities:<br />
• Defining activity triggers, page 34<br />
• Creating wait activities, page 34<br />
• Sending tasks to a temporary set of users, page 34<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 33
<strong>Designing</strong> the Process<br />
Defining activity triggers<br />
One of the most common mistakes when building a business process is to not define activity triggers<br />
correctly. This means that the tasks in an activity may never be triggered.<br />
When you define or change the flow of a process, it is a common mistake to leave an activity with the<br />
default trigger setting of all input flows are selected. Always check that the Trigger tab of each activity<br />
has been defined with the correct number of incoming activities before you install and run the process.<br />
Creating wait activities<br />
When a process must wait for a response, you can create an activity that pauses the process until the<br />
response is received. To pause the process, create an activity that sends a task to an inbox that belongs<br />
to a placeholder user such as dm_bps_inbound_user. Next, configure the post-timer to expire after<br />
the time you need the process to wait, and have the activity complete the task automatically after the<br />
post-timer expires. The process resumes after the system completes the activity.<br />
To create a wait for activity:<br />
1. Add a manual activity to the process.<br />
2. Define dm_bps_inbound_user as the performer for the activity.<br />
The system sends the task to the inbox of dm_bps_inbound_user rather than an actual user’s inbox.<br />
3. In the Timer tab of the activity, define a post-timer to be triggered after the period of time that<br />
you need the process to wait.<br />
4. Configure the action of the post-timer to complete the workitem after the post-timer expires.<br />
The system creates the task, sends it to the nonexistent user, but it is not completed until the<br />
post-timer expires, thus causing the process to wait for a specified time.<br />
Sending tasks to a temporary set of users<br />
In case management applications, it is common to have a requirement in which you need to set up<br />
a temporary set of users that need to perform a task. Within this temporary set of users, you would<br />
specify one of the following options for performing the task:<br />
1. Set a single user from the temporary group to perform the task. In this case, after the first user<br />
selects this task, it disappears from everyone else’s task list.<br />
2. Set all users from the temporary group to perform the task. In this case, everyone must perform the<br />
task.<br />
To do this, create three sequential activities:<br />
1. Activity A: You need an automated activity to create the ad hoc group. This requires writing some<br />
custom Documentum Foundation Class (DFC) code. Your code should also add a set of users to<br />
the group. Store the name of the group in a process variable.<br />
2. Activity B: This activity takes the group name from the process variable and assigns the tasks. In<br />
this activity you specify whether a single user from a group or all users from the group perform the<br />
task.<br />
34 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
3. Activity C: This activity performs the cleanup. It deletes the temporary group that you just created.<br />
If you do not delete the temporary group, performance may suffer.<br />
<strong>Designing</strong> <strong>processes</strong><br />
Consider the following when designing the process:<br />
• Creating complex conditional routing with a decision split, page 35<br />
• Using sub-<strong>processes</strong>, page 36<br />
• Understanding message correlation, page 36<br />
Creating complex conditional routing with a decision<br />
split<br />
This section describes how to configure a complex type of routing, one that you can consider three<br />
different routing options based on criteria. An example of a less complex decision split is if you have a<br />
document that must be reviewed by a Vice President (VP). If it is a marketing document, then the VP<br />
of Marketing must review and approve it. If it is an engineering document, then the VP of Engineering<br />
must review and approve it. In this example, the process diagram looks like this:<br />
However, you may have a requirement that is more complex. Similar to the previous example, you<br />
may want the VP of Marketing to review marketing documents or the VP of Engineering to review<br />
engineering documents, but what do you do with a document that is neither marketing or engineering<br />
In this example, a document that does not fall into one of those two categories must be reviewed and<br />
approved by both VPs. This means that there are cases where only one task is triggered (going to one<br />
of the VPs), whereas in other cases both tasks are triggered (going to both of the VPs).<br />
To model this complex routing, you need to add a Join activity. Even though it is common to create<br />
a Join after a decision split, this example uses the Join to consider the two out of three case. In this<br />
example, the process diagram looks like this:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 35
<strong>Designing</strong> the Process<br />
The transition conditions are expressed as:<br />
The use of Join in the first two conditions ensures that each option leads to two activities being<br />
selected. The trigger option at the Join activity looks like this:<br />
Using sub-<strong>processes</strong><br />
Process Builder enables you to create in-line sub-<strong>processes</strong>. Using sub-<strong>processes</strong> can improve your<br />
ability to communicate the structure and the business meaning of a process template. A large or<br />
complicated process can become difficult to organize visually when there are many activities required<br />
to complete an entire workflow. To simplify the layout of a process, group related activities into<br />
sub-<strong>processes</strong> that collectively represent a business process.<br />
In Process Builder, sub-<strong>processes</strong> can be expanded to view the individual activities or collapsed to<br />
create a more simplified overview of a process. The process contains activities that are related in some<br />
way and are grouped into a container for ease of administration. This can be useful when grouping a<br />
set of activities that collectively represents a business function or a logical step in a process. Activities<br />
that share the same process data can also be grouped into a sub-process.<br />
It is also possible for one process to invoke another process. In this case the invoking process is called<br />
the parent and the invoked process is called the child. If you want to build a process that invokes one<br />
or more child <strong>processes</strong>, use the Invoke Process activity template. If you need the child process to post<br />
events to the parent process, then use the Post Event to Parent Process.<br />
Understanding message correlation<br />
The basic idea of correlation is simple. Processes can send messages and receive messages from<br />
external systems and services. A process instance can, for example, send a Java Message Service<br />
(JMS) message (request) to an external system. This message is sent to the external system by the<br />
Process Integrator. After sending the request message, the process instance enters a wait state. When<br />
the external system completes the request, it sends its response message back to the Process Integrator.<br />
However, there can be many process instances in flight at the same time, each waiting for a response<br />
to its own request. Therefore, it is necessary to match the response to the correct requesting process<br />
36 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
instance. To make this match, the request message has to include some data that uniquely identifies the<br />
requesting process instance. This is called the correlation identifier. The response message coming<br />
from the service also contains the same correlation identifier, so that when the Process Integrator<br />
receives the incoming message, it reads the correlation identifier and then routes the message to the<br />
right process instance.<br />
There are two basic approaches to specify a correlation identifier:<br />
• Transport-based<br />
• Content-based<br />
In the transport-based approach, the identifier is created as part of the protocol control field. For<br />
example, a Java Message Service (JMS) message can generate a unique key that can be used to<br />
identify the process instance.<br />
In the content-based approach, the identifier is taken from the payload. For example, in a purchase<br />
order application, the purchase order number is unique to each process instance. Therefore, it can be<br />
used to match the response to the requesting process instance. In some situations you need to combine<br />
multiple data fields to ensure uniqueness.<br />
If a correlation identifier has not been configured for an activity or if it is missing from the incoming<br />
message, the system looks for a correlation set to match the message to a workflow. Correlation<br />
sets are specified at the process level in the Advanced tab of the Process Properties. They are used<br />
to enable correlation in the activities of that process. You can use one or more process variables to<br />
create a correlation set to uniquely identify the process instance.<br />
Use the data mapper’s copy function to compare one of the attributes of your incoming data to the<br />
value of one of your process variables belonging to a correlation set.<br />
Note: The copy function is used to compare these values. If there is a match between the value of<br />
the process variable (belonging to a correlation set) and the value of a data attribute of the incoming<br />
message, the match is successful and the step activity is completed.<br />
Using the data mapper<br />
The data mapper is a graphical tool that simplifies the exchange of process data, such as workflow<br />
method arguments, web services parameters, return values from database queries, and attributes<br />
specific to services such as JMS, HTTP, or FTP. This section addresses several topics involving the use<br />
of the data mapper that can arise in your projects.<br />
Mapping repeating attributes<br />
There are times that you need to copy a source variable to multiple target variables. This can be done<br />
using the data mapper. You can also perform operations in the course of the mapping, for example,<br />
mapping a date to a date and also mapping the date to a string variable (using the date-to-string<br />
function) at the same time.<br />
To copy one variable to many variables:<br />
1. Create the copy function as usual for the first item.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 37
<strong>Designing</strong> the Process<br />
2. Add a second copy function and click the destination variable.<br />
3. Click the Line drawing mode button in the toolbar.<br />
4. Place the cursor over the small handle in the source variable and click once.<br />
5. Click the handle on the left side of the copy function to complete the mapping.<br />
As you can see, Var 0 on the left, has been mapped to Var 0 and to Var 1 on the right.<br />
Setting the context for repeating attributes<br />
A multi-valued attribute can be mapped to a single-valued attribute or to another multi-valued attribute.<br />
Depending on how you set the Input Context option, the mapping rule function is executed once<br />
for each input value (the for-each case) or the mapping rule function is executed against the array<br />
of attributes as a whole (the for-all case). You can view or update the Input Context option in the<br />
function dialog box.<br />
The following example clarifies this feature. In this example, on the input side (left-hand side) of the<br />
mapping you have a repeating attribute IntArray, of type Int, with values [1, 2, 3, 4, 5]. The mapping<br />
rule function is Add(IntArray, 1).<br />
Case 1: (for-each). This performs the Add function for each individual value in IntArray, creating<br />
a multi-valued attribute on the right-hand side. In this case the output on the right-hand side will<br />
be [2, 3, 4, 5, 6].<br />
Case 2: (for-all). This performs the Add function against IntArray as an argument, creating a<br />
single-valued output. In this case the output on the right-hand side will be 16 = (1+2+3+4+5) + 1.<br />
Here is an example to show the use of the for-each construction. In this example, you have a process<br />
receiving emails with attachments but do not know the content type of the attachments. You just have<br />
the attachment name, but you need to know the content type in order to store it in the repository. To<br />
solve this problem, look at the file extension of each attachment and use it to set the object type. To<br />
do this you iterate through the file names, getting the file name and the extension. The for-each<br />
38 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
construct allows you to implement this loop. The split construct allows you to extract the file extension<br />
for each attachment.<br />
Here are the detailed steps of the implementation:<br />
1. Select Split function in the Data mapper.<br />
2. Double-click the Split function icon that shows up, and select the For Each radio button.<br />
3. Map Email → Attachment → Name to Attachment → Content → file-extension.<br />
The Activity Inspector screen appears as:<br />
4. Double-click the Split function that is connecting the left-hand side to the right-hand side.<br />
5. Click the plus sign (+) and add a period (.).<br />
6. Click the plus sign (+) and add 1.<br />
7. Use the up/down arrows to reorder them as follows:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 39
<strong>Designing</strong> the Process<br />
The end result is:<br />
40 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
In general, you can use this approach whenever you are working with repeating elements and you<br />
wish to take action for each one of the elements.<br />
Adding multi-valued attributes<br />
When you are mapping repeating nodes, you want to retrieve all the values of the repeating node from<br />
the left-hand side and then insert these values in the proper position on the right-hand side. To achieve<br />
this, multi-valued attributes have an Add link next to their names. Use the Add link to create a node<br />
that represents a specific index of multi-valued attributes.<br />
To add a node with a new index value:<br />
1. Click Add next to the attribute for which you want the system to create a node with a default<br />
index value.<br />
2. Double-click the new index value to launch the Repeating Index dialog box.<br />
3. To change the index value, select FIRST, LAST, or type a numeric value for the index position.<br />
FIRST creates the first index position for the attribute. This is generally more useful on the<br />
Input Message Mapping side when mapping the first value of an attribute to another attribute on<br />
the Output Message Mapping side.<br />
LAST creates the attribute at the end of any other existing attributes. The input values are appended<br />
after any other values. This ensures that mapped data does not overwrite any existing value.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 41
<strong>Designing</strong> the Process<br />
To copy all values of a multi-valued attribute to a specific index of multi-valued indexes:<br />
1. In the target tree, create a node representing the specific index of the multi-valued attribute.<br />
2. Select the node representing all values (the index value for this node is ALL) in the source tree.<br />
3. Select the node representing the single-attribute node in the source tree.<br />
4. Launch the function dialog box by double-clicking on the function.<br />
5. In the function dialog box, select FOR-EACH as the value for Input Context, and select<br />
Over-Write, Insert Before, or Insert After as the value of Output Context.<br />
When using the Insert After or Insert Before options, the values are inserted after or before the<br />
index. When using the Overwrite option, the existing values are overwritten.<br />
XML and other data formats<br />
Since Extensible Markup language (XML) is the standard used to exchange structured data between<br />
applications, the activity templates shipped with Process Builder support XML natively. Process<br />
designers can associate an XML schema with a service-specific message and use the data mapper to<br />
create an XML payload that can be sent to other applications. However, if the target application<br />
uses another data format (like Comma Separated Value (CSV)), then associate a translator with the<br />
message. At runtime, the Process Integrator uses a translator, if specified in data mapper, to convert the<br />
XML document into the desired format. A translator is a custom Business Object Framework (BOF)<br />
module that you write, for example, to convert a Comma Separated Variable (CSV) file to an XML<br />
document. This is a standard feature of the data mapper.<br />
Setting custom object types for attachments<br />
In some applications, executing <strong>processes</strong> must receive email with attachments. The default object<br />
type for an attachment is dm_document. However, you can also treat it as a custom object type by<br />
using the data mapper for the Email Inbound activity template. In the data mapper, set the ObjectType<br />
attribute in the Attachments node of the process data to any type that is valid for your repository.<br />
Looping<br />
Many applications must perform a series of activities several times in succession. Process Builder<br />
enables you to define loops by using a counter mechanism. The following process shows how to set up<br />
looping within a process. In the first activity, a human performer specifies a set of departments. Then,<br />
an automated loop cycles through each department, invoking a process for each department.<br />
42 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
To create a simple loop:<br />
1. Create a manual activity called Define Departments in which the user defines the departments<br />
for which a new process is started.<br />
2. Create a Process Data Mapping activity called Setup Loop.<br />
This activity gets the number of departments defined in the manual activity and assigns that<br />
number to a counter.<br />
3. Use another data mapping activity to decrement the CurrentCount by 1.<br />
Use a Subtract function to subtract 1 from CurrentCount and map it back to the same variable. It is<br />
valid to map the variable back to itself to get: CurrentCount = CurrentCount -1. This is necessary<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 43
<strong>Designing</strong> the Process<br />
because the index of a multi-valued attribute starts at zero, so if you have three values, the index<br />
must decrement from 2 to 0, rather than 3 to 1.<br />
4. Add an automatic activity as a decremental decision transition to begin the loop.<br />
The activity executes a no (Begin Loop) operation (dm_noop_auto_method). The trigger is<br />
configured to create a task when either of the two inputs is followed. Configure it to trigger<br />
for 1 out of 2 possible input flows.<br />
5. Next, include an Invoke Process activity template to map the data into the child process.<br />
In the data mapper, use the Get Value function to set the value of the process variable department<br />
on the new process instance.<br />
6. Create a decision split activity called End Loop. In this activity, there is a transition condition that<br />
returns to the loop if the counter is greater than zero. If the counter is zero, then it will exit. The<br />
Cleanup activity (also a no op) is needed to connect to the end of the process.<br />
44 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
Waiting for invoked process instances to<br />
complete<br />
In the looping example in the previous section, the Invoke Process activity started the child <strong>processes</strong><br />
asynchronously. The child <strong>processes</strong> can continue to execute even after the main process has finished.<br />
However, you can apply logic to force the main process to wait until all the child process instances in<br />
the loop complete. To illustrate this, create two activities: Wait and Count Children.<br />
To add and configure a wait condition:<br />
1. Create an activity named Wait.<br />
2. In Process Builder, configure the performer for the Wait activity to dm_bps_inbound_user to<br />
prevent a human user from picking up the task to do.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 45
<strong>Designing</strong> the Process<br />
3. On the Timers tab, set a timeout interval for the Wait step.<br />
In our example, we set the post timer to expire one minute after the task is created. (This is the<br />
polling interval. We assume that the child <strong>processes</strong> are short and will complete within one minute.)<br />
When the timer expires, the task will complete.<br />
4. On the Trigger tab, set the trigger condition of the Wait activity to 1 out of 2 possible input flows,<br />
since it can be triggered in two mutually exclusive ways.<br />
46 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
After the timer expires and the task is completed, the process proceeds to the Count Children activity.<br />
To add and configure the Count Children activity:<br />
1. Add a Database Query Language (DQL) Read activity named Count Children.<br />
The Count Children activity queries the number of child process instances invoked by the parent<br />
process instance.<br />
2. On the DQL Configuration tab, set up the Count Children activity to query the number of child<br />
process instances invoked by the parent process instance.<br />
The following illustrates the configuration:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 47
<strong>Designing</strong> the Process<br />
48 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
3. On the Transition tab, configure which activity is next in the process and what the conditions are.<br />
The following screenshot illustrates using a count function to count the number of r_object_ids<br />
returned from the query, and we assign this number to the process variable runningChildrenCount.<br />
When runningChildrenCount is equal to zero, the process proceeds to the Cleanup activity. When<br />
runningChildrenCount is greater than zero, then there are still running instances of the child process<br />
and the process returns to the Wait activity.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 49
<strong>Designing</strong> the Process<br />
Inter-process communication<br />
Process Builder includes an Invoke Process activity template that enables a parent process to invoke a<br />
child process. An example of this is if you have an order process that must perform a credit check.<br />
Instead of building the credit check procedure into the order process, create it as a separate process to<br />
be invoked as a child process. You can manage the credit check process separately and independently,<br />
and it can be called by other parent <strong>processes</strong>.<br />
The Invoke Process activity template provides a basic mechanism to pass process data from the parent<br />
process to the child process. By using the Post Event to Parent activity template, the child process<br />
communicates to the parent process by posting events to the parent process instance. However, the<br />
posted event is only a name that carries no payload to the parent. To pass a data payload from the<br />
child to the parent, use the following approach:<br />
In this example, the parent process invokes the child process in the third activity:<br />
50 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
The Invoke Process activity passes a workflow correlation identifier to the child. The child process<br />
needs this identifier to call the correct parent process instance. Map the correlation identifier of the<br />
parent to the variable parentInstanceCorrId of the child, as illustrated:<br />
After invoking the child process, the parent process instance waits for a response message with the<br />
payload from the child in the HTTP Inbound - Step activity. The following shows the configuration<br />
for the HTTP Inbound - Step activity:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 51
<strong>Designing</strong> the Process<br />
In the HTTP Inbound - Step activity, the parent sets the Correlation Property Name to CorrId. When<br />
the child process instance posts an HTTP request, the system looks for a workflow instance with a<br />
correlation identifier that matches CorrId in the URL Parameter of the request.<br />
When configuring the HTTP Inbound - Step activity, select With Attachments. The attachment carries<br />
the payload from the child process to the parent process.<br />
To enable the payload to pass from the child process to the parent process, map the HTTP attachment<br />
data posted by the child to the attachment data field of the parent, as illustrated:<br />
52 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
Next, look at the child process:<br />
After the parent process invokes the child process, the child process carries out the request of the<br />
parent. The child process then posts a response message back to the parent instance in the HTTP<br />
Outbound activity. The parent process instance waits for the message with the payload from the child<br />
and receives it in the HTTP Inbound - Step activity.<br />
Configure the HTTP Outbound activity as illustrated:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 53
<strong>Designing</strong> the Process<br />
For the child process instance to post the message to the correct parent process instance, it uses the<br />
parentInstanceCorrId. The child process receives this identifier from the parent process when the<br />
parent invoked the child. This variable is mapped to the URL parameter CorrId as illustrated:<br />
54 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
Attachments pass from the child process instance to the parent process instance by mapping them to<br />
the HTTP Request attachments.<br />
This approach was based on HTTP Post. An alternate approach is to use JMS as the protocol for<br />
inter-process communications. This approach is useful when the child process must pass data to the<br />
parent process.<br />
Using the process debugger<br />
Process Builder’s debugger enables you to test the design of a process template interactively by setting<br />
breakpoints, running through the process, examining and modifying process data, testing integrations,<br />
and acquiring and acting upon tasks within a process.<br />
Debugging a process before deploying it to a production environment helps to ensure that the process<br />
flow you designed satisfies the original business requirements upon which you based your design.<br />
Using the debugger to troubleshoot a process enables you to test a process from within the process<br />
design environment without having to save, validate, or install the process. You can also test activities<br />
as you develop them to ensure that you have configured a complex process flow correctly. Executing a<br />
particular path within a flow can also give you important feedback during the development process.<br />
You can use the debugger to walk through the invocation of a web service. You can visually inspect<br />
the outgoing message, the returned response from the web service, the document metadata and process<br />
variable values. Errors display immediately in the debugger console. Make sure to place a breakpoint<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 55
<strong>Designing</strong> the Process<br />
at or right after the service invocation step. As a recommended best practice, as you build up your<br />
<strong>processes</strong>, particularly with web services integration activities, regularly test them with the debugger.<br />
Use the debugger every time you change the process to ensure the integrity of data that may have<br />
changed.<br />
Debugging custom methods with the process<br />
debugger<br />
If you are using custom methods in your workflows, you can debug them using the process debugger.<br />
To debug a custom method:<br />
1. Launch Process Builder in debug mode.<br />
2. Modify the shortcut to add debug options and enable debugging using the specified port.<br />
For example:<br />
-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n<br />
The complete shortcut may look similar to the following:<br />
C:\Program Files\Documentum\jreForPB\bin\java.exe"<br />
-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n<br />
-Xms128m -Xmx256m -Dswing.aatext=true -cp ".;lib\bpm.jar;..\..\dctm.jar;<br />
C:\Documentum\config" WorkflowEditor -locale en_US<br />
3. In your integrated development environment (IDE), add a new debug configuration to connect<br />
the host and port.<br />
56 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
4. Place breakpoints in your code, run this debug configuration from your IDE, and begin debugging<br />
your process from Process Builder.<br />
Whenever an activity that uses your custom method is reached, you can debug through your<br />
custom method code.<br />
Note: To make the method code available to the process debugger, it must be a Class that is<br />
located in the appropriate directory structure or a JAR file located under \classes\custom folder in<br />
the Process Builder installation directory.<br />
Process design and Business Activity Monitor<br />
(BAM)<br />
BAM extracts information from executing <strong>processes</strong>, runs reports against this information, and<br />
provides a dashboard for viewing the reports. Plan to specify the monitoring configuration as you<br />
design your process in Process Builder. If you plan on using BAM, you must plan for:<br />
• Enabling reporting for BAM, page 58<br />
• Reporting on data in an external database to BAM, page 59<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 57
<strong>Designing</strong> the Process<br />
Enabling reporting for BAM<br />
In Process Builder you specify the process execution data to be recorded in BAM, so that report<br />
designers can create BAM reports based on this data.<br />
Activating the Audit Trail<br />
You must activate the audit trail for each process that you want BAM to monitor. Activating the audit<br />
trail enables the BAM server to extract the reporting data and insert it into the BAM database.<br />
In the Process Template Properties dialog box, select the General tab. In the Audit Trail Settings<br />
group box, select the On option.<br />
When auditing is on, audit trail information is saved for each workflow instance created from this<br />
template.<br />
Note: To change audit trail settings, you must have CONFIG_AUDIT privileges. CONFIG_AUDIT<br />
is an extended user privilege and must be granted by another repository owner or superuser using<br />
Documentum TaskSpace or Documentum Webtop. The Documentum Webtop User Guide and the<br />
Documentum TaskSpace Configuration Guide provide more details on extending user privileges.<br />
Enabling monitoring of structured data types<br />
You must specify the activities in which you want to record process data to BAM. It is not necessary<br />
(or desirable) to do this for every activity. Select the SDT attributes to include in reporting from<br />
each activity.<br />
Use the Add Structured Data Type Wizard to create structured data types. To record a data attribute in<br />
the BAM database, select the Reportable checkbox in the wizard. Make sure to update the data type<br />
definitions with BAM by selecting Update BAM Database tables based on this SDT definition.<br />
This procedure creates the tables in the BAM database, which are used to report on business data.<br />
Examples of such reports include total weekly revenue per branch office, average duration of claim<br />
resolution by type, and number of new grants applications by state.<br />
Selecting packages for reporting<br />
Report data can come from packages as well as from SDTs. Select the packages to include in reporting<br />
at the process level or in the individual activity. To enable Process Builder to publish reporting data<br />
to the BAM database for the package, select This package can be used to generate reports in the<br />
Process Properties dialog box or in the Data tab of the Activity Inspector. When you do this, all the<br />
custom attributes of the object are available to the BAM database. Unlike the case with SDTs, you<br />
cannot select individual attributes for reporting.<br />
You must specify the activities in which you want to record process data to BAM. It is not necessary (or<br />
desirable) to do this for every activity. Select the packages to include in reporting from each activity.<br />
Selecting process variables for reporting<br />
You must specify the activities in which you want to record process data to BAM. It is not necessary (or<br />
desirable) to do this for every activity. Select the variables to include in reporting from each activity.<br />
58 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
Process variables can be simple types (Boolean or string) or can be structured data types that were<br />
selected for reporting when they were created. To expose this variable and use it to generate reports,<br />
select the This variable can be used to generate reports checkbox in the Data tab of the activity.<br />
Synchronizing with the BAM database<br />
If you change the process data in a process, there is the danger that these changes are not reflected in<br />
the BAM database structure. Ensure that any changes to the business data that you are monitoring have<br />
been updated in the BAM database. The Update BAM Data Definitions page enables you to update<br />
selected process data from Process Builder with the existing reporting data in the BAM database. This<br />
ensures that there is consistency between the structure of the data in Process Builder and the structure<br />
in BAM. This option updates the BAM process data with the process data that you select in the<br />
Update BAM Data Definitions page.<br />
Select Tools > Update BAM Data Definitions to use the Update BAM Data Definitions page.<br />
Reporting on data in an external database to BAM<br />
BAM reports on information in <strong>processes</strong> automated by the Process Engine. A common question is<br />
how to report on data that is contained in an external database. The best way to do this is to create a<br />
small process that makes this data available to BAM. You can configure a Database Read activity to<br />
retrieve data from the database outside of Documentum and then mark the data elements for reporting.<br />
This creates a simple process with one automatic activity that retrieves the specified data and sends<br />
reporting information to BAM.<br />
Note: Because Process Builder does not support a process with a single activity, you must add one<br />
more dummy activity to the process. That activity is an automated activity in which the method<br />
is dm_noop_auto_method.<br />
Process design and performance<br />
This section describes some practices that could improve performance.<br />
Choose one automatic performer<br />
To improve the performance of automatic activities in your process, make one user (or a small set<br />
of users) the performer of all the automatic activities. For example, if you define a user, such as<br />
auto_executor, and make that user the performer of all the automatic activities, the runtime execution<br />
of these automatic activities increases considerably.<br />
For security reasons, only a superuser can select a specific user as a performer for an automatic<br />
activity in Process Builder.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 59
<strong>Designing</strong> the Process<br />
Performance and stability of executing automated<br />
workflow activities<br />
The Process Engine’s multi-threaded workflow allows concurrent execution of automated workflow<br />
activities. The workflow agent responds to Content Server notifications and can execute queries based<br />
on a polling interval to claim work for its worker threads to execute.<br />
There are only two ways the workflow worker threads can execute the work:<br />
• Notification: They get notified through shared memory inter-process communication (IPC).<br />
• Claim query: The workflow master runs the UPDATE query that claims available items for<br />
working and then distributes the work to workers.<br />
If the automated workflow activities are not executing on time or never at all, check for the following:<br />
• The claim query can take too long to execute.<br />
This can occur when the number of worker threads is increased to a high number (for example, 100)<br />
with the intent that more workers results in better performance. However, with this increase, the<br />
UPDATE query executes as a nested loop in the underlying RDBMS, pinning the RDBMS CPU.<br />
This dramatically increases the time that it takes to execute the claim query. Check the statspack for<br />
top queries and if the UPDATE on dmi_workitem_s is taking a long time, then it is a confirmation<br />
of the problem.<br />
• Content Server is configured for high availability.<br />
With a Content Server high availability configuration, confirm that a unique dm_server_config<br />
object is specified for each content server. If you have two workflow masters operating using the<br />
same serverconfig object, then workflow automated activities execution can fail. To fix this problem,<br />
ensure that each content server has a unique serverconfig object.<br />
• You are not using the no_op method from Process Builder 6.5 or later.<br />
In Process Builder 6.5, the default DocBasic no_op method to run the automated activities<br />
such as splits, joins, and data mappers was changed. If you are using an older version of<br />
dm_noop_auto_method, switch to the newer version of dm_noop_auto_method_java.<br />
Large SDTs and performance<br />
Creating large SDTs or adding many SDTs to a process degrades performance in TaskSpace task<br />
lists. Try to create SDTs based on logically related objects and consolidate attributes if it makes<br />
sense within the process.<br />
Deployment considerations<br />
• Migrating or upgrading Process Builder, page 61<br />
• Process versioning, page 61<br />
60 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
<strong>Designing</strong> the Process<br />
Migrating or upgrading Process Builder<br />
After upgrading to a newer version of Documentum Process Builder, delete the BOF cache as<br />
well as the temp/work directory of the application server, and restart the application server. The<br />
cache folder location is specified by the dfc.cache.dir key in the dfc.properties file. It is located in<br />
$DOCUMENTUM/cache/bof on the client machine by default. Clearing the bof<br />
folder contents clears the BOF cache.<br />
Note: The DFC cache folder also contains caches other than BOF. Do not delete these additional<br />
cache folders.<br />
Process versioning<br />
Use versioning carefully and sparingly to avoid creating inconsistencies in the process data. It is best<br />
to create versions when deploying a process to the production environment. This is because creating<br />
different versions of a process can result in process data getting out of sync. Use versioning carefully<br />
and only when the process is moved to a production environment.<br />
During design, it is a best practice to use the process debugger frequently to troubleshoot and validate<br />
the process without installing it. When the activities and the data model are defined and the debugger<br />
is run without errors, then check the process into the repository. Install the process only when you<br />
want to run it.<br />
Note: It is not recommended to use Save As on a process multiple times and then install each of the<br />
cloned <strong>processes</strong>. This practice can lead to instabilities at runtime.<br />
Accessing structured data types from a custom<br />
application<br />
To gain access to the attributes of structured data types, you can use IDfWorkitemEx<br />
and IDfWorkflowEx APIs. Details can be found in the Javadoc files located in Program<br />
Files\Documentum\help\bpm\api.<br />
Note: During the installation process, ensure you have selected the option to install the developer<br />
documentation. This option installs the Javadocs on your local system.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 61
<strong>Designing</strong> the Process<br />
62 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 6<br />
Creating the User Interface<br />
This chapter discusses the following:<br />
• Creating form templates in Forms Builder<br />
• Implementing TaskSpace applications<br />
Creating form templates in Forms Builder<br />
The form templates in Forms Builder are the basis for the user interface (UI) in TaskSpace and require<br />
careful consideration.<br />
This section provides general tips and information on the following:<br />
• How to create a well-designed user interface<br />
• Options to start a process from a template<br />
• Options for what appears when a process starts<br />
• Options to design a task view<br />
• Process and task template versioning<br />
• Custom error messages<br />
• How to use data adaptors<br />
• Performance considerations<br />
General tips for user interface design<br />
• Consider creating a style guide for the user interface, in collaboration with the client.<br />
• Prepare a detailed design document and confer with the client to resolve all issues ahead of<br />
time. Preparing a detailed design document in advance makes creating the form templates a<br />
straightforward process.<br />
• <strong>Designing</strong> forms requires increased interaction with the client. The clients are the ones who will<br />
be using the forms, so let them see the forms often during the design phase and solicit as much<br />
input as possible.<br />
• The UI must be as intuitive as possible, with a common look and feel across all form templates.<br />
• Make a prototype and get it fully functional to help ensure that the UI design is as user-friendly as<br />
possible and that the client approves of the design before doing the actual development. Keep in<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 63
Creating the User Interface<br />
mind that the size and complexity of the prototype is not necessarily indicative of the development<br />
effort. The development time will be greater due to coding complexity and customization. You also<br />
cannot necessarily predict performance issues from the prototype.<br />
• Consider how many task templates you need. You may want to make one template for each step or<br />
activity in the process, and they should all have a common look. This also improves performance.<br />
• When initially designing templates, keep in mind that it can sometimes be easier and quicker to<br />
delete a template and start over again.<br />
• Sometimes what the client wants is not a good design. For example, even though you can search on<br />
20 attributes does not mean that you should.<br />
• Try to design forms so there is no scrolling for the end user. This may mean using more tabs in<br />
TaskSpace.<br />
• After creating a template with the template wizard, if you start changing and adding controls and<br />
moving items around on the canvas, especially if you use drag and drop, frequently verify how things<br />
look on the Preview pane. When using drag and drop, items can appear to line up using the vertical<br />
bar, but the spacing and padding appear differently on the Design pane than on the Preview pane or<br />
at runtime. To ensure correct alignment, especially for labels, use the settings on the Style tab.<br />
Multiple ways to start a process<br />
This section describes the different ways in which you can start a process. You can:<br />
• Use the <strong>processes</strong> tab, page 64<br />
• Use a search template, page 64<br />
• Use a configurable action, page 65<br />
• Use a configurable action with an attachment, page 66<br />
When a process starts, there are three possible options: an initiate process form appears, a package<br />
form appears, or a standard WDK component appears (which does not use a form). Options for what<br />
appears when a process starts are described in Options for when a process starts, page 69.<br />
Use the <strong>processes</strong> tab<br />
The most straightforward way to start a process is to go to the Processes tab. You can select one of the<br />
<strong>processes</strong> that are listed there and click Start Process.<br />
Use a search template<br />
You can use a search template that is configured to search on <strong>processes</strong> in a specific folder. This is<br />
useful if you want to filter the list of <strong>processes</strong> that a user sees.<br />
On a search tab in TaskSpace, you select a process from the search results set and then select Start<br />
from the context menu.<br />
64 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
Figure 5<br />
Start a process from a search<br />
Use a configurable action<br />
To make things simpler and avoid selecting from a list of <strong>processes</strong>, you can start a specific process<br />
using a configurable action on a custom tab:<br />
1. Create a configurable action to start a process.<br />
2. Select the specific process to start.<br />
3. Add the action to a custom tab.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 65
Creating the User Interface<br />
Figure 6<br />
Start a process with a configurable action<br />
Use a configurable action with an attachment<br />
If you first receive a document and then want to start a process with the document as an attachment,<br />
you can start a specific process with an attachment using a configurable action:<br />
1. Create a configurable action to start a process with a selected object.<br />
66 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
2. Configure how the object is routed by selecting Dynamic Object Value Selection.<br />
3. Select Objects to be routed.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 67
Creating the User Interface<br />
4. Select the specific process.<br />
68 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
5. Start the process from a search by selecting a document and then clicking the configured action<br />
button. The process starts with the selected document added as an attachment.<br />
Options for when a process starts<br />
When a process starts, there are also options for what appears next. You can show an initiate process<br />
template or you can show an electronic form in a package. A third option, calling a standard WDK<br />
component, does not use a form and is therefore not described here.<br />
Use an initiate process template<br />
The standard option when a process starts is to open an initiate process template. Each template is<br />
associated with a specific process and you can show process variables and use a package control to<br />
allow users to upload or select an existing document to be the package content. You can also further<br />
customize the template by adding additional controls.<br />
Use an electronic form in a package<br />
If you want a specific form as a package in the process, which appears when the process starts, you can<br />
use an electronic form in a package:<br />
1. Create an electronic form and specify it with a Start Activity.<br />
2. Open the Activity Inspector for the Start Activity in Process Builder, specify the electronic form<br />
with a package, and select to automatically launch the package.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 69
Creating the User Interface<br />
Figure 7<br />
Start a process using a form in a package<br />
3. At runtime, when the process starts, the configured electronic form in the package appears<br />
automatically. This is useful if you need to fill out a specific form for the associated process.<br />
4. When the user submits the form, if any of the mandatory packages are not fulfilled, the user is<br />
prompted to fulfill the mandatory packages.<br />
Options to design a task view<br />
The basic way to design a task view is to use the task template creation wizard to create a task view<br />
by selecting a specific process and process variables and by using the default controls. After the<br />
wizard creates the task view, you can then add custom logic, such as adaptors or an invoke button.<br />
With the default task template, users can also view attachments or packages in the TaskSpace preview<br />
pane. You also have additional options.<br />
Display a document package inline<br />
You can display a specific document package inline using the task template with an embedded form<br />
control.<br />
When selecting the data binding for the embedded form, be sure to bind to the valid object path:<br />
/Activity/...//DocumentId (you can also bind to a process variable assuming that<br />
the variable value is an object ID).<br />
70 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
Next, select the appropriate form template to show the package content, which is a document view<br />
template or an electronic form. You can then preview a document and modify document data while<br />
processing the task. It is possible to have multiple embedded forms in one view, but the UI can be<br />
busy when there are multiple packages.<br />
Figure 8<br />
Task template with embedded document view<br />
Display folder package inline<br />
You can display a specific folder package inline using the task template with a folder view control.<br />
Select a folder package for the data binding, then configure how the folder view is displayed. This<br />
option allows you to treat a folder as a case and preview a document while processing a task, but you<br />
must show less information due to space limitations.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 71
Creating the User Interface<br />
Figure 9<br />
Task template with folder view control<br />
Display multiple packages inline<br />
You can display multiple packages inline using the task template with a folder view control and an<br />
attachment list control. This option allows you to accommodate multiple types of packages (documents<br />
and folders) but you are limited by available space. The folder view can display a folder object from<br />
the attachment list. You can use the preview pane to view an object from the folder view or a document<br />
from the attachment list. When viewing a document from the attachment list, the folder view is empty.<br />
Figure 10 Task template with folder view and attachment list controls - folder<br />
information displayed<br />
72 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
Figure 11<br />
Task Template with folder view and attachment list - document displayed<br />
Process and form template version links<br />
When using form templates associated with a process, namely task, initiate process, and process<br />
parameter templates, you must keep the version links between the form template and the associated<br />
process correctly aligned. The recommended practice is to always create a new version of the process<br />
and then create a new version of the template. When you create a new version of one of these<br />
templates without also creating a new version of the process, the old version of the template becomes<br />
orphaned. When a template is orphaned, it cannot be used until it is linked back to a process. In the<br />
following graphic, if you created form template version 1.1 before creating process template 1.1,<br />
then form template 1.0 would become orphaned.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 73
Creating the User Interface<br />
Figure 12<br />
Process and form template version links<br />
When a form template associated with a process is checked out and a new version created, Forms<br />
Builder automatically links the process to the latest version of the template. Conversely, if you delete<br />
the most recent form template version, the associated process automatically points to the previous<br />
version. You also cannot delete a task, initiate process, or process parameter template if the template<br />
and its associated process are both non-current versions. However, if either the process or the<br />
associated form template are the current version, you can delete the form template.<br />
Custom error messages<br />
The custom error message is important to the validation process and requires careful consideration. It<br />
is also an important element of the UI design as it provides useful feedback to the user when entering<br />
data. Error messages are created in Forms Builder by the template designer during template creation<br />
and are entered in the error message field for each control on the Display tab in the Properties pane.<br />
When writing custom error messages, you should give the user-specific information about the correct<br />
value to enter. Telling the user that the value entered is invalid does not provide much guidance. It is<br />
better to phrase the message in a positive manner and provide an example of a valid value to enter.<br />
A good example would be: Enter a valid date using the format MM/DD/YYYY.<br />
Another technique that is helpful to users is to provide default values for controls that use specific<br />
masks, such as dates, social security numbers, and phone numbers, so that the user has an example to<br />
follow before entering a new value.<br />
If a control does not have a custom error message defined in the template and the value entered is not<br />
valid, the system displays a default error message. The default error messages are generic and only<br />
provide guidance as to the data constraints for the control. An example of a default message for an<br />
invalid data type is: Value entered is not valid for the integer data type. An<br />
example of a default message for an invalid value for a specific data constraint is: Enter a valid<br />
value equal to or greater than %%" (where %% = the defined minimum<br />
74 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
value). While these messages may be helpful to the user, they are not as helpful as messages created<br />
specifically for a template, tailored to the data requirement for that template.<br />
Data adaptors<br />
Some general guidelines for using adaptors are:<br />
• Do not use too many different adaptors as it can impede performance. You can use one data source<br />
adapter to populate multiple fields at once by populating off one database table with multiple<br />
columns. This way, the adaptor only runs once.<br />
• Keep adaptors simple and lightweight and keep the execution time of data source adaptors as<br />
short as possible.<br />
• Do not perform high latency calls within data source adaptors, such as long-running queries or slow<br />
web service invocations, as these calls can greatly impede performance of the UI.<br />
• If you plan to use more than one adaptor, concentrate on getting one adaptor to work before<br />
creating another.<br />
• When using a data source adaptor, make sure that the input is required and that the output is<br />
repeating.<br />
• When creating a custom data source adaptor, you have a choice of creating it as a class or<br />
service-based business object (SBO). If you create it as a class first it is much easier to validate and<br />
debug the adaptor. You can then convert the adaptor to an SBO if desired.<br />
The following table provides information on which templates or controls each adapter can be used<br />
with, guidelines for how best to use each type of adaptor, and important limitations.<br />
Table 4<br />
Adaptor Types and Uses<br />
Adaptor Type<br />
Item Initializer<br />
Available Templates<br />
or Controls<br />
Not available on folder<br />
information, process<br />
parameter, or task<br />
templates<br />
Available on these<br />
controls: Text Field,<br />
RichText, Number Field,<br />
Date Field, DateTime<br />
Field, CheckBox,<br />
CheckBox Group,<br />
Radio Button Group,<br />
ListBox, Dropdown<br />
List, Readonly Table,<br />
Bar Codes, Slider,<br />
Embedded Form, and<br />
Filter<br />
Best Uses/Limitations<br />
Use this adaptor if you want a value entered automatically in<br />
a field when the template instance is created.<br />
The out-of-the-box item initializer is configured to enter the<br />
current date/time in a date/time field. To use your own logic,<br />
create a custom initializer.<br />
When using an item initializer for an integer value in a<br />
number field, also specify a default value for the field.<br />
On a document view template, the initialization will only<br />
execute when the document view is used while importing<br />
documents in TaskSpace.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 75
Creating the User Interface<br />
Adaptor Type<br />
Item Validator<br />
Document<br />
Validator<br />
Data Source<br />
Available Templates<br />
or Controls<br />
Not available on high<br />
fidelity templates<br />
Available on these<br />
controls: Text Field,<br />
RichText, Number Field,<br />
Date Field, DateTime<br />
Field, CheckBox,<br />
CheckBox Group,<br />
Radio Button Group,<br />
ListBox, Dropdown<br />
List, Comment history,<br />
Readonly Table, Slider,<br />
Embedded Form, and<br />
Filter<br />
Not available on high<br />
fidelity templates<br />
Not available on high<br />
fidelity templates<br />
Available on selection<br />
controls only:<br />
CheckBox Group,<br />
ListBox, Dropdown<br />
List, and Readonly<br />
Table<br />
Best Uses/Limitations<br />
Use this adaptor if you want to validate a user’s input values<br />
on individual fields. An item validator applies to one field<br />
and occurs when the user submits the template.<br />
For example, if a data item is an email address, the item<br />
validator could check that it contains exactly one @, at least<br />
one dot after the @, and a recognized domain after the final<br />
dot.<br />
If an error occurs, an error indicator appears next to the<br />
control and the full error message appears at the bottom<br />
of the template. You can create custom error messages<br />
(recommended), or if there is no custom message a default<br />
error message appears. However, if there is a hidden field<br />
on the form that is also marked as required (this should be<br />
avoided), the error message still appears at the bottom. You<br />
can create a custom error message in a validator adaptor by<br />
throwing an exception in the validator adaptor code.<br />
The out-of-the-box validator adaptor validates string inputs<br />
(from user) against the current repository by searching for<br />
them in the list returned by a DQL query.<br />
To perform other validation operations you create a custom<br />
validator adaptor.<br />
Use this adaptor to validate an entire form template.<br />
Validation against a custom document validator and required<br />
fields occurs when the user submits the template.<br />
Error messages display at the bottom of the form. You can<br />
create custom error messages (recommended), or if there are<br />
no custom messages then default error messages appear. You<br />
can create a custom error message in a validator adaptor by<br />
throwing an exception in the validator adaptor code.<br />
Use this adaptor to access information from an external data<br />
source and then populate one or more selection controls on<br />
the template. The data source can be either a properties file,<br />
the repository, or a data source that responds to the Java<br />
database connectivity (JDBC) protocol.<br />
For example, when the user selects from a dropdown list of<br />
manager names, the dropdown list of employees could be<br />
automatically populated with only the employees who report<br />
to the selected manager.<br />
For data source adaptors, you also have the option of creating<br />
a custom, complex output type. An output type communicates<br />
between the adaptor and the form and defines the structure for<br />
the values returned from the adaptor. The output type creates<br />
a schema that corresponds to columns in the returned data.<br />
This schema can then be used to map the returned values to<br />
one or more fields on the form.<br />
76 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
Adaptor Type<br />
Data Source Set<br />
Value<br />
Document<br />
Processor -<br />
Initialization<br />
Document<br />
Processor -<br />
Pre-submission<br />
Document<br />
Processor -<br />
Post-submission<br />
Available Templates<br />
or Controls<br />
Not available on high<br />
fidelity templates<br />
Available on these<br />
controls: Text Field,<br />
Number Field, Date<br />
Field, DateTime<br />
Field, Radio Button<br />
Group, CheckBox,<br />
ListBox, Dropdown<br />
List, Package, Slider,<br />
and Embedded Form<br />
Not available on folder<br />
information, process<br />
parameter, task, or high<br />
fidelity templates<br />
Not available on folder<br />
contents, process<br />
instance list, search,<br />
task list, or high fidelity<br />
templates<br />
Not available on folder<br />
contents, process<br />
instance list, process<br />
parameter, search, task<br />
list, or high fidelity<br />
templates<br />
Best Uses/Limitations<br />
Use this adaptor to automatically populate one field on the<br />
template. There are two types of Set Value adaptors:<br />
• On Change - populates a field based on a value entered by<br />
the user in another field. For example, when an employee<br />
is selected from a dropdown list, a field for office location<br />
could then be automatically populated for the selected<br />
employee.<br />
• On Init - populates a field when the form renders at runtime.<br />
An initialization adaptor initializes values for the entire form.<br />
On a document view template, the initialization executes only<br />
when the document view is used while importing documents<br />
in TaskSpace.<br />
A pre-submission adaptor executes prior to form submission<br />
provided the validation succeeds, then the form is saved.<br />
A post-submission adaptor executes after a form is submitted.<br />
There are two out-of-the-box document post-submission<br />
adaptors:<br />
• MoveOrLinkToLocationPostProcessor - moves or links a<br />
form instance to a specified location in the repository.<br />
• StartWorkflowPostProcessor - starts a workflow with the<br />
form instance as the initial package.<br />
Using one data source adaptor to populate multiple<br />
fields<br />
If you want to automatically populate multiple fields on a template, creating one data source adaptor<br />
that populates multiple fields greatly improves performance. The following example takes you through<br />
creating two data source adaptors. The first adaptor populates a list box of employee names from the<br />
repository. When a name is selected, the second adaptor then automatically populates ID, E-mail<br />
Address, Phone Number, and Department fields for the selected employee from an external database.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 77
Creating the User Interface<br />
Figure 13<br />
Employee information lookup adaptors<br />
Populating a list box of employee names<br />
The first data source adaptor populates the Name list box with employee names from the repository.<br />
78 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
Figure 14<br />
Data source adaptor for employee names<br />
To create this adaptor:<br />
1. Open the Adaptor Configuration Manager and add a new adaptor with the name<br />
GetAllEmployeeNames.<br />
2. Select Data Source as the adaptor type.<br />
3. Select<br />
com.documentum.xforms.engine.adaptor.datasource.docbase.IDocbaseDataSourceAdaptorService<br />
as the class name and SBO as the type.<br />
4. Enter dql for the initial parameter and enter the appropriate DQL clause.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 79
Creating the User Interface<br />
5. Specify the output type to describe the return value. Note that the columns returned from the DQL<br />
query conform to the items in the output schema.<br />
6. Click OK to save your configuration and close the Adaptor Configuration Manager.<br />
7. On the Design panel, select the Name drop-down list and open the Properties > Data & Storage<br />
tab.<br />
8. In the External Data Source field, select the GetAllEmployeeNames adaptor.<br />
9. Configure the data source output by specifying the Row Selection, which is the repeating element<br />
that is the parent element of the elements you will select in the Value and Display fields (/data/item).<br />
In the Value field, select the element that provides the data value (/data/item/employeeid). In the<br />
Display field, select the element that is what the users will see (/data/item/name).<br />
80 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
You have finished configuring the data source adaptor to populate the Name drop-down list.<br />
Populating employee information fields<br />
The second data source adaptor populates ID, E-mail Address, Phone Number, and Department fields<br />
for the employee selected in the Name field.<br />
Figure 15<br />
Data source adaptor for employee information fields<br />
To create this adaptor:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 81
Creating the User Interface<br />
1. Open the Adaptor Configuration Manager and add a new adaptor with the name<br />
GetEmployeeInformation.<br />
2. Select Data Source as the adaptor type.<br />
3. Select com.documentum.xforms.engine.adaptor.datasource.jdbc.JDBCDataSourceAdaptor as<br />
the class name and Class as the type.<br />
4. Enter sql for the initial parameter and enter the appropriate SQL clause for pulling information<br />
from the data base. In the SQL clause, you specify the parameter with ${} (if<br />
using dql, use single quote, e.g., id=’${id}’).<br />
5. Define the substitute parameter in the Input field. Be sure to select the Required option for the<br />
input field name. The parameter must match the input name.<br />
82 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
6. Specify the output type to describe the return value. Note that the columns returned from the SQL<br />
query conform to the items in the output schema. This should include all the employee information<br />
fields you want to populate.<br />
7. Click OK to save your configuration and close the Adaptor Configuration Manager.<br />
8. On the Design panel, select the ID field and open the Properties > Special tab.<br />
9. Select the option to Execute adaptor after the input value changes. This triggers the adaptor to<br />
fire after selecting an employee in the Name field.<br />
10. In the Data Source field, select the GetEmployeeInformation adaptor.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 83
Creating the User Interface<br />
11. In the input binding id field, select the xpath where the input value is stored (/employee_id). When<br />
you specify an input value, the adaptor returns database table values associated with that input value.<br />
In the Output data field, select the xpath where the ouput is stored (for the ID field, this would be<br />
/data/item/employee_id). This indicates the value in the database table that populates the field.<br />
12. Repeat the configuration on the Special tab for the other fields you want to populate from this<br />
adaptor. The settings are the same for each, except that the output data should match the field being<br />
populated. For example, for the E-mail Address field, you would select /data/item/email_address<br />
in the Output data field.<br />
13. Add the properties file for this JDBC adaptor to the \WEB-INF\classes directory.<br />
The properties file name corresponds to the adaptor name and in this case would be<br />
jdbc_GetEmployeeInformation.properties. The properties file specifies the location of the data<br />
source and standard JDBC configuration parameters, such as login credentials for the data source<br />
and the path to the JDBC driver. The properties file for this adaptor would be similar to:<br />
url=jdbc:mysql://localhost:3306/mysql<br />
driver=com.mysql.jdbc.Driver<br />
user=root<br />
password=forms (or password=pT9oeWTVuFI=)<br />
To encrypt the password, you can use the DFC encryption method:<br />
java com.documentum.fc.tools.RegistryPasswordUtils <br />
You have finished configuring the data source adaptor to populate the employee information fields.<br />
Performance<br />
When working with form templates, the following tips can improve performance:<br />
84 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
• From the beginning of the project through the design, maintain focus on performance. Performance<br />
takes precedence over appearance and special effects.<br />
• Reducing complexity in form templates aids TaskSpace performance: fewer fields and fewer<br />
adaptors.<br />
• On a task list template, keep the search simple as this greatly aids performance.<br />
• When possible, do not enable ACL security for structured data types and process variables when<br />
designing a task list template. It takes longer to load task lists in TaskSpace if process variables<br />
and structured data types have to be evaluated for ACL settings.<br />
• While using multiple task templates for different activities may improve performance, it also<br />
increases maintenance. A better approach may be to use one task template with conditional display<br />
settings.<br />
• Keep everything optimized for the chosen database.<br />
• Data adaptors and rules all affect the length of time it takes to open the form.<br />
• When designing a custom forms template list view, such as a search view, task list, or folder content<br />
form template, include the r_object_type, r_content_size, r_lock_owner, and a_content_type<br />
attributes. If these attributes are not present in the DQL of the forms templates, the system performs<br />
full object fetches for each data row.<br />
Implementing TaskSpace applications<br />
This section contains information that partners and field engineers can use to better implement<br />
TaskSpace applications.<br />
If your planning is well-executed, and you did a good job implementing your process and forms, then<br />
implementing TaskSpace is a simple matter of assembling the parts. Nevertheless, there are some<br />
things you can do to implement TaskSpace more effectively.<br />
Iterative rollout of a TaskSpace application<br />
When working with a customer to develop a TaskSpace application, use an iterative approach. This<br />
approach helps avoid having to redo a large and complex application when your customer informs you<br />
late in the process that what you have developed is not what they wanted.<br />
1. Determine the business <strong>processes</strong> necessary for the application.<br />
2. Determine the data model for the process.<br />
3. Create mock-ups of the Forms for that process.<br />
4. Quickly produce a TaskSpace application and ask the customer, Is this what you want<br />
Allowing the customer to see what you have in mind helps them to more fully visualize what it is they<br />
really want and need. Producing quick, iterative applications enables them to help you develop the<br />
right application for them.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 85
Creating the User Interface<br />
Working with task templates<br />
Task templates are complex and, given the close connection to <strong>processes</strong>, subject to problems if the<br />
underlying process changes. The following sections provide information specific to the buttons on task<br />
templates that can be affected by changes to the process or data model.<br />
Which task buttons to add<br />
When you create a task template, Forms Builder automatically adds the appropriate buttons based on<br />
whether there are one or more forward tasks, if the forwarding is conditional or manual, or if there<br />
are reject paths. However, if you add or remove process flows when modifying the process, these<br />
buttons remain static and therefore do not necessarily reflect the new process flows. When you test the<br />
application you may find that you are not able to finish or forward a task.<br />
The easiest solution is to add ALL task buttons that you think you may need. TaskSpace automatically<br />
shows and hides buttons as appropriate. This can save you much time during development. As a<br />
good practice, name the buttons with the same name as the actual activity (for example, if it is a<br />
Reject button, label it Reject). You can give it a custom display label, but the name should reflect<br />
the actual activity being performed.<br />
Finish button fails to work if the data model has changed<br />
If you change the underlying data model (such as a structured data type definition), update the task<br />
template itself to reflect this change, otherwise the Finish button may fail to work.<br />
1. Uninstall the task template.<br />
2. Save the task template.<br />
3. Install the task template again to refresh the template’s data model.<br />
Setting the height of the metadata pane in a folder<br />
view<br />
You can set the height of the metadata pane in a folder view using the Folder tab when configuring a<br />
role. Set the height of the metadata pane by selecting Show overview panel and then setting the height<br />
in pixels in the Overview panel height field.<br />
To determine how high you want the metadata:<br />
1. Open the folder contents template (Folder tab) in TaskSpace after creating a folder information<br />
template (which specifies the metadata).<br />
2. Drag the metadate frame to the desired size.<br />
3. Use Firebug (http://getfirebug.com) or a similar tool to find the height that you chose.<br />
This value is in the frameset’s cols attribute. The first value is the height in pixels of the metadata<br />
view.<br />
4. Use Role > Edit to set the height.<br />
Note: Add 16 pixels to compensate for the scroll bar.<br />
86 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Creating the User Interface<br />
Working with configurable actions<br />
The following sections provide some important guidelines when working with configurable actions.<br />
Configuring current object actions<br />
When configuring current object actions (that is, selecting Current Folder, Current Calendar, or<br />
Current Object as opposed to Selected Object) be sure to select the Always option for the Enable<br />
action if setting.<br />
A current object action is invoked against an object you are currently viewing (in the Open Item tab)<br />
such as a document, folder or task. Always indicates that the required action parameters are supplied<br />
by the object being viewed and that the action can be evaluated when the action control is rendered.<br />
Configuring selected object actions<br />
When configuring selected object actions (that is, selecting Selected Object as opposed to Current<br />
Folder, Current Calendar, or Current Object), be sure to select the One object selected\More than<br />
one object... option for the Enable action if setting.<br />
A selected object action is invoked against an object you have selected in the data grid. One object<br />
selected\More than one object... indicates that the required action parameters are not present until<br />
objects are selected in the data grid and that the action should not be evaluated until then.<br />
Assigning current object actions to menus<br />
Do not assign current object actions for use in configured menus. It is confusing to the user as to<br />
when menu items should be enabled or disabled:<br />
• If an object is selected in a folder content data grid, the action is enabled on the menu.<br />
• If an object is selected in a search view data grid, the action option is disabled on the menu.<br />
• Because the folder view provides proper current object context, the action can be enabled in folder<br />
view but not in search view.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 87
Creating the User Interface<br />
88 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 7<br />
Monitoring Business Activity<br />
This chapter discusses the following:<br />
• System requirements<br />
• Reporting requirements<br />
• Dashboard design considerations<br />
• Crystal Reports versus Simple Reports<br />
• Cleaning production environments<br />
• Custom aggregation<br />
• Leveraging the Preconfigured Dashboards<br />
• Dashboard refresh intervals<br />
• <strong>Designing</strong> drill-down reports<br />
• Formatting reports to be more readable<br />
• Computed Column dates and sorting<br />
System requirements<br />
It is a best practice to use the BAM Sizing Calculator to determine your hardware requirements before<br />
you install Business Activity Monitor. The sizing calculator is available on the <strong>EMC</strong> Download Center<br />
in the Documentum Business Activity Monitor Supplemental Files zip file. This tool calculates the size<br />
of the BAM database, the BAM server, and the Taskspace/BAM dashboard server, based on several<br />
metrics that you enter, including the number of <strong>processes</strong> you are monitoring, the number of process<br />
instances monitored per day, and the average number of activities in each process.<br />
Reporting requirements<br />
Planning is the most important step in deploying any component of xCP, including the Business<br />
Activity Monitor. If you are deploying BAM with Process Builder, Forms Builder, and TaskSpace,<br />
it is a best practice to define your reporting requirement as one of your first steps in deploying xCP.<br />
This requires that you brainstorm and design mock-ups of the BAM reports and dashboards that<br />
your business requires, even before you begin to design your process. Your reporting requirements<br />
can have a large impact on how your process is designed and the substance and structure of your data<br />
model, including SDTs and package attributes.<br />
The more detail included in your requirements specifications, the better. At a minimum, reporting<br />
requirements should include:<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 89
Monitoring Business Activity<br />
• purpose of report<br />
• report type (management report, operational report)<br />
• report columns<br />
• a description of drill-down relationships (both single and multi-drill-down reports)<br />
• audience<br />
• frequency and timing<br />
• report filters and dashboard filters (both default and initial filters)<br />
• graphical representation<br />
Providing a sample of the report helps identify the attributes that must be monitored in the process.<br />
The easiest way to design mock-ups is with Microsoft Excel where reports can be formatted numerous<br />
ways (tables, pie charts, bar charts, and so on). Although a fairly simple example, the following<br />
mock-up highlights that vendor and amount attributes must be monitored within the invoice process.<br />
In addition, since this report calculates an average amount, we know that aggregation is also required.<br />
This mock-up provides important information that impacts the design of your process.<br />
Identifying reports that rely on aggregation is an important part of defining report requirements. BAM<br />
provides three methods of aggregating report data. First, there is report aggregation which is based on<br />
instance-level data. Then, there is server aggregation where data is automatically aggregated for nine<br />
different time intervals (5 minutes, daily, and so on). And finally, there is custom aggregation. The<br />
Business Activity Monitor Implementation Guide has more information on each type of aggregation. In<br />
terms of planning, anticipating the type of aggregation you require is helpful. For example, if you have<br />
high-volume <strong>processes</strong> where thousands of instances are running each day, then report aggregation is<br />
not recommended. Attempting to aggregate large volumes of instance data (on request) consumes<br />
high server memory resources and can result in poor response time.<br />
Dashboard design considerations<br />
There are several best practices that relate to BAM dashboard design.<br />
90 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Monitoring Business Activity<br />
1. Dashboard content and quantity - It is best practice to determine the content to display in each<br />
dashboard. This work is really an extension of identifying reporting requirements since a majority<br />
of dashboards contain reports (dashboards can also contain process diagrams, alerts, and process<br />
simulation dashlets). One strategy to determine dashboard content is for each dashboard to contain<br />
the same type of information.<br />
• For instance, if you are monitoring a purchase order process, then you may want one dashboard<br />
(or more) to contain only summary information. Summary reports would be designed by using<br />
report aggregation or an aggregation report entity. This type of dashboard may be appropriate for<br />
an Operations Manager, for instance.<br />
• Then, you may want another set of dashboards to display instance-level data that looks at the<br />
status of individual <strong>processes</strong>. This type of dashboard may be appropriate for a task processor.<br />
• A third dashboard might include only alerts, which would be of interest to a supervisor.<br />
Another approach is to design dashboards that incorporate single and multi-drill-down reports.<br />
These dashboards integrate high-level, aggregated reports with reports that provide greater<br />
amounts of detail. Users can navigate, or drill-down, from one report to another based on their<br />
needs. Multi-drill-down reports update the contents in surrounding target reports based on a<br />
users’ selection in a base report. Single and multi-drill-down reports are addressed in the Business<br />
Activity Monitor Implementation Guide.<br />
Drill-down reports are well-suited in situations where the purpose of the dashboard is to identify<br />
root causes of process problems. Users must be able to move from one level of detail to another,<br />
while attempting to isolate the process instances that are problematic. Dashboards configured in<br />
this way should be provided to users that also have the authority to change the process, if necessary.<br />
2. Dashboard users - It is best practice to always consider the characteristics of your dashboard users<br />
as you design reports and begin to think through the contents of each dashboard. Individual users<br />
are assigned to one or more roles and dashboards are assigned to roles. That is the extent of the<br />
security, so when a dashboard is assigned to a role, all users associated with that role can view the<br />
contents of the dashboard. It is important to compile a complete list of users and roles so you do<br />
not inadvertently assign dashboards to users that do not require them. You may find that the roles<br />
available in the repository are too broad. In this case, you may need to create separate dashboard<br />
roles. Another method for controlling access is to use filter variables that limit the data displayed in<br />
dashboard reports to that owned by a specific dashboard user.<br />
3. Number of dashlets for each dashboard - The optimum number of dashlets contained in a single<br />
dashboard is determined by the resolution of the users’ monitors. If monitor resolution is 1440 x<br />
900, then no more than four dashlets should be included in a dashboard. If monitor resolution is<br />
set to 1920 x 1200, then up to six dashlets can be placed on a dashboard. It is best practice, then,<br />
to know the capabilities of users’ hardware, and to plan for the lowest common denominator.<br />
If 50 users have the higher monitor resolution, and 10 have the lower resolution, then plan for<br />
dashboard to contain four dashlets.<br />
There are a few other points to consider:<br />
• Dashlets containing Crystal Reports require more space so take this into consideration when<br />
you are planning dashboards<br />
• Small dashlets can be maximized<br />
Crystal Reports versus Simple Reports<br />
The Business Activity Monitor offers two approaches to designing BAM dashboard reports: simple<br />
reports and Crystal Reports. Simple reports are designed exclusively in Process Reporting Services<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 91
Monitoring Business Activity<br />
(PRS). Crystal Reports are designed first in PRS and then opened in the Crystal Report software<br />
where report design continues.<br />
Consider the following points when deciding whether to use simple reports or Crystal Reports:<br />
• Report formatting: While simple reports offer some formatting options, Crystal Reports offers<br />
more, including the use of report headers and watermarks. Crystal Reports has a greater selection of<br />
chart types and a richer syntax for writing computed column formulas. If you require a high degree<br />
of control over the look and feel of a report, then Crystal Reports is the best option.<br />
• Amount of report data: If you implement large grid reports with greater than 1,000 records, use<br />
Crystal Reports to improve performance. Use simple reports for smaller grid reports.<br />
Cleaning production environments<br />
Purging permanently deletes data from the BAM database, so developing a purging strategy is<br />
recommended. Ultimately, what to purge and how often to purge depends on how quickly the BAM<br />
database table space fills up. Your purge strategy also depends on how long you must keep BAM<br />
data for reporting purposes. One approach is to generate a dump file of the BAM database on a<br />
periodic basis, and then purge the entire BAM database. Historic data can be restored when required.<br />
Depending on the volume of process data, your strategy can be to take a snapshot of the BAM<br />
database every three or six months.<br />
Another strategy to use is to selectively purge tables that contain a lot of data. In BAM, there are<br />
instance-level tables and nine types of aggregation tables. Over the course of a single day, for instance,<br />
the 5 minutes aggregation table holds 288 rows, over a week it holds 2016 rows, and over a year this<br />
aggregation table holds 105,210 rows of data. The 5 minute aggregation data may not be useful to you<br />
beyond a few months, so purging this table every six months is probably reasonable. The same can be<br />
said of the 15 minutes aggregation table, although this table holds less data than the 5 minutes table,<br />
with 35,040 rows per year compared to 105,210 for the 5 minute table.<br />
Custom aggregation<br />
Your need to define custom aggregation report entities relates to the attributes you have selected to<br />
monitor. As a practical matter, do not collect data unless you absolutely must. If you need process<br />
data only once, then collect it at the end. If you need data more than once, for multiple activities in<br />
a process, then you may have problems with business data aggregation. For example, if a numeric<br />
attribute value during Activity A is 3 and the same attribute value for Activity D is 9, then the<br />
calculated average is 6, which is inaccurate. In reality, the value that should be incorporated into the<br />
calculation is 9, not 6. In these cases, custom aggregation report entities must be created. Custom<br />
aggregation must also be used when you want to combine data from multiple data sources and in<br />
situations when you need to combine process data and business data. For example, if you want to<br />
calculate the average duration it takes to process orders from the state of California, then custom<br />
aggregation must be used. Custom aggregation can also be used to improve BAM server performance<br />
when report aggregation attempts to collapse thousands and thousands of instance-level data.<br />
For more on custom aggregation, please see the Creating Custom Aggregation, Report, and Filter<br />
Entities chapter of the Business Activity Monitor Implementation Guide.<br />
92 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Monitoring Business Activity<br />
Leveraging the Preconfigured Dashboards<br />
The Preconfigured Dashboards, and the reports on which they are based, are an excellent source of<br />
learning and should be leveraged whenever possible. The simplest approach is to use the Preconfigured<br />
Dashboard reports to learn about data source creation and report design. In this way, users can reverse<br />
engineer the reports to learn how they were designed. Another way to leverage the Preconfigured<br />
Dashboard reports is to open them for editing in PRS, and add and/or remove data as appropriate. For<br />
instance, add SDT or package attribute data to the List of Process Instance report, since business data<br />
is not included in any of the Preconfigured Dashboard reports.<br />
CAUTION: If you modify any of the Preconfigured Dashboard reports, you must understand<br />
how to reformat the chart data. Adding and subtracting data disturbs the X-axis and Y-axis<br />
settings.<br />
Another approach to leveraging the Preconfigured Dashboards is to design a report and replace one<br />
of the dashlets in either of the three dashboards. With this approach you do not need to design a<br />
dashboard from scratch, you are simply replacing the contents of a dashboard that already exists.<br />
You are not required to create a dashboard tab, or assign the tab to roles, as is typically required<br />
when you design a dashboard. Keep in mind, though, that editing a dashboard changes the contents<br />
for users that are viewing it.<br />
Dashboard refresh intervals<br />
BAM dashboards can be configured to refresh after a certain interval of time. While there is no<br />
absolute best practice regarding refresh intervals, it is recommended that you determine how often you<br />
need to see updated data. If you have low volumes of long running <strong>processes</strong>, then a refresh interval of<br />
every few days may suffice. If you have high volumes of <strong>processes</strong> and your data changes frequently,<br />
then more regularly scheduled refresh periods is more appropriate. Refresh intervals are scheduled in<br />
minutes. Since refreshing a dashboard is somewhat demanding on the BAM system, it is important<br />
that you balance your needs with the frequency with which the data changes.<br />
<strong>Designing</strong> drill-down reports<br />
Single and multi-drill-down reports are configured with a source report and a target report. It is best<br />
practice to design the target report first, so that it is available on picklists when the source report is<br />
designed.<br />
Formatting reports to be more readable<br />
There are a few methods for making BAM dashboard reports more readable:<br />
• Entering a report title and subtitle in the Chart Properties window is not necessary since the name of<br />
the report appears in the title bar of the dashlet.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 93
Monitoring Business Activity<br />
• Use both report filters and dashlet filters as methods to reduce the number of records that appear<br />
in simple reports. This is especially true for bar and pie charts where 12 or more records make<br />
these reports difficult to read.<br />
• Modify the length of bar chart labels with the Limit Characters chart property.<br />
• Edit entity field captions so they are shorter.<br />
• Suppress chart animation in the Chart Properties window.<br />
• Remove the chart legend.<br />
• Use computed columns to shorten long date values.<br />
Computed Column dates and sorting<br />
The Computed Columns feature can be used to display Start Date and Time data in a number of date<br />
formats. For example, the Start Date and Time value of April 7, 2009 3:46:40 PM can be formatted<br />
as April 7, 2009, 4/7/2009, or Apr 7. The new date format can be displayed as the x-axis in a report. To<br />
display dates chronologically (and not alphabetically), select the original Start Date and Time column<br />
in the Sort field of the Chart Data window. In the following example, a computed column (date) is<br />
selected as the x-axis while Start Date and Time is selected as the sort column.<br />
94 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 8<br />
Performance and Scalability<br />
This chapter discusses the following:<br />
• General approach to performance<br />
• System configuration guidelines<br />
• Factors that affect performance and scalability<br />
• Recommended application server settings<br />
• Recommended Content Server settings<br />
• Recommended database server settings<br />
• Tuning and troubleshooting performance problems<br />
General approach to performance<br />
This section discusses general performance theory. Performance analysis treats a large number of<br />
different metrics, such as response time, throughput, efficiency, and capacity. The two that are the most<br />
important to process-based applications are response time and throughput.<br />
• Response time measures the amount of time you must wait to receive any response to a request;<br />
for example, running a series of automated activities may incur a response time of one second<br />
between each one.<br />
• Throughput measures the number of transactions the system can process per unit of time; for<br />
example, a system may be able to handle only 100 TaskSpace searches per minute.<br />
As you design the application, you should:<br />
• Not go deep. The reason for the recommendation to not go deep is that every layer of database<br />
tables generates additional joins that impact performance. You should keep your inheritance<br />
hierarchy as flat as you can.<br />
• Tune for the highest-yield queries. Yield is the number of times a query is executed multiplied by<br />
the execution time of the query. By anticipating the yield and tuning it for the highest-yield query,<br />
your performance does not degrade unacceptably for that use case. To achieve this you may need to<br />
de-normalize, pulling attributes into one or two physical tables.<br />
In general, the recommended approach to performance testing is to carry out two classes of tests:<br />
• Single user profiling — In single-user profiling you run unit tests, such as collecting Documentum<br />
Class Library (DMCL)/DFC traces.<br />
• Load testing — In load testing you are looking for bottlenecks and capacity issues.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 95
Performance and Scalability<br />
System configuration guidelines<br />
During the planning phase of a project it is important to define the scalability and performance<br />
requirements of the solution. Some process-based applications are high volume and require special<br />
considerations for deployment in a production environment. System configurations for production<br />
deployment can be grouped roughly by size as follows:<br />
• Small — Fewer than 300 TaskSpace users, fewer than 10,000 active workflow instances, one<br />
central location<br />
• Medium — Fewer than 2,000 TaskSpace users and fewer than 100,000 active workflow instances,<br />
distributed architecture<br />
• Large — More than 2,000 TaskSpace users, more than 100,000 active workflows, distributed<br />
architecture with clustering and failover<br />
To be accurate, identify sizing parameters such as the numbers of documents, number of activities per<br />
process, process duration, and the amount of data processed. One approach is for the project team<br />
to create a template that captures relevant sizing parameters and then validates the template with the<br />
client. Specify in the template the types of actions required for different volume levels. Large volumes<br />
of <strong>processes</strong> can raise issues of High Availability and Disaster Recovery, which require more complex<br />
and robust hardware requirements. Listing the types of equipment to support various volume levels<br />
helps clients make informed business decisions.<br />
Small configurations<br />
The recommended approach to host small configuration environments is to use WMware. Create a<br />
separate virtual machine for every tier. Each tier should have roughly 2 to 4 Central Processing<br />
Units (CPUs) with 4 GB to 8 GB of Random Access Memory (RAM). A WMware configuration<br />
could include:<br />
• TaskSpace application server<br />
• Content server<br />
• Database server<br />
• BAM application server<br />
• BAM server<br />
• BAM database server<br />
Medium configurations<br />
The recommended approach for medium configuration environments is to use enterprise machines.<br />
Software clustering can be used at the application server, database server, and content server levels.<br />
WMware can be used for the TaskSpace application server and the BAM application server. Large<br />
servers ranging from 4 CPUs to 16 CPUs and 8 GB to 32 GB of RAM are used for each of the<br />
following tiers:<br />
• TaskSpace application server<br />
• Content server<br />
• Database server<br />
96 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Performance and Scalability<br />
• BAM application server<br />
• BAM server<br />
• BAM database server<br />
• BOCS server at branch offices<br />
If required, this type of configuration supports multiple content server instances on a single machine<br />
and multiple content servers implemented on multiple machines.<br />
Large configurations<br />
Enterprise machines are used to host large configuration environments. Large configurations include<br />
hardware and software clustering at the application server, database server, and content server levels.<br />
WMware can be used for the TaskSpace application server and the BAM application server. Large<br />
servers with machines ranging from 16 CPUs to 64 CPUs and 32 GB to 128 GB of RAM are used for<br />
each of the following tiers:<br />
• TaskSpace application server<br />
• Content server<br />
• Database server<br />
• BAM application server<br />
• BAM server<br />
• BAM database server<br />
• BOCS server at branch offices<br />
Configuration best practices<br />
<strong>EMC</strong> recommends the following best practices:<br />
• Do not run TaskSpace and BAM on the same Java Virtual Machine (JVM).<br />
• Keep databases on separate servers.<br />
• If WMware is used, ensure that there is a fast pipeline to the Storage Area <strong>Network</strong>/<strong>Network</strong><br />
Attached Storage (SAN/NAS). <strong>EMC</strong> recommends using dedicated Fiber or 10 gigabit Internet Small<br />
Computer System Interface (ISCSI).<br />
• The network must not experience performance issues and it must have minimal latency.<br />
Documentum products are network sensitive and require a high speed network.<br />
• All tiers of the server environment must be co-located in the same data center.<br />
Consider system sizing during the design phase, since volumetric considerations influence the system<br />
design. For example, some process transactions, like the Task List, are high yield, which means<br />
that they are performed frequently. A transaction like that can perform well in a test environment,<br />
but can cause performance problems when you have many users making simultaneous transactions.<br />
Each transaction queries the database that must return results in under one second. Aggregate demand<br />
on the database adversely impacts user performance when a browser is unable to render screens in a<br />
timely fashion. It can take five seconds or longer in some cases. If there are thousands of simultaneous<br />
users querying the database, there may not be enough bandwidth to accommodate the demand and<br />
performance continues to degrade.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 97
Performance and Scalability<br />
Factors that affect performance and scalability<br />
This section describes the following factors that can affect performance and scalability:<br />
• Automatic activities, page 98<br />
• Search forms, page 98<br />
• Task lists, page 99<br />
• Preconditions, page 99<br />
• Skill-set matching, page 100<br />
• Logins, page 100<br />
Automatic activities<br />
To improve the performance of automatic activities in your process, make one user (or a small set<br />
of users) the performer of all the automatic activities. For example, if you define a user, such as<br />
auto_executor, and make that user the performer of all the automatic activities, the runtime execution<br />
of these automatic activities increases considerably.<br />
For security reasons, only a superuser can select a specific user as a performer for an automatic<br />
activity in Process Builder.<br />
Search forms<br />
A client may ask you to implement a more complex search option in TaskSpace. Even though it can<br />
be easy to configure multiple search options, advise the client against doing it. The difference in<br />
database performance (and maintenance) between three search options and four is enormous. The best<br />
performing applications enable users to complete their jobs with a minimum of actions and choices.<br />
<strong>Designing</strong> search forms that are seldom or never used is not advised.<br />
Minimize search criteria<br />
Design search forms with as few search criteria and columns as possible. This keeps application<br />
performance degradation to a minimum and makes any future scaling of the application easier. Each<br />
search criterion requires more maintenance by the database and adds load to the system. For instance,<br />
just one poorly constructed search form with many search options and columns can render the<br />
application non-operational. Before designing search forms, it is important that you fully understand<br />
the business use cases.<br />
Wildcard searches<br />
Avoid implementing wildcard searches because exact searches are the only searches that scale. All<br />
other types of searches involve some form of scanning (index or table), which can hinder the scalability<br />
of the database, and ultimately the entire application.<br />
It is important to separate what a client needs from what a client wants. The needs of the business<br />
should determine how search forms should be designed and used. System performance and future<br />
scalability become victim to over-engineered search forms. Articulate to the client the impact of search<br />
98 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Performance and Scalability<br />
technology on system performance. In most cases, clients are willing to reconsider a feature that<br />
negatively impacts system performance.<br />
Mandatory search attributes<br />
When designing a search panel, identify the mandatory fields so the user must always enter them to<br />
improve performance. Most attributes that are drop-downs or check boxes qualify for this case. Once<br />
you make them mandatory, create a composite index on these combined attributes. This ensures all<br />
search queries will at least use this index, instead of open-ended searches, to improve performance.<br />
Task lists<br />
Task lists are one of the most frequently used views in TaskSpace. The best performing task lists limit<br />
the number of SDTs and process variables that appear within the task list. Each additional SDT and<br />
process variable results in a new query to the database. When several concurrent users are working<br />
on the system, these queries add up. As a practical matter, you can consolidate one or more process<br />
variables into a single SDT. For example, a task list containing nine process variables takes 10 seconds<br />
to 15 seconds to populate the window. The same task list built with one SDT containing nine attributes<br />
takes only 3 seconds to 5 seconds. The difference is that the first task list issued nine requests to the<br />
database while the second task list issued only one request. (The best way to understand this behavior<br />
is to take a single click trace of the transaction).<br />
Consider the number of filters that you create in a task list because each filter impacts system<br />
performance.<br />
You can further improve task list performance by disabling full-text indexing if it is not being used.<br />
Refer to Disabling full-text indexing, page 103 for more information.<br />
Preconditions<br />
Be careful when using preconditions in a TaskSpace application because they inject row-by-row<br />
processing into the response time. If there are ten tasks in a task list and there is a precondition<br />
defined for the object type, then the precondition fires ten times. Although preconditions provide<br />
rich functionality, they can negatively affect system performance. For example, a task queue with<br />
preconditions took 8 seconds to 10 seconds to render. Without the preconditions, the same task list<br />
rendered in 3 seconds.<br />
It is recommended that you take a baseline timing of a task or search form before you add<br />
preconditions. After you establish the baseline, the incremental performance cost of a feature can be<br />
assessed. Associate a response time or resource cost for each feature request. Then it is possible to<br />
calculate the cost and benefit of each feature. Calculate a cost, even if a feature is mandatory. Discuss<br />
feature costs together with performance and scalability with the client.<br />
To optimize custom action preconditions for datagrid rendering, define scope values for action<br />
definitions that use the precondition.<br />
Avoid permission checking in precondition classes, since the system will do object full fetches for each<br />
data row. If your precondition must do permission checking, consider using lazy evaluation by adding<br />
the oneexecutiononly=’true’ attribute in the tag.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 99
Performance and Scalability<br />
Skill-set matching<br />
Skill-set matching is another feature that, if not used wisely, can lead to system performance issues.<br />
There are two reasons for system performance issues.<br />
First, skill-set matching involves row-by-row processing where every task that returns in a task list is<br />
evaluated against the user’s competency. This is a drain on system resources.<br />
Second, skill-set matching does not use task list database query language (DQL) optimizations.<br />
Without skill-set matching, a task list brings back the first 100 to 300 tasks. This means that the data<br />
list generated requires less resource consumption and performs faster. To bring back the tasks to the<br />
user when the system matches user skills against tasks, it requires the whole data list.<br />
This means that all tasks are sent to the application server for evaluation against the skill-set. If a task<br />
list contains 10,000 tasks, it brings back 10,000 tasks. Even if the user matches one task out of 10,000<br />
the system still brings back 10,000 tasks, which takes time. A task list with 10,000 tasks that does<br />
not match skill-sets brings back 100 to 300 tasks depending on the number of SDTs involved. It is a<br />
best practice to calculate a baseline timing of a task list before implementing skill-sets. This baseline<br />
calculation enables you to determine how skill-set matching impacts performance. It is important to<br />
realize that performance costs grow as the number of tasks grow in a task list. For example, a task list<br />
that returns 100,000 tasks is unusable.<br />
Logins<br />
The user login operation takes 2 seconds to 10 seconds to complete. The variable that most influences<br />
the login time is the landing tab that opens after a user logs in. If the client prefers a fast login, then set<br />
the landing page to the default page or to a blank search page. However, if the user has a preference<br />
about the tab, then the time to log in can take longer.<br />
Recommended application server settings<br />
<strong>EMC</strong> recommends using the following application server settings:<br />
Recommended Java Flags for a tomcat server<br />
JAVA_OPTS=-server -Xms1024m -Xmx1024m -XX:MaxPermSize=256m -XX:+UseParallelOldGC<br />
Server flag (-server) explanation<br />
JVM server mode provides better performance for long running tests. This must be the first flag.<br />
Permanent generation (-XX:MaxPermSize) explanation<br />
The application dynamically generates and loads many classes expanding the space in the heap to<br />
accommodate its reuse.<br />
Parallel garbage collection (-XX:+UseParallelOldGC) explanation<br />
This allows the JVM to use parallel garbage collection for the full collections.<br />
JVM Capacity<br />
Heap size and threads control the number of users the JVM can support. A JVM can accommodate 150<br />
to 300 users per instance depending on the user activity footprint (opening large forms can reduce the<br />
number of users) and throughput (how fast they are trying to finish the tasks). Response times degrade<br />
as more users enter the JVM. The degradation is due to non-availability of free heap space and users<br />
waiting for available threads. <strong>EMC</strong> recommends a 1024 MB heap. A heap size smaller than 512 MB<br />
100 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Performance and Scalability<br />
results in an out-of-memory error. If the permanent generation is not increased to a minimum of 128<br />
MB, it could also result in an out-of-memory error. The CPU is the first resource to bottleneck on<br />
this tier. The application server is the most scalable tier in the system because there is no limit to the<br />
number of JVM or servers that can be added.<br />
Additional tips<br />
• Configure JVM memory minimum and maximum heap size arguments to be the same.<br />
• If running Oracle WebLogic or IBM Web Sphere application server, apply different JVM memory<br />
arguments for Administrative and Managed Servers (less resources). Allocate less memory to the<br />
administrative server of each cluster and more memory to the managed server.<br />
• Each JVM has a finite capacity number of users it can accommodate. To increase the number of<br />
users a physical server can accommodate, create several JVM nodes on the server. Each JVM needs<br />
to have a different port. It is not uncommon for a physical server to have 4, 8, or 12 JVM instances.<br />
• If running WebLogic, have one Internet Information Services (IIS) server installed on each web<br />
server host machine and for each IIS server installation provide appropriate mappings to the<br />
different cluster Internet Protocols (IPs).<br />
• If running WebLogic, use JRockit.<br />
• Turn off AnnotationHelper for Tomcat 6.x. To turn off AnnotationHelper, set<br />
metadata-complete=true in the tag of the web.xml file.<br />
• In web.xml, you can increase the value of to push off the expiration date for files,<br />
such as icons and images, on the client side cache.<br />
Recommended Content Server settings<br />
To ensure that Content Server is running to its potential, turn off mail notification, if possible. To turn<br />
off mail notification, put MAIL_NOTIFICATION=F in the server.ini and reboot. Also, narrow the<br />
audit trails to track only the essential events. Audits can slow down response times and increase CPU<br />
on the Content Server and database. Increasing CPU usage decreases performance on the content<br />
server.<br />
The Content Server is scalable. You can add a second Content Server to the same or different server<br />
without causing a problem, but both Content Servers should be close in proximity. If a second Content<br />
Server is created either on the same or a different server, configure the server.ini file to make it also<br />
project to the docbroker with the same proximity.<br />
Turn off debugging on the process engine. By default, the debug mode is turned on. This results in<br />
unnecessary Input/Output (IO) and CPU resource consumption. To turn off debugging, copy and paste<br />
the following to the xml file:<br />
%Documentum%\jboss4.3.0\server\DctmServer_MethodServer\conf\jboss-log4j.xml (Windows)<br />
$DOCUMENTUM_SHARED/jboss4.3.0/server/DctmServer_MethodServer/conf/jboss-log4j.xml<br />
(UNIX/Linux)<br />
<br />
<br />
<br />
<br />
<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 101
Performance and Scalability<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
If you are using the JBoss Application Server, turn off debugging. By default, the debug mode is<br />
turned on. This results in unnecessary IO and CPU resource consumption. To turn off debugging, copy<br />
and paste the following to the xml file:<br />
%Documentum%\jboss4.3.0\server\DctmServer_MethodServer\conf\jboss-log4j.xml (Windows)<br />
$DOCUMENTUM_SHARED/jboss4.3.0/server/DctmServer_MethodServer/conf/jboss-log4j.xml<br />
(UNIX/Linux)<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
102 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Performance and Scalability<br />
Disabling full-text indexing<br />
If you do not need indexing for your xCP applications, disable full-text indexing by unregistering the<br />
events related to full-text indexing. If your system is in production when you unregister full-text<br />
events, you must also purge any existing events. Refer to Purging existing full-text events, page 104<br />
for more information.<br />
Each sysobject has about five registered events related to dm_fulltext_index_user:<br />
• dm_save<br />
• dm_destroy<br />
• dm_readonlysave<br />
• dm_checkin<br />
• dm_move_content<br />
If you are using indexing, these events are dequeued and purged when the index server is running. If<br />
you do not have an index server or it is not running for administrative reasons, the queue can become<br />
too large causing performance problems for task list queries.<br />
To unregister full-text events:<br />
1. In Documentum Administrator, navigate to the Type Properties ‐ Info page:<br />
a. Navigate to Administration > Types to access the Types list page.<br />
A list of existing object types is displayed.<br />
b. Select the type to modify and then select View > Properties > Info to access the Type<br />
Properties ‐ Info page.<br />
2. Clear the Enable Indexing: Register for indexing checkbox to unregister the type for full‐text<br />
indexing.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 103
Performance and Scalability<br />
If registering a particular type for indexing, the system automatically selects its subtypes for<br />
indexing. When registering a type for indexing, the system checks for any of its subtypes that are<br />
registered. If a subtype is registered, the system unregisters it before registering the type.<br />
The system displays the Enable Indexing checkbox based on the following criteria:<br />
• If the type is dm_sysobject or its subtypes and you are connected as a Superuser to a 5.3 SP5<br />
or later repository, the system displays the checkbox. If neither of these conditions is met,<br />
the system does not display the checkbox.<br />
• If a type and none of its supertypes are registered, the system displays the checkbox cleared and<br />
enabled. You can select the checkbox to register the type for full‐text indexing.<br />
• If a type is registered and none of its supertypes are registered, the system displays the Enable<br />
Indexing checkbox selected and enabled.<br />
• If a type’s supertype is registered for indexing, the system displays the Enable Indexing<br />
checkbox selected but disabled. You cannot clear the checkbox.<br />
Note: The system does not display the Enable Indexing checkbox on the New Types - Info page<br />
when you create a new type. You must first create the type and then save it.<br />
3. Click OK to save your changes.<br />
Purging existing full-text events<br />
To purge existing events:<br />
1. Export the dmi_queue_item_s table using database utilities like exp in Oracle. For example,<br />
the commands for Oracle are shown below.<br />
a. Export the full table in this step to have a backup.<br />
exp username/password file=dmi_queue_item_s_full.dat log=dmi_queue_item_s_full.log<br />
tables=dmi_queue_item_s buffer=100000<br />
b. Export the table again by selectively retrieving rows that you want other than<br />
dm_fulltext_index_user.<br />
(Windows) — Notice that there are three double quotes in the query clause:<br />
exp username/password file=dmi_queue_item_s.dat log=dmi_queue_item_s.log<br />
tables=dmi_queue_item_s buffer=100000 query="""where name not in<br />
’dm_fulltext_index_user’"""<br />
(UNIX) — Notice the back slash (\) instead of double quotes ("):<br />
exp username/password file=dmi_queue_item_s.dat log=dmi_queue_item_s.log<br />
tables=dmi_queue_item_s buffer=100000 query=\"where name not in<br />
\’dm_fulltext_index_user\’ \"<br />
2. Truncate the table dmi_queue_item_s as it will not create any redo entries and is the fastest way to<br />
delete millions of rows that are related to full text. If you do not have too many rows, you can do a<br />
simple delete and you do not have to reimport the data.<br />
truncate table dmi_queue_item_s<br />
3. Reimport the exported data that does not contain full-text events.<br />
104 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Performance and Scalability<br />
imp username/password file=dmi_queue_item_s.dat log=dmi_queue_item_s_imp.log<br />
buffer=100000 full=y<br />
4. Gather statistics on the table to capture the correct statistics.<br />
Recommended database server settings<br />
The following Oracle database parameters are essential for xCP:<br />
cursor_sharing = FORCE<br />
optimizer_mode = ALL_ROWS<br />
optimizer_index_cost_adj = 5<br />
optimizer_index_caching = 95<br />
The optimizer_index_* parameter values 5 and 95 are good starting levels.<br />
These database parameters can be modified in the init.ora or through Oracle Enterprise Manager<br />
(OEM).<br />
Frequently monitor Automatic Workload Repository (AWR) reports collected during peak usage to<br />
identify whether you allocated enough memory to the System Global Area (SGA) and Program Global<br />
Area (PGA). Determine if there are any queries consuming considerable resources.<br />
The following Microsoft SQL Server database parameters are essential for xCP:<br />
Parameterization = FORCED<br />
max degree of parallelism = 1<br />
The Parameterization database parameter can be changed using SQL Server management studio or<br />
by running this command:<br />
alter database set parameterization forced<br />
The max degree of parallelism can be changed as follows:<br />
sp_configure ’max degree of parallelism’,’1’<br />
reconfigure<br />
On the Content Server, especially when running with a SQL Server database, you should also set the<br />
DM_LEFT_OUTER_JOIN_FOR_ACL=’T’ environment variable to improve performance.<br />
Tuning and troubleshooting performance<br />
problems<br />
If a certain type of user click in the application takes longer than expected, tune it. The fast and<br />
efficient way to solve performance problems is to take and analyze a Documentum Foundation<br />
Class (DFC) trace. Documentum provides scripts that aggregate this information and present it in a<br />
readable format, with a complete breakdown of the transaction. By examining the analyzed trace, you<br />
can determine whether the issue is poorly-performing DQL, inefficient code, list generation issue,<br />
or a non-optimized system.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 105
Performance and Scalability<br />
106 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 9<br />
Deploying the Application<br />
This chapter discusses the following:<br />
• Deploying the application overview<br />
• The deployment process<br />
• Deployment best practices<br />
Deploying the application overview<br />
After the application has been developed and tested, it is ready for the production environment. The<br />
environment in which process-based applications are put into production generally differs from the<br />
development environment. The production environment usually has more users and, therefore, requires<br />
more hardware components, software modules, and databases. In this document, the term deployment<br />
means the transfer of applications between environments: from development to test or from test to<br />
production, with as many intermediate environments as necessary. In the general setting, you deploy<br />
applications from a source environment to a target environment.<br />
The deployment process begins by preparing the target environment. To prepare the target<br />
environment, <strong>EMC</strong> Documentum products such as Content Server, Process Engine, Process<br />
Builder, and BAM that were installed in the source environment must also be installed in the target<br />
environment. The next step is to define the users in the target environment. In most cases, the users in<br />
the target environment are different from the users in the source environment.<br />
The deployment process<br />
After you have developed a TaskSpace application with BAM dashboards and have completed testing<br />
the application, you can begin deployment. (If you have not implemented BAM in your solution,<br />
skip steps 3, 4, and 6).<br />
To deploy:<br />
1. Install TaskSpace and other xCP products in the target environment.<br />
2. Create a Composer project. Add the SDTs that you used to create BAM reports to this project.<br />
Build a Documentum Archive (DAR) file. Install it on the target environment.<br />
3. Start BAM in the production environment. The report entities corresponding to the SDTs you<br />
imported in Step 1 will be populated in the Documentum repository.<br />
4. If you created BAM custom entities, they are not migrated by using Composer. When you created<br />
those entities you would have run one or more DQL scripts. Save the DQL scripts as a text file.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 107
Deploying the Application<br />
At deployment time, manually run those scripts in the target environment to create your custom<br />
entities in the BAM database.<br />
5. In Composer, create a new TaskSpace application project. Select the TaskSpace application name<br />
from the list of available TaskSpace applications.<br />
This action automatically pulls in all related artifacts:<br />
• The associated process (from Process Builder), associated forms, roles, tabs<br />
• Associated BAM dashboards (defined as tabs in TaskSpace)<br />
• First-level BAM reports on these dashboards (First-level reports are not defined as drilldown<br />
reports)<br />
6. Manually import the drilldown reports. This action is required because the drilldown reports you<br />
created in your dashboards are not automatically imported into the project. Also, import the<br />
BAM Configuration artifact that contains various settings used by BAM (such as time settings for<br />
the gap filler).<br />
7. If you are using headless Composer, build the DAR file for this project.<br />
Composer builds the DAR automatically. It is located in the bin-dar folder of the project root.<br />
8. Install the Composer project into the target environment.<br />
Deployment best practices<br />
This section lists some best practices to follow for deployment:<br />
Composer version<br />
Use the latest version of Composer including any hot fixes that are available.<br />
Linking process templates to your application<br />
When constructing your TaskSpace application, it is best to link the process templates to your<br />
application. This causes the linked process templates to import automatically into your Composer<br />
Project when your TaskSpace application is imported into your Composer Project. Processes required<br />
by your application that are not linked to your TaskSpace application are not imported automatically<br />
when the TaskSpace application is imported and must be added individually to your Composer project<br />
or they will not be available in the production environment after the Composer project is installed.<br />
Database references<br />
Whenever database references change as you move from the source to the target environment, these<br />
references must be manually updated to the new database reference. Do this after you install your<br />
application into the production environment.<br />
Specific performers in <strong>processes</strong><br />
When <strong>processes</strong> contain specific performers, reference those performers as process parameters.<br />
Process parameters become installation parameters in the Composer project. This enables you to make<br />
the replacement in your Composer project once for each process rather than once for each activity in<br />
108 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Deploying the Application<br />
which the performer is referenced. It also enables you to replace a performer globally throughout a<br />
process with a new performer without making a replacement at each activity the performer is used.<br />
Note: A process parameter is specific to a process. Therefore, process designers must update the<br />
process parameter for each process, even if two <strong>processes</strong> have a process parameter with the same<br />
name.<br />
Updating process data<br />
To modify an SDT in any of the following ways, delete the SDT (from the target environment) before<br />
installing your application into the production environment:<br />
• Remove an attribute.<br />
• Decrease the length of a string variable.<br />
• Change a repeating attribute to a non-repeating attribute.<br />
• Change the data type of an attribute.<br />
To update an object type in any of the following ways, drop the object type from the production<br />
environment before installing your application into the production environment:<br />
• Remove an attribute.<br />
• Decrease the length of a string variable.<br />
• Change a non-repeating attribute to a repeating attribute.<br />
• Change a repeating attribute to a non-repeating attribute.<br />
• Change the data type of an attribute.<br />
Versioning the process template<br />
If the application you are deploying replaces existing process templates that have running workflows,<br />
version the process template. Versioning the process template enables existing workflows to continue<br />
to function after the application updates the process template. To version the process template, do the<br />
following:Existing workflows complete by using the older version of the process template, while new<br />
instances of the process template use the new version of the process template.<br />
1. Import your updated process template into your project and set the installation options of the<br />
process template to VERSION.<br />
2. Install the DAR file created from this project into your target repository.<br />
Overwriting an existing process<br />
When deploying an application from one environment to another, do the following to overwrite<br />
an existing process (rather than versioning it).<br />
1. Uninstall the process templates that will be overwritten. This halts running workflows.<br />
2. Reinstall the process template, selecting to abort all running workflows. This ensures that there are<br />
no running workflows when the process template is overwritten.<br />
When to use Composer<br />
Do not use Composer as a development environment to modify your <strong>processes</strong>. Use Composer only to<br />
archive and install (including the use of installation parameters). Use the appropriate tool in xCP to<br />
make changes.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 109
Deploying the Application<br />
110 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Chapter 10<br />
Archiving the Application<br />
This chapter discusses the following:<br />
• Manually Archiving TaskSpace Applications<br />
Manually Archiving TaskSpace Applications<br />
This section provides step-by-step instructions on manually archiving and installing a TaskSpace<br />
application. However, it does not address automatic builds with Apache Ant. Since the incorporation<br />
of importArtifacts in Composer version 6.6, it is possible to build TaskSpace applications with Ant.<br />
This approach can be preferable if you are packaging with any frequency (daily, weekly, or bi-weekly<br />
builds).<br />
Manual archiving uses a zipped composer project file, rather than a DAR file, to enable you to fix any<br />
problems when reinstalling the target side application.<br />
The following are examples of when to archive a TaskSpace application manually:<br />
• Moving an application from one environment to another<br />
• Saving an application for later use or reference<br />
Do not use manual application archiving as part of the development process of a project, try to use<br />
automatic builds instead.<br />
Best practices before and after archiving<br />
When you decide to create a TaskSpace application, the following best practices can make archiving<br />
the application quicker and easier.<br />
• When you decide to archive an application, consider Composer only as a transport or archiving<br />
utility. Do not modify your Composer project after you have imported your artifacts. If you created<br />
your types or objects in a Composer project, consider it only as a bootstrapping project to create the<br />
artifacts for your application archive.<br />
• Always define your folder structure for your TaskSpace application so that you can simply archive<br />
the whole cabinet or folder with the workflows already in there. This way you avoid archiving the<br />
workflows separately.<br />
• Store workflows for a specific application in their own folder to make them more recognizable.<br />
Archive this folder manually. DO NOT archive it in a cabinet or folder that needs a manual archive.<br />
• Organize your Structured Data Types under a category to make them easier to identify when<br />
archiving.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 111
Archiving the Application<br />
• When you create custom objects (forms, object types, process templates, and so on), it is beneficial<br />
to have a standard naming convention. For example, you can add the same prefix to the name of the<br />
object. This way, the custom objects are easier to identify when archiving.<br />
• Always make sure to add all object types, forms, <strong>processes</strong>, and roles that your Taskspace<br />
application uses in the Configuration tab.<br />
• If possible, always test your archived application on a virtual machine. If the archived application<br />
fails, the virtual machine enables you to roll back the system to its initial state.<br />
Archiving in Documentum releases 6.6 and higher<br />
In versions 6.6 and higher, it is no longer necessary to download TCMReferenceProject into Composer<br />
to make the archive work properly.<br />
1. For every TaskSpace application you want to archive, repeat steps 1a to 1f in Composer:<br />
a. Select File > New > Project > Documentum Project > Documentum Project From<br />
TaskSpace Application and click Next.<br />
b. Log in to the repository and click Next.<br />
c. Select your TaskSpace application from the list and click Next.<br />
112 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Archiving the Application<br />
d. Click Finish when done.<br />
e. When you are asked if you want to open the associated perspective, click Yes.<br />
f. Make sure both TCMReferenceProject and the new one you just created reference each other.<br />
Right-click the project, select Properties, and then select the Project References option.<br />
2. Expand the new TaskSpace project, expand Artifacts, and import the following artifacts for<br />
any custom folders:<br />
a. Right-click Folders and select Import > Documentum > Artifacts From Repository.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 113
Archiving the Application<br />
b. Log in to the repository and click Next.<br />
c. In the Choose Artifact Type field, select Folder.<br />
d. Select all your custom folders (press Ctrl and then click to select more than one), hover your<br />
mouse over the first option (Import the selected folder with all sub-folders), and click it.<br />
114 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Archiving the Application<br />
e. If you are asked if you want to overwrite the artifact, click Skip.<br />
3. For every item under Artifacts, verify that your custom objects are imported correctly. If not,<br />
right-click the item and import what is missing (refer to steps 2a to 2e for importing objects).<br />
4. Build the new projects:<br />
a. Turn off automatically building the project. Select Project from the menu and click Build<br />
Automatically to clear the check box.<br />
b. Right-click your project and select Build Project.<br />
Building a project generates a DAR file in the ...\\\bin‐dar directory.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 115
Archiving the Application<br />
5. Create a zip file of the composer project to use later when installing the archived application.<br />
In File Explorer, find your workspace, right-click the project, select 7-Zip > Add to archive<br />
to create a zip file of each project.<br />
Testing the Archived Application, page 116 details the steps required to install the archived<br />
application.<br />
6. Copy the zip file to a location that can be accessible for later use in other systems.<br />
For example, you can:<br />
• Email it to yourself.<br />
• Paste it to a folder in an FTP site.<br />
• Paste it to a folder in ftp://ftp2.emc.com/, which is available in all demo systems.<br />
You are now done with archiving your TaskSpace application.<br />
Testing the Archived Application<br />
We recommend that you use a VM (Virtual Machine) to test the archived application. With a virtual<br />
machine, you can roll back the system to the initial state in case of failure.<br />
To install the archived TaskSpace applications, you can use the DAR file generated while archiving<br />
the application or import the zipped project into Composer. This procedure describes importing the<br />
zipped project into Composer.<br />
To install the archived application:<br />
1. Import the zipped project into composer:<br />
a. Retrieve the Composer project zip file and put it into a temporary location on the target system.<br />
b. In Composer, select File > Import > Documentum > Existing Projects Into Workspace<br />
and click Next.<br />
116 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Archiving the Application<br />
c. In the Select archive file field, select the zip file from your temporary location.<br />
d. Click Finish.<br />
The system creates a project for your TaskSpace application in Composer.<br />
e. When asked if you want to open the associated perspective, click Yes.<br />
f. Expand the Artifacts folder of the project. Verify that all of your custom components are<br />
available.<br />
g. Right-click the project and select Install Documentum Project.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 117
Archiving the Application<br />
h. Select the appropriate repository; enter the user name and password; and then log in to the<br />
repository.<br />
i. Click Next.<br />
A list of your custom components appears.<br />
j. To add an Installation Parameter File, in the box at the bottom, click Browse.<br />
k. Click Finish.<br />
2. To access the application on the new system:<br />
http://:/taskspace/component/main/appname=<br />
3. When archiving an xCP application using Composer, the association of the users to any roles that<br />
you have setup is not going to be included. Therefore, you either have to set them up in the<br />
new environment manually, or use a script to do it automatically. This script is described at the<br />
following link:<br />
https://community.emc.com/docs/DOC-10087<br />
Troubleshooting the Archived Application<br />
While archiving and/or after you install the archived application, if there are any error messages<br />
try the following:<br />
• In Content Server, check the log files under C:\temp\documentum.<br />
118 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Archiving the Application<br />
• In Composer, check all the artifacts for your custom objects. If any are missing, import them to<br />
the specific artifact, and rebuild the project.<br />
• For any specific error message, log in to the <strong>EMC</strong> Developers <strong>Community</strong> site<br />
(https://community.emc.com) and search for the error. You can find helpful tips that other<br />
developers have posted.<br />
• If you need further details, you can enable tracing. Try the operations and then check the logs<br />
again. They can provide a clearer picture as to what Composer tried to do and what failed. The<br />
Documentum Composer User Guide provides details on how to enable tracing.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 119
Archiving the Application<br />
120 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Appendix A<br />
Prototyping Business Activity Monitor<br />
dashboards<br />
This appendix contains the following:<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
∙<br />
Prototyping overview<br />
Understanding the example<br />
Understanding the approach to prototyping<br />
Including Business Data in your prototype<br />
Create and run the New Account Applications process<br />
<strong>Designing</strong> the New Account Applications report<br />
Design dashboard and add dashlets<br />
Process Duration alert<br />
New Account Process - Average Duration<br />
<strong>Designing</strong> the New Account Process - Average Duration process<br />
Running the Average Duration process<br />
<strong>Designing</strong> the Average Duration report<br />
New Accounts by Customer Type<br />
<strong>Designing</strong> the New Account by Customer Type process<br />
Running the New Accounts by Customer Type process<br />
<strong>Designing</strong> the New Accounts by Customer Type report<br />
New Accounts Opened This Week<br />
<strong>Designing</strong> the New Accounts Opened this Week process<br />
Running the New Accounts Opened this Week process<br />
<strong>Designing</strong> the New Accounts Opened this Week report<br />
New Accounts Opened Last Week<br />
<strong>Designing</strong> the New Accounts Opened Last Week process<br />
Running the New Accounts Opened Last Week process<br />
Completing the prototype dashboard<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 121
Prototyping overview<br />
Prototyping overview<br />
Technical solutions that include Business Activity Monitor and other applications of xCP (Process<br />
Builder, Forms Builder, TaskSpace) take time to design and deploy to end users. When a project is<br />
completed a fully designed, tested, and monitored process is deployed to users who complete real<br />
work. Dashboards are populated when users start and work with their <strong>processes</strong>. Dashboards can also<br />
be populated with data from test <strong>processes</strong> (ones yet to be deployed) but the process designer is<br />
still responsible for designing a fully functional process. How then, is it possible to design a mock<br />
dashboard that includes a variety of dashboard features, without having a fully developed process<br />
This answer is to design a dashboard prototype. Dashboard prototypes are designed in TaskSpace, and<br />
contain reports designed in Process Reporting Services (PRS). The simple reports (this document does<br />
not include adding Crystal Reports to a dashboard) display example data that you populate while a<br />
number of small <strong>processes</strong> run. This data is formatted to appear as bar charts, pie charts, line graphs,<br />
and dial gauges. Prototypes can also include multi- and single drill-down reports.<br />
<strong>Designing</strong> prototype dashboards serves a few functions. First, prototypes are used by internal resources<br />
of organizations deploying BAM. xCP projects that require planning and designing prototypes help<br />
project members determine which reports are important. Prototyping is also a good way of helping to<br />
define some of the process data requirements. Since a prototype dashboard can contain business data<br />
reports, key business attributes should be included in your data model, and flagged for monitoring.<br />
Dashboard prototypes can also be demonstrated to either internal or external audiences to obtain<br />
valuable feedback prior to actual deployment. Prototypes are an excellent method for demonstrating<br />
the concepts and value of process monitoring.<br />
Whatever the goal, this approach assumes that the prototype designer has a basic understanding of<br />
Process Builder, TaskSpace, and Business Activity Monitor. This documentation does not replace the<br />
Process Builder User Guide or the Business Activity Monitor Implementation Guide. It is assumed that<br />
you are already familiar with those technologies.<br />
This appendix explains how to easily design prototype dashboards that can be used for planning and<br />
demonstrations. The audience for this information is:<br />
• an <strong>EMC</strong> partner that is engaged with a client that wants to see proof that BAM dashboards can be<br />
designed to meet their needs<br />
• an <strong>EMC</strong> customer that is involved in the planning phase of an implementation and wants to see<br />
prototype BAM dashboards without going through an entire xCP deployment<br />
• a pre-sales resource<br />
Note: The procedures provided in this document provide actual data that you can enter. If you follow<br />
this approach you will design the Finance Corp prototype dashboard in its entirety. Or, you can apply<br />
the approach described to your own situation, and attempt to build your own prototype dashboard.<br />
Understanding the example<br />
The example used throughout this document focuses on a fictitious company called Finance Corp.<br />
Finance Corp is in the process of building an automated approach to the New Account Opening<br />
process. As part of the planning, Finance Corp is designing a BAM dashboard prototype that includes<br />
reports about their New Account Opening process. The dashboard prototype includes six dashlets:<br />
122 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
Finance Corp is also interested in demonstrating the following dashboard capabilities:<br />
• single drill-down reports<br />
• multi-drill-down reports<br />
• Service Level Agreement (SLAs)<br />
The dashboard is conceptually divided into two parts. The contents of the New Account Applications<br />
report and the Alert List and Process Diagram dashlets are each related to a real, but mock process<br />
called New Account Applications. Understanding the approach to prototyping, page 124 addresses<br />
the role and design of the New Account Applications process. In addition, each of these three<br />
dashlets are designed with entities that are shipped with BAM which means they can be applied to<br />
all demonstration scenarios.<br />
• New Account Applications — this report is designed with the Process Execution entity.<br />
• Alert List — this dashlet displays information about <strong>processes</strong> or activities that meet an alert<br />
condition defined in PRS. Defining alerts in PRS is not included in this document. Refer to the<br />
Business Activity Monitor Implementation Guide for more information on alerting.<br />
• Process Diagram — this dashlet displays the progress of a single process instance when a process is<br />
selected in the New Account Applications report.<br />
The remaining three dashlets in this dashboard contain four business data reports. Four different<br />
business data reports can be viewed because the New Accounts this Week report is configured as a<br />
single drill-down report that displays the New Accounts by Customer Type report when any of the bars<br />
are clicked in the source report. The most important point to understand about business data reports<br />
is that they are designed with report entities that reflect the name and structure of SDTs defined in<br />
Process Builder.<br />
• New Account Process — this report is formatted as a dial gauge that displays average process<br />
duration.<br />
• New Accounts Opened this Week — this report is formatted as a bar chart that counts the number<br />
of new accounts opened in each country within the last week.<br />
• New Accounts By Customer Type — this report is formatted as a pie chart and is configured as the<br />
target report in a single drill-down report. It is linked to the New Accounts Opened this Week report.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 123
Understanding the approach to prototyping<br />
• New Accounts Opened Last Week — this report is formatted as a line graph that counts the number<br />
of new accounts opened each day during the last week. This report includes a Service Level<br />
Agreement (SLA) represented as a line.<br />
Understanding the approach to prototyping<br />
You may have a process already designed in Process Builder, and instead of going through a full<br />
deployment, you want to extend the design to incorporate a prototype dashboard. The approach<br />
outlined in this document accommodates this particular case, but it does not assume it. That is, you<br />
can begin with nothing. Either way, your first step is to design a mock process. A mock process is a<br />
legitimate process in Process Builder that executes in Process Engine, but it does not perform any real<br />
work. There is no scanning in Captiva, documents are not linked to folders, there are no forms to fill<br />
out, web services are not used, and there are no SDTs or packages. All of the automated steps in the<br />
mock process are no-ops. Each manual step requires a human performer to click the Finish button.<br />
If you already have a pre-existing business process you can substitute your process for the process<br />
outlined in Create and run the New Account Applications process, page 126. We recommend that<br />
you leverage the best practices discussed in this document to organize a single complex business<br />
process into smaller reusable grouped sub-<strong>processes</strong>. This is important when displaying dashboard<br />
diagrams because long and complex <strong>processes</strong> are difficult to interpret and understand by the typical<br />
target audience. Dashboard users are more focused on groups of activities that apply directly to them.<br />
Fortunately, leveraging Process Builder, it is possible to group related activities into sub-<strong>processes</strong> that<br />
simplify the process into its essential user activities. If you don’t have a pre-existing process, you can<br />
design the example process described in this document.<br />
Note: The simplified, but realistic no-op process you design provides what you need for the New<br />
Account Applications report, the Alert List dashlet, and the Process Diagram dashlets. The remaining<br />
reports are populated by the approach described in Including Business Data in your prototype,<br />
page 125.<br />
The following figures display the before and after views of a New Applications process following best<br />
practices.<br />
Figure 16<br />
Before<br />
124 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
Figure 17<br />
After<br />
Including Business Data in your prototype<br />
In a typical deployment of BAM groups of process instances can be analyzed over time. Trend reports<br />
that capture the behavior of <strong>processes</strong> over time, like the one shown below, is a common dashboard<br />
requirement. This report calculates the number of process instances that are started each day during the<br />
last week. This type of calculation requires process data to be aggregated by BAM over the course<br />
of a week. But when building a dashboard prototype, a week’s worth of data will not be available.<br />
In addition, the simplified, mock process does not carry any content, so how are reports that include<br />
business data (in this case, SDT attribute values) supposed to be included in a prototype dashboard<br />
The answer is to use a series of <strong>processes</strong> that each carry an SDT. SDTs are used to enter data values<br />
directly and treat them as if they were daily summaries.<br />
Prototypes are designed so that each report in the dashboard is populated with data from its own<br />
process. Each process contains two activities, one manual and one automatic. The automated activity<br />
is completed by a no-op method, and the manual activity is completed by a user. During the manual<br />
step, values to be displayed in the report are entered as process variables. Once the <strong>processes</strong> are run,<br />
the reports can be designed in PRS.<br />
This approach gives the illusion that all of the business data reports are derived from the simplified<br />
process (in this case, the New Account Applications process) when in fact they are completely separate.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 125
Create and run the New Account Applications process<br />
Create and run the New Account Applications<br />
process<br />
The New Account Applications process is a realistic, but mock process. It is realistic in the sense that<br />
the activities have meaning, and look as though worked is being completed. But in actuality there<br />
is no work being performed. There is no content attached to the process, no queues, and no human<br />
performers. All automated activities are executed by a no-op method. The process is functional,<br />
however, and will be started a few times. There are manual steps that can be completed by clicking the<br />
OK button in TaskSpace. Including a process like this in your prototype is important because it can be<br />
used to demonstrate how process diagrams are displayed in a dashboard. If you have chosen to use<br />
alerts in your prototype, then the contents displayed in the Alert List dashlet is also a by-product of<br />
running this process.<br />
To create and run the New Account Applications process:<br />
1. Lay out the New Account Applications process in Process Builder.<br />
2. For each automated activity, select dm_noop_auto_method as the method.<br />
3. Leave each manual activity as is.<br />
4. Open the Process Properties dialog and select On for the Audit Trail Settings.<br />
Note: Your user must be assigned the Config Audit extended privilege in TaskSpace. For<br />
more information on assigning this extended privilege refer to the Business Activity Monitor<br />
Implementation Guide.<br />
5. Save, validate, and install the process.<br />
6. Log in to TaskSpace and click the Processes tab.<br />
7. Select the New Account Applications process and click Start Process.<br />
126 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
8. On the Start Workflow: Info window, click Finish. The New Account Applications process is<br />
now completed.<br />
9. Repeat the previous step to start the New Account Applications process four more times. Complete<br />
two of these four <strong>processes</strong>.<br />
<strong>Designing</strong> the New Account Applications report<br />
The New Account Applications report provides a list of process instances that have started and<br />
for those that have completed, the finished time and duration is displayed. This report is a table<br />
that contains four columns: Process, Start Date and Time, Finished Date and Time, and Duration<br />
(hh:mm:ss). The data source also includes one additional field, Process Instance ID, that is used to<br />
configure Process as a multi-drill-down column. In the New Account Applications report the process<br />
name appears as a hyperlink that when selected updates the alert list and process diagram dashlets.<br />
To design the New Account Applications report:<br />
1. Log in to PRS.<br />
2. From the File menu select New > Category.<br />
3. In the Name field enter New Account Opening Reports and click Finish.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 127
<strong>Designing</strong> the New Account Applications report<br />
4. Right-click the New Account Opening Reports category and select New > Simple Report.<br />
5. In the Name field enter New Account Applications and click Finish. The report design canvas<br />
appears.<br />
6. On the Palette, click the Process report entity category. A list of report entities displays.<br />
7. Click and drag the Process Execution report entity to the canvas and select the following fields:<br />
• Duration (hh:mm:ss)<br />
• Finished Date and Time<br />
• Process<br />
• Process Instance ID<br />
• Start Date and Time<br />
128 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
8. Right-click the Process Execution report entity and select Filter. The Filter dialog opens.<br />
9. Click the Processes (PRO) tab and open the Processes filter item.<br />
10. Double-click New Account Applications. The filter expression is displayed in the Filter<br />
Expression field.<br />
Note: It is important that a filter be designed so that other monitored <strong>processes</strong> are not included in<br />
this report. Later in this appendix you will learn to create a series of other mock <strong>processes</strong> that<br />
are used to help design business data reports. It is important that these mock <strong>processes</strong> be filtered<br />
out of the New Account Applications report.<br />
11. Click OK. The Filter dialog closes and you are brought back to the report design canvas.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 129
<strong>Designing</strong> the New Account Applications report<br />
12. Click the Refresh button in the Data Source Preview window. You should see a list of<br />
process instances.<br />
Note: If you don’t see a list of the process instances you started in TaskSpace, then check the<br />
Process Properties dialog in Process Builder to make sure the Audit Trail is turned on.<br />
130 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
13. Click the Chart Data tab to establish the order of the columns as they appear in the table. In this<br />
example:<br />
a. Select Process in Column-1.<br />
b. Select Start Date and Time in Column-2.<br />
c. Select Finished Date and Time in Column-3.<br />
d. Select Duration (hh:mm:ss) in Column-4.<br />
e. Select none in Column-5.<br />
14. Click the Drilldown row in Column-1 and click the browse button (...). The Drilldown dialog<br />
opens.<br />
15. Click the Dashboard Event radio button and select Process Instance from the list box.<br />
16. Click OK to close the Drilldown dialog.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 131
Design dashboard and add dashlets<br />
17. State list box and then save the report. Publishing the report makes it available to use in a<br />
dashboard.<br />
In the next section you will design a dashboard and add to it the New Account Applications report, the<br />
Alert List dashlet, and the Process Diagram dashlet.<br />
Design dashboard and add dashlets<br />
In this section you will design a dashboard in TaskSpace and add three dashlets: the New Account<br />
Applications report, the Alert List dashlet, and the Process Diagram dashlet. Later in this appendix you<br />
will design business data reports and also add them to this dashboard.<br />
The Alert List dashlet displays a list of <strong>processes</strong> or activities that have met or exceeded an alert<br />
threshold. Alerts are defined in PRS, with a data source and an alert expression that defines the<br />
threshold. Once an alert is triggered, its details are displayed in the Alert List dashlet including the<br />
alert status, severity, and start and stop times. Initially, the Alert List dashlet displays a list of all alerts<br />
in the system. However, when a user clicks a process instance in the New Account Applications report,<br />
the Alert List is automatically filtered to show only the alerts that were generated for the selected<br />
process instance. This document does not describe how to design alerts in PRS. It focuses on adding<br />
the dashlet in the event that alerting is important in your situation. For more information on how to<br />
design alerts in PRS, refer to the Business Activity Monitor Implementation Guide.<br />
The Process Diagram is another type of dashlet included with the BAM software. The diagram dashlet<br />
is designed to distinguish between those activities that are in-process and those that are completed.<br />
Activities annotated with a green check mark are completed, and activities annotated with a gear icon<br />
are in-process. By configuring the Process column of the New Account Applications report as a<br />
multi-drill-down, the Process Diagram dashlet displays the progress of the process selected in the New<br />
Account Applications report. This is tested when the dashboard is designed.<br />
It is assumed that you do not have a TaskSpace application to which you are adding a dashboard. If<br />
you already have a TaskSpace application then you can skip steps 3–5 and just add a dashboard<br />
to the TaskSpace application you already have.<br />
To design a dashboard and add dashlets:<br />
1. Log in to TaskSpace.<br />
132 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
2. Click the Configuration tab.<br />
3. Click the New Application button, in the Name field enter FinanceCorp and in the Label field<br />
enter Finance Corp.<br />
4. Click OK. This closes the Create Application window and opens the Confirmation window.<br />
Note the URL of the TaskSpace application and log in to the new application.<br />
5. Click the Configuration tab and select Dashboards from the menu.<br />
6. Click the Create button. The Create Dashboard Configuration window opens.<br />
7. In the Name field enter NewAccountApplications and in the Label field enter New Account<br />
Applications.<br />
8. Click Next. The dashboard design canvas opens.<br />
9. Expand Report Categories > New Account Opening Reports.<br />
10. Click and drag the New Account Applications report to the canvas.<br />
11. Click and drag the Alert List dashlet and place it under the New Account Applications report.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 133
Design dashboard and add dashlets<br />
12. Click and drag the Process Diagram dashlet and place it under the Alert List dashlet.<br />
13. To test that the multi-drill-down between the New Account Applications report and the Process<br />
Diagram dashlet works, click any of the New Account Applications hyperlinks. The Process<br />
Diagram dashlet displays an image of the process you selected, and indicates those activities<br />
that are complete, incomplete, and in-process.<br />
14. Click Save and then click Finish. You are brought back to the Dashboards window. You will add<br />
more dashlets to the dashboard at the end of this document.<br />
134 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
Process Duration alert<br />
This section focuses on the design of a process duration alert that triggers whenever in-flight New<br />
Account Applications <strong>processes</strong> exceed one minute in duration. Alerts are comprised of a data source<br />
and an alert expression. Since the goal of this alert is to identify those in-flight <strong>processes</strong> that exceed<br />
one minute, the Incomplete Process Execution entity is used in the data source. If, however, the<br />
purpose of an alert was to list completed <strong>processes</strong> that exceeded the threshold, then the Process<br />
Execution entity would be used in the data source. The alert expression defines the duration threshold<br />
(in minutes) and constrains the alert to the New Account Applications process only. The one minute<br />
threshold allows you to see the alert populated in the dashboard two minutes after the process is started<br />
(the system considers 1.9 minutes within the first minute). At the moment an alert is triggered the<br />
details are displayed in the Alert List dashlet in the dashboard you created.<br />
Note: Alerts cannot be triggered on <strong>processes</strong> started prior to the design and publishing of an alert.<br />
Historical process data can be used to test that an alert expression is valid, but the alert details<br />
are not displayed in a dashboard. Alerts are constrained to those <strong>processes</strong> that are started after the<br />
alert is defined.<br />
In this procedure you create an alert category, design and test an alert, and start a process so the<br />
alert is triggered and displayed in the dashboard.<br />
To design a Process Duration alert:<br />
1. Log in to PRS.<br />
2. Click the Alerts tab.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 135
Process Duration alert<br />
3. From the File menu select New > Category. The New Category dialog appears.<br />
4. In the New Category Name field enter New Account Applications and click Finish. The New<br />
Category dialog closes and the category is displayed on the tree menu.<br />
5. On the tree menu, click the New Account Applications category.<br />
6. From the File menu select New > Alert. The New Alert dialog appears.<br />
7. In the New Alert name field enter Process Duration Alert and click Finish. The New Alert<br />
dialog closes and the alert design canvas opens. Your next step is to define the alert data source.<br />
8. On the Palette, click Process.<br />
9. Click and drag the Incomplete Process Execution entity to the design canvas.<br />
10. Deselect the Ongoing Duration (seconds) field.<br />
11. Select the Ongoing Duration (minutes) field.<br />
12. Click the Alert tab that is located next to the DataSource tab.<br />
136 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
13. From the State list box select Published. This makes the alert operational in the dashboard<br />
once the alert expression is defined and saved.<br />
14. Place your cursor in the Expression field and press the Ctrl-space keys simultaneously. A list of<br />
fields that can be used in an alert expression is displayed.<br />
15. Double-click ${Ongoing Duration (minutes)}. The ${Ongoing Duration (minutes)} field is<br />
added to the alert expression.<br />
16. On the keypad, click the greater than symbol (>) and then enter 1.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 137
Process Duration alert<br />
17. On the keypad, click the && button. You are defining a compound expression that limits the alert<br />
to those New Account Applications <strong>processes</strong> that exceed 1 minute.<br />
18. Press the Ctrl-space keys simultaneously.<br />
19. Double-click ${Process} and then click the = = button on the keypad.<br />
20. Enter "New Account Applications" (including the quotation marks) after the equals symbol (= =).<br />
Note: You do not need to configure the email.<br />
21. To test the alert expression, click the Refresh button in the Data Source Preview window and<br />
click OK on the Confirm Save dialog. Processes displayed in bold have exceeded the threshold.<br />
In the following steps, you start a new process instance so that the alert displays in the dashboard.<br />
22. Within TaskSpace, click the Processes tab and start the New Account Applications process and<br />
wait a few minutes.<br />
138 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
23. Click the Configuration tab and on the tree menu select Dashboards.<br />
24. Click the New Account Applications dashboard and click Edit.<br />
25. Click Next on the Modify Dashboard Configuration window. The dashboard design canvas opens.<br />
26. Within the New Account Applications report, locate the New Account Applications process you<br />
started in Step #22 and click it. The Alerts List dashlet displays the duration alert triggered for<br />
that specific process.<br />
New Account Process - Average Duration<br />
The New Account Process report is a dial gauge that displays the average duration of the New Account<br />
Applications process. In a real deployment, dial gauges measure average process duration over some<br />
specified period of time. A prototype of this report relies on creating a process in Process Builder that<br />
consists of two steps, a manual activity and an automated activity. An SDT is also created which<br />
includes a single attribute: Value. The SDT is assigned to the manual activity, and as the process<br />
executes a user can enter an average duration value. The needle on the dial gauge points to the average<br />
duration value. If you enter a duration value greater than 100, then you may need to adjust the range<br />
properties of the report in the Chart Properties window in PRS.<br />
The following topics include procedures for designing, running, and reporting on the New Accounts<br />
Process - Average Duration.<br />
<strong>Designing</strong> the New Account Process - Average<br />
Duration process<br />
1. Create the following process in Process Builder. The first activity is manual. It submits the SDT<br />
data. The second activity is automated and is used to end the workflow.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 139
<strong>Designing</strong> the New Account Process - Average Duration process<br />
2. From the File menu select New > Structured Data Type. The Add Structured Data Type Wizard<br />
dialog appears.<br />
3. In the Name field enter AverageDuration and in the Display Name field enter Average Duration.<br />
4. Select the Update BAM Database tables based on this SDT definition checkbox.<br />
5. Click the Add Attributes button .<br />
6. In the Name field enter Value. In the Display Name field enter Value. As the process runs this field<br />
is populated with the average duration it takes to complete the New Account Applications process.<br />
7. In the Type list box select INT.<br />
8. Select both the Searchable and Reportable checkboxes.<br />
9. Click OK.<br />
140 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
10. Select Tools > Process Properties to open the Process Properties dialog.<br />
11. Click the Data tab.<br />
12. Highlight Process Variable and then click the Add new process data button .<br />
13. From the Type list box, select . The Choose Structured Data Type dialog appears.<br />
14. Select Average Duration and click OK. You are brought back to the Process Properties dialog.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 141
<strong>Designing</strong> the New Account Process - Average Duration process<br />
15. Click the General tab.<br />
16. Turn the Audit Trail On.<br />
17. Click OK. The Process Properties window closes.<br />
18. For the manual activity, open the Activity Inspector window.<br />
19. Select the Data tab.<br />
20. Select the process variable and then select the This variable can be used to generate reports<br />
checkbox.<br />
142 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
21. Click OK. The Activity Inspector window closes.<br />
22. Open the Activity Inspector for the automated activity.<br />
23. Click the Performer tab and select dm_noop_auto_method as the method.<br />
24. Click OK to close the Activity Inspector dialog.<br />
25. Save, validate, and install the process. Enter AverageDurationReport as the name of the process.<br />
Running the Average Duration process<br />
1. Log in to TaskSpace and click the Processes tab.<br />
2. Locate and select the AverageDurationReport process and click the Start Process button.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 143
Running the Average Duration process<br />
3. Click Finish. You do not need to add a workflow description.<br />
4. Click the Tasks tab.<br />
5. Locate Activity-1 and double-click it.<br />
6. Click the Process Variables tab.<br />
7. Enter a number in the Value field. It can be any number you want. It is meant to represent<br />
average duration.<br />
8. Click Finish and then click OK. You are now ready to design a report that uses the average<br />
duration value you just entered.<br />
144 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
<strong>Designing</strong> the Average Duration report<br />
1. Log in to PRS.<br />
2. Right-click the New Account Opening Reports category and select New > Simple Report. The<br />
New Simple Report dialog opens.<br />
3. In the Name field, enter New Account Process - Average Duration and click Finish.<br />
4. From the Palette, select the Business Data report entity category.<br />
5. Click and drag the AverageDuration report entity to the canvas. By default the Value field<br />
is selected.<br />
6. Click the Refresh button in the Data Source Preview window. The value you entered during<br />
the process displays.<br />
7. Click the Chart Type tab.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 145
<strong>Designing</strong> the Average Duration report<br />
8. In the Type property, select Gauge from the list box.<br />
The report format adjusts to become a dial gauge with the arrow pointing to the value you entered<br />
during the process.<br />
Note: You may need to adjust the range values in the Chart Properties window.<br />
9. To adjust the range values, click the Chart Properties tab.<br />
10. Select a range property and enter a new value. The properties you can modify include the dial<br />
lower and upper limits, Range-1 (From/To), Range-2 (From/To), and Range-3 (From/To).<br />
11. To enter a title (or subtitle) select the appropriate property and enter a title. The title displays<br />
above the dial gauge.<br />
12. Select Published in the State list box and then save the report. Publishing the report makes<br />
it available to use in a dashboard.<br />
146 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
New Accounts by Customer Type<br />
New Accounts by Customer Type is a pie chart that is configured as the target in a single drill-down<br />
report configuration. When a user selects any of the bars in the New Accounts Opened This Week<br />
report, the New Accounts by Customer Type report displays. The first step is to create a mock process<br />
in Process Builder that consists of a manual and automated activity. An SDT captures information<br />
about the number of accounts for each account type (i.e. Gold, Platinum, or Silver). This process<br />
must be executed three times.<br />
The following topics include procedures for designing, running, and reporting on the New Accounts<br />
by Customer Type process.<br />
<strong>Designing</strong> the New Account by Customer Type<br />
process<br />
1. Create a process in Process Builder. The first activity is manual. It submits the SDT data. The<br />
second activity is automated and is used to end the workflow.<br />
2. Create an SDT and in the Name field enter CustomerType and in the Display Name field enter<br />
Customer Type.<br />
3. Add two attributes to the SDT. In the Name field of the first attribute enter AccountType.<br />
4. In the Display Name field enter Account Type. As the process runs you will populate this field<br />
with either Gold, Platinum, or Silver.<br />
5. In the Type list box select String.<br />
6. Select both the Searchable and Reportable checkboxes.<br />
7. Select the Update BAM Database tables based on this SDT definition checkbox.<br />
8. Create a second attribute.<br />
a. In the Name field enter AccountTypeAmount.<br />
b. In the Display Name field enter Account Type Amount.<br />
c. In the Type list box select INT.<br />
d. Select both the Searchable and Reportable checkboxes.<br />
9. Click OK.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 147
<strong>Designing</strong> the New Account by Customer Type process<br />
10. Select Tools > Process Properties to open the Process Properties dialog.<br />
11. Click the Data tab.<br />
12. Highlight Process Variable and then click the Add new process data button.<br />
13. From the Type list box select Customer Type.<br />
14. Click the General tab.<br />
15. Turn the Audit Trail On.<br />
16. Click OK. The Process Properties window closes.<br />
17. For the manual activity, open the Activity Inspector window.<br />
18. Select the Data tab.<br />
19. Select the process variable and then select the This variable can be used to generate reports<br />
checkbox.<br />
20. Click OK. The Activity Inspector window closes.<br />
21. Open the Activity Inspector for the automated activity.<br />
22. Click the Performer tab and select dm_noop_auto_method as the method.<br />
23. Click OK to close the Activity Inspector dialog.<br />
148 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
24. Save, validate, and install the process. Enter New Account Customer Type as the name of<br />
the process.<br />
Running the New Accounts by Customer Type<br />
process<br />
1. Log in to TaskSpace.<br />
2. Click the Processes tab.<br />
3. Locate and select the New Account Customer Type process and click the Start Process button.<br />
4. Click Finish on the Start Workflow: Info window. You do not need to add a description.<br />
5. Click the Tasks tab.<br />
6. Locate Activity-1 and double-click it.<br />
7. Click the Process Variables tab.<br />
8. In the AccountType field enter Gold. In the AccountTypeAmount field enter 100.<br />
9. Click the Finish button and then click OK on the Finish window.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 149
<strong>Designing</strong> the New Accounts by Customer Type report<br />
10. Repeat steps 2–9 twice and enter the following data:<br />
AccountType<br />
Platinum 30<br />
Silver 1000<br />
AccountTypeAmount<br />
After you have completed three <strong>processes</strong>, you are ready to design the New Accounts by Customer<br />
Type report.<br />
<strong>Designing</strong> the New Accounts by Customer Type<br />
report<br />
1. Log in to PRS.<br />
2. Right-click the New Account Opening Reports category and select New > Simple Report. The<br />
New Simple Report dialog opens.<br />
3. In the Name field enter New Accounts by Customer Type and click Finish.<br />
4. From the Palette select the Business Data report entity category.<br />
5. Place the CustomerType report entity on the canvas. By default the AccountType and<br />
AccountTypeAmount fields are selected.<br />
6. Click the Refresh button in the Data Source Preview window. The values you entered during<br />
the process display.<br />
150 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
7. Click the Chart Type tab and in the Type property select Pie.<br />
8. Click the Chart Data tab.<br />
9. In the Category (X) axis property select AccountType and in the Value (Y) axis property select<br />
AccountTypeAmount.<br />
Note: It is possible that the category and value properties are correctly configured by default,<br />
which means that the pie chart displays correctly and you do not have to do anything.<br />
10. Select Published in the State list box and then save the report. Publishing the report makes<br />
it available for use in a dashboard.<br />
New Accounts Opened This Week<br />
New Accounts Opened This Week is a bar chart report that provides the number of new accounts<br />
opened during the week for each of five counties. As with the other reports, a mock process consisting<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 151
<strong>Designing</strong> the New Accounts Opened this Week process<br />
of a manual activity and automated activity is designed. An SDT captures information about the<br />
number of accounts for each of five countries. This process must be executed five times. The country<br />
column in the data source is configured as a single drill-down, so that when a bar is selected in<br />
the report, the contents of the New Accounts by Customer Type report displays. This drill-down<br />
relationship is tested once you complete the dashboard.<br />
These topics include procedures for designing, running, and reporting on the New Accounts Opened<br />
This Week process.<br />
<strong>Designing</strong> the New Accounts Opened this Week<br />
process<br />
1. Create a process in Process Builder. The first activity is manual. It submits the SDT data. The<br />
second activity is automated and is used to end the workflow.<br />
2. Create an SDT and in the Name field enter AccountsThisWeek. In the Display Name field<br />
enter Accounts This Week.<br />
3. Add two attributes to the SDT. In the Name field of the first attribute enter Country.<br />
4. In the Display Name field enter Country. As the process runs you will populate this field with<br />
five different countries.<br />
5. In the Type list box select String.<br />
6. Select the Searchable, Reportable and Update BAM Database tables based on this SDT<br />
definition checkboxes.<br />
7. Create a second attribute.<br />
a. In the Name field enter NewAccounts.<br />
b. In the Display Name field enter New Accounts.<br />
c. In the Type list box select INT.<br />
d. Select both the Searchable and Reportable checkboxes.<br />
8. Click OK.<br />
152 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
9. Select Tools > Process Properties to open the Process Properties dialog.<br />
10. Click the Data tab.<br />
11. Highlight Process Variable and then click the Add new process data button.<br />
12. From the Type list box select Accounts This Week and then click the General tab.<br />
13. Turn the Audit Trail On and click OK. The Process Properties window closes.<br />
14. For the manual activity, open the Activity Inspector window and select the Data tab.<br />
15. Select the process variable (Var0), select the This variable can be used to generate reports<br />
checkbox, and click OK. The Activity Inspector window closes.<br />
16. Open the Activity Inspector for the automated activity and click the Performer tab.<br />
17. Select dm_noop_auto_method as the method and click OK to close the Activity Inspector dialog.<br />
18. Save, validate, and install the process. Enter Accounts This Week as the name of the process.<br />
Running the New Accounts Opened this Week<br />
process<br />
1. Log in to TaskSpace.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 153
<strong>Designing</strong> the New Accounts Opened this Week report<br />
2. Click the Processes tab.<br />
3. Locate and select the Accounts This Week process and click the Start Process button.<br />
4. Click Finish on the Start Workflow: Info window. You do not need to add a description.<br />
5. Click the Tasks tab, locate Activity-1, and double-click it.<br />
6. Click the Process Variables tab and in the Country field enter Belgium. In the NewAccounts<br />
field enter 100.<br />
7. Click the Finish button and then click OK on the Finish window.<br />
8. Repeat steps 2–7 four times and enter the following data:<br />
Country<br />
Germany 1200<br />
France 1000<br />
Denmark 600<br />
Czech Republic 1130<br />
NewAccounts<br />
After you have completed five <strong>processes</strong>, you are ready to design the New Accounts Opened this<br />
Week report.<br />
<strong>Designing</strong> the New Accounts Opened this Week<br />
report<br />
1. Log in to PRS.<br />
2. Right-click the New Account Opening Reports category and select New > Simple Report. The<br />
New Simple Report dialog opens.<br />
3. In the Name field enter New Accounts this Week and click Finish.<br />
4. From the Palette select the Business Data report entity category and place the AccountsThisWeek<br />
report entity on the canvas. By default the Country and NewAccounts fields are selected.<br />
5. Click the Refresh button in the Data Source Preview window. The values you entered during<br />
the process display.<br />
154 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
6. Click the Chart Type tab and in the Type property select Bar.<br />
7. Click the Chart Data tab and in the Category (X) axis property select Country and in the Value<br />
(Y) axis property select NewAccounts.<br />
Note: It is possible that the category and value properties are correctly configured by default.<br />
8. Select the Drilldown property and click the browse button (...). The Drilldown dialog opens.<br />
9. Click the Report radio button and then click the Browse button. The Select Target Report dialog<br />
opens.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 155
<strong>Designing</strong> the New Accounts Opened this Week report<br />
10. Select the New Accounts by Customer Type report and click OK. The Select Target Report dialog<br />
closes.<br />
11. Click OK to close the Drilldown window.<br />
12. Select Published in the State list box and then save the report. Publishing the report makes<br />
it available for use in a dashboard.<br />
156 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
New Accounts Opened Last Week<br />
This report shows the number of new account applications submitted each day during the last week. It<br />
provides a trend over time. There is also a horizontal line in the report that represents a SLA value that<br />
represents the target number of applications to be received each day. In this scenario the SLA (defined<br />
as 4500 applications) was missed on Wednesday when only 3000 applications were received. The<br />
report displays five ordered pairs of data values: (Monday, 5000), (Tuesday, 4000), and so on. This<br />
data is populated by a process and an SDT that contains a Date and Amount attribute. A third attribute<br />
called Order is used for sorting purposes, so that the days of the week appear in order on the report.<br />
These topics include procedures for designing, running, and reporting on the New Accounts Opened<br />
Last Week process.<br />
<strong>Designing</strong> the New Accounts Opened Last<br />
Week process<br />
1. Create a process in Process Builder. The first activity is manual. It submits the SDT data. The<br />
second activity is automated and is used to end the workflow.<br />
2. Create an SDT with the name AccountsLastWeek and the display name Accounts Last Week.<br />
3. Add three attributes to this SDT. In the Name field of the first attribute enter Date and in the<br />
Display Name field enter Date. As the process runs five times, you will populate this field with<br />
one of five different days of the week.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 157
<strong>Designing</strong> the New Accounts Opened Last Week process<br />
4. In the Type list box select String.<br />
5. Select the Searchable, Reportable and Update BAM Database tables based on this SDT<br />
definition checkboxes.<br />
6. Create a second attribute.<br />
a. In the Name field enter Amount.<br />
b. In the Display Name field enter Amount.<br />
c. In the Type list box select INT.<br />
d. Select both the Searchable and Reportable checkboxes.<br />
7. Create a third attribute.<br />
a. In the Name field enter Order.<br />
b. In the Display Name field enter Order.<br />
c. In the Type list box select INT.<br />
d. Select both the Searchable and Reportable checkboxes.<br />
8. Click OK.<br />
9. Select Tools > Process Properties to open the Process Properties dialog.<br />
10. Click the Data tab.<br />
11. Highlight Process Variable and then click the Add new process data button.<br />
12. From the Type list box select Accounts Last Week and then click the General tab.<br />
13. Turn the Audit Trail On and click OK. The Process Properties window closes.<br />
14. For the manual activity, open the Activity Inspector window and select the Data tab.<br />
15. Select the process variable (Var0), select the This variable can be used to generate reports<br />
checkbox, and click OK. The Activity Inspector window closes.<br />
158 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
16. Open the Activity Inspector for the automated activity and click the Performer tab.<br />
17. Select dm_noop_auto_method as the method and click OK to close the Activity Inspector dialog.<br />
18. Save, validate, and install the process. Enter Accounts Last Week as the name of the process.<br />
Running the New Accounts Opened Last Week<br />
process<br />
1. Log in to TaskSpace.<br />
2. Click the Processes tab.<br />
3. Locate and select the Accounts Last Week process and click the Start Process button.<br />
4. Click Finish on the Start Workflow: Info window. You do not need to add a description.<br />
5. Click the Tasks tab, locate Activity-1, and double-click it.<br />
6. Click the Process Variables tab and in the Date field enter Monday. In the Amount field enter<br />
5000. In the Order field enter 1.<br />
7. Click the Finish button and then click OK on the Finish window.<br />
8. Repeat steps 2–7 four times and enter the following data:<br />
Date Amount Order<br />
Tuesday 4000 2<br />
Wednesday 3000 3<br />
Thursday 6000 4<br />
Friday 5000 5<br />
After you have completed five <strong>processes</strong>, you are ready to design the New Accounts Opened Last<br />
Week report.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 159
Completing the prototype dashboard<br />
Completing the prototype dashboard<br />
In this section, you will add the remaining reports to the prototype dashboard and test that the single<br />
drill-down report works.<br />
To complete the prototype dashboard:<br />
1. Launch TaskSpace and log in to the dashboard application you created earlier.<br />
2. Click the Configuration tab and then click Dashboards from the menu.<br />
3. Click the dashboard you created earlier and then click the Edit button.<br />
4. Click Next on the Modify Dashboard Configuration window. The dashboard design canvas opens.<br />
5. Select Report Categories > New Account Opening Reports.<br />
6. Click and drag the New Account Process - Average Duration report and place it next to the New<br />
Account Applications report. Adjust the size of the dashlets if necessary.<br />
7. Click and drag the New Accounts This Week report and place it next to the Alert List dashlet.<br />
Adjust the size of the dashlets if necessary.<br />
8. Click and drag the New Account Last Week report and place it next to the Process Diagram<br />
dashlet. Adjust the size of the dashlets when necessary.<br />
9. Test the single drill-down report by clicking any of the bars in the New Accounts This Week<br />
report. The New Accounts by Customer Type report displays, along with a trail of bread crumbs<br />
for navigating back to the source report.<br />
160 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Prototyping Business Activity Monitor dashboards<br />
10. Click Save and then click Finish. Your prototype dashboard is complete.<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 161
Index<br />
A<br />
activities<br />
count children, 45<br />
wait, 45<br />
adaptors, 75<br />
controls, 75<br />
types, 75<br />
uses, 75<br />
aggregation, 92<br />
application<br />
phases, 17<br />
planning, 18<br />
application servers<br />
settings, 100<br />
archiving<br />
application, 111<br />
attachments<br />
using, 66<br />
audit trail<br />
configuring, 58<br />
enabling, 58<br />
automated activities, 60<br />
automated system, advantages, 9<br />
automatic activities<br />
performance, 98<br />
B<br />
BAM<br />
Crystal reports, 91<br />
dashboard design, 90<br />
enabling packages reporting, 58<br />
enabling SDT monitoring, 58<br />
external database, 59<br />
process variables reporting, 58<br />
purging production environments, 92<br />
reporting, 58<br />
reporting requirements, 89<br />
simple reports, 91<br />
synchronizing BAM database, 59<br />
system requirements, 89<br />
BAM database<br />
synchronizing , 59<br />
BAM reporting<br />
configuring audit trail, 58<br />
enabling, 58<br />
Business Activity Monitor, 58<br />
See also BAM<br />
business process management products, 13<br />
business requirements, 19<br />
C<br />
choose one automatic performer<br />
process design, 59<br />
Composer<br />
deploying, 108<br />
process performers, 108<br />
process templates, 108<br />
using, 109<br />
conditional routing, 35<br />
configurable actions, 65<br />
attachments, 66<br />
guidelines, 87<br />
content server, 14<br />
settings, 101<br />
Crystal reports, 91<br />
custom object types, 42<br />
D<br />
dashboards<br />
design considerations, 90<br />
pre-configured, 93<br />
refresh intervals, 93<br />
data adaptors, 75<br />
data mapper, 37<br />
data mapping<br />
input context, 38<br />
multi-valued attributes, 41<br />
repeating attributes, 37<br />
XML support, 42<br />
data model<br />
description, 29<br />
permissions, 20<br />
planning, 29<br />
roles, 20<br />
database<br />
references, 108<br />
database server<br />
settings, 105<br />
deploying<br />
application, 107<br />
Composer version, 108<br />
steps, 107<br />
deployment, 107<br />
Composer version, 108<br />
deleting SDTs, 109<br />
migrating, 61<br />
overwriting existing process, 109<br />
planning, 28<br />
process templates, 108<br />
setting up, 20<br />
updating database references, 108<br />
upgrading, 61<br />
versioning process templates, 109<br />
DFC trace, 105<br />
disabling<br />
full-text indexing, 103<br />
document view, 70<br />
documents<br />
displaying inline, 70<br />
Documentum repository, 14<br />
Documentum xCP products, 14<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 163
Index<br />
E<br />
<strong>EMC</strong> products, 11<br />
enterprise content management platform, 14<br />
enterprise content management products, 13<br />
environment<br />
application server settings, 100<br />
content server settings, 101<br />
database server settings, 105<br />
environments<br />
purging , 92<br />
error messages, 74<br />
F<br />
folders<br />
displaying inline, 71<br />
form templates<br />
creating, 63<br />
forms<br />
electronic forms, 69<br />
performance, 98<br />
full-text events<br />
purging, 104<br />
full-text indexing<br />
disabling, 103<br />
I<br />
implementing<br />
TaskSpace, 85<br />
initiate process template, 69<br />
J<br />
JVM capacity, 100<br />
L<br />
logins<br />
performance, 100<br />
looping<br />
count children activity, 45<br />
defining, 42<br />
simple loop, 43<br />
wait activity, 45<br />
M<br />
manual archive<br />
Documentum, 112<br />
testing, 116<br />
troubleshooting, 118<br />
message correlation, 36<br />
migrating, 61<br />
monitoring<br />
enabling SDTs, 58<br />
O<br />
object types<br />
custom object types, 42<br />
P<br />
package attributes<br />
monitoring, 31<br />
SDTs<br />
using, 30<br />
using, 30<br />
packages, 29<br />
description, 30<br />
displaying inline, 72<br />
electronic forms, 69<br />
enabling reporting, 58<br />
performance, 98<br />
analyzing, 105<br />
automated workflow activities, 60<br />
automatic activities, 98<br />
configuration recommendations, 97<br />
impactors to, 98<br />
large configurations, 97<br />
logins, 100<br />
mandatory search attributes, 99<br />
medium configurations, 96<br />
preconditions, 99<br />
SDTs, 60<br />
search criteria, 98<br />
search forms, 98<br />
skill set matching, 100<br />
small configurations, 96<br />
system configuration, 96<br />
task lists, 99<br />
tuning, 105<br />
wildcard searches, 98<br />
permissions, 20<br />
process data, 29<br />
process debugger<br />
debugging custom methods, 56<br />
using, 55<br />
process design<br />
BAM, 57<br />
choose one automatic performer, 59<br />
process parameters, 29<br />
using, 31<br />
process performers, 108<br />
process templates<br />
Composer, 108<br />
versioning, 109<br />
process variables, 29<br />
enabling reporting, 58<br />
types, 29<br />
<strong>processes</strong><br />
activity names, 31<br />
child process, 50<br />
designing, 33<br />
designing activities, 33<br />
164 <strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Index<br />
designing activity triggers, 34<br />
initiate process template, 69<br />
making changes, 31<br />
mapping data, 37<br />
options for after a process starts, 69<br />
overwriting existing process, 109<br />
starting, 64<br />
starting using a search template, 64<br />
starting using an attachment, 66<br />
starting using configurable actions, 65<br />
sub-<strong>processes</strong>, 36<br />
using a form in a package, 69<br />
versioning, 61<br />
wait activities, 34<br />
<strong>processes</strong> tab, 64<br />
project plan, 19<br />
prototyping, 21<br />
purging<br />
development production, 92<br />
full-text events, 104<br />
R<br />
reporting<br />
configuring audit trail , 58<br />
configuring audit trail settings, 58<br />
Crystal reports, 91<br />
data in an external database, 59<br />
enabling, 58<br />
packages, 58<br />
process variables, 58<br />
simple reports, 91<br />
reporting requirements<br />
BAM, 89<br />
reports<br />
drill-down, 93<br />
formatting, 93<br />
roles, 20<br />
S<br />
SDTs<br />
accessing attributes, 61<br />
deleting, 109<br />
description, 29<br />
enabling monitoring, 58<br />
monitoring, 31<br />
performance, 60<br />
search forms<br />
criteria, 98<br />
mandatory search attributes, 99<br />
performance, 98<br />
wildcard searches, 98<br />
search template<br />
using, 64<br />
service-oriented architecture, 14<br />
simple reports, 91<br />
skill set matching<br />
performance, 100<br />
structured data types, 29<br />
See also SDTs<br />
system configuration<br />
guidelines, 96<br />
large configurations, 97<br />
medium configurations, 96<br />
recommendations, 97<br />
small configurations, 96<br />
system design, 20<br />
T<br />
task lists<br />
performance, 99<br />
task templates<br />
displaying multiple packages, 72<br />
document view, 70<br />
folder view, 71<br />
using, 86<br />
task view<br />
designing, 70<br />
tasks<br />
sending to temporary group, 34<br />
TaskSpace<br />
adding buttons to a task form, 86<br />
assigning current object actions to<br />
menus, 87<br />
current object actions, 87<br />
finish buttons failing on a task form, 86<br />
implementing, 85<br />
iterative rollout, 85<br />
metadata pane in a folder view, 86<br />
preconditions, 99<br />
selected object actions, 87<br />
task lists, 99<br />
tomcat server<br />
settings, 100<br />
U<br />
upgrading, 61<br />
user interface<br />
design tips, 63<br />
form templates, 63<br />
search templates, 64<br />
V<br />
versioning<br />
process templates, 109<br />
<strong>processes</strong>, 61<br />
W<br />
workflow<br />
automated activities, 60<br />
<strong>EMC</strong> Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide 165