XCP 1.6 BestPracticesGuide

EMC Documentum
xCelerated Composition
Platform
Version 1.6
Best Practices Guide
EMC Corporation
Corporate Headquarters:
Hopkinton, MA 017489103
15084351000
www.EMC.com
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without
notice.
The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with
respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a
particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software
license.
For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used
herein are the property of their respective owners.
Copyright 2011 EMC Corporation. All rights reserved.
Table of Contents
Chapter 1
Overview ..........................................................................................................9
Introduction........................................................................................................9
Advantages of using an automated system ..........................................................9
Recommended approach to solution construction...............................................10
An example: a Grants Management application .................................................10
Technology Considerations ............................................................................... 11
Chapter 2
Product Overview...........................................................................................13
Documentum products......................................................................................13
Documentum ECM platform ..............................................................................14
Service-oriented architecture .........................................................................14
Content management and repository services.................................................14
Business process management.........................................................................14
Chapter 3
Planning and Designing the Application ........................................................17

Planning and designing the application overview ................................................17
Project preparation ...........................................................................................18
Business requirements phase ...........................................................................19
Interpreting the intentions of the client ............................................................19
Customization...............................................................................................20
Roles and permissions .....................................................................................20
Setting up the Development Environment ..........................................................20
System Design and Prototyping Phase ..............................................................20
Prototyping and Workshops ...........................................................................21
Planning the Deployment ..................................................................................28
Design Review .................................................................................................28
Chapter 4
Creating the Data Model .................................................................................29

Understanding the data model...........................................................................29
Understanding process variables ...................................................................29
Understanding packages ...............................................................................30
Package attributes versus SDTs.....................................................................30
Understanding process parameters................................................................31
Changing process elements...........................................................................31
Selecting SDTs and package attributes for monitoring.........................................31
Chapter 5
Designing the Process ...................................................................................33

Designing the process overview ........................................................................33
EMC Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide
Table of Contents
Designing activities...........................................................................................33
Defining activity triggers ................................................................................34
Creating wait activities...................................................................................34
Sending tasks to a temporary set of users ......................................................34
Designing processes ........................................................................................35
Creating complex conditional routing with a decision split ................................35
Using sub-processes.....................................................................................36
Understanding message correlation ...............................................................36
Using the data mapper .....................................................................................37
Mapping repeating attributes..........................................................................37
Setting the context for repeating attributes ......................................................38
Adding multi-valued attributes ........................................................................41
XML and other data formats...........................................................................42
Setting custom object types for attachments ...................................................42
Looping ...........................................................................................................42
Inter-process communication ............................................................................50
Using the process debugger .............................................................................55
Debugging custom methods with the process debugger ..................................56
Process design and Business Activity Monitor (BAM)..........................................57
Enabling reporting for BAM............................................................................58
Reporting on data in an external database to BAM ..........................................59
Process design and performance ......................................................................59
Choose one automatic performer ...................................................................59
Performance and stability of executing automated workflow activities ...............60
Large SDTs and performance ........................................................................60
Deployment considerations ...............................................................................60
Migrating or upgrading Process Builder ..........................................................61
Process versioning........................................................................................61
Accessing structured data types from a custom application .................................61
Chapter 6
Creating the User Interface.............................................................................63

Creating form templates in Forms Builder ..........................................................63
General tips for user interface design .............................................................63
Multiple ways to start a process .....................................................................64
Options for when a process starts ..................................................................69
Options to design a task view ........................................................................70
Process and form template version links.........................................................73
Custom error messages ................................................................................74
Data adaptors ...............................................................................................75
Using one data source adaptor to populate multiple fields................................77
Performance.................................................................................................84
Implementing TaskSpace applications ...............................................................85
Iterative rollout of a TaskSpace application .....................................................85
Working with task templates ..........................................................................86
Setting the height of the metadata pane in a folder view ..................................86
Working with configurable actions ..................................................................87
Chapter 7
Monitoring Business Activity .........................................................................89

System requirements........................................................................................89
Reporting requirements ....................................................................................89
Dashboard design considerations......................................................................90
Crystal Reports versus Simple Reports..............................................................91
Table of Contents
Cleaning production environments.....................................................................92

Custom aggregation .........................................................................................92
Leveraging the Preconfigured Dashboards.........................................................93
Dashboard refresh intervals ..............................................................................93
Designing drill-down reports ..............................................................................93
Formatting reports to be more readable .............................................................93
Computed Column dates and sorting .................................................................94
Chapter 8
Performance and Scalability...........................................................................95

General approach to performance .....................................................................95
System configuration guidelines ........................................................................96
Small configurations......................................................................................96
Medium configurations ..................................................................................96
Large configurations......................................................................................97
Configuration best practices...........................................................................97
Factors that affect performance and scalability ...................................................98
Automatic activities .......................................................................................98
Search forms ................................................................................................98
Task lists ......................................................................................................99
Preconditions................................................................................................99
Skill-set matching........................................................................................ 100
Logins ........................................................................................................ 100
Recommended application server settings ....................................................... 100
Recommended Content Server settings........................................................... 101
Disabling full-text indexing ........................................................................... 103
Purging existing full-text events.................................................................... 104
Recommended database server settings ......................................................... 105
Tuning and troubleshooting performance problems........................................... 105
Chapter 9
Deploying the Application ............................................................................ 107

Deploying the application overview .................................................................. 107
The deployment process................................................................................. 107
Deployment best practices .............................................................................. 108
Chapter 10
Archiving the Application............................................................................. 111

Manually Archiving TaskSpace Applications ..................................................... 111
Best practices before and after archiving ...................................................... 111
Archiving in Documentum releases 6.6 and higher ........................................ 112
Testing the Archived Application................................................................... 116
Troubleshooting the Archived Application ..................................................... 118
Appendix A
Prototyping Business Activity Monitor dashboards..................................... 121
Preface
This guide is intended to help EMC partners and practitioners use the Documentum xCelerated
Composition Platform (xCP) products to build repeatable business solutions. It focuses on the
best practices for using these products by covering topics such as planning, implementation,
performance, and deployment.
This guide addresses process-based applications and makes recommendations on how to integrate
these products to produce an end-to-end solution. These processed-based applications can be broken
down into a series of steps, in which an individual or software system performs each step. Examples
of process-based applications are ordering a book over the Internet, applying for a checking account,
placing a trip reservation, making an insurance claim, and applying for a loan.
Note:
This guide should be used in addition to, and not a replacement for, the user guides that come
with the individual products. This guide also assumes that you are familiar with xCP products.
We refer to the recommendations in this guide as best practices. However, most of the
recommendations are really good practices that work under most conditions. Each client is
different in both goals and environment, and not all recommendations work in all situations.
As you design a solution, consider the trade-offs between usability, performance, and time to
market, and make an assessment based on that information. For example, this guide provides
several suggestions on improving performance, these suggestions could be relaxed for small
implementations with just a handful of users. You may determine that it is best to deviate from
some of these best practices based on your trade-off analysis.
Intended Audience
The audience for this guide is the project team that is creating business solutions. In particular,
the primary audience includes Application Development Managers, Partner Project Architects,
and Project Managers.
Revision History
The following changes have been made to this document.
Revision Date
Description
April 2011
Initial publication
August 2011
BAM topic updated: Crystal Reports versus Simple Reports.

Archiving the Application section added.
Preface
Chapter 1
Overview
This chapter discusses the following:
Introduction
Advantages of using an automated system
Recommended approach to solution construction
An example: a Grants Management application
Technology Considerations
Introduction
Business processes occur in many contexts: government, law, health-care, insurance, retail,
telecommunications, and other domains. A process orchestrates a combination of human and
automated activities that produce and deliver information. This information can be in the form of
structured data or unstructured content, and the process must be able to manage both types easily and
seamlessly. During the course of the process, users add documents and enter business data. The
process uses this information to route the process to the correct people. The people working in the
process use this process information to make the correct decisions.
One example of process-based solution is case management. The case launches one or more processes
to perform its work. The best practices described in this document apply to both case management
solutions and to process-based applications in general. See the xCelerated Composition Platform (xCP)
Grants Management Sample Application and its documentation (xCelerated Composition Platform
Grants Management Sample Application Technical Reference Guide) for an in-depth discussion of
case management concepts and practices.
Advantages of using an automated system

Using an automated system to manage a business process improves efficiency and effectiveness and
provides better service to the client. Using an automated system provides these benefits:
Eliminates the need for time-consuming and error-prone paper-based systems to compile and
manage process data
Improves processing time by eliminating the need to locate and physically transport information
stored in file cabinets
Enables ongoing monitoring and control of the process through a real-time dashboard
Allows process participants to interact, giving their inputs and participating in discussion threads
Overview
Provides security and information rights management to keep personal information secure
Uses a secure repository to meet government requirements for secure records management
Recommended approach to solution

construction
The approach to solution construction that is being recommended in this document is based on the
configuration of pre-built templates and components. This represents a significant departure from
the conventional approach of writing custom code. This is important to the business stakeholders
for these reasons:
Cost - Programming resources, such as Java programmers, are expensive. Any solution that
minimizes custom development also reduces cost.
Risk - Working from components and design patterns that have been proven in many client solutions
minimizes technical risk.
Adaptability - Solutions constructed through configuration are much easier to modify as needs
evolve.
Time to market - The time required to design, implement, and debug custom code is significant.
Configuration of reusable components is dramatically faster than custom coding.
An example: a Grants Management application

The following scenario describes the process of applying for grant funding. This process is divided
into a series of activities.
1. A grant applicant fills out a grant application form and submits it by email.
2. The grantor agency receives the application, which initiates the grants management process.
3. An automated activity performs a quick validation of the application and assigns a priority level
to it.
4. The grants management process automatically sends a notification of receipt to the grant applicant
and creates a case folder. This folder contains all information related to the case, including the
application data, supporting documents, emails about the case, and so on.
5. A Grants Manager receives a task to work on the grant application.
6. If the Grants Manager does not think the documents supplied by the grant applicant are sufficient,
the Grants Manager can ask for additional supporting documentation.
7. The Grants Manager selects a team of experts to review the application.
8. The Grants Reviewers can add comments to informal discussion groups. After the reviewers
make a final determination, they recommend to approve or deny the application and provide a
justification for their recommendation.
9. The Grants Manager makes a final decision based on the recommendations from the Grants
Reviewers. The system automatically sends an email notification to the grants applicant advising
the applicant whether the request for funding was approved or denied.
10
Overview
This scenario is an example of a case management application. It triggers several processes to

manage the progress of the grant application. You can apply the best practices in this guide to all
process-based applications.
Technology Considerations
Process-based applications blend the human element with the software system element. The human
element is the part that calls for making judgment calls and decisions. The software systems that
manage the information and the process support these decisions.
The solution is based on three technology foundations:
Business Process Management - to define and orchestrate the series of activities to be performed
Enterprise Content Management - to manage documents, images, and associated metadata
Collaboration - to provide the ability for involved parties to interact, share information, and make
joint decisions
In addition, the following EMC products provide vital services to a process-based application solution:
Captiva: The product family for transforming business-critical paper, fax, and electronic data
sources into business-ready content suitable for processing by enterprise applications.
Process Builder: Allows for the creation of process templates. A process template captures the
definition of a business process, enabling users to perform the process repeatedly.
Forms Builder: An interactive tool used to create and modify form-based templates and store them
in a repository. Forms Builder enables users to design user interface templates for searching, viewing
documents and folders, process initiation, task lists, tasks, and basic forms within Documentum xCP.
Process Engine/Process Integrator: The server components that orchestrate processes and
integrate with external systems and data.
TaskSpace: The easy to configure user interface that can be used for task processing and document
retrieval in the business process. TaskSpace offers integrated document viewing with annotations
and enables the management of work queues. TaskSpace is the user interface for the application.
Business Activity Monitor (BAM): Provides a performance dashboard for monitoring and
analyzing process-based applications. In real time, BAM tracks defined key performance indicators
(KPIs), reporting on process performance and providing alerts for conditions that fall outside of
designated thresholds. With BAM, the manager can assess the overall performance level of the
application and focus on problems in a specific case.
Records Management: Provides the means to ensure compliance with legal and regulatory
requirements. The agency can set rules for retention policies to preserve case files for a specified
time. The process automatically triggers this capability.
Documentum Collaborative Services: Enables teams to work securely and collaboratively within
web applications.
11
Overview
12
Chapter 2
Product Overview
Documentum products
Documentum ECM platform
Business process management
Documentum products
The Documentum enterprise content management (ECM) and business process management (BPM)
products provide a single platform with a complete, fully integrated set of technologies that interact to
build comprehensive business solutions.
The following figure illustrates the core Documentum ECM and BPM products as they are typically
deployed to support business solutions:
Figure 1
Documentum ECM and BPM products
13
Product Overview
Documentum ECM platform

The Documentum ECM platform provides a unified environment for capturing, storing, accessing,
organizing, controlling, retrieving, delivering, and archiving any type of unstructured information
across an extended enterprise. With support for Web 2.0 information requirements and high-volume
transaction and archive environments, the Documentum content management platform can support
global enterprise deployments.
Based on an extensible, open, scalable, secure, and service-oriented architecture, Documentum
comprises a set of integrated products and services that work together to provide comprehensive
content-enabled solutions.
Service-oriented architecture
Service-oriented architecture (SOA) looks at IT assets as service components, establishing a software
architectural approach to building business applications. The SOA approach is based on creating
standalone, task-specific reusable software components that function and are made available as
services.
Content management and repository services

The Documentum Content Server and Repository manage information and content with
enterprise-grade security, scalability, and reliability, and a common set of policies for all content assets
across an organization. Additionally, the Documentum Repository manages the application definition
artifacts, configurations, and supporting models.
Business process management

Documentum xCP provides business process management capabilities and integrates fully with the
ECM platform. Using a model-driven approach, combined with services orchestration capabilities,
Documentum xCP provides the ability to configure applications without coding requirements. xCP
also provides a complete range of tools for process and task modeling, data and content modeling,
presentation modeling, and business-logic modeling. Changes to business solutions can be made
declaratively in the appropriate model, without writing or modifying software code, providing a flexible
and agile framework for building as well as maintaining and improving business solutions over time.
The service-oriented architecture also allows for easy integration with existing line of business systems,
applications, and external systems to gain additional value and leverage from those investments. As a
composition platform, xCP provides reusable components, model-based configuration, a configurable
user interface and dashboard tools, and reference applications to enable developers and IT architects to
compose and maintain applications using graphical tools.
Documentum xCP includes the following capabilities and products:
14
Product Overview
Application
presentation and
composition
Documentum TaskSpace provides a highly configurable user interface

that unites process, content, and monitoring into a single user experience
for transactional business applications. TaskSpace is deployed as a web
application into a Java Application server.
Business process
design and workflow
configuration
Process Builder is a business process design tool that allows

non-programmers to configure how services, manual activities, and
information are combined and orchestrated to accomplish specific business
actions and logic. Process Builder allows the designer to configure
process activities such as simple manual tasks, high-volume work
queues, automated content management actions, and sophisticated system
integration logic through easy-to-use visual design techniques. In addition,
Process Builder supports the defining of process rules, priorities, and
exception handling. Deployment of standard activity templates enables
enterprises to maximize both productivity and standardization through
reuse across multiple applications. The process models defined by
Process Builder are deployed into Documentum repositories through the
Documentum Content Server. The runtime execution of the process models
is carried out by the Process Engine.
Application GUI
design
Forms Builder is used to create web-based graphical user interfaces

available through TaskSpace. Forms Builder also serves as the design tool
for producing high-fidelity, paper-like electronic forms for data capture and
presentation. Forms Builder produces XForms models that are stored in
the Documentum Repository. At runtime, web-based user interfaces are
generated by an embedded forms engine that interprets the XForms models
and produces HTML. The forms engine deploys as part of TaskSpace in
the same web application.
Reports
Documentum Business Activity Monitor (BAM) and Process Reporting

Services (PRS) provide detailed reporting and monitoring of solutions.
BAM deploys in two parts, as a server-side engine (BAM Server) and
as a TaskSpace component. The BAM Server continuously formats and
aggregates events and data as the application runs. This engine deploys into
any Java application server. The BAM TaskSpace component deploys
as part of TaskSpace and generates the graphical dashboards that contain
the reports around the data and events managed by the BAM Server.
BAM typically uses a separate database from the Documentum Repository
for managing its reporting data, although in some cases, it can share
the same database instance using different tablespaces. The BAM data
definitions (including both structured data types and content metadata)
are synchronized by Process Builder through the BAM Server. PRS is a
reports builder tool that enables users to configure graphical reports against
the data in the BAM database. The reports are presented in the TaskSpace
dashboards.
Team collaboration
Documentum Collaborative Services (DCS) provide team collaboration

around artifacts and information. DCS is a set of services and objects
supporting team collaboration exposed in the TaskSpace application
environment. The primary capability includes ad-hoc discussion threads
available on any item in TaskSpace.
15
Product Overview
Process automation,
services orchestration,
human task
management
The Documentum Process Engine carries out the automation of all business
processes defined by Process Builder in the applications. Process Engine
deploys into the embedded JBoss application server that is provided as part
of the Documentum Server. Certain aspects of the Process Engine also
execute in the Documentum Content Server, specifically process runtime
state management, which uses the Documentum Repository for state
persistence.
Data and content

integration
Process Integrator manages both inbound and outbound integration of data

and content for the applications and provides mapping and transformation
capabilities for both data and content integration. The integration
configuration, including connector end-point definition and correlation
mapping, is carried out with Process Builder. Process Integrator deploys
its outbound integration services, data/content mapping, and correlation
capabilities in the embedded JBoss application server. Inbound protocol
connectors can be deployed into any Java application server, including the
embedded JBoss application server.
The following products are optionally available and provide additional integrated capabilities to
Documentum xCP:
Compliance
Retention Policy Services and Records Manager automate the entire content
lifecycle to mitigate risk of non-compliance and leverage full audit control
for retention policy management and records management.
Information capture
and input
Captiva InputAccel provides intelligent capture for paper, fax, and

electronic data sources
Dynamic
correspondence
generation
Document Sciences xPression automatically generates and distributes

customer communications via customer-preferred formats and channels
(e-mail, web, print, and mobile).
16
Chapter 3
Planning and Designing the Application
Planning and designing the application overview
Project preparation
Business requirements phase
Roles and permissions
Setting up the Development Environment
System Design and Prototyping Phase
Planning the Deployment
Design Review
Planning and designing the application

overview
Case management projects, like other xCP applications, are created in a series of phases. The following
diagram illustrates a typical phase structure:
Thorough planning and testing is important for process-based applications and can make a difference
in whether a project succeeds or fails. What makes this possible is the extensive use of templates for
creating processes, forms, reports, and user interfaces. Anticipating risks, aligning on requirements,
and designing the solution carefully are critical to success.
Another best practice recommendation is to use an agile methodology. Break up the full application
into smaller modules and establish frequent cycles of design, implementation, and testing, as illustrated
in the above diagram. This approach is considered a more successful alternative to the classic waterfall
approach.
17
The goal of the xCP platform is to enable solution construction with little or no custom coding. Use
templates to create processes, forms, and user interface screens. For planning, xCP applications can
require more time dedicated to requirements gathering and solution prototyping.
This chapter addresses business requirements, solution design, and prototyping. It offers suggestions
for planning and designing solutions that are directly relevant to EMC products.
Project preparation
To prepare the project, do the following:
Read the documentation

Define project roles
Take training
Create a project plan
Read the documentation

The delivery team must understand the intended purposes of EMC products. Members of the project
team must read and understand the product documentation. The best place to start is with the EMC
Documentum xCelerated Composition Platform Sample Application Tutorial. The tutorial takes the
reader through the development of a simple process-based application and describes how to create
reports and a BAM dashboard. In addition, each product ships with documentation that introduces
and explains the product functions and provides guidance on how to use them correctly. Reading the
documentation helps to avoid misunderstandings, plan your project, and save development time.
Define project roles

The following is a list of key roles that are needed in a process-based project. (This is not a complete
list of roles.)
EMC Project Manager

Client Project Manager, to assist with internal project coordination
Business Users, to define and clarify functional requirements
Information Architect, responsible for creating the data model
Process Architect, responsible for designing the process in Process Builder
User Interface Architect, responsible for designing Forms and TaskSpace screens
BAM Architect, responsible for designing the reports and dashboard
Client System Administrator, Network Administrator, and Information Security, and Database
Administrator (DBA) to support the implementation and enable account creation
A single person or several people can play these roles, depending on the size and staffing of the project.
The architects must work closely together to ensure consistency of approach.
Take Training
Training is important for project architects to understand the product architecture and current features
of EMC Documentum products. Training can be carried out in formal training classes, in targeted
meetings with engineering, or in EMC MyLearn web-based classes.
18
Create a Project Plan

Create a Project Plan to outline the basic set of tasks required to implement a solution. This plan can
assume an out-of-the-box solution without any customization. If customization becomes necessary,
add it to the project plan as a separate module. For each customization module, the project manager
can estimate the impact on cost and schedule.
Include a Project Roadmap in the Project Plan that lays out the major phases of the project in the form
of a flow diagram and specifies the inputs and outputs of each phase. The inputs are templates that
define the minimum information that must be gathered to perform the phase. Include information or
participation needed from the client. The outputs are the deliverables produced by the phase. Negotiate
the level of participation by the client with the project sponsor in the planning phase.
Business requirements phase

Request that the client provide the following information for the Business Requirements phase:
Current technical environment

High-level business requirements
Numbers and roles of system users
Estimated transaction volumes
Descriptions of ingestion mechanisms (such as email, scanners, and EDI) and equipment used to
capture the data
Samples of the content that the system will ingest
Relationships between data and user roles (required to define security roles)
Existing business process diagrams
The project team can prepare templates for this data so that the client clearly understands, in advance
of the engagement, what is needed and how to gather and format the information. Design these
templates so that the delivery team can use the information to configure the system.
Negotiate the project roadmap with the project sponsor. Consider a solution that takes into account
both the needs of the client and the capabilities of the product. Both views are critical for success.
Interpreting the intentions of the client

An engagement often begins when the client provides functional specifications. Think of the functional
specifications as a starting point for the design discussion. If you follow the requirements too literally,
you run the risk of not being able to use EMC products as they are intended to be used. This can lead
to expensive customization, which can lead to support issues and an unsatisfied client.
Translate the functional requirements into business requirements. Ask questions so that you can
reveal the requirements behind the requirements. For example, a specification might state that the
system should limit a users ability to work on multiple cases. If the requirement does not look right,
it probably is not right. A business requirement can often be implemented in different ways. For
example, calculate sales tax is a business requirement. One functional requirement can state that the
system must populate a database lookup table with date, item type, and the tax to be charged. Or,
the business requirement could be met by a second, alternative functional requirement. Articulate to
19
the client the ways in which xCP addresses these alternatives. Define the client requirements clearly
before implementing xCP projects.
Customization
Try to avoid customization. Following client specifications exactly can require costly and
time-consuming customization. It is more efficient to work within the functionality of the tools.
Customization prolongs the time to solution and creates a challenge with future upgrades. xCP
projects are high volume. If there are numerous customizations, the upgrade process can be risky and
expensive. The client may need to rebuild each application customization from scratch, driving up
the total cost of ownership and increases risk. There may be some cases when you need to write
custom code, but keep it to the absolute minimum.
Roles and permissions

During the planning stage of your project, identify the roles of the performers involved in the process.
For each role, identify the permissions that each performer must have to access the data required to
complete assigned tasks. Include permissions for data that is read-only and for data that the performer
enters or modifies.
Configure permissions as follows:
Give the user who will be starting workflow instances RELATE permissions and START
PROCEDURE extended permissions.
Set the access control list (ACL) of the process variables to allow performers to edit the process
variables in a manual task.
Set the ACL of the package object to allow performers to read or edit the package fields based on
the business requirements.
Setting up the Development Environment

We recommend using WMware images to manage the development environment. This approach
offers several advantages. It allows the delivery team the ability to control its own infrastructure,
which is preferable to relying on the client to manage the development environment for the team. It
can also speed up the delivery cycle and facilitate the testing cycle by providing a clean environment
for validating the solution. Eliminating the peculiarities and idiosyncrasies of a client environment
saves time.
System Design and Prototyping Phase

In the design phase, identify detailed requirements and create the design for:
Process Definition
Task Processing User Interface
BAM Reporting
20
The Data Model
Do not think of these areas as being independent from one another. For example, requirements for
BAM reports can suggest data fields to incorporate into the data model. In turn, these fields will be
entered into forms by task processors (or captured in automated activities). One corollary of this
observation is that the user interface architect must communicate frequently with the information
architect to ensure consistency and completeness.
The delivery team must understand the interdependence of the Process Definition, UI, BAM, and Data
Model so they can properly advise the client. Ideally, the project team creates templates to facilitate the
clients understanding of the interdependencies. If the client wants to change the model, then the client
understands the corresponding impact on cost. This also helps the client to understand the importance
of the information the client provides to the delivery team.
The guiding principle of this phase is Iterative Design. This means that a solution cannot be designed
in a single step, but you need a series of workshops to reveal the design. It is not a linear path and
the design can change several times, which is relatively easy to do in the planning phase. After the
data model is finalized and development begins, fundamental changes can be disruptive. For example,
changing the field definitions in the data model causes forms to break (since forms link to data through
xpath). Complete the data model in the design phase and then lock it down.
Prototyping and Workshops

Dedicate one-quarter to one-third of the project to functional prototyping and client workshops. It is
easy to prototype and make changes in designs within xCP during the prototyping stage. Do not move
into the development phase in your project until the design is stable.
Combine prototyping with workshops in which you present the design to the client and solicit
feedback. These workshops should have a consistent structure and format. Use a set of predefined
templates to present the information and collect feedback. These workshops can ensure that the design
meets the true needs of the client and that the client understands and agrees to the solution. Initially,
these workshops can be done in a storyboard manner using a whiteboard with hand-drawn screens. As
you progress in the design, conduct the workshops using real screens in TaskSpace or BAM.
At the beginning of the project, it is important to convince the project sponsor to make client resources
available for workshops. Negotiating this agreement ensures that clients take the time from their
schedule to meet with you, understand the design, and provide input.
Example: Process Builder

Articulate that the application is based on a process. Sometimes clients have a Visio diagram that
shows the process exactly as they want it. Other times, the desired process is not well defined. In the
latter case, map the process first at the business level; that is, the process shows only the activities that
are significant in a business sense, dispensing with technical steps like process data mapping. One tool
that is useful for this purpose is the Process Analyzer. In a series of interviews with the client business
users, the process can be defined to the appropriate level of detail. This process can take a few days to
complete, assuming that you have access to the subject matter experts. The following is a swim-lane
process diagram in Process Analyzer depicting the hand-offs between two roles in a process.
21
After the client business team agrees with the structure and flow of the process, it can be transferred to
Process Builder to add the technical detail. As you refine the process in Process Builder, continue
to review the process flow with the client. One effective way to review the process flow is to use
the Process Debugger.
The Process Debugger allows you to execute the process one step at a time with real data. This can be
done even if the user interface has not yet been designed. This is an effective way to show the client,
while still in the design stage, how the process will work. In some cases, the client may be familiar
with how the process should work, while in other cases, the client may still be learning the process. In
general, the message is to use the Process Debugger early and use it often.
22
Example: TaskSpace
Creating the user interface is one of the biggest challenges in solution development. TaskSpace,
because it is composed of forms, provides flexibility in user interface design. The following is an
example of a TaskSpace screen showing a view of a case folder:
Work with the client to define a consistent approach to style. We recommend writing a Style Guide
that specifies standards for colors, skins, columns, labels, search criteria, sort order, and any items
pertaining to the UI. A detailed specification takes time to write, but it saves time during the
implementation phase of the project. Keep it simple and do not over-engineer.
Note: Design the Style Guide as a structured template to ensure that you are gathering the appropriate
information. Also use this template to show the client how things will be implemented and to track any
configuration changes. The result is to create a consistent look and feel for the application.
Example: BAM
With BAM, the first step in the planning is to identify the users; that is, the roles of the individuals who
need access to the dashboards. For example, one role can be the operational manager who watches
each case or process instance to ensure that it meets the Key Performance Indicators (KPIs) for
process timing and quality. Another role can be the Line of Business (LOB) executive who tracks
process performance against aggregate business goals. These two roles require different dashboards
that contain different reports.
Following is an example of a template for capturing this information:
23
Dashboard User Summary

Role 1: Operational Manager
Examples: Wayne Tyson, Shirley Rosen, and Roxanne Plaskow
Responsibility: Identify processes that violate Service Level Agreements and take immediate action.
Frequency of Access: Every 15 minutes
Role 2: Line of Business Executive
Examples: Henrietta van Kampen
Responsibility: Ensure that the process meets business metrics for revenue and quality.
Frequency of Access: Twice a day
The next step is to focus on each role and identify the report required. Write a reports summary
specification, which can be based on the following template:
01-RPT-07 - Revenue by Type (report number and name)
Report Purpose
Summarize why this report is needed.
Report Details
Report Type
Describe the structure, information contained in the report and any drill-down behavior.
Audience
The audience for this report includes:
Role 1
Role 2...
Frequency and Timing
How often will the data in this report be changed? How often should the report be refreshed?
Report Sample (mockup)
24
Filters
Describe filters that the user needs
Drilldowns
Is there a need to drill this report down? If so, on what field will the drill-down occur and what is the
drill-down report?
Avoid burdening the user with too much information in the dashboard. If more detail is needed,
then the report designer can create drilldowns.
For example, you have a process that is a new account opening. The executive user has requested
to see three things in the dashboard:
The number of new accounts that were opened in each country (this week)
The distribution of new accounts by customer type
The average time to complete the new accounts opening process
The first report is a bar chart, the second report is a pie chart, and the third report is a dial-gauge. In the
client workshops, the BAM architect can present the following reports to the client in rough form:
25
Figure 2
Number of new accounts by country
Figure 3
Number of new accounts by customer type
26
Figure 4
Average Process Duration (in hours)
These reports can be created in Excel, PowerPoint, or drawn by hand. The dashboard can be mocked
up by copying and pasting these reports.
The general approach is to do simple things first to ensure that everyone agrees on the report
prototypes. The report can be polished or enhanced at a later date. The goal is to confirm early and
27
then refine to avoid creating something that the client does not want. After the client is comfortable
with the rough dashboard prototype, progress to more polished reports that were created in Process
Reporting Services:
Over time, the number of reports will grow and drill-downs and multi-drill-downs will be defined. You
can create additional dashboard pages. Some reports can be moved from one page to another. This
process is the normal, iterative process of designing BAM dashboards.
Planning the Deployment

During the planning phase, make note of any aspects of the system that can change when the
application is transferred from the development environment to production. For example, databases
used by the application generally change when moving to the production environment. Users assigned
to specific activities can also be different in the production environment. It is important to compile a
complete inventory of these items to use during deployment.
Design Review
At the end of the design phase, the project manager can schedule a design review to validate the
design. This meeting can include architects and system experts who are not members of the solution
project in addition to EMC engineers to ensure the technical feasibility of the proposed solution. The
information gathered in the templates can be used as supporting materials to the solution design
presented to the client for signature. This process reinforces the design direction the team has taken
and justifies decisions made on the design. Following a successful design review with client sign-off,
the project can move into the implementation/development phase.
28
Chapter 4
Creating the Data Model
Understanding the data model
Selecting SDTs and package attributes for monitoring
Understanding the data model

The data model represents the data that is created or modified in a process. It is a key foundation for
the solution. A flawed data model leads to rework, which consumes valuable time. Therefore, the data
model must be established as early in the implementation phase as possible.
Process data refers to the different types of data that flow through the process. Process data consists of:
Packages, which capture metadata associated with Documentum objects such as documents
or folders.
Process variables, such as part numbers or customer addresses. Process variables can be simple
data types (like String or Int) or structured data types (SDTs).
Process parameters, which enable administrators to modify and control all instances of a given
workflow template.
Process data can be used in transition conditions (where the next activity executing is dependent on the
data values), conditional performers (in which the performer for a manual activity is selected based on
a data value), and in creating service-specific messages (for instance, the creation of a SOAP message
to invoke a web service). The process data model can contain transient data (modeled using process
variables) as well as persistent data (modeled as packages). Define your data model early in the
design process before you begin creating the process within Process Builder. Also consider the data
requirements of the entire application, including the process, forms, and user interface (TaskSpace).
Understanding process variables

Process variables can be simple or complex. Simple process variables are based on a single attribute,
such as String or Boolean. Complex process variables are based on an SDT, which is composed
of a hierarchy of attributes.
SDTs are composed of several attributes, organized in a hierarchical order. SDTs are used to group
logically related business data. These can be created in Process Builder by importing XML schemas or
by manually creating the type and then adding individual attributes to it. For example, elements of an
appropriation request can be organized into the group Request with the attributes submitter_name,
29
submitter_address, and equipment_type. Within each SDT, you can also organize attributes into related
groups that give visual structure to the data type. For example, within the customer SDT, you can
have an address group that contains the attributes for city and state.
SDT definitions are global and can be used by any process. An SDT used by an installed process
cannot be deleted nor should any of its attributes be modified or deleted. However, it is possible
to add new attributes to an SDT that is in use.
Process variables store transient data; that is, data that is not needed after the workflow terminates.
Typically, this data is fetched from a non-Documentum system of record (another database, for
example) or is used for an internal calculation. The Process Engine manages the lifecycle of a
process instantiating the process variables when the workflow is started and destroying them when the
workflow terminates.
Creating an SDT for each object in your workflow can help to simplify your data model. However,
you should organize your SDTs in a logical manner, corresponding to business entities. If you have
too many SDTs, you can end up with performance problems with the TaskSpace task list. If that
occurs, then you need to consolidate the SDTs.
Understanding packages
A package is associated with a Documentum object, such as documents or image files, which is
passed between activities in an executing process.
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
case folder. When documents are held in a case folder, you can attach the folder as a package, but
you may want to consider attaching other key documents as separate packages. This enables users to
act on the documents separately, so that you can perform operations such as conducting conditional
routing based on the package metadata itself.
Package data is persistent. However, package data is not shown in TaskSpace task lists or task forms.
To enable package attributes to appear in TaskSpace, you first map the attributes to process variables by
using a Process Data Mapping activity template. After you map these attributes to process variables,
you can base decisions on the package attributes, such as transitioning to the next activity. Conversely,
process variables are not persistent and must be mapped so that you can base decisions on the package
attributes, such as routing the process to the next activity back to package attributes if you want the
data to persist beyond the life of the process.
Package attributes versus SDTs

During the design phase, decide when you will be using packages and when you will be using process
variables. The decision is important and is a key part of successful design and implementation:
If the customer wants to store and search data in the task list template, use SDTs.
If the customer wants to persist data beyond the process instance, use package attributes.
If you want both, you must initially use SDTs and then map them to package attributes at the end
of the process.
Some additional considerations include:
30
To search on SDTs in the user interface, use a task list template for the search.
If you delete or change the name of an SDT after implementing it, you will break the data binding in
Forms Builder. You must delete the dangling control or rebind it to the renamed SDT.
SDTs are more lightweight than object attributes and are better for performance and scalability.
Understanding process parameters

Process parameters provide agility and control by allowing an application administrator to intervene,
overriding the normal process execution. Process parameter values provide administrators with a high
level of control over a process. Specifically, process parameters are used in place of fixed values within
a process such as escalation roles, transition conditions, performer conditions, dynamic performer
assignments, task name, and task instructions. Administrators can change process parameters
without uninstalling the process. When an administrator changes the values of the parameter from
the Administration tab in TaskSpace, the value is used in all process instances started after the
change is made.
Changing process elements

When you decide to alter a process, use caution as you make your changes. You can add elements to
the process, but avoid deleting process variables, Java methods, or structured data types. Create a data
field and use it in the process, but do not delete the old field. Just avoid using it. Deleting a process
variable or package from a process template can cause the process to become unstable.
If you must update process data in Process Builder, ensure that you update the process data in Forms
Builder, as well. Changing the name of a field in Process Builder invalidates the binding to the form
template. Open the templates in Forms Builder and save them to restore the binding. Any changes to
the data model (for example, adding a new SDT) require that you uninstall, save, and reinstall the
form templates and processes.
Changing activity names

When you change the name of an activity, it is equivalent to deleting it and creating an activity in its
place. All the associated information is logically deleted. Thus, it is a best practice not to change
activity names after the process has been deployed.
Selecting SDTs and package attributes for

monitoring
When you create an SDT you must mark it as reportable if you want to create BAM reports on this
data. You also have to choose the activities in which to collect this data. Even though it is technically
feasible to monitor every attribute of every SDT and package, do not do that. It is a best practice to
understand thoroughly your reporting requirements. For reports based on SDT/package attributes,
you must precisely identify which attributes to monitor and the location in the process this monitoring
31
should occur. You also have to choose the activities in which to collect this data. Consider the
following when determining which SDT and package attributes to monitor:
1. If an attributes value does not change from one activity to another, then only monitor the attribute
once rather than for each step in the process. If you monitor this attribute in several locations,
then you are capturing meaningless rows of data that are needlessly filling up the audit trail and
BAM database.
2. Do not collect process data unless you absolutely must and if you need process data only once, you
may want to collect it at the end of the process.
3. If attribute values change during a process and you want to monitor this change, then select to
monitor the attributes within the activities that generate the change. However, reports that rely on
business data aggregation may be inaccurate. For example, if the order is entered for three widgets
in Activity A but is later changed to nine widgets in Activity B, then the correct number is nine.
But if you record both numbers, then you will compute six as an average value, which is incorrect.
32
Chapter 5
Designing the Process
Designing the process overview
Designing activities
Designing processes
Using the data mapper
Looping
Waiting for invoked process instances to complete
Inter-process communication
Using the process debugger
Process design and Business Activity Monitor (BAM)
Process design and performance
Deployment considerations
Accessing structured data types from a custom application
Designing the process overview

Process Builder is the tool used to design and implement the process. It enables you to create the
process by dragging and dropping activity templates. See the Process Builder User Guide for details
on product features and functions. This chapter describes several best practices for designing the
process by using Process Builder.
Designing activities
Consider the following when designing activities:
Defining activity triggers, page 34
Creating wait activities, page 34
Sending tasks to a temporary set of users, page 34
33
Defining activity triggers

One of the most common mistakes when building a business process is to not define activity triggers
correctly. This means that the tasks in an activity may never be triggered.
When you define or change the flow of a process, it is a common mistake to leave an activity with the
default trigger setting of all input flows are selected. Always check that the Trigger tab of each activity
has been defined with the correct number of incoming activities before you install and run the process.
Creating wait activities

When a process must wait for a response, you can create an activity that pauses the process until the
response is received. To pause the process, create an activity that sends a task to an inbox that belongs
to a placeholder user such as dm_bps_inbound_user. Next, configure the post-timer to expire after
the time you need the process to wait, and have the activity complete the task automatically after the
post-timer expires. The process resumes after the system completes the activity.
To create a wait for activity:
1. Add a manual activity to the process.
2. Define dm_bps_inbound_user as the performer for the activity.
The system sends the task to the inbox of dm_bps_inbound_user rather than an actual users inbox.
3. In the Timer tab of the activity, define a post-timer to be triggered after the period of time that
you need the process to wait.
4. Configure the action of the post-timer to complete the workitem after the post-timer expires.
The system creates the task, sends it to the nonexistent user, but it is not completed until the
post-timer expires, thus causing the process to wait for a specified time.
Sending tasks to a temporary set of users

In case management applications, it is common to have a requirement in which you need to set up
a temporary set of users that need to perform a task. Within this temporary set of users, you would
specify one of the following options for performing the task:
1. Set a single user from the temporary group to perform the task. In this case, after the first user
selects this task, it disappears from everyone elses task list.
2. Set all users from the temporary group to perform the task. In this case, everyone must perform the
task.
To do this, create three sequential activities:
1. Activity A: You need an automated activity to create the ad hoc group. This requires writing some
custom Documentum Foundation Class (DFC) code. Your code should also add a set of users to
the group. Store the name of the group in a process variable.
2. Activity B: This activity takes the group name from the process variable and assigns the tasks. In
this activity you specify whether a single user from a group or all users from the group perform the
task.
34
3. Activity C: This activity performs the cleanup. It deletes the temporary group that you just created.
If you do not delete the temporary group, performance may suffer.
Designing processes
Consider the following when designing the process:
Creating complex conditional routing with a decision split, page 35
Using sub-processes, page 36
Understanding message correlation, page 36
Creating complex conditional routing with a decision

split
This section describes how to configure a complex type of routing, one that you can consider three
different routing options based on criteria. An example of a less complex decision split is if you have a
document that must be reviewed by a Vice President (VP). If it is a marketing document, then the VP
of Marketing must review and approve it. If it is an engineering document, then the VP of Engineering
must review and approve it. In this example, the process diagram looks like this:
However, you may have a requirement that is more complex. Similar to the previous example, you
may want the VP of Marketing to review marketing documents or the VP of Engineering to review
engineering documents, but what do you do with a document that is neither marketing or engineering?
In this example, a document that does not fall into one of those two categories must be reviewed and
approved by both VPs. This means that there are cases where only one task is triggered (going to one
of the VPs), whereas in other cases both tasks are triggered (going to both of the VPs).
To model this complex routing, you need to add a Join activity. Even though it is common to create
a Join after a decision split, this example uses the Join to consider the two out of three case. In this
example, the process diagram looks like this:
35
The transition conditions are expressed as:
The use of Join in the first two conditions ensures that each option leads to two activities being
selected. The trigger option at the Join activity looks like this:
Using sub-processes
Process Builder enables you to create in-line sub-processes. Using sub-processes can improve your
ability to communicate the structure and the business meaning of a process template. A large or
complicated process can become difficult to organize visually when there are many activities required
to complete an entire workflow. To simplify the layout of a process, group related activities into
sub-processes that collectively represent a business process.
In Process Builder, sub-processes can be expanded to view the individual activities or collapsed to
create a more simplified overview of a process. The process contains activities that are related in some
way and are grouped into a container for ease of administration. This can be useful when grouping a
set of activities that collectively represents a business function or a logical step in a process. Activities
that share the same process data can also be grouped into a sub-process.
It is also possible for one process to invoke another process. In this case the invoking process is called
the parent and the invoked process is called the child. If you want to build a process that invokes one
or more child processes, use the Invoke Process activity template. If you need the child process to post
events to the parent process, then use the Post Event to Parent Process.
Understanding message correlation

The basic idea of correlation is simple. Processes can send messages and receive messages from
external systems and services. A process instance can, for example, send a Java Message Service
(JMS) message (request) to an external system. This message is sent to the external system by the
Process Integrator. After sending the request message, the process instance enters a wait state. When
the external system completes the request, it sends its response message back to the Process Integrator.
However, there can be many process instances in flight at the same time, each waiting for a response
to its own request. Therefore, it is necessary to match the response to the correct requesting process
36
instance. To make this match, the request message has to include some data that uniquely identifies the
requesting process instance. This is called the correlation identifier. The response message coming
from the service also contains the same correlation identifier, so that when the Process Integrator
receives the incoming message, it reads the correlation identifier and then routes the message to the
right process instance.
There are two basic approaches to specify a correlation identifier:
Transport-based
Content-based
In the transport-based approach, the identifier is created as part of the protocol control field. For
example, a Java Message Service (JMS) message can generate a unique key that can be used to
identify the process instance.
In the content-based approach, the identifier is taken from the payload. For example, in a purchase
order application, the purchase order number is unique to each process instance. Therefore, it can be
used to match the response to the requesting process instance. In some situations you need to combine
multiple data fields to ensure uniqueness.
If a correlation identifier has not been configured for an activity or if it is missing from the incoming
message, the system looks for a correlation set to match the message to a workflow. Correlation
sets are specified at the process level in the Advanced tab of the Process Properties. They are used
to enable correlation in the activities of that process. You can use one or more process variables to
create a correlation set to uniquely identify the process instance.
Use the data mappers copy function to compare one of the attributes of your incoming data to the
value of one of your process variables belonging to a correlation set.
Note: The copy function is used to compare these values. If there is a match between the value of
the process variable (belonging to a correlation set) and the value of a data attribute of the incoming
message, the match is successful and the step activity is completed.
Using the data mapper

The data mapper is a graphical tool that simplifies the exchange of process data, such as workflow
method arguments, web services parameters, return values from database queries, and attributes
specific to services such as JMS, HTTP, or FTP. This section addresses several topics involving the use
of the data mapper that can arise in your projects.
Mapping repeating attributes

There are times that you need to copy a source variable to multiple target variables. This can be done
using the data mapper. You can also perform operations in the course of the mapping, for example,
mapping a date to a date and also mapping the date to a string variable (using the date-to-string
function) at the same time.
To copy one variable to many variables:
1. Create the copy function as usual for the first item.
37
2. Add a second copy function and click the destination variable.
3. Click the Line drawing mode button in the toolbar.

4. Place the cursor over the small handle in the source variable and click once.
5. Click the handle on the left side of the copy function to complete the mapping.
As you can see, Var 0 on the left, has been mapped to Var 0 and to Var 1 on the right.
Setting the context for repeating attributes

A multi-valued attribute can be mapped to a single-valued attribute or to another multi-valued attribute.
Depending on how you set the Input Context option, the mapping rule function is executed once
for each input value (the for-each case) or the mapping rule function is executed against the array
of attributes as a whole (the for-all case). You can view or update the Input Context option in the
function dialog box.
The following example clarifies this feature. In this example, on the input side (left-hand side) of the
mapping you have a repeating attribute IntArray, of type Int, with values [1, 2, 3, 4, 5]. The mapping
rule function is Add(IntArray, 1).
Case 1: (for-each). This performs the Add function for each individual value in IntArray, creating
a multi-valued attribute on the right-hand side. In this case the output on the right-hand side will
be [2, 3, 4, 5, 6].
Case 2: (for-all). This performs the Add function against IntArray as an argument, creating a
single-valued output. In this case the output on the right-hand side will be 16 = (1+2+3+4+5) + 1.
Here is an example to show the use of the for-each construction. In this example, you have a process
receiving emails with attachments but do not know the content type of the attachments. You just have
the attachment name, but you need to know the content type in order to store it in the repository. To
solve this problem, look at the file extension of each attachment and use it to set the object type. To
do this you iterate through the file names, getting the file name and the extension. The for-each
38
construct allows you to implement this loop. The split construct allows you to extract the file extension
for each attachment.
Here are the detailed steps of the implementation:
1. Select Split function in the Data mapper.
2. Double-click the Split function icon that shows up, and select the For Each radio button.
3. Map Email Attachment Name to Attachment Content file-extension.
The Activity Inspector screen appears as:
4. Double-click the Split function that is connecting the left-hand side to the right-hand side.
5. Click the plus sign (+) and add a period (.).
6. Click the plus sign (+) and add 1.
7. Use the up/down arrows to reorder them as follows:
39
The end result is:
40
In general, you can use this approach whenever you are working with repeating elements and you
wish to take action for each one of the elements.
Adding multi-valued attributes

When you are mapping repeating nodes, you want to retrieve all the values of the repeating node from
the left-hand side and then insert these values in the proper position on the right-hand side. To achieve
this, multi-valued attributes have an Add link next to their names. Use the Add link to create a node
that represents a specific index of multi-valued attributes.
To add a node with a new index value:
1. Click Add next to the attribute for which you want the system to create a node with a default
index value.
2. Double-click the new index value to launch the Repeating Index dialog box.
3. To change the index value, select FIRST, LAST, or type a numeric value for the index position.
FIRST creates the first index position for the attribute. This is generally more useful on the
Input Message Mapping side when mapping the first value of an attribute to another attribute on
the Output Message Mapping side.
LAST creates the attribute at the end of any other existing attributes. The input values are appended
after any other values. This ensures that mapped data does not overwrite any existing value.
41
To copy all values of a multi-valued attribute to a specific index of multi-valued indexes:

1. In the target tree, create a node representing the specific index of the multi-valued attribute.
2. Select the node representing all values (the index value for this node is ALL) in the source tree.
3. Select the node representing the single-attribute node in the source tree.
4. Launch the function dialog box by double-clicking on the function.
5. In the function dialog box, select FOR-EACH as the value for Input Context, and select
Over-Write, Insert Before, or Insert After as the value of Output Context.
When using the Insert After or Insert Before options, the values are inserted after or before the
index. When using the Overwrite option, the existing values are overwritten.
XML and other data formats

Since Extensible Markup language (XML) is the standard used to exchange structured data between
applications, the activity templates shipped with Process Builder support XML natively. Process
designers can associate an XML schema with a service-specific message and use the data mapper to
create an XML payload that can be sent to other applications. However, if the target application
uses another data format (like Comma Separated Value (CSV)), then associate a translator with the
message. At runtime, the Process Integrator uses a translator, if specified in data mapper, to convert the
XML document into the desired format. A translator is a custom Business Object Framework (BOF)
module that you write, for example, to convert a Comma Separated Variable (CSV) file to an XML
document. This is a standard feature of the data mapper.
Setting custom object types for attachments

In some applications, executing processes must receive email with attachments. The default object
type for an attachment is dm_document. However, you can also treat it as a custom object type by
using the data mapper for the Email Inbound activity template. In the data mapper, set the ObjectType
attribute in the Attachments node of the process data to any type that is valid for your repository.
Looping
Many applications must perform a series of activities several times in succession. Process Builder
enables you to define loops by using a counter mechanism. The following process shows how to set up
looping within a process. In the first activity, a human performer specifies a set of departments. Then,
an automated loop cycles through each department, invoking a process for each department.
42
To create a simple loop:

1. Create a manual activity called Define Departments in which the user defines the departments
for which a new process is started.
2. Create a Process Data Mapping activity called Setup Loop.
This activity gets the number of departments defined in the manual activity and assigns that
number to a counter.
3. Use another data mapping activity to decrement the CurrentCount by 1.

Use a Subtract function to subtract 1 from CurrentCount and map it back to the same variable. It is
valid to map the variable back to itself to get: CurrentCount = CurrentCount -1. This is necessary
43
because the index of a multi-valued attribute starts at zero, so if you have three values, the index
must decrement from 2 to 0, rather than 3 to 1.
4. Add an automatic activity as a decremental decision transition to begin the loop.
The activity executes a no (Begin Loop) operation (dm_noop_auto_method). The trigger is
configured to create a task when either of the two inputs is followed. Configure it to trigger
for 1 out of 2 possible input flows.
5. Next, include an Invoke Process activity template to map the data into the child process.
In the data mapper, use the Get Value function to set the value of the process variable department
on the new process instance.
6. Create a decision split activity called End Loop. In this activity, there is a transition condition that
returns to the loop if the counter is greater than zero. If the counter is zero, then it will exit. The
Cleanup activity (also a no op) is needed to connect to the end of the process.
44
Waiting for invoked process instances to

complete
In the looping example in the previous section, the Invoke Process activity started the child processes
asynchronously. The child processes can continue to execute even after the main process has finished.
However, you can apply logic to force the main process to wait until all the child process instances in
the loop complete. To illustrate this, create two activities: Wait and Count Children.
To add and configure a wait condition:

1. Create an activity named Wait.
2. In Process Builder, configure the performer for the Wait activity to dm_bps_inbound_user to
prevent a human user from picking up the task to do.
45
3. On the Timers tab, set a timeout interval for the Wait step.
In our example, we set the post timer to expire one minute after the task is created. (This is the
polling interval. We assume that the child processes are short and will complete within one minute.)
When the timer expires, the task will complete.
4. On the Trigger tab, set the trigger condition of the Wait activity to 1 out of 2 possible input flows,
since it can be triggered in two mutually exclusive ways.
46
After the timer expires and the task is completed, the process proceeds to the Count Children activity.
To add and configure the Count Children activity:
1. Add a Database Query Language (DQL) Read activity named Count Children.
The Count Children activity queries the number of child process instances invoked by the parent
process instance.
2. On the DQL Configuration tab, set up the Count Children activity to query the number of child
process instances invoked by the parent process instance.
The following illustrates the configuration:
47
48
3. On the Transition tab, configure which activity is next in the process and what the conditions are.
The following screenshot illustrates using a count function to count the number of r_object_ids
returned from the query, and we assign this number to the process variable runningChildrenCount.
When runningChildrenCount is equal to zero, the process proceeds to the Cleanup activity. When
runningChildrenCount is greater than zero, then there are still running instances of the child process
and the process returns to the Wait activity.
49
Inter-process communication
Process Builder includes an Invoke Process activity template that enables a parent process to invoke a
child process. An example of this is if you have an order process that must perform a credit check.
Instead of building the credit check procedure into the order process, create it as a separate process to
be invoked as a child process. You can manage the credit check process separately and independently,
and it can be called by other parent processes.
The Invoke Process activity template provides a basic mechanism to pass process data from the parent
process to the child process. By using the Post Event to Parent activity template, the child process
communicates to the parent process by posting events to the parent process instance. However, the
posted event is only a name that carries no payload to the parent. To pass a data payload from the
child to the parent, use the following approach:
In this example, the parent process invokes the child process in the third activity:
50
The Invoke Process activity passes a workflow correlation identifier to the child. The child process
needs this identifier to call the correct parent process instance. Map the correlation identifier of the
parent to the variable parentInstanceCorrId of the child, as illustrated:
After invoking the child process, the parent process instance waits for a response message with the
payload from the child in the HTTP Inbound - Step activity. The following shows the configuration
for the HTTP Inbound - Step activity:
51
In the HTTP Inbound - Step activity, the parent sets the Correlation Property Name to CorrId. When
the child process instance posts an HTTP request, the system looks for a workflow instance with a
correlation identifier that matches CorrId in the URL Parameter of the request.
When configuring the HTTP Inbound - Step activity, select With Attachments. The attachment carries
the payload from the child process to the parent process.
To enable the payload to pass from the child process to the parent process, map the HTTP attachment
data posted by the child to the attachment data field of the parent, as illustrated:
52
Next, look at the child process:
After the parent process invokes the child process, the child process carries out the request of the
parent. The child process then posts a response message back to the parent instance in the HTTP
Outbound activity. The parent process instance waits for the message with the payload from the child
and receives it in the HTTP Inbound - Step activity.
Configure the HTTP Outbound activity as illustrated:
53
For the child process instance to post the message to the correct parent process instance, it uses the
parentInstanceCorrId. The child process receives this identifier from the parent process when the
parent invoked the child. This variable is mapped to the URL parameter CorrId as illustrated:
54
Attachments pass from the child process instance to the parent process instance by mapping them to
the HTTP Request attachments.
This approach was based on HTTP Post. An alternate approach is to use JMS as the protocol for
inter-process communications. This approach is useful when the child process must pass data to the
parent process.
Using the process debugger

Process Builders debugger enables you to test the design of a process template interactively by setting
breakpoints, running through the process, examining and modifying process data, testing integrations,
and acquiring and acting upon tasks within a process.
Debugging a process before deploying it to a production environment helps to ensure that the process
flow you designed satisfies the original business requirements upon which you based your design.
Using the debugger to troubleshoot a process enables you to test a process from within the process
design environment without having to save, validate, or install the process. You can also test activities
as you develop them to ensure that you have configured a complex process flow correctly. Executing a
particular path within a flow can also give you important feedback during the development process.
You can use the debugger to walk through the invocation of a web service. You can visually inspect
the outgoing message, the returned response from the web service, the document metadata and process
variable values. Errors display immediately in the debugger console. Make sure to place a breakpoint
55
at or right after the service invocation step. As a recommended best practice, as you build up your
processes, particularly with web services integration activities, regularly test them with the debugger.
Use the debugger every time you change the process to ensure the integrity of data that may have
changed.
Debugging custom methods with the process

debugger
If you are using custom methods in your workflows, you can debug them using the process debugger.
To debug a custom method:
1. Launch Process Builder in debug mode.
2. Modify the shortcut to add debug options and enable debugging using the specified port.
For example:
-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n
The complete shortcut may look similar to the following:

C:\Program Files\Documentum\jreForPB\bin\java.exe"
-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n
-Xms128m -Xmx256m -Dswing.aatext=true -cp ".;lib\bpm.jar;..\..\dctm.jar;
C:\Documentum\config" WorkflowEditor -locale en_US
3. In your integrated development environment (IDE), add a new debug configuration to connect
the host and port.
56
4. Place breakpoints in your code, run this debug configuration from your IDE, and begin debugging
your process from Process Builder.
Whenever an activity that uses your custom method is reached, you can debug through your
custom method code.
Note: To make the method code available to the process debugger, it must be a Class that is
located in the appropriate directory structure or a JAR file located under \classes\custom folder in
the Process Builder installation directory.
Process design and Business Activity Monitor

(BAM)
BAM extracts information from executing processes, runs reports against this information, and
provides a dashboard for viewing the reports. Plan to specify the monitoring configuration as you
design your process in Process Builder. If you plan on using BAM, you must plan for:
Enabling reporting for BAM, page 58
Reporting on data in an external database to BAM, page 59
57
Enabling reporting for BAM

In Process Builder you specify the process execution data to be recorded in BAM, so that report
designers can create BAM reports based on this data.
Activating the Audit Trail

You must activate the audit trail for each process that you want BAM to monitor. Activating the audit
trail enables the BAM server to extract the reporting data and insert it into the BAM database.
In the Process Template Properties dialog box, select the General tab. In the Audit Trail Settings
group box, select the On option.
When auditing is on, audit trail information is saved for each workflow instance created from this
template.
Note: To change audit trail settings, you must have CONFIG_AUDIT privileges. CONFIG_AUDIT
is an extended user privilege and must be granted by another repository owner or superuser using
Documentum TaskSpace or Documentum Webtop. The Documentum Webtop User Guide and the
Documentum TaskSpace Configuration Guide provide more details on extending user privileges.
Enabling monitoring of structured data types

You must specify the activities in which you want to record process data to BAM. It is not necessary
(or desirable) to do this for every activity. Select the SDT attributes to include in reporting from
each activity.
Use the Add Structured Data Type Wizard to create structured data types. To record a data attribute in
the BAM database, select the Reportable checkbox in the wizard. Make sure to update the data type
definitions with BAM by selecting Update BAM Database tables based on this SDT definition.
This procedure creates the tables in the BAM database, which are used to report on business data.
Examples of such reports include total weekly revenue per branch office, average duration of claim
resolution by type, and number of new grants applications by state.
Selecting packages for reporting

Report data can come from packages as well as from SDTs. Select the packages to include in reporting
at the process level or in the individual activity. To enable Process Builder to publish reporting data
to the BAM database for the package, select This package can be used to generate reports in the
Process Properties dialog box or in the Data tab of the Activity Inspector. When you do this, all the
custom attributes of the object are available to the BAM database. Unlike the case with SDTs, you
cannot select individual attributes for reporting.
You must specify the activities in which you want to record process data to BAM. It is not necessary (or
desirable) to do this for every activity. Select the packages to include in reporting from each activity.
Selecting process variables for reporting

You must specify the activities in which you want to record process data to BAM. It is not necessary (or
desirable) to do this for every activity. Select the variables to include in reporting from each activity.
58
Process variables can be simple types (Boolean or string) or can be structured data types that were
selected for reporting when they were created. To expose this variable and use it to generate reports,
select the This variable can be used to generate reports checkbox in the Data tab of the activity.
Synchronizing with the BAM database

If you change the process data in a process, there is the danger that these changes are not reflected in
the BAM database structure. Ensure that any changes to the business data that you are monitoring have
been updated in the BAM database. The Update BAM Data Definitions page enables you to update
selected process data from Process Builder with the existing reporting data in the BAM database. This
ensures that there is consistency between the structure of the data in Process Builder and the structure
in BAM. This option updates the BAM process data with the process data that you select in the
Update BAM Data Definitions page.
Select Tools > Update BAM Data Definitions to use the Update BAM Data Definitions page.
Reporting on data in an external database to BAM

BAM reports on information in processes automated by the Process Engine. A common question is
how to report on data that is contained in an external database. The best way to do this is to create a
small process that makes this data available to BAM. You can configure a Database Read activity to
retrieve data from the database outside of Documentum and then mark the data elements for reporting.
This creates a simple process with one automatic activity that retrieves the specified data and sends
reporting information to BAM.
Note: Because Process Builder does not support a process with a single activity, you must add one
more dummy activity to the process. That activity is an automated activity in which the method
is dm_noop_auto_method.
Process design and performance

This section describes some practices that could improve performance.
Choose one automatic performer

To improve the performance of automatic activities in your process, make one user (or a small set
of users) the performer of all the automatic activities. For example, if you define a user, such as
auto_executor, and make that user the performer of all the automatic activities, the runtime execution
of these automatic activities increases considerably.
For security reasons, only a superuser can select a specific user as a performer for an automatic
activity in Process Builder.
59
Performance and stability of executing automated

workflow activities
The Process Engines multi-threaded workflow allows concurrent execution of automated workflow
activities. The workflow agent responds to Content Server notifications and can execute queries based
on a polling interval to claim work for its worker threads to execute.
There are only two ways the workflow worker threads can execute the work:
Notification: They get notified through shared memory inter-process communication (IPC).
Claim query: The workflow master runs the UPDATE query that claims available items for
working and then distributes the work to workers.
If the automated workflow activities are not executing on time or never at all, check for the following:
The claim query can take too long to execute.
This can occur when the number of worker threads is increased to a high number (for example, 100)
with the intent that more workers results in better performance. However, with this increase, the
UPDATE query executes as a nested loop in the underlying RDBMS, pinning the RDBMS CPU.
This dramatically increases the time that it takes to execute the claim query. Check the statspack for
top queries and if the UPDATE on dmi_workitem_s is taking a long time, then it is a confirmation
of the problem.
Content Server is configured for high availability.
With a Content Server high availability configuration, confirm that a unique dm_server_config
object is specified for each content server. If you have two workflow masters operating using the
same serverconfig object, then workflow automated activities execution can fail. To fix this problem,
ensure that each content server has a unique serverconfig object.
You are not using the no_op method from Process Builder 6.5 or later.
In Process Builder 6.5, the default DocBasic no_op method to run the automated activities
such as splits, joins, and data mappers was changed. If you are using an older version of
dm_noop_auto_method, switch to the newer version of dm_noop_auto_method_java.
Large SDTs and performance

Creating large SDTs or adding many SDTs to a process degrades performance in TaskSpace task
lists. Try to create SDTs based on logically related objects and consolidate attributes if it makes
sense within the process.
Deployment considerations
Migrating or upgrading Process Builder, page 61
Process versioning, page 61
60
Migrating or upgrading Process Builder

After upgrading to a newer version of Documentum Process Builder, delete the BOF cache as
well as the temp/work directory of the application server, and restart the application server. The
cache folder location is specified by the dfc.cache.dir key in the dfc.properties file. It is located in
$DOCUMENTUM/cache/<docbase_version>bof on the client machine by default. Clearing the bof
folder contents clears the BOF cache.
Note: The DFC cache folder also contains caches other than BOF. Do not delete these additional
cache folders.
Process versioning
Use versioning carefully and sparingly to avoid creating inconsistencies in the process data. It is best
to create versions when deploying a process to the production environment. This is because creating
different versions of a process can result in process data getting out of sync. Use versioning carefully
and only when the process is moved to a production environment.
During design, it is a best practice to use the process debugger frequently to troubleshoot and validate
the process without installing it. When the activities and the data model are defined and the debugger
is run without errors, then check the process into the repository. Install the process only when you
want to run it.
Note: It is not recommended to use Save As on a process multiple times and then install each of the
cloned processes. This practice can lead to instabilities at runtime.
Accessing structured data types from a custom

application
To gain access to the attributes of structured data types, you can use IDfWorkitemEx
and IDfWorkflowEx APIs. Details can be found in the Javadoc files located in Program
Files\Documentum\help\bpm\api.
Note: During the installation process, ensure you have selected the option to install the developer
documentation. This option installs the Javadocs on your local system.
61
62
Chapter 6
Creating the User Interface
Creating form templates in Forms Builder
Implementing TaskSpace applications
Creating form templates in Forms Builder

The form templates in Forms Builder are the basis for the user interface (UI) in TaskSpace and require
careful consideration.
This section provides general tips and information on the following:
How to create a well-designed user interface
Options to start a process from a template
Options for what appears when a process starts
Options to design a task view
Process and task template versioning
Custom error messages
How to use data adaptors
Performance considerations
General tips for user interface design

Consider creating a style guide for the user interface, in collaboration with the client.
Prepare a detailed design document and confer with the client to resolve all issues ahead of
time. Preparing a detailed design document in advance makes creating the form templates a
straightforward process.
Designing forms requires increased interaction with the client. The clients are the ones who will
be using the forms, so let them see the forms often during the design phase and solicit as much
input as possible.
The UI must be as intuitive as possible, with a common look and feel across all form templates.
Make a prototype and get it fully functional to help ensure that the UI design is as user-friendly as
possible and that the client approves of the design before doing the actual development. Keep in
63
mind that the size and complexity of the prototype is not necessarily indicative of the development
effort. The development time will be greater due to coding complexity and customization. You also
cannot necessarily predict performance issues from the prototype.
Consider how many task templates you need. You may want to make one template for each step or
activity in the process, and they should all have a common look. This also improves performance.
When initially designing templates, keep in mind that it can sometimes be easier and quicker to
delete a template and start over again.
Sometimes what the client wants is not a good design. For example, even though you can search on
20 attributes does not mean that you should.
Try to design forms so there is no scrolling for the end user. This may mean using more tabs in
TaskSpace.
After creating a template with the template wizard, if you start changing and adding controls and
moving items around on the canvas, especially if you use drag and drop, frequently verify how things
look on the Preview pane. When using drag and drop, items can appear to line up using the vertical
bar, but the spacing and padding appear differently on the Design pane than on the Preview pane or
at runtime. To ensure correct alignment, especially for labels, use the settings on the Style tab.
Multiple ways to start a process

This section describes the different ways in which you can start a process. You can:
Use the processes tab, page 64
Use a search template, page 64
Use a configurable action, page 65
Use a configurable action with an attachment, page 66
When a process starts, there are three possible options: an initiate process form appears, a package
form appears, or a standard WDK component appears (which does not use a form). Options for what
appears when a process starts are described in Options for when a process starts, page 69.
Use the processes tab

The most straightforward way to start a process is to go to the Processes tab. You can select one of the
processes that are listed there and click Start Process.
Use a search template

You can use a search template that is configured to search on processes in a specific folder. This is
useful if you want to filter the list of processes that a user sees.
On a search tab in TaskSpace, you select a process from the search results set and then select Start
from the context menu.
64
Figure 5
Start a process from a search
Use a configurable action

To make things simpler and avoid selecting from a list of processes, you can start a specific process
using a configurable action on a custom tab:
1. Create a configurable action to start a process.
2. Select the specific process to start.
3. Add the action to a custom tab.
65
Figure 6
Start a process with a configurable action
Use a configurable action with an attachment

If you first receive a document and then want to start a process with the document as an attachment,
you can start a specific process with an attachment using a configurable action:
1. Create a configurable action to start a process with a selected object.
66
2. Configure how the object is routed by selecting Dynamic Object Value Selection.
3. Select Objects to be routed.
67
4. Select the specific process.
68
5. Start the process from a search by selecting a document and then clicking the configured action
button. The process starts with the selected document added as an attachment.
Options for when a process starts

When a process starts, there are also options for what appears next. You can show an initiate process
template or you can show an electronic form in a package. A third option, calling a standard WDK
component, does not use a form and is therefore not described here.
Use an initiate process template

The standard option when a process starts is to open an initiate process template. Each template is
associated with a specific process and you can show process variables and use a package control to
allow users to upload or select an existing document to be the package content. You can also further
customize the template by adding additional controls.
Use an electronic form in a package

If you want a specific form as a package in the process, which appears when the process starts, you can
use an electronic form in a package:
1. Create an electronic form and specify it with a Start Activity.
2. Open the Activity Inspector for the Start Activity in Process Builder, specify the electronic form
with a package, and select to automatically launch the package.
69
Figure 7
Start a process using a form in a package
3. At runtime, when the process starts, the configured electronic form in the package appears
automatically. This is useful if you need to fill out a specific form for the associated process.
4. When the user submits the form, if any of the mandatory packages are not fulfilled, the user is
prompted to fulfill the mandatory packages.
Options to design a task view

The basic way to design a task view is to use the task template creation wizard to create a task view
by selecting a specific process and process variables and by using the default controls. After the
wizard creates the task view, you can then add custom logic, such as adaptors or an invoke button.
With the default task template, users can also view attachments or packages in the TaskSpace preview
pane. You also have additional options.
Display a document package inline

You can display a specific document package inline using the task template with an embedded form
control.
When selecting the data binding for the embedded form, be sure to bind to the valid object path:
/Activity/.../<package name>/DocumentId (you can also bind to a process variable assuming that
the variable value is an object ID).
70
Next, select the appropriate form template to show the package content, which is a document view
template or an electronic form. You can then preview a document and modify document data while
processing the task. It is possible to have multiple embedded forms in one view, but the UI can be
busy when there are multiple packages.
Figure 8
Task template with embedded document view
Display folder package inline

You can display a specific folder package inline using the task template with a folder view control.
Select a folder package for the data binding, then configure how the folder view is displayed. This
option allows you to treat a folder as a case and preview a document while processing a task, but you
must show less information due to space limitations.
71
Figure 9
Task template with folder view control
Display multiple packages inline

You can display multiple packages inline using the task template with a folder view control and an
attachment list control. This option allows you to accommodate multiple types of packages (documents
and folders) but you are limited by available space. The folder view can display a folder object from
the attachment list. You can use the preview pane to view an object from the folder view or a document
from the attachment list. When viewing a document from the attachment list, the folder view is empty.
Figure 10 Task template with folder view and attachment list controls - folder
information displayed
72
Figure 11
Task Template with folder view and attachment list - document displayed
Process and form template version links

When using form templates associated with a process, namely task, initiate process, and process
parameter templates, you must keep the version links between the form template and the associated
process correctly aligned. The recommended practice is to always create a new version of the process
and then create a new version of the template. When you create a new version of one of these
templates without also creating a new version of the process, the old version of the template becomes
orphaned. When a template is orphaned, it cannot be used until it is linked back to a process. In the
following graphic, if you created form template version 1.1 before creating process template 1.1,
then form template 1.0 would become orphaned.
73
Figure 12
Process and form template version links
When a form template associated with a process is checked out and a new version created, Forms
Builder automatically links the process to the latest version of the template. Conversely, if you delete
the most recent form template version, the associated process automatically points to the previous
version. You also cannot delete a task, initiate process, or process parameter template if the template
and its associated process are both non-current versions. However, if either the process or the
associated form template are the current version, you can delete the form template.
Custom error messages

The custom error message is important to the validation process and requires careful consideration. It
is also an important element of the UI design as it provides useful feedback to the user when entering
data. Error messages are created in Forms Builder by the template designer during template creation
and are entered in the error message field for each control on the Display tab in the Properties pane.
When writing custom error messages, you should give the user-specific information about the correct
value to enter. Telling the user that the value entered is invalid does not provide much guidance. It is
better to phrase the message in a positive manner and provide an example of a valid value to enter.
A good example would be: Enter a valid date using the format MM/DD/YYYY.
Another technique that is helpful to users is to provide default values for controls that use specific
masks, such as dates, social security numbers, and phone numbers, so that the user has an example to
follow before entering a new value.
If a control does not have a custom error message defined in the template and the value entered is not
valid, the system displays a default error message. The default error messages are generic and only
provide guidance as to the data constraints for the control. An example of a default message for an
invalid data type is: Value entered is not valid for the integer data type. An
example of a default message for an invalid value for a specific data constraint is: Enter a valid
value equal to or greater than %%" (where %% = the defined minimum
74
value). While these messages may be helpful to the user, they are not as helpful as messages created
specifically for a template, tailored to the data requirement for that template.
Data adaptors
Some general guidelines for using adaptors are:
Do not use too many different adaptors as it can impede performance. You can use one data source
adapter to populate multiple fields at once by populating off one database table with multiple
columns. This way, the adaptor only runs once.
Keep adaptors simple and lightweight and keep the execution time of data source adaptors as
short as possible.
Do not perform high latency calls within data source adaptors, such as long-running queries or slow
web service invocations, as these calls can greatly impede performance of the UI.
If you plan to use more than one adaptor, concentrate on getting one adaptor to work before
creating another.
When using a data source adaptor, make sure that the input is required and that the output is
repeating.
When creating a custom data source adaptor, you have a choice of creating it as a class or
service-based business object (SBO). If you create it as a class first it is much easier to validate and
debug the adaptor. You can then convert the adaptor to an SBO if desired.
The following table provides information on which templates or controls each adapter can be used
with, guidelines for how best to use each type of adaptor, and important limitations.
Table 4
Adaptor Types and Uses
Adaptor Type
Available Templates
Best Uses/Limitations
or Controls
Item Initializer
Not available on folder

information, process
parameter, or task
templates
Available on these
controls: Text Field,
RichText, Number Field,
Date Field, DateTime
Field, CheckBox,
CheckBox Group,
Radio Button Group,
ListBox, Dropdown
List, Readonly Table,
Bar Codes, Slider,
Embedded Form, and
Filter
Use this adaptor if you want a value entered automatically in

a field when the template instance is created.
The out-of-the-box item initializer is configured to enter the
current date/time in a date/time field. To use your own logic,
create a custom initializer.
When using an item initializer for an integer value in a
number field, also specify a default value for the field.
On a document view template, the initialization will only
execute when the document view is used while importing
documents in TaskSpace.
75
Adaptor Type
Available Templates
or Controls
Item Validator
Not available on high

fidelity templates
Available on these
RichText, Number Field,
Date Field, DateTime
Field, CheckBox,
CheckBox Group,
Radio Button Group,
ListBox, Dropdown
List, Comment history,
Readonly Table, Slider,
Embedded Form, and
Filter
Use this adaptor if you want to validate a users input values

on individual fields. An item validator applies to one field
and occurs when the user submits the template.
For example, if a data item is an email address, the item
validator could check that it contains exactly one @, at least
one dot after the @, and a recognized domain after the final
dot.
If an error occurs, an error indicator appears next to the
control and the full error message appears at the bottom
of the template. You can create custom error messages
(recommended), or if there is no custom message a default
error message appears. However, if there is a hidden field
on the form that is also marked as required (this should be
avoided), the error message still appears at the bottom. You
can create a custom error message in a validator adaptor by
throwing an exception in the validator adaptor code.
The out-of-the-box validator adaptor validates string inputs
(from user) against the current repository by searching for
them in the list returned by a DQL query.
To perform other validation operations you create a custom
validator adaptor.
Document
Validator

fidelity templates
Use this adaptor to validate an entire form template.

Validation against a custom document validator and required
fields occurs when the user submits the template.
Error messages display at the bottom of the form. You can
create custom error messages (recommended), or if there are
no custom messages then default error messages appear. You
can create a custom error message in a validator adaptor by
throwing an exception in the validator adaptor code.
Data Source

fidelity templates
Available on selection
controls only:
CheckBox Group,
ListBox, Dropdown
List, and Readonly
Table
Use this adaptor to access information from an external data

source and then populate one or more selection controls on
the template. The data source can be either a properties file,
the repository, or a data source that responds to the Java
database connectivity (JDBC) protocol.
For example, when the user selects from a dropdown list of
manager names, the dropdown list of employees could be
automatically populated with only the employees who report
to the selected manager.
For data source adaptors, you also have the option of creating
a custom, complex output type. An output type communicates
between the adaptor and the form and defines the structure for
the values returned from the adaptor. The output type creates
a schema that corresponds to columns in the returned data.
This schema can then be used to map the returned values to
one or more fields on the form.
76
Adaptor Type
Available Templates
or Controls
Data Source Set
Value

fidelity templates
Use this adaptor to automatically populate one field on the

template. There are two types of Set Value adaptors:
Available on these
Number Field, Date
Field, DateTime
Field, Radio Button
Group, CheckBox,
ListBox, Dropdown
List, Package, Slider,
and Embedded Form
On Change - populates a field based on a value entered by

the user in another field. For example, when an employee
is selected from a dropdown list, a field for office location
could then be automatically populated for the selected
employee.
Document
Processor Initialization

information, process
parameter, task, or high
fidelity templates
An initialization adaptor initializes values for the entire form.
Document
Processor Pre-submission

contents, process
instance list, search,
task list, or high fidelity
templates
A pre-submission adaptor executes prior to form submission

provided the validation succeeds, then the form is saved.
Document
Processor Post-submission

contents, process
instance list, process
parameter, search, task
list, or high fidelity
templates
A post-submission adaptor executes after a form is submitted.
On Init - populates a field when the form renders at runtime.
On a document view template, the initialization executes only

when the document view is used while importing documents
in TaskSpace.
There are two out-of-the-box document post-submission

adaptors:
MoveOrLinkToLocationPostProcessor - moves or links a
form instance to a specified location in the repository.
StartWorkflowPostProcessor - starts a workflow with the
form instance as the initial package.
Using one data source adaptor to populate multiple

fields
If you want to automatically populate multiple fields on a template, creating one data source adaptor
that populates multiple fields greatly improves performance. The following example takes you through
creating two data source adaptors. The first adaptor populates a list box of employee names from the
repository. When a name is selected, the second adaptor then automatically populates ID, E-mail
Address, Phone Number, and Department fields for the selected employee from an external database.
77
Figure 13
Employee information lookup adaptors
Populating a list box of employee names

The first data source adaptor populates the Name list box with employee names from the repository.
78
Figure 14
Data source adaptor for employee names
To create this adaptor:

1. Open the Adaptor Configuration Manager and add a new adaptor with the name
GetAllEmployeeNames.
2. Select Data Source as the adaptor type.
3. Select
com.documentum.xforms.engine.adaptor.datasource.docbase.IDocbaseDataSourceAdaptorService
as the class name and SBO as the type.
4. Enter dql for the initial parameter and enter the appropriate DQL clause.
79
5. Specify the output type to describe the return value. Note that the columns returned from the DQL
query conform to the items in the output schema.
6. Click OK to save your configuration and close the Adaptor Configuration Manager.
7. On the Design panel, select the Name drop-down list and open the Properties > Data & Storage
tab.
8. In the External Data Source field, select the GetAllEmployeeNames adaptor.
9. Configure the data source output by specifying the Row Selection, which is the repeating element
that is the parent element of the elements you will select in the Value and Display fields (/data/item).
In the Value field, select the element that provides the data value (/data/item/employeeid). In the
Display field, select the element that is what the users will see (/data/item/name).
80
You have finished configuring the data source adaptor to populate the Name drop-down list.
Populating employee information fields

The second data source adaptor populates ID, E-mail Address, Phone Number, and Department fields
for the employee selected in the Name field.
Figure 15
Data source adaptor for employee information fields
To create this adaptor:

81
1. Open the Adaptor Configuration Manager and add a new adaptor with the name
GetEmployeeInformation.
2. Select Data Source as the adaptor type.
3. Select com.documentum.xforms.engine.adaptor.datasource.jdbc.JDBCDataSourceAdaptor as
the class name and Class as the type.
4. Enter sql for the initial parameter and enter the appropriate SQL clause for pulling information
from the data base. In the SQL clause, you specify the parameter with ${<param name>} (if
using dql, use single quote, e.g., id=${id}).
5. Define the substitute parameter in the Input field. Be sure to select the Required option for the
input field name. The parameter must match the input name.
82
6. Specify the output type to describe the return value. Note that the columns returned from the SQL
query conform to the items in the output schema. This should include all the employee information
fields you want to populate.
7. Click OK to save your configuration and close the Adaptor Configuration Manager.
8. On the Design panel, select the ID field and open the Properties > Special tab.
9. Select the option to Execute adaptor after the input value changes. This triggers the adaptor to
fire after selecting an employee in the Name field.
10. In the Data Source field, select the GetEmployeeInformation adaptor.
83
11. In the input binding id field, select the xpath where the input value is stored (/employee_id). When
you specify an input value, the adaptor returns database table values associated with that input value.
In the Output data field, select the xpath where the ouput is stored (for the ID field, this would be
/data/item/employee_id). This indicates the value in the database table that populates the field.
12. Repeat the configuration on the Special tab for the other fields you want to populate from this
adaptor. The settings are the same for each, except that the output data should match the field being
populated. For example, for the E-mail Address field, you would select /data/item/email_address
in the Output data field.
13. Add the properties file for this JDBC adaptor to the <web app>\WEB-INF\classes directory.
The properties file name corresponds to the adaptor name and in this case would be
jdbc_GetEmployeeInformation.properties. The properties file specifies the location of the data
source and standard JDBC configuration parameters, such as login credentials for the data source
and the path to the JDBC driver. The properties file for this adaptor would be similar to:
url=jdbc:mysql://localhost:3306/mysql
driver=com.mysql.jdbc.Driver
user=root
password=forms (or password=pT9oeWTVuFI=)
To encrypt the password, you can use the DFC encryption method:
java com.documentum.fc.tools.RegistryPasswordUtils <password>
You have finished configuring the data source adaptor to populate the employee information fields.
Performance
When working with form templates, the following tips can improve performance:
84
From the beginning of the project through the design, maintain focus on performance. Performance
takes precedence over appearance and special effects.
Reducing complexity in form templates aids TaskSpace performance: fewer fields and fewer
adaptors.
On a task list template, keep the search simple as this greatly aids performance.
When possible, do not enable ACL security for structured data types and process variables when
designing a task list template. It takes longer to load task lists in TaskSpace if process variables
and structured data types have to be evaluated for ACL settings.
While using multiple task templates for different activities may improve performance, it also
increases maintenance. A better approach may be to use one task template with conditional display
settings.
Keep everything optimized for the chosen database.
Data adaptors and rules all affect the length of time it takes to open the form.
When designing a custom forms template list view, such as a search view, task list, or folder content
form template, include the r_object_type, r_content_size, r_lock_owner, and a_content_type
attributes. If these attributes are not present in the DQL of the forms templates, the system performs
full object fetches for each data row.
Implementing TaskSpace applications

This section contains information that partners and field engineers can use to better implement
TaskSpace applications.
If your planning is well-executed, and you did a good job implementing your process and forms, then
implementing TaskSpace is a simple matter of assembling the parts. Nevertheless, there are some
things you can do to implement TaskSpace more effectively.
Iterative rollout of a TaskSpace application

When working with a customer to develop a TaskSpace application, use an iterative approach. This
approach helps avoid having to redo a large and complex application when your customer informs you
late in the process that what you have developed is not what they wanted.
1. Determine the business processes necessary for the application.
2. Determine the data model for the process.
3. Create mock-ups of the Forms for that process.
4. Quickly produce a TaskSpace application and ask the customer, Is this what you want?
Allowing the customer to see what you have in mind helps them to more fully visualize what it is they
really want and need. Producing quick, iterative applications enables them to help you develop the
right application for them.
85
Working with task templates

Task templates are complex and, given the close connection to processes, subject to problems if the
underlying process changes. The following sections provide information specific to the buttons on task
templates that can be affected by changes to the process or data model.
Which task buttons to add

When you create a task template, Forms Builder automatically adds the appropriate buttons based on
whether there are one or more forward tasks, if the forwarding is conditional or manual, or if there
are reject paths. However, if you add or remove process flows when modifying the process, these
buttons remain static and therefore do not necessarily reflect the new process flows. When you test the
application you may find that you are not able to finish or forward a task.
The easiest solution is to add ALL task buttons that you think you may need. TaskSpace automatically
shows and hides buttons as appropriate. This can save you much time during development. As a
good practice, name the buttons with the same name as the actual activity (for example, if it is a
Reject button, label it Reject). You can give it a custom display label, but the name should reflect
the actual activity being performed.
Finish button fails to work if the data model has changed

If you change the underlying data model (such as a structured data type definition), update the task
template itself to reflect this change, otherwise the Finish button may fail to work.
1. Uninstall the task template.
2. Save the task template.
3. Install the task template again to refresh the templates data model.
Setting the height of the metadata pane in a folder

view
You can set the height of the metadata pane in a folder view using the Folder tab when configuring a
role. Set the height of the metadata pane by selecting Show overview panel and then setting the height
in pixels in the Overview panel height field.
To determine how high you want the metadata:
1. Open the folder contents template (Folder tab) in TaskSpace after creating a folder information
template (which specifies the metadata).
2. Drag the metadate frame to the desired size.
3. Use Firebug (http://getfirebug.com) or a similar tool to find the height that you chose.
This value is in the framesets cols attribute. The first value is the height in pixels of the metadata
view.
4. Use Role > Edit to set the height.
Note: Add 16 pixels to compensate for the scroll bar.
86
Working with configurable actions

The following sections provide some important guidelines when working with configurable actions.
Configuring current object actions

When configuring current object actions (that is, selecting Current Folder, Current Calendar, or
Current Object as opposed to Selected Object) be sure to select the Always option for the Enable
action if setting.
A current object action is invoked against an object you are currently viewing (in the Open Item tab)
such as a document, folder or task. Always indicates that the required action parameters are supplied
by the object being viewed and that the action can be evaluated when the action control is rendered.
Configuring selected object actions

When configuring selected object actions (that is, selecting Selected Object as opposed to Current
Folder, Current Calendar, or Current Object), be sure to select the One object selected\More than
one object... option for the Enable action if setting.
A selected object action is invoked against an object you have selected in the data grid. One object
selected\More than one object... indicates that the required action parameters are not present until
objects are selected in the data grid and that the action should not be evaluated until then.
Assigning current object actions to menus

Do not assign current object actions for use in configured menus. It is confusing to the user as to
when menu items should be enabled or disabled:
If an object is selected in a folder content data grid, the action is enabled on the menu.
If an object is selected in a search view data grid, the action option is disabled on the menu.
Because the folder view provides proper current object context, the action can be enabled in folder
view but not in search view.
87
88
Chapter 7
Monitoring Business Activity
System requirements
Reporting requirements
Dashboard design considerations
Crystal Reports versus Simple Reports
Cleaning production environments
Custom aggregation
Leveraging the Preconfigured Dashboards
Dashboard refresh intervals
Designing drill-down reports
Formatting reports to be more readable
Computed Column dates and sorting
System requirements
It is a best practice to use the BAM Sizing Calculator to determine your hardware requirements before
you install Business Activity Monitor. The sizing calculator is available on the EMC Download Center
in the Documentum Business Activity Monitor Supplemental Files zip file. This tool calculates the size
of the BAM database, the BAM server, and the Taskspace/BAM dashboard server, based on several
metrics that you enter, including the number of processes you are monitoring, the number of process
instances monitored per day, and the average number of activities in each process.
Reporting requirements
Planning is the most important step in deploying any component of xCP, including the Business
Activity Monitor. If you are deploying BAM with Process Builder, Forms Builder, and TaskSpace,
it is a best practice to define your reporting requirement as one of your first steps in deploying xCP.
This requires that you brainstorm and design mock-ups of the BAM reports and dashboards that
your business requires, even before you begin to design your process. Your reporting requirements
can have a large impact on how your process is designed and the substance and structure of your data
model, including SDTs and package attributes.
The more detail included in your requirements specifications, the better. At a minimum, reporting
requirements should include:
89
purpose of report
report type (management report, operational report)
report columns
a description of drill-down relationships (both single and multi-drill-down reports)
audience
frequency and timing
report filters and dashboard filters (both default and initial filters)
graphical representation
Providing a sample of the report helps identify the attributes that must be monitored in the process.
The easiest way to design mock-ups is with Microsoft Excel where reports can be formatted numerous
ways (tables, pie charts, bar charts, and so on). Although a fairly simple example, the following
mock-up highlights that vendor and amount attributes must be monitored within the invoice process.
In addition, since this report calculates an average amount, we know that aggregation is also required.
This mock-up provides important information that impacts the design of your process.
Identifying reports that rely on aggregation is an important part of defining report requirements. BAM
provides three methods of aggregating report data. First, there is report aggregation which is based on
instance-level data. Then, there is server aggregation where data is automatically aggregated for nine
different time intervals (5 minutes, daily, and so on). And finally, there is custom aggregation. The
Business Activity Monitor Implementation Guide has more information on each type of aggregation. In
terms of planning, anticipating the type of aggregation you require is helpful. For example, if you have
high-volume processes where thousands of instances are running each day, then report aggregation is
not recommended. Attempting to aggregate large volumes of instance data (on request) consumes
high server memory resources and can result in poor response time.
Dashboard design considerations

There are several best practices that relate to BAM dashboard design.
90
1. Dashboard content and quantity - It is best practice to determine the content to display in each
dashboard. This work is really an extension of identifying reporting requirements since a majority
of dashboards contain reports (dashboards can also contain process diagrams, alerts, and process
simulation dashlets). One strategy to determine dashboard content is for each dashboard to contain
the same type of information.
For instance, if you are monitoring a purchase order process, then you may want one dashboard
(or more) to contain only summary information. Summary reports would be designed by using
report aggregation or an aggregation report entity. This type of dashboard may be appropriate for
an Operations Manager, for instance.
Then, you may want another set of dashboards to display instance-level data that looks at the
status of individual processes. This type of dashboard may be appropriate for a task processor.
A third dashboard might include only alerts, which would be of interest to a supervisor.
Another approach is to design dashboards that incorporate single and multi-drill-down reports.
These dashboards integrate high-level, aggregated reports with reports that provide greater
amounts of detail. Users can navigate, or drill-down, from one report to another based on their
needs. Multi-drill-down reports update the contents in surrounding target reports based on a
users selection in a base report. Single and multi-drill-down reports are addressed in the Business
Activity Monitor Implementation Guide.
Drill-down reports are well-suited in situations where the purpose of the dashboard is to identify
root causes of process problems. Users must be able to move from one level of detail to another,
while attempting to isolate the process instances that are problematic. Dashboards configured in
this way should be provided to users that also have the authority to change the process, if necessary.
2. Dashboard users - It is best practice to always consider the characteristics of your dashboard users
as you design reports and begin to think through the contents of each dashboard. Individual users
are assigned to one or more roles and dashboards are assigned to roles. That is the extent of the
security, so when a dashboard is assigned to a role, all users associated with that role can view the
contents of the dashboard. It is important to compile a complete list of users and roles so you do
not inadvertently assign dashboards to users that do not require them. You may find that the roles
available in the repository are too broad. In this case, you may need to create separate dashboard
roles. Another method for controlling access is to use filter variables that limit the data displayed in
dashboard reports to that owned by a specific dashboard user.
3. Number of dashlets for each dashboard - The optimum number of dashlets contained in a single
dashboard is determined by the resolution of the users monitors. If monitor resolution is 1440 x
900, then no more than four dashlets should be included in a dashboard. If monitor resolution is
set to 1920 x 1200, then up to six dashlets can be placed on a dashboard. It is best practice, then,
to know the capabilities of users hardware, and to plan for the lowest common denominator.
If 50 users have the higher monitor resolution, and 10 have the lower resolution, then plan for
dashboard to contain four dashlets.
There are a few other points to consider:
Dashlets containing Crystal Reports require more space so take this into consideration when
you are planning dashboards
Small dashlets can be maximized
Crystal Reports versus Simple Reports

The Business Activity Monitor offers two approaches to designing BAM dashboard reports: simple
reports and Crystal Reports. Simple reports are designed exclusively in Process Reporting Services
91
(PRS). Crystal Reports are designed first in PRS and then opened in the Crystal Report software
where report design continues.
Consider the following points when deciding whether to use simple reports or Crystal Reports:
Report formatting: While simple reports offer some formatting options, Crystal Reports offers
more, including the use of report headers and watermarks. Crystal Reports has a greater selection of
chart types and a richer syntax for writing computed column formulas. If you require a high degree
of control over the look and feel of a report, then Crystal Reports is the best option.
Amount of report data: If you implement large grid reports with greater than 1,000 records, use
Crystal Reports to improve performance. Use simple reports for smaller grid reports.
Cleaning production environments

Purging permanently deletes data from the BAM database, so developing a purging strategy is
recommended. Ultimately, what to purge and how often to purge depends on how quickly the BAM
database table space fills up. Your purge strategy also depends on how long you must keep BAM
data for reporting purposes. One approach is to generate a dump file of the BAM database on a
periodic basis, and then purge the entire BAM database. Historic data can be restored when required.
Depending on the volume of process data, your strategy can be to take a snapshot of the BAM
database every three or six months.
Another strategy to use is to selectively purge tables that contain a lot of data. In BAM, there are
instance-level tables and nine types of aggregation tables. Over the course of a single day, for instance,
the 5 minutes aggregation table holds 288 rows, over a week it holds 2016 rows, and over a year this
aggregation table holds 105,210 rows of data. The 5 minute aggregation data may not be useful to you
beyond a few months, so purging this table every six months is probably reasonable. The same can be
said of the 15 minutes aggregation table, although this table holds less data than the 5 minutes table,
with 35,040 rows per year compared to 105,210 for the 5 minute table.
Custom aggregation
Your need to define custom aggregation report entities relates to the attributes you have selected to
monitor. As a practical matter, do not collect data unless you absolutely must. If you need process
data only once, then collect it at the end. If you need data more than once, for multiple activities in
a process, then you may have problems with business data aggregation. For example, if a numeric
attribute value during Activity A is 3 and the same attribute value for Activity D is 9, then the
calculated average is 6, which is inaccurate. In reality, the value that should be incorporated into the
calculation is 9, not 6. In these cases, custom aggregation report entities must be created. Custom
aggregation must also be used when you want to combine data from multiple data sources and in
situations when you need to combine process data and business data. For example, if you want to
calculate the average duration it takes to process orders from the state of California, then custom
aggregation must be used. Custom aggregation can also be used to improve BAM server performance
when report aggregation attempts to collapse thousands and thousands of instance-level data.
For more on custom aggregation, please see the Creating Custom Aggregation, Report, and Filter
Entities chapter of the Business Activity Monitor Implementation Guide.
92
Leveraging the Preconfigured Dashboards

The Preconfigured Dashboards, and the reports on which they are based, are an excellent source of
learning and should be leveraged whenever possible. The simplest approach is to use the Preconfigured
Dashboard reports to learn about data source creation and report design. In this way, users can reverse
engineer the reports to learn how they were designed. Another way to leverage the Preconfigured
Dashboard reports is to open them for editing in PRS, and add and/or remove data as appropriate. For
instance, add SDT or package attribute data to the List of Process Instance report, since business data
is not included in any of the Preconfigured Dashboard reports.
CAUTION: If you modify any of the Preconfigured Dashboard reports, you must understand
how to reformat the chart data. Adding and subtracting data disturbs the X-axis and Y-axis
settings.
Another approach to leveraging the Preconfigured Dashboards is to design a report and replace one
of the dashlets in either of the three dashboards. With this approach you do not need to design a
dashboard from scratch, you are simply replacing the contents of a dashboard that already exists.
You are not required to create a dashboard tab, or assign the tab to roles, as is typically required
when you design a dashboard. Keep in mind, though, that editing a dashboard changes the contents
for users that are viewing it.
Dashboard refresh intervals

BAM dashboards can be configured to refresh after a certain interval of time. While there is no
absolute best practice regarding refresh intervals, it is recommended that you determine how often you
need to see updated data. If you have low volumes of long running processes, then a refresh interval of
every few days may suffice. If you have high volumes of processes and your data changes frequently,
then more regularly scheduled refresh periods is more appropriate. Refresh intervals are scheduled in
minutes. Since refreshing a dashboard is somewhat demanding on the BAM system, it is important
that you balance your needs with the frequency with which the data changes.
Designing drill-down reports

Single and multi-drill-down reports are configured with a source report and a target report. It is best
practice to design the target report first, so that it is available on picklists when the source report is
designed.
Formatting reports to be more readable

There are a few methods for making BAM dashboard reports more readable:
Entering a report title and subtitle in the Chart Properties window is not necessary since the name of
the report appears in the title bar of the dashlet.
93
Use both report filters and dashlet filters as methods to reduce the number of records that appear
in simple reports. This is especially true for bar and pie charts where 12 or more records make
these reports difficult to read.
Modify the length of bar chart labels with the Limit Characters chart property.
Edit entity field captions so they are shorter.
Suppress chart animation in the Chart Properties window.
Remove the chart legend.
Use computed columns to shorten long date values.
Computed Column dates and sorting

The Computed Columns feature can be used to display Start Date and Time data in a number of date
formats. For example, the Start Date and Time value of April 7, 2009 3:46:40 PM can be formatted
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
display dates chronologically (and not alphabetically), select the original Start Date and Time column
in the Sort field of the Chart Data window. In the following example, a computed column (date) is
selected as the x-axis while Start Date and Time is selected as the sort column.
94
Chapter 8
Performance and Scalability
General approach to performance
System configuration guidelines
Factors that affect performance and scalability
Recommended application server settings
Recommended Content Server settings
Recommended database server settings
Tuning and troubleshooting performance problems
General approach to performance

This section discusses general performance theory. Performance analysis treats a large number of
different metrics, such as response time, throughput, efficiency, and capacity. The two that are the most
important to process-based applications are response time and throughput.
Response time measures the amount of time you must wait to receive any response to a request;
for example, running a series of automated activities may incur a response time of one second
between each one.
Throughput measures the number of transactions the system can process per unit of time; for
example, a system may be able to handle only 100 TaskSpace searches per minute.
As you design the application, you should:
Not go deep. The reason for the recommendation to not go deep is that every layer of database
tables generates additional joins that impact performance. You should keep your inheritance
hierarchy as flat as you can.
Tune for the highest-yield queries. Yield is the number of times a query is executed multiplied by
the execution time of the query. By anticipating the yield and tuning it for the highest-yield query,
your performance does not degrade unacceptably for that use case. To achieve this you may need to
de-normalize, pulling attributes into one or two physical tables.
In general, the recommended approach to performance testing is to carry out two classes of tests:
Single user profiling In single-user profiling you run unit tests, such as collecting Documentum
Class Library (DMCL)/DFC traces.
Load testing In load testing you are looking for bottlenecks and capacity issues.
95
System configuration guidelines

During the planning phase of a project it is important to define the scalability and performance
requirements of the solution. Some process-based applications are high volume and require special
considerations for deployment in a production environment. System configurations for production
deployment can be grouped roughly by size as follows:
Small Fewer than 300 TaskSpace users, fewer than 10,000 active workflow instances, one
central location
Medium Fewer than 2,000 TaskSpace users and fewer than 100,000 active workflow instances,
distributed architecture
Large More than 2,000 TaskSpace users, more than 100,000 active workflows, distributed
architecture with clustering and failover
To be accurate, identify sizing parameters such as the numbers of documents, number of activities per
process, process duration, and the amount of data processed. One approach is for the project team
to create a template that captures relevant sizing parameters and then validates the template with the
client. Specify in the template the types of actions required for different volume levels. Large volumes
of processes can raise issues of High Availability and Disaster Recovery, which require more complex
and robust hardware requirements. Listing the types of equipment to support various volume levels
helps clients make informed business decisions.
Small configurations
The recommended approach to host small configuration environments is to use WMware. Create a
separate virtual machine for every tier. Each tier should have roughly 2 to 4 Central Processing
Units (CPUs) with 4 GB to 8 GB of Random Access Memory (RAM). A WMware configuration
could include:
TaskSpace application server

Content server
Database server
BAM application server
BAM server
BAM database server
Medium configurations
The recommended approach for medium configuration environments is to use enterprise machines.
Software clustering can be used at the application server, database server, and content server levels.
WMware can be used for the TaskSpace application server and the BAM application server. Large
servers ranging from 4 CPUs to 16 CPUs and 8 GB to 32 GB of RAM are used for each of the
following tiers:
Content server
Database server
96

BAM server
BAM database server
BOCS server at branch offices
If required, this type of configuration supports multiple content server instances on a single machine
and multiple content servers implemented on multiple machines.
Large configurations
Enterprise machines are used to host large configuration environments. Large configurations include
hardware and software clustering at the application server, database server, and content server levels.
WMware can be used for the TaskSpace application server and the BAM application server. Large
servers with machines ranging from 16 CPUs to 64 CPUs and 32 GB to 128 GB of RAM are used for
each of the following tiers:
Content server
Database server
BAM server
BAM database server
BOCS server at branch offices
Configuration best practices

EMC recommends the following best practices:
Do not run TaskSpace and BAM on the same Java Virtual Machine (JVM).
Keep databases on separate servers.
If WMware is used, ensure that there is a fast pipeline to the Storage Area Network/Network
Attached Storage (SAN/NAS). EMC recommends using dedicated Fiber or 10 gigabit Internet Small
Computer System Interface (ISCSI).
The network must not experience performance issues and it must have minimal latency.
Documentum products are network sensitive and require a high speed network.
All tiers of the server environment must be co-located in the same data center.
Consider system sizing during the design phase, since volumetric considerations influence the system
design. For example, some process transactions, like the Task List, are high yield, which means
that they are performed frequently. A transaction like that can perform well in a test environment,
but can cause performance problems when you have many users making simultaneous transactions.
Each transaction queries the database that must return results in under one second. Aggregate demand
on the database adversely impacts user performance when a browser is unable to render screens in a
timely fashion. It can take five seconds or longer in some cases. If there are thousands of simultaneous
users querying the database, there may not be enough bandwidth to accommodate the demand and
performance continues to degrade.
97
Factors that affect performance and scalability

This section describes the following factors that can affect performance and scalability:
Automatic activities, page 98
Search forms, page 98
Task lists, page 99
Preconditions, page 99
Skill-set matching, page 100
Logins, page 100
Automatic activities
To improve the performance of automatic activities in your process, make one user (or a small set
of users) the performer of all the automatic activities. For example, if you define a user, such as
auto_executor, and make that user the performer of all the automatic activities, the runtime execution
of these automatic activities increases considerably.
For security reasons, only a superuser can select a specific user as a performer for an automatic
activity in Process Builder.
Search forms
A client may ask you to implement a more complex search option in TaskSpace. Even though it can
be easy to configure multiple search options, advise the client against doing it. The difference in
database performance (and maintenance) between three search options and four is enormous. The best
performing applications enable users to complete their jobs with a minimum of actions and choices.
Designing search forms that are seldom or never used is not advised.
Minimize search criteria

Design search forms with as few search criteria and columns as possible. This keeps application
performance degradation to a minimum and makes any future scaling of the application easier. Each
search criterion requires more maintenance by the database and adds load to the system. For instance,
just one poorly constructed search form with many search options and columns can render the
application non-operational. Before designing search forms, it is important that you fully understand
the business use cases.
Wildcard searches
Avoid implementing wildcard searches because exact searches are the only searches that scale. All
other types of searches involve some form of scanning (index or table), which can hinder the scalability
of the database, and ultimately the entire application.
It is important to separate what a client needs from what a client wants. The needs of the business
should determine how search forms should be designed and used. System performance and future
scalability become victim to over-engineered search forms. Articulate to the client the impact of search
98
technology on system performance. In most cases, clients are willing to reconsider a feature that
negatively impacts system performance.
Mandatory search attributes

When designing a search panel, identify the mandatory fields so the user must always enter them to
improve performance. Most attributes that are drop-downs or check boxes qualify for this case. Once
you make them mandatory, create a composite index on these combined attributes. This ensures all
search queries will at least use this index, instead of open-ended searches, to improve performance.
Task lists
Task lists are one of the most frequently used views in TaskSpace. The best performing task lists limit
the number of SDTs and process variables that appear within the task list. Each additional SDT and
process variable results in a new query to the database. When several concurrent users are working
on the system, these queries add up. As a practical matter, you can consolidate one or more process
variables into a single SDT. For example, a task list containing nine process variables takes 10 seconds
to 15 seconds to populate the window. The same task list built with one SDT containing nine attributes
takes only 3 seconds to 5 seconds. The difference is that the first task list issued nine requests to the
database while the second task list issued only one request. (The best way to understand this behavior
is to take a single click trace of the transaction).
Consider the number of filters that you create in a task list because each filter impacts system
performance.
You can further improve task list performance by disabling full-text indexing if it is not being used.
Refer to Disabling full-text indexing, page 103 for more information.
Preconditions
Be careful when using preconditions in a TaskSpace application because they inject row-by-row
processing into the response time. If there are ten tasks in a task list and there is a precondition
defined for the object type, then the precondition fires ten times. Although preconditions provide
rich functionality, they can negatively affect system performance. For example, a task queue with
preconditions took 8 seconds to 10 seconds to render. Without the preconditions, the same task list
rendered in 3 seconds.
It is recommended that you take a baseline timing of a task or search form before you add
preconditions. After you establish the baseline, the incremental performance cost of a feature can be
assessed. Associate a response time or resource cost for each feature request. Then it is possible to
calculate the cost and benefit of each feature. Calculate a cost, even if a feature is mandatory. Discuss
feature costs together with performance and scalability with the client.
To optimize custom action preconditions for datagrid rendering, define scope values for action
definitions that use the precondition.
Avoid permission checking in precondition classes, since the system will do object full fetches for each
data row. If your precondition must do permission checking, consider using lazy evaluation by adding
the oneexecutiononly=true attribute in the <precondition> tag.
99
Skill-set matching
Skill-set matching is another feature that, if not used wisely, can lead to system performance issues.
There are two reasons for system performance issues.
First, skill-set matching involves row-by-row processing where every task that returns in a task list is
evaluated against the users competency. This is a drain on system resources.
Second, skill-set matching does not use task list database query language (DQL) optimizations.
Without skill-set matching, a task list brings back the first 100 to 300 tasks. This means that the data
list generated requires less resource consumption and performs faster. To bring back the tasks to the
user when the system matches user skills against tasks, it requires the whole data list.
This means that all tasks are sent to the application server for evaluation against the skill-set. If a task
list contains 10,000 tasks, it brings back 10,000 tasks. Even if the user matches one task out of 10,000
the system still brings back 10,000 tasks, which takes time. A task list with 10,000 tasks that does
not match skill-sets brings back 100 to 300 tasks depending on the number of SDTs involved. It is a
best practice to calculate a baseline timing of a task list before implementing skill-sets. This baseline
calculation enables you to determine how skill-set matching impacts performance. It is important to
realize that performance costs grow as the number of tasks grow in a task list. For example, a task list
that returns 100,000 tasks is unusable.
Logins
The user login operation takes 2 seconds to 10 seconds to complete. The variable that most influences
the login time is the landing tab that opens after a user logs in. If the client prefers a fast login, then set
the landing page to the default page or to a blank search page. However, if the user has a preference
about the tab, then the time to log in can take longer.
Recommended application server settings

EMC recommends using the following application server settings:
Recommended Java Flags for a tomcat server
JAVA_OPTS=-server -Xms1024m -Xmx1024m -XX:MaxPermSize=256m -XX:+UseParallelOldGC
Server flag (-server) explanation
JVM server mode provides better performance for long running tests. This must be the first flag.
Permanent generation (-XX:MaxPermSize) explanation
The application dynamically generates and loads many classes expanding the space in the heap to
accommodate its reuse.
Parallel garbage collection (-XX:+UseParallelOldGC) explanation
This allows the JVM to use parallel garbage collection for the full collections.
JVM Capacity
Heap size and threads control the number of users the JVM can support. A JVM can accommodate 150
to 300 users per instance depending on the user activity footprint (opening large forms can reduce the
number of users) and throughput (how fast they are trying to finish the tasks). Response times degrade
as more users enter the JVM. The degradation is due to non-availability of free heap space and users
waiting for available threads. EMC recommends a 1024 MB heap. A heap size smaller than 512 MB
100
results in an out-of-memory error. If the permanent generation is not increased to a minimum of 128
MB, it could also result in an out-of-memory error. The CPU is the first resource to bottleneck on
this tier. The application server is the most scalable tier in the system because there is no limit to the
number of JVM or servers that can be added.
Additional tips
Configure JVM memory minimum and maximum heap size arguments to be the same.
If running Oracle WebLogic or IBM Web Sphere application server, apply different JVM memory
arguments for Administrative and Managed Servers (less resources). Allocate less memory to the
administrative server of each cluster and more memory to the managed server.
Each JVM has a finite capacity number of users it can accommodate. To increase the number of
users a physical server can accommodate, create several JVM nodes on the server. Each JVM needs
to have a different port. It is not uncommon for a physical server to have 4, 8, or 12 JVM instances.
If running WebLogic, have one Internet Information Services (IIS) server installed on each web
server host machine and for each IIS server installation provide appropriate mappings to the
different cluster Internet Protocols (IPs).
If running WebLogic, use JRockit.
Turn off AnnotationHelper for Tomcat 6.x. To turn off AnnotationHelper, set
metadata-complete=true in the <web-app> tag of the web.xml file.
In web.xml, you can increase the value of <cache-control> to push off the expiration date for files,
such as icons and images, on the client side cache.
Recommended Content Server settings

To ensure that Content Server is running to its potential, turn off mail notification, if possible. To turn
off mail notification, put MAIL_NOTIFICATION=F in the server.ini and reboot. Also, narrow the
audit trails to track only the essential events. Audits can slow down response times and increase CPU
on the Content Server and database. Increasing CPU usage decreases performance on the content
server.
The Content Server is scalable. You can add a second Content Server to the same or different server
without causing a problem, but both Content Servers should be close in proximity. If a second Content
Server is created either on the same or a different server, configure the server.ini file to make it also
project to the docbroker with the same proximity.
Turn off debugging on the process engine. By default, the debug mode is turned on. This results in
unnecessary Input/Output (IO) and CPU resource consumption. To turn off debugging, copy and paste
the following to the xml file:
%Documentum%\jboss4.3.0\server\DctmServer_MethodServer\conf\jboss-log4j.xml (Windows)
$DOCUMENTUM_SHARED/jboss4.3.0/server/DctmServer_MethodServer/conf/jboss-log4j.xml
(UNIX/Linux)
<appender name="FILE" class="org.jboss.logging.appender.DailyRollingFileAppender">
<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
<param name="File" value="${jboss.server.log.dir}/server.log"/>
<param name="Threshold" value="INFO"/>
<param name="Append" value="false"/>
101


<param name="DatePattern" value=".yyyy-MM-dd"/>

<layout class="org.apache.log4j.PatternLayout">

<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>

</layout>
</appender>
If you are using the JBoss Application Server, turn off debugging. By default, the debug mode is
turned on. This results in unnecessary IO and CPU resource consumption. To turn off debugging, copy
and paste the following to the xml file:
%Documentum%\jboss4.3.0\server\DctmServer_MethodServer\conf\jboss-log4j.xml (Windows)
$DOCUMENTUM_SHARED/jboss4.3.0/server/DctmServer_MethodServer/conf/jboss-log4j.xml
(UNIX/Linux)
<appender name="FILE" class="org.jboss.logging.appender.DailyRollingFileAppender">
<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
<param name="File" value="${jboss.server.log.dir}/server.log"/>
<param name="Threshold" value="INFO"/>
<param name="Append" value="false"/>

<param name="DatePattern" value=".yyyy-MM-dd"/>

<layout class="org.apache.log4j.PatternLayout">

<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>

</layout>
</appender>
102
Disabling full-text indexing

If you do not need indexing for your xCP applications, disable full-text indexing by unregistering the
events related to full-text indexing. If your system is in production when you unregister full-text
events, you must also purge any existing events. Refer to Purging existing full-text events, page 104
for more information.
Each sysobject has about five registered events related to dm_fulltext_index_user:
dm_save
dm_destroy
dm_readonlysave
dm_checkin
dm_move_content
If you are using indexing, these events are dequeued and purged when the index server is running. If
you do not have an index server or it is not running for administrative reasons, the queue can become
too large causing performance problems for task list queries.
To unregister full-text events:
1. In Documentum Administrator, navigate to the Type Properties Info page:
a. Navigate to Administration > Types to access the Types list page.

A list of existing object types is displayed.
b. Select the type to modify and then select View > Properties > Info to access the Type
Properties Info page.
2. Clear the Enable Indexing: Register for indexing checkbox to unregister the type for fulltext
indexing.
103
If registering a particular type for indexing, the system automatically selects its subtypes for
indexing. When registering a type for indexing, the system checks for any of its subtypes that are
registered. If a subtype is registered, the system unregisters it before registering the type.
The system displays the Enable Indexing checkbox based on the following criteria:
If the type is dm_sysobject or its subtypes and you are connected as a Superuser to a 5.3 SP5
or later repository, the system displays the checkbox. If neither of these conditions is met,
the system does not display the checkbox.
If a type and none of its supertypes are registered, the system displays the checkbox cleared and
enabled. You can select the checkbox to register the type for fulltext indexing.
If a type is registered and none of its supertypes are registered, the system displays the Enable
Indexing checkbox selected and enabled.
If a types supertype is registered for indexing, the system displays the Enable Indexing
checkbox selected but disabled. You cannot clear the checkbox.
Note: The system does not display the Enable Indexing checkbox on the New Types - Info page
when you create a new type. You must first create the type and then save it.
3. Click OK to save your changes.
Purging existing full-text events

To purge existing events:
1. Export the dmi_queue_item_s table using database utilities like exp in Oracle. For example,
the commands for Oracle are shown below.
a. Export the full table in this step to have a backup.

exp username/password file=dmi_queue_item_s_full.dat log=dmi_queue_item_s_full.log
tables=dmi_queue_item_s buffer=100000
b. Export the table again by selectively retrieving rows that you want other than
dm_fulltext_index_user.
(Windows) Notice that there are three double quotes in the query clause:
exp username/password file=dmi_queue_item_s.dat log=dmi_queue_item_s.log
tables=dmi_queue_item_s buffer=100000 query="""where name not in
dm_fulltext_index_user"""
(UNIX) Notice the back slash (\) instead of double quotes ("):
exp username/password file=dmi_queue_item_s.dat log=dmi_queue_item_s.log
tables=dmi_queue_item_s buffer=100000 query=\"where name not in
\dm_fulltext_index_user\ \"
2. Truncate the table dmi_queue_item_s as it will not create any redo entries and is the fastest way to
delete millions of rows that are related to full text. If you do not have too many rows, you can do a
simple delete and you do not have to reimport the data.
truncate table dmi_queue_item_s
3. Reimport the exported data that does not contain full-text events.
104
imp username/password file=dmi_queue_item_s.dat log=dmi_queue_item_s_imp.log

buffer=100000 full=y
4. Gather statistics on the table to capture the correct statistics.
Recommended database server settings

The following Oracle database parameters are essential for xCP:
cursor_sharing = FORCE
optimizer_mode = ALL_ROWS
optimizer_index_cost_adj = 5
optimizer_index_caching = 95
The optimizer_index_* parameter values 5 and 95 are good starting levels.
These database parameters can be modified in the init.ora or through Oracle Enterprise Manager
(OEM).
Frequently monitor Automatic Workload Repository (AWR) reports collected during peak usage to
identify whether you allocated enough memory to the System Global Area (SGA) and Program Global
Area (PGA). Determine if there are any queries consuming considerable resources.
The following Microsoft SQL Server database parameters are essential for xCP:
Parameterization = FORCED
max degree of parallelism = 1
The Parameterization database parameter can be changed using SQL Server management studio or
by running this command:
alter database <databasename> set parameterization forced
The max degree of parallelism can be changed as follows:
sp_configure max degree of parallelism,1
reconfigure
On the Content Server, especially when running with a SQL Server database, you should also set the
DM_LEFT_OUTER_JOIN_FOR_ACL=T environment variable to improve performance.
Tuning and troubleshooting performance

problems
If a certain type of user click in the application takes longer than expected, tune it. The fast and
efficient way to solve performance problems is to take and analyze a Documentum Foundation
Class (DFC) trace. Documentum provides scripts that aggregate this information and present it in a
readable format, with a complete breakdown of the transaction. By examining the analyzed trace, you
can determine whether the issue is poorly-performing DQL, inefficient code, list generation issue,
or a non-optimized system.
105
106
Chapter 9
Deploying the Application
Deploying the application overview
The deployment process
Deployment best practices
Deploying the application overview

After the application has been developed and tested, it is ready for the production environment. The
environment in which process-based applications are put into production generally differs from the
development environment. The production environment usually has more users and, therefore, requires
more hardware components, software modules, and databases. In this document, the term deployment
means the transfer of applications between environments: from development to test or from test to
production, with as many intermediate environments as necessary. In the general setting, you deploy
applications from a source environment to a target environment.
The deployment process begins by preparing the target environment. To prepare the target
environment, EMC Documentum products such as Content Server, Process Engine, Process
Builder, and BAM that were installed in the source environment must also be installed in the target
environment. The next step is to define the users in the target environment. In most cases, the users in
the target environment are different from the users in the source environment.
The deployment process

After you have developed a TaskSpace application with BAM dashboards and have completed testing
the application, you can begin deployment. (If you have not implemented BAM in your solution,
skip steps 3, 4, and 6).
To deploy:
1. Install TaskSpace and other xCP products in the target environment.
2. Create a Composer project. Add the SDTs that you used to create BAM reports to this project.
Build a Documentum Archive (DAR) file. Install it on the target environment.
3. Start BAM in the production environment. The report entities corresponding to the SDTs you
imported in Step 1 will be populated in the Documentum repository.
4. If you created BAM custom entities, they are not migrated by using Composer. When you created
those entities you would have run one or more DQL scripts. Save the DQL scripts as a text file.
107
At deployment time, manually run those scripts in the target environment to create your custom
entities in the BAM database.
5. In Composer, create a new TaskSpace application project. Select the TaskSpace application name
from the list of available TaskSpace applications.
This action automatically pulls in all related artifacts:
The associated process (from Process Builder), associated forms, roles, tabs
Associated BAM dashboards (defined as tabs in TaskSpace)
First-level BAM reports on these dashboards (First-level reports are not defined as drilldown
reports)
6. Manually import the drilldown reports. This action is required because the drilldown reports you
created in your dashboards are not automatically imported into the project. Also, import the
BAM Configuration artifact that contains various settings used by BAM (such as time settings for
the gap filler).
7. If you are using headless Composer, build the DAR file for this project.
Composer builds the DAR automatically. It is located in the bin-dar folder of the project root.
8. Install the Composer project into the target environment.
Deployment best practices

This section lists some best practices to follow for deployment:
Composer version
Use the latest version of Composer including any hot fixes that are available.
Linking process templates to your application

When constructing your TaskSpace application, it is best to link the process templates to your
application. This causes the linked process templates to import automatically into your Composer
Project when your TaskSpace application is imported into your Composer Project. Processes required
by your application that are not linked to your TaskSpace application are not imported automatically
when the TaskSpace application is imported and must be added individually to your Composer project
or they will not be available in the production environment after the Composer project is installed.
Database references
Whenever database references change as you move from the source to the target environment, these
references must be manually updated to the new database reference. Do this after you install your
application into the production environment.
Specific performers in processes

When processes contain specific performers, reference those performers as process parameters.
Process parameters become installation parameters in the Composer project. This enables you to make
the replacement in your Composer project once for each process rather than once for each activity in
108
which the performer is referenced. It also enables you to replace a performer globally throughout a
process with a new performer without making a replacement at each activity the performer is used.
Note: A process parameter is specific to a process. Therefore, process designers must update the
process parameter for each process, even if two processes have a process parameter with the same
name.
Updating process data

To modify an SDT in any of the following ways, delete the SDT (from the target environment) before
installing your application into the production environment:
Remove an attribute.
Decrease the length of a string variable.
Change a repeating attribute to a non-repeating attribute.
Change the data type of an attribute.
To update an object type in any of the following ways, drop the object type from the production
environment before installing your application into the production environment:
Remove an attribute.
Decrease the length of a string variable.
Change a non-repeating attribute to a repeating attribute.
Change a repeating attribute to a non-repeating attribute.
Change the data type of an attribute.
Versioning the process template

If the application you are deploying replaces existing process templates that have running workflows,
version the process template. Versioning the process template enables existing workflows to continue
to function after the application updates the process template. To version the process template, do the
following:Existing workflows complete by using the older version of the process template, while new
instances of the process template use the new version of the process template.
1. Import your updated process template into your project and set the installation options of the
process template to VERSION.
2. Install the DAR file created from this project into your target repository.
Overwriting an existing process

When deploying an application from one environment to another, do the following to overwrite
an existing process (rather than versioning it).
1. Uninstall the process templates that will be overwritten. This halts running workflows.
2. Reinstall the process template, selecting to abort all running workflows. This ensures that there are
no running workflows when the process template is overwritten.
When to use Composer

Do not use Composer as a development environment to modify your processes. Use Composer only to
archive and install (including the use of installation parameters). Use the appropriate tool in xCP to
make changes.
109
110
Chapter 10
Archiving the Application
Manually Archiving TaskSpace Applications
Manually Archiving TaskSpace Applications

This section provides step-by-step instructions on manually archiving and installing a TaskSpace
application. However, it does not address automatic builds with Apache Ant. Since the incorporation
of importArtifacts in Composer version 6.6, it is possible to build TaskSpace applications with Ant.
This approach can be preferable if you are packaging with any frequency (daily, weekly, or bi-weekly
builds).
Manual archiving uses a zipped composer project file, rather than a DAR file, to enable you to fix any
problems when reinstalling the target side application.
The following are examples of when to archive a TaskSpace application manually:
Moving an application from one environment to another
Saving an application for later use or reference
Do not use manual application archiving as part of the development process of a project, try to use
automatic builds instead.
Best practices before and after archiving

When you decide to create a TaskSpace application, the following best practices can make archiving
the application quicker and easier.
When you decide to archive an application, consider Composer only as a transport or archiving
utility. Do not modify your Composer project after you have imported your artifacts. If you created
your types or objects in a Composer project, consider it only as a bootstrapping project to create the
artifacts for your application archive.
Always define your folder structure for your TaskSpace application so that you can simply archive
the whole cabinet or folder with the workflows already in there. This way you avoid archiving the
workflows separately.
Store workflows for a specific application in their own folder to make them more recognizable.
Archive this folder manually. DO NOT archive it in a cabinet or folder that needs a manual archive.
Organize your Structured Data Types under a category to make them easier to identify when
archiving.
111
When you create custom objects (forms, object types, process templates, and so on), it is beneficial
to have a standard naming convention. For example, you can add the same prefix to the name of the
object. This way, the custom objects are easier to identify when archiving.
Always make sure to add all object types, forms, processes, and roles that your Taskspace
application uses in the Configuration tab.
If possible, always test your archived application on a virtual machine. If the archived application
fails, the virtual machine enables you to roll back the system to its initial state.
Archiving in Documentum releases 6.6 and higher

In versions 6.6 and higher, it is no longer necessary to download TCMReferenceProject into Composer
to make the archive work properly.
1. For every TaskSpace application you want to archive, repeat steps 1a to 1f in Composer:
a. Select File > New > Project > Documentum Project > Documentum Project From
TaskSpace Application and click Next.
b. Log in to the repository and click Next.
c. Select your TaskSpace application from the list and click Next.
112
d. Click Finish when done.

e. When you are asked if you want to open the associated perspective, click Yes.
f. Make sure both TCMReferenceProject and the new one you just created reference each other.
Right-click the project, select Properties, and then select the Project References option.
2. Expand the new TaskSpace project, expand Artifacts, and import the following artifacts for
any custom folders:
a. Right-click Folders and select Import > Documentum > Artifacts From Repository.
113
b. Log in to the repository and click Next.

c. In the Choose Artifact Type field, select Folder.
d. Select all your custom folders (press Ctrl and then click to select more than one), hover your
mouse over the first option (Import the selected folder with all sub-folders), and click it.
114
e. If you are asked if you want to overwrite the artifact, click Skip.
3. For every item under Artifacts, verify that your custom objects are imported correctly. If not,
right-click the item and import what is missing (refer to steps 2a to 2e for importing objects).
4. Build the new projects:
a. Turn off automatically building the project. Select Project from the menu and click Build
Automatically to clear the check box.
b. Right-click your project and select Build Project.
Building a project generates a DAR file in the ...\<workspace>\<project>\bindar directory.
115
5. Create a zip file of the composer project to use later when installing the archived application.
In File Explorer, find your workspace, right-click the project, select 7-Zip > Add to archive
to create a zip file of each project.
Testing the Archived Application, page 116 details the steps required to install the archived
application.
6. Copy the zip file to a location that can be accessible for later use in other systems.
For example, you can:
Email it to yourself.
Paste it to a folder in an FTP site.
Paste it to a folder in ftp://ftp2.emc.com/, which is available in all demo systems.
You are now done with archiving your TaskSpace application.
Testing the Archived Application

We recommend that you use a VM (Virtual Machine) to test the archived application. With a virtual
machine, you can roll back the system to the initial state in case of failure.
To install the archived TaskSpace applications, you can use the DAR file generated while archiving
the application or import the zipped project into Composer. This procedure describes importing the
zipped project into Composer.
To install the archived application:
1. Import the zipped project into composer:
a. Retrieve the Composer project zip file and put it into a temporary location on the target system.
b. In Composer, select File > Import > Documentum > Existing Projects Into Workspace
and click Next.
116
c. In the Select archive file field, select the zip file from your temporary location.
d. Click Finish.
The system creates a project for your TaskSpace application in Composer.
e. When asked if you want to open the associated perspective, click Yes.
f. Expand the Artifacts folder of the project. Verify that all of your custom components are
available.
g. Right-click the project and select Install Documentum Project.
117
h. Select the appropriate repository; enter the user name and password; and then log in to the
repository.
i. Click Next.
A list of your custom components appears.
j. To add an Installation Parameter File, in the box at the bottom, click Browse.
k. Click Finish.
2. To access the application on the new system:
http://<host>:<port>/taskspace/component/main/?appname=<application name>
3. When archiving an xCP application using Composer, the association of the users to any roles that
you have setup is not going to be included. Therefore, you either have to set them up in the
new environment manually, or use a script to do it automatically. This script is described at the
following link:
https://community.emc.com/docs/DOC-10087
Troubleshooting the Archived Application

While archiving and/or after you install the archived application, if there are any error messages
try the following:
In Content Server, check the log files under C:\temp\documentum.
118
In Composer, check all the artifacts for your custom objects. If any are missing, import them to
the specific artifact, and rebuild the project.
For any specific error message, log in to the EMC Developers Community site
(https://community.emc.com) and search for the error. You can find helpful tips that other
developers have posted.
If you need further details, you can enable tracing. Try the operations and then check the logs
again. They can provide a clearer picture as to what Composer tried to do and what failed. The
Documentum Composer User Guide provides details on how to enable tracing.
119
120
Appendix A
Prototyping Business Activity Monitor
dashboards
This appendix contains the following:
Prototyping overview
Understanding the example
Understanding the approach to prototyping
Including Business Data in your prototype
Create and run the New Account Applications process
Designing the New Account Applications report
Design dashboard and add dashlets
Process Duration alert
New Account Process - Average Duration
Designing the New Account Process - Average Duration process
Running the Average Duration process
Designing the Average Duration report
New Accounts by Customer Type
Designing the New Account by Customer Type process
Running the New Accounts by Customer Type process
Designing the New Accounts by Customer Type report
New Accounts Opened This Week
Designing the New Accounts Opened this Week process
Running the New Accounts Opened this Week process
Designing the New Accounts Opened this Week report
New Accounts Opened Last Week
Designing the New Accounts Opened Last Week process
Running the New Accounts Opened Last Week process
Completing the prototype dashboard
121
Technical solutions that include Business Activity Monitor and other applications of xCP (Process
Builder, Forms Builder, TaskSpace) take time to design and deploy to end users. When a project is
completed a fully designed, tested, and monitored process is deployed to users who complete real
work. Dashboards are populated when users start and work with their processes. Dashboards can also
be populated with data from test processes (ones yet to be deployed) but the process designer is
still responsible for designing a fully functional process. How then, is it possible to design a mock
dashboard that includes a variety of dashboard features, without having a fully developed process?
This answer is to design a dashboard prototype. Dashboard prototypes are designed in TaskSpace, and
contain reports designed in Process Reporting Services (PRS). The simple reports (this document does
not include adding Crystal Reports to a dashboard) display example data that you populate while a
number of small processes run. This data is formatted to appear as bar charts, pie charts, line graphs,
and dial gauges. Prototypes can also include multi- and single drill-down reports.
Designing prototype dashboards serves a few functions. First, prototypes are used by internal resources
of organizations deploying BAM. xCP projects that require planning and designing prototypes help
project members determine which reports are important. Prototyping is also a good way of helping to
define some of the process data requirements. Since a prototype dashboard can contain business data
reports, key business attributes should be included in your data model, and flagged for monitoring.
Dashboard prototypes can also be demonstrated to either internal or external audiences to obtain
valuable feedback prior to actual deployment. Prototypes are an excellent method for demonstrating
the concepts and value of process monitoring.
Whatever the goal, this approach assumes that the prototype designer has a basic understanding of
Process Builder, TaskSpace, and Business Activity Monitor. This documentation does not replace the
Process Builder User Guide or the Business Activity Monitor Implementation Guide. It is assumed that
you are already familiar with those technologies.
This appendix explains how to easily design prototype dashboards that can be used for planning and
demonstrations. The audience for this information is:
an EMC partner that is engaged with a client that wants to see proof that BAM dashboards can be
designed to meet their needs
an EMC customer that is involved in the planning phase of an implementation and wants to see
prototype BAM dashboards without going through an entire xCP deployment
a pre-sales resource
Note: The procedures provided in this document provide actual data that you can enter. If you follow
this approach you will design the Finance Corp prototype dashboard in its entirety. Or, you can apply
the approach described to your own situation, and attempt to build your own prototype dashboard.
Understanding the example

The example used throughout this document focuses on a fictitious company called Finance Corp.
Finance Corp is in the process of building an automated approach to the New Account Opening
process. As part of the planning, Finance Corp is designing a BAM dashboard prototype that includes
reports about their New Account Opening process. The dashboard prototype includes six dashlets:
122
Prototyping Business Activity Monitor dashboards
Finance Corp is also interested in demonstrating the following dashboard capabilities:

single drill-down reports
multi-drill-down reports
Service Level Agreement (SLAs)
The dashboard is conceptually divided into two parts. The contents of the New Account Applications
report and the Alert List and Process Diagram dashlets are each related to a real, but mock process
called New Account Applications. Understanding the approach to prototyping, page 124 addresses
the role and design of the New Account Applications process. In addition, each of these three
dashlets are designed with entities that are shipped with BAM which means they can be applied to
all demonstration scenarios.
New Account Applications this report is designed with the Process Execution entity.
Alert List this dashlet displays information about processes or activities that meet an alert
condition defined in PRS. Defining alerts in PRS is not included in this document. Refer to the
Business Activity Monitor Implementation Guide for more information on alerting.
Process Diagram this dashlet displays the progress of a single process instance when a process is
selected in the New Account Applications report.
The remaining three dashlets in this dashboard contain four business data reports. Four different
business data reports can be viewed because the New Accounts this Week report is configured as a
single drill-down report that displays the New Accounts by Customer Type report when any of the bars
are clicked in the source report. The most important point to understand about business data reports
is that they are designed with report entities that reflect the name and structure of SDTs defined in
Process Builder.
New Account Process this report is formatted as a dial gauge that displays average process
duration.
New Accounts Opened this Week this report is formatted as a bar chart that counts the number
of new accounts opened in each country within the last week.
New Accounts By Customer Type this report is formatted as a pie chart and is configured as the
target report in a single drill-down report. It is linked to the New Accounts Opened this Week report.
123
New Accounts Opened Last Week this report is formatted as a line graph that counts the number
of new accounts opened each day during the last week. This report includes a Service Level
Agreement (SLA) represented as a line.

You may have a process already designed in Process Builder, and instead of going through a full
deployment, you want to extend the design to incorporate a prototype dashboard. The approach
outlined in this document accommodates this particular case, but it does not assume it. That is, you
can begin with nothing. Either way, your first step is to design a mock process. A mock process is a
legitimate process in Process Builder that executes in Process Engine, but it does not perform any real
work. There is no scanning in Captiva, documents are not linked to folders, there are no forms to fill
out, web services are not used, and there are no SDTs or packages. All of the automated steps in the
mock process are no-ops. Each manual step requires a human performer to click the Finish button.
If you already have a pre-existing business process you can substitute your process for the process
outlined in Create and run the New Account Applications process, page 126. We recommend that
you leverage the best practices discussed in this document to organize a single complex business
process into smaller reusable grouped sub-processes. This is important when displaying dashboard
diagrams because long and complex processes are difficult to interpret and understand by the typical
target audience. Dashboard users are more focused on groups of activities that apply directly to them.
Fortunately, leveraging Process Builder, it is possible to group related activities into sub-processes that
simplify the process into its essential user activities. If you dont have a pre-existing process, you can
design the example process described in this document.
Note: The simplified, but realistic no-op process you design provides what you need for the New
Account Applications report, the Alert List dashlet, and the Process Diagram dashlets. The remaining
reports are populated by the approach described in Including Business Data in your prototype,
page 125.
The following figures display the before and after views of a New Applications process following best
practices.
Figure 16
124
Before
Figure 17
After
Including Business Data in your prototype

In a typical deployment of BAM groups of process instances can be analyzed over time. Trend reports
that capture the behavior of processes over time, like the one shown below, is a common dashboard
requirement. This report calculates the number of process instances that are started each day during the
last week. This type of calculation requires process data to be aggregated by BAM over the course
of a week. But when building a dashboard prototype, a weeks worth of data will not be available.
In addition, the simplified, mock process does not carry any content, so how are reports that include
business data (in this case, SDT attribute values) supposed to be included in a prototype dashboard?
The answer is to use a series of processes that each carry an SDT. SDTs are used to enter data values
directly and treat them as if they were daily summaries.
Prototypes are designed so that each report in the dashboard is populated with data from its own
process. Each process contains two activities, one manual and one automatic. The automated activity
is completed by a no-op method, and the manual activity is completed by a user. During the manual
step, values to be displayed in the report are entered as process variables. Once the processes are run,
the reports can be designed in PRS.
This approach gives the illusion that all of the business data reports are derived from the simplified
process (in this case, the New Account Applications process) when in fact they are completely separate.
125
Create and run the New Account Applications process
Create and run the New Account Applications

process
The New Account Applications process is a realistic, but mock process. It is realistic in the sense that
the activities have meaning, and look as though worked is being completed. But in actuality there
is no work being performed. There is no content attached to the process, no queues, and no human
performers. All automated activities are executed by a no-op method. The process is functional,
however, and will be started a few times. There are manual steps that can be completed by clicking the
OK button in TaskSpace. Including a process like this in your prototype is important because it can be
used to demonstrate how process diagrams are displayed in a dashboard. If you have chosen to use
alerts in your prototype, then the contents displayed in the Alert List dashlet is also a by-product of
running this process.
To create and run the New Account Applications process:
1. Lay out the New Account Applications process in Process Builder.
2. For each automated activity, select dm_noop_auto_method as the method.
3. Leave each manual activity as is.

4. Open the Process Properties dialog and select On for the Audit Trail Settings.
Note: Your user must be assigned the Config Audit extended privilege in TaskSpace. For
more information on assigning this extended privilege refer to the Business Activity Monitor
Implementation Guide.
5. Save, validate, and install the process.
6. Log in to TaskSpace and click the Processes tab.
7. Select the New Account Applications process and click Start Process.
126
8. On the Start Workflow: Info window, click Finish. The New Account Applications process is
now completed.
9. Repeat the previous step to start the New Account Applications process four more times. Complete
two of these four processes.

The New Account Applications report provides a list of process instances that have started and
for those that have completed, the finished time and duration is displayed. This report is a table
that contains four columns: Process, Start Date and Time, Finished Date and Time, and Duration
(hh:mm:ss). The data source also includes one additional field, Process Instance ID, that is used to
configure Process as a multi-drill-down column. In the New Account Applications report the process
name appears as a hyperlink that when selected updates the alert list and process diagram dashlets.
To design the New Account Applications report:
1. Log in to PRS.
2. From the File menu select New > Category.
3. In the Name field enter New Account Opening Reports and click Finish.
127
4. Right-click the New Account Opening Reports category and select New > Simple Report.
5. In the Name field enter New Account Applications and click Finish. The report design canvas
appears.
6. On the Palette, click the Process report entity category. A list of report entities displays.
7. Click and drag the Process Execution report entity to the canvas and select the following fields:
Duration (hh:mm:ss)
Finished Date and Time
Process
Process Instance ID
Start Date and Time
128
8. Right-click the Process Execution report entity and select Filter. The Filter dialog opens.
9. Click the Processes (PRO) tab and open the Processes filter item.
10. Double-click New Account Applications. The filter expression is displayed in the Filter
Expression field.
Note: It is important that a filter be designed so that other monitored processes are not included in
this report. Later in this appendix you will learn to create a series of other mock processes that
are used to help design business data reports. It is important that these mock processes be filtered
out of the New Account Applications report.
11. Click OK. The Filter dialog closes and you are brought back to the report design canvas.
129
12. Click the Refresh button

process instances.
in the Data Source Preview window. You should see a list of
Note: If you dont see a list of the process instances you started in TaskSpace, then check the
Process Properties dialog in Process Builder to make sure the Audit Trail is turned on.
130
13. Click the Chart Data tab to establish the order of the columns as they appear in the table. In this
example:
a.
b.
c.
d.
e.
Select Process in Column-1.

Select Start Date and Time in Column-2.
Select Finished Date and Time in Column-3.
Select Duration (hh:mm:ss) in Column-4.
Select none in Column-5.
14. Click the Drilldown row in Column-1 and click the browse button (...). The Drilldown dialog
opens.
15. Click the Dashboard Event radio button and select Process Instance from the list box.
16. Click OK to close the Drilldown dialog.

131
17. State list box and then save the report. Publishing the report makes it available to use in a
dashboard.
In the next section you will design a dashboard and add to it the New Account Applications report, the
Alert List dashlet, and the Process Diagram dashlet.

In this section you will design a dashboard in TaskSpace and add three dashlets: the New Account
Applications report, the Alert List dashlet, and the Process Diagram dashlet. Later in this appendix you
will design business data reports and also add them to this dashboard.
The Alert List dashlet displays a list of processes or activities that have met or exceeded an alert
threshold. Alerts are defined in PRS, with a data source and an alert expression that defines the
threshold. Once an alert is triggered, its details are displayed in the Alert List dashlet including the
alert status, severity, and start and stop times. Initially, the Alert List dashlet displays a list of all alerts
in the system. However, when a user clicks a process instance in the New Account Applications report,
the Alert List is automatically filtered to show only the alerts that were generated for the selected
process instance. This document does not describe how to design alerts in PRS. It focuses on adding
the dashlet in the event that alerting is important in your situation. For more information on how to
design alerts in PRS, refer to the Business Activity Monitor Implementation Guide.
The Process Diagram is another type of dashlet included with the BAM software. The diagram dashlet
is designed to distinguish between those activities that are in-process and those that are completed.
Activities annotated with a green check mark are completed, and activities annotated with a gear icon
are in-process. By configuring the Process column of the New Account Applications report as a
multi-drill-down, the Process Diagram dashlet displays the progress of the process selected in the New
Account Applications report. This is tested when the dashboard is designed.
It is assumed that you do not have a TaskSpace application to which you are adding a dashboard. If
you already have a TaskSpace application then you can skip steps 35 and just add a dashboard
to the TaskSpace application you already have.
To design a dashboard and add dashlets:
1. Log in to TaskSpace.
132
2. Click the Configuration tab.

3. Click the New Application button, in the Name field enter FinanceCorp and in the Label field
enter Finance Corp.
4. Click OK. This closes the Create Application window and opens the Confirmation window.
Note the URL of the TaskSpace application and log in to the new application.
5. Click the Configuration tab and select Dashboards from the menu.
6. Click the Create button. The Create Dashboard Configuration window opens.
7. In the Name field enter NewAccountApplications and in the Label field enter New Account
Applications.
8. Click Next. The dashboard design canvas opens.
9. Expand Report Categories > New Account Opening Reports.
10. Click and drag the New Account Applications report to the canvas.
11. Click and drag the Alert List dashlet and place it under the New Account Applications report.
133
12. Click and drag the Process Diagram dashlet and place it under the Alert List dashlet.
13. To test that the multi-drill-down between the New Account Applications report and the Process
Diagram dashlet works, click any of the New Account Applications hyperlinks. The Process
Diagram dashlet displays an image of the process you selected, and indicates those activities
that are complete, incomplete, and in-process.
14. Click Save and then click Finish. You are brought back to the Dashboards window. You will add
more dashlets to the dashboard at the end of this document.
134

This section focuses on the design of a process duration alert that triggers whenever in-flight New
Account Applications processes exceed one minute in duration. Alerts are comprised of a data source
and an alert expression. Since the goal of this alert is to identify those in-flight processes that exceed
one minute, the Incomplete Process Execution entity is used in the data source. If, however, the
purpose of an alert was to list completed processes that exceeded the threshold, then the Process
Execution entity would be used in the data source. The alert expression defines the duration threshold
(in minutes) and constrains the alert to the New Account Applications process only. The one minute
threshold allows you to see the alert populated in the dashboard two minutes after the process is started
(the system considers 1.9 minutes within the first minute). At the moment an alert is triggered the
details are displayed in the Alert List dashlet in the dashboard you created.
Note: Alerts cannot be triggered on processes started prior to the design and publishing of an alert.
Historical process data can be used to test that an alert expression is valid, but the alert details
are not displayed in a dashboard. Alerts are constrained to those processes that are started after the
alert is defined.
In this procedure you create an alert category, design and test an alert, and start a process so the
alert is triggered and displayed in the dashboard.
To design a Process Duration alert:
1. Log in to PRS.
2. Click the Alerts tab.
135
3. From the File menu select New > Category. The New Category dialog appears.
4. In the New Category Name field enter New Account Applications and click Finish. The New
Category dialog closes and the category is displayed on the tree menu.
5. On the tree menu, click the New Account Applications category.
6. From the File menu select New > Alert. The New Alert dialog appears.
7. In the New Alert name field enter Process Duration Alert and click Finish. The New Alert
dialog closes and the alert design canvas opens. Your next step is to define the alert data source.
8. On the Palette, click Process.

9. Click and drag the Incomplete Process Execution entity to the design canvas.
10. Deselect the Ongoing Duration (seconds) field.
11. Select the Ongoing Duration (minutes) field.
12. Click the Alert tab that is located next to the DataSource tab.
136
13. From the State list box select Published. This makes the alert operational in the dashboard
once the alert expression is defined and saved.
14. Place your cursor in the Expression field and press the Ctrl-space keys simultaneously. A list of
fields that can be used in an alert expression is displayed.
15. Double-click ${Ongoing Duration (minutes)}. The ${Ongoing Duration (minutes)} field is
added to the alert expression.
16. On the keypad, click the greater than symbol (>) and then enter 1.
137
17. On the keypad, click the && button. You are defining a compound expression that limits the alert
to those New Account Applications processes that exceed 1 minute.
18. Press the Ctrl-space keys simultaneously.
19. Double-click ${Process} and then click the = = button on the keypad.
20. Enter "New Account Applications" (including the quotation marks) after the equals symbol (= =).
Note: You do not need to configure the email.
in the Data Source Preview window and
21. To test the alert expression, click the Refresh button
click OK on the Confirm Save dialog. Processes displayed in bold have exceeded the threshold.
In the following steps, you start a new process instance so that the alert displays in the dashboard.
22. Within TaskSpace, click the Processes tab and start the New Account Applications process and
wait a few minutes.
138
23. Click the Configuration tab and on the tree menu select Dashboards.
24. Click the New Account Applications dashboard and click Edit.
25. Click Next on the Modify Dashboard Configuration window. The dashboard design canvas opens.
26. Within the New Account Applications report, locate the New Account Applications process you
started in Step #22 and click it. The Alerts List dashlet displays the duration alert triggered for
that specific process.
New Account Process - Average Duration

The New Account Process report is a dial gauge that displays the average duration of the New Account
Applications process. In a real deployment, dial gauges measure average process duration over some
specified period of time. A prototype of this report relies on creating a process in Process Builder that
consists of two steps, a manual activity and an automated activity. An SDT is also created which
includes a single attribute: Value. The SDT is assigned to the manual activity, and as the process
executes a user can enter an average duration value. The needle on the dial gauge points to the average
duration value. If you enter a duration value greater than 100, then you may need to adjust the range
properties of the report in the Chart Properties window in PRS.
The following topics include procedures for designing, running, and reporting on the New Accounts
Process - Average Duration.
Designing the New Account Process - Average

Duration process
1. Create the following process in Process Builder. The first activity is manual. It submits the SDT
data. The second activity is automated and is used to end the workflow.
139
2. From the File menu select New > Structured Data Type. The Add Structured Data Type Wizard
dialog appears.
3. In the Name field enter AverageDuration and in the Display Name field enter Average Duration.
4. Select the Update BAM Database tables based on this SDT definition checkbox.
5. Click the Add Attributes button
6. In the Name field enter Value. In the Display Name field enter Value. As the process runs this field
is populated with the average duration it takes to complete the New Account Applications process.
7. In the Type list box select INT.
8. Select both the Searchable and Reportable checkboxes.
9. Click OK.
140
10. Select Tools > Process Properties to open the Process Properties dialog.
11. Click the Data tab.
12. Highlight Process Variable and then click the Add new process data button
13. From the Type list box, select <More Types>. The Choose Structured Data Type dialog appears.
14. Select Average Duration and click OK. You are brought back to the Process Properties dialog.
141
15. Click the General tab.

16. Turn the Audit Trail On.
17. Click OK. The Process Properties window closes.
18. For the manual activity, open the Activity Inspector window.
19. Select the Data tab.
20. Select the process variable and then select the This variable can be used to generate reports
checkbox.
142
21. Click OK. The Activity Inspector window closes.
22. Open the Activity Inspector for the automated activity.

23. Click the Performer tab and select dm_noop_auto_method as the method.
24. Click OK to close the Activity Inspector dialog.
25. Save, validate, and install the process. Enter AverageDurationReport as the name of the process.

1. Log in to TaskSpace and click the Processes tab.
2. Locate and select the AverageDurationReport process and click the Start Process button.
143
3. Click Finish. You do not need to add a workflow description.
4. Click the Tasks tab.

5. Locate Activity-1 and double-click it.
6. Click the Process Variables tab.
7. Enter a number in the Value field. It can be any number you want. It is meant to represent
average duration.
8. Click Finish and then click OK. You are now ready to design a report that uses the average
duration value you just entered.
144

1. Log in to PRS.
2. Right-click the New Account Opening Reports category and select New > Simple Report. The
New Simple Report dialog opens.
3. In the Name field, enter New Account Process - Average Duration and click Finish.
4. From the Palette, select the Business Data report entity category.
5. Click and drag the AverageDuration report entity to the canvas. By default the Value field
is selected.
6. Click the Refresh button in the Data Source Preview window. The value you entered during
the process displays.
7. Click the Chart Type tab.

145
8. In the Type property, select Gauge from the list box.

The report format adjusts to become a dial gauge with the arrow pointing to the value you entered
during the process.
Note: You may need to adjust the range values in the Chart Properties window.
9. To adjust the range values, click the Chart Properties tab.

10. Select a range property and enter a new value. The properties you can modify include the dial
lower and upper limits, Range-1 (From/To), Range-2 (From/To), and Range-3 (From/To).
11. To enter a title (or subtitle) select the appropriate property and enter a title. The title displays
above the dial gauge.
12. Select Published in the State list box and then save the report. Publishing the report makes
it available to use in a dashboard.
146
New Accounts by Customer Type

New Accounts by Customer Type is a pie chart that is configured as the target in a single drill-down
report configuration. When a user selects any of the bars in the New Accounts Opened This Week
report, the New Accounts by Customer Type report displays. The first step is to create a mock process
in Process Builder that consists of a manual and automated activity. An SDT captures information
about the number of accounts for each account type (i.e. Gold, Platinum, or Silver). This process
must be executed three times.
The following topics include procedures for designing, running, and reporting on the New Accounts
by Customer Type process.
Designing the New Account by Customer Type

process
1. Create a process in Process Builder. The first activity is manual. It submits the SDT data. The
second activity is automated and is used to end the workflow.
2. Create an SDT and in the Name field enter CustomerType and in the Display Name field enter
Customer Type.
3. Add two attributes to the SDT. In the Name field of the first attribute enter AccountType.
4. In the Display Name field enter Account Type. As the process runs you will populate this field
with either Gold, Platinum, or Silver.
5. In the Type list box select String.
6. Select both the Searchable and Reportable checkboxes.
7. Select the Update BAM Database tables based on this SDT definition checkbox.
8. Create a second attribute.
a. In the Name field enter AccountTypeAmount.

b. In the Display Name field enter Account Type Amount.
c. In the Type list box select INT.
d. Select both the Searchable and Reportable checkboxes.
9. Click OK.
147
Designing the New Account by Customer Type process
12. Highlight Process Variable and then click the Add new process data button.
13. From the Type list box select Customer Type.
14. Click the General tab.
15. Turn the Audit Trail On.
16. Click OK. The Process Properties window closes.
17. For the manual activity, open the Activity Inspector window.
18. Select the Data tab.
19. Select the process variable and then select the This variable can be used to generate reports
checkbox.
20. Click OK. The Activity Inspector window closes.
21. Open the Activity Inspector for the automated activity.
22. Click the Performer tab and select dm_noop_auto_method as the method.
23. Click OK to close the Activity Inspector dialog.
148
24. Save, validate, and install the process. Enter New Account Customer Type as the name of
the process.
Running the New Accounts by Customer Type

process
2. Click the Processes tab.
3. Locate and select the New Account Customer Type process and click the Start Process button.
4. Click Finish on the Start Workflow: Info window. You do not need to add a description.
5. Click the Tasks tab.
6. Locate Activity-1 and double-click it.
7. Click the Process Variables tab.
8. In the AccountType field enter Gold. In the AccountTypeAmount field enter 100.
9. Click the Finish button and then click OK on the Finish window.
149
Designing the New Accounts by Customer Type report
10. Repeat steps 29 twice and enter the following data:

AccountType
AccountTypeAmount
Platinum
30
Silver
1000
After you have completed three processes, you are ready to design the New Accounts by Customer
Type report.
Designing the New Accounts by Customer Type

report
1. Log in to PRS.
3. In the Name field enter New Accounts by Customer Type and click Finish.
4. From the Palette select the Business Data report entity category.
5. Place the CustomerType report entity on the canvas. By default the AccountType and
AccountTypeAmount fields are selected.
6. Click the Refresh button in the Data Source Preview window. The values you entered during
the process display.
150
7. Click the Chart Type tab and in the Type property select Pie.
8. Click the Chart Data tab.
9. In the Category (X) axis property select AccountType and in the Value (Y) axis property select
AccountTypeAmount.
Note: It is possible that the category and value properties are correctly configured by default,
which means that the pie chart displays correctly and you do not have to do anything.
it available for use in a dashboard.
New Accounts Opened This Week

New Accounts Opened This Week is a bar chart report that provides the number of new accounts
opened during the week for each of five counties. As with the other reports, a mock process consisting
151
Designing the New Accounts Opened this Week process
of a manual activity and automated activity is designed. An SDT captures information about the
number of accounts for each of five countries. This process must be executed five times. The country
column in the data source is configured as a single drill-down, so that when a bar is selected in
the report, the contents of the New Accounts by Customer Type report displays. This drill-down
relationship is tested once you complete the dashboard.
These topics include procedures for designing, running, and reporting on the New Accounts Opened
This Week process.
Designing the New Accounts Opened this Week

process
2. Create an SDT and in the Name field enter AccountsThisWeek. In the Display Name field
enter Accounts This Week.
3. Add two attributes to the SDT. In the Name field of the first attribute enter Country.
4. In the Display Name field enter Country. As the process runs you will populate this field with
five different countries.
6. Select the Searchable, Reportable and Update BAM Database tables based on this SDT
definition checkboxes.
a. In the Name field enter NewAccounts.

b. In the Display Name field enter New Accounts.
c. In the Type list box select INT.
d. Select both the Searchable and Reportable checkboxes.
8. Click OK.
152
12. From the Type list box select Accounts This Week and then click the General tab.
13. Turn the Audit Trail On and click OK. The Process Properties window closes.
14. For the manual activity, open the Activity Inspector window and select the Data tab.
15. Select the process variable (Var0), select the This variable can be used to generate reports
checkbox, and click OK. The Activity Inspector window closes.
16. Open the Activity Inspector for the automated activity and click the Performer tab.
17. Select dm_noop_auto_method as the method and click OK to close the Activity Inspector dialog.
18. Save, validate, and install the process. Enter Accounts This Week as the name of the process.
Running the New Accounts Opened this Week

process
153

3. Locate and select the Accounts This Week process and click the Start Process button.
5. Click the Tasks tab, locate Activity-1, and double-click it.
6. Click the Process Variables tab and in the Country field enter Belgium. In the NewAccounts
field enter 100.
8. Repeat steps 27 four times and enter the following data:
Country
NewAccounts
Germany
1200
France
1000
Denmark
600
Czech Republic
1130
After you have completed five processes, you are ready to design the New Accounts Opened this
Week report.
Designing the New Accounts Opened this Week

report
1. Log in to PRS.
3. In the Name field enter New Accounts this Week and click Finish.
4. From the Palette select the Business Data report entity category and place the AccountsThisWeek
report entity on the canvas. By default the Country and NewAccounts fields are selected.
5. Click the Refresh button in the Data Source Preview window. The values you entered during
the process display.
154
6. Click the Chart Type tab and in the Type property select Bar.
7. Click the Chart Data tab and in the Category (X) axis property select Country and in the Value
(Y) axis property select NewAccounts.
Note: It is possible that the category and value properties are correctly configured by default.
8. Select the Drilldown property and click the browse button (...). The Drilldown dialog opens.
9. Click the Report radio button and then click the Browse button. The Select Target Report dialog
opens.
155
10. Select the New Accounts by Customer Type report and click OK. The Select Target Report dialog
closes.
11. Click OK to close the Drilldown window.

it available for use in a dashboard.
156
New Accounts Opened Last Week

This report shows the number of new account applications submitted each day during the last week. It
provides a trend over time. There is also a horizontal line in the report that represents a SLA value that
represents the target number of applications to be received each day. In this scenario the SLA (defined
as 4500 applications) was missed on Wednesday when only 3000 applications were received. The
report displays five ordered pairs of data values: (Monday, 5000), (Tuesday, 4000), and so on. This
data is populated by a process and an SDT that contains a Date and Amount attribute. A third attribute
called Order is used for sorting purposes, so that the days of the week appear in order on the report.
These topics include procedures for designing, running, and reporting on the New Accounts Opened
Last Week process.
Designing the New Accounts Opened Last

Week process
2. Create an SDT with the name AccountsLastWeek and the display name Accounts Last Week.
3. Add three attributes to this SDT. In the Name field of the first attribute enter Date and in the
Display Name field enter Date. As the process runs five times, you will populate this field with
one of five different days of the week.
157
Designing the New Accounts Opened Last Week process

5. Select the Searchable, Reportable and Update BAM Database tables based on this SDT
definition checkboxes.
a.
b.
c.
d.
In the Name field enter Amount.

In the Display Name field enter Amount.
In the Type list box select INT.
Select both the Searchable and Reportable checkboxes.
7. Create a third attribute.
a.
b.
c.
d.
In the Name field enter Order.

In the Display Name field enter Order.
In the Type list box select INT.
Select both the Searchable and Reportable checkboxes.
8. Click OK.
12. From the Type list box select Accounts Last Week and then click the General tab.
13. Turn the Audit Trail On and click OK. The Process Properties window closes.
14. For the manual activity, open the Activity Inspector window and select the Data tab.
15. Select the process variable (Var0), select the This variable can be used to generate reports
checkbox, and click OK. The Activity Inspector window closes.
158
16. Open the Activity Inspector for the automated activity and click the Performer tab.
17. Select dm_noop_auto_method as the method and click OK to close the Activity Inspector dialog.
18. Save, validate, and install the process. Enter Accounts Last Week as the name of the process.
Running the New Accounts Opened Last Week

process
3. Locate and select the Accounts Last Week process and click the Start Process button.
5. Click the Tasks tab, locate Activity-1, and double-click it.
6. Click the Process Variables tab and in the Date field enter Monday. In the Amount field enter
5000. In the Order field enter 1.
8. Repeat steps 27 four times and enter the following data:
Date
Amount
Order
Tuesday
4000
Wednesday
3000
Thursday
6000
Friday
5000
After you have completed five processes, you are ready to design the New Accounts Opened Last
Week report.
159

In this section, you will add the remaining reports to the prototype dashboard and test that the single
drill-down report works.
To complete the prototype dashboard:
1. Launch TaskSpace and log in to the dashboard application you created earlier.
2. Click the Configuration tab and then click Dashboards from the menu.
3. Click the dashboard you created earlier and then click the Edit button.
4. Click Next on the Modify Dashboard Configuration window. The dashboard design canvas opens.
5. Select Report Categories > New Account Opening Reports.
6. Click and drag the New Account Process - Average Duration report and place it next to the New
Account Applications report. Adjust the size of the dashlets if necessary.
7. Click and drag the New Accounts This Week report and place it next to the Alert List dashlet.
Adjust the size of the dashlets if necessary.
8. Click and drag the New Account Last Week report and place it next to the Process Diagram
dashlet. Adjust the size of the dashlets when necessary.
9. Test the single drill-down report by clicking any of the bars in the New Accounts This Week
report. The New Accounts by Customer Type report displays, along with a trail of bread crumbs
for navigating back to the source report.
160
10. Click Save and then click Finish. Your prototype dashboard is complete.
161
Index
A
activities
count children, 45
wait, 45
adaptors, 75
controls, 75
types, 75
uses, 75
aggregation, 92
application
phases, 17
planning, 18
application servers
settings, 100
archiving
application, 111
attachments
using, 66
audit trail
configuring, 58
enabling, 58
automated activities, 60
automated system, advantages, 9
automatic activities
performance, 98
B
BAM
Crystal reports, 91
dashboard design, 90
enabling packages reporting, 58
enabling SDT monitoring, 58
external database, 59
process variables reporting, 58
purging production environments, 92
reporting, 58
reporting requirements, 89
simple reports, 91
synchronizing BAM database, 59
system requirements, 89
BAM database
synchronizing , 59
BAM reporting
configuring audit trail, 58
enabling, 58
Business Activity Monitor, 58
See also BAM
business process management products, 13
business requirements, 19
C
choose one automatic performer
process design, 59
Composer
deploying, 108
process performers, 108

process templates, 108
using, 109
conditional routing, 35
configurable actions, 65
attachments, 66
guidelines, 87
content server, 14
settings, 101
Crystal reports, 91
custom object types, 42
D
dashboards
design considerations, 90
pre-configured, 93
refresh intervals, 93
data adaptors, 75
data mapper, 37
data mapping
input context, 38
multi-valued attributes, 41
repeating attributes, 37
XML support, 42
data model
description, 29
permissions, 20
planning, 29
roles, 20
database
references, 108
database server
settings, 105
deploying
application, 107
Composer version, 108
steps, 107
deployment, 107
Composer version, 108
deleting SDTs, 109
migrating, 61
overwriting existing process, 109
planning, 28
setting up, 20
updating database references, 108
upgrading, 61
versioning process templates, 109
DFC trace, 105
disabling
full-text indexing, 103
document view, 70
documents
displaying inline, 70
Documentum repository, 14
Documentum xCP products, 14
163
Index
EMC products, 11
enterprise content management platform, 14
enterprise content management products, 13
environment
application server settings, 100
content server settings, 101
database server settings, 105
environments
purging , 92
error messages, 74
object types
custom object types, 42
F
folders
form templates
creating, 63
forms
electronic forms, 69
performance, 98
full-text events
purging, 104
full-text indexing
disabling, 103
I
implementing
TaskSpace, 85
initiate process template, 69
J
JVM capacity, 100
L
logins
performance, 100
looping
count children activity, 45
defining, 42
simple loop, 43
wait activity, 45
M
manual archive
Documentum, 112
testing, 116
troubleshooting, 118
message correlation, 36
migrating, 61
monitoring
enabling SDTs, 58
164
P
package attributes
monitoring, 31
SDTs
using, 30
using, 30
packages, 29
description, 30
electronic forms, 69
enabling reporting, 58
performance, 98
analyzing, 105
automated workflow activities, 60
automatic activities, 98
configuration recommendations, 97
impactors to, 98
large configurations, 97
logins, 100
mandatory search attributes, 99
medium configurations, 96
preconditions, 99
SDTs, 60
search criteria, 98
search forms, 98
skill set matching, 100
small configurations, 96
system configuration, 96
task lists, 99
tuning, 105
wildcard searches, 98
permissions, 20
process data, 29
process debugger
debugging custom methods, 56
using, 55
process design
BAM, 57
choose one automatic performer, 59
process parameters, 29
using, 31
process performers, 108
process templates
Composer, 108
versioning, 109
process variables, 29
enabling reporting, 58
types, 29
processes
activity names, 31
child process, 50
designing, 33
designing activities, 33
Index
designing activity triggers, 34

initiate process template, 69
making changes, 31
mapping data, 37
options for after a process starts, 69
overwriting existing process, 109
starting, 64
starting using a search template, 64
starting using an attachment, 66
starting using configurable actions, 65
sub-processes, 36
using a form in a package, 69
versioning, 61
wait activities, 34
processes tab, 64
project plan, 19
prototyping, 21
purging
development production, 92
full-text events, 104
performance, 100
structured data types, 29
See also SDTs
system configuration
guidelines, 96
large configurations, 97
medium configurations, 96
recommendations, 97
small configurations, 96
system design, 20
reporting
configuring audit trail , 58
configuring audit trail settings, 58
Crystal reports, 91
data in an external database, 59
enabling, 58
packages, 58
process variables, 58
simple reports, 91
reporting requirements
BAM, 89
reports
drill-down, 93
formatting, 93
roles, 20
task lists
performance, 99
task templates
displaying multiple packages, 72
document view, 70
folder view, 71
using, 86
task view
designing, 70
tasks
sending to temporary group, 34
TaskSpace
adding buttons to a task form, 86
assigning current object actions to
menus, 87
current object actions, 87
finish buttons failing on a task form, 86
implementing, 85
iterative rollout, 85
metadata pane in a folder view, 86
preconditions, 99
selected object actions, 87
task lists, 99
tomcat server
settings, 100
SDTs
accessing attributes, 61
deleting, 109
description, 29
enabling monitoring, 58
monitoring, 31
performance, 60
search forms
criteria, 98
mandatory search attributes, 99
performance, 98
wildcard searches, 98
search template
using, 64
service-oriented architecture, 14
simple reports, 91
skill set matching
upgrading, 61
user interface
design tips, 63
form templates, 63
search templates, 64
V
versioning
processes, 61
W
workflow
automated activities, 60
165

XCP 1.6 BestPracticesGuide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

XCP 1.6 BestPracticesGuide

Uploaded by

Copyright:

Available Formats

EMC Documentum

Best Practices Guide

Planning and Designing the Application ........................................................17

Creating the Data Model .................................................................................29

Designing the Process ...................................................................................33

Creating the User Interface.............................................................................63

Monitoring Business Activity .........................................................................89

Cleaning production environments.....................................................................92

Performance and Scalability...........................................................................95

Deploying the Application ............................................................................ 107

Archiving the Application............................................................................. 111

Prototyping Business Activity Monitor dashboards..................................... 121

BAM topic updated: Crystal Reports versus Simple Reports.

Advantages of using an automated system

Recommended approach to solution construction

An example: a Grants Management application

Advantages of using an automated system

Recommended approach to solution

An example: a Grants Management application

This scenario is an example of a case management application. It triggers several processes to

Documentum ECM platform

Business process management

Documentum ECM and BPM products

Documentum ECM platform

Content management and repository services

Business process management

Documentum TaskSpace provides a highly configurable user interface

Process Builder is a business process design tool that allows

Forms Builder is used to create web-based graphical user interfaces

Documentum Business Activity Monitor (BAM) and Process Reporting

Documentum Collaborative Services (DCS) provide team collaboration

Data and content

Process Integrator manages both inbound and outbound integration of data

Captiva InputAccel provides intelligent capture for paper, fax, and

Document Sciences xPression automatically generates and distributes

Planning and designing the application overview

Business requirements phase

Roles and permissions

Setting up the Development Environment

System Design and Prototyping Phase

Planning the Deployment

Planning and designing the application

Planning and Designing the Application

Read the documentation

Read the documentation

Define project roles

EMC Project Manager

Planning and Designing the Application

Create a Project Plan

Business requirements phase

Current technical environment

Interpreting the intentions of the client

Planning and Designing the Application

Roles and permissions

Setting up the Development Environment

System Design and Prototyping Phase

Planning and Designing the Application

The Data Model

Prototyping and Workshops

Example: Process Builder

Planning and Designing the Application

Planning and Designing the Application

Planning and Designing the Application

Dashboard User Summary