Designing processes - EMC Community Network

EMC ® Documentum ® 

xCelerated Composition 

Platform 

Version 1.6 

Best Practices Guide 

EMC Corporation 

Corporate Headquarters: 

Hopkinton, MA 01748–9103 

1–508–435–1000 

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 

Chapter 2 

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 

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 3


Chapter 6 

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 

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 

4 EMC Documentum xCelerated Composition Platform Version 1.6 Best Practices Guide


Chapter 8 

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 

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 

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 

April 2011 

August 2011 

Description 

Initial publication 

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. 


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. 


Overview 


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 



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: 



Application 

presentation and 

composition 

Business process 

design and workflow 

configuration 

Application GUI 

design 

Reports 

Team collaboration 

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. 

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. 

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. 

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. 

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. 



Process automation, 

services orchestration, 

human task 

management 

Data and content 

integration 

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. 

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 

Information capture 

and input 

Dynamic 

correspondence 

generation 

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. 

Captiva InputAccel provides intelligent capture for paper, fax, and 

electronic data sources 

Document Sciences xPression automatically generates and distributes 

customer communications via customer-preferred formats and channels 

(e-mail, web, print, and mobile). 


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. 



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. 



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 user’s 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 



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 



• 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 

client’s 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. 



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. 



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: 



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) 



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: 



Figure 2 

Number of new accounts by country 

Figure 3 

Number of new accounts by customer type 



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 



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. 


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, 



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: 



• 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 



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 attribute’s 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. 


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 



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 user’s 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 else’s 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. 



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: 



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 



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 mapper’s 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. 



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 



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: 



The end result is: 



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. 



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. 



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 



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. 



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. 



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. 



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: 





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. 



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: 



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: 



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: 



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: 



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: 



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 Builder’s 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 



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. 



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 



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. 



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. 



Performance and stability of executing automated 

workflow activities 

The Process Engine’s 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 



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/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. 




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 



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. 



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. 



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. 



2. Configure how the object is routed by selecting Dynamic Object Value Selection. 

3. Select Objects to be routed. 



4. Select the specific process. 



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. 



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/...//DocumentId (you can also bind to a process variable assuming that 

the variable value is an object ID). 



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. 



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 



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. 



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 



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 

Item Initializer 

Available Templates 

or Controls 

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 

Best Uses/Limitations 

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. 



Adaptor Type 

Item Validator 

Document 

Validator 

Data Source 


or Controls 

Not available on high 

fidelity templates 



RichText, Number Field, 

Date Field, DateTime 

Field, CheckBox, 


Radio Button Group, 


List, Comment history, 

Readonly Table, Slider, 

Embedded Form, and 

Filter 





Available on selection 

controls only: 



List, and Readonly 

Table 


Use this adaptor if you want to validate a user’s 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. 

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. 

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. 



Adaptor Type 

Data Source Set 

Value 

Document 

Processor - 

Initialization 

Document 

Processor - 

Pre-submission 

Document 

Processor - 

Post-submission 


or Controls 





Number Field, Date 

Field, DateTime 

Field, Radio Button 

Group, CheckBox, 


List, Package, Slider, 

and Embedded Form 


information, process 

parameter, task, or high 



contents, process 

instance list, search, 

task list, or high fidelity 

templates 


contents, process 

instance list, process 

parameter, search, task 

list, or high fidelity 

templates 


Use this adaptor to automatically populate one field on the 

template. There are two types of Set Value adaptors: 

• 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. 

• On Init - populates a field when the form renders at runtime. 

An initialization adaptor initializes values for the entire form. 

On a document view template, the initialization executes only 

when the document view is used while importing documents 

in TaskSpace. 

A pre-submission adaptor executes prior to form submission 

provided the validation succeeds, then the form is saved. 

A post-submission adaptor executes after a form is submitted. 

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. 



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. 



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. 



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). 



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: 



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 ${} (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. 



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. 



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-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 

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: 



• 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. 



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 template’s 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 frameset’s 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. 



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. 




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: 



• 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. 



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 



(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. 



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. 



• 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. 


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. 



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: 









• 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: 







• 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. 



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 



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 tag. 



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 user’s 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 



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 tag of the web.xml file. 

• In web.xml, you can increase the value of 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) 

 

 

 

 

 



 

 

 

 

 

 

 

 

 

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) 

 

 

 

 

 

 

 

 

 

 

 

 

 

 



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 full‐text 

indexing. 



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 full‐text 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 type’s 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. 



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 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. 




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. 



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 



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. 




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. 



• 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. 



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. 



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. 



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 ...\\\bin‐dar directory. 



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. 



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. 



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://:/taskspace/component/main/appname= 

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. 



• 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. 




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 




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: 


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. 



• 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 don’t 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 

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 week’s 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. 


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. 



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. 



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 



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. 



12. Click the Refresh button in the Data Source Preview window. You should see a list of 

process instances. 

Note: If you don’t 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. 



13. Click the Chart Data tab to establish the order of the columns as they appear in the table. In this 

example: 

a. Select Process in Column-1. 

b. Select Start Date and Time in Column-2. 

c. Select Finished Date and Time in Column-3. 

d. Select Duration (hh:mm:ss) in Column-4. 

e. 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. 



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 3–5 and just add a dashboard 

to the TaskSpace application you already have. 

To design a dashboard and add dashlets: 

1. Log in to TaskSpace. 



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. 



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. 




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: 


2. Click the Alerts tab. 



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. 



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. 



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. 

21. To test the alert expression, click the Refresh button in the Data Source Preview window and 

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. 



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. 



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. 



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 . The Choose Structured Data Type dialog appears. 

14. Select Average Duration and click OK. You are brought back to the Process Properties dialog. 



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. 



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. 



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. 





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. 



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. 



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. 


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. 



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. 


Designing the New Accounts by Customer Type report 

10. Repeat steps 2–9 twice and enter the following data: 

AccountType 

Platinum 30 

Silver 1000 

AccountTypeAmount 

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 




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. 



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 


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. 



8. Click OK. 






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 





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 2–7 four times and enter the following data: 

Country 

Germany 1200 

France 1000 

Denmark 600 

Czech Republic 1130 

NewAccounts 

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 




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. 



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. 



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. 



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. 


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. In the Name field enter Amount. 

b. In the Display Name field enter Amount. 



7. Create a third attribute. 

a. In the Name field enter Order. 

b. In the Display Name field enter Order. 



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. 



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 2–7 four times and enter the following data: 

Date Amount Order 

Tuesday 4000 2 

Wednesday 3000 3 

Thursday 6000 4 

Friday 5000 5 

After you have completed five processes, you are ready to design the New Accounts Opened Last 

Week report. 




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. 



10. Click Save and then click Finish. Your prototype dashboard is complete. 


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 


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 


Index 

E 

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 

F 

folders 


form templates 

creating, 63 

forms 

electronic forms, 69 


full-text events 

purging, 104 

full-text indexing 

disabling, 103 

I 

implementing 

TaskSpace, 85 

initiate process template, 69 

J 

JVM capacity, 100 

L 

logins 


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 

O 

object types 

custom object types, 42 

P 

package attributes 

monitoring, 31 

SDTs 

using, 30 

using, 30 

packages, 29 



electronic forms, 69 

enabling reporting, 58 


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 

R 

reporting 

configuring audit trail , 58 

configuring audit trail settings, 58 


data in an external database, 59 

enabling, 58 

packages, 58 

process variables, 58 


reporting requirements 

BAM, 89 

reports 

drill-down, 93 

formatting, 93 

roles, 20 

S 

SDTs 

accessing attributes, 61 

deleting, 109 


enabling monitoring, 58 

monitoring, 31 


search forms 

criteria, 98 

mandatory search attributes, 99 


wildcard searches, 98 

search template 

using, 64 

service-oriented architecture, 14 


skill set matching 


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 

T 

task lists 


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 

U 

upgrading, 61 

user interface 

design tips, 63 

form templates, 63 

search templates, 64 

V 

versioning 


processes, 61 

W 

workflow 

automated activities, 60

Designing processes - EMC Community Network

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?