OpenText Documentum XCelerated Composition Platform CE 22.2 - Deployment Guide English (EDCPKL220200-IGD-En-01)

OpenText™ Documentum™ xCelerated
Composition Platform
Deployment Guide
This guide describes how to provision Documentum xCelerated

Composition Platform (xCP) environments and deploy xCP
applications into those environments.
EDCPKL220200-IGD-EN-01
OpenText™ Documentum™ xCelerated Composition Platform
Deployment Guide
EDCPKL220200-IGD-EN-01
Rev.: 2023-Jan-11
This documentation has been created for OpenText™ Documentum™ xCelerated Composition Platform CE 22.2.
It is also valid for subsequent software releases unless OpenText has made newer documentation available with the product,
on an OpenText website, or by any other means.
Open Text Corporation
275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1
Tel: +1-519-888-7111
Toll Free Canada/USA: 1-800-499-6544 International: +800-4996-5440
Fax: +1-519-888-0677
Support: https://support.opentext.com
For more information, visit https://www.opentext.com
Copyright © 2023 Open Text. All Rights Reserved.

Trademarks owned by Open Text.
One or more patents may cover this product. For more information, please visit https://www.opentext.com/patents.
Disclaimer
No Warranties and Limitation of Liability
Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However,
Open Text Corporation and its affiliates accept no responsibility and offer no warranty whether expressed or implied, for the
accuracy of this publication.
Table of Contents
1 Getting Started ......................................................................... 11
1.1 Deployment environments overview ................................................. 11
1.2 Deployment methods ...................................................................... 12
1.3 Managing environments .................................................................. 12
1.4 Upgrading an environment ............................................................... 12
1.5 Updated attributes for REST API properties ...................................... 13
1.6 Security configuration ...................................................................... 13
2 Manually provisioning an xCP environment ......................... 15

2.1 Overview ........................................................................................ 15
2.2 Manual provisioning ........................................................................ 16
2.3 Prerequisites .................................................................................. 16
2.4 Installing and configuring xCP components and third-party software ... 17
2.5 xCP deployment scenarios .............................................................. 19
2.6 Installing Document Image Services ................................................. 21
2.6.1 Installing the Document Image Services DAR file .............................. 22
2.6.2 Enabling page serving on the BOCS server ...................................... 22
2.7 Installing the xCP Viewer Services DAR ........................................... 22
2.7.1 Checking ACS server for xCP Viewer ............................................... 22
2.8 Configuring the xCP Advanced Viewer ............................................. 23
2.9 Installing Brava! Enterprise for Documentum xCP ............................. 24
2.10 Installing the Job Processor ............................................................. 25
2.11 Installing the Brava! Server .............................................................. 26
2.12 Installing Process Engine ................................................................. 27
2.12.1 Starting the Connection Broker and all repositories ........................... 27
2.12.2 Preparing non-Windows Platforms for Process Engine installation ...... 27
2.12.3 Installing Process Engine ................................................................. 28
2.12.3.1 Installing Process Engine in silent mode ........................................... 29
2.12.4 Adding Process Engine to a new repository ...................................... 30
2.12.5 Installing Process Engine in an environment with multiple
Documentum servers ...................................................................... 30
2.13 Configuring the Application Server for xCP applications ..................... 31
2.13.1 Configuring the tc Server instance .................................................... 32
2.13.2 Configuring Tomcat ......................................................................... 35
2.13.3 Configuring the WebLogic Server ..................................................... 39
2.13.4 Configuring the WildFly or JBoss application server ........................... 41
2.13.5 Configuring the WebSphere Liberty application server ....................... 45
2.14 Installing Business Activity Monitor ................................................... 47
2.14.1 Creating the Microsoft SQL Server database .................................... 47
2.14.2 Creating the Oracle database .......................................................... 48
EDCPKL220200-IGD-EN-01 Deployment Guide iii

Table of Contents
2.14.3 Deploying the BAM server ............................................................... 49

2.14.4 Deploying the BAM server on tc server ............................................. 52
2.14.5 Deploying the BAM server on Apache Tomcat application server ....... 54
2.14.6 Deploying the BAM server in a clustered environment ....................... 57
2.14.7 Deploying the BAM server on WebLogic server ................................. 57
2.14.8 Deploying the BAM server on WebSphere Liberty application server .. 59
2.14.9 Deploying the BAM server on WildFly server ..................................... 59
2.15 Upgrading BAM server and xCP application ...................................... 61
2.16 Installing Process Integrator ............................................................. 61
2.16.1 Understanding Process Integrator inbound services .......................... 62
2.16.2 Installing Process Integrator inbound services ................................... 62
2.16.2.1 Installing Process Integrator inbound services on WebLogic
application server ............................................................................ 64
2.16.2.2 Installing Process Integrator Inbound Services on WildFly
Application Server ........................................................................... 65
2.16.2.3 Installing Process Integrator inbound services on WebSphere
Liberty application server ................................................................. 65
2.16.3 Using the password encryption utility ................................................ 67
2.16.4 Configuring inbound listeners ........................................................... 67
2.16.5 Configuring Process Integrator to support High Availability ................. 68
2.16.6 Setting the listener table attributes .................................................... 68
2.16.7 Using DQL to set the listener table attributes ..................................... 69
2.16.8 Using a script to set listener table attributes ...................................... 69
2.16.9 Validating inbound services and listeners .......................................... 71
2.16.10 Viewing a list of available web services ............................................. 71
2.16.11 Validating outbound messaging configuration ................................... 72
2.16.12 Importing SSL certificates to support encrypted connections for
process activities ............................................................................. 73
2.16.13 Configuring an HTTP Proxy server for web services .......................... 74
2.17 Installing the xCP Deployment Agent ................................................ 75
2.17.1 Setting up xDA and xDA tools .......................................................... 75
2.17.2 Installing xDA as a Windows service ................................................ 80
2.17.3 Connecting to xDA from xDA tools ................................................... 82
2.17.4 Logging In to xDA from xDA tools ..................................................... 83
2.18 Using the xDA management center to register an environment .......... 83
2.18.1 Logging In to the xDA management center ....................................... 83
2.18.2 Configuring an environment template ............................................... 84
2.18.3 Registering an environment ............................................................. 85
2.18.4 Configuring general properties ......................................................... 86
2.18.5 Configuring accounts ....................................................................... 86
2.18.6 Configuring host groups ................................................................... 86
2.18.7 Configuring hosts ............................................................................ 87
2.18.8 Configuring services ........................................................................ 88
iv OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

Table of Contents
2.18.9 Service endpoint configuration ......................................................... 89

2.18.10 Configuring a clustered environment ................................................ 96
2.18.11 Updating environment configuration ................................................. 96
2.18.12 Viewing service component versions ................................................ 97
2.18.13 Synchronizing a manually provisioned environment ........................... 98
2.18.14 Synchronizing an environment ......................................................... 99
2.18.15 Unregistering an environment .......................................................... 99
2.19 Using Commands to Create an Environment ..................................... 99
2.19.1 Creating an environment ............................................................... 100
2.19.2 Encrypting passwords ................................................................... 100
2.19.3 Configuring general properties ....................................................... 101
2.19.4 Configuring accounts ..................................................................... 101
2.19.5 Configuring host groups and hosts ................................................. 102
2.19.6 Configuring services ...................................................................... 102
2.19.7 Service endpoint configuration ....................................................... 103
2.19.8 Deleting an environment ................................................................ 108
2.20 Managing xDA users ..................................................................... 109
2.20.1 Guidelines for username and password creation ............................. 109
2.20.2 Using the xDA management center ................................................ 110
2.20.3 Using commands .......................................................................... 111
2.20.4 Creating a user ............................................................................. 111
2.20.5 Viewing a list of users .................................................................... 112
2.20.6 Changing a user password ............................................................ 112
2.20.7 Deleting a user .............................................................................. 113
2.21 Viewing environments ................................................................... 113
2.21.1 Viewing a list of environments ........................................................ 113
2.21.2 Viewing properties of a specific environment ................................... 114
2.22 Deploying xCP Designer ................................................................ 116
2.23 Content Intelligence Services sizing for better performance ............. 116
2.24 Documentum login ticket-based authentication support .................... 117
2.25 Single-Sign on .............................................................................. 119
2.25.1 Configuring Kerberos Authentication .............................................. 120
2.25.1.1 Configure Kerberos Authentication on Documentum Server ............. 120
2.25.1.2 Configure Kerberos Authentication for xCP Application .................... 120
2.25.1.3 Configure at client end to display BAM reports ................................ 125
2.25.2 Configuring CAS Authentication ..................................................... 126
2.25.2.1 Configure CAS Authentication on CAS Server ................................. 127
2.25.2.2 Configure CAS Authentication on Documentum Server .................... 130
2.25.2.3 Configure CAS Authentication for xCP Application .......................... 131
2.25.3 Configuring SiteMinder Authentication ............................................ 132
2.25.3.1 Configure SiteMinder Authentication on Documentum Server .......... 132
2.25.3.2 Configure SiteMinder Authentication for xCP Application ................. 133
EDCPKL220200-IGD-EN-01 Deployment Guide v

Table of Contents
2.25.3.3 Install and configure LDAP Data Adapter ........................................ 133

2.25.3.4 Install and configure SiteMinder Policy Server ................................. 133
2.25.3.5 Install and configure SiteMinder Web Agent .................................... 133
2.25.4 Configuring SAML authentication ................................................... 134
2.25.4.1 SAML based SSO Authentication Workflow .................................... 134
2.25.4.2 Enabling HTTPS for Application Server .......................................... 136
2.25.4.3 Configuring Relying party for AD FS (IDP Server) ............................ 139
2.25.4.4 Editing Relying party for AD FS (IDP Server) .................................. 139
2.25.4.5 Configuring SAML SSO for a cluster environment ........................... 140
2.25.5 Troubleshooting SSO .................................................................... 140
2.25.5.1 SSO fails when multiple applications deployed on same Application
Server .......................................................................................... 141
2.25.5.2 Accessing SSO-enabled xCP application fails ................................. 141
2.25.5.3 xCP application fails to start in SAML ............................................. 141
2.25.5.4 Limitation of ADFS Identity Provider Server .................................... 142
2.25.5.5 Log error of SAML message signature failure .................................. 142
2.25.6 Configuring OpenText Directory Services Authentication in
Documentum Server ..................................................................... 142
2.26 Cross-Origin Resource Sharing (CORS) support ............................. 147
3 Deploying an xCP Application ............................................. 149

3.1 Overview of Deploying an xCP Application ...................................... 149
3.2 Application Deployment Using xCP Designer .................................. 149
3.3 Application Deployment Using xDA Tools ....................................... 151
3.3.1 Deploying an Application with xDA Tools ........................................ 151
3.3.2 Deploying an Application with Full-text Indexing .............................. 155
3.3.3 Deploying an Application Deferring Full-text Indexing ...................... 156
3.4 Deploying an Application to an application server ............................ 157
3.4.1 Deploying an application to WildFly or JBoss server ........................ 157
3.4.2 Deploying an Application to WebLogic Server ................................. 159
3.4.3 Deploying an Application to Websphere Liberty Application Server ... 160
3.5 Deploying an Application in a Clustered Environment ...................... 161
3.5.1 Completing Deployment with Multiple xCP Application Hosts ........... 161
3.5.2 Completing Deployment with Multiple BAM Instances ...................... 162
3.6 Using the Sample Application to Validate the Deployment ............... 162
3.7 Creating a Simple Application to Validate the Deployment ............... 163
3.8 Enabling xCP Viewer to Access ACS and BOCS for Searches ......... 166
3.9 Configuring xCP to Interact with CTS ............................................. 167
3.10 Using Dedicated CTS Instances for Real-time Requests .................. 169
3.11 Validating if CTS is set up Correctly ................................................ 170
3.12 Enabling the Privileged DFC Client ................................................. 172
3.13 Enabling CTS to interact with supported viewers ............................. 173
3.14 Integrating the GHS into xCP ......................................................... 175
vi OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

Table of Contents
3.15 Integrating the PHS into xCP ......................................................... 175
4 Deploying and Configuring xCP Designer and Runtime

Language Files ...................................................................... 177
4.1 Deploying xCP Designer Language Packs ...................................... 177
4.2 Running an xCP Application in Different Languages ........................ 178
4.2.1 Deploying xCP Runtime Library Language Files .............................. 178
4.2.2 Localizing xCP Runtime Application Labels ..................................... 179
4.2.3 Localizing Validation Messages in an xCP Application ..................... 180
4.2.4 Localizing Custom Messages in an xCP Application ........................ 180
4.3 Adding and Configuring new Language Files for new Locale
Support for Runtime ...................................................................... 182
4.3.1 Localizing xCP Runtime Library Language Files .............................. 182
4.3.2 Localization of Third-party Products ................................................ 183
4.3.3 Configuring for a New Locale ......................................................... 184
4.3.4 Forcing Locale Fallback ................................................................. 184
4.4 Locale Loading Method ................................................................. 185
4.5 Modifying Runtime Library Language Files ...................................... 187
4.6 Running an xCP Application in Different Languages in Preview
Mode ............................................................................................ 188
5 Uninstalling an Application .................................................. 191

5.1 Manually Uninstalling Application Data ........................................... 191
5.2 Undeploy the xCP Application ........................................................ 191
5.3 Removing Data from the BAM Database ........................................ 192
5.4 Removing Data from the Repository ............................................... 192
5.4.1 Retrieving a List of Application Artifact Bundles ............................... 193
5.4.2 Removing Application Data ............................................................ 194
5.4.2.1 Removing Business Object, Folder, and Content Data ..................... 194
5.4.2.2 Removing Relation Data ................................................................ 194
5.4.2.3 Removing Java Module and Java Service Data ............................... 195
5.4.2.4 Removing Process Data ................................................................ 195
5.4.2.5 Removing Group Data ................................................................... 196
5.4.2.6 Removing Parameter and Endpoint Data ........................................ 197
5.4.2.7 Removing permission set data ....................................................... 197
5.4.2.8 Removing Historical Data .............................................................. 197
5.4.2.9 Removing Type Fragment Data ..................................................... 197
5.4.2.10 Removing Application Artifact Bundles ........................................... 198
6 Administering the xCP System ............................................ 199

6.1 Tuning the Documentum Server Database ...................................... 199
6.2 Updating Endpoint Values After Application Deployment ................. 200
6.3 Enabling Priority Levels for System Activities in Processes .............. 204
6.4 Modifying the Message Queue Strategy ......................................... 204
EDCPKL220200-IGD-EN-01 Deployment Guide vii

Table of Contents
6.5 Adding BAM server Pipe Jobs to a Message Queue ........................ 206
6.6 Troubleshooting Queries with Debug Mode ..................................... 207
6.7 Connecting xCP Application through Load Balancer ........................ 208
7 Migrating Applications .......................................................... 209

7.1 Migrating an Application from an Earlier Version to a Current
Version of xCP .............................................................................. 209
7.1.1 Troubleshooting ............................................................................ 214
7.2 Type Adoption .............................................................................. 215
7.2.1 Adopting Data Types ..................................................................... 215
7.3 Type Migration .............................................................................. 216
7.3.1 Importing Types from Composer .................................................... 216
7.4 Interoperability .............................................................................. 216
7.5 Reverse Interoperability ................................................................. 217
8 xCP Process Manager ........................................................... 219

8.1 Overview ...................................................................................... 219
8.2 Prerequisites ................................................................................ 219
8.3 Importing the xCP Process Manager application ............................. 220
8.4 Inbox – My Task ........................................................................... 220
8.5 Task Details .................................................................................. 221
8.6 Context Menu ............................................................................... 223
8.7 Process Instances ......................................................................... 223
8.8 Sorting Results List ....................................................................... 224
8.9 Process Template ......................................................................... 225
8.10 Search ......................................................................................... 226
8.11 Enabling search for custom types ................................................... 227
8.12 Full text search ............................................................................. 228
8.13 Repository Browser ....................................................................... 229
8.14 Customizing xCP Process Manager ............................................... 229
8.14.1 Creating or adding a process to xCP Process Manager ................... 229
8.14.2 Adding Roles or Groups to xCP Process Manager .......................... 230
8.14.3 Configuring Process Template ....................................................... 230
8.14.4 Configuring Process Instance ........................................................ 231
8.14.5 Preserving the result list page filter ................................................. 232
8.15 Deploying xCP Process Manager ................................................... 233
8.16 Resolving DQL failure .................................................................... 233
8.17 Resolving xCP Process Manager deployment failure ....................... 233
9 Setting up xCP in Kubernetes Environment ....................... 235

9.1 Introduction ................................................................................... 235
10 Troubleshooting Manually-provisioned Environments ..... 237

10.1 Environment Status Registration Incomplete ................................... 237
viii OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

Table of Contents
10.2 Application Deployment Problems .................................................. 237

10.3 Page Modification and Display ....................................................... 238
10.4 Privileged DFC Problems ............................................................... 238
10.5 Cannot Save Annotations .............................................................. 240
10.6 Document is not Available for Viewing ............................................ 240
10.7 xCP Viewer is not Displaying a Document ...................................... 241
10.8 Specific Document Formats are Never Available for Viewing ............ 242
10.8.1 Setting the richmedia_enabled Flag ................................................ 242
10.9 Delayed Document Display ............................................................ 242
10.10 Retrieving a List of Namespaces .................................................... 243
10.11 Incorrect URL Appears After Deploying an Application .................... 243
10.11.1 Configuring xCP Designer to Show the Correct URL ....................... 244
10.12 xCP Viewer is not displaying document for application with CAS ...... 245
10.13 Process Integrator Fails to Start Listener ........................................ 245
10.14 Multi-Select Result List Unable to Send Data to a Stateless Process 247
10.15 FAST 11 hint on SQL query results in performance issue ................ 247
10.16 BPS conflicts with DFS deployed on the same Tomcat instance ....... 248
10.17 xCP Viewer with HTTPS mode ....................................................... 248
EDCPKL220200-IGD-EN-01 Deployment Guide ix

Chapter 1
Getting Started
1.1 Deployment environments overview

Deployment of Documentum components require installation of both the OpenText
Documentum components and the additional infrastructure hardware and software
prerequisites.
Note: The information in this guide is for application and system

administrators who deploy and administer the xCP software. It assumes
familiarity with basic Documentum functionality, such as repository
configuration.
• Common Documentum components include:
– Documentum Server
– Documentum Administrator (DA)
– Documentum Business Activity Monitor (BAM)
– Documentum Process Engine
– Documentum Process Integrator
– Documentum xPlore
• Additional extended services include:
– Documentum Content Intelligence Services (CIS)

– Documentum Content Transformation Services (CTS)
○ CTS Documents
○ CTS Audio-Video
○ CTS Media
– Documentum Document Image Services (DIS)
– xCP Viewer Services
Make sure you have the appropriate licensing for each component in order to
download, install, and use the software.
Note: When runtime components, such as BAM and xPlore components are
disabled in xCP Deployment Agent, these components appear as disabled
while deploying the application.
EDCPKL220200-IGD-EN-01 Deployment Guide 11

Chapter 1 Getting Started
1.2 Deployment methods

An xCelerated Composition Platform (xCP) deployment environment contains the
Documentum components and third-party software needed to run an xCP
application. The environment can include third-party software.
You can build environments only through the manual mode. You can build an xCP
physical or virtual deployment environment by manually installing Documentum
components and third-party software. Use xCP Deployment Agent (xDA) to deploy
xCP applications into the manually-built environment. “Manual provisioning”
on page 16 provides more details.
The term Documentum software components refers to the xCP programs listed in
“Deployment environments overview” on page 11.
1.3 Managing environments

The following steps provide an overview of the chapters in this manual:
1. Provision environments: To provision environments manually, install

components, create application server homes or instances, install xDA, and
register the environment with xDA. “Manual provisioning” on page 16
provides details.
2. Deploy applications. “Overview of Deploying an xCP Application” on page 149

provides details.
1.4 Upgrading an environment

Upgrade each component in your environment. The documentation for each
component provides details.
The Migrating an application topic in the xCP Designer Help describes how to migrate
xCP applications so that they are compatible with the latest version of xCP Designer.
Now you can deploy applications to the upgraded environment. “Overview of
Deploying an xCP Application” on page 149 provides details.
xCelerated Management System to xCP Deployment Agent

migration
Starting with xCP 2.3 release, xCP Deployment Agent (xDA) tools is a replacement
of xCelerated Management System (xMS) tools and xMS tools no longer exists. It is
recommended that the end user must not attempt to upgrade xMS tools to xDA
tools. xMS Agent catalog migration to xDA is not supported. There is no migration
path for the existing environment in xMS to xDA and new environment
configuration need to be created in xDA.
Refer to the Installing the xCP Deployment Agent section for more details about
installing xDA and registering an environment in xDA. Use xCP Deployment Agent
12 OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

1.5. Updated attributes for REST API properties
to deploy the application package to a staging or production environment, instead of

xMS Agent that was used for deploying applications with previous versions of xCP
Designer.
1.5 Updated attributes for REST API properties

Starting with Documentum xCP 21.4 release, the following attribute names have
been updated:
Old attribute name New attribute name

xcp.security.logon.secured rest.security.logon.secured
xcp.security.saml2.url.context.path rest.security.saml2.url.context.path
xcp.security.saml2.url.port rest.security.saml2.url.port
xcp.security.saml2.url.hostname rest.security.saml2.url.hostname
xcp.security.saml2.url.scheme rest.security.saml2.url.scheme
xcp.security.saml2.entity.base.url rest.security.saml2.entity.base.url
xcp.signon.logout.url rest.signon.logout.url
xcp.security.logon.audit rest.security.logon.audit
xcp.security.kerberos.enable.dt.support rest.security.kerberos.enable.dt.support
xcp.signon.ticket.timeout rest.signon.ticket.timeout
xcp.signon.logout.url rest.signon.logout.url
xcp.signon.saml.assertion.maxage rest.signon.saml.assertion.maxage
Note: The attribute, xcp.security.logon.challenge.suffix, has been

removed starting with Documentum xCP 21.4 release.
1.6 Security configuration

This guide provides information on the following security configurations:
Security Configuration Details or Instructions

Password Encryption Utility Using the Password Encryption Utility
SSL Importing SSL Certificates to Support
Encrypted Connections for Process Activities
Microsoft SQL Server Database Creating the Microsoft SQL Server Database
Service Endpoint Service Endpoint Configuration
Process Integrator Installing Process Integrator Inbound
Services
Web Services Configuring an HTTP Proxy Server for Web
Services

Chapter 1 Getting Started
Security Configuration Details or Instructions

Documentum Login Ticket-based Configuring an HTTP Proxy Server for Web
Authentication Support and rest-api- Services
runtime.properties
SSO Single-Sign on

Chapter 2
Manually provisioning an xCP environment
2.1 Overview
You provision the environments manually and use xCP Deployment Agent (xDA) to
deploy xCP applications in those environments. xDA is the lightweight application
used for application deployment and endpoint resolution in a manually created
environment. The main purpose of xCP Deployment Agent (xDA) is to allow
registration of manually provisioned environment and deploy xCP applications to
that environment.
To register an environment with xDA, you use xDA Management Center or create-
environment xDA command and you can deploy the xCP applications using xCP
Designer or xDA Tools:
• xDA Management Center is a web user interface utility. The xDA Management
Center has a set of default environment templates based on module template
files, which are like the blueprint files. You can create additional environment
templates to meet your needs. The xDA catalog contains these environment
templates.
You use default or custom environment templates to register manually
provisioned environments. The xDA Management Center enables you to
configure various manually installed xCP components. xDA uses this
information to deploy xCP application to these environments.
• xDA Tools is a command-line interface (CLI). It connects to xDA to perform
validations and deploy xCP application.
Deploying an xCP application includes configuring application deployment

parameters and endpoints, and deploying the application using xDA. xDA deploys
repository and application server artifacts to its proper locations in the environment.
Additionally, it performs necessary application configuration based on rules in the
application package.

Chapter 2 Manually provisioning an xCP environment
2.2 Manual provisioning

You provision an xCP environment manually.
1. Download and install Documentum components and third-party software into a

physical or virtual environment. “Installing and configuring xCP components
and third-party software” on page 17 provides instructions.
2. Configure the xCP application host. The xCP application host is the application
server which you intend to use for deploying xCP applications. “Configuring the
Application Server for xCP applications” on page 31 provides instructions.
3. Install the xCP Deployment Agent (xDA). “Installing the xCP Deployment
Agent” on page 75 provides instructions.
4. Register the environment with xDA. “Registering an environment” on page 85
provides instructions.
5. When the status of the environment is Registered, synchronize the environment.
“Synchronizing a manually provisioned environment” on page 98 provides
instructions.
After the environment has been successfully registered and synchronized, you can
deploy applications to the environment. “Overview of Deploying an xCP
Application” on page 149 provides details.
2.3 Prerequisites
The following table describes where to find information on the prerequisites for xCP
environments:
Prerequisites for Source of information

Each xCP component Documentum xCelerated Composition Platform
Release Notes
Any third-party software, such as database Third-party documentation
software and application server
xCP Deployment Agent (xDA) Installing the xCP Deployment Agent

2.4. Installing and configuring xCP components and third-party software
2.4 Installing and configuring xCP components and

third-party software
1. Install each of the components listed in the following table, in the order listed,
into a physical or virtual environment. Download all components from
OpenText MySupport (https://support.opentext.com) site, except third-party
software.
xCP requires all components unless otherwise indicated. If you neglect to install
any one of them, the application deployment fails.
Required/Optional Component Source of Information

Required JDK (third-party JDK documentation
component)
Required Documentum Server and OpenText Documentum
Documentum Foundation Platform and Platform
Classes (DFC) Extensions Installation Guide
Required Document Image Services “Installing Document
(DIS) Image Services”
on page 21
Required xCP Viewer Services “Installing the xCP Viewer
Services DAR” on page 22
Optional Documentum OpenText Documentum
Administrator (DA) Administrator Deployment
Guide
Required Process Engine “Installing Process Engine”
on page 27
Required Application server (third- OpenText Documentum
party component) xCelerated Composition
Platform Release Notes
Required Process Integrator (BPS) “Installing Process
Integrator” on page 61
Required xCP Deployment Agent “Installing the xCP
(xDA) Deployment Agent”
on page 75
Optional xDA Tools OpenText Documentum
xCelerated Composition
Platform Deployment Guide
Required xCP Designer “Deploying xCP Designer”
on page 116
Optional Business Activity Monitor “Installing Business
(BAM) Activity Monitor”
on page 47

Required/Optional Component Source of Information

Optional xPlore OpenText Documentum
xPlore Deployment Guide
Optional Content Intelligence OpenText Platform and
Services (CIS) Platform Extension
Installation Guide
Optional Content Transformation OpenText Documentum
Services (CTS). This Content Transformation
component CTS - Services Installation Guide
Documents, CTS - Audio/
Video, and CTS - Media.
Optional Documentum Trusted OpenText Documentum
Content Services (TCS) Platform and Platform
Extensions Installation Guide
Note: CIS is required for discovered metadata and CTS is required for the
Viewer to display formats other than PDF.
2. Record your environment information. You may need the following

environment information:
• xCP application host username and password

• Search Index Agent username and password
• Search Dsearchadmin password
• Repository administrator username and password
• Repository name
• Repository port
• Repository host (IP address or host name)
• xPlore host (IP address or host name)
• xPlore Server Search port
• xPlore Index Agent port
• xPlore Server URL
• xPlore Index Agent URL
• BAM server URL
• BAM server host (IP address or host name)
• BAM server port
• BAM server protocol
• xCP application endpoint URL
• xCP application host (IP address or host name)

2.5. xCP deployment scenarios
• xCP application port

• xCP application protocol
• Process Integrator URL
• DA URL
• CTS host (IP address or host name)
• CIS host (IP address or host name)
Use this information to deploy applications using xCP Deployment Agent.

“Application Deployment Using xDA Tools” on page 151 provides information.
Alternatively, provide this information to developers using xCP Designer to
design applications.
3. The following files are available for your reference:

Download the ApphostCustomconf.zip file from OpenText My Support https://
support.opentext.com and extract these files.
• transformation.properties
• deployment.properties
• rest-api-runtime.properties
• dfc.properties
• bam-server.properties
You can use these files and customize them, if required.
2.5 xCP deployment scenarios

You can deploy xCP components across one or more physical or virtual server
machines. The two-machine deployment scenario is the preferred development
setup to maintain optimal performance but you can use fewer application server
instances or hosts as per your own requirements.
This section describes a two-machine deployment scenario that serves as a

development environment. In this example environment, the application server is tc
Server.

Machine Install the following On the Application Server

1 JDK Create two application server
instances:
Documentum Server and its
components • Instance 1 – deploy the
xCP application and the
Database BAM server
• Instance 2 – deploy
Application server Process Integrator
You can also deploy the BAM

server into its own
application server instance.
2 JDK Create one application server
instance into which you
xPlore deploy DA.
CIS
CTS
Application server
Client Machine xCP Designer
xDA
Supported browser
A development environment can have CTS and xPlore or Documentum Server on

the same machine. However, to ensure optimal system performance on a production
environment, do not install CTS on the same host as the Documentum Server or
xPlore.
Your deployment could also include Branch Office Caching Services (BOCS), which
you install on separate machine. BOCS is not represented in this deployment
scenario.
The following figure illustrates a two-machine deployment:

2.6. Installing Document Image Services
2.6 Installing Document Image Services

This section describes how to use the DAR Installer to install Document Image
Services (DIS). DIS provides end users with imaging-related features such as
annotations, page serving, and page modifications. The xCP Content Viewer uses
these capabilities while performing various operations on documents.
Before installing DIS, ensure that you:
• Install Documentum Server and create a repository.

• Install Documentum Administrator and create a user with Documentum
administrator or Superuser privileges. The OpenText Documentum Server
Administration and Configuration Guide provides information on creating users.
• Download the DIS DAR from the OpenText MySupport (https://
support.opentext.com) site.

2.6.1 Installing the Document Image Services DAR file

Use the DAR Installer to install DIS. The OpenText Documentum Content
Transformation Services Installation Guide provides guidelines on using the DAR
Installer.
2.6.2 Enabling page serving on the BOCS server

Complete this procedure if you are using BOCS and want to enable page serving.
The OpenText Documentum Server Distributed Content Management Guide provides
more information on BOCS.
1. Download the ImageServices_BOCS_*.*.zip file from the OpenText MySupport

(https://support.opentext.com) site.
2. Extract the ZIP file and copy image-services-bocs-plugin.jar to the bocs.ear\
lib directory of the BOCS EAR on the application server.
3. Open the app_osgi_config file in the bocs.ear\lib\configs.jar directory

and add the following line to the bootload_packages entry:
com.documentum.pageaware.tiff,com.documentum.services.imaging.pagemodifier,
com.documentum.services.imaging.tifflib.impl,
com.documentum.services.imaging.tifflib,com.documentum.pageaware,
com.documentum.services.imaging.pdflib,
com.documentum.services.imaging.pdflib.impl,com.documentum.pageaware.pdf,
com.documentum.services.imaging.pagemodifier,com.documentum.pageaware.pdf
Save your changes.

4. Restart the application server.
2.7 Installing the xCP Viewer Services DAR

xCP Viewer Services provide the functionality to add comments to the specific page
locations in a document. Use the DAR Installer to install xCP Viewer Services
(xCP_Viewer_Services.dar). The OpenText Documentum Content Transformation
Services Installation Guide provides guidelines on using the DAR Installer.
2.7.1 Checking ACS server for xCP Viewer

In order for the xCP Viewer to work properly, the Accelerated Content Services
(ACS) Server must be available.
1. Verify that the ACS server is running.

2. Check to see if the ACS URLs are resolvable from the domain of the end users:
In a browser on the domain of the end users, type the following URL to access
the ACS server:
http://<ACS-server>:<port>/ACS/servlet/ACS
If the ACS server is resolvable from the domain of the end users, you see the
following message:

2.8. Configuring the xCP Advanced Viewer
ACS Server is Running.
2.8 Configuring the xCP Advanced Viewer

Use the viewerconfig-advancedviewer.properties file to configure the xCP
Advanced Viewer. The OpenText Documentum xCelerated Composition Platform User
Guide provides instructions about using the xCP Advanced Viewer.
Server side configuration

While viewing a larger document that spans across multiple pages, it makes sense to
chunk the document so that it appears in a browser in a seamless manner without a
delay. For the end user, it enhances readability of the document and eventually
improves user experience.
Extract the viewerconfig-advancedviewer.properties file from the props folder

in xcp-ivf-provider-advancedviewer-x.y.zzzz.jar file available at
<Designer_location>\maven\designer\com\emc\xcp\xcp-ivf-provider-
advancedviewer\x.y.zzzz folder.
Place this file under classpath for the application server (for example, CustomConf
folder). Modify the contents of the file as required. The comments marked in the file
explain what each property controls.
# Flag to indicate whether page chunking should be enabled or not
# (Default = true)
chunking.enabled = true
# Even when chunking is enabed, it is triggered only when either file size is
# more than "filesizeMB", or total number of
# pages in the file is more than "pageCount"
# (Default = 5)
chunking.trigger.filesizeMB = 5
# (Default = 15)
chunking.trigger.pagecount = 15
# Number of pages to download in one chunk
# (Default = 5)
chunking.chunksize = 5
# Folder in repository that stores the images for image annotation
# (Default = None, no server side images will be fetched)
image.directory = /System/AdvancedViewer/Images
# Formats to be filtered inside the folder for images
# (Default = bmp,gif,jpeg,png)
image.formats = bmp,gif,jpeg,png
#Changemark Config file location
changemark.config = /System/AdvancedViewer/config/ChangemarkConfig.xml
# Search XML size threshold value in KB beyond
# which the search will be done on server side
# (Default = 512)
search.xml.filesizeKB = 512
# Flag to indicate whether all required transformation should be
# done in case of real-time renditions.
# false = only view rendition is generated
# true = view rendition, thumbnails and search XML rendition are generated
# (Default = false)
realtime.fullTransform = false

2.9 Installing Brava! Enterprise for Documentum

xCP
The (required) Brava! License is a web application that runs within a servlet engine
and is composed of various supporting configuration files.
A 64-bit server servlet is required for Brava! Enterprise and must be installed prior to
running the Brava! Enterprise installer. If no servlet engine is found during the
Brava! license installation, you are prompted to install Tomcat or use a different
servlet engine.
64-bit Java 7 64-bit Runtime is a requirement of Brava! Enterprise servlet container

and will appear in the prerequisite list if not found on your machine during the
installation. If not detected, the Java installation will run and a system and setup
restart will be required.
Licensing
By default, the Brava! Enterprise product installs a 5-user 30 day evaluation key.
Once you obtain permanent keys from us, you must copy them to the installation
directories to replace the 30 day evaluation keys. These three keys are included in
the following two files, which will need to be updated after installation:
The Job Processor IGCKey.lic file (located in your installed \<install location>
\OpenText\Brava! Enterprise\JobProcessor\directory).
The Brava! Server and Brava! client keys contained in the IGCKey.lic file (located in
your \<install location>\OpenText\Brava! Enterprise\Brava! License\
directory).
Notes
• The purchase of client license seats entitles you to a single Brava! Server, Job
Processor, and License Server. Increasing the number of Brava! Servers,
License Servers, or Job Processors in your environment involves an
additional licensing fee that must be discussed with your Sales group
Account Executive.
• Starting with xCP 21.2 release, Brava! version 16.6.3 is supported.
Running the Installation Wizard
1. Double-click on the installer file that you downloaded. An Installshield Wizard

begins; if .NET Framework components are not detected, they will be installed
at this time.
2. On the Welcome screen, click Next.
3. Read the Brava! Enterprise End user License Agreement and select I accept... if
you have read, understand, and agree to the terms of the Licensing Agreement,
and then click Next.

2.10. Installing the Job Processor
4. In the Choose Destination Location screen, use the Browse button to select a
custom location for the Brava! Enterprise files or click Next to accept the default
location and continue.
5. In the Custom setup screen, select which Brava! Enterprise components you
would like to install on this machine. Install the components on different
machines, depending on your scaling requirements. Multiple Job Processor
machines increases scalability.
2.10 Installing the Job Processor

1. Run the Brava! Enterprise on a separate machine than the one where Brava!
Server is installed and continue from the Select Components screen.
2. From the drop down arrow for the Brava! Server, and License Server, select
This feature will not be available. Components displaying an X will not be
installed at this time.
3. The Job Processor service components are installed by default. The CSF Writer
is a required component for use with Job Processor print publishing. If you
would not like the Job Processor to be installed as services, you can expand the
+ symbol and select your installation preference. If not installed, the service will
need to be installed and started manually or as a service before Brava! can
function.
4. In the Brava! Server URL screen, enter the fully qualified domain name and
port number of the machine where the Brava! Server is or will be installed.
5. If you have elected to install the Service, enter the account user name and
password in the Service Logon Information screen.
6. Click Install to begin the installation of the Job Processor components and
service.
7. If not detected (or incorrect version detected), the installer automatically installs
the CSF Writer, which is a required component of the Job Processor.
8. At the end of the installation, the installer starts the Brava! services. Click
Finish. The installation of the Job Processor and components and services is
complete.

2.11 Installing the Brava! Server

1. Install the Brava! Server and optionally the Brava! License on a separate
machine as the Job Processor(s). At least one License Server must be installed,
typically on the Brava! Server machine. To do this, from the Brava! JobProcessor
selection list, choose This feature will not be available. Components displaying
an X will not be installed at this time.
2. In the Servlet Engine screen, select Use Tomcat <version> or, if you will be
using a different Application Server, simply select Use different servlet engine.
Click Next.
3. A prompt displays, allowing you to customize the Tomcat installation directory

if desired.
4. If not automatically detected, browse to the directory of your web server

webapp folder and click Next. The Brava! client files that will be pushed out to
client machines are installed to your webapp. It’s best to select a common
default location for your application server.
5. In the Brava! Server URL screen, the default servlet port 8080 is shown. This is
the default port to use for Tomcat. If your application server is not Tomcat, or if
you have configured Tomcat to use a non-default port, enter the application
server’s communication port number.
Complete the three fields provided for the Brava! Server and click Next:
• URL Prefix: Enter either HTTP:// or HTTPS:// depending on whether the

servers are configured to communicate using SSL.
• Hostname: Enter the fully qualified domain name of the server that is used
for communicating with the Brava! Server.
• Port: Enter the port number that your application server is using (where
Brava! Server is running/deployed to).
Examples: Tomcat (Default): 8080
6. In the Brava! License Server URL screen, enter the fully qualified domain name
for the host running the Brava! License service. The hostname shown by default
for the Brava! License Server will be the same machine entered for the machine
hosting the Brava! Server webapp.
7. In the License Server Notification Settings screen, enter the server SMTP
information for sending emails from Brava! Configuration of this screen is
optional and you can simply click Next on this screen if you do not want to
receive email notifications for the Brava! License.
8. Click Install to begin the Brava! Server, Brava! License and service, and Brava!
HTML client file installation. The Brava! HTML Client setup package is
installed and deployment instructions are provided in this document.
9. Click Finish. The installation of the Brava! Server components is complete.

2.12. Installing Process Engine
It is mandatory to provide the IP address of the Brava! Server,where Brava!

Server is hosted. Navigate to the deployment.properties file available at the
<application_server_home>\<server_instance>\Customconf location and
add these entries to the end of the file:
connectionType=http
host=127.0.0.1
port=8080
2.12 Installing Process Engine

This section provides instructions for installing Process Engine on Documentum
Server using the Process Engine installer. Before installing Process Engine, ensure
that Java Method Server (JMS) service is stopped.
2.12.1 Starting the Connection Broker and all repositories

1. Select Start > Programs > Documentum Server Manager.
2. On the Documentum Server Manager dialog box, click DocBroker, select the
connection broker, and click Start.
3. Click Docbase, select a repository, and click Start.

4. Click OK.
2.12.2 Preparing non-Windows Platforms for Process Engine

installation
Before you install Process Engine on Linux platforms, source the script
dm_set_server_env.csh or script dm_set_server_env.sh (depending on the shell in
which you run), in the owner environment for the Documentum Server installation.
This sets the environment variables required by the installer. The script is located at
$DM_HOME/bin. The following example shows the script for a C shell:
source ./dm_set_server_env.csh
The OpenText Documentum Platform and Platform Extensions Installation Guide

provides more information on manually configuring environment variables.

2.12.3 Installing Process Engine

1. Download the Process Engine software.
You must have received instructions through email regarding how to download
products from the OpenText MySupport (https://support.opentext.com) site.
2. Locate the file that corresponds to your operating system and extract the file.
• Process_Engine_linux.tar (For Linux)

• Process_Engine_win.zip (For Windows)
Extracting the file creates a new folder that stores the installer files. For
example, unpacking Process_Engine_win.zip creates a folder named
Process_Engine_win.
3. Browse to the new folder. For example, open the Process_Engine_win folder.
4. Depending on the operating system, run one of the following installation
programs:
• peSetup.bin (For Linux)

• peSetup.exe (For Windows)
5. Read the Software License and Maintenance agreement page.
6. To continue with the installation, click I accept the terms of the license
agreement and click Next.
7. The installer displays a list of repositories where you want to install Process
Engine. Click Next.
Make sure you have started all the repositories where you want to install
Process Engine. If you do not start the repositories, the installation fails when
the installer unpacks the DAR files and tries to install them.
You can add the Process Engine functionality to the repository by upgrading it
by using the Documentum Server configuration program. Add the repository to
the bpm.ear/lib/web.xml file. “Adding Process Engine to a new repository”
on page 30 provides more information.
8. The system prompts you for the Application Server credentials. Enter your
credentials, confirm and click Next.
9. The installer displays the installation location. To continue with the installation,
click Install.
The installer installs Process Engine on all repositories that are served by the
Documentum Server. This installs the bpm.ear file on Java Method Server (JMS)
and installs the DAR files on each repository.
The Process Engine installer extracts the contents of the bpm.ear file to
%DOCUMENTUM%\tomcat<version>\webapps\bpm\server\DctmServer_
MethodServer\deployments on the Microsoft Windows platform and creates
the following folder structure:

2.12. Installing Process Engine
• bpm folder containing the web application files

• WEB-INF folder
• WEB-INF\lib folder
• META-INF folder
On the Microsoft Windows platform, the installer creates the pe folder at

%DOCUMENTUM%\.
On all non-Windows platforms, the installer extracts the contents of the bpm.ear
file to $DOCUMENTUM_SHARED/tomcat<version>/webapps/bpm/server/
DctmServer_MethodServer/deployments.
The installer creates the pe folder at $DOCUMENTUM_SHARED.
10. Click Done to close the Process Engine Installation wizard.
11. Restart the Documentum Sever and Java Method Server.
12. To verify that the Process Engine installation is successful:
a. Type the following URL into a browser to ensure JMS started successfully:
http://<host>:<port>/bpm/servlet/DoMethod
b. To check the version of the Process Engine installed, type

http://<host>:<port>/bpm/modules.jsp
where <host> is the host name or IP address of the JMS and <port> is the port
number of the JMS.
If the installation fails, view the installation error details in the setupError.log
file in the Process Engine installation folder.
2.12.3.1 Installing Process Engine in silent mode

To install the Process Engine patch in silent mode, perform these steps:
1. Specify the following parameters—username, password and domain name in

the test.properties file.
INSTALLER_UI=silent
PROCESS_ENGINE.GLOBAL_REGISTRY_ADMIN_USER_NAME="AdminUserName"
PROCESS_ENGINE.GLOBAL_REGISTRY_ADMIN_DOMAIN=”domainName”
PROCESS_ENGINE.SECURE.GLOBAL_REGISTRY_ADMIN_PASSWORD=”AdminPassword”
2. Specify the port number and password for the application host server.
APPSERVER.SERVER_HTTP_PORT=9080
APPSERVER.SECURE.PASSWORD=jboss
3. Specify the location of Documentum or IJMS, domain name, administrator

name and password:
Used for Default JMS / Independent Java Method Server
\\ Location of DCTM
PE.INSTALL_TARGET= C:\Documentum

\\Location of IJMS
PE.INSTALL_TARGET= C:\IJMS
PE.FQDN=
PE.DOCBASES_ADMIN_USER_NAME=username
PE.DOCBASES_ADMIN_USER_PASSWORD=password
4. Invoke the Process Engine silent installation using this command:

peSetup.exe/peSetup.bin -f c:\test.properties
2.12.4 Adding Process Engine to a new repository

If you configure a new repository on the Documentum Server after installing Process
Engine, the repository configuration program automatically installs the DAR files.
You do not have to install the Process Engine for this new repository.
2.12.5 Installing Process Engine in an environment with

multiple Documentum servers
1. Make sure all connection brokers, Documentum Servers, and repositories for
which the Process Engine must be installed are running.
“Starting the Connection Broker and all repositories” on page 27 and the
OpenText Documentum Server Administration and Configuration Guide explain how
to start connection brokers and all repositories.
2. Prepare non-Windows platforms for installing Process Engine.

“Preparing non-Windows Platforms for Process Engine installation” on page 27
provides more information.
3. Perform the following for each Documentum Server:
a. Install Process Engine on all Documentum Servers.

“Installing Process Engine” on page 28 provides more information.
b. Configure the Workflow Agent threads according to your sizing

requirements.
Set the workflow agent threads to zero for other Documentum Servers that
are not participating in processing activities.
c. Configure the workflow agents.

The workflow agent controls the execution of automatic activities in a
workflow. The OpenText Documentum Server Administration and Configuration
Guide explains how to configure workflow agents.
For the distributed Documentum Server setup, it is recommended to
manually approve the DFC privileged client on the secondary Documentum
Server.

2.13. Configuring the Application Server for xCP applications
2.13 Configuring the Application Server for xCP

applications
The xCP application host is the application server which you intend to use for
deploying xCP applications. Each application you build is deployed as a full web
application (WAR file) to the xCP application host.
You deploy the xCP application into the xCP application host on the application
server. Use one of the following procedures to configure the application server for
the xCP applications:
• “Configuring the tc Server instance” on page 32

• “Configuring Tomcat” on page 35
• “Configuring the WildFly or JBoss application server” on page 41
Before configuring the xCP application host, ensure that you download bam-
server.war from the OpenText MySupport (https://support.opentext.com) site. The
bam-server WAR file contains a properties file.
Note: Best Practice: When both BAM server and xCP application host refers to
the same host server, if end user wants to have separate log files for BAM and
XCP Application, it is recommended to place the log4j2.properties file into the
Classpath of each application, for example ..\WEB-INF\classes\log4j2.
properties. Do not include the jvm parameter -Dlog4j2.configurationFile
referenced in the application server configuration modifications, which
overrides the log4j2 configurations of that individual applications.
The SSL mode on these application servers is supported. For more information
about how to enable SSL mode, refer to the third-party documentation.
At times, when you deploy the xCP application into the xCP application host on the
application server, you may see an exception error instead of the login screen.
Exception:
org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean

with name 'businessDataController': Unsatisfied dependency expressed through field
'validator'; nested exception is
org.springframework.beans.factory.BeanCreationException: Error creating bean with name
'validator' defined in URL [wsjar:file:/opt/websphere/85/appserver/profiles/N_SBELD00445/
installedApps/N_SBELD00445/EDMApplication.ear/edma.war/WEB-INF/lib/xcp-rest-
core-16.4.0110.00243.jar!/META-INF/spring/xcp-rest-web.xml]: Invocation of init method
failed;nested exception is java.lang.NoClassDefFoundError: javax.el.ELManager
Resolution: The application server must provide its own implementation

of Expression Language. However, if the expression language (javax.el) JAR is not
available in application server, you must add the same JAR in WEB-INF\lib folder
of the deployed war application. For example, add el-api.jar for Tomcat 9.0.39.

2.13.1 Configuring the tc Server instance

1. Create an instance on tc Server. The tc Server documentation provides
information on creating the tc Server instance and modifying the ports used by
the instance.
The Insight application provided with tc Server has conflicts with xCP runtime.
Do not include Insight while creating the application server instance.
2. Create a folder and copy the log4j2.properties file in it:
a. Create a folder named bam in the application server home directory. For
example:
<<application_server_home>\<server_instance>\bam>
b. Copy the log4j2.properties to the bam folder.
You can extract log4j2.properties from /WEB-INF/classes/ of the bam-
server.war file.
3. Create and copy the dfc.properties file for the application to reference the
repository, as follows:
a. Create a Customconf folder at the root of the application server instance:

<application_server_home>\<server_instance>\Customconf.
b. Copy the dfc.properties file from the %Documentum%\Config folder on
the Documentum Server to the Customconf folder.
4. Create the rest-api-runtime.properties file in the <application_server_home>
\<server_instance>\Customconf folder and add these properties to the end of the
file:rest.user.private.session.preferred=true(Optional) Set this property
for performance tuning of the Microsoft SQL Server:
rest.api.paged_query_template.db_hint.com.emc.documentum.rest.dfc.impl.query.FolderC
hildrenQueryTemplate=SQL_SERVER('FORCESEEK')
rest.security.logon.secured=false
5. Open the dfc.properties file in <application_server_home>\<server_instance>

\Customconf and add the following entries and save your changes.
dfc.session.allow_trusted_login = false
dfc.docbroker.host[0]=<Name or IP address of the
machine where
docbroker is running>
dfc.docbroker.port[0]=1489
dfc.docbroker.host[1]=xCPH1CS
6. Create the deployment.properties file in the <application_server_home>

\<server_instance>\Customconf folder and add rest.repository.
name=<repository name> to the end of the file.
7. To configure the BAM server information for the xCP application host, perform
the following steps:
a. Extract the bam-server.war file you downloaded and open bam-

server.properties.

b. Revise the following lines to reflect the IP address or host name, port details,
and context name for the deployed BAM web application:
# bam.server.host=localhost
# bam.server.port=8000
# bam.server.context=bam-server
If you deploy the BAM server in a clustered environment, specify the IP

address and port details of the load balancer for BAM.
c. If you deploy BAM in SSL mode, locate the bam.server.protocol property
and change it to https.
d. If the bam.server.protocol property is not available, type bam.server.
protocol = https and save your changes.
e. Copy the bam-server.properties file to the Customconf folder on the

application server instance. For example, <application_server_home>
\<server_instance>\Customconf
8. Include the Customconf folder location in the Java Classpath.

For example, edit <application_server_home>\<server_instance>\conf
\wrapper.conf as shown in the following code sample:
...
wrapper.java.classpath.$$="<application_server_home>\<server_instance>\
Customconf"
...
where $$ is the next sequential number, for example, 8.
9. Set the Java system property log4j2.configurationFile as follows in the

wrapper.conf file:
wrapper.java.additional.$$="-Dlog4j2.configurationFile=
<application_server_home>\bam\log4j2.properties"
10. In the Catalina.properties file located in <application_server_home>

\<server_instance>\conf, add the following:
base.jmx.port=7999
bio.http.port=8000
bio.https.port=8001
11. Open wrapper.conf located in <application_server_home>\<server_instance>\conf

and specify the following Java memory settings:
a. If the following parameters are available, place a comment symbol (#) before
each parameter:
#wrapper.java.additional.$$="-Xmx512M"
#wrapper.java.additional.$$="-Xss256K"
b. Add the following parameters and save your changes:

wrapper.java.additional.$$="-Xmx2048M"
wrapper.java.additional.$$="-Xss1024K"
wrapper.java.additional.$$="-XX:MaxPermSize=512m"

12. Open web.xml and in the JSP servlet, disable pooling by adding the
enablePooling parameter with a value of false.
For example, edit <application_server_home>\<server_instance>\conf\web.xml as
shown in the following code sample:
<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
<init-param>
<param-name>fork</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>enablePooling</param-name>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>
Open the file in a browser to check for well-formed XML.
13. Create a user for the instance. xCP Designer uses this user to deploy the xCP
application.
For example, edit <application_server_home>\<server_instance>\conf\tomcat-
users.xml and add a user name and password as shown in the following code
sample:
<?xmlversion="1.0"?>
<tomcat-users>
<user name="USER_NAME" password="PASSWORD" roles="manager-script" />
</tomcat-users>

Ensure that the Tomcat Manager is successfully accessible using the username
and password from where you deploy the application. Else, the system throws
an error Unable to connect to app server using URL.
14. Edit the <application_server_home>\<server_instance>\conf\context.xml file and

set the Context xml node to the following:
<Context antiResourceLocking="true">
This step enables you to deploy or undeploy web applications remotely on the
application server. This also avoids redeployment issues. Open the file in a
browser to check for well-formed XML.
15. Install the application server instance as a service. Start the service. Check the
wrapper file in the logs folder to verify that the service is starting. Validate the
installation by opening the following URL in a browser:
http://localhost:8000/
16. If you are using tc Server Standard Edition, deploy the Application Manager to
the application server instance:

a. Download the xda-tools.zip file to your local system.

b. Extract the xda-tools.zip file to a folder. This extraction places a
manager.war file in the <xDA-tools>\lib\recipes\ApphostServiceType\
resources folder.
c. Copy the manager.war file to the \<application_server_home>

\<server_instance>\webapps folder.
If you are using tc Server Developer Edition, the Application Manager is

available in the application server by default.
17. Verify that the Application Manager is running by opening the following URL
in a browser:
http://localhost:8000/manager/html
Log in using the user credentials you created for the application instance.
If you are using the manager.war file provided in the xda-tools.zip file for xCP
deployment, you cannot access the Tomcat manager user interface using the
preceding URL. In this case, deploy an application to verify if the Application
Manager is running correctly. Also, view the application server logs to check for
any errors. If there are no errors, the manager.war is deployed correctly.
For development environments where you intend to deploy applications frequently

through xCP Designer, we recommend that you use the port 8000 in order to avoid
the incorrect URL issue. “Incorrect URL Appears After Deploying an Application”
on page 243 provides information.
2.13.2 Configuring Tomcat

1. Install the Apache Tomcat application server.
a. Create a folder called bam in the application server home directory. For
example:
<<application_server_home>\bam>
b. Copy the log4j2.properties file to the specified location.
You can extract the log4j2.properties file from /WEB-INF/classes/ of the
bam-server.war file.
a. Create a Customconf folder at the root of the application server home

directory:
<application_server_home>\Customconf
the Documentum Server to the specified location.

4. (Optional) Create the rest-api-runtime.properties file in the

<application_server_home>\Customconf folder and add the following property
for performance tuning of the SQL Server:
rest.api.paged_query_template.db_hint.com.emc.documentum.rest.dfc.impl.query.FolderC
hildrenQueryTemplate=SQL_SERVER('FORCESEEK')
5. Open the dfc.properties file in <application_server_home>\Customconf and add

the following parameter and save the changes:

\Customconf folder and add rest.repository.name=<repository name> at
the end of the file.

server.properties.
b. Revise the following lines to reflect the IP address or hostname, port details,

c. If you deploy BAM in SSL mode, locate the bam.server.protocol property
and change it to https.
d. If the bam.server.protocol property is not available, type bam.server.
protocol = https and save your changes.
e. Copy the bam-server.properties file to the Customconf folder in the

application server home directory.
In this case, <application_server_home>\Customconf.

For example, edit <application_server_home>\bin\setclasspath.bat and add the
entry as shown in the following code sample:
# Java Classpath
...
set "CLASSPATH=%CLASSPATH%<application_server_home>\Customconf"
9. In Catalina.bat located in <application_server_home>\bin, set the JAVA_OPTS

parameter by adding the following lines to set the log4j2.configurationFile
java system property:
set JAVA_OPTS=-Xms1024m -Xmx2048m -XX:MaxPermSize=512m -XX:+UseParallelOldGC
-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n
-Dlog4j2.configurationFile=<application_server_home>\bam\log4j2.properties

10. Open web.xml and in the JSP servlet, disable pooling by adding the
enablePooling parameter with a value of false.
For example, edit <application_server_home>\conf\web.xml as shown in the
following code sample:
<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
<init-param>
<param-name>fork</param-name>
</init-param>
<init-param>
<param-name>enablePooling</param-name>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>
11. Create a user for the Tomcat application server. xCP Designer uses this user to
deploy the xCP application.
For example, edit <application_server_home>\conf\tomcat-users.xml and add a
user name and password as shown in the following code sample:
<?xmlversion="1.0"?>
<tomcat-users>
<user name="USER_NAME" password="PASSWORD" roles="manager-script" />
</tomcat-users>

Ensure that the Tomcat Manager is successfully accessible using the username
and password from where you deploy the application. Else, the system throws
an error Unable to connect to app server using URL.
12. Edit the <application_server_home>\conf\context.xml file and set the Context xml
node to the following:
<Context antiResourceLocking="true">
This step enables you to deploy or undeploy web applications remotely on the
application server. This also avoids redeployment issues. Open the file in a
browser to check for well-formed XML.
13. Start the Tomcat service. Validate the installation by opening the following URL
in a browser:
http://localhost:<port>/
Where <port> is the port where the Tomcat application server is running. The
default port is 8080.
14. Ensure that your application server has UTF-8 set for URI encoding. If it does
not, edit the server.xml file as follows:

<Connector port="8080" URIEncoding="UTF-8" protocol="HTTP/1.1"

connectionTimeout="2000"
redirectPort="8443" />
15. This step is applicable only for a clustered environment with multiple Tomcat
nodes. Deploy the Application Manager to the application server:
a. Download the xda-tools.zip file to your local system.

b. Extract the xda-tools.zip file to a folder. This extraction places a
manager.war file in the <xDA-tools>\lib\recipes\ApphostServiceType\
resources folder.
c. Copy the manager.war file to the \<application_server_home>\webapps

folder.
16. For a clustered environment with multiple Tomcat nodes, repeat this procedure
on each Tomcat node.
17. For a clustered environment with multiple Tomcat nodes, modify clustering
configuration in server.xml to support FarmWarDeployer capability.
a. Within the <Host> element, add a <Cluster> element.

b. Within the <Cluster> element, add a <Deployer> element.
c. Within the <Deployer> element, set attributes exactly as follows:
className="org.apache.catalina.ha.deploy.FarmWarDeployer"
watchEnabled="true"
d. Specify unique values for three additional <Deployer> attributes:
Attribute Description
tempDir Specify a temporary folder for the
system to store uploaded xCP
applications.
watchDir Specify the folder for the system to copy
the xCP war file in a cluster node.
deployDir Specify the \<application_server_home>
\webapps folder.
These folders are mandatory for the FarmWarDeployer class.
The following is an example configuration:

<Host …>
<Cluster …>
…
<Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="C:/Temp/war-temp"
deployDir="C:/tomcat-apphost/webapps"
watchDir="C:/Temp/war-listen"
watchEnabled="true" />
</Cluster>
</Host>

18. The manager.war context file allows access to Tomcat manager application only
from the configured hosts. By default, the manager.war allows incoming traffic
from the localhost. You can configure these valve properties to allow access of
traffic inflow from a remote machine (xDA in this case):
a. Remote Address Valve: The remote address valve, RemoteAddrValve, either

allows or denies incoming requests based on the IP Address.
<Context antiResourceLocking="false" privileged="true" >
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="<your-xda-server-ip-
address>" />
</Context>
Example:Here, 192.168.2.101 is the machine where xDA is running.

Allows access only for the clients connecting from localhost or 192.168.2.101:
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="192\.168\.2\.101|127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />
b. Remote Host Valve: The remote host valve, RemoteHostValve, either allows
or denies incoming requests based on the host name.
<Context antiResourceLocking="false" privileged="true" >
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow="APPVM|CTSVM|<your-xda-server-
name>" />
</Context>
Example:
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow="xDAVM" />
</Context>
• When using remote host valve, the Connector in the server.xml must be
enabled for DNS lookups using enableLookups as true.
• Both remote address valve and remote host valve are mutually
exclusive. Only one of them can be used at a time.
• When Tomcat is configured for SSL, the Apphost certificate must be
added to the xDA Truststore and cacerts of Java used by xDA.
For more information about valves, refer to the third-party documentation

on the Tomcat site.
2.13.3 Configuring the WebLogic Server

Ensure the WebLogic Server is installed and not running when you configure the
WebLogic Server. Configure the WebLogic Server before you deploy the xCP
application on it. Complete the following steps to configure the WebLogic server:
a. Create a folder named, bam, in the application server home directory. For
example:
<application_server_home>\bam

b. Copy the log4j2.properties file to the bam folder.You can extract the
log4j2.properties file from /WEB-INF/classes/ of the bam-server.war
file.

directory:

3. Optional Create the rest-api-runtime.properties file in the
<application_server_home>\Customconf folder and add the following property
for performance tuning of the SQL Server:
rest.api.paged_query_template.db_hint.com.emc.documentum.
rest.dfc.impl.query.FolderChildrenQueryTemplate= SQL_SERVER('FORCESEEK')

\<server_instance>\Customconf folder and add
rest.repository.name=<repository name> to the end of the file.

server.properties.
b. Revise the following lines to reflect the IP address or hostname, port
details, and context name for the deployed BAM web application:
# bam.server.host=hostname

c. Copy the bam-server.properties file to the Customconf folder on the
application server instance. For example:
<application_server_home>\<server_instance>\Customconf
6. In the <WebLogic domain directory>\bin\ folder, edit the setDomainEnv.cmd

file and perform the following steps:
a. Set the classpath by adding the following line at the end of the file:
set CLASSPATH=%CLASSPATH%;<application_server_home>\customConf
where application_server_home> is the home directory of WebLogic

Server.
b. Set the log4j2.configurationFile system property by modifying the
following line:

set JAVA_PROPERTIES=-Dplatform.home=%WL_HOME% -Dwls.home=%WLS_HOME% -

Dweblogic.home=%WLS_HOME%
to
-Dlog4j2.configurationFile=<application_server_home>\log4j2.properties
c. Set the memory settings by adding the following lines:

Memory arguments:
set WLS_MEM_ARGS_64BIT=-Xms1024m -Xmx2048m
7. Save the setDomainEnv.cmd file.
8. In the <WebLogic domain directory>\config\ folder, edit the config.xml file by

adding these lines in the <security-configuration> element:
<security-configuration>
<enforce-valid-basic-auth-credentials>
false
</enforce-valid-basic-auth-credentials>
</security-configuration>
9. Save the config.xml file.
Note: For a clustered environment with multiple WebLogic Servers, repeat this
procedure on each WebLogic server node.
2.13.4 Configuring the WildFly or JBoss application server

1. Install the WildFly or JBoss Enterprise application platform.
2. Create a custom module for the Documentum properties file:
a. Create a folder, com\emc\xcp\main, at the application server home

directory. For example:
<<application_server_home>\modules\system\layers\base>
b. Download reactive-streams-1.0.3.jar file from the following location:
<https://mvnrepository.com/artifact/org.reactivestreams/reactive-streams/1.0.3>
c. Add the following code to the module.xml file:
<resource-root path="reactive-streams-1.0.3.jar"/>
d. Clear appserver cache and logs, and restart the server.

e. Save the reactive-streams-1.0.3.jar file at the following location of
appserver installation directory:
<<appserver_install_dir>\modules\system\layers\base\com\emc\xcp\main>
f. Create a file, module.xml, at the specified location:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.5" name="com.emc.xcp">
<resources>
<resource-root path="reactive-streams-1.0.3.jar"/>

<resource-root path="."/>
</resources>
</module>
g. Create the dfc.properties file for the application to reference the repository
and copy the dfc.properties file from the %Documentum%\Config folder on
h. (Optional) Update the dfc.properties file by adding the following key:
dfc.security.keystore.file=< location of dfc.keystore file >\dfc.keystore
i. (Optional) Create the rest-api-runtime.properties file in the <application_

server_home>\modules\system\layers\base\com\emc\xcp\main folder
and add the following property for performance tuning of the MS SQL
server:
rest.dfc.impl.query.FolderChildrenQueryTemplate=
SQL_SERVER(’FORCESEEK’)
j. Create the deployment.properties file in the <application_server_home>

\modules\system\layers\base\com\emc\xcp\main folder and add rest.
repository.name=<repo_name> at the end of the file.
a. Create a folder, bam, at the application server home directory. For example:
<application_server_home>\standalone\bam
b. Copy the log4j2.properties file to the specified location.

You can extract log4j2.properties file from /WEB-INF/classes/ of the
bam-server.war file.

server.properties.

c. Copy the bam-server.properties file to the main folder on the application
server instance. For example, <application_server_home>\modules\
system\layers\base\com\emc\xcp\main
5. In the <application_server_home>\standalone\configuration\ folder,

edit the port information in the standalone.xml file and save the
standalone.xml file.

Notes
• Specify jboss.management.native.port port as the port for the

WildFly or JBoss endpoint in xDA agent. The default port is 9990.
• Specify jboss.management.http.port port as the port for the WildFly
or JBoss endpoint in xDA agent. The default port is 9990.
6. WildFly defaults to an HTTP post size limit of 10 MB. To allow signing larger
files, increase the limits on the HTTP/HTTPS listeners using the max-post-size
attribute in <application_server_home>\standalone\configuration\
standalone.xml file.
<http-listener name="default" socket-binding="http" max-header-size="974247881"
redirect-socket="https" enable-http2="true" max-post-size="974247881"/>
7. At the <application_server_home>\bin\ command prompt, run the add-

user.bat file to create a management user.
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): a
Enter the details of the new user to add.

Realm (ManagementRealm) :<Enter>
Username : <WildFly_Admin_User_Name>
Password requirements are listed below. To modify these restrictions edit the
add-user.properties
configuration file.
- The password must not be one of the following restricted values {root,
admin, administrator}
- The password must contain at least 8 characters, 1 alphabetic character(s),
1 digit(s), 1 non-
alphanumeric symbol(s)
- The password must be different from the username
Password :
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma
separated list, or leave blank for none)
[ ]:
About to add user 'test' for realm 'ManagementRealm'
Is this correct yes/no? yes
Added user 'WildFly_User_Name' to file 'C:\Node2\standalone\
configuration\mgmt-users.properties'
Added user 'WildFly_User_Name' to file 'C:\Node2\domain
\configuration\mgmt-users.properties'
Added user 'WildFly_User_Name' with groups to file 'C:\Node2\
standalone\configuration\mgmt-groups.properties'
Added user 'WildFly_User_Name' with groups to file 'C:\Node2\
domain\configuration\mgmt-groups.properties'
Is this new user going to be used for one AS process to
connect to another AS process?
e.g. for a slave host controller connecting to the master or
for a Remoting connection for server to server EJB calls.
yes/no? yes
To represent the user add the following to the
server-identities definition <secret value="cGFzc3dvcmQ=" />
[dmadmin@APPVM bin]$ ./add-user.sh
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by __redirected.__SAXParserFactory
(file :C:\Node2\standalone\
configuration\jboss-modules.jar) to constructor com.sun.org.apache.xerces.
internal.jaxp.SAXParserFactoryImpl()
WARNING: Please consider reporting this to the maintainers of __

redirected.__SAXParserFactory
WARNING: Use --illegal-access=warn to enable warnings of further illegal
reflective
access operations
WARNING: All illegal access operations will be denied in a future release
What type of user do you wish to add?

a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): b
Enter the details of the new user to add.

Using realm 'ApplicationRealm' as discovered from the existing property files.
Username : <Wildfly_Admin_User_Name>
Password recommendations are listed below. To modify these restrictions edit the
add-
user.properties configuration file.
- The password should be different from the username
- The password should not be one of the following restricted values {root,
admin, administrator}
- The password should contain at least 8 characters, 1 alphabetic character(s),
1 digit(s), 1 non-
alphanumeric symbol(s)
Password :
WFLYDM0101: Password should have at least 1 digit.
Are you sure you want to use the password entered yes/no? yes
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma separated
list,
or leave blank for none)[ ]:

About to add user 'Wildfly_User_Name' for realm 'ApplicationRealm'
Is this correct yes/no? yes
Added user 'Wildfly_User_Name' to file 'C:\Node2\
standalone\configuration\application-users.properties'
Added user 'Wildfly_User_Name' to 'C:\Node2\
standalone\configuration\application-users.properties'
Added user 'Wildfly_User_Name' with groups to file 'C:\Node2\
standalone\configuration\application-roles.properties'
Added user 'Wildfly_User_Name' with groups to file 'C:\Node2\
standalone\configuration\application-roles.properties'
Is this new user going to be used for one AS process to connect
to another AS process?
e.g. for a slave host controller connecting to the master or for a
Remoting connection for server to server EJB calls.
yes/no? yes
To represent the user add the following to the server-identities
definition <secret value="cGFzc3dvcmQ=" />
8. Before starting the WildFly or JBoss application in a Windows environment,

add the following Java Options properties in the standalone.conf.bat file.
For Linux, update the standalone.conf file.
set "JAVA_OPTS=-Xms4096m -Xmx4096m -XX:MetaspaceSize=2048M -
XX:MaxMetaspaceSize=2048m -Djava.locale.providers=COMPAT,SPI --illegal-
access=permit -Dbam.properties=C:\Wildfly19_APPHOST\standalone\bam\bam.properties -
Dlog4j2.configurationFile=C:\Wildfly19_APPHOST\standalone\bam\log4j2.properties"
rem # Prefer IPv4

set "JAVA_OPTS=%JAVA_OPTS% -Djava.net.preferIPv4Stack=true -
Djboss.as.management.blocking.timeout=7000 -
Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax
.TransformerFactory"
9. At the <application_server_home>\bin\ command prompt and start the

WildFly or JBoss server with these options:

standalone.bat -b <WildFly_HOSTNAME> -bmanagement <WildFly_HOSTNAME>
where as,
<WildFly_HOSTNAME> depends on what is registered in xDA.
If xDA refers to machines with Hostnames, host names must be provided here.
This option binds the WildFly interfaces to the hostname of the machine rather
than IP address of the machine.
2.13.5 Configuring the WebSphere Liberty application server

1. Install the WebSphere Liberty Application Server.
2. Create a server and configure server.xml file as described:

<server description="new server">

<featureManager>
<feature>webProfile-8.0</feature>
<feature>restConnector-2.0</feature>
</featureManager>
....
....
....
....
<remoteFileAccess>
<writeDir>${server.config.dir}/dropins</writeDir>
</remoteFileAccess>
<library id="xcppropeties">
<fileset dir="${server.config.dir}/lib/global" includes="*.properties" />
</library>

<applicationManager autoExpand="true"/>
</server>
a. Create a folder, lib\global, at the application server home directory. For

example:
<<application_server_home>\lib\global>
b. Create the dfc.properties file for the application to reference the repository
and copy the dfc.properties file from the %Documentum%\Config folder
on the Documentum Server to the specified location.
c. (Optional) Update the dfc.properties file by adding the following key:
d. (Optional) Create the rest-api-runtime.properties file in the <application_

server_home>\lib\global folder and add the following property for
performance tuning of the MS SQL server:
rest.dfc.impl.query.FolderChildrenQueryTemplate=
SQL_SERVER(’FORCESEEK’)
e. Create the deployment.properties file in the <application_server_home>

\lib\global folder and add rest.repository.name=<repo_name> at the
end of the file.

3. Copy the log4j2.properties file to the specified location.

You can extract log4j2.properties file from /WEB-INF/classes/ of the bam-
server.war file.

server.properties.
c. Copy the bam-server.properties file to the main folder on the application

server instance. For example, <application_server_home>\lib\global
5. Before starting the WebSphere Liberty application server in a Windows

environment, add the following jvm.options properties in the <application_
server_home>\<server_name>.
-Xms1024m
-Xmx2048m
-XX:MaxPermSize=512m
-Xdebug
-Xnoagent
-Xrunjdwp:transport=dt_socket,server=y,suspend=n
-XX:+DisableExplicitGC
-Dbam.properties=<application_server_home>\bam\bam.properties
-Dlog4j2.configurationFile=<application_server_home>\lib\global\log4j2.properties
6. Copy the transformation.properties file to <application_server_home>\lib\

global. Refer to “Configuring xCP to Interact with CTS” on page 167 section for
more information.
7. At the <application_server_home>\bin\ command prompt start the

WebSphere Liberty application server:

2.14. Installing Business Activity Monitor
2.14 Installing Business Activity Monitor

This section contains instructions on installing BAM.
Before installing BAM, ensure that you:
• Install Documentum Server and create a repository. The OpenText Documentum

Platform and Platform Extensions Installation Guide provides guidelines on
installing Documentum Server and creating a repository.
• Download bam-server.war from the OpenText MySupport (https://
support.opentext.com) site.
• Create an Oracle or MS SQL Server database instance.
• Deploy the BAM server. The “Deploying the BAM server” on page 49 section
provides instructions.
2.14.1 Creating the Microsoft SQL Server database

Make a note of the following BAM database connection parameters when you create
the BAM database because you add them to bam.properties after you deploy the
BAM server.
• Database server host name

• Database name
• User name
• Password
1. Set the data file size to 500 MB.
2. Set the transaction log size to 500 MB and the transaction log file to auto-
growth.
Check the size of the log file periodically. If the log files get too large, back it up
and truncate it.
3. Create a BAM database user.
4. For the BAM database user, select SQL Server authentication and create a
password.
5. Associate the db_owner role with the BAM database user.
6. Set the default schema of the user to dbo.
7. The following table summarizes the initialization parameters to use for the
BAM database:
Parameter Value
Security SQL Server And Windows Authentication

Parameter Value
Connections Query Time-Out = 0 (unlimited)
Maximum Concurrent User connections =
0 (unlimited)
Attributes Close cursor on Commit = V (enable)
ANSI Warning = V (enable)
ANSI padding = V (enable)
ANSI nulls = V (enable)
Autostart policies when the operating Autostart SQL Server (enable) Autostart
system starts SQL Server Agent (enable)
Network TCP/IP
Server Collation Case-sensitive
MS SQL collation Code page To avoid loss of data, configure the BAM
database collation and the Documentum
Server database collation to be the same.
Configure the BAM database collation and
BAM database instance collation to be the
same.
By default, Microsoft SQL Server limits the size of index to 900 bytes. To optimize
the performance of an xCP application, BAM server creates index entries on the
aggregation table. For example, if HDS row contains large data, such as 4000 or
more characters, the index value may go beyond the set limit of 900 bytes. In this
case, you need to manually drop the index on each aggregation table for the
historical query in Microsoft SQL Server. Revisit the design and see if 4000
characters for an attribute is required. Recreate the index manually by skipping
attribute with such large data.
If an application is redeployed, BAM recreates the index entries and you need to
repeat the steps to drop the indexes.
2.14.2 Creating the Oracle database

The following procedure guides you in creating the Oracle database.
1. Verify that the Oracle server is installed and running.
2. To support multi-byte languages set the database character set to AL32UTF8.
3. Create an Oracle user and password.
4. Create a TableSpace with auto extend property enabled for BAM. For example:
CREATE TABLESPACE BAM_tablespace_name DATAFILE datafile_name SIZE tablespace_size
REUSE AUTOEXTEND ON NEXT increment_size MAXSIZE max_tablespace_size;
5. Create a user for the TableSpace created in the previous step. For example:

CREATE USER BAM_user_name IDENTIFIED BY BAM_user_pwd DEFAULT TABLESPACE

BAM_tablespace_name;
6. Grant the following access to the Oracle user:
• Grant CONNECT
• Grant RESOURCE
• Grant CREATE VIEW
• Grant CREATE SEQUENCE
Example
Grant CONNECT, RESOURCE, CREATE VIEW, CREATE SEQUENCE to BAM_user_name;
7. Monitor the database and modify the parameters based on the amount of data
being stored.
2.14.3 Deploying the BAM server

You can deploy the BAM server to the xCP application host or to its own application
server.
You can deploy the BAM server to the same machine as the database server or on a
separate machine. It is recommended to deploy the BAM server on a separate
machine from the database server to increase performance. The server uses the JDBC
driver for database operations and does not require the database client for its
operations.
To deploy the BAM server:
1. Provide access from the server to the database by way of a TCP/IP connection.
2. Extract bam-server.war to a temporary folder.
3. Open bam.properties located in bam-server\WEB-INF\classes\config.
4. To connect the BAM server with the SQL Server database, edit the JDBC
connection parameters accordingly, for example:
bam.jdbc.dialect=mssql
bam.jdbc.url=jdbc:sqlserver://<IP or Hostname>:1433;databasename=<name of
database>;SELECTMETHOD=Cursor
bam.jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
bam.jdbc.userName=<$database.username>
bam.jdbc.password=<$database.password>
bam.dfc.session.repository=<$documentum.repositoryname>
bam.dfc.session.repositoryUserName=<$documentum.username>
bam.dfc.session.repositoryPassword=<$documentum.password>
bam.cluster.activateOnStartup=false
bam.cluster.ttl=1500
bam.cluster.pulse=500

Note: Refer to specific documentation for information about JDBC

connection parameter configuration.
Where <hostname> is the IP address of the BAM database server. If you install
the BAM database and BAM server on the same machine, you can type
localhost or the loopback IP address (127.0.0.1).
Type the dialect in lower case.
5. To connect the BAM server with the Oracle database, edit the following JDBC
connection parameters:
bam.jdbc.dialect=oracle
bam.jdbc.url=jdbc:oracle:thin:system/password@hostname:1521:orcl
#bam.jdbc.url= jdbc:oracle:thin:@hostname:1521:SID
bam.jdbc.driver= oracle.jdbc.driver.OracleDriver
bam.dfc.session.repository=<$documentum.repositoryname>
bam.dfc.session.repositoryUserName=<$documentum.username>
bam.dfc.session.repositoryPassword=<$documentum.password>
Where <hostname> is the IP address of the BAM database server. If you install
the BAM database and BAM server on the same machine, you can type
localhost or the loopback IP address (127.0.0.1).
Configure the Service Name, SID, or the TNSName:

bam.jdbc.url= jdbc:oracle:thin:@hostname:1521:SERVICE_NAME
bam.jdbc.url= jdbc:oracle:thin:@hostname:1521:SID
bam.jdbc.url= jdbc:oracle:thin:@<TNSName>
To connect to the BAM database using TNSName, add the following parameter
in the application server:
-Doracle.net.tns_admin=<ADMIN_folder_path>
For BAM, SID and Service Name are both set to ORCL to avoid confusion.
Type the dialect in lower case.
For example, edit bam.properties as shown in the following sample:
bam.dfc.session.repositoryPassword=password
bam.jdbc.preference.maxIdle=-1
bam.jdbc.dialect=oracle
bam.jdbc.preference.initialSize=10
bam.dfc.session.repository=xcprc3
bam.jdbc.preference.maxActive=-1
bam.jdbc.preference.deployBatchSize=2500
bam.jdbc.preference.maxRows=100
bam.jdbc.url=jdbc\:oracle\:thin\:@127.0.0.1\:1521\:ORCL
#bam.jdbc.url=jdbc\:oracle\:thin\:@DCMXo21-CR3\:1521\:ORCL (with hostname)
bam.jdbc.password=password
bam.jdbc.driver=oracle.jdbc.driver.OracleDriver
bam.jdbc.preference.dataFormatBatchSize=1000
bam.dfc.session.repositoryUserName=dmadmin
bam.jdbc.userName=system

In the tnsnames.ora file, <myhost> points to localhost by default. If you use

localhost for the hostname, you cannot connect to an Oracle database outside of
the virtual machine (VM). The Oracle service runs only on the localhost.
6. To connect to a BAM Oracle database located on another VM, in the

tnsnames.ora file located in %ORACLE_HOME%\Network\ADMIN\, modify
<myhost> with the hostname of the database and restart OracleORCLService.
The TNSListener is configured on the VM where the SID is registered to this
listener. Ensure that the OracleOraClient11g_home1TNSListener service
restarts.
You can find the SID/Service Name in your tnsnames.ora file:
ORCL =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = myhost)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = orcl)
)
)
The following sample tnsnames.ora content enables clients to access a BAM

database on another VM:
ORCL =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = DCMXo21-CR3)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = orcl)
)
)
7. To connect the BAM server with the Postgres SQL Server database, edit the
following JDBC connection parameters:
bam.jdbc.dialect=postgres
bam.jdbc.url=jdbc\:postgresql\://<hostname>\:<port>/<name_of_database>
bam.jdbc.driver=org.postgresql.Driver
bam.jdbc.preference.deployBatchSize=2500
bam.jdbc.preference.maxIdle=-1
bam.jdbc.preference.initialSize=10
bam.jdbc.preference.maxActive=-1
bam.jdbc.preference.maxRows=100
bam.jdbc.preference.dataFormatBatchSize=1000
Note: Ensure that the search_path variable is pointing to the correct

schema, as this variable aids in creating the database tables correctly. You
can use SHOW search_path SQL query to view this variable. When you
find that the search_path variable is not pointing to the correct schema,
you can set the runtime variable as follows:
ALTER DATABASE <database_name> SET search_path = "$user",public;

Also, make sure that you have right privilege on any of the schemas of the
search_path variable.
8. Complete the steps in one of the following procedures:
• “Deploying the BAM server on tc server” on page 52

• “Deploying the BAM server on Apache Tomcat application server”
on page 54
• “Deploying the BAM server on WildFly server” on page 59
• “Configuring the WebSphere Liberty application server” on page 45
2.14.4 Deploying the BAM server on tc server

This procedure is a continuation of the “Deploying the BAM server” on page 49
procedure with steps specific to tc Server.
1. Complete the steps in “Deploying the BAM server” on page 49.

2. Create a bam folder for tc Server in <application_server_home>\<server_
instance>.
3. Copy bam.properties to <application_server_home>\<server_instance>

\bam.
4. To reset the password in bam.properties file, remove the bam.encrypted

property or set its value to false and manually re-type the original password in
the bam.jdbc.password and bam.dfc.session.repositoryPassword properties.
On starting the BAM server, the system encrypts the password automatically in
the bam.properties file and sets the bam.encrypted property to true.
When a password is encrypted, setting the bam.encrypted property to false or
removing this property results in failure of the BAM server startup.

\Customconf and add the following:
machine where
Save your changes.


For example, edit <application_server_home>\<server_instance>\conf
\wrapper.conf as shown in the following code sample:
...
wrapper.java.classpath.$$="<application_server_home>\<server_instance>\
Customconf"
...
where $$ is the next sequential number, for example, 8.
8. Perform one of the following:
• If you are installing a BAM server in a Windows environment, add the

location of bam.properties file as a system property in the wrapper.conf file.
For example, open <application_server_home>\<server_instance>
\conf\wrapper.conf and set <application_server_home>\<server_
instance>\bam\bam.properties as the value of the system property bam.
properties.
The following code sample shows bam.properties added as a system
property:
# Java Additional Parameters
wrapper.java.additional.$$="-Dbam.properties=<application_server_home>
\<server_instance>\bam\bam.properties"
• If you are installing a BAM server in a Linux environment, add the location
of bam.properties as a parameter to the setenv.sh file. For example, in tc
Server, open <application_server_home>/<server_instance>/bin/
setenv.sh and add <application_server_home>/<server_instance>/
bam/bam.properties to the Dbam.properties parameter and map it to the
WRAPPER_CONF property inside the setenv.sh file.
The following code sample shows bam.properties added as a parameter:
VM_OPTS="-Xmx2048M -Xss192K"
WRAPPER_CONF="-XX:MaxPermSize=512m -XX:PermSize=192M -Xms1024M
-Dbam.properties=/home/dmadmin/APPSERVER/APPHOST/bam/bam.properties
JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBRARY_PATH
$WRAPPER_CONF"
CLASSPATH="/home/dmadmin/APPSERVER/APPHOST/Customconf:$CLASSPATH"
9. To modify the location of the log files, open log4j2.properties located in bam-
server\WEB-INF\classes.
10. Use log4j2 standards to modify the location of the log files.
If the log file location is unchanged, the system writes the log files to the
application server home.
11. Save and close log4j2.properties.
12. Copy log4j2.properties to <application_server_home>\<server_instance>

\bam.

• If you are installing a BAM server in a Windows environment, set the

location of the log4j2.properties file to the system property log4j2.
configurationFile in the wrapper.conf file. For example, in tc Server,
open <application_server_home>\<server_instance>\conf\wrapper.
conf and set <application_server_home>\<server_instance>\bam\
log4j2.properties to log4j2.configurationFile system property.
The following code sample shows it:
wrapper.java.additional.$$="-Dlog4j2.configurationFile=
<application_server_home>\<server_instance>\bam\log4j2.properties"
• If you are installing a BAM server in a Linux environment, set the location of
log4j2.properties file to the system property log4j2.configurationFile in
the setenv.sh file. For example, in tc Server, open <application_server_
home>/<server_instance>/bin/setenv.sh and set <application_
server_home>/<server_instance>/bam/log4j2.properties to log4j2.
configurationFile system property and map it to the WRAPPER_CONF
property inside the setenv.sh file.
The following code sample shows log4j2.properties added as a parameter:
VM_OPTS="-Xmx2048M -Xss192K"
WRAPPER_CONF="-XX:MaxPermSize=512m -XX:PermSize=192M -Xms1024M
-Dlog4j2.configurationFile=/home/dmadmin/APPSERVER/APPHOST/bam/
log4j2.properties"
JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBRARY_PATH
$WRAPPER_CONF"
CLASSPATH="/home/dmadmin/APPSERVER/APPHOST/Customconf:$CLASSPATH"
14. Deploy bam-server.war into the application server in the following location:
<application_server_home>\<server_instance>\webapps
15. Start the application server instance.
16. Browse to the BAM server URL to verify that the BAM server is up and
running: http://<hostname>:<port>/bam-server/admin?action=status
2.14.5 Deploying the BAM server on Apache Tomcat

application server
procedure with steps specific to the Apache Tomcat application server.
2. Create a bam folder in the Tomcat application server home directory:

<application_server_home>
3. Copy bam.properties to <application_server_home>\bam.
4. To reset the password in bam.properties file, remove the bam.encrypted

property or set its value to false and manually re-type the original password in
the bam.jdbc.password and bam.dfc.session.repositoryPassword properties.

On starting the BAM server, the system encrypts the password automatically in
the bam.properties file and sets the bam.encrypted property to true.
When a password is encrypted, setting the bam.encrypted property to false or
removing this property, results in failure of the BAM server startup.


\Customconf and add the following:
machine where
Save your changes.
• Windows: Open <application_server_home>\bin\setclasspath.bat

and add the following line:
Set CLASSPATH="<application_server_home>\Customconf;%CLASSPATH%"
• Linux: Open <application_server_home>\bin\setclasspath.sh and

add the following line:
CLASSPATH="<application_server_home>/Customconf:$CLASSPATH"
• If you are installing a BAM server in a Windows environment, set the

location of bam.properties as a system property in the setclasspath.bat file.
For example, in Tomcat 9.0.39, open <application_server_home>\bin\
setclasspath.bat and add <application_server_home>\bam\bam.
properties to the bam.properties system property.
The following code sample shows it:
Set JAVA_OPTS=%JAVA_OPTS% -Dbam.properties=<application_server_home>\bam
\bam.properties
• If you are installing a BAM server in a Linux environment, set the location of
bam.properties file as a system property in the setclasspath.sh file. For
example, in Tomcat 9.0.39, open <application_server_home>/bin/
setclasspath.sh and set <application_server_home>/bam/bam.
properties to the bam.properties system property.

9. To modify the location of the log files, open log4j2.properties located in bam-
server\WEB-INF\classes.
10. Use log4j2 standards to modify the location of the log files.
If the log file location is unchanged, the system writes the log files to the
application server home.
11. Save and close log4j2.properties.
12. Copy log4j2.properties to <application_server_home>\bam.
• If you are installing a BAM server in a Windows environment, add the

location of log4j2.properties as a parameter to the setclasspath.bat file. For
example, in Tomcat 9.0.39, open <application_server_home>\bin\
setclasspath.bat and add <application_server_home>\bam
\log4j2.properties to the Dlog4j2.configurationFile parameter.
The following code sample shows log4j2.properties added as a parameter:
Set JAVA_OPTS=%JAVA_OPTS% -Dlog4j2.configurationFile=
<application_server_home>\bam\
log4j2.properties
• If you are installing a BAM server in a Linux environment, add the location
of log4j2.properties as a parameter to the setclasspath.sh file. For example,
in Tomcat 9.0.39, open <application_server_home>/bin/setclasspath.
sh and add <application_server_home>/bam/log4j2.properties to the
Dlog4j2.configurationFile parameter.
14. To start BAM server as a service, set CLASSPATH and JVM options parameter
to the service.bat file and then execute the following command:
set "CLASSPATH=%CATALINA_HOME%\Customconf;%CATALINA_HOME%\bam;%CLASSPATH%"
bam.properties=%CATALINA_HOME%\bam\bam.properties;
-Dlog4j2.configurationFile=%CATALINA_HOME%\bam\log4j2.properties;
//Run the command to start BAM as a service

service.bat install BAM
15. Deploy bam-server.war into the Tomcat application server in the following
location: <application_server_home>\webapps
16. Start the application server.
running: http://<hostname>:<port>/bam-server/admin?action=status

2.14.6 Deploying the BAM server in a clustered environment

To provide high availability of end user report viewing, the BAM server can be
deployed on a manually-provisioned clustered environment. BAM does not support
concurrent processing of events by multiple servers.
1. Deploy the BAM server on each node in the cluster behind a single load
balancer.
2. Edit bam.properties file, when setting up multiple instances of the BAM

server such that all instances point to the same BAM database. “Deploying the
BAM server” on page 49 provides details.
3. Configure bam.cluster.activateOnStartup=true on every BAM server

instance when setting up multiple instances. Ensure that only one instance
processes events at any point in time.
Note: To know which node is processing events, you can execute the
following query:SELECT R.SERVER_NAME,R.TOUCH_TIME,R.STATUS,R.
STATE FROM BAM_SERVER_REGISTRY R. If you stop Server1, then Server2
starts processing events as configured in bam.properties file.
4. Restart the BAM server.
2.14.7 Deploying the BAM server on WebLogic server

procedure with steps specific to the WebLogic Server.
1. Complete the steps in Deploying the BAM server.
2. Create a folder and copy the bam.properties and log4j2.properties file in it:
a. Create a folder called bam in the application server home directory. For
example:
b. Copy the bam.properties and log4j2.properties to the specified location.

You can extract bam.properties from /WEB-INF/classes/ config/ of the bam-
server.war file. You can extract log4j2.properties from /WEB-INF/classes/ of
the bam-server.war file.

directory:


4. In the <WebLogic domain directory>\bin\ folder, edit the setDomainEnv.cmd

file and perform the following steps:
a. Set the classpath by adding the following line at the end of the file:
where <application_server_home> is the home directory of WebLogic

Server.
b. Set the bam.properties and log4j2.configurationFile system property by
modifying the following line:
to
-Dbam.properties="<application_server_home>\bam\bam.properties"
-Dlog4j2.configurationFile="<application_server_home>\log4j2.properties"
c. Set the memory settings by adding the following lines:

Memory arguments:
5. Save the setDomainEnv.cmd file.
6. In the <WebLogic domain directory>\config\ folder, edit the config.xml file by

adding these lines in the <security-configuration> element:
<security-configuration>
false
</security-configuration>
7. Save the config.xml file.
8. Start the WebLogic Server.
9. Login to the WebLogic Server Administration Console as an administrator.
10. In the left pane, select Environment under the Domain Structure section.
11. Select the <AppHost_Server> under the Servers section.
12. In the Settings for <AppHost_Server> page, select the Enable Tunneling
checkbox in the Protocols tab and click Save.
13. In the left pane, select Deployments under the Domain Structure section.
14. In the Control tab under the Summary of Deployments section, click Install.
15. Specify the location of the bam-server.war file in the Path text box.
16. Select the bam-server.war file and click Next.
17. Select the Install this deployment as an application option, and click Next.

18. Verify that the name of the deployment is bam-server and click Next.
19. In the next page, select the No, I will review the configuration later option and
click Finish.
20. In the Control tab under the Summary of Deployments section, select the bam-
server deployment.
21. From the Start drop-down list, select Servicing all requests and click Yes to
confirm. The BAM application is started.
22. Ensure that the state of the bam-server deployment is Active.
running:
http://<hostname>:<port>/bam-server/
2.14.8 Deploying the BAM server on WebSphere Liberty

application server
This procedure is a continuation of the procedure with steps specific to the WildFly
Server.
2. Deploy the bam-server.war file by copying the WAR file to <application_

server_home>\dropins.
running:
2.14.9 Deploying the BAM server on WildFly server

This procedure is a continuation of the procedure with steps specific to the WildFly
Server.
2. Create a custom module for Documentum properties file:
a. Create a folder, com\emc\xcp\main, at the application server home

directory. For example:
<<application_server_home>\modules\system\layers\base>
b. Create a file, module.xml, at the specified location:
<module xmlns="urn:jboss:module:1.1" name="com.emc.xcp">
<resources>
<resource-root path="."/>
</resources>
</module>

c. Create the dfc.properties file for the application to reference the repository
d. (Optional) Update the dfc.properties file by adding the following key:
3. Create a folder and copy the bam.properties and log4j2.properties in it:
<application_server_home>\standalone\bam
b. Copy the bam.properties and log4j2.properties to the specified location.

You can extract bam.properties from /WEB-INF/classes/ config/ of the bam-
server.war file.
You can extract log4j2.properties from /WEB-INF/classes/ of the bam-
server.war file.
repository:
a. Copy the dfc.properties file from the %Documentum%\Config folder on

the Documentum Server to the <application_server_home>\modules\
system\layers\base\com\emc\xcp\main location.
b. Update the dfc.properties file by adding the following key:

5. If you are installing a BAM server in a Windows environment, add the location
of bam.properties file as a system property in the standalone.conf file. For
example, open <application_server_home>\bin\standalone.conf and set
<application_server_home>\standalone\bam\bam.properties as the value
of the system property bam.properties.
The following code sample shows bam.properties added as a system property:
set "JAVA_OPTS=-Xms1G -Xmx1G -XX:MaxPermSize=256M
-Dbam.properties=<application_server_home>\standalone\bam\bam.properties
-Dlog4j2.configurationFile=<application_server_home>\standalone\bam
\log4j2.properties"
6. Start the WildFly Server.
7. In the console management, on the Deployments tab, click Add.
8. Browse and select the bam-server.war file and click Next.
9. Deploy the bam-server.war file by checking the Enable option.
10. Click Save.
running:

2.15. Upgrading BAM server and xCP application
2.15 Upgrading BAM server and xCP application

In xCP 2.0, xCP runtime libraries were bundled separately. It was mandatory to
copy xCP runtime JAR libraries to the lib folder of the application server. Both the
BAM server and the xCP application required these JAR files. While, in xCP 2.1 and
later, the BAM server and xCP application WAR files are packaged differently. The
BAM server and xCP application contain all necessary xCP runtime JAR library files
within their respective WAR files under WEB-INF\lib. So, it is necessary to ensure
that the lib folder of the application server does not contain any of the xCP runtime
libraries to avoid conflict with the JAR files packaged within the WAR files of the
BAM server and xCP application.
To upgrade BAM server and xCP application from 2.0 to 2.2, perform the following
steps:
1. Remove xCP runtime libraries from the lib folder of the application server.
2. Upgrade the BAM server WAR from 2.0 to 2.2.
3. Redeploy all the existing xCP applications. This ensures that the WAR files of
the existing xCP applications are rebuilt with all the necessary JAR files and
redeployed on the application server. If you do not perform this step, existing
xCP applications may fail.
To upgrade BAM server and xCP application from 2.1, perform the following steps:
1. Stop the application server.

2. Upgrade the BAM server WAR.
3. Save the changes.
2.16 Installing Process Integrator

This section provides instructions for installing Process Integrator into an
application server.

2.16.1 Understanding Process Integrator inbound services

Process Integrator provides inbound messaging capabilities to applications based on
the Documentum platform. This capability enables the applications to exchange
documents and information with people outside the organization.
You can install and configure the bps.war file into an application server to enable
use of the delivered Process Integrator inbound messaging process activities. When
you extract the bps.war file, you find these two files available in the bps/WEB-INF/
classes folder:
• bps_template.xml
• dfc.properties
Configure the bps_template.xml and dfc.properties files to use the inbound services.
The following sections describe how to configure these files.
2.16.2 Installing Process Integrator inbound services

1. Download the Process Integrator software.
You must have received instructions through email regarding how to download
products from the OpenText MySupport (https://support.opentext.com) site.
2. Install an application server and create an application server instance for the
supported application server. The application server documentation provides
installation instructions and information on creating an application server
instance.
3. Locate the bps.war file and extract it to a temporary folder using the following
command:
jar -xvf bps.war
4. Edit the bps_template.xml file.
a. Locate bps_template.xml within bps.war\WEB-INF\classes. You edit this

file to specify the repository connection information. This template contains
sample information that you can use as a guide when adding the connection
information for your specific repository.
b. You can encrypt the password in the bps_template.xml file using the
Password Encryption utility. “Using the password encryption utility”
on page 67 provides information on encrypting the password.
c. Remove the comments in the bps_template.xml file after you modify it.
Make sure the bps_template.xml file is a well-formed XML file.
Example:
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<polling_interval>300</polling_interval>
<message_store_home_dir>C:/BPS/message_store</message_store_home_dir>
<instance_name>bps</instance_name>

2.16. Installing Process Integrator
<ha_enabled>FALSE</ha_enabled>
<config_properties>
<property name="mail.imap.partialfetch" value="false"/>
<property name="mail.debug" value="false"/>
</config_properties>
<connections>
<docbase-connection>
<docbase> BPM_Inbound_D6</docbase>
<user> tuser1</user>
<password> tuser1</password>
<domain/>
</docbase-connection>
</connections>
</config>
Polling_interval is the time interval (in seconds) after which the Process
Integrator framework polls for new activity endpoints (inbound listeners).
The default specified in the file is 300 seconds (5 minutes). Use a large value
such as 3600 in a production environment where new endpoints are not
created frequently.
5. Edit the dfc.properties file.
The dfc.properties file is part of the extracted bps.war file. Edit the
dfc.properties file to specify the correct connection broker information and the
correct dfc.data.dir. Add any other properties to dfc.properties.
a. Add the fully qualified hostname for the connection broker to the following
key. You can add backup hosts by incrementing the index number within
brackets.
dfc.docbroker.host[0]=<host_name>
b. If you want to use a port for the connection broker other than the default of
1489, add a port key to the dfc.properties.
dfc.docbroker.port=<port_number>
c. Add the global registry repository name to the following key:
dfc.globalregistry.repository=<repository_name>
d. Add the key for the location of DFC configuration files:
dfc.data.dir=<C\:/Documentum>
e. Add the username of the dm_bof_registry to the following key:
dfc.globalregistry.username=<dm_bof_registry_user_name>
The global registry user, who has the username of dm_bof_registry, has
read access to objects in the /System/Modules and /System/
NetworkLocations only.
f. Add an encrypted password value for the following key:
dfc.globalregistry.password=encrypted_password
Copy the username and encrypted password from the dfc.properties file on
the global registry Documentum Server host. You can also select another
global registry user and encrypt the password using the following
command from a command prompt (assumes the directory containing
javaw.exe is on the system path):

java -cp dfc.jar com.documentum.fc.tools.RegistryPasswordUtils

<password_to_be_encrypted>
6. Save the bps_template.xml and dfc.properties files.
7. Remove the unmodified bps.war file from the temporary folder in Step 3 and
package bps.war using the following command:
jar -cvf bps.war *
8. Deploy the WAR file into the application server.

The first time bps.war is installed, the system reads the bps_template.xml file
and copies it to <dfc.data.dir>/config/bps as bps.xml. The repository password
is encrypted in the bps.xml file in <dfc.data.dir>/config/bps.
The system uses the bps.xml file for retrieving configuration details for message
processing. If there are any changes to configuration details, update the bps.xml
file with current configuration details. Then, restart Process Integrator.
9. In the catalina.properties file located in \tcServer\bpsServer\conf, add the

following:
base.shutdown.port=8042
base.jmx.port=8043
bio.http.port=8040
bio.https.port=8041
2.16.2.1 Installing Process Integrator inbound services on WebLogic

application server
This procedure is a continuation of the “Installing Process Integrator inbound
services” on page 62, procedure with steps specific to the WebLogic Application
Server.
1. Download the bps.war to your local system.
2. Complete Step 2 to Step 6 in “Installing Process Integrator inbound services”

on page 62 section.
3. Complete Step 7 to Step 8 in “Installing Process Integrator inbound services”

on page 62 section.

2.16.2.2 Installing Process Integrator Inbound Services on WildFly

Application Server
Download the latest BPS WAR files for WildFly Application Server from the
OpenText MySupport (https://support.opentext.com) site. Follow these steps to
configure BPS on WildFly Server:
1. Create a folder structure as follows:

<application_server_home>\modules\system\layers\base\<Subfolder1>\<subfolder2>\main
2. Create a module.xml file in the <WildFly-Home>\modules\system\layers\base

\<Subfolder1>\<subfolder2>\main folder location:
<module xmlns="urn:jboss:module:1.1" name="com.bps">
<resources>
</resources>
</module>
3. Add the module created in Step 3 as global-module in

<application_server_home>\standalone\configuration\Standalone.xml file as
follows:
<subsystem xmlns="urn:jboss:domain:ee:4.0">
<global-modules>
<module name=”com.bps”/>
</global-modules>
</subsystem>
4. Add this content in the /sun/jdk/main/module.xml file:

<path name="com/sun/rowset/internal"/>
5. Optional (Optional) Update the dfc.properties of Application.war by adding the

following key:
dfc.security.keystore.file=<Any Physical Directory Location>\dfc.keystore
Note: The keyStore folder is not created automatically, you have to create
it manually.
2.16.2.3 Installing Process Integrator inbound services on WebSphere

Liberty application server
Download the latest BPS WAR files for WebSphere Liberty Application Server from
the OpenText MySupport (https://support.opentext.com) site. Follow these steps to
configure BPS on Liberty Server:
1. Install the WebSphere Liberty Application Server.
2. Create a server and configure server.xml file as described:

<server description="new server">


<featureManager>
<feature>webProfile-8.0</feature>
</featureManager>
....
....
....
....
<remoteFileAccess>
<writeDir>${server.config.dir}/dropins</writeDir>
</remoteFileAccess>
<library id="xcppropeties">
<fileset dir="${server.config.dir}/lib/global" includes="*.properties" />
</library>

<applicationManager autoExpand="true"/>
</server>
a. Create a folder, lib\global, at the application server home directory. For

example:
<<application_server_home>\lib\global>
b. Create the dfc.properties file for the application to reference the repository
c. (Optional) Update the dfc.properties file by adding the following key:
3. Copy the log4j2.properties file to the application_server_home>\lib\

global location.
4. Before starting the WebSphere Liberty application server in a Windows

environment, add the following jvm.options properties in the <application_
server_home>\<server_name>.
-Xms512m
-Xmx1024m
-XX:MaxPermSize=512m
-Dlog4j2.configurationFile=<application_server_home>\lib\global\log4j2.properties
5. Download and deploy the WebSphere specific bps.war file by copying the
WAR file to <application_server_home>\dropins.
6. At the <application_server_home>\bin\ command prompt and start the

WebSphere Liberty application server:
7. Browse to the Process Integrator Server URL to verify that the process integrator
server is up and running:
http://<hostname>:<port>/bps/lsnrs.jsp

2.16.3 Using the password encryption utility

If your security policies require encrypting the authentication password found in
bps_template.xml, use the delivered script located in the bpsInboundTools archive.
1. After editing the bps_template.xml file to include the clear-text username and
password, save and close the file.
2. Locate encryptBPSPassword batch/shell script file.

Navigate to the directory into which you unpacked the bpsInboundTools
archive.
For example, if you extracted bpsInboundTools.zip to the C drive, you can
find the file in C:\bpsInboundTools\bin and the required JAR files in
C:\bpsInboundTools\lib.
3. Open the encryptBPSPassword batch/shell script file and edit the properties to
set the DFC configuration directory, the Java path, and the bps_template.xml
file path.
For example:
set DFC_CONFIG_DIR=C:\Documentum\config
set JAVA=C:\Program Files\Java\jdk<version>\bin\java
set BPS_TEMPLATE_XML_FILE_PATH=C:\Tools\bps_template.xml
4. Execute the encryptBPSPassword batch/shell script.

The script processes the bps_template.xml file and replaces the password with
the string of the encrypted password.
2.16.4 Configuring inbound listeners

Inbound listeners for inbound process activities cannot use the same endpoint
configuration. Avoid creating multiple inbound activities that point to the same
endpoint configuration. To prevent listeners from looking for messages from the
same endpoint, the system does not create listeners for multiple activities that point
to the same endpoint.
Inbound activity type Endpoint configuration parameters

Java Message Service (JMS) Same provider class, provider URL,
connection factory, and queue/topic name
Email Same email server host name, port, user,
email server type, and folder
HTTP Same HTTP URL suffix
FTP Same FTP server host name, port, server
type, base directory, inclusion and exclusion
criteria
Web Services Target Namespace Uniform Resource
Identifier (URI), Port Type, Operation Name

Inbound activity type Endpoint configuration parameters

Java Database Connectivity (JDBC) JDBC URL, SQL Query
Data Query Language (DQL) Local or remote repository (true or false),
repository name, and DQL query
2.16.5 Configuring Process Integrator to support High

Availability
The high availability feature ensures the messaging system continues working
without interruption in the event of a hardware or software failure.
Protocol listeners are assigned an active Process Integrator instance with other
passive instances available, as well. When the active system fails, one of the other
instances provides services for that listener ensuring continual inbound messaging
services. The high availability feature must be enabled for each instance of Process
Integrator.
1. Open the bps.xml file in the bps.war file.
2. Set the element ha_enabled to TRUE. For example:

<ha_enabled>TRUE<ha_enabled>
3. Specify a unique name for the instance in the bps.xml file. For example:
<instance_name>bps1<instance_name>
If you do not specify an instance name, the system creates a default name,
BPS_Instance when the Process Integrator inbound listener starts. If you are
enabling high availability, each instance needs a unique instance name.
4. Repeat steps 2 and 3 for each instance of Process Integrator on the application
server that uses high availability.
The listeners do not automatically fail back to the first server when it comes up.
2.16.6 Setting the listener table attributes

The system creates an entry in the dmc_bps_listener table for every process with an
inbound activity that is installed in the repository. For example, you may want the
FTP listener to run on bps1 and the email listener to run on bps2. Either server can
act as the failover server for the other listener.
There are two ways to set the preferred_instance name and run_in_all instances
(boolean) attributes in the listener table: using DQL or using a script that is provided
for Microsoft Windows systems.

2.16.7 Using DQL to set the listener table attributes

1. Find the r_object_id of the inbound activity located in the dmc_bps_listener
table.
2. Run the following DQL command to set preferred_instance:

update dmc_bps_listener object set
preferred_instance='<preferred instance name>' where
listener_act_id='<objid of inbound activity>';
For example:
update dmc_bps_listener object set
preferred_instance='bps1' where
listener_act_id='4c23cb538003f1b4'
The listener_act_id in the table is the activity ID of the inbound activity.
3. Run the following DQL command to set run_in_all_instances to TRUE.()

By default, this Boolean attribute is false and so the listener can run only in one
running Process Integrator instance.
update dmc_bps_listener object set run_in_all_instances=true
where listener_act_id='4c23cb538003f1b4';
2.16.8 Using a script to set listener table attributes

Note: Do not run listeners for asynchronous protocols on multiple Process
Integrator instances. The run_in_all_instances value must remain 0 for
asynchronous protocols listeners like FTP, email, DQL, DB, and JMS. Two
listeners must not pick up the same message.
1. Locate the setValuesInListenerTable script in the bin directory of the

bpsInboundTools ZIP or TAR file.
The script contains the following text:
echo off
REM ** Point the DFC_CONFIG_DIR to the same location

as the one pointed to by Inbound Framework **
REM ** Point JAVA to the java executable **
set DFC_CONFIG_DIR=
set JAVA=
echo on
"%JAVA%" -classpath %DFC_CONFIG_DIR%;..\lib

[[bpm_infra.jar]|[bpm_infra.jar]];..\lib[[bpm-commons.jar]|
[bpm-commons.jar]];..\lib[[bpmutil.jar]|
[bpmutil.jar]];..\lib\dfc[[dfc.jar]|[dfc.jar]]
[com.documentum.bps.utils.SetAttributesInListenerTable] %1 %2 %3 %4
2. In this script, set the DFC_CONFIG_DIR to the directory containing the

[dfc.properties]. Set JAVA to the java executable directory.
3. Create the listener text file.

The template file setValues_listener_template.txt, located in the bin directory

must be edited to contain the settings for the process name, activity name,
preferred instance, and run_in_all_instances.
Preferred Instance Name is the name of the instance that is designated as the
preferred instance for the listener. Run In All Instances is set to true or false. If
specified as true, the listener can run in any running instance. If not specified,
the default is false and the listener can run only in one inbound instance.
The format for specifying the preferred instance and the run in all instances
settings are:
#ProcessName::ActivityName::<Preferred Instance Name>

::<Run In All Instances>
#<Name of Process>::<name of activity>::<preferred instance name>
#<Name of Process>::<name of activity>::<preferred instance name>
::<Run In All Instances>
#ex:
In each line of the text file, specify each inbound activity for which the preferred
instance needs to be set.
For example:
#Process1::Activity1Inbound::bps1
#Process2::Activity2Inbound::bps1::true
Only update the Preferred Instance column. The other columns are reserved for
internal use only and must not be edited.
4. Save the setValues_listener_template.txt file and record the file path.

The file path is used in the script as a parameter.
5. Complete the four parameters of the script.

Set values for the docbase name, the user, the password, and the full file path to
the file specifying the attributes to be set.
6. Run the setValuesInListenerTable script.

setValuesInListenerTable<docbase><user><password>
<full path to the setValues_listener_template text file>
Running the script populates the listener table for each activity with the values
specified in the file.

2.16.9 Validating inbound services and listeners

Once the web archive (WAR) file has been installed, use the validation URL to check
that the inbound services and listeners are running. The validation URL provides
access to the following information:
• Installed product versions

• Inbound listener details
• Inbound web services
1. Type the following URL into the browser:

http://<host_name>:<port_number>/bps/inbound_details.jsp
If the system shows an error page rather than the Inbound Details page, ensure
that you have correctly entered the host name and port number in the URL. If
the error persists, you may need to reinstall the WAR file.
2. On the Inbound Details page, click the link for the appropriate page:
• Click Here to View Versions

This page lists the versions of the different JAR files used in the inbound
WAR file.
• Click Here to View Inbound Listener Details
This page lists the framework details including the names of any repositories
to which the host machine is listening and the names and versions of
installed inbound runtime modules. The names and status details of all
running inbound listeners on the inbound host are shown after they are
installed and are running. You configure and install inbound listeners using
the integration activities in the process model from xCP Designer. The
inbound_details.jsp page also lists the HTTP URL suffix for HTTP listeners.
• Click Here to View Inbound Web Services
This page lists the Web Service Definition Languages (WSDLs) that are
available to Process Integrator. “Viewing a list of available web services”
on page 71 provides more information about this page.
2.16.10 Viewing a list of available web services

Whenever an inbound web services listener is running, Process Integrator hosts the
corresponding web services. You can view the list of all inbound web services
hosted by Process Integrator using the web services validation URL.
The validation URL provides access to the following information:
• Name of the process with a link to the WSDL

• Port type
• Operations that the web service supports

1. Type the following URL into the browser:

http://<host_name>:<port>/bps/webservice
The page can also be accessed by clicking Click Here to View Inbound Web
services on the inbound_details.jsp page or on the direct jsp page:
http://<host_name>:<port>/bps/webservices.jsp
“Validating inbound services and listeners” on page 71 provides instructions on
using the .jsp pages.
2. To view the WSDL, click the (wsdl) link.
2.16.11 Validating outbound messaging configuration

When the Java Method Server is installed along with the Documentum Server, use
the following URL to view details of the outbound messaging configuration. The
validation URL provides access to the following information:
• System properties
• Installed product versions
• Repository information and runtime modules
1. Type the following URL into the browser after ensuring that the host_name and
port_number in the URL reference the Java Method Server and not the server
hosting the bps.war file:
http://<host_name>:<port_number>/bpm/outbound_details.jsp
If the system shows an error page rather than the Outbound Details page,
ensure that you have correctly entered the host name and port number in the
URL. If the error persists, there may be a problem with the JMS installation.
2. On the Outbound Details page, click the link for the appropriate page:
• View Versions
This page lists the details for the Java system properties on the host machine.
• View Docbases and Runtime Modules
This page lists the framework details including the names of any repositories
the host machine is listening to, the names and versions of installed
outbound runtime modules, and the BPM Servlet URI.

2.16.12 Importing SSL certificates to support encrypted

connections for process activities
To support SSL encryption, you must have an SSL certificate in your environment.
Most of the certification authority (CA) issued certificates are validated by the
system since the Java truststore contains most of the popular root certificates.
For self-signed certificates, the imported certificate must reside in the following
locations:
• Java truststore used by xCP Designer

• Java Method Server bundled Java truststore to make it available during runtime
outbound execution
• Application server bundled Java truststore where Process Integrator is installed
to make it available to Process Integrator during runtime
• xCP application host bundled Java truststore
1. Generate or export the SSL certificate, noting its location.
2. Use the following keytool command to import the certificate from the command
prompt:
keytool -import -noprompt -trustcacerts -alias <alias> -file <certificate-location>
-keystore <java_truststore> -storepass <password>
Where:
• <alias> is the unique name for the alias

• <certificate-location> is the location of the certificate
• <password> is the password of the truststore (default is changeit)
• <java_truststore> is the Java home location of xCP Designer, the bundled Java
truststore of the method server, or the Java home location of the application
server on which Process Integrator runs:
– For xCP Designer:

<java location used by xCPDesigner>\lib\security\cacerts
– For the Method Server:

%Documentum%\java64\JAVA_LINK\lib\security\cacerts (Microsoft
Windows)
$DOCUMENTUM_SHARED$/java64/JAVA_LINK/lib/security/cacerts
(Linux)
– For the application server on which Process Integrator is running:
Import the certificate into the Java truststore (cacerts) to which the
application server points. For example:
%JAVA_HOME%\lib\security\cacerts (Tomcat on Microsoft Windows)

$JAVA_HOME/lib/security/cacerts (Tomcat on Linux)

– For the xCP application host:
For example:
%JAVA_HOME%\lib\security\cacerts (Microsoft Windows)
$JAVA_HOME/lib/security/cacerts (Linux)
3. Verify that the certificate imported successfully.

The system shows a message that the certificate was added to the keystore after
importing the certificate to the trust store. To list the content imported use the
command:
keytool -v -list -alias <alias> -keystore <java_truststore> -storepass <password>
2.16.13 Configuring an HTTP Proxy server for web services

To access a web service that is located outside the firewall through an HTTP proxy
server, configure the HTTP proxy parameters. Adding HTTP proxy parameters to
the Documentum Server Java Method Server startup parameters enables web service
access at application runtime.
1. To configure the Java Method Server startup parameters, open the

StartMethodServer.cmd file from $DOCUMENTUM.
2. Add the HTTP proxy parameters for basic authentication or HTTP over SSL to
the JAVA_OPTIONS.
For example, add the following lines to support HTTP basic authentication:
-Dhttp.proxyHost=<proxy_host> -Dhttp.proxyPort=<port_number> -
Dhttps.nonProxyHosts="<non_proxy_hosts>"
Where:
• <proxy_host> is the hostname of the proxy server.

• <port_number> is the port number of the proxy server. The default value is 80
for HTTP Basic authentication and 443 for HTTP over SSL.
• <non_proxy_hosts> is the list of hosts that can be reached directly, bypassing
the proxy server. This list contains regular expressions separated by '|'. Any
host matching one of these regular expressions is reached through a direct
connection instead of through a proxy.

2.17. Installing the xCP Deployment Agent
2.17 Installing the xCP Deployment Agent

The prerequisites for installing the xCP Deployment Agent are:
• Install the 64-bit Java Development Kit (JDK) and set JAVA_HOME (an
operating system environment variable) to the JDK installation directory. Set
environment variable PATH to %JAVA_HOME%\bin.
• A client system or a VM for xDA Tools.
2.17.1 Setting up xDA and xDA tools

To install xCP Deployment Agent:
1. Download and extract the contents of the xDA_win64.zip or xDA_linux64.tar

to your local machine. Throughout this guide, ${xda-home} refers to the root
directory of xDA.
2. Edit the xda-config.properties in ${xda-home}\config. The following table
describes the value for each parameter:
Parameter Description
xda.data.dir (Optional) Specify the path to alternate
location on the xDA machine where you
want xDA to maintain catalog information
and log files. Ensure that the directory
name does not contain spaces. The default
location is ${xda-home}.
logging.config The path of the log4j2.properties file.
Do not change the value.
server.port Specify the port where you want the xDA
application to run. Default port is 7000.
wildfly.libs.home (Optional) Specify the path to the WildFly
client directory on the xDA machine while
deploying an application in the WildFly
application server.
jboss.libs.home (Optional) Specify the path to the JBoss
client directory on the xDA machine while
deploying an application in the JBoss
application server.
websphereliberty.libs.home (Optional) Specify the path to the
WebSphere client directory on the xDA
machine while deploying an application in
the WebSphere application server.

redirectToHTTPS 1 (Optional) Set this variable to true if the
LoadBalancer is configured in HTTPS and
the proxy is configure in HTTP mode.
When set to true, HTTP response is
redirected to HTTPS protocol.
redirectPort 1 (Optional) If redirectToHTTPS is enabled
Default redirection port is set to 443.
Should be changed if https is configured
on different port.
1 If xDA is not accessible when we have proxy layer between LoadBalancer and xDA
service in Cloud. Use the following properties to reteieve the protocol from
LoadBalancer and route the response using the same protocol.
3. For log4j2.properties file, set logs for various parameters to debug the
configuration.
4. Add these entries to the xda-config.properties file to enable SSL mode on xDA
as follows:
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=keystore.jks
server.ssl.key-store-password=<keystore-password>
server.ssl.key-alias=<certificate-alias>
server.ssl.key-password=<key-password>
server.ssl.trust-store=truststore.jks
server.ssl.trust-store-password=<truststore-password>
This looks for the TrustStore and KeyStore at ${xda-home}\xDA\bin folder.
5. While using strong encryption, use the appropriate java.policy and JCE JAR
along with the following properties:
server.ssl.ciphers=<ssl cipher used to create certificate>
server.ssl.protocol=<Compatible ssl protocol>
For example: If a certificate is created with "256-bit AES encryption with

SHA-1 message authentication and RSA key exchange",
set the properties as follows:
server.ssl.ciphers=TLS_RSA_WITH_AES_256_CBC_SHA
server.ssl.protocol=TLS
6. Configuring Repository service

By default, DFC searches the value of dfc.security.ssl.truststore (property for
certificate) in dfc.properties for SSL communication. If found, DFC uses the
certificate-based SSL communication. Otherwise, DFC defaults to the cipher-
based anonymous SSL supported by Java.
JDK 11.0.12 and later do not support anonymous ciphers for SSL or TLS
communication and results in the handshake failure exception while xDA
connects with repository. You can use one of these methods to connect with the
repository:
a. Anonymous SSL communication:

OpenText strongly recommends to use certificate-based SSL communication.

However, if you want to use anonymous SSL communication, perform the
following steps:
i. In JDK 11.0.12 and later, open the java.security file from <Java_Home>
\conf\security.
ii. Find the line starting with jdk.tls.disabledAlgorithms.
iii. Remove anon from the list of disabled algorithms.
iv. Save your changes.
b. Certificate-based SSL communication:
• When xDA is running in HTTP mode, perform the following steps:

i. Create a Truststore and add Documentum Server certificates (server,
connection broker, and exdocbroker) to it.
ii. Add these arguments in xda.bat and xDA-service-installer.xml
(Windows) or xda.sh (Linux) file of xDA as follows:
-Djavax.net.ssl.trustStore=<trust-store>
-Djavax.net.ssl.trustStorePassword=<trust-store-password>
Examples:
xda.bat : "%JAVAHOME%"\bin\java.exe -Djavax.net.ssl.trustStore=<trust-

store>
xda-service-installer.xml : <arguments> -Xmx1024m

-Djavax.net.ssl.trustStore=<trust-store>
xda.sh : "$JAVA_HOME"/bin/java -Djavax.net.ssl.trustStore=<trust-

store>
• When xDA is running in HTTPS mode, add the Documentum Server

certificates (server, connection broker, and exdocbroker) in Truststore
specified in the server.ssl.trust-store property of the xda-config.
properties file.
7. To start xDA application:
• For Windows: Run xda.bat in ${xda-home}\bin using administrator role.
Note: A separate command prompt is opened for Basex server when

you run the xda.bat command. Do not close either of the two
command prompts.
• For Linux:
a. Open xda.sh located at ${xda-home}\xDA\bin for editing.
b. Append -Djava.security.egd=file:/dev/./urandom at the end of
XDA_OPTS parameter as follows:

XDA_OPTS="-Xmx4096m……
……/log4j2.properties -Djava.security.egd=file:/dev/./urandom"
c. Run xda.sh in ${xda-home}\bin to start the xDA application.

8. To verify that the xDA installation is successful, open the following URL in a
web browser:
https://<host>:<port>/xda
<host> is the host name or IP address of the machine where xDA is installed.
<port> is the port number on which xDA is listening.
The installation is successful if you can see the login page.
Note: When you log in to xDA through GUI or xDA-Tools utility for the
first time, the system prompts you to change the default password.
9. To install xDA tools on the same machine where you have installed xCP
Deployment Agent, complete the following steps:
a. Install the 64-bit JDK on a machine that meets the requirements for xDA
Tools. Set JAVA_HOME (an operating system environment variable) to the
directory where the 64-bit JDK is installed.
b. Download and extract xda-tools_win64.zip or xda-tools_linux64.tar
to a convenient location in this machine.
c. The extracted xDA Tools folder structure is described in the following table:
Folder Contents
bin Executable files, including xda.bat/sh
and configure-xda.bat/sh.
blueprints Module-template files that describe the
structure of environment templates used
to register manually-provisioned
environments.
config Configuration files, including
xda.properties to connect to xDA.
lib Libraries needed to deploy the xCP
application and libraries required by the
xDA API plug-ins.
logs Log files.
reports Reports generated by the xDA CLI
commands.
Throughout this guide, ${xda-tools-home} refers to the root directory of

xDA Tools.
You can set up xDA Tools on any number of machines. Your organization might
want to have xDA Tools installed on additional machines so that each member
of a team can run xDA commands on a separate machine.

10. To enable SSL communication between xDA Tools and xDA, append these
entries to the XDA_OPTS parameter in the xda.bat or xda.sh file located at $
{xda-tools-home}\bin:
-Djavax.net.ssl.trustStore=<path-to-xdatoolsTrustStore>
-Djavax.net.ssl.trustStorePassword=<truststore-password>
11. On an xDA tools machine, run the xDA configuration script:

a. Connect to xDA: Set up xDA Tools and open the ${xda-tools-home}
\config\xda.properties file.
• Specify the IP address of the machine where the xDA is running and the
port number on which the xDA is listening.
• For xda-schema, specify the xDA host protocol as http or https.
These entries point xDA Tools to the running xCP Deployment Agent.
b. Set up a password for the xDA admin user and run xDA configuration
script: Double-click configure-xda.bat (for linux, run configure-xda.sh)
in ${xda-tools-home}\bin. At the prompt, type the user name and
password. If you have not changed the default xDA password, you will be
prompted to change it.
Note: If you change xDA password using xDA tool or UI, you must
reopen the xDA tool and run configure-xda command to sync the
updated password.
The system imports the following configuration information:
• The bootstrap-dctm-configuration.xml file from ${xda-tools-home}

\config
• Default environment templates from ${xda-tools-home}\blueprints\

module-templates.
12. To enable SSL communication between xCP Designer and xDA, add these
entries to the xCPDesigner.ini file:
-Djavax.net.ssl.trustStore=<path-to-xcpTrustStore>
-Djavax.net.ssl.trustStorePassword=<truststore-password>
You can now use the xDA Management Center to register an environment. “Using
the xDA management center to register an environment” on page 83 provides
instructions.

2.17.2 Installing xDA as a Windows service

The prerequisites for installing xDA as a Windows service are as follows:
• Install the 64-bit Java Development Kit (JDK).

• Install the Microsoft .NET framework 3.5 version.
Installing xDA Windows service

1. Download and extract the contents of the xDA_win64.zip to your Windows
machine. Throughout this guide, ${xda-home} refers to the root directory of
xDA.
2. Log in to the Windows machine as an administrator user or a user with
administrative privileges.
3. At the ${xda-home}\bin prompt, run the manage-xda-services.bat
command and enter I when prompted to install and create xDA as a service:
xDA\bin>manage-xda-services.bat
Choose from the following options for xDA services
I to Install
U to Uninstall
S to Start
T to Stop
C to Check status
E to Exit
Enter your choice : I
4. Click Start > Programs > Administrative Tools > Services.

5. Open Windows Services application to verify if the xDA service has been
successfully installed. The name of the service appears as Documentum xCP
Deployment Agent and Documentum xCP Deployment Agent Basex Service.
Starting or stopping xDA Windows service

1. Log in to the Windows machine.
2. There are two ways to start or stop xDA windows service:
• Using create-xda.bat file.

• Using the Windows Services option
3. Using manage-xda-services.bat:
• To start xDA service, run the manage-xda-services.bat command and

enter S when prompted:
I to Install
U to Uninstall
S to Start
T to Stop
C to Check status
E to Exit

Enter your choice : S
• To stop xDA service, run the manage-xda-services.bat command and

enter T when prompted:
I to Install
U to Uninstall
S to Start
T to Stop
C to Check status
E to Exit
Enter your choice : T
4. Using the Windows Services option:
• To start xDA service:

a. Click Start > Programs > Administrative Tools > Services.
b. Select Documentum xCP Deployment Basex Agent service and click
Start service.
c. Select Documentum xCP Deployment Agent service and click Start
service.
• To stop xDA service:
a. Click Start > Programs > Administrative Tools > Services.
b. Select Documentum xCP Deployment Agent service and click Stop
service.
c. Select Documentum xCP Deployment Basex Agent service and click
Stop service.
Uninstalling xDA Windows services

1. Log in to the Windows machine as an administrator user.
2. At the ${xda-home}\bin prompt, run the manage-xda-services.bat
command and enter U when prompted to uninstall xDA services:
I to Install
U to Uninstall
S to Start
T to Stop
C to Check status
E to Exit
Enter your choice : U
Upgrading xDA
While installing any newer version of xDA or installing the xDA patch, if your $
{xda-home} path changes, the user must stop and remove the existing xDA Service.

1. Remove the existing xDA Service by following instructions in the Uninstalling

xDA Windows Servicesection.
2. Reinstall the newer xDA service by following instructions in the Installing xDA
Windows Service section.
Troubleshooting
While starting a xDA service, in case you experience any errors, check the xDA-
installer-service.err.log file located at ${xda-home}\logs.
2.17.3 Connecting to xDA from xDA tools

After you have set up xDA Tools and installed xDA, you can connect to xDA from
xDA Tools.
1. On each machine that you intend to use for connection to the xDA, set up xDA
Tools. “Setting up xDA and xDA tools” on page 75 provides details.
2. On each machine where you have set up xDA Tools, edit the xda.properties
file in ${xda-tools-home}\config.
Example 2-1:
The following is an example of the xda.properties file:
xda-host = 192.0.2.0
xda-port = 8080
xda-schema = http
The following table describes each property in this file:
Property Description
xda-host The IP address or hostname of xDA.
xda-port The port of the xDA.
xda-schema Specify the protocol for access to the xDA:
• http
• https
You can point xDA Tools to a different xDA by replacing or revising the xda.
properties file.

2.18. Using the xDA management center to register an environment
2.17.4 Logging In to xDA from xDA tools

1. To login to xDA, double-click xda.bat in ${xda-tools-home}\bin.
2. At the prompt, type your username and password.

Three failed attempts end the session.
To end a session, type exit.
2.18 Using the xDA management center to register an

environment
The xDA Management Center lets you register manually-provisioned environments.
This process includes configuring various manually-installed xCP components.
The statuses for a manually-provisioned environment, a service, or an endpoint are

similar. The following table describes these possible statuses:
Status Manual Service Endpoint

Environment
Registered The system has all The service has all The endpoint has all
required information required information. required information.
for all host groups
and services.
Registration Some required Some required Some required
Incomplete information for host information for the information for the
groups or services is service is missing. endpoint is missing.
missing.
2.18.1 Logging In to the xDA management center

Before you log in to the xDA Management Center install the xCP Deployment
Agent. “Installing the xCP Deployment Agent” on page 75 provides details.
1. Open the following URL in a browser:

http://<host>:<port>/xda
where <host> is the host name or IP address of the machine where the xCP
Deployment Agent is running and <port> is the port number on which the xCP
Deployment Agent is listening. If this server is the same computer as the
browser, you can use:
http://localhost:<port>/xda
2. Type an xCP Deployment Agent user name and password. Click Login.

2.18.2 Configuring an environment template

The system uses an environment template as a base when you register your
environment. Default environment templates are available for this purpose.
However, if you need to customize an environment template to use the supported
Application servers, or for any reason, use the following steps:
1. Start xDA and log in to xDA Management Center. “Logging In to the xDA
management center” on page 83 provides instructions.
2. Click Catalog. A list of environment templates appears.
3. Clone an environment template:
a. Select an environment template and click Clone Template. The system

creates a copy of the selected environment template.
b. Type a unique name for the new environment template.
c. Type a unique key for the environment template.
d. (Optional) Type a description for the new environment template.
e. Click Done. The system saves the information to the database.
f. Click OK. The new environment template appears in the list.
4. Update the new environment template:
a. Select the environment template and click Update Template.

b. (Optional) In the Properties tab, type a key and a description for the
environment template. These fields contain the same values as when you
cloned the environment template.
c. In the Prerequisites tab, specify on which application server you intend to
deploy the application.
d. In the Host Groups tab, select each host group and click Edit. The Edit Host
Group dialog box appears. For each host group, specify value for the field
described in the following table:
Field Description
Description (Optional) Type a description for the
host group.
In Edit Host Group dialog box, click Done. The system saves any new
information into memory, but does not save the information to the database.
e. In the Services tab, select each service and click Edit. The Edit Service
dialog box appears. Configure each tab as follows:
• On the Properties tab, specify values for the fields described in the
following table:

Field Description
Enable Service Indicate whether you want to enable
the service for the environment
template.
Some services, such as the repository
service, are required. You cannot
disable these services.
Host Group Specify which host group you want to
associate with the service.
• On the Service Components tab, indicate which optional service

components you want to disable for the service.
Click Done. The system saves any new information into memory, but does
not save the information to the database.
f. Click Finish. The system saves all information (any information in memory
and any new information) to the database.
2.18.3 Registering an environment

1. Start xDA and log in to the xDA Management Center. “Logging In to the xDA
2. Click Environments.
3. Click Create Environment. The Environment Template Selector appears.
4. (Optional) Click View Details next to each environment template name for
more details.
5. Select an environment template. After you finish creating the environment, you
cannot choose a different environment template for this environment.
6. Click Done. The system saves any new information into memory, but does not
save the information to the database.
7. Configure each tab:
• “Configuring general properties” on page 86

• “Configuring accounts” on page 86
• “Configuring host groups” on page 86
• “Configuring hosts” on page 87
• “Configuring services” on page 88
8. At any point, you can click Apply to save to the database any properties you
have specified so far.
9. When you have finished configuring the environment, click Finish. The system
saves all information (any information in memory and any new information) to
the database.

2.18.4 Configuring general properties

In the Properties tab, specify environment properties as described in the following
table:
Field Description
Environment Mode Select either Production or Development as
the mode of the environment. After creating
an environment, you can change the
environment mode only from Production to
Development. Once you change the
environment mode to Development, you
need to create an environment again with
environment mode as Production.
Environment Name Type a name for the environment, unique
within the xDA Management Center.
Description (Optional) Type a description for the
environment.
2.18.5 Configuring accounts

In the Accounts tab, provide credentials to serve as the default account for service
endpoints:
Field Description
Username Type a user name to access the relevant
systems.
Password Type the password for accessing the relevant
systems.
Domain (Optional) Type the domain for accessing the
relevant systems. For clustered
environments, the domain is required.
2.18.6 Configuring host groups

The system automatically populates the Host Groups tab with information from the
selected environment template.
(Optional) In the Host Groups tab, configure each host group as a container for one
or more hosts:
1. Select the host group that you want to modify and click Edit. Type a description
for the host group and click Done. The system saves any new information into
memory, but does not save the information to the database.
2. If you want to add a host group, click Add. Type a name for the host group,
unique within the environment. After you finish creating the host group, you
cannot type a different name for this host group. Type a description for the host

group. If you want to add another host group, click Save and Add Another.
Otherwise, click Done. The system saves any new information into memory,
but does not save the information to the database.
Delete is not available for a default host group, or for a host group associated
with a service.
The system does not allow you to enter the same IP address for different host
groups. Instead, you can associate more than one service to the same host group. For
example, if you are using the same load balancer machine for two AppHost
machines and two BAM machines, you can associate all four services and all five
machines with one host group:
• The AppHost load balancer service

• The AppHost service
• The BAM load balancer service
• The BAM service
• Both AppHost machines
• Both BAM machines
• The load balancer machine
2.18.7 Configuring hosts

Use the Hosts tab to specify each host in your environment:
1. Click Add.
2. Specify an IP address or a host name.
3. Select a host group.
4. If you want to add another host, click Save and Add Another. Otherwise, click
Done. The system saves any new information into memory, but does not save
the information to the database.
5. If you want to modify the properties for a host, select the host from the list and
click Edit. When you have finished modifying the host, click Done. The system
saves any new information into memory, but does not save the information to
the database.

2.18.8 Configuring services

In the Services tab, configure each service in your environment:
1. Select the service from the list and click Edit Service.
2. Specify the general properties of the service as described in the following table:
Field Description
Enable Service (Optional) If you do not need this service
in your environment, clear the checkbox to
disable the service.
The repository service is always enabled.
Host Group Select the host group on which the service
is running.
If you change the host group associated
with a service, remember to update
endpoint properties to choose one or more
hosts from that host group.
Version Type the version of the service, using the
following format:
mm.mn.xxxx.yyyy
Where:
• mm is the major version number
• mn is the minor version number
• xxxx is the update number
• yyyy is the build number
For example, the service version can be:
7.0.0001.0005
3. On the Endpoints tab for each service, configure each service endpoint.
Endpoints enable you to configure communication pathways between systems.
Select the endpoint and click Edit.
a. “Service endpoint configuration” on page 89 describes how to configure

the fields unique to each endpoint.
b. Specify credentials for the service endpoints that require credentials: By
default, some services use the credentials that you specified on the Accounts
tab. If you want the service to use different credentials, clear Use Default
Service Account?. Specify a username, password, and (optionally) domain.
For the Tomcat or tc Server application server, specify Tomcat manager user
credentials.
c. Select one or more hosts for the service endpoint. The list of hosts depends
on the host group associated with the service endpoint.
If you deploy the BAM server in a clustered environment, select the host of
the load balancer for BAM.

d. When you have finished configuring the service endpoint, click Done. The
system saves any new information into memory, but does not save the
information to the database.
4. When you have finished configuring the service, click Apply or Finish. The
system saves all information (any information in memory and any new
information) to the database.
2.18.9 Service endpoint configuration

“Configuring services” on page 88 describes how to specify credentials and hosts for
service endpoints. The following table lists the endpoints for each service and
describes how to configure each endpoint further:
Service Endpoint Field Description

Advanced Document adtsEndpoint Port Type the HTTP port
Transformation of the CTS Advanced
Services Document
Transformation
Services component.
AppHost appHostEndpoint Port Type the HTTP port
or HTTPS port of the
xCP application host.
Protocol Select either HTTP or
HTTPS as a
communication
protocol.


URL Type the URL to
access the
administrative
console of the
AppHost application
server. Include the
protocol, host, and
port as follows:
<protocol>://
<host>:<port>
For WildFly or JBoss:

<protocol>://
<host>:<port>/
console
For WebLogic:
<protocol>://
<host>:<port>/
console
For WebSphere
Liberty:
<protocol>://
<host>:<port>
Note: Both
remote address
valve and
remote host
valve are
mutually
exclusive. Only
one of them can
be used at a
time.
AppHost (if you have WildFlyEndpoint/ WildFly/ Select either native
selected WildFly or JBossEndpoint JBossEndpoint or HTTPS as a
JBoss server) Management communication
Protocol protocol.


WildFly/ Type the WildFly or
JBossEndpoint JBossEndpoint
Management Port management port of
the Apphost WildFly
or JBoss server
(Management port of
Domain Controller
for a clustered
WildFly).
• Management-http
port if native
protocol is
selected.
• Management-https
port if HTTPS
protocol is
selected.
Key Store Path (Optional) Type the
path of the keystore
for the system to use
during SSL
handshake.
Key Store Password (Optional) Type the
password of the
keystore for the
system to use during
SSL handshake.
Trust Store Path (Optional) Type the
path of the truststore
during SSL
handshake.
Trust Store Password (Optional) Type the
password of the
truststore for the
SSL handshake.
Cluster Enabled Specify whether you
want xDA to enable
clustering for this
endpoint.


WildFly or JBoss Specify the server
Server Group group to which the
application is to be
deployed.
If Cluster Enabled is
enabled, you must
configure the
property.
AppHost (If you have weblogicEndpoint webLogic- Type the name of the
selected weblogic TargetServers target server where
server) you intend to deploy
xCP applications. If
AppHost is clustered
in your environment,
type the cluster
name.
webLogicAd- Type either http or
minProtocol https as a
communication
protocol.
clusterEnabled Type either true or
false to indicate
whether your
environment is
cluster enabled.
AppHost (If you have WebSphereLibertyEn WebSphereLiberty Type the
selected dpoint connector port WebSphereLiberty
WebSphereLiberty management port of
server) the Apphost
WebSphereLiberty.
Trust Store Path Type the path of the
truststore for the
SSL handshake.
Note: When
Liberty is
configured for
SSL, the
Apphost
certificate must
be added to the
xDA Truststore
and cacerts of
Java used by
xDA.


Trust Store Password Type the password of
the truststore for the
SSL handshake.
Audio Video avtsEndpoint Port Type the HTTP port
Transformation of the CTS Audio
Services Video
Transformation
Services component.
Business Activity bamEndpoint Port Type the HTTP port
Monitor of the BAM
component. If you
deploy the BAM
server in a clustered
environment, specify
port details of the
load balancer for
BAM.
URL Type the URL to
access the BAM
component. Include
the protocol, host,
port, and default
URL prefix as
follows:
http://
<host>:<port>/
bam-server
Business Activity loadBalancerEndpoin Port Type the HTTP port
Monitor Load t of the Business
Balancer Activity Monitor load
balancer.
URL Type the URL to
access the Business
Activity Monitor load
balancer. Include the
protocol, host, and
port as follows:
http://
<host>:<port>
Content Intelligence cisEndpoint Port Type the HTTP port
Service of the CIS
component.
Documentum daEndpoint Port Type the HTTP port
Administrator of the Documentum
Administrator.


URL Type the URL to
access the
Documentum
Administrator.
Include the protocol,
host, port, and
default URL prefix as
follows:
http://
<host>:<port>/da
File Server dataAccess UNC Path Type the shared UNC
path.
Media mtsEndpoint Port Type the HTTP port
Transformation of the CTS Media
Services Transformation
Services component.
Process Integrator bpsEndpoint Port Type the HTTP port
of the Process
Integrator
component.
URL Type the URL to
access the Process
Integrator
component. Include
the protocol, host,
port, and default
URL prefix as
follows:
http://
<host>:<port>/
bps
Repository repositoryEndpoint Repository Name Type a unique user-
defined value to
identify the
repository.
Connection Broker Type the HTTP port
Port of the machine where
connection broker is
installed.


xPlore xploreEndpoint xPlore Server Port Type the port
number on which the
xPlore primary
instance is listening.
Note: Dsearch
and xDB admin
password
should be same
inside the
DSearch
service. Make
sure that the
same password
is configured in
the xDA
endpoint.
xPlore Server URL Type the URL to test
if the xPlore primary
instance is running.
primary host, port,
and default URL
prefix as follows:
http://<xPlore
Server primary
host>:<port>/
dsearch
xPlore Index Agent Type the port
Port number at which the
xPlore Index Agent
listens for HTTP
requests.
xPlore Index Agent Type the URL to start
URL the xPlore Index
Agent servlet.
primary host, port,
and default URL
prefix as follows:
http://<xPlore
Index Agent
primary
host>:<port>/
IndexAgent

2.18.10 Configuring a clustered environment

1. When you begin registering your manually provisioned environment, in the
Environment Template Selector, select a cluster template.
2. In the Hosts tab, specify multiple hosts for each clustered component.
For example, if your environment has a clustered Documentum Server with two
nodes, add two hosts for the repoVM host group. When you are done adding
those two hosts, the repoVM host group appears twice in the list of hosts.
3. In the Host Groups tab, look at the number of hosts for each clustered
component.
Considering the example in the previous step, the repoVM row would have 2 in
the Number of Hosts column.
4. In the Services tab, when configuring each clusterable service in your

environment, perform the following steps:
a. In the Properties tab, make sure the service is associated with an

appropriate host group.
By default, the repository service is associated with the repoVM host group.
b. In the Endpoints tab, select the endpoint and click Edit. In the Endpoint
dialog box, under Configuration Details, select multiple hosts for the host
group.
Considering the example in the previous steps, for the repository endpoint,
you could enable or disable each of the two hosts that you previously
specified for repoVM.
2.18.11 Updating environment configuration

1. Start the xDA Management Center and log in. “Logging In to the xDA
2. Select the environment that you want to update. Click Update Environment.
3. Configure each tab:

• “Configuring host groups” on page 86
• “Configuring hosts” on page 87
4. At any point, you can click Apply to save to the database any properties you
have specified so far.

2.18.12 Viewing service component versions

1. Start xDA and log in to the xDA Management Center. “Logging In to the xDA
2. Select the environment for which you want to view the versions of the service
components.
3. Depending on the option you select to view service component versions,

perform these steps:
a. View Environment
b. Validate Environment Result
4. View Environment: Perform the following steps:
a. Click View Environment.

b. Examine the information in the Component Properties tab.
c. View the properties of the service components as described in the following
table:
Field Description
Service Component Identifies service components that are
part of a specific service.
Service Identifies the services in the
environment.
Version Identifies the version of a specific
service component.
By default, all default versions appear
for the service components. When you
synchronize the environment, the
system fetches, saves, and displays the
actual version for service components.
In case services are not available or in
down state, the default versions are
displayed.
d. Click Copy version information to copy version specific information of the

services to the clipboard. On successful operation, you can paste the
information to any external text editor.
Note: On successful copy operation, the system shows the success

message.
e. Click Export version information to export the service component
information in CSV format. The information contains these entities—service
component, service, and version.
f. Click OK.

5. Validate Environment Results: Perform the following steps:
a. Click Validate Environment Results.

b. Examine the information in the Service Status screen.
c. View the properties of the service components as described in the following
table:
Field Description
Service Component Identifies core service component that is
part of a specific service.
Validation URL Details Identifies the URL of a service
component.
Status Identifies the status of the service
component—Failed or Passed.
Version Identifies the version of the core service
component.
By default, all default versions appear
for the service components. However,
when you synchronize the environment,
the system fetches and displays the
actual version for the core service
component. For example, for ADTS
service, the ADTS and JDK services are
required. On synchronization, the
system displays the actual version of the
ADTS service.
d. Click OK.
2.18.13 Synchronizing a manually provisioned environment

When you synchronize an environment, the xCP Deployment Agent examines your
environment and updates the system to reflect the correct services, components, and
their versions. Perform synchronization in each of the following scenarios:
• After you register your manually provisioned environment.

• After manually changing any components in your environment.
• Before deploying an xCP application to your environment.
Synchronizing an environment requires a connection to the xCP Deployment Agent.

2.19. Using Commands to Create an Environment
2.18.14 Synchronizing an environment

1. Start xDA and log in to the xDA Management Center. A list of environments
appears.
2. Select the environment that you want to synchronize. Click Maintenance. The
Maintenance dialog box for the selected environment appears.
3. Click Synchronize Environment and then click OK.

Details about the running job are available on the Operations tab.
4. (Optional) When the synchronization completes, verify the changes. In the list
of environments, select the environment and click View Environment. Examine
the information on the Services tab.
After the environment has been successfully synchronized, you can deploy xCP
applications to the environment.
2.18.15 Unregistering an environment

You can use the xDA Management Center to unregister an environment, if it is not
currently in use. If the system is currently registering the environment, wait until
that process completes before attempting to unregister the environment.
1. Start xDA and log in to the xDA Management Center.“Logging In to the xDA
2. Select the environment or environments that you want to unregister. Click

Unregister Environment and then click Yes.
2.19 Using Commands to Create an Environment

The environment.yml file lets you create manually-provisioned environment and it
includes setting up values for various manually-installed xCP components.
Prerequisites
• Ensure that xDA is installed and configured with xCP environment templates.
Installing the xCP Deployment Agent provides details about installing xDA.

2.19.1 Creating an environment

1. Double-click xda.bat in ${xda-tools-home}\bin and log in to xDA.
2. At the xda> prompt, type

create-environment --yml-file <Location of YML file>
The sample environment.yml is located at the ${xda-tools-home}\config

folder. Edit this file to provide your environment endpoint details.
3. Resolve any errors that may occur and run the command again.
On successful execution of the command, the system displays this successful
message. For example:
Environment "xyz" created successfully with "Registered" status.
All values for password related properties mentioned in the environment.

ymlfile can be entered as plain text, encrypted or can be left blank. The system
prompts you to enter password on the console when password is left blank in
the environment.yml file.
4. Configure each section in the environment.yml file:
• Encrypting Passwords
• “Configuring host groups and hosts” on page 102
2.19.2 Encrypting passwords

For security purpose, use the command to encrypt your system account passwords.
You may specify these encrypted passwords in the environment.yml file while
creating environment using create-environment command.

encrypt-passwords [--properties-file Location of Password Properties File]
• The command encrypts the passwords mentioned in plain text in the

passwords.properties file and creates an encrypted counterpart text file at $
{xda-tools-home}\config. For example, when you specify location of
passwords.properties file, the system encrypt the passwords and creates an
encrypted counterpart text file as encrypted_passwords.txt file.
• If you do not specify the location of password properties file, the encrypt-
passwords command, by default, picks up the ${xda-tools-home}\config\
properties-file\passwords.properties file to encrypt passwords.

2.19.3 Configuring general properties

The system uses an environment template as a base when you register your
environment. Default environment templates are available for this purpose.
1. Locate environment.yml file in the ${xda-tools-home}\config folder and

open it with any external text editor.
# environmentTemplate, environmentName are mandatory fields
environmentTemplate: xCP-16.7-Developer-Environment-Template
environmentName: myEnvironmentName12345
# environmentMode is mandatory and can be 'Development' or 'Production'
environmentMode: Development
environmentDescription: My Environment Description
2. For each property, specify value in the field described in the following table:
Fields Description
environmentTemplate Specify the name of the environment
template. Configuring an Environment
Template provides instructions.
environmentName Type a unique name for the environment.
environmentMode Select either Production or Development
as the mode of the environment.
environmentDescription (Optional) Type a description for the
environment.
2.19.4 Configuring accounts

1. Edit environment.yml file in the ${xda-tools-home}\config folder with any
external text editor.
defaultSystemAccount:
username: myDefaultUsername
password:
domain:
2. In the defaultSystemAccountsection, specify value in the field described in the

following table:
Fields Description
username Type a user name to access the relevant
systems.
password Type the password for accessing the
relevant systems.
domain (Optional) Type the domain for accessing
the relevant systems. For clustered
environments, the domain is required.

2.19.5 Configuring host groups and hosts

hostGroups:
# 'name' is mandatory field for hostGroup
- name: xCPVM1
description: Developer Environment Host Group 1
# Provide either 'hostname' or 'ipAddress' for a host
hosts:
- hostname: MYHOST1
ipAddress:
# uncomment below to add multiple hosts to host group
# - hostname:
# ipAddress: 192.168.1.1
2. In the hostGroups section, configure each host group as a container for one or
more hosts:
Fields Description
name Type a name for the host group, unique
within the environment.
description (Optional) Type the description for the
host group.
3. In the hosts section, specify one or more hosts for your environment:
Fields Description
hostname Type the host name associated with a host
group.
ipaddress Type an IP address associated with a host
group.
Note: Specify either an IP address or host name.
You can add multiple host groups in a similar manner.
2.19.6 Configuring services

2. In the services section, configure each service for your environment.
Fields Description
serviceName Displays the name of the service. Do not
change the name of the service.

Fields Description
enabled If you do not need this service in your
environment, set this value as false to
disable the service.
version Type the version of the service, using the
following format:
mm.mn.xxxx.yyyy
Where:
• mm is the major version number
• mn is the minor version number
• xxxx is the update number
• yyyy is the build number
For example, the service version
can be:
16.7.0000.0005
hostGroup Type the existing host group on which the

service is running. It is a mandatory field
for service and it must be existing
HostGroup name from hostGroups
section.
3. “Service endpoint configuration” on page 103 describes what values to provide

for service endpoint properties.
4. If your service uses different credentials, set useDefaultSystemAccount as

false. Otherwise, the service uses defaultSystemAccount credentials.
5. Select one or more hosts for the service endpoint. The list of hosts depends on
the host group associated with the service endpoint.
6. Save the file.
2.19.7 Service endpoint configuration

Endpoints enable you to configure communication pathways between systems.
“Configuring services” on page 102 describes how to specify credentials and hosts
for service endpoints. The following table lists the endpoints for each service and
describes how to configure each endpoint further:
Service Endpoint Property Description

Advanced Document adtsEndpoint port Type the http port of
Transformation the CTS Advanced
Services Document
Transformation
Services component.
AppHost appHostEndpoint port Type the http port or
https port of the xCP
application host.


protocol Type the http or https
protocol as a
communication
protocol.
url Type the URL to
access the
administrative
console of the
AppHost application
server. Include the
protocol, host, and
port as follows:
<protocol>://
<host>:<port>
For WildFly:
<protocol>://
<host>:<port>/
console
AppHost (for wildflyEndpoint WildFlyManagement Type either native
WildFly endpoint) Protocol or https as a
communication
protocol.
WildFlyManagement Type the WildFly
Port management port of
the Apphost WildFly
server (Management
port of Domain
Controller for a
clustered WildFly).
keyStorePath (Optional) Type the
path of the keystore
during SSL
handshake.
keyStorePassword (Optional) Type the
password of the
keystore for the
SSL handshake.
trustStorePath (Optional) Type the
path of the truststore
during SSL
handshake.


trustStorePassword (Optional) Type the
password of the
truststore for the
SSL handshake.
clusterEnabled Specify either true or
false to indicate
whether you want
xDA to enable
clustering for this
endpoint.
WildFlyServerGroup Specify the server
group to which the
application is to be
deployed.
If Cluster Enabled is
set as true, you
must configure the
property.
AppHost Load loadBalancerEndpoin port Type the http port or
Balancer t https port.
protocol Type the http or http
protocol.
url Type the URL to
access the
administrative
console of the
AppHost application
server load balancer.
host, and port as
follows:
http://
<host>:<port>
Audio Video avtsEndpoint port Type the http port of
Transformation the CTS Audio Video
Services component.


Business Activity bamEndpoint port Type the http port of
Monitor the BAM component.
If you deploy the
BAM server in a
clustered
environment, specify
port details of the
load balancer for
BAM.
protocol.
url Type the URL to
access the BAM
component. Include
the protocol, host,
port, and default
URL prefix as
follows:
<protocol>://
<host>:<port>/
bam-server
Business Activity loadBalancerEndpoin port Type the http port of
Monitor Load t the Business Activity
Balancer Monitor load
balancer.
url Type the URL to
access the Business
Activity Monitor load
balancer. Include the
protocol, host, and
port as follows:
http://
<host>:<port>
Content Intelligence cisEndpoint port Type the http port of
Service the CIS component.
Documentum daEndpoint port Type the http port of
Administrator the Documentum
Administrator.
protocol.


url Type the URL to
access the
Documentum
Administrator.
host, port, and
default URL prefix as
follows:
<protocol>://
<host>:<port>/da
File Server dataAccess uncPath Type the shared UNC
path.
Media mtsEndpoint port Type the http port of
Transformation the CTS Media
Services component.
Process Integrator bpsEndpoint port Type the http port of
(BPS) the Process Integrator
component.
url Type the URL to
access the Process
Integrator
component. Include
the protocol, host,
port, and default
URL prefix as
follows:
<protocol>://
<host>:<port>/
bps
Repository repositoryEndpoint repositoryName Type a unique user-
defined value to
identify the
repository.
docBrokerPort Type the http port of
the machine where
connection broker is
installed.
xPlore (Search) xploreEndpoint eSSPort Type the port
number on which the
xPlore primary
instance is listening.


eSSUrl Type the URL to test
if the xPlore primary
instance is running.
primary host, port,
and default URL
prefix as follows:
<protocol>://
<xPlore Server
primary
host>:<port>/
dsearch
indexAgentPort Type the port
number at which the
xPlore Index Agent
listens for HTTP
requests.
indexAgentURLPrefi Type the URL to start
x the xPlore Index
Agent servlet.
primary host, port,
and default URL
prefix as follows:
<protocol>://
<xPlore Index
Agent primary
host>:<port>/
IndexAgent
2.19.8 Deleting an environment

Use the command to delete an environment if it is not currently in use.
2. At the xda> prompt, type:

delete-environment --environment-name <Environment Name>
Specify an existing environment name for deletion.

2.20. Managing xDA users
2.20 Managing xDA users

You can use the xDA Management Center or a set of commands to manage xDA
users.
The following points apply to user • The same guidelines for username and
management: password apply to all xDA users,
including the default admin user.
“Guidelines for username and password
creation” on page 109 provides details.
• You cannot delete the default admin
user.
• Only the admin user can create user,
change user password, and delete user.
• Users cannot delete themselves.
• There is no password retrieval in xDA.
• Usernames are case sensitive.
• You cannot change the username after
you finish creating an account.
The following additional points apply when • All users can access My Profile, where
you are using the xDA Management Center they can update only their own user
to manage users: account.
• Only the default admin user can access
the Users tab, to add, update, or delete
user accounts.
• Each user account requires a username,
password, first name, and last name. You
can also specify an email address.
2.20.1 Guidelines for username and password creation

The following table provides guidelines for username and password creation:
Guideline Username Password

Minimum length 4 characters 8 characters
Maximum length 12 characters (No maximum)
Character usage You can use alphanumeric Use at least 1 non-alphabetic
characters, underscore (_), character.
and 1 period (.). Do not use
spaces or any other special
characters.

2.20.2 Using the xDA management center
The xDA Management Center lets admin user to add, update and delete users. All
users can access My Profile, where you can update only your own user account.
Creating a user
1. Start xDA and log in to xDA Management Center with admin user. “Logging In
to the xDA management center” on page 83 provides instructions.
2. Click Users.
3. Click Add User.
Note: You cannot change the user name after you finish creating an
account.
4. In the Add User screen, type the following details:
• Username
• Password
• Confirm password
• First name
• Last name
• (Optional) Email Id
5. Click Finish. The system saves the new user information in the database.
Updating a User
The admin user can update these items— first name, last name, email ID and change
the password.
2. Click Users.
3. Click Update User.
4. In the Update User screen, type the following details:
• First name
• Last name
• (Optional) Email Id
5. If you intend to change the password, click the Change Password checkbox,
type the new password to change the password.

2.20. Managing xDA users
6. Click Finish. The system saves the updated user information in the database.
Deleting a user
2. Click Users.
3. Click Delete User. You cannot delete the default admin user.
4. Click Yes to confirm the deletion of the user. The system deletes the user
information from the database.
2.20.3 Using commands

The following table lists the commands to manage xDA users:
Command Description
change-password Changes xDA user password.
create-user Creates a new xDA user.
delete-user Deletes an existing xDA user.
show-users Shows xDA users list.
2.20.4 Creating a user


create-user ––username <username> [––password <password>]
Notes
• Only the admin user can create other users using this command.
• If the user provides only username, the system prompts you to enter the
password in a masked (*) format.
3. If the new user needs access to xDA from a different machine, give the new user
a copy of the xda-tools.zip file and the xda.properties file.

2.20.5 Viewing a list of users


show-users
The information for each user includes:
• Username
• The user creation date
• Name of the user who created this user
• Last modification date for the user
• Name of the user who last modified this user
2.20.6 Changing a user password

The following principles apply for changing the user password:
• Only the admin user can change the password of other users.
• You can change your own password.
• There is no password retrieval in xDA.

show-users

change-password ––username <name> [--new-password <password>]
where <password> is the new password for the named user.
Note: If the user provides only username, the system prompts you to enter
the password in a masked (*) format.

2.21. Viewing environments
2.20.7 Deleting a user


show-users

delete-user ––username <name>
where <name> is the name of the user that you want to delete.
Note: Only the admin user can delete any user.
4. When the system prompts you to confirm, type

y
2.21 Viewing environments

After you have created an environment, you might need to view a list of
environments or view the properties of the environment, as described in the
following sections.
2.21.1 Viewing a list of environments

You can use the xDA Management Center or a command to view a list of
environments.

show-environments [--report <reportname>]
If you do not specify parameters, the system shows a list of all environments in
the system. The information for each environment includes:
• Environment name
• Environment template used to register the environment
• Environment label (description)
• Provisioning date of the environment
• Status of the environment
• Name of the user who created the environment
If you specify a parameter, the system shows information or creates a report as


--report The system creates a report containing the
information shown with the show-
environments command. The default
location is ${xda-tools-home}\reports. You
cannot save reports outside the reports
folder. The report name depends on the
following:
• If you do not specify a name, the
system creates a report with the name
<yyyy-mm-dd>-show-environments.txt
and puts it in the default location.
• If you specify a name, the system
creates a report with that name and .txt
extension, and puts it in the default
location. The system converts any
spaces in the name to an underscore
(_). The system appends a .txt
extension to the name even if you
specify a different extension, for
example, report.doc becomes
report.doc.txt. The system converts
a .TXT extension to a .txt extension.
2.21.2 Viewing properties of a specific environment

You can use the xDA Management Center or a command to view the properties of a
specific environment.

show-environment-details --name <name> [--report <reportname>] [--
services][--applications] [--endpoints]
where the only required parameter is --name <name>.
The system shows information or creates a report as described in the following
table:
--name The environment name. The system shows
basic information, including the
environment name, the environment
description, the template name, the
provisioning date of the environment, and
the mode of the environment.
Additionally, it shows a list of services,
endpoints, and xCP applications deployed
on that environment.

2.21. Viewing environments
--report The system creates a report containing the
information shown with the show-
environment-details command. The
default location is ${xda-tools-home}
\reports. You cannot save reports outside
the reports folder. The report name
depends on the following:
• If you do not specify a name, the
system creates a report with the name
<yyyy-mm-dd>-show-environment-
details.txt and puts it in the default
location.
• If you specify a name, the system
creates a report with that name and .txt
extension, and puts it in the default
location. The system converts any
spaces in the name to an underscore
(_). The system appends a .txt
extension to the name even if you
specify a different extension, for
example, report.doc becomes
report.doc.txt. The system converts
a .TXT extension to a .txt extension.
--services The system shows basic environment and
services information. Services include, for
example, VM information and IP
addresses.
--applications The system shows basic environment and
application information. Application
information includes a list of all the xCP
applications deployed on the specified
environment. For each application in the
list, the system shows the application
name, the application version, and the
deployment date of the application.
--endpoints The system shows basic environment and
endpoint information. Endpoint
information includes endpoint name,
service name and application endpoint
details, for example, host, port, protocol
and URL.

2.22 Deploying xCP Designer

If you want to use multiple instances of xCP Designer on your computer, use the
same version of xCP Designer for each instance. The first instance of xCP Designer
has an internal application server that subsequent instances use. The first instance
needs to stay open to use the other instances.
1. Obtain the xCP Designer ZIP file.

2. Extract the contents of the file to your computer.
The file contents are stored in an xCPDesigner folder.
3. Double-click xcpdesigner.exe to open xCP Designer.
2.23 Content Intelligence Services sizing for better

performance
Depending on your needs in content analytics, Content Intelligence Services (CIS)
can be scaled to increase the performance of processing content objects. CIS
processing occurs when an application developer adds Discovered Metadata to
content models.
The processing is asynchronous and scheduled to run every 15 minutes. As a

consequence, there is a short latency between the content update and the availability
of updated discovered metadata values. The latency also applies on business events
set on discovered metadata update.
The throughput is different based on the type of processing. The xCP Designer Help
describes the processing types.
The following table indicates the throughput by type of processing:
Type of processing Throughput Example with Examples of

documents of 4KB Discovered
metadata
Entity detection 10 MB/hour 2500 documents/hour Fax number,
organization, people,
phone number, place,
postal address.
Categorization 1 GB/hour 250000 documents/ Business terms
hour (USA), Science and
Engineering
Pattern detection 1 GB/hour 250000 documents/ Email address, SSN
hour (USA), URL
These measurements are for your information and not guaranteed. They reflect the
results of a test in specific conditions: processings were measured separately, with 1
CPU for each processing, and the number of threads was adjusted for each
processing.

2.24. Documentum login ticket-based authentication support
The following factors can impact the performance:
• Hardware requirements: number of CPUs, network configuration, network

speed, Random-access memory (RAM).
• Server configuration: number of parallel threads, size limits.
• Data: size and number of content objects, file format.
To increase the performance of entity detection, install additional entity detection

server and adjust the number of threads. If no discovered metadata based on entity
detection are defined in the application, increase the number of threads.
The OpenText Documentum Content Intelligence Services Administration Guide contains

the detailed procedures and hardware and server settings.
In a multiple docbase environment, by default, CIS points to only one docbase at a

time.
2.24 Documentum login ticket-based authentication

support
A Documentum ticket represents a URL link that an application can use instead of a
user password when connecting to a repository. You can use login tickets to
establish a connection with a repository.
Each login ticket has a scope that defines who can use the ticket and how many
times the ticket can be used. By default, login tickets may be used multiple times.
However, you can create a ticket configured for only one use. If a ticket is configured
for just one use, the ticket must be used by the issuing server or another designated
server.
The ticket logs the user in without a login screen and the user logs directly to the
home page or requested page of the application.
URL format
The URL link containing a ticketed login has the following format. Spaces must be
escaped (replaced with %20).
http://<server_name>:<port_number>/<application_name>/
?ticket=<ticket>&user=<user>
server_name Specifies the host specific alias to access the
server.
application_name Specifies the Virtual name for your
application. This is used to access the
application.

ticket Specifies a ticket that has been generated
within the required time frame (default 5
minutes) generated by the DFC call
getLoginTicket() or getLoginTicketEx().
user Identifies the user name to access the xCP
application.
For example, the following URL contains a login ticket (line break inserted for
display purposes only):
http://10.31.83.101:8000/xcp_229/?ticket=DM_TICKET=T0JKIE5VTEwgMAox
Mwp2ZXJzaW9uIElOVCBTIDAKMwpmbGFncyBJTlQgUyAwCjEKc2VxdW
VuY2VfbnVtIElOVCBTIDAKMTgKY3JlYXRlX3RpbWUgSU5UIFMgMAoxNDQyNTYwODg4
CmV4cGlyZV90aW1lIElOVCBTIDAKMTQ0MjU2MTE4OApkb21haW4gU1RSSU5HIFMgMAp
BIDYgY3N2bTAxCnVzZXJfbmFtZSBTVFJJTkcgUyAwCkEgNyBkbWFkbWluCnBhc3N3b3
JkIFNUUklORyBTIDAKQSAxMDggRE1fRU5DUl9URVhUX1YyPUFBQUFFSkNKSUgySXI4
QjgzRFlSaU1Tb3hjT2lSRXgyajlpYmpYS0U4cHNNbTl0aUZseUhmK294NXY3Y3JjNFV
tdlhUSys3dUNhYmhaRFVoOGZYM2gvaytTbUE9CmRvY2Jhc2VfbmFtZSBTVFJJTkcgUy
AwCkEgNyBGUElSZXBvCmhvc3RfbmFtZSBTVFJJTkcgUyAwCkEgNiBDU1ZNMDEKc2
VydmVyX25hbWUgU1RSSU5HIFMgMApBIDcgRlBJUmVwbwpzaWduYXR1cmVfbGVuIEl
OVCBTIDAKMTEyCnNpZ25hdHVyZSBTVFJJTkcgUyAwCkEgMTEyIEFBQUFFTlFPMzRzU2
JyWXhRRUpWbHZZWUxpUGhaZlp2WlRBNTBnTWttQk9EWThlSXg1YkVoTERrQUZTR1U0dl
VLZENZcUhVSWJoUmgrOWFHQmdWb1RJcXlsaGJNL0RLbkFLSlJlMEViU2
VweFN3YUEK&user=dmadmin
You can extract the command using the IAPI command:

getlogin,c,[user_name][,scope][,timeout_period]
For example, getlogin, c, admin
Note: With ticketed login, both its creation time and expiration time are
recorded as UTC time. This ensures that problems do not arise from tickets
used across time zones. When a ticket is sent to a server other than the server
that generated the ticket, the receiving server tolerates up to a three minute
difference in time to allow for minor differences in machine clock time across
host machines. System administrators must ensure that the machine clocks on
host machines on which applications and repositories reside are set as closely
as possible to the correct time.
For more information about login tickets, see OpenText Documentum DFC
Development guide and OpenText Documentum Server Fundamentals Guide.
Configure rest-api-runtime.properties
1. Download the ApphostCustomconf.zip file from the Download Center and
extract the rest-api-runtime.properties file.
2. Locate the rest-api-runtime.properties file in the application server home
directory.
3. Configure the following properties in the rest-api-runtime.properties file:
rest.security.auth.mode=ticket
rest.security.auth.mode=ticket-basic

2.25. Single-Sign on
where:
• ticket is the authentication scheme that supports Ticket based authentication.

• For the fallback authentication to work, specify the authentication scheme as
ticket-basic.
The OpenText Documentum Platform REST Services Development Guide provides

more information about REST API properties file.
4. To secure application against clickjacking, configure the following properties in
the rest-api-runtime.properties file:
rest.security.xframeoption.value=DENY
rest.security.contentsecuritypolicy.value=frame-options 'deny'
5. To prevent an application from sending debug information to the user agent,

ensure that the <rest.security.verbose.error> property in the rest-api-runtime.
properties file is set to false:
rest.security.verbose.error = false
6. To enable logging into xCP application, set the <rest.security.logon.secured>

property to false:
Note: Opentext recommends you to use CSP compliant user agent and
configure the required CSP settings using the
xcp.security.contentsecuritypolicy.value attribute in the rest-api-
runtime.properties file.
Non CSP compliant user agents do not support this configuration. To support
non CSP compliant user agents, set the x_cp.security.xframeoption.value
attribute to DENY to prevent unauthorized frame hosting.
For a CSP compliant user agent, CSP takes precedence over x-frame-options.
2.25 Single-Sign on
Authentication can be implemented using the following Single-Sign On (SSO)
methodologies:
• Kerberos
• Central Authentication Service (CAS)
• CA SiteMinder
• SAML

2.25.1 Configuring Kerberos Authentication

Kerberos Single Sign-On (SSO) authentication scheme is used to authenticate the
user who wants to log in to the xCP application from a computer that is in the
Kerberos domain.
Prerequisites
Set up the domain controller and create multiple computers and users in the
corresponding active directory. If you need to run multi-domain Kerberos
authentication, set multi domains as 2-Way trusts in one forest and they must be
reachable to each other.
Ensure that the system time is in sync across all computers.
2.25.1.1 Configure Kerberos Authentication on Documentum Server

The OpenText Documentum Server Administration and Configuration Guide provides
information on configuring Kerberos authentication on Documentum Server.
2.25.1.2 Configure Kerberos Authentication for xCP Application
Determine Service Principal Name (SPN) for xCP

The service principal name for the application server, where xCP application is
deployed, can be in the <service class>/<host>:<port>/<service name> format.
However, to make the SPN compatible with all the Web clients, set SPN in the http/
<fully-qualified-domain-name> format. For example, http/xcpserver.acme.
com.
Register SPN and Map User

1. Log in to Kerberos Key Distribution Center (KDC).
2. In domain computers and users management, create a service account for the
application server, where xCP application is deployed. For example, webadmin.
3. To create SPN in the Windows server machine, run the command in the
format:setspn -a <xCP-SPN> <xCP-service-account>
Example:setspn -a http/xcpserver.acme.com webadmin
4. To create a keytab file for SPN and map to the service account, run the command
in the format:
ktpass /pass <PASSWORD>
-out <output-keytab-file-location>
-princ <xCP-SPN>@<REALM-NAME>
crypto <encrypt-type> +DumpSalt
-ptype KRB5_NT_PRINCIPAL /mapOp set /mapUser <xCP-service-account>
Example:
ktpass /pass Password123
-out c:\shared\acme01.acme.keytab

-princ http/xCPserver.acme.com@ACME.COM
-crypto RC4-HMAC-NT +DumpSalt
-ptype KRB5_NT_PRINCIPAL /mapOp set /mapUser webadmin
5. Once you have generated a keytab file, perform the following steps:
a. Log in to the Windows active directory domain.
b. Click Users and select the created service account, for example, webadmin.
c. Right-click and select <service account> Properties.
d. Click the Delegation tab.
e. Select the Trust this user for delegation to any service (Kerberos) only
option.
f. Save your changes.
6. Copy the keytab file to the machine where application is to be deployed.
To enable Kerberos authentication in a clustered environment with a load balancer

configured, you must generate a keytab only for the load balancer and use the same
keytab in all AppHost nodes. You need not generate keytab for each AppHost node.
JAAS Configuration
The JAAS configuration is applicable to all supported application servers. However,
you need to make custom modification for WebLogic application servers.
The JAAS configuration file entry contains JAAS specific settings such as the
<LoginContext> name (which is also the name of the configuration entry), settings
for the Kerberos login module, the application server's SPN, and the location of the
*.keytab file.
The location and format of the JAAS configuration settings might be different for
each application server. The JAAS configuration file in most application servers is
named jaas.conf.
Copy the jaas.conf file to the machine where application is to be deployed.
Example of JAAS Configuration referring to QUEST Libraries, which support both

single domain and multi domain:
<LoginContext>
{
com.sun.security.kerberos.jaas.KerberosLoginModule required
debug=false
principal="<SPN@domain>"
refreshKrb5Config=true
noTGT=true
useKeyTab=true
storeKey=true
doNotPrompt=true
useTicketCache=false
isInitiator=false
keyTab="<xCP_user_keytab_path>";
};

Example:
http-xcpserver-acme-com
{
com.sun.security.auth.module.Krb5LoginModule required
debug=true
principal="HTTP/KERBCSXCPNEW.XCPNEWRC.LOCAL@XCPNEWRC.LOCAL"
refreshKrb5Config=true
useKeyTab=true
storeKey=true
doNotPrompt=true
useTicketCache=false
isInitiator=false
noTGT=true
keyTab="C:\shared\acme01.acme.keytab";
};
<loginContext> Corresponds to the SPN of Documentum

xCP application. You replace separator
characters with hyphen characters and omit
the @REALM segment in the SPN. For
example, the following LoginContext is
derived from the corresponding SPN:
• LoginContext:
http-myhost-mydomain-com
• SPN:
http/myhost.mydomain.com
<LoginModule> Specify the Kerberos login module to be used
to perform user authentication.
Referring to QUEST Libraries for both Single

Domain and Multi-Domain:
com.dstc.security.kerberos.jaas.KerberosLog
inModule
Enable ticket cache by setting

useTicketCache to true. Otherwise,
disable ticket cache by setting
useTicketCache to false.
<SPN> For QUEST login modules, the SPN does not
contain the @ character and the string after
that. For example:
http/myhost.mydomain.com
<REALM> For a single domain, specify the realm as

parent-domain.com.
For multi-domain, specify the realm as

parent-domain.child-domain.com.
<xCP_user_keytab_path> Specify the path to the user account *.keytab
file on the application server. For example:
c:\acme01.acme.keytab

JAAS Configuration in WebLogic Application Server
If Documentum xCP is deployed on WebLogic, Kerberos authentication requires the

following configurations:
• Set the location of the jaas.config and krb5.ini files using a JVM argument of the
setDomainEnv script:
set JAVA_OPTIONS=%JAVA_OPTIONS% -Djava.security.auth.login.config=jaas config file
path>
SET JAVA_OPTIONS=%JAVA_OPTIONS% -Djava.security.krb5.conf=C:\Windows\krb5.ini
-Djava.security.auth.login.config=C:\krb5Login.conf
-Djavax.security.auth.useSubjectCredsOnly=false
OpenText Documentum Server Administration and Configuration Guide provides

information about how to configure the krb5.ini file.
Configure rest-api-runtime.properties
1. Download the ApphostCustomconf.zip file and extract the rest-api-runtime.properties
file.
2. Locate the rest-api-runtime.properties file in the application server home directory.
rest.security.auth.mode=kerberos
rest.security.realm.name=<Realm or Domain name>
rest.security.kerberos.spn=<SPN>
rest.security.kerberos.jaas.conf=<JAAS-CONF-FILE-PATH>
rest.security.kerberos.nameservers=<COLON-SEPARATED-NAME-SERVERS>
rest.security.kerberos.maxpacksize=<MAX-PACK-SIZE>
where:
• basic-kerberos is the authentication scheme that supports both HTTP basic

and Kerberos schemes. For the fallback authentication to work, you can
specify the authentication scheme in the rest-api-runtime.properties file as:
set rest.security.auth.mode=basic-kerberos
• Instead of specifying the rest.security.kerberos.jaas.conf property,

you can specify it through JVM startup parameter:
-Djava.security.auth.login.config=<JAAS-CONF-FILE-PATH>
• <COLON-SEPARATED-NAME-SERVERS> is the name server corresponding to the

hostname or IP of DNS for a domain. If there are multi domain Kerberos
environments, specify multiple name servers, separated by the colon (“:”).
Alternatively, you can specify it through JVM startup parameter:
-Djcsi.kerberos.nameservers=<COLON-SEPARATED-NAME-SERVERS>
• <MAX-PACK-SIZE> specify the threshold (in bytes) at which we cut over from
UDP to TCP. This property can be left as empty where the actual threshold
resolves to the default value of 2000 bytes.
4. If Documentum xCP is deployed on the WebSphere Server and WebLogic
Server, Kerberos authentication requires the following configurations. Append

the realm name to the rest.security.kerberos.spn property and specify the

jsafejce.mode property in the rest-api-runtime.properties file:
For WebSphere Server:
rest.security.kerberos.spn=http/myhost.mydomain.com@mydomain.mycorp.com
rest.security.crypto.provider.jsafejce.mode=NON_FIPS140_MODE
For WebLogic Server:

rest.security.kerberos.spn=http/myhost.mydomain.com
The OpenText Documentum Platform REST Services Development Guide provides more
information about REST API properties file.
In the rest-api-runtime.properties file, there are options to set time out (Hard,
Tolerant, or Touched). xCP does not support setting time out values for Kerberos,
whereas xCP supports setting time out values for CAS.
For a clustered environment, repeat these procedures on each node.
Configure client browser to use the SPNEGO protocol

You can configure your browser to use the SPNEGO protocol.
To configure Internet Explorer:
1. Log in to the Windows active directory domain.

2. Open the Internet Explorer browser.
3. Select Tools > Internet Options.The Internet Options dialog box appears.
4. Click the Security tab.
5. Select the Local intranet icon, and click Sites. The Local intranet dialog box
appears.
6. Ensure that all settings are selected and click Advanced. The Local intranet
dialog box appears.
7. In the Add this Web site to the zone field, specify the web address of the host
name to enable single sign-on (SSO) and add it to the Web sites list.
8. Click OK.
9. Click OK.
10. Click the Advanced tab and scroll to Security settings.
11. Ensure that the Enable Integrated Windows Authentication (requires restart)
option is selected.
12. Click OK.
13. Restart your Microsoft Internet Explorer to activate this configuration.
To configure Firefox:

1. Log in to the Windows active directory domain.

2. Open the Firefox browser.
3. In the Address field, type about:config and press Enter.
4. In the Filter field, type network.n. All preferences are listed.
5. Double-click the network.negotiate-auth.trusted-uris and network.negotiate-
auth.delegation-uris preferences.
These preferences list the sites that are permitted to engage in SPNEGO
Authentication with the browser.
6. Enter a comma-delimited list of trusted domains or URLs.For example, type
http://wdkapp.dctmlabs.com.
7. Click OK.
8. Restart the Firefox browser to activate the configuration.
To configure Chrome:
1. Start the Windows Command Prompt.

2. Change directory to the location where Chrome is installed. Typically, Chrome is
installed under C:\Program Files\Google\Chrome\Application.
3. Run the following command to start Chrome:chrome.exe --args --auth-
server-whitelist=".DOMAIN.com" --auth-negotiate-delegate-
whitelist=".DOMAIN.com"
where, DOMAIN is your domain name.
2.25.1.3 Configure at client end to display BAM reports

Windows registry settings
1. In the Windows Start menu, click Start > Run.

2. Type regedit.msc. The Registry Editor is displayed.
3. In the navigation pane, go to HKEY_LOCAL_MACHINE > SYSTEM >
CurrentControlSet > Control > Lsa > Kerberos > Parameters.
4. Right-click and select New > DWORD (32–bit) Value.
5. Specify Allowtgtsessionkey as a value name and 1 (one) as a Value data.
6. Click OK.
7. Click File > Exit.
Local security policy settings
1. In the Windows Start menu, click Start > Run.

2. Type gpedit.msc. The Group Policy Management Console (GPMC) is
displayed.

3. In the navigation pane, go to Local Computer Policy > Computer Configuration

> Windows Settings > Security Settings > Local Policies > Security Options.
4. Double-click the Network security: LAN Manager authentication level.
5. Select Send LM & NTLM responses and click OK.
6. Click File > Exit.
Internet Explorer settings
1. Open the Internet Explorer browser.

2. Select Tools > Internet Options.The Internet Options dialog box appears.
3. Click the Security tab.
4. Select the Local intranet icon, and click Custom level.
5. Under User Authentication > Logon, select Automatic logon using current user
name and password.
6. Click OK.
7. Restart your Microsoft Internet Explorer to activate this configuration.
2.25.2 Configuring CAS Authentication

Central Authentication Service (CAS) is a HTTP based protocol that requires each of
its components to be accessed through specific URIs. Documentum Server provides
support for CAS SSO through an authentication plug-in for CAS. The plug-in
supports CAS server connection over HTTP and HTTPS protocols. Documentum
Server authentication supports CAS protocol 2.0.
Prerequisites
• JDK version 6.0 or later
• Enable LDAP module
• Enable SSL in CAS
• Enable SSL in the Application Server
• For clustered environment, enable SSL on the load balancer that communicates
with CAS

2.25.2.1 Configure CAS Authentication on CAS Server

CAS plug-in supports authentication for LDAP users and requires customization in
the /WEB-INF/deployerConfigContext.xml. After you have installed the CAS plug-
in, perform the following steps:
1. Add an entry to the contextSource bean property in the

deployerConfigContext.xml file. This property lets you connect to LDAP to
perform authentication operations.
<bean id="contextSource"
class="org.springframework.ldap.core.support.LdapContextSource">
<property name="pooled" value="false"/>
<property name="url" value="ldap://domainctlr.iigplat.com:389" />
<property name="userDn"
value="CN=Administrator,CN=Users,DC=iigplat,DC=com"/>
<property name="password" value="password"/>
<property name="baseEnvironmentProperties">
<map>
<entry key="com.sun.jndi.ldap.connect.timeout" value="3000" />
<entry key="com.sun.jndi.ldap.read.timeout" value="3000" />
<entry key="java.naming.security.authentication"
value="simple" />
</map>
</property>
</bean>
2. Define an authentication handler for every Identity Provider. The

authentication handler for LDAP (Microsoft Active Directory) is defined as
follows:
<bean class="org.jasig.cas.adaptors.ldap.BindLdapAuthenticationHandler"
p:filter="sAMAccountName=%u"
p:searchBase="OU=testou,DC=iigplat,DC=com"
p:contextSource-ref="contextSource"
p:ignorePartialResultException="true" />
3. Add the CredentialsToPrincipalResolver bean property in the

deployerConfigContext.xml file. This property maps user credential attributes
with a principal property. The principal property defines an authenticated user
with its attributes.
<bean class="org.jasig.cas.authentication.principal.
CredentialsToLDAPAttributePrincipalResolver">
<property name="credentialsToPrincipalResolver">
<bean class="org.jasig.cas.authentication.principal.
UsernamePasswordCredentialsToPrincipalResolver"/>
</property>
<property name="filter" value="(sAMAccountName=%u)"/>
<property name="principalAttributeName" value="sAMAccountName"/>
<property name="searchBase" value="OU=testou,DC=iigplat,DC=com"/>
<property name="contextSource" ref="contextSource"/>
<property name="attributeRepository" ref="attributeRepository"/>
</bean>
4. Add the attributeRepository bean property in the deployerConfigContext.xml

file. The attributeRepository property defines the attributes that CAS returns to
the Documentum Server. The dmCSLdapUserDN attribute is used for
authentication response that exposes the user LDAP distinguished name (DN).
<bean id="attributeRepository"
class="org.jasig.services.persondir.support.ldap.LdapPersonAttributeDao">

<property name="contextSource" ref="contextSource" />

<property name="baseDN"
value="OU=testou,DC=iigplat,DC=com" />
<property name="requireAllQueryAttributes" value="true" />
<property name="queryAttributeMapping">
<map>
<entry key="username" value="sAMAccountName" />
</map>
</property>
<property name="resultAttributeMapping">
<map>
<entry value="dmCSLdapUserDN" key="distinguishedName"/>
</map>
</property>
</bean>
where distinguishedName is the attribute of Active Directory. Use this attribute

depending on your LDAP server.
The OpenText Documentum Server Administration and Configuration Guide
provides information on configuring CAS on Documentum Server.
5. Customize the casServiceValidationSuccess.jsp file located at WEB-INF/
view/jsp/ protocol/2.0 for CAS so that it includes user distinguished name in the
response sent to Documentum Server for proxy ticket validation request. Add
the following after the <cas:user> element:
<c:forEach var="auth" items="${assertion.chainedAuthentications}">
<c:forEach var="attr" items="${auth.principal.attributes}" >
<cas:attribute name="${fn:escapeXml(attr.key)}"
value="${fn:escapeXml(attr.value)}"/>
</c:forEach>
</c:forEach>
6. Once the Documentum Server is registered in CAS for proxy, set the
customized attribute dmCSLdapUserDN in the list of allowedAttributes. Here
is a sample of in-memory service registry setting:
<bean id="serviceRegistryDao" class="org.jasig.cas.services.
InMemoryServiceRegistryDaoImpl">
<property name="registeredServices">
<list>
<! --the following registered service is for Documentum Server, as an example -->
<property name="id" value="1" />
<property name="name" value="Content Server proxy service" />
<property name="description" value="Allows CAS Proxy for Content Server
repositories" />
<property name="serviceId" value="ContentServer" />
<property name="evaluationOrder" value="0" />
<property name="allowedAttributes">
<list><value>dmCSLdapUserDN</value><list>
</property>
</bean>

<bean ..../>
</list>
</property>
</bean>
7. Service Management: This section shows how to log in to the service

management application and register service for Documentum Server with CAS
server.
Log in to service management application of CAS as an administrator user:

a. Edit the userDetailsService bean in WEB-INF/deployerConfigContext.xml

and modify the user name. This user must be a valid user and CAS must
authenticate this user.
b. Start the CAS Server and access https://<cas_server_url>/services.
c. Log in to the system using administrator user created.
Register service for Documentum Server:
a. Click on Add New Service or access https://<cas_server_url>/services/

add.html and add details for these fields—Name, Service URL, description,
Attributes, status, and order.
b. Fill the form to create a new service and save it. Make sure that the name
used in Service URL is same as that configured in CAS plug-in
configuration file.
c. Verify that the service is created.
d. Once the Documentum Server is registered in CAS for proxy, set the
customized attribute dmCSLdapUserDN in the list of allowedAttributes.
Here is a sample of in-memory service registry setting:
<bean id="serviceRegistryDao" class="org.jasig.cas.services.
InMemoryServiceRegistryDaoImpl">
<property name="registeredServices">
<list>
<! --the following registered service is for Documentum Server,
as an example -->
<property name="id" value="1" />
<property name="name" value="Content Server proxy service" />
<property name="description" value="Allows CAS Proxy for
Documentum Server repositories" />
<property name="serviceId" value="ContentServer" />
<property name="evaluationOrder" value="0" />
<property name="allowedAttributes">
<list><value>dmCSLdapUserDN</value><list>
</property>
</bean>

<bean ..../>
</list>
</property>
</bean>
For more information about CAS RESTful API, refer to the CAS website.

2.25.2.2 Configure CAS Authentication on Documentum Server

1. Stop all Repository Services.
2. Copy CAS plug-in binary, dm_cas_auth.dll, from %DM_HOME%\install

\external_apps\authplugins\ CentralAuthenticationService to
%DOCUMENTUM%\dba\auth directory.
On server startup, the plug-in that resides in %DOCUMENTUM%\dba\auth
directory is automatically loaded.
3. Create a CAS plug-in configuration file, dm_cas_auth.ini, in the

%DOCUMENTUM%\dba\auth directory and add these properties:
[DM_CAS_AUTH_CONF]
server_host=cas
server_port=8443
url_path=/cas/proxyValidate
service_param=ContentServer
is_https=T
Name Description
server_host Host name that resolves to the CAS.
server_port HTTPS port number for connection with
CAS server.
url_path URL path used to send HTTP request sent
to CAS server to validate proxy ticket.
service_param Service name for which the proxy ticket is
generated.
Note: The service name must be a

registered service in CAS.
is_https Specify if HTTP connection must be done
over HTTPS.
4. To verify CAS plug-in load successfully, start the docbase, and look at the
docbase log for an entry starting with
[DM_SESSION_I_AUTH_PLUGIN_LOADED]info:
[DM_SESSION_I_AUTH_PLUGIN_LOADED]info: "Loaded Authentication Plugin with code
'dm_cas' (C:\Documentum\dba\auth\dm_cas_auth.dll)."
Documentum Authentication Plugin Trace File

(c) Copyright EMC Corp., 2012
All rights reserved.
05/15/13 23:27:03 Initializing dm_cas plugin
05/15/13 23:27:03 Following are the auth init params
is_https = True
05/15/13 23:27:03 server_host = cas
05/15/13 23:27:03 server_port = 8443
05/15/13 23:27:03 url_path = /cas/proxyValidate
05/15/13 23:27:03 service_param = ContentServer

2.25.2.3 Configure CAS Authentication for xCP Application

1. Locate rest-api-runtime.properties file in the application server home directory
and append these properties:
rest.security.auth.mode=ct-cas
rest.security.cas.server.url= https://cas:8443/cas
rest.security.cas.server.login.url= https://cas:8443/cas/login
rest.security.cas.server.logout.url= https://cas:8443/cas/logout
rest.security.cas.server.tickets.url= https://cas:8443/cas/v1/tickets
rest.security.cas.proxy.service=<service name>
rest.security.server.url=<applicationserver:port>
rest.security.cas.callback.service.url=<applicationserver:port/xCPapp>
rest.security.auth.cas.client.pgt.storage=inmemory
rest.security.client.token.expiration.policy=com.emc.documentum.rest.
security.ticket.impl.TolerantTimeoutExpirationPolicy
The same value of rest.security.cas.proxy.service property must be registered

for CAS server and dm_cas.ini of Documentum Server.
Note: When there are multiple applications deployed on the application

server, it is mandatory to update therest.security.cas.callback.service.url
property in the rest-api-runtime.properties file for each application. Then,
you must place the rest-api-runtime.properties file to /WEB-INF/classes
folder location for each application.
For more information about these properties, see the instructions in the rest-
api-runtime.properties file.
2. For a manually-provisioned environment, you need to manually add the

rest.security.crypto.provider.jsafejce.mode property in the rest-api-
3. In the rest-api-runtime.properties file, there are options to set time out values
for expiration policies in CAS:
• com.emc.documentum.rest.security.ticket.impl.HardTimeoutExpirationPolic
y
• (default)
com.emc.documentum.rest.security.ticket.impl.TolerantTimeoutExpirationP
olicy
• com.emc.documentum.rest.security.ticket.impl.TouchedTimeoutExpirationP
olicy
The Documentum Platform REST Services Development Guide provides more

information about REST API properties file.
For more information about CAS RESTful API, refer to the CAS website.
4. Modify cas.properties available in the WEB-INF/cas.properties folder:

Name Description
server.name Enter the CAS URL providing the
complete host name. It is recommended to
use https in deployment environments.
For example, https://cas:8443
host.name Enter the host name, for example, cas.
server.prefix Enter the CAS application name, for
example, ${server.name}/cas.
For a clustered environment, repeat this procedure on each node.
2.25.3 Configuring SiteMinder Authentication

SiteMinder provides you an enterprise-class secure SSO and flexible identity access
management so that you can authenticate users and control access to Web
applications and portals.
Prerequisites
Set up the SiteMinder environment and configure it.
2.25.3.1 Configure SiteMinder Authentication on Documentum Server

1. Stop all Repository Services.
2. Copy the dm_netegrity_auth.dll file from %DM_HOME%\install

\external_apps\authplugins\netegrity to %DOCUMENTUM%\dba\auth
directory.
3. Copy the dm_netegrity_auth.ini file from %DM_HOME%\install

\external_apps\authplugins\netegrity to %DOCUMENTUM%\dba\auth
directory.
On server startup, the plug-in that resides in %DOCUMENTUM%\dba\auth
directory is automatically loaded.
4. Edit the dm_netegrity_auth.ini file and set these mandatory parameters:
• agent_name = <Agent name created in Policy Server>

• shared_secret = <Shared secret password>
• policy_server_ip = <IP address of Policy Server>
• resource =</xCP application>
5. Copy the supporting shared libraries:

For Windows: Copy smagentapi.dll, smerrlog.dll, ipthread.dll,
libetpki_openssl_crypto.dll, libetpki_openssl_ssl.dll, libetpki2.dll,
libetpki2_thread.dll and smcommonutil.dll from %DM_HOME% /install/
external_apps/authplugins/netegrity to %DM_HOME%\bin directory.

6. To verify SiteMinder plug-in load successfully, start the docbase, and look at the
docbase log.
2.25.3.2 Configure SiteMinder Authentication for xCP Application

1. Install an application server and deploy an xCP application on any of the
supported WebLogic Application Servers.
2. Locate the rest-api-runtime.properties file under the application server home

directory and specify the following properties:rest.security.auth.mode=
siteminderrest.security.siteminder.cookie.name= SMSESSIONrest.
security.siteminder.user.header= SM_USER//By default, the
application takes end user to the xCP signon pagerest.signon.logout.
url= <SiteMinder session logout URL> or <Logout success URL>
The OpenText Documentum Platform REST Services Development Guide provides
more information about REST API properties file.
For a clustered environment, repeat this procedure on each node.
2.25.3.3 Install and configure LDAP Data Adapter

The LDAP Data Adapter allows SiteMinder Policy Server to use your LDAP
Directory as a Data Store. Create a directory server instance on the LDAP, for
example Sun Directory Service Control Center.
For more information about installing and configuring the data adapter, refer to the
SiteMinder website.
2.25.3.4 Install and configure SiteMinder Policy Server

xCP applications support SSO using SiteMinder Policy Server. The SiteMinder
Policy Server lets you enforce access control policies, which it communicates to a
SiteMinder Agent.
For more information about installing and configuring SiteMinder Policy Server,
refer to the SiteMinder website.
2.25.3.5 Install and configure SiteMinder Web Agent

The SiteMinder Web Agent allows you to communicate with the Policy Server to
authenticate and authorize users.
For more information about installing and configuring SiteMinder Web agent, refer
to the SiteMinder website.

2.25.4 Configuring SAML authentication

Security Assertion Markup Language 2.0 (SAML 2.0) is an XML-based protocol used
for exchanging authentication and authorization data between an identity provider
and a service provider. xCP Application supports SAML 2.0 based SSO
authentication.
The SAML authentication consists of these entities:
• Principal - A principal is an entity that acts on behalf of a user.

• Service Provider - A service provider is an entity that provides a web-based
service, application, or resource.
• Identity Provider - An identity provider is an entity that authenticates principals
and produces assertions of authentication and attribute information in
accordance with SAML Assertions and Protocols specifications.
xCP supports SAML based SSO. Configure these components:
• xCP Application– Refer the Enabling HTTPS for Application Server section to
know about how to enable SAML on xCP components.
• Identity Provider Server— Microsoft Active Directory Federation Services (AD
FS) 2.0 is used as the Identity Provider Server. For more information about ADFS
2.0, refer the documentation provided by Microsoft.
• Documentum Server— For more information about enabling SAML on
Documentum Server, refer OpenText Documentum Server Administration and
Configuration Guide.
2.25.4.1 SAML based SSO Authentication Workflow

The following illustration describes the steps for SAML SSO in a xCP scenario with
an Identity Provider configured.

1. Request xCP Application resource: Usually, the repository is the first resource that
requires authentication. Since only an Identity Provider metadata file is
configured in the REST Server, this Identity Provider acts as the default
provider.
2. Initialize SAML request: The xCP Application initializes a SAML

<AuthnRequest> and redirects the User Agent to the Identity Provider.
3. Authenticate the Principal: The Identity Provider communicates with the User
Agent for the credentials. The process is different for various kinds of Identity
Providers.
4. Issue SAML Response: When the input credential of the Principal is verified by
the Identity Prover, a SAML < Response> that is sent by the Identity Provider is
redirected to the xCP Application by the User Agent.
5. Validate SAML Response: xCP Application validates the assertion. Once the
validation is done, the principal name is extracted as per the the attribute name
specified in the rest-api-runtime.properties file.
6. SAML Login to Documentum Server: xCP Application sends the principal name
along with the SAML < Response> to the Documentum Server for SAML user
login.
7. Return SAML Login Session: When the principal name and the SAML <
Response> are verified, Documentum Server returns a session for the Principal.
At this point, the SAML authentication has been successfully completed.

8. Get User Login Ticket: The Documentum Ticket is used after the SAML
authentication succeeds. At this point, the xCP application requests a login
ticket for the authenticated user by using the SAML login session. The timeout
for the Documentum Ticket is as per the value provided in the rest-api-
9. Return User Login Ticket: The Documentum Server returns a user login ticket to
the xCP Application.
10. Redirect to the Original REST Resource: Once the Documentum Ticket is available,
the xCP application redirects the user agent to the original xCP application
resource.
2.25.4.2 Enabling HTTPS for Application Server

1. Perform the following steps to enable HTTPS on the supported application
server:
a. Create a certificate keystore by executing the following command:

keytool -genkey -alias xcpapp -keyalg RSA -keystore xcpapp.keystore
b. Export the certificate by executing the following command:

-export -alias xcpapp -keystore xcpapp.keystore -file
xcpapp.cer -storepass <changeit>
c. Import the certificate to the Java trust store by executing the following
command:
-import -trustcacerts -alias xcpapp -keystore <java_truststore>
-file xcpapp.cer -storepass <changeit>
where:
• <java_truststore> is the path to the Java cacerts folder,
Example:%JAVA_HOME%\jre\lib\security\cacerts\
• <changeit> is the password that you specify for the keystore file
d. Navigate for the server.xml file at the following location and open the
server.xml file in a text editor.
<application_server_home>\conf
e. The following sample shows how to enable HTTPS on the Tomcat server.
Update server.xml of the application server where xCP application is
deployed.
<Connector port="8443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_S
HA,
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
TLS_ECDHE_RSA_WITH_RC4_128_SHA,TLS_RSA_WITH_AES_128_CBC_SHA256,
TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256,
TLS_RSA_WITH_AES_256_CBC_SHA,SSL_RSA_WITH_RC4_128_SHA"
sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2,TLSv1.3"
enableLookups="true"
sslProtocol="TLS"
keystorePass="password"
keystoreFile="path-of-the-saml-cerficate-file.keystore"
clientAuth="want"

secure="true"
scheme="https"
SSLEnabled="true"
maxThreads="150"/>
For more information about enabling SSL, refer the Enabling SSL on the xCP
Application Host section.
2. Download the metadata file of the Identity Provider Server to the local path of the
xCP deployed application server installation after the Identity Provider Server is
configured. For example, the path of the metadata file is shown as path-of-
the-idp-metadata-file
3. To download metadata file of Identity Provider Server, use the following

command:
ADFS IPS Server URL:
https://<hostname-of-IPS>/federationmetadata/2007-06/federationmetadata.xml
4. Install an application server and deploy an xCP application on any of the

supported Application Servers.
5. Locate the rest-api-runtime.properties file under the application server

home directory and specify the following properties. The rest-api-runtime.
properties.template file, which is in the same location, has all the
configuration parameters as follows:
The runtime property rest.security.saml2.user.attributes specifies the
user principal attributes in SAML assertion. The availability of these attributes
is configured by Identity Provider’s attribute release policy.
In this sample, the Identity Provider’s attribute release policy is configured by
the ADFS 2.0 attribute http://schemas.microsoft.com/ws/2008/06/identity/
claims/windowsaccountname. Multiple attributes can be specified as the
runtime property.
# SAML authentication schema
rest.security.auth.mode=saml
# For fallback support, change the mode to saml-basic

rest.security.auth.mode=saml-basic
#specify the java key store file

rest.security.saml2.ks.file=path-of-the-saml-certificate-file.keystore
#specify the password of the java key store

rest.security.saml2.ks.password=password
#specify the alias of key entry used by the SAML Service Provider to
#sign the SAML message
rest.security.saml2.ks.entry.alias=alias
#specify the password of the key entry used by the SAML Service Provider
#to sign the SAML message
rest.security.saml2.ks.entry.password=password
#specify the HTTP method used to send SAML request to the Identity Provider
rest.security.saml2.request.binding=HTTP-Redirect
#specify the metadata files of the Identity Providers

rest.security.saml2.idp.metadata.files=path-of-the-idp-metadata-file

#specify the attributes used to extract principal names from the SAML response
rest.security.saml2.user.attributes=http://schemas.microsoft.com/ws/2008/06/
identity/claims/windowsaccountname
#specify the cookie timeout of SAML request token

rest.security.client.saml2.timeout=300
#specify the documnetum ticket timeout , our recommendation is to set the

#value twice as the http session timeout for the xCP application and
#provide value is in minutes
#To avoid using the SAML login for each request, xCP SAML SSO has been
#integrated with Documentum Ticket. After the SAML login succeeds, xCP
#application requires the Documentum Login Ticket from the Documentum Server
#with the SAML DFC session. All the subsequent xCP requests are based
#on Documentum ticket authentication, with the exception of the SAML login
.
rest.signon.ticket.timeout=480
6. When rest.security.saml2.request.signature.algorithm property in the

rest-api-runtime.properties file is not commented, it is madatory to
specify one of the signature algorithms— RSA-SHA1, RSA-SHA256, and RSA-
SHA512. Otherwise, the default algorithm is RSA-SHA256.
7. Edit dfc.properties under the application server home directory according to

the Documentum Server configuration.
8. Download the metadata file for the xCP application (SP).
9. Deploy the xCP Application to the Tomcat application server, and download
the Service provider metadata by accessing the xCP application as per the
following URL:
https://<application_server_hostname>:8443/xcpAPP/saml/metadata
10. Copy the spring_saml_metadata.xml to AD FS 2.0 Identity Provider Server

machine and create Relying party in AD FS Management console.
a. Launch AD FS Management Console.

b. Navigate to AD FS 2.0 > Trust Relationships > Relying Party Trust, right-
click and then select Add Relying Party Trust.
c. Click Start.
d. Select Import data about the relying party from a file and browse for the
spring_saml_metadata.xml file and click Next.
e. In the Specify Display Name screen, provide a relevant name and click
Next.
f. In the Choose Issuance Authorization Rules screen, select Permit all users
to access this relying party and click Next.
g. In the Ready to Add Trust screen, click Next
h. Select Open the Edit Claim Rules dialog for this relying party trust when
the wizard closes and click Close.

2.25.4.3 Configuring Relying party for AD FS (IDP Server)

1. In Edit Claim Rules for relying party, select Issuance Transform Rules and
then select Add Rule.
2. In Select Rule Template, select the Send LDAP Attributes as Claims from the
drop-down list of Claim rule template.
3. In Configure Rule , specify the claim rule name and select the attribute store as
Active Directory from the drop-down list.
4. In Mapping of LDAP attributes to outgoing claim types, perform the
following:
• Select LDAP Attribute as Display-name and select Outgoing Claim Type as

Windows account name
• Select LDAP Attribute as Display-name and select Outgoing Claim Type as
Name ID
5. Select Finish.
2.25.4.4 Editing Relying party for AD FS (IDP Server)

1. Navigate to AD FS 2.0 > Trust Relationships > Relying Party Trust , right-click
and then select Edit Claim Rules .
2. Select the created relying party.
3. In Replying Party Properties page, click the Advanced tab and select SHA-1 as
secure hash algorithm.
4. Remove the default encrytion certificate under the tab Encryption and click OK.
5. Restart the AD FS 2.0 service.
6. Access the xCP application from the following URL:

https://appserverIP:8443/application
This link redirects to the authentication page for your credentials and extracts a
new SAML ticket. Once you have provided your credentials, it logs to the xCP
application home page.

2.25.4.5 Configuring SAML SSO for a cluster environment

When you deploy an application in a cluster environment such as behind a reverse-
proxy or load balancer, ensure that the entityBaseUrl parameter is configured. To
configure SAML SSO in a cluster environment, complete the following steps:
1. Create a new samlKeystore.jks file and distribute it to all the xCP nodes.
2. For all the xCP app-server nodes, open the customConf\rest-api-runtime.

properties file and configure the following properties.
Configure the authorization mode:
rest.security.auth.mode=saml-basic-lb # or saml-lb
Configure the entityBaseURL with the front-end URL to generate SP metadata:
xcp.security.saml2.entity.base.url=https://<fqdn>/app_root_context>
# https://www.myxcp.com/myapp
#to provide information about front-end URL to the back-end servers
xcp.security.saml2.url.scheme=<protocol> #https
xcp.security.saml2.url.hostname=<fqdn> #www.myxcp.com
xcp.security.saml2.url.port=<port> #443
xcp.security.saml2.url.context.path=<context_path> #/myapp
Notes
• Use saml-basic-lb attribute to enable SAML and form based login.

• Use saml-lb attribute to enable only SAML authentication with no
fallback support of form based login.
• Make sure that the load-balancer is configured to use sticky sessions.
2.25.5 Troubleshooting SSO

To enable logging of error messages, configure these packages in the
log4j2.properties configuration file:
# XRest Security
logger.xRestSecurity.name=com.emc.rest.rest.security
logger.xRestSecurity.level=DEBUG
logger.xRestSecurity.additivity = false
logger.xRestSecurity.appenderRef.xRestSecurity.ref=xRestSecurity //create your own
appender
# Documentum Rest
logger.documentumRest.name=com.emc.documentum.rest
logger.documentumRest.level=DEBUG
logger.documentumRest.additivity = false
logger.documentumRest.appenderRef.documentumRest.ref= documentumRest //create your own
appender
# Spring
logger.spring.name=org.springframework
logger.spring.level=DEBUG

2.25.5.1 SSO fails when multiple applications deployed on same

Application Server
Problem
When you have multiple xCP applications using SSO deployed on same application
server, SSO fails.
Resolution
1. Stop the Application server.
2. Move vsj-license.jar and vsj-standard-3.3.jar files from <webapps_
home>/xcpapp/WEB-INF/lib (from all xCP applications deployed on the
Application Server) to the <app_server>/lib folder.
3. Restart the Application Server.
2.25.5.2 Accessing SSO-enabled xCP application fails
Problem
While accessing the SSO-enabled xCP application that is configured in the rest-api-
runtime properties, you may see the login page instead of being automatically
logged to the application using SSO.
Resolution
Verify the parameters in the rest-api-runtime properties file to ensure the system
picks up the right version of the rest-api-runtime properties file from the current
location.
2.25.5.3 xCP application fails to start in SAML
Problem
xCP application fails to start as it is unable to access federationmetadata.xml from
some folder location.
Resolution
To resolve the issue, put the federationmetadata.xml file inside the application
server folder location. For example: C:\tomcat\webapps\sampleapp\foldername
\federationmetadata.xml.

2.25.5.4 Limitation of ADFS Identity Provider Server
Problem
Due to limitation of ADFS Identity provider server, you cannot have two
applications deployed on the application server on the same machine.
Resolution
Avoid this scenario in your environment.
2.25.5.5 Log error of SAML message signature failure
Problem
On the ADFS Server log, you may see The verification of the SAML message
signature failed error message.
Message issuer: abc
Exception details:
MSIS1016: Relying party trust 'abc' indicates that authentication
equests sent by this relying party will be signed but no signature present.
Resolution
To resolve the issue, execute the following commands from powershell:
Add-PSSnapin Microsoft.Adfs.PowerShell
Get-ADFSRelyingPartyTrust
set-ADFSRelyingPartyTrust -TargetName
RelyingParty Name" -SignedSamlRequestsRequired $False
2.25.6 Configuring OpenText Directory Services

Authentication in Documentum Server
OpenText Directory Services (OTDS) enables identity management and SSO user
authentication across OpenText products.
1. Install the Documentum Server.

2. Download and install OTDS 16.6 or later. Make sure that otds-admin and otdsws
services have been started.
Extract the certificate from OTDS. Go to http://<otds-server>:8080/otdsws/rest/
systemconfig/certificate_content and get the certificate content of OTDS.
3. On the Documentum Server machine, locate the otdsauth.properties file at
<Documentum Root Folder>/tomcat<version>/webapps/
OTDSAuthentication/WEB-INF/classes.
4. Copy the certificate content between BEGIN CERTIFICATE and END

CERTIFICATE as a single line string and make sure that you have removed all
newline and spaces.

5. Set the value of otds_rest_credential_url as http://<otds-server>:8080/

otdsws/rest/authentication/credentials.
6. Run IAPI to execute the following commands to enable OTDS authentication in
Documentum Server:
API> retrieve,c,dm_server_config
API> append,c,l,app_server_name
SET> OTDSAuthentication
API> append,c,l,app_server_uri
SET> http://<DocumentumServer>:9080/OTDSAuthentication/servlet/authenticate
API> save,c,l
7. Restart the connection brokers and repositories to reflect the settings.

8. Set up Active Directory and OTDS. For more information, refer the OpenText
Documentum Server Administration and Configuration Guide.
9. Make sure the Active Directory users are synchronized into OTDS. Perform the
following steps to synchronize the active directory users into OTDS:
a. Open the otds-admin web application in your browser using http://<OTDS
machine>:8080/otds-admin and log in.
b. Click Partitions, then click Add > New Synchronized User Partition.
c. Specify the Connection information using the Active Directory host name
and port.
d. Enter the Authentication information.
Note: Do not change the General, Server Settings, and Group

Location information. These sections are already updated with the
default values.
e. Enter the User Location. Example: User Locations can be OU=engineering,
DC=xcp, DC=com rather than DC=xcp, DC=com to narrow down the sync to
only members of the engineering organization.
f. Do not change the User Mappings, Group Mapping, Scheduler,
Monitoring, Notifications/Search, and Extended functionality information.
These sections are already populated with default values.
g. Click Save, click Actions on the newly created partition, and then select
View Members.
Note: The members from the Active Directory are synchronized into
OTDS.
10. Perform the following steps to configure Documentum Server as a resource in
OTDS:
a. Log in to otds-admin web application.
b. From the otds-admin web application, click Resources, then click Add.
c. Specify a Resource Name, and retain the rest of the information as their
default values.

d. Under Synchronization, select User and group synchronization, Create

users and groups, Modify users and groups, and Delete users and groups.
Choose REST (Generic) from the Synchronization connector list.
e. Enter the Documentum Server dmotdsrest URL as http://
<DocumentumServer>:9080/dmodtsrest, user name, and password, and
then click Test Connection.
f. Add client_capability value of 2 and default_folder resource attribute
as /%s and retain the default values of other attributes. Click Next.
g. Retain the default values on the next screen and click Save. Note at this time
that the resource is not activated.
h. Configure an access role. Select Access Roles > Actions > Include-Groups
and click OK.
i. Click View Access Role Details.
j. Click Add, select the newly created partition, and select Add Selected Items
to Access Role. The partition’s user and group is synced to the Documentum
Server.
k. Click the Groups tab and delete the default otdsadmins@otds.admin group
and click Save to save the access role changes and synchronize the users to
the Documentum Server.
l. To synchronize partition users into Documentum Server successfully, from
the otds-admin web application, click Resources, then select the resource
you just created.
m. Click Actions, then select Consolidate to perform a full synchronization.
n. Use iDQL to verify that the users are synchronized into the dm_user table.
Configuring OTDS authentication for xCP

1. To configure OTDS authentication for xCP, ensure that OTDS authentication is
already configured in Documentum Server.
Notes
• OTDS implementation in xCP does not provide a fallback mechanism.

• xCP supports Multi-factor authentication through OTDS, for more
information, see OpenText Directory Services Installation and Administration
Guide.
2. xCP supports full-way OTDS SSO authentication over OAuth2 protocol. To
configure an OAuth2 client in OTDS, perform the following steps:
a. Open the otds-admin web application in your browser using http://<OTDS
machine>:8080/otds-admin and log in.
b. Go to the otds-admin web application, click OAuth Clients and click Add.

Notes
• Ensure that the Confidential checkbox is selected.

• To avoid OTDS SSO failure when using load balancer, add the
following configuration in the rest-api-runtime.properties file:
rest.security.otds.reverseproxy.url=https://<reverseproxy>
c. Click Next until the Redirect URLs page appears, add https:\/\/<regular
expression for host name and port of AppHost>\/.*\/otds-signin
\.jsp as the redirect URL.
Examples:
http:\/\/10\.194\.52\.246:8000\/.*\/otds-signin\.jsp
Or,
https:\/\/appserver\.xcp\.com:8443\/.*\/otds-signin\.jsp
d. Click Save. The Client Secret is generated. Copy the Client Secret value.
e. Generate the OAuth2 access token using otdsws:
https://<otdsidp>:8443/otdsws/oauth2/auth?response_type=token
&client_id=<client_id>
&redirect_uri=<url encoded value of <app host URL>
/testapp/otds-signin.jsp>
f. Log in to OTDS as a user from the partition configured in the OTDS.

g. Copy the OAuth2 access_token from the redirect URL and use it to
authenticate on Documentum Server. Run the following commands in IAPI
API> connect,<repo_name>,<USER_LOGIN_NAME>,dm_otds_oauth=<OAuth2 access token>
3. Add the following properties to the <CustomConf>/rest-api-runtime.properties

file available in the <WebAppName>/WEB-INF/classes/ folder:
rest.security.auth.mode=otds
rest.security.otds.login.url=<otds-idp>/otdsws/login?
response_type=token&client_id=<client_id>
rest.security.realm.name=com.emc.documentum.rest
//Default is 480 minutes
rest.signon.ticket.timeout=
rest.signon.logout.url=/otds-signin.jsp?logout=yes
rest.security.auth.mode=otds-basic
rest.security.realm.name=com.emc.documentum.rest
rest.security.otds.login.url=<otds-idp>/otdsws/login?
response_type=token&client_id=<client_id>&logon_appname=<app_name>rest.signon.logout
.url=/otds-signin.jsp?logout=yes
Sample configuration:
rest.security.otds.login.url=https://10.194.52.116:8080/otdsws/login?
response_type=token&client_id=xcp-client
&logon_appname=ap2801
4. Restart the application server on which the xCP application is deployed.

5. Access the xCP login page. The user is redirected to the OTDS sign in page.

Configuring OTDS authentication for iHub widget

xCP iHub integration is supported for iHub version 16.4 and later.
To configure OTDS authentication for the xCP iHub widget, perform the following
steps:
1. Configure iHub resource in OTDS. For more information, refer the iHub
documentation.
2. The iHub resource configuration in OTDS must have Principal Attribute
mapped to oTExternalID3.
3. Ensure that the iHub resource in OTDS is in Deactivated state.
4. Only iHub OTDS authentication over the OAuth2 protocol is supported by the
xCP iHub widget.
Note: The same OAuth2 confidential client profile must be used by both
xCP application and iHub.
5. In the iHub system console, ensure that the following configuration settings are
set under the User Management settings of the cluster:
Configuration Setting Value

User Management OpenText Directory Services
Integration Type OAuth2
OAuth2 Client Client ID of the OAuth2 client configured
in OTDS
OAuth2 Secret Key Client secret of the OAuth2 client
configured in OTDS
User Email Attribute oTExternalID3
Group Name Attribute oTExternalID1
Note: When the iHub widget is not used over the OTDS configuration,
non–confidential OAuth2 client configuration works for xCP, and
rest.security.otds.login.url configuration in rest-api-runtime.
proeprties does not require client_secret parameter to be set.
6. Click Save and restart the iHub server.
7. Refresh the resources in OTDS and ensure that iHub resource is in Activated
state.
8. Access the xCP login page. The user is redirected to the OTDS sign in page.

2.26. Cross-Origin Resource Sharing (CORS) support
2.26 Cross-Origin Resource Sharing (CORS) support

The Cross-Origin Resource Sharing (CORS) specification defines a mechanism to
enable client-side cross-origin requests. Specifications that enable an API to make
cross-origin requests to resources can use the algorithms defined by this
specification.For example, when an API is used on http://example.org resources, a
resource on http://hello-world.example can be made to use the mechanism described
by the CORS specification by setting Access-Control-Allow-Origin: http://
example.org in the Response Header. This mechanism retrieves the resource cross-
origin from http://example.org.
You can enable xCP CORS support by configuring therest-api-runtime.

properties file:
1. Locate the rest-api-runtime.properties file in the application server home

directory.
# Whether or not cross origin resource sharing support is enabled.

# Specifies whether to enable cross origin resource sharing support.
# The default value is false.
rest.cors.enabled=false
#
# Specifies the origins which are allowed to share.
# When you want to enable an origin to share, set the value to *.
# When there are more than one origin exists, the value should
# be seperated by a comma.
# For example, http://emc.com,https://test.com:8443
# The default value *.
rest.cors.allowed.origins=*
# Specifies the HTTP methods allowed to be shared.

# Common methods are GET, POST, PUT, DELETE, OPTIONS, HEAD.
# The value should be in upper case, and seperated by a comma.
# The default value is: *.
rest.cors.allowed.methods= *
#
# Specifies the HTTP headers (Origin, X-Requested-With, Content-Type,
# Accept, Range, Authorization)
# allowed to be sent.
# The value should be separated by a comma.
# The default value is '*', which means all headers are allowed.
rest.cors.allowed.headers=*
#
# Specifies whether to allow user credentials.
# The default value is true.
rest.cors.allow.credentials=true
#
# Specifies the headers which are safe to expose to the API.
# The values are seperated by a comma.
# The simple headers are exposed by CORS specification,
# and need not be set: Cache-Control, Content-Language,
# Content-Type, Expires,Last-Modified, Pragma.
# The default exposed header is 'Location'.
rest.cors.exposed.headers=Location
#
# Specifies the life time in seconds; the results of a 'preflight'
# request can be cached.
# The value is in seconds, and the default is 3600 (one hour).

rest.cors.max.age=
Note: The Cross-Origin HTTP POST is blocked when CORS is enabled,

which affects the SAML assertion post binding. To enable, SAML IdP must
be specified in allowed origin list (which by default is set 'to *', allowing
POST from any origin)
For more information, refer to the OpenText Documentum Platform REST Services
Development Guide. The World Wide Web Consortium (W3C) site provides more
information about Cross-Origin Resource Sharing specifications.

Chapter 3
Deploying an xCP Application
3.1 Overview of Deploying an xCP Application

The following table lists the application deployment methods, connections, and data
policies that you can use with each environment mode:
Environment Mode Application Application Application

Deployment Method Deployment Deployment Data
Connection Policy
Development xCP Designer only xCP Deployment Clean, Minimal, or
Agent only Maintain
Production xCP Designer or xDA xCP Deployment Maintain only
Tools Agent only
The prerequisites for deploying an application is environment configuration details

registered in xDA. “Registering an environment” on page 85 provides details.
Best practice:
• To avoid disk space issues, clear the cache before deploying applications.
• If you access the application within 1 hour of redeployment, clear the browser
cache.
If you have developed an application using previous version of xCP, and if you
want to deploy that application to the current runtime environment, the application
requires some migration steps in the current version of xCP Designer. The Migrating
an application topic in the xCP Designer Help describes how to perform these
migration steps. Now you can deploy applications to the current runtime
environment.
3.2 Application Deployment Using xCP Designer

In xCP Designer, you typically deploy an application to a Development environment
or a test environment. You can deploy an application in secure mode as well. The
prerequisites for deploying an application using xCP Designer are:
• The prerequisites listed in “Overview of Deploying an xCP Application”

on page 149
– In the folder where you have installed xCP Designer, edit the xcpdesigner.ini
file. Find the following parameters:
-Dxcp.application.url.host=
-Dxcp.application.url.port=8000

Chapter 3 Deploying an xCP Application
These are the default settings. When rest.application.url.host is set to nothing,

the system uses the IP address of xCP Deployment Agent.
– Set the rest.application.url.host parameter to the IP address of the xCP
application host.
– If the xCP application host is not installed on port 8000, then set the
xcp.application.url.port parameter to the correct port number.
– Restart the xCP Designer.
• Information registered in xCP Designer. The required information includes:
– The name of the deployment environment.

– The IP address and port number of xDA so that the system can connect to the
xCP Deployment Agent.
– xCP Deployment Agent credentials (user name and password).
– The name of the target environment registered in xDA on which you intend
to deploy the application.
• For deploying large and complex applications using xCP Designer, you need to
increase the heap size of XMX to 1024 in the .ini file of the xCP Designer. Then,
restart the xCP designer.
When you click Run Application on the xCP Designer toolbar, the system deploys
the application to the deployment environment.
If you make a change to a deployed business object that requires data to be

destroyed, re-running the application forces the changed business object definitions
to be redeployed. In the following scenarios, data associated with the business object
is deleted:
• Removing an attribute from a type

• Renaming an attribute on a type
• Shortening the length of a string attribute
• Changing an attribute from single to repeating
• Changing an attribute from repeating to single
Business object instances are also deleted when the business object is deleted from
the application.
If you have test data in your environment, any of the preceding changes to your data
model causes some data to be lost. As a best practice for these situations, build
loader scripts using API, DQL or Java DFC code to load the data, and periodically
use the clean option to clean your data and then reload it.
As a best practice, if you make a change to an application that is already in

production, use the maintain data policy to ensure that you do not run into issues

3.3. Application Deployment Using xDA Tools
during application upgrade, since maintain is the only supported data policy in a
Production environment.
3.3 Application Deployment Using xDA Tools

A developer or consultant packages an application created in xCP Designer when it
is ready to be deployed to a staging or Production environment. Packaging is the
automated process of validating an application, compiling it, and putting the
application in the correct format for a deployment environment. The packaging
process produces two files: a WAR file and an application configuration file in XML
format. You could receive these files in various ways, for example, after an upload to
a staging area, by FTP, in email, or on physical media. After you receive these files,
save them to a desired location.
When you deploy an application for the first time, you can enter or overwrite
endpoint and parameter values in the application configuration file. When you
redeploy the same application to an environment in Production mode, the system
deploys only new parameter or endpoint values. You can deploy an application in
secure mode as well.
The prerequisites for deploying an application using xDA Tools are listed in
“Overview of Deploying an xCP Application” on page 149.
3.3.1 Deploying an Application with xDA Tools

1. Navigate to the location of the xCP Designer application package.
2. Open the application configuration file in a text editor.
3. Enter or overwrite endpoint or parameter values as necessary. For example, you
could enter a value for the property name WSDL URL in the ABC Web Service
endpoint as shown in the following code sample:
<configuration type="Web Service (SOAP) endpoint" name="ABC Web Service">
<property name="WSDL URL">http://www.someurl.com</property>
<property name="User name"></property>
<property name="Password"></property>
</configuration>
“Updating Endpoint Values After Application Deployment” on page 200

provides details on updating endpoint values after you have deployed an
application. Use the Manage Application Parameters page in xCP Designer to
update application parameter values after you have deployed an application.
xCP Designer Help provides the steps to perform this task.
4. Save the file.
5. Double-click xda.bat in ${xda-tools-home}\bin and log in with xCP Deployment
Agent user name and the password of that user. For Linux environment, run
xda-tools\bin\xda.sh using Administrator credentials.
6. At the <xda> prompt, type

deploy-xcp-application --environment <name>--war-file <filename>
--configuration-file <filename> [--deployment-method <method>][––

data-policy <policy>] [--validateonly <validateonlyflag>] [--

xploreindexing <xploreindexingflag>] [--repositoryservicesonly
<repositoryservicesonlyflag>]
Specify the parameters --war-file, --configuration-file, and ––
environment, either on the command line or in the deploy-xcp-application.
properties file.
The following table describes the parameters:
war-file Specify the path, including the file name,
to the WAR file in the application package.
For model-only deployment, specify the
path, including the file name, to the
artifact_bundle JAR file and set the
repositoryservicesonly parameter value as
true.
If the path to the file contains a space, put
double quotation marks around the path.
configuration-file Specify the path, including the file name,
to the application configuration file in the
application package. If the path to the
configuration file contains a space, put
double quotation marks around the path.
environment Specify the environment name where you
want to deploy the application.
deployment-method (Optional) Specify the deployment
method. The method can be:
• Incremental: Deploys only application
components that changed since the last
deployment or new application
components (for example, an updated
business object model or a new
application page). This is the default.
• Full: Deploys the full application.

data-policy (Optional) Specify the data policy. The
data policy defines what happens to
application data in the environment when
you deploy a new version of the
application. Examples of application data
include runtime instances of business
objects, content objects, processes, and
reports. The policy can be:
• Clean: Deletes application data from
the environment.
• Minimal: Updates application data
associated with application data that
changed since the last deployment.
This is the default if you set the
environment mode to Development.
• Maintain: Preserves application data.
Deploying the updated application
does not affect existing application
data in the environment. This is the
default if you set the environment
mode to Production.
Best practice: Use Maintain when there is
an existing production deployment of the
application you are working on and you
want to change the application. Setting the
deployment to use Maintain mode
ensures you capture any data upgrade
issues before you deploy to the Production
environment. Use a representative set of
test data in your Development
environment to accurately catch any issues
that might occur in production when you
try to redeploy the upgraded application.
An environment set to Development mode
supports all the data policies. An
environment set to Production mode
supports only the Maintain policy.
If you have test data that is important,
create test loader scripts using API, DQL,
or Java DFC code to load the data. If your
data policy is set to Minimal or Clean,
you could lose the test data, in which
means that you need an automated way to
re-populate it.

validateonly (Optional) Indicate whether the entire
deployment must be performed or only
the validation step. The options are:
• False: Validates the application and
deploys it if it is valid. This is the
default.
• True: Validates the application and logs
information about full-text indexing
considerations that helps you decide if
you want to skip full-text indexing
during the deployment.
xploreindexing (Optional) Indicate whether the entire
deployment must be performed or if full-
text indexing must be deferred. The
options are:
• True: Performs full-text indexing
during the application deployment.
This is the default.
• False: Skip full-text indexing during the
application deployment. In this case,
launch full-text indexing manually.
“Deploying an Application with Full-text
Indexing” on page 155 provides more
information about full-text indexing
considerations during the application
deployment.
repositoryservicesonly (Optional) Indicates whether to deploy the
complete application or only the
repository artifact bundle. The options are:
• False: The system accepts the war file
for the --war-file parameter. This is the
default.
• True: The system accepts the artifact
bundle JAR file for the --war-file
parameter.
The system looks for manifest files in subfolders of ${xda-home}\installs on the

machine where xCP Deployment Agent is running. After successful application
deployment, the system shows a message that it executed the command.
When an application is deployed, system creates temporary files in ${xda-home}
\temp\work. System automatically delete these temporary files post
application deployment.

3.3.2 Deploying an Application with Full-text Indexing

xPlore automatically indexes the content and metadata of the object models defined
in the application. xPlore creates an index, based on its name, for each attribute.
There is no reference to the object model or to the application in which the object
model was created. Each attribute corresponds to a subpath element in xPlore index
definition. Depending on the query models, the xCP Deployment Agent modifies
the index definition during application deployment to optimize the queries, for
example, when you set output columns as sortable. In some cases, xPlore needs to
rebuild the index.
When the repository contains over a million of objects, the indexing can take several
days. To avoid preventing the application from deploying because it is being
indexed, you can deploy the application without having it perform indexing and,
instead, launch the indexing manually as a background task using xPlore
administration tool. “Deploying an Application Deferring Full-text Indexing”
on page 156 describes how to skip the indexing during the application deployment.
During the validation step of the application, the system tests whether xPlore server
and index agent are running and provides you with the following information:
• The subpaths required for the application.
• The subpaths already defined in xPlore index definition.
• The subpaths that must be updated for the application deployment.
• Conflicts between attributes with the same name but of different types. These
internal conflicts stop the validation. You must fix them manually in xCP
Designer by modifying the object models.
• Potential conflicts with other applications. For example, changing the data type
of an attribute introduces the risk of a conflict with another application. You
must make sure there are no conflicts with other applications.
• The actions performed during the deployment or actions you must perform
manually if you skip the indexing:
– Index definition update: The system automatically updates the index

definition even if you skip indexing.
– Clean-up of the indexes: If you skip indexing, delete the indexes manually. If
an object model is deleted from an application, the artifacts and instances are
deleted from the repository but the corresponding indexes are not removed
from xPlore. They must be deleted to avoid future conflicts, for example if
another object model is created with an attribute with the same name but of
different type.
– Rebuilding indexes: If you skip the indexing and the validation step indicates
that a rebuild of the indexes is necessary, launch the rebuild manually using
xPlore Administrator.

– Reindexing of the objects: If you skip the indexing and the validation step
indicates that a refeed objects is necessary, launch a reindexing operation
using the Index agent UI to retrieve objects from the repository.
When you launch the indexing manually, end users may be unable to find some
content objects or to see facets values until the objects are indexed. To avoid this
issue, you must perform a two-phase deployment:
1. Deploy an initial version of the application in which all the object models and
full-text query models are defined. The search pages must not use the full-text
query models. This deployment triggers the indexing of the repository content.
2. Once indexing is complete, deploy a second version of the application in which
the search pages are bound to the full-text query models. Because the models are
not modified, no re-indexing is necessary, and all the search functions are
immediately available to the end users.
If you deleted object models or attributes, run the ftintegrity tool to verify that all
content objects, ACLs, and groups from the repository have been indexed by xPlore.
The OpenText Documentum xPlore Administration and Configuration Guide describes
how to run the ftintegrity tool.
3.3.3 Deploying an Application Deferring Full-text Indexing

The following procedure describes when you can modify xPlore configuration and
environment and when you can launch the indexing with regard to application
deployment.
1. To start xDA, double-click xda.bat in ${xda-tools-home}\bin and log in.

2. At the xda> prompt, run the deploy-xcp-application command with the
parameter --validateonly true.
3. Review the messages to understand the impact on the full-text index.
4. Assess reindexing time and evaluate if you need to modify xPlore environment.
For example, you can create additional instances.
Use xPlore documentation and xPlore tools to help you size your environment.
5. Launch the deployment:
• To launch the deployment and automatically build or rebuild the full-text

index, use the deploy-xcp-application command with the parameter --
xploreindexing true or omit it.
• To launch the deployment without rebuilding the full-text index, use the
deploy-xcp-application command with the parameter --xploreindexing
false
6. Start the xPlore administration tool.

7. Make the necessary configuration adjustments depending on your environment,
for example, you can modify the index definition.

3.4. Deploying an Application to an application server
OpenText Documentum xPlore Administration and Configuration Guide provides

details about configuring the full-text index.
8. If you skipped the indexing, perform required operations manually.
a. Review the messages logged in the xDA console and look for the messages
starting with Steps that should be run to deploy on xPlore.
b. If a message indicates Rebuild xPlore indexes, log on to xPlore
administration tool, navigate to the collection, and click Rebuild indexes.
c. If a message indicates Refeed following type(s), log on to the index
agent UI and reindex the specific object model.
The OpenText Documentum xPlore Administration and Configuration Guide
describes the ways to launch the reindexing. The section Migrating content
(reindexing) describes how to reindex everything. The section Migrating
documents by object type describes how to reindex instances of a specific
object model.
9. If you deleted object models or attributes, run the ftintegrity tool to verify that
all content objects from the repository have been indexed by xPlore.
The OpenText Documentum xPlore Administration and Configuration Guide
describes how to run the ftintegrity tool.
10. If you are using Java Method Server and have deployed into a clustered
environment, restart all Java Method Servers in the environment.
3.4 Deploying an Application to an application

server
You can deploy xCP applications to Tomcat, tc Server, JBoss application server. You
can deploy applications to Tomcat or tc Server with no additional configuration.
3.4.1 Deploying an application to WildFly or JBoss server

The following sections describe how to configure the system to deploy xCP
applications to the JBoss application server. Before deploying an application to
WildFly or JBoss Server:
• Install and configure WildFly or JBoss.

• Install xCP Deployment Agent. “Installing the xCP Deployment Agent”
on page 75 provides instructions.
• Register your environment. “Using the xDA management center to register an
environment” on page 83 provides details.
1. Configure your system so that xDA can locate the WildFly Management JAR
file:

a. Create a folder (for example, C:\wildflylibs) and copy the jboss-cli-

client.jar file from the <WildFly_Install_Location>\bin\client to your
local file system.
b. On xDA machine, navigate to ${xda-home}\xDA\config. Open xda-
config.properties for editing. Add wildfly.libs.home property,
specifying the location of the JAR file, as in the following example:
wildfly.libs.home=C:\wildflylibs
2. Configure your system so that xDA can locate the JBoss Management JAR file:
a. Create a folder (for example, C:\jbosslibs) and copy the jboss-cli-

client.jar file from the <JBoss_Install_Location>\bin\client to your local
file system.
b. On xDA machine, navigate to ${xda-home}\xDA\config. Open xda-
config.properties for editing. Add jboss.libs.home property, specifying
the location of the JAR file, as in the following example:
jboss.libs.home=C:\jbosslibs
3. For HTTPS mode: When WildFly application server is configured in HTTPS

mode, in addition to the jboss-cli-client.jar file, make these changes:
a. Copy the jboss-cli.xml file from <WildFly_Install_Location>\bin to the

C:\wildflylibs folder location.
b. Change the protocol to remote+https from the existing protocol of http-
remoting in the jboss-cli.xml file.
c. Modify the port number to match with the management-https port

configured for the WildFly appserver.
<code snippet of jboss-cli.xml file>
<jboss-cli xmlns="urn:jboss:cli:3.1">
...
<default-protocol use-legacy-override="true">remote+https
</
default-protocol>

<host>APPVM</host>
<!-JBOSS management-https port -->
<port>9993</port>
</default-controller>
</jboss-cli>
4. Restart the xDA application.
5. Change the configuration of your WildFly or JBoss server environment to meet

prerequisites:

3.4. Deploying an Application to an application server
a. In the classpath, include the directory containing the following property

files:
• dfc.properties
Now you can deploy applications. “Application Deployment Using xCP Designer”
on page 149 and “Application Deployment Using xDA Tools” on page 151 provide
details.
3.4.2 Deploying an Application to WebLogic Server

Before deploying an application to WebLogic Server:
• Install and configure WebLogic. The WebLogic Server documentation provides

installation and configuration instructions.
• Install xCP Deployment Agent. For more information, see Installing the xCP
Deployment Agent.
• Register your environment. For more information, see “Using the xDA
management center to register an environment” on page 83.
1. Ensure that Enable RESTful Management Services options is selected. To

verify or update this option, complete the following steps:
a. Log in to the WebLogic server console.

b. Click root domain under Domain Structure area.
c. Navigate to Configuration> General tab.
d. Expand Advanced section and select Enable RESTful Management
Services option.
e. Click Save.
2. If the application that you want to deploy is dependent on any shared libraries,
place these libraries in the lib folder of the domain.
3. Change the configuration of your WebLogic server environment to meet the
required prerequisites:
a. In the classpath, include the directory containing the following property

files:
• dfc.properties
You can do so by opening the following file for editing:

WebLogic domain directory>\bin\setDomainEnv.cmd

At the end of the file, add the following line:

To deploy the application on the application server successfully, disable

assertions in the setDomainEnv.cmd file as follows:
debugFlag=False
b. Set the -Dlog4j2.configurationFile system properties. You can do so by

opening the following file for editing:
<WebLogic domain directory>\config\config.xml
Locate the <security-configuration> element. Under that element, add the

following entry:
false
Note: Now you can deploy applications. For more information, see
“Application Deployment Using xCP Designer” on page 149 section and
“Application Deployment Using xDA Tools” on page 151 section.
3.4.3 Deploying an Application to Websphere Liberty

Application Server
Configure your system so that xDA can locate the WebSphere Liberty Management
JAR file:
1. Create C:\LibertyLibs folder.
2. Copy the following files from WebSphere Liberty installation folder to

C:\LibertyLibs folder:
• C:\IBM\WebSphere\Liberty\clients\restConnector.jar
• C:\IBM\WebSphere\Liberty\dev\api\ibm\com.ibm.websphere.
appserver.api.basics_1.4.47.jar
• C:\IBM\WebSphere\Liberty\dev\api\ibm\com.ibm.websphere.
appserver.api.restConnector_1.3.47.jar
3. On xDA machine, navigate to ${xda-home}\xDA\config folder and open

xdaconfig.properties file for editing. Add websphereliberty.libs.home
property and specifiy the location of the JAR file, as shown in the following
example:
websphereliberty.libs.home = C:\LibertyLibs

3.5. Deploying an Application in a Clustered Environment
3.5 Deploying an Application in a Clustered

Environment
With manual provisioning, you can set up a clustered environment to enable load
balancing, scalability, and high availability. However, for some components,
deploying an application in a clustered environment requires manual configuration:
• For additional Documentum Servers or additional CTS instances, deploying an

application does not require any manual configuration.
• For additional xPlore instances, deploying an application does not require any
manual configuration.
• For additional xCP application hosts, deploying an application does require
manual configuration. “Completing Deployment with Multiple xCP Application
Hosts” on page 161 provides details.
• For additional BAM instances, the following circumstances indicate whether
changes are needed for xCP application deployment:
– If BAM was already in a cluster with at least two nodes, when you add
another node, no changes are needed for xCP application deployment.
– If BAM was not in a cluster and you add an extra node to form a new cluster,
then deploying an application does require manual configuration.
“Completing Deployment with Multiple BAM Instances” on page 162
provides details.
When you use xDA to provision a clustered environment, xDA handles all required
configurations.
3.5.1 Completing Deployment with Multiple xCP Application

Hosts
When you deploy an application to a clustered environment, the xCP Designer or
xDA deploys it on the primary xCP application host node.
1. If you are using Tomcat, configure each xCP application host node.
“Configuring Tomcat” on page 35 provides instructions to be repeated on each
node.
2. If you are using tc Server, configure clustered load balancing and failover for
the xCP application by manually updating the primary and additional xCP
application hosts.
3. If you are deploying an application to a manually-provisioned environment,
you determine the primary node when creating the instance by giving it a
unique name.
When multiple xCP applications built using different versions of xCP are
deployed on separate repositories but in the same Documentum Server
instance, the BPM workflow fails. For example, when xCP 2.0 and xCP 2.1

applications are deployed to separate repositories (repo1 and repo2

respectively) but in the same Documentum Server instance, BPM workflows
fails.
Workaround: To have a separate JMS for each repository.
3.5.2 Completing Deployment with Multiple BAM Instances

1. Look for a bam-server.properties file in the Customconf folder on the
application server instance. For example, <application_server_home>
\<server_instance>\Customconf
2. If the bam-server.properties file does not exist in the Customconf folder,

perform the following steps:
a. Download bam-server.war from the OpenText MySupport (https://

support.opentext.com) site. The bam-server WAR file contains the
properties file.
b. Extract the bam-server WAR file you downloaded and open bam-
server.properties.
c. Remove the comment symbol (#) from the following lines and enter values
for your environment:
Specify the IP address and port details of the load balancer for BAM.
3. If the bam-server.properties file exists in the Customconf folder, open it. Revise
the following lines to reflect the IP address and port details of the load balancer
for BAM:
bam.server.host=localhost
bam.server.port=8010
bam.server.context=bam-server
3.6 Using the Sample Application to Validate the

Deployment
After installing the software for the xCP environment and registering your
environment, you can use the provided sample application to validate that the
application deploys correctly. This validation is not an extensive test, but it provides
initial validation that the basic deployment is successful.
1. Navigate to the location of the application package:

${xda-tools-home}\xCPSampleApplication
2. Use xDA Tools to deploy the application. “Deploying an Application with xDA
Tools” on page 151 provides instructions.

3.7. Creating a Simple Application to Validate the Deployment
3.7 Creating a Simple Application to Validate the

Deployment
After installing the software for the xCP environment and registering your
environment, you can create a simple application to validate that the application
deploys correctly. This is not an extensive test, but it provides initial validation that
the basic deployment is successful.
1. In the directory where xCP Designer is installed, double-click xcpdesigner.exe

to launch xCP Designer.
For example: C:\xCPDesigner\xcpdesigner.exe
2. Create an application:
a. Click New Application.

b. In the Application Name field of the New xCP Application dialog box, type
a name for the simple application (for example, test_app) and click Next.
c. In the Namespace field, type a namespace for the application (for example,
tst), and click Finish.
3. Create a business object model:
a. In the Object Models navigator, right-click Business Objects and select

New Business Object.
b. In the New Business Object Model dialog box, in the Label field, type
Customer, and click Finish.
c. On the Attributes tab, from the Data Types palette, drag and drop a String
attribute onto the Customer business object model, and type Customer Name
for the name.
d. Drag and drop a second String attribute onto the Customer business object
model, type Customer Address for the name, and click Save All.
4. Create a real-time query:
a. In the Data Services navigator, right-click Real-Time Query and select New
Real-Time Query.
b. In the New Real-Time Query wizard, in the Label field, type Customer
Lists, and click Finish.
c. On the Dataset tab, from the Context Data palette, drag and drop the
following Customer attributes onto the Output Columns:
• Customer Name
• Customer Address
• Object ID

• Created on
d. Click Save All.
5. Create user interface pages and a context menu for the Customer business
object:
a. In the User Interface navigator, expand Business Object UI, right-click the
Customer business object, and select New Page.
b. In the New Page wizard, select Create Customer and click Finish.
c. In the same way, create two additional pages for View Customer and Edit
Customer.
d. In the User Interface navigator, right-click the Customer business object,
and select Create Context Menu.
6. Create a page for a list of customers and add a query:
a. In the User Interface navigator, right-click Application UI, select New

Page.
b. In the Label field, type List Customers, and click Finish.
c. In the Data Service Instances section of the layout editor, click Add.
d. In the Select Data Service dialog box, select Customer Lists and click
Finish.
e. Drag and drop a Results List widget from the Widgets palette onto the
layout editor.
f. On the General tab in the Properties view, in the Data service instance
field, select Customer Lists to bind the query to the results list and click OK.
g. In the Title field, type Customer List and click Save All.
7. Set the navigation menus:
a. In the User Interface navigator, double-click Master to edit the application

master page.
b. In the navigation menu, click Menu Item 1 and configure the fields on the
Menu Item tab in the Properties view as described in the following table:
Field Description
Label Type Create Customer.
Link type Select Application page.
Link page Select Create Customer.
c. In the navigation menu, click Menu Item 2 and configure the fields on the
Menu Item tab in the Properties view as described in the following table:

3.7. Creating a Simple Application to Validate the Deployment
Field Description
Label Type List Customer.
Link type Select Application page.
Link page Select List Customers.
d. Click Save All.

8. Create the deployment environment:
a. Click Preferences on the main toolbar.

b. In the Preferences dialog box, select Deployment Environments and click
Add.
c. In the Add Deployment Environment dialog box, type NewDeploy in the
Environment name field.
d. Type connection details for the xCP Deployment Agent as described in the
following table:
Field Description
Hostname Type the hostname or IP address of the
system where the xDA is running. If you
type the hostname, connectivity must be
available for the end user to connect to
the xCP Deployment Agent using the
hostname.
Port number Type the port number on which xDA is
running.
Username Type the username to access xDA.
Password Type the password for xDA user.
e. Click Test Connection to get the list of environment names from xDA
catalog. Select the target environment name from the list on which you
intend to deploy the application and then click Finish.
Note: The system fetches only the environment names whose status is
provisioned in xDA, that is, the environments that are completely
registered with all endpoint details and are successfully synchronized
to be ready for application deployment.
9. Create the run configuration:
a. In the Preferences dialog box, select Run Configurations and click Add.
b. Click Apply Now.
c. In the Add Run Configuration dialog box, in the Name field, type newrun
and in the Environment field, select NewDeploy.
d. If the mode of the provisioned environment is Production, verify that
Minimal is the selection for the Data Policy field.

e. Click Finish.
f. In the Preferences dialog box, click OK.
10. Click Run Application on the main toolbar to deploy the application.
11. If the application deployment fails, check the message in the Deployment
dialog box and investigate the log files. Check the runapp.log and the xDA logs
located in ${xda-home}\logs for setup and configuration issues.
12. Test the xCP runtime application:
a. Log in to the xCP application.

b. From the menu, select Create Customer.
c. Add a customer address, a customer name, and click Create to create a
customer (business object instance).
d. From the menu, select List Customer to view the list of customers.
e. Right-click a customer and select View Customer to access a page to view
the customer information.
f. From the menu, select List Customer, right-click a customer, and select Edit
Customer to access a page to modify the customer information.
If you are able to complete these tasks, the basic deployment is successful.
3.8 Enabling xCP Viewer to Access ACS and BOCS

for Searches
For the search functionality of xCP Viewer and xCP Advanced Viewer to access
Accelerated Content Services (ACS) and Branch Office Caching Services (BOCS)
directly from a web browser, enable cross-origin resource sharing in ACS and BOCS.
Otherwise, the search functionality uses the application server proxy of xCP Viewer
or xCP Advanced Viewer, which is slower than direct access.
Note: BOCS support is limited to the xCP Content Viewer and not the Import,
Import new version, Download or other content transfer functionality that is
performed outside of the xCP Content Viewer.
For ACS, change the CORSAllowed parameter to true in the web.xml file at the
following location:
%Documentum%\tomcat<version>\webapps\ACS\WEB-INF
For example:
<init-param>
<param-name>CORSAllowed</param-name>
<param-value>true</param-value>
</init-param>

3.9. Configuring xCP to Interact with CTS
Note: Ensure that CORSAllowed is set to true for Advanced Viewer to function
as expected.
For BOCS, change the CORSAllowed parameter to true in the web.xml file at the
following location:
%Documentum%\tomcat<version>\webapps\ACS\WEB-INF
After you update the web.xml files, restart the Java Method Server.
3.9 Configuring xCP to Interact with CTS

To enable an xCP application to send real-time requests for CTS to process,
configure xCP to interact with CTS. Perform this configuration after you deploy an
xCP application. This configuration is required only when you provisioned the
target environment manually.
1. Create a folder, ctsws_config, in the application server machine where an xCP

application is deployed.
a. Create the following subfolders inside ctsws_config folder.
• \cache
• \pfile
b. Copy the mspassword.txt file from a CTS product host (located at (%CTS%
\docbases\<your_docbase>\config\pfile) and paste it to the \ctsws_config
\pfile folder.
c. Copy the aek.key file from a CTS product host (located at %CTS%\config)
and paste it to the \ctsws_config folder.
2. Open a text editor and create a preferences.xml file with the following content
and save it in the ctsws_config folder. Values that you need to verify and
update are given in bold.
<ServiceConfiguration ID="CTS Web Services">
<PropertyList>
<ServerProperty Key="Cache" Description="The Temperory Cache Directory"
Value="C:/ctsws_config/cache" />
<ServerProperty Key="AllowDirectTransfer" Description="Allow Direct File
Transfer From CTS Server to Client. Set it to false if there is a
firewall restriction" Value="true" />
<ServerProperty Key="CTSWSPingInterval" Description="Interval (in seconds)
used to specify how frequent the LB should ping its CTS instances for
heart rate." Value="30" />
<ServerProperty Key="FailoverRetries" Description="Allow a number of
retries if a request fails while waiting on the HTTP response from CTS"
Value="1" />
<ServerProperty Key="FailoverWait" Description="Wait between failover
retries" Value="1"/>
<ServerProperty Key="InstanceSelector" Description="Specify an
implementation class for instance selection"
Value="com.emc.documentum.cts.lb.workers.OccupancyBasedSelector"/>
<ServerProperty Key="CTSOccupancyPollingInterval" Description="Specify
occupancy polling interval in seconds" Value="7"/>
<ServerProperty Key="ConnectionRetries" Description="Specify connection

retries (in case Repositories section is not configured )" Value="10"/>

<ServerProperty Key="AvailabilityRetries" Description="Number of retries
when CTS instances are not available" Value="2"/>
<ServerProperty Key="AvailabilityWait" Description="Number of seconds to
wait for rechecking availability" Value="4"/>

<LoadBalancer type="local" URL="" sendMode=""/>


<Repositories>
<AekFilePath>C:/ctsws_config/aek.key</AekFilePath>
<LoginContext DocbaseName="lrx64">
<ServerProperty Key="domain" Value=""/>
<ServerProperty Key="userName" Value="Administrator"/>
<ServerProperty Key="passwordFile"
Value="C:/ctsws_config/pfile/mspassword.txt"/>
<ServerProperty Key="maxConnectionRetries" Value="10"/>
<! -- A new boolean property useAdminSession is introduced to get the admin
session. By default, this configuration is not available, so the logged in
user session is used. If you have to generate real-time renditions for a
end user with, say READ permissions, setting this property to true
generates the renditions and the end user will be able to view the document./>
<ServerProperty Key="useAdminSession" Value="true" />
</LoginContext>
</Repositories>
</PropertyList>
</ServiceConfiguration>
3. To access username and password from the deployed CTS instance, perform the
following steps:
<AekFilePath>C:/ctsws_config/aek.key</AekFilePath>
<LoginContext DocbaseName="lrx64">
<ServerProperty Key="domain" Value=""/>
<ServerProperty Key="userName" Value="Administrator"/>
<ServerProperty Key="passwordFile"
Value="C:/ctsws_config/pfile/mspassword.txt"/>
<ServerProperty Key="maxConnectionRetries" Value="10"/>
a. Login to the CTS host server.
b. Navigate to <CTS>\config\SessionService.xml. This file contains the

required username and password file information.
c. Copy the password file and corresponding username to the preferences.xml
file of xCP host.
d. If there are multiple repositories, configure multiple <Repositories> tags in

preferences.xml.
For more information about SessionService.xml file, refer to the OpenText

Documentum Content Transformation Services Installation Guide.
4. Open a text editor and create a transformation.properties file with the following
content and save it in your classpath (in the same location as the dfc.properties
file in the application server). Values that you need to verify and update are
given in bold.
#cts ws preferences config location
CTSWSConfig=C:/ctsws_config/preferences.xml

3.10. Using Dedicated CTS Instances for Real-time Requests
5. To enable CTS request logging, open the log4j2.properties file of the xCP
application and add the following lines. Values that you need to verify and
update are given in bold.
Example 3-1:
appender.A1.type = RollingFile
appender.A1.name = CLIENT_APPENDER
appender.A1.fileName = C:/ctsws_config/client_log.log
appender.A1.filePattern = C:/ctsws_config/client_log-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
appender.A1.layout.type = PatternLayout
appender.A1.layout.pattern = %d{ISO8601_OFFSET_DATE_TIME_HHMM} %l [%t] %-5level
%logger{36} - %msg%n
appender.A1.policies.type = Policies
appender.A1.policies.time.type = TimeBasedTriggeringPolicy
appender.A1.policies.time.interval = 1
appender.A1.policies.time.modulate = true
appender.A1.policies.size.type = SizeBasedTriggeringPolicy
appender.A1.policies.size.size=100MB
appender.A1.strategy.type = DefaultRolloverStrategy
appender.A1.strategy.max = 5
logger.L1.name = com.emc.documentum.cts.lb
logger.L1.level = trace
logger.L1.additivity = false
logger.L1.appenderRef.A1.ref = CLIENT_APPENDER
logger.L2.name = com.emc.documentum.cts.common
logger.L3.name = com.documentum.services.cts.impl.transform
If the system cannot find the transformation.properties or preferences.xml file, an

error message is recorded in the log file specified in the log4j2.properties file.
3.10 Using Dedicated CTS Instances for Real-time

Requests
It is recommended you create multiple CTS instances to process real-time requests.
1. In each of the application servers where the xCP application is deployed, open
the preferences.xml file in a text editor.
2. Navigate to the following line:

<ServerProperty Key="AvailabilityWait" Description=
"Number of seconds to wait for rechecking availability" Value="4"/>
and succeed it with the following line:

<ServerProperty Key="CTS_SkipList" Description="list of cts instances
(semicolon separated) to skip (scalability)" Value="CTS-1;CTS-2"/>

Replace CTS-1 and CTS-2 with the names of CTS instances dedicated to realtime
processing.
3. Save the file.
5. Navigate to the <%CTS_install_folder%>/config folder and open

CTSServerService.xml for editing.
6. To ensure that the dedicated real-time CTS instance does not process
asynchronous requests, edit the following attributes in the
CTSServerService.xml file as follows:
<QueueProcessorContext DocbaseName="xcprepo">
<CTSServer AttributeName="queueItemName"
AttributeValue="dm_mediaserver"/>
to
AttributeValue="dm_mediaserver_temp"/>
and
AttributeValue="dm_autorender_win31"/>
to
AttributeValue="dm_autorender_win31_temp"/>
Documentum Content Transformation Services Transformation Suite Administration

Guide. provides information about the CTSServerService.xml file.
3.11 Validating if CTS is set up Correctly

1. To validate whether you have configured Content Transformation Services
(CTS) correctly to receive real-time requests, import a large file (for example,
DOCX or PDF) to the repository.
2. See if you can view the content using the xCP Viewer.
3. If content is not consistently available, verify the connectivity to the CTS Server:
a. Log in to Documentum Administrator.

provides additional information.
b. Select Tools > Dql Editor.
c. On the Dql - Enter Query page, type the following command in the text
box:
select websrv_url from cts_instance_info

3.11. Validating if CTS is set up Correctly
The websvr_url is in the following format:

http://<CTS_HOSTNAME>:<PORT>/cts/
d. Click Execute.
e. Copy the CTS machine hostname and ping it from the machine (or
machines) hosting the xCP Viewer application.
f. If you do not get a response, update the hosts file on this machine with the
CTS hostname and IP address.
g. Ping the CTS machine hostname again.
4. If content is still not consistently available, check the CTS log files at the path
specified in the log4j2.properties file of the xCP application. “Configuring xCP
to Interact with CTS” on page 167 provides information on how to enable CTS
request logging.
a. Search for errors related to transformation.properties or preferences.xml.

These files are required to send a real-time request to the CTS Server.
b. If there are any errors, verify that the paths listed in these files are
accessible.
5. Verify that CTS is set up to use Accelerated Content Services (ACS) as the
method of content transfer. The OpenText Documentum Content Transformation
Services Administration Guide provides instructions to configure CTS for Branch
Office Caching Services (BOCS) and ACS.
6. If you have issues with an ACS download, verify the connectivity to ACS:
a. On the Dql - Enter Query page in Documentum Administrator, type the

following command in the text box:
select acs_base_url from dm_acs_config
b. Click Execute.
c. Copy the acs_base_url value and see if you can access it from the CTS
machine.
d. If the URL is not accessible, add the hostname and IP address of the ACS
machine to the hosts file on the CTS machine.

3.12 Enabling the Privileged DFC Client

Prerequisites:
• You must enable the application server on which you installed the xCP
application as a privileged DFC client.
• Note the host name and port on which you deployed the xCP application.
After you have deployed the xCP application, the system automatically enables the
privileged DFC client. However, for any reason if it does not happen, you must
follow this procedure.
To alleviate the privilege to DFC client used by the application server host, perform
1. Run a browser and type the URL to enable the privileged DFC client as follows:
<protocol>://<host>:<port>/<app-name>/privilige-client
// where <protocol> stands for http or https protocol
Note: To add a privileged DFC client, you must log in with superuser
credentials.
2. Enter superuser name and superuser password credentials.
3. Click Grant Privilege.
Note: On successful access, the system grants the privilege to the super
user. Otherwise, the system throws an error to enter the super user
credentials correctly.
When any xCP application relies upon Collaboration services, it is must that the
application must run in a privileged DFC client mode. You must register the client
as a privileged client through DA. The default client name is as follows:
dfc_<host>_XXXXXXXXXwhere, <host> is the host name or IP address of the
AppHost machine where xCP application is deployed.
You can also add the dfc.name property in the dfc.properties file on the AppHost
machine as follows: dfc.name = xcpAppFor this case, the client name becomes
xcpApp_<host>_XXXXXXXXX.
Navigate to Administration > Client Rights Management > Privileged Clients in

DA. Search for the client and then add the same to the selected list. Right-click on the
client and select Approve Privilege.

3.13. Enabling CTS to interact with supported viewers
3.13 Enabling CTS to interact with supported viewers

1. Install the latest version of Documentum Content Transformation Services
(CTS).
2. On the CTS machine, browse the CTS profile, CTSProfileService.xml file located
at %CTS%\config location.
3. Edit the file by modifying the <ForClients> element in the file:

<!DOCTYPE CTSConfig SYSTEM "C:\Documentum\CTS\config\CTSConfig.dtd"[

<!ELEMENT ProfileManagerContext (CTSServerProfile*,ForClients?)>
<!ATTLIST ProfileManagerContext
DocbaseName CDATA #REQUIRED
ProcessExternally (true | false) "false"
>
<!ELEMENT CTSServerProfile (#PCDATA)>
<!ATTLIST CTSServerProfile
CTSProfileName CDATA #REQUIRED
CTSProfileValue CDATA #REQUIRED
>
<!ELEMENT ProfileConfig (#PCDATA)>
<!ATTLIST ProfileConfig
ProfileConfigName CDATA #REQUIRED
ProfileConfigValue CDATA #REQUIRED
>
<!ELEMENT ForClients (#PCDATA)>
]>
<CTSConfig>
<CTSConfigHeader ID="CTSProfileService">
<TYPE>THREE_ZERO_CORE_SERVICE</TYPE>
<SUBTYPE>CTSSERVERPROFILE</SUBTYPE>
<CLASSNAME>com.documentum.cts.impl.services.CTSProfileServiceImpl
</CLASSNAME>
<DESCRIPTION/>
<ACTIVATION>FIRSTUSE</ACTIVATION>
</CTSConfigHeader>
<CTSHandlerList>
<CTSHandler ID="CTSProfileHandlerImpl" DEFAULT="1"
CLASSNAME="com.documentum.cts.impl.services.ctsprofile.
CTSProfileHandlerImpl">
<CTSCustomConfig>
<ProfileConfig ProfileConfigName="profileRefreshInterval"
ProfileConfigValue="5"/>
<ProfileConfig ProfileConfigName="cacheCapabilityOnStartup"
ProfileConfigValue="true"/>
<ProfileManagerContext DocbaseName="winsqlcs72">
<CTSServerProfile CTSProfileValue="C:\Documentum\CTS
\\docbases\\winsqlcs72\\config
\\profiles\
\lightWeightProfiles"
CTSProfileName="lightWeightProfile"/>
\\docbases\\winsqlcs72\\config
\\profiles\
\lightWeightSystemProfiles"
CTSProfileName="lightWeightSystemProfile"/>
\\docbases\\winsqlcs72
\\config\\profiles\
\heavyWeightProfiles"

CTSProfileName="heavyWeightProfile"/>
<CTSServerProfile CTSProfileValue="/System/Media Server/Profiles"
CTSProfileName="lightWeightProfileFolder"/>
<CTSServerProfile CTSProfileValue="/System/Media Server/
System Profiles"
CTSProfileName="lightWeightSystemProfileFolder"/>
<CTSServerProfile CTSProfileValue="/System/Media Server/
Command Line Files"

CTSProfileName="heavyWeightProfileFolder"/>
<CTSServerProfile CTSProfileValue="C:\Documentum\CTS\
docbases
\winsqlcs72\config\temp_profiles"
CTSProfileName="tempFileDir"/>
<CTSServerProfile CTSProfileValue="ProfileSchema.dtd"
CTSProfileName="lwProfileDTD"/>
<CTSServerProfile CTSProfileValue="MP_PROPERTIES.dtd"
CTSProfileName="hwProfileDTD"/>
<ForClients>XCP_ADV</ForClients>
</ProfileManagerContext>
</CTSCustomConfig>
</CTSHandler>
</CTSHandlerList>
</CTSConfig>
Note: By default, the xcp profile (XCP) is mentioned in the <ForClients>

element. You can change the value to xcp_advanced profiling (XCP_ADV)
as per your requirements. Also, you cannot add both of these profiles
concurrently in the CTSProfileService.xmlfile.
4. Based on your requirements, you can select either of the profiles—XCP_ADV or

XCP.
Here is a snapshot of the profiles and expected behavior with these supported
viewers:
Profile Action Renditions Generated

XCP_ADV Content imported • PDF
• JPEG Story (for
thumbnails)
• Search Info XML
Content viewed in Content JPEG low resolution
Viewer
Content viewed in No new renditions are
Advanced Viewer generated.
XCP Content imported • JPEG low resolution
• JPEG Story (for
thumbnails)
• Search Info XML
Content viewed in Content No new renditions are
Viewer generated.

3.14. Integrating the GHS into xCP
Profile Action Renditions Generated

Content viewed in PDF
Advanced Viewer
5. Save the changes and restart CTS.
3.14 Integrating the GHS into xCP

Global Help Server (GHS) with xCP Designer is now available by default. All the
help information is retrieved from the help server. You need to ensure that Internet
connectivity to access help information from GHS.
3.15 Integrating the PHS into xCP

You can install PHS into Tomcat server using three different methods:
• Using the Installer file

• Using the Silent mode
• Using the Command line
See PHS - Administration Guide for detailed steps on private help installation on your
system. PHS is useful for environments with no or limited access to Internet
connectivity. To integrate private help server into xCP complete the following steps:
1. Install and configure OpenJDK version 11.0.14 on the server.
2. Set up a server in your environment for deploying the help system.
3. Setup the private help server (PHS) on the server. See Installing the OpenText
Private Help Server section in PHS - Administration guide. Save the PHS root URL
(http://<host-name>:<port-number>) for future reference.
4. Test the PHS configuration on the help server. See Testing a Private Help Server
installation section in PHS - Administration guide.
5. Deploy the xCP help files to the server as described in the Adding product online
help to the Private Help section in PHS - Administration guide.
Note: Use the docId for To deploy Opentext Help text field. For example,
docId for xCP Deployment guide 22.2 release is EDCPKL220200-IGD.
6. Update the xcpdesigner.ini file with the PHS root URL noted earlier. For
example:
-Doffline.help.server.url=http://host_ip:port
where http://host_ip:port is the PHS root URL.

For detailed information about setting up PHS, see PHS - Administration guide.

Chapter 4
Deploying and Configuring xCP Designer and
Runtime Language Files
4.1 Deploying xCP Designer Language Packs

The following procedures describe how to download and deploy language packs for
xCP Designer.
1. Download the xCPDesigner_<version>.zip file from the OpenText

MySupport (https://support.opentext.com). Extract the contents of the
xCPDesigner_<version>.zip file to a folder in any directory.
2. Download one or more language pack ZIP files from the OpenText MySupport
(https://support.opentext.com). Extract the contents of each language pack ZIP
file to the same folder as in Step 1.
3. Do one of the following:
• If xCP Designer is installed on a localized operating system, double-click

xcpdesigner.exe in the xCPDesigner folder to launch the localized xCP
Designer.
• If xCP Designer is not installed on a localized operating system, in the
command prompt window, change the current working directory to the
directory where you extracted the contents of the xCP Designer ZIP file.
a. Type
cd xCPDesigner
to point to the folder that has the executable file for xCP Designer.
b. Type
xcpdesigner -nl <lang>
to launch the localized xCP Designer, where <lang> is the abbreviation of
the language pack.
For example, the command xcpdesigner -nl zh launches a localized xCP
Designer which in this case is in the Chinese language interface.
The display language for xCP Designer depends on the regional setting of
the operating system. Launching xCP Designer using the command option
overrides the regional setting and displays xCP Designer in the language
you specify in the command.
For example, if you install a French language pack in an operating system
with English as the base language but with the French regional setting,
double-click xcpdesigner.exe to launch xCP Designer in French. However, if

Chapter 4 Deploying and Configuring xCP Designer and Runtime Language Files
you want to run xCP Designer in English, launch it using the command
xcpdesigner -nl en from the command prompt window.
4.2 Running an xCP Application in Different

Languages
These procedures describe how to run an xCP application in a language other than
the default language. The xCP Release Notes contain a list languages for which
OpenText provides runtime out-of-the-box user interfaces. Running an xCP
application in different languages includes the following:
• Deploying xCP runtime library language files. “Deploying xCP Runtime Library
Language Files” on page 178 provides details.
• Localizing xCP runtime language files for an xCP application. This includes the
following:
– Localizing xCP runtime application labels. “Localizing xCP Runtime

Application Labels” on page 179 provides details.
– Localizing validation messages in an xCP application. “Localizing Validation
Messages in an xCP Application” on page 180 provides details.
4.2.1 Deploying xCP Runtime Library Language Files

There are 2 ways to deploy the xCP runtime library language files:
Method 1: Follow these steps in xCP Designer:
1. Extract the contents of the xCP_Runtime_Localized<_<version>>.zip file to

Applications\<application_name>\<application_name>\src\main\webapp
\WEB-INF\lib location where xCP Designer is installed.
2. Copy <\webapps\<application_name>\locales\application.properties> file from the

application and save it as application_<lang>.properties using UTF-8.
3. Translate all labels contained in the <application_<lang>.properties> file.
4. Copy the application_<lang>.properties file to the Applications
\<application_name>\<application_name>\src\main\webapp\locales folder in
xCP Designer.
5. If there are any validation messages to translate, follow the same procedure with
the \webapps\<application_name>\WEB-INF\classes
\<namespace>_Nls_<lang>.properties file, and save it as
<namespace>_Nls_<lang>.properties using UTF-8.
6. Copy the <<namespace>_Nls_<lang>.properties>file at Applications
\<application_name>\<application_name>\src\main\webapp\WEB-INF\
classes in xCP Designer.
7. For custom messages, refer to the Localizing Custom Messages in an xCP

Application section.

4.2. Running an xCP Application in Different Languages
You must add the runtime library to the application using the Add Library option.
The xCP Designer Help describes the steps to perform this task.
Method 2: After you deploy the xCP application, do the following:
2. Extract the contents of xCP_Runtime_Localized_<version>.zip file to

\webapps\<application_name>\WEB-INF folder.
4. Clear the browser cache and restart the browser or open a new tab.
Note: Ensure that you follow the Method 2 instructions after every
deployment of xCP application.
The language of the runtime user interface is based on the language selected in
the sign in page or in the user settings page.
4.2.2 Localizing xCP Runtime Application Labels

When you deploy an xCP application, the system extracts and copies all the labels
provided while creating the application and other out-of-the-box labels to \webapps
\<application_name>\locales\application.properties file. Regardless of the
locale in which you create the application, the system generates the application.
properties file without any locale added to the filename.
For example, if you create an application using the German version of the xCP
Designer, the system generates the application.properties file with out-of-the-
box German labels and other labels available in the system.
1. Copy the \webapps\<application_name>\locales\application.

properties file and rename the copy as application_<lang>.properties,
where <lang> is the abbreviation of the new language that you want to add.
For example, to add a French locale file of the application.properties file, create
a copy of the application.properties file, rename it as application_fr.properties
and translate all the labels within that file.
You can identify the locale information by the suffix _xx_YY in the filenames,
where xx is the language code and YY is the country or region code. The http://
www.ISO.org site provides the language codes and country/region codes for
your reference.
2. Save the file to the same location. If the labels include non-ASCII characters,
save the file using UTF-8 encoding.

4.2.3 Localizing Validation Messages in an xCP Application

The validation messages and other out-of-the-box validation messages for xCP
objects are externalized in \webapps\<application_name>\WEB-INF\classes
\<namespace>_Nls_<lang>.properties file. The system localizes out-of-the-box
validation messages by default on the basis of the xCP Designer locale and the
availability of the xCP Designer language pack in the locale.
To localize validation messages in the desired language:
1. Copy the \webapps\<application_name>\WEB-INF\classes

\<namespace>_Nls.properties file and rename the copy as
<namespace>_Nls_<lang>.properties, where <namespace> is the namespace
of your application and <lang> is the abbreviation of the language.
For example, to add a French locale file of the <namespace>_Nls.properties
file, create a copy of the <namespace>_Nls.properties file, rename it as
<namespace>_Nls_fr.properties and translate the validation messages
within that file.
2. Save the file. If the labels include non-ASCII characters, save the file using
UTF-8 encoding.
4.2.4 Localizing Custom Messages in an xCP Application

To localize custom messages, firstly create a localization library. The library contains
these artifacts:
• JavaScript file: Defines the localized messages, for example, CustomMessages.js.

• Configuration XML file: Loads the JavaScript file.
• Library Manifest file: Defines the library.
The structure of the localization library appears as follows:
1. To create a localization library, perform the steps of creating these files as

follows:

4.2. Running an xCP Application in Different Languages
• Create a JavaScript file: The JavaScript content file contains a function

definition along with the required namespace definition. The sample
JavaScript file is as follows:
Java Script File ( CustomMessages.js)
Ext.namespace("rest.customMessages");
Ext.apply(rest.customMessages, {
successMessage : 'success Message localized',
errorMessage : 'error message localized'});
• Configure XML file: Contains library definition XML file. The sample
configuration XML file is as follows:
<library xmlns="http://documentum.emc.com/2010/UI-Model"
id="xcp_custom_message" version="1.0.0000.001">
<name>xcp_custom_message</name>
<description>Supports application custom messages</description>
<content src="content/xcp/customMessages/CustomMessages.js" type="text/
javascript" mode="runtime"/>
</library>
• Create a Library Manifest file: Create the manifest file and store it at the
META-INF/MANIFEST.MF path. This file is case sensitive by default.
Manifest-Version: 1.0
Ant-Version: Apache Ant 1.9.2
Component-Bundle: customMessages
Require-Bundle: rest.xcpcore, xcpcomm.xcpcommons, xcpui.xcpui
Built-Time: 2016-12-03_11:25:09
Built-By: xxx
Bundle-Version: 1.0
EMC-XCP-ExecutionEnvironment: com.emc.executionenvironment.xcp:22.2
Bundle-Name: customMessages
Created-By: yyy
Bundle-SymbolicName: customMessages
Version: 1.0
NAMESPACE: ctml
<blank line>
2. Run the command to build the localization library:

jar -cvfm customMessages.jar <Path to MANIFEST.MF> <Path to the root directory>
3. Navigate to the created library on your file system and import it using xCP
Designer.
4. After you have imported the library, populate the localized custom messages
(success or error) using an expression editor:
getJavascriptPropertyValue ('rest.customMessages.successMessage')
5. To support multiple locales, create a JavaScript file that contains definitions of

multiple locales as follows:
Ext.namespace("rest.customMessages");
Ext.apply(rest.customMessages.en_US, {
successMessage : 'success Message localized',
errorMessage : 'error message localized'});
Ext.namespace("rest.customMessages.fr_FR");
Ext.apply(rest.customMessages.fr_FR, {
successMessage : 'success Message localized in french',
errorMessage : 'error message localized in french'});

6. After you have imported the library for multiple locales, use the expression
editor to pick up the message depending on the end-user locale:
getJavascriptPropertyValue('rest.customMessages.'+getUserLocale()
+'.successMessage')
4.3 Adding and Configuring new Language Files for

new Locale Support for Runtime
This section describes how to add additional language files to runtime and configure
it to run an application in different locales. The current version of xCP supports
Arabic content and metadata with right-to-left support. To display runtime user
interface in a specific language, localize the following components:
• Runtime library language files. “Localizing xCP Runtime Library Language

Files” on page 182 provides details.
• xCP runtime application labels. “Localizing xCP Runtime Application Labels”
on page 179 provides details.
• Validation messages in an xCP runtime application. “Localizing Validation
Messages in an xCP Application” on page 180 provides details.
• Third-party products such as Ext JS and CK Editor. “Localization of Third-party
Products” on page 183 provides details.
4.3.1 Localizing xCP Runtime Library Language Files

Runtime library language files include widget library strings and service layer
strings and OpenText provides out-of-the-box translations for the supported
languages in the xCP_Runtime_Localized_<version>.zip file.
1. Download xCP_Runtime_LocalizableSourceFiles_<version>.zip to your

local drive.
2. Extract the JAR file contents. There are JAR files in English locale composed of
user interface source files which you can use for translation.
3. Identify the .js files that you want to localize.
4. Translate the strings in .js files using the following guidelines:
a. In .js files, translate only the string values. Strings are the text that show in
the user interface. For example, in the following extract from a .js file,
translate only the text that is shown in bold font.
* Copyright (c) 2010-2021. OpenText. All Rights Reserved.

*/
// UpdateAction-strings.js
Ext.namespace("rest.Strings.action.form.UpdateAction");
Ext.apply(rest.Strings.action.form.UpdateAction, {
confirmationTitle: "Update Item?",

4.3. Adding and Configuring new Language Files for new Locale Support for Runtime
confirmationPromptTemplate: "Are you sure you want to update this item?",

updateSuccessNotificationTemplate: "The item has been updated.",
updateErrorTemplate: "An error occurred while updating this item."
});
b. For .js files:
• If the languages contain non-ASCII characters, save the .js files using
UTF-8 encoding.
• Do not use double quotes in the translation.
• Double quotes are reserved to mark the beginning and end of the strings.
If you want to use double quotes for translation, escape the double
quotes.
• Standard escape characters are allowed. For example, use \n for a new
line and \t for a tab. All the content must be in a single line and not
broken.
5. Rename the folder in each JAR and the JAR name with the same locale code
used for renaming properties files.
For example, if you want to use Finnish language, rename the folder path \
\xcp-core\locales\content\en\xcp to \\xcp-core\locales\content\fi\
xcp and the JAR file xcp-core_en.jar as xcp-core_fi.jar.
6. Copy the JAR files to \webapps\<application_name>\WEB-INF\lib folder.
4.3.2 Localization of Third-party Products

xCP Designer includes third-party files and the localized language sets for these
third-party products may vary. For example, all the supported third-party products
are localized into Russian, however for Arabic, only CK Editor is localized. For
details about current localization status and adding additional language files for
these third-party products, contact the respective product vendors.
• Ext JS: These files are found in the xCPDesigner_<version>.zip file. The files to
localize are packaged in xcp-appjs-<version>.jar file. For details about
localizing Ext JS for additional languages, contact Sencha Inc.
• CK Editor: These files are found in WEB-INF\lib\xcp-core-2.2.xxxx.yyyy.
jar file of the deployed web application. For details about localizing CK Editor
for additional languages, contact CK Source.

4.3.3 Configuring for a New Locale

To load new locale resource files during runtime, add the locale as a supported
locale in applicationContext-ui-app.xml file.
1. Edit the ..\WEB-INF\classes\com\emc\xcp\config\app\

applicationContext-ui-app.xml file and save your changes.
For example, to add a new variant of Chinese, add a line with the value zh_SG
to the file as shown in the following example:
<property name="supportedLocales">
<set>
...
<value>zh_SG</value>
...
</set>
</property>
2. Save your changes and restart the application server.
3. Clear the browser cache and restart the browser or open a new tab. The
language of the runtime user interface is based on the language selected in the
sign in page or in the user settings page.
4.3.4 Forcing Locale Fallback

To force a locale to fall back to another locale:
1. Edit the ..\WEB-INF\classes\com\emc\xcp\config\app\

applicationContext-ui-app.xml file.
For example, to make a variant of Chinese zh_TW (Traditional Chinese) fall
back to English rather than to zh or zh_CN (Simplified Chinese), add a line with
the value zh_TW and the fall back locale value “en” to the file as shown:
<property name="fallbackLocale">
<map>
<entry key="zh_TW" value="en"/>
</map>
</property>
2. Save your changes and restart the application server.
3. Clear the browser cache and restart the browser or open a new tab. The
language of the runtime user interface is based on the language selected in the
sign in page or in the user settings page.

4.4. Locale Loading Method
4.4 Locale Loading Method

This section provides details about language loading behaviors for different types of
components used for an xCP application. When locale is passed from language
selection in sign in page or in the user settings page, the locale loading method goes
through two phases:
• Resolve Locale: Get the locale to use on the basis of the configuration in the
applicationcontext-ui-app.xml.
• Load Language File: The system loads the properties file in the file system.
In the Resolve Locale phase, the system uses the following logical sequence:
If locale xx_YY or xx passed from browser is defined in the fallbackLocale property

in the applicationcontext-ui-app.xml, resolve to fallbackLocale property value.
Else if locale xx_YY or xx passed from browser is defined in the supportedLocales

property in the applicationcontext-ui-app.xml, resolve that locale as xx_YY or xx.
Else if locale xx_YY passed from browser is not defined in the supportedLocales
property in the applicationcontext-ui-app.xml, but if xx is defined as supported,
resolve locale as xx.
Else resolve locale as defined in the defaultLocale property in applicationcontext-ui-

app.xml.
When configuring locales, ensure that:
• The locale value you configure in the fallback locale section exists in the
supported locale section.
• The locale you configure in the default locale section exists in the supported
locale section.
• Localize the application label files, runtime libraries, and validation messages
into locales that you set as fallback locale or default locale in the
applicationcontext-ui-app.xml file.
In Load Language File phase, there are three different types of behavior on the basis
of the layers in the stack.
The following table lists the behavior:

Component Behavior
Labels in Application.properties, component If localized files for locale xx_YY exists
library files packaged in runtime library, and
third-party user interface Load xx_YY
Else if localized files for locale xx exists
Load xx
Else
Load the files with no language extension.

For example, Application.properties and
xcp-core.jar files.
Services layer out-of-the-box message If localized file for locale xx_YY exists
packaged in runtime library
Load xx_YY locale file
Else if localized file for locale xx exists
Load xx locale file
Else if localized file for application server’s

JVM locale yy_YY or yy exists
Load yy_YY or yy locale file
Else
Load the file in class path with no language

extension:
xcp-rest-core-config.jar
Validation message loaded by aspect Even if resolved locale is xx_YY, the system
always loads xx locale files.
If localized files for locale xx exists
Load xx
Else if localized files for application server’s

JVM locale yy_YY or yy exists
Load yy locale file
Else
Load the files with no language extension.

For example, <namespace>_Nls.properties.
Ensure that default locale you configure in applicationcontext-ui-app.xml and xCP

application host JVM locale are the same. To modify the default JVM locale, pass
command-line arguments to the JVM. For example, to change the locale to en_US,
pass the arguments into the tcserver\apphost\conf\wrapper.conf file as follows:

4.5. Modifying Runtime Library Language Files

…
wrapper.java.additional.10="-Dbam.properties=C:\tcServer\apphost\bam\
bam.properties"
wrapper.java.additional.11="-XX:MaxPermSize=512m"
wrapper.java.additional.12="-Duser.country=US"
wrapper.java.additional.13=”-Duser.language=en"
Regardless of the application server OS locale, using these settings the locale always
falls back to en_US, before trying to get the filename.properties without any
language code for services layer and validation messages.
4.5 Modifying Runtime Library Language Files

xCP runtime out-of-the-box user interface includes service layer strings and widget
bundle strings. It is localized into the following languages: French, German, Italian,
Spanish, Swedish, Brazilian Portuguese, Dutch, Russian, Japanese, Simplified
Chinese, Korean, and Arabic. While French, German, Italian, Spanish, Japanese, and
Simplified Chinese are fully tested, Arabic, Dutch, Swedish and Russian language
files are added without a linguistic verification process.
If you want to change out-of-the-box translation, perform the following:
1. Open the downloaded xCP_Runtime_Localized_<version>.zip, and look for

the applicable language JAR files.
For example, the Dutch language JAR file name uses the suffix _nl.jar.
2. Extract the contents of the JAR file to a temporary location. You can find all
localized strings in .properties files or in .js files.
For .properties files:
• ASCII is the format of all .properties files for all languages. For encoding the
content of .properties file, use the ISO 8859-1 character encoding (also
known as Latin-1). All non-Latin-1 characters, such as Japanese, Korean,
Simplified Chinese, Arabic, and Russian characters, must be entered using
Unicode escape characters.
• When you use a single quote and curly braces in the same segment, always
precede each single quote using another single quote.
For example, replace the text Création de l’armoire ”{0}” effectuée
with Création de l”armoire ”{0}” effectuée.
• Standard escape characters are allowed.
For example, use \n for a new line and \t for a tab.
• All the content must be in a single line and not broken.
For .js files:
• If the languages contain non-ASCII characters, save the .js files using UTF-8
encoding.

• Do not use double quotes in the translation. Double quotes are reserved to
mark the beginning and end of the strings. If you want to use double quotes
for translation, escape the double quotes.
• Standard escape characters are allowed.
For example, use \n for a new line and \t for a tab.
• All the content must be in a single line and not broken.
3. Search for the string you want to edit.
4. After editing, save the file.
5. Repackage the affected JAR file while keeping its original structure.
7. Copy the JAR file you want to update and place it in \webapps\<application_
name>\WEB-INF\lib folder on the application server.
4.6 Running an xCP Application in Different

Languages in Preview Mode
Using preview mode, you can preview the application in a browser during design
time. This feature replaces the need of end-to-end deployment to view the design
changes in an application, which saves time and resources.
To view the Preview mode in a localized user interface, there are 2 ways to add the
localized runtime library JAR files:
Method 1
You must add the runtime library to the application using the Add Library option.
The xCP Designer Help describes the steps to perform this task.
Method 2:
To view the Preview mode in a localized user interface, perform the following steps:
1. Create a lib folder in <xCP Designer Home>\Applications\<App Name> \<App

Name>\target\m2e-webby\war\WEB-INF.
2. Extract the JAR file contents of the xCP_Runtime_Localized_<version>.zip

file to the created lib folder.
3. Localize application.properties file available in the \webapps\<application

name>\locales folder.
4. Localize xCP_Nls.properties and other application Nls properties files in the

\webapps\<application_name>\WEB-INF\classes\ folder.

4.6. Running an xCP Application in Different Languages in Preview Mode
When you make changes in the xCP Designer that can trigger a clean build,
these files get deleted automatically. Then, you need to create these files again.
5. Save your changes.

Chapter 5
Uninstalling an Application
5.1 Manually Uninstalling Application Data

Applications cannot share namespaces in the same environment. When you finish
testing an application in a development environment, uninstall the application so
the namespace can be reused. If you move an application from one production
environment to another production environment, uninstall the application from the
original environment.
Uninstalling an application consists of the following high-level steps:
• Removing the web application archive (WAR) file

• Removing application data from the BAM database
• Removing application data from the Documentum repository
You do not have to uninstall data from components such as xPlore and Content
Intelligence Services (CIS). When you remove object instances from the
Documentum repository, the system automatically removes indexes from xPlore
and discovered metadata from CIS.
5.2 Undeploy the xCP Application

1. Stop the application server on which you deployed the xCP application.
The following example shows the path to a tc Server instance:
C:\tcserver\apphost
2. Navigate to the webapps folder and delete the application web application
archive (WAR) file and application folder.
The following example shows the path to a WAR file for an application named
Loan:
C:\tcserver\apphost\webapps\Loan.war
3. Start the application server.

Chapter 5 Uninstalling an Application
5.3 Removing Data from the BAM Database

1. Open a browser on the BAM host machine.
2. Type an undeploy action URL as shown in the following example:

http://<bam-server-machine-ip>:<port>/bam-server/admin?action=
undeploy&namespace=<application_namespace>
Note: You can retrieve the namespace of an application from Home >
Application Model > Properties view > General tab in xCP Designer.
The BAM_VERSION_REGISTERY table is not dropped when you undeploy an xCP

application.
5.4 Removing Data from the Repository

Removing data from the Documentum repository consists of retrieving a list of
artifact bundles in the application and then removing the following artifacts:
• Business objects, folders, and content objects

• Relations
• Java modules
• Java Services
• Processes and activities
• Groups
• Parameters and endpoints
• Permission sets
• Historical data
• Type fragment
When you remove data from the repository, you use the Documentum
Administrator DQL Editor and API Tester to run commands that retrieve and
remove the data. The OpenText Documentum Server Administration and Configuration
Guide contains more information on Documentum Administrator.

5.4. Removing Data from the Repository
5.4.1 Retrieving a List of Application Artifact Bundles

Use the Documentum Administrator DQL Editor to run the commands in this
procedure.
1. Retrieve a list of all instances of a deployed application by running the

following command:
Select r_object_id, r_modify_date from xcp_artifact_bundle (all)
where object_name='<$appname>' order by r_modify_date asc
where <$appname> is the name of the application.
The query returns a list of object IDs for each deployed instance of the
application. The most recently deployed instance is at the bottom of the list.
When you remove application data, you remove the data associated with each
instance.
2. Retrieve a list of bundle libraries for an application instance by running:

Select bundlelibrary from xcp_artifact_bundle where r_object_id='<
$bundleobjectid>'
where <$bundleobjectid> is an object ID for an instance of application or library
or project returned in step 1.
3. Repeat the command in step 2 for each library bundle for an instance until you
have retrieved the object IDs for all library bundles associated with the instance.
For example, after you run the command in step 2 with the object ID for an
application instance, the query returns library bundles 080004d180005e47 and
080004d180005e46. Run the command again using 080004d180005e47 as the
value for <$bundleobjectid> and then run the command again using
080004d180005e46 as the value for <$bundleobjectid>.
4. For a library bundle, retrieve the object IDs for the artifacts that have been
translated into repository objects.
Do not retrieve the IDs for bundles shared between applications, the xcpcore
bundle, and the xcpcommons bundle. Retrieve the IDs by running the following
command:
Select installedobjectid from xcp_artifact_bundle where r_object_
id='<$bundleobjectid>'
The remaining sections in this chapter explain how to delete data associated
with the object IDs that you retrieve in this step.
5. Repeat steps 2 through 4 for each application instance in the query results from
step 1. The resultant of this step provides object IDs for all bundle libraries.

5.4.2 Removing Application Data

5.4.2.1 Removing Business Object, Folder, and Content Data
Skip this procedure if the types are adopted types.
1. Run the following command from the Documentum Administrator DQL Editor
to retrieve a list of type names and object IDs:
Select r_object_id, name from dm_type where r_object_id in (select
installedobjectid from xcp_artifact_bundle where r_object_id='<
$bundleobjectid>')
2. Identify the hierarchy of types and then remove the types starting from sub
types to super types.
3. Run the following command from the Documentum Administrator API Tester
to delete objects from the repository:
query,c,delete <name_of_type> objects
to remove the type definition:
query,c,drop type <name_of_type>
5. Repeat steps 2 and 3 for all type names returned in step 1.
5.4.2.2 Removing Relation Data

to retrieve the application namespace:
Select namespace from xcp_artifact_bundle where r_object_id='<
$bundleobjectid>'
to retrieve the dm_relation_type object ID for the namespace:
Select r_object_id,relation_name from dm_relation_type where
relation_name like '<namespace>_%'
to remove the objects associated with the dm_relation_type:
destroy,c,<object_ID>
to retrieve the dm_type that corresponds to the relation:
Select r_object_id,name from dm_type where name like '%<namespace>_
%'
to delete dm_type objects from the repository:
query,c,delete <name_of_type> objects

query,c,drop type <name_of_type>
5.4.2.3 Removing Java Module and Java Service Data

to retrieve a list of dmc_module object names and object IDs:
Select r_object_id, object_name, r_folder_path from dmc_module where
r_object_id in (select installedobjectid from xcp_artifact_bundle
where r_object_id='<$bundleobjectid>')
to retrieve a list of dmc_jar objects for a dmc_module object:
Select r_object_id, object_name from dmc_jar(all) where FOLDER('/
System/Modules/<module_object_name>'
to unlink each dmc_jar object from the dmc_module object:
unlink,c,<<object_id>>,/System/Modules/<module_object_name>'
to remove each dmc_jar object from the repository:
destroy,c,<<object_id>>
5. Repeat steps 2 through 4 for each dmc_jar object.

to remove each dmc_module object from the repository:
destroy,c,<object_id of dmc_module>
5.4.2.4 Removing Process Data

to retrieve a list of processes:
Select r_object_id, object_name from dm_process where r_object_id in
(select installedobjectid from xcp_artifact_bundle where r_object_
id='<$bundleobjectid>')
to abort workflows for a process:
uninstall,c,<<process_id>>
to re-install the process with the option to abort halted workflows:
install,c,<<process_id>>,T,F
to retrieve a list of activities for the process:

Select r_act_def_id from dm_process where r_object_id='<process_

id>'
to uninstall the process from the repository:
uinstall,c,<process_id>
to invalidate the process:
invalidate,c,<process_id>
to remove the process from the repository:
destroy,c,<process_id>
to uninstall each activity:
uninstall,c,<act_id>
to invalidate each activity:
invalidate,c,<act_id>
to remove each activity:
destroy,c,<act_id>
11. Repeat steps 2 through 10 for each process returned in step 1.
12. Remove aborted workflows and orphaned structured data type (SDT) objects by
using Documentum Administrator to run a dm_DMClean job with the
following argument:
'-clean_aborted_wf TRUE' and '-clean_wf_template TRUE'
5.4.2.5 Removing Group Data

to retrieve a list of groups for application bundles:
Select r_object_id, group_name from dm_group where r_object_id in
to remove each group from the repository:
destroy,c,<group_id>
where <group_id> is the object ID for a group.

5.4.2.6 Removing Parameter and Endpoint Data

to retrieve the namespace of the application:
$bundleobjectid>'
to remove all objects related to the namespace:
query,c,delete dmc_xcp_app_config objects where
namespace='<namespace>'
5.4.2.7 Removing permission set data

to retrieve a list of dm_acl objects:
Select r_object_id, object_name from dm_acl where r_object_id in
to remove each dm_acl object:
destroy,c,<acl_id>
5.4.2.8 Removing Historical Data

to retrieve the namespace of the application:
$bundleobjectid>'
to remove message queue tables:
query,c,drop type dmc_mq_<namespace>_<applicationname>
The <applicationname> must be all lowercase with any underscores removed.
5.4.2.9 Removing Type Fragment Data

Skip this procedure for out-of-the-box Message Type Fragment.
to retrieve a list of dmc_aspect_type object names, object IDs and type definition
for Type Fragment:
select r_object_id, object_name,i_attr_def from dmc_aspect_type
where r_object_id in (select installedobjectid from xcp_artifact_
bundle where r_object_id=’$bundleobjectid’)

2. If the Type Fragment contains attributes, dm_type is created and i_attr_def

contains the type name. Run the following command from the Documentum
Administrator API Tester to delete dm_type created for Type Fragment from
the repository:
query,c,delete <i_attr_def> objects
query,c,drop type <i_attr_def>
to retrieve object id of defaultaspect.jar:
select r_object_id from dmc_jar where object_name='defaultaspect.
jar'
5. Run the following commands from the Documentum Administrator API Tester
to unlink defaultaspect.jar from the type fragment:
unlink,c,<object ID of defaultaspect.jar>,<object ID of dmc_aspect_
type> save,c,<object ID of defaultaspect.jar>
to remove each dmc_aspect_type object from the repository:
destroy,c,<object_id of dmc_aspect_type>
5.4.2.10 Removing Application Artifact Bundles

Remove application artifact bundles from the repository by running the following
command from the Documentum Administrator API Tester:
destroy,c,'$objectid'
Perform the “Removing Application Data” on page 194 procedure for each bundle
retrieved in step 1 and step 5 in “Retrieving a List of Application Artifact Bundles”
on page 193.

Chapter 6
Administering the xCP System
6.1 Tuning the Documentum Server Database

The following table contains performance recommendations for the Documentum
Server database:
Database Recommended settings

Oracle 11g • cursor_sharing=FORCE
• Turn auditing off. If you choose to keep
auditing on configure the system to write
database audit records to an operating
system with a large file.
• Use DM_NO_EXTRA_JOINS to eliminate
redundant join predicates. Redundant
join predicates can cause Oracle
optimizer to choose a sub-optimal
execution plan that results in poor
performance. The OpenText Documentum
Server Administration and Configuration
Guide provides more information on
optimization.
Microsoft SQL Server 2008 • Parameterization = forced
• Auto Create Statistics = false
• Auto Update Statistics = true
• Enable snapshot isolation
• If the host has more than 4 CPUs set
Maximum degree of parallelism to a
value less than 4.
• If you deploy Microsoft SQL Server on a
shared host, set maximum server
memory.

Chapter 6 Administering the xCP System
6.2 Updating Endpoint Values After Application

Deployment
You can update existing endpoint values in the repository anytime after an
application is deployed. To update an endpoint value on the Documentum Server,
use to:
• Retrieve the endpoint object ID for the endpoint from the repository
• Retrieve the metadata for the endpoint
• Set a new property value for the endpoint
• Save your changes

additional information.
1. Log in to Documentum Administrator.
2. Select Tools > Api Tester.
3. On the Api Tester page, select Single Line Command Entry.
4. In the Command field, type

retrieve,c,dmc_xcp_app_config where namespace='<namespace>' and
config_name='<endpoint-system-name>'
where <namespace> is the namespace of the application and <endpoint-system-
name> is the system name of the endpoint you want to update.
Due to PDF formatting constraints, this API command might not be valid if you
copy and paste it directly into the Command field. You can fix this issue by
replacing the single-quote characters with the simple single-quote (represented
by ASCII-39).
5. Leave the Data field blank and click Execute.

The system retrieves the endpoint object ID from the repository and displays it
in the Results text box as shown in the following example:
API>retrieve,c,dmc_xcp_app_config where namespace='ns1' and config_name='jms'
...
08001639800173a4

dump,c,<r_object_id>
where <r_object_id> is the endpoint object ID obtained from the previous
command.
7. Leave the Data field blank and click Execute.

The system lists the metadata for the endpoint object. The metadata includes
two repeating attributes, property_name and property_value, and an index

6.2. Updating Endpoint Values After Application Deployment
number associated with the attributes. The following table shows the
property_name (grouped by endpoint) and its label in the Endpoint Editor:
Endpoint/property_name Label in the Endpoint Editor

Database
DRIVER_CONFIG_PARAM JDBC Driver
DB_URL_CONFIG_PARAM Connection string
USERNAME_CONFIG_PARAM Username
PASSWORD_CONFIG_PARAM Password
Email
HOSTNAME Hostname
PORT_NUMBER Port number
USER_NAME Username
PASSWORD Password
USE_ENCRYPTION Encryption
EMAIL_SERVER_TYPE Protocol (if server connection is incoming
only)
FTP
FTP_SERVER_TYPE Protocol
FTP_HOST Hostname
FTP_PORT Port number
FTP_USER_NAME Username
FTP_PASSWORD Password
FTP_BASE_DIR Base folder path
SFTP_USE_PUBLIC_KEY_AUTHENTICA Authentication (Basic or Public key
TION authentication)
HTTP
URL Parameters URL
HTTP_USERNAME Username
HTTP_PASSWORD Password
JMS
JMS_INIT_CONTEXT_FACTORY_CONFI Context factory
G_PARAM
JMS_INIT_CONTEXT_PROVIDER_URL_ Provider URL
CONFIG_PARAM
JMS_INIT_CONTEXT_USERNAME_CON Username (Context factory)
FIG_PARAM

Endpoint/property_name Label in the Endpoint Editor

JMS_INIT_CONTEXT_PASSWORD_CON Password (Context factory)
FIG_PARAM
JMS_DESTINATION_ADDITIONAL_PRO Additional properties
PERTIES
JMS_DESTINATION_TYPE_CONFIG_PA Queue/Topic (Connection type)
RAM
JMS_CONNECTION_FACTORY_CONFI Connection factory
G_PARAM
JMS_DESTINATION_NAME_CONFIG_P Queue/Topic name
ARAM
JMS_DESTINATION_USERNAME_CONF Username (Connection factory)
IG_PARAM
JMS_DESTINATION_PASSWORD_CONF Password (Connection factory)
IG_PARAM
Repository
DOCBROKER_HOST Docbroker Hostname
DOCBROKER_PORT Docbroker Port
DOCBASE_CONFIG_PARAM Repository Name
USERNAME_CONFIG_PARAM Username
PASSWORD_CONFIG_PARAM Password
DOCBASE_DOMAIN Domain
Webservice
WSDL_URL_CONFIG_PARAM WSDL URL
AUTHENTICATION_USERNAME_CON Username
FIG_PARAM
AUTHENTICATION_PASSWORD_CONF Password
IG_PARAM
xPression
XPRESSION_SERVERURL xPression URL
USER_NAME Username
PASSWORD Password

set,c,<r_object_id>,property_value[<index>]
where <r_object_id> is the endpoint object ID and <index> is the index number of
the property_name and of the property_value you want to update.
9. In the Data field, type

6.2. Updating Endpoint Values After Application Deployment
<value>
where <value> is the new property_value you want to enter for the
property_name attribute.
For example, for the Queue/Topic name value for the JMS endpoint, the
corresponding property_name is
JMS_DESTINATION_NAME_CONFIG_PARAM at index number 8. If you
want to change the Queue/Topic name value, in the Command field type
set,c,08001639800173a4,property_value[8]
and type the new value in the Data field.
10. Click Execute.

In the Results text box, the system displays OK to indicate that it updated the
value.
11. After you finish updating the values for the endpoint object, in the Command
field, type
save,c,<r_object_id>
where <r_object_id> is the endpoint object ID for which you want to save the
updated value or values.
12. Clear the Data field and click Execute.
13. Click OK.
14. Log out of Document Administrator.
15. Restart the following:
a. Java Method Server

b. For tc Server, the application server instance where you deployed Process
Integrator. For Tomcat, the application server where you deployed Process
Integrator.
c. For tc Server, the application server instance where you deployed the xCP
application. For Tomcat, the application server where you deployed the xCP
application.

6.3 Enabling Priority Levels for System Activities in

Processes
By default, the system executes system activity tasks in a process based on the task
creation date. To prioritize system activities by priority levels instead of creation
date, enable priority levels for system activities on the Documentum Server. The
OpentText Documentum xCP Designer Help provides information on defining priority
levels in the process model.
To enable priority levels for system activities on the Documentum Server:

2. Select Tools > Api Tester.
3. On the Api Tester page, select Script (multi-line) Entry.
4. In the Commands text box, type the following Documentum Server internal
API script:
retrieve,c,dm_docbase_config
append,c,l,r_module_name
WF_PROCESS_PRIORITY_BASED
append,c,l,r_module_mode
1
save,c,l
5. Click Execute.
6. Click OK.
7. Log out of Documentum Administrator.
8. Restart the Documentum Server.
6.4 Modifying the Message Queue Strategy

Documentum Server message queues hold business event data generated by the
runtime application until another component, for example, the BAM server,
retrieves and processes the data. The BAM server runs a job that pipes the data from
the message queue to the BAM database.
The message queue strategy determines the number of message queues the system
creates. The strategy correlates with system performance. Generally, the more
message queues the system creates the better the BAM server performs. By default,
the system uses strategy ID 4.
The system adds a BAM pipe job to each message queue it creates. You must
monitor the amount of data in each message queue. If you have a back log of data
you can add pipe jobs to a message queue as a way to improve system performance.

6.4. Modifying the Message Queue Strategy
Use this procedure to change the message queue strategy of the system.
1. Log on to the machine with xCP Deployment Agent.
2. For Windows, open xda.bat located at <${xda-home}>\<bin>. For Linux, open

xda.sh located at <${xda-home}>\<bin>.
3. Append -Drest.mq.creation.strategy at the end of XDA_OPTS parameter to

specify how the system creates message queues as follows:
SET XDA_OPTS=-Xmx1024m -Dfile.encoding=UTF-8.log4j2.properties
-Drest.mq.creation.strategy=<ID>”
Use the following table to select a strategy ID:
Strategy ID The system creates a message queue

for each
1 Business event to which a historical query
subscribes
For example, if the historical query
subscribes to the Loan.created event and
the Collateral.relate event, the system
creates two queues in the repository.
2 Artifact
For example, if the historical query
subscribes to the Loan.created,
Loan.updated, and Collateral.relate
events, the system creates one queue for
the Loan business object and another
queue for the Collateral business object.
3 Artifact category
For example, the system creates one queue
for business objects, another queue for
documents, and a third queue for folders.
4 Namespace
The system creates one message queue for
each application. The system uses this
strategy by default.
4. Redeploy the xCP application.

6.5 Adding BAM server Pipe Jobs to a Message

Queue
The BAM server runs one pipe job for each message queue, taking data from the
queue and inserting it into the BAM database. You must monitor the amount of data
in each message queue. If you have a backlog of data you can add pipe jobs to a
message queue as a way to improve system performance.
1. Stop the BAM server.
2. To count the number of items in a message queue, execute the following

statement against the repository:
select count (*) from dmc_mq_<namespace>_<queue_name>
Where:
• <namespace> is the namespace that contains the queue

• <queue_name> is the name of the message queue
3. Determine the SEQ_ID of the pipe job you want to duplicate:
a. Execute the following statement against the repository to list the scheduled
pipe jobs.
SELECT SEQ_ID,NAME FROM BAM_S_JOBS WHERE SOURCE_TYPE=
'BUSINESS_EVENTS_PIPE';
A list of pipe jobs with names and IDs appears.

b. Locate the pipe job you want to duplicate and make note of the SEQ_ID
value.
4. If you are using a Microsoft SQL Server database, execute the following
command to create a pipe job:
INSERT INTO BAM_S_JOBS (NAME,LAST_RUN,SOURCE_TYPE,
STEP_SIZE,HIERARCHY,STATUS,STATUS_TIME,STATUS_DESCRIPTION,
THREAD_COUNT,TIMEOUT,SCHEDULER_PERIOD,SCHEDULER_GROUP_NAME,
APP_NAMESPACE) SELECT NAME,LAST_RUN,SOURCE_TYPE,STEP_SIZE,
HIERARCHY,STATUS,STATUS_TIME,STATUS_DESCRIPTION,THREAD_COUNT,
TIMEOUT,SCHEDULER_PERIOD,SCHEDULER_GROUP_NAME,APP_NAMESPACE
FROM BAM_S_JOBS WHERE SEQ_ID=<seq_id>;
Where <seq_id> is the SEQ_ID value of the pipe job you are replicating.
5. If you are using an Oracle database, execute the following statement to create a
pipe job:
INSERT INTO BAM_S_JOBS (SEQ_ID,NAME,LAST_RUN,SOURCE_TYPE,
THREAD_COUNT,TIMEOUT,SCHEDULER_PERIOD,SCHEDULER_GROUP_NAME,
APP_NAMESPACE) (select <new_seq_id>,NAME,LAST_RUN,SOURCE_TYPE,
THREAD_COUNT,TIMEOUT, SCHEDULER_PERIOD,SCHEDULER_GROUP_NAME,
APP_NAMESPACE from BAM_S_JOBS where SEQ_ID=<seq_id>);
Where:

6.6. Troubleshooting Queries with Debug Mode
• <new_seq_id> is a unique value given to the job you are creating

• <seq_id> is the SEQ_ID value of the pipe job you are replicating
6. Use a cron expression to schedule the pipe job so that all jobs do not run at the
same time.
The first statement schedules the SEQ_ID=4 job to run on the first and 32nd
second of each minute. The second statement schedules the SEQ_ID=5 job to run
on the second and 33rd second of each minute.
UPDATE BAM_S_JOBS SET SCHEDULER_PERIOD='1/31 * * ? * *' WHERE SEQ_ID=4;
UPDATE BAM_S_JOBS SET SCHEDULER_PERIOD='2/32 * * ? * *' WHERE SEQ_ID=5;
7. Restart the BAM server.
6.6 Troubleshooting Queries with Debug Mode

The debug mode for query data services can be activated at runtime by adding the
debug parameter in the URL calling the services. The debug information is useful to
troubleshoot issues such as performance issues. It allows you to check results,
execution events, and the query sent to the source.
1. Identify the query by performing one of the following:
• Use a web debug tool such as Firebug, Fiddler or any built-in developer tool
that traces the network communication.
• Search in the application server logs located at:
For tc Server: <application_server_home>/<server_instance>/logs/
localhost_access_log.<date>.txt
For Tomcat: <application_server_home>/logs/localhost_access_
log.<date>.txt
The query URL looks like:

http://<host>:8090/<application_name>/application/documents?
_dc=1335361466590&type=ft_doc&q=active&facet_authors=David%20Miller
&page=1&start=0&limit=10
Where document is the object model,

ft_doc is the system name of the query model,
q parameter is the full-text input,
and facet_authors parameter is the system name of the facet authors
2. Copy and paste the URL in the browser address bar and append the debug
parameter such as:
http://<host>:8090/<application_name>/application/documents?
_dc=1335361466590&type=ft_doc&q=active&facet_authors=David%20Miller
&page=1&start=0&limit=10&debug
The output is a text file that starts with the list of results then details the query
sent to the source.

3. If the output does not contain debug information, make sure the debug mode is
enabled. To do so, refer to the procedure for disabling the query debug mode
and verify that the property debugAllowed is set to true.
6.7 Connecting xCP Application through Load

Balancer
The xCP REST Service supports both HTTP and HTTPS requests. But the client
connects through using either of these requests. Or, the client may send both
requests. This scenario works fine when there is no load balancer in between the
xCP REST service and the client.
However, if there is a load balancer in between, the client forwards the request from
the client to the xCP REST service. Therefore, the requirement of xCP REST is, if
client sends the HTTP request to the xCP REST through load balancer, then load
balancer forwards it as HTTP request to xCP REST. And, if the client sends the
HTTPS request, then the load balancer forwards it as HTTPS to xCP REST. The xCP
REST listens on two different ports for both HTTP and HTTPS requests. So, the load
balancer forwards HTTP request to xCP REST HTTP port and HTTPS request to
HTTPS port respectively.

Chapter 7
Migrating Applications
7.1 Migrating an Application from an Earlier Version

to a Current Version of xCP
Application Migration describes how to migrate applications, libraries, custom
widgets, and custom themes.
Before you perform application migration, ensure that you know how the
application and its components are structured.

Chapter 7 Migrating Applications
The current version of xCP Designer is 22.2. This procedure describes how to
migrate an application from xCP Designer 2.x to the current version of xCP
Designer.
Note: You can now import older xCP application to xCP 22.2 version.
1. Export the application from xCP Designer 2.x.
a. From the xCP Designer 2.x Home page, select an application and click
Export.

7.1. Migrating an Application from an Earlier Version to a Current Version of xCP
b. Click Browse to select a destination folder. Select Include all dependent

projects and click Finish.
2. In the application exported from Step 1, locate the artifact libraries and prepare
the replacement libraries for it as follows. If the application contains any
libraries based on sub-projects, you must migrate them to the current version of
xCP.
a. Open the original application that contains the source project for the Artifact
library from the xCP Designer 2.x Home page.
b. In the Application Model editor, select the project and click Export. Do not
select Export as a library. Then, click Finish.
c. Start the current version of xCP Designer.
d. Create a new dummy application.
e. Import the project exported from Step a.
f. Select Import a copy to copy the selected project to the root folder of your
new application.
g. On Properties tab, increment the Version of the project.
Note: If the same version is used for the exported library, the system
rejects the replacement library during import of the final application to
the current version of xCP Designer.
h. Select the project and click Export.
i. Click Browse to select a folder and select Export as a library.
j. Click Finish.
Keep the exported library JAR at a separate location. Ensure that you do not
overwrite the artifact library in the source application.
Repeat these steps for every library that contains xCP artifacts. You can use
these new JAR files as a replacement library when you import an xCP 2.x
application that contains the original library.
If you see The input attributes for data actions in activity 'Initiate' are out of
date with attributes in package. Save process again to refresh the recent
changes error in the Problems tab, open the process and save it again to refresh
the recent changes. This error occurs if the libraries are not updated. You must
import the new libraries from the Designer and the error is resolved.
When you import applications with new libraries, all the old libraries are
automatically deleted.
3. In the application exported from Step 1, locate the custom component or theme
libraries and prepare the replacement libraries. Ensure that you copy the
exported library JAR to a separate location and then edit the MANIFEST.MF file
of the JAR.

a. Increment the Bundle-Version number and update the JAR filename to

match with the new version. If the Bundle-Version only has two digits,
extend it to three such as 1.0.0 instead of 1.0.
b. Prefix Bundle-SymbolicName with the namespace value. For instance, if the
namespace is human, then Bundle-SymbolicName is human.HumanizeJS.
c. Change the original manifest entry from Require-Bundle: xcpcore,
xcpcommons to Require-Bundle: rest.xcpcore, xcpcomm.xcpcommons,
xcpui.xcpui
d. Add the line EMC-XCP-ExecutionEnvironment: com.emc.

executionenvironment.xcp:16.7.0 in the MANIFEST.MF file.
e. Add a blank line at the end of the manifest file as shown in this sample
MANIFEST.MF file:
Manifest-Version: 2Ant-Version: Apache Ant 1.8.2Created-By: 1.6.0_32-b05 (Sun

Microsystems Inc.)Built-By: xxxComponent-Bundle: SliderWidgetRequire-Bundle:
rest.xcpcore, xcpcomm.xcpcommons, xcpui.xcpuiBundle-Version: 1.0.0Bundle-
Name: SliderWidgetBundle-SymbolicName: sw.SliderWidgetNAMESPACE:
swEMC-XCP-ExecutionEnvironment:
com.emc.executionenvironment.xcp:16.7.0<blank line>
f. This step is applicable only for custom theme libraries. The current version
of xCP Designer is based on Ext JS 7.4.0.42, while the earlier versions of xCP
Designer used Ext JS 6.0.1 or Ext JS 4.x. So, the way custom themes are
structured is different. As Ext JS 7.4.0.42 uses a new technology, Fashion,
instead of SASS, ensure that the code adheres to the Fashion syntax. For
more information, refer to https://docs.sencha.com/cmd/6.x/fashion.html.
Due to the Ext JS upgrade, perform these steps to upgrade the theme
library:
• Remove Theme-Sass-File attribute from the MANIFEST.MF file.

• Place all images at the resources folder. In the SCSS file, the image can
be referenced assuming resources folder is the root folder. For example,
the icon.png image file available at resources/images/icon.png in
the JAR file and the same image file can be referenced as url('images/
icon.png') in the SCSS file.
• The actual SCSS code can be separated into three files. Each file must be
placed under SASS folder in the JAR and named as follows:
– sass/etc.scss – Contains any utility and mix-ins files.

– sass/var.scss – Contains all new variable declarations and override
values for variables declared in the xCP System Default theme.
– sass/src.scss – Contains main CSS class definitions.
These files are optional, but at least one file must be created and made
available at the required location.

7.1. Migrating an Application from an Earlier Version to a Current Version of xCP
Note: The sass extension files are not supported anymore. You
must convert these files to scss extension.
• For organizational purposes, you can have multiple SCSS files, and you
can use import statements to reference these files.
• The common.scss is not required anymore. If the file is included in the
theme, it must be removed including its import reference from the main
scss file.
• Remove the import of Ext or xCP default theme, wherever applicable.
Note: While importing an application to the current version of xCP

Designer, the theme of the Migrated application differs from the
source version of migration as follows:
Behavior in themes migrated from Behavior in themes migrated from

versions prior to 2.3 2.3 and later versions
Any theme resets to new default • When migrated, the new system
theme and theme selection can be default theme is selected by
done as per your requirements. default. And if Legacy theme is
required, you must select the same
theme manually.
• Custom theme remains as such.
4. Import the exported application to the current version of xCP Designer.
a. From the xCP Designer Home page, click Import Application.

b. Click Browse to select the destination folder.
c. Select the desired checkboxes next to the application and all the projects that
belongs to it.
d. Select Import a copy to copy the selected projects to the root folder of your
new application.
e. Click Next. You can Add or Remove the compatible versions of the libraries
created from Step 2 and Step 3, as required.
f. Click Finish.
If you see The Fragment input/output attributes for fragment <filename>_imp

are out of sync with actual attributes in model reopen the fragment to update
the fragment model OR The Fragment input/output attributes for fragment
<filename>_chk are out of sync with actual attributes in model reopen the
fragment to update the fragment model error in the Problems tab, double-click
to open the error message. The page reloads and the error is resolved.
If you see ERROR::Widget object_name:Invalid expression,Variable
Inputs.object_name not found error in the Problems tab for any base_folder*.*
files after the application is imported to the latest xCP Designer, then close the
xCP Designer, manually delete all the base_folder*.actionflow and

base_folder*.uistep files in the artifacts folder, and .index file in top folder of the
application. Then, restart the xCP Designer and verify that the error is resolved.
The current version of xCP Designer restarts in a new workspace.
7.1.1 Troubleshooting
Artifact Libraries Throw Errors During Runtime
The artifact libraries were not migrated to the current version of the xCP Designer.
• Migrate the artifact libraries to the current version of the xCP Designer and then
use it as a replacement library.
• Do not manually update the MANIFEST.MF file.
Custom Widgets Break During Migration

The current version of the xCP Designer uses Ext JS 7.4.0.42.
You must manually test and update for compatibility.
Replacement Libraries Throw Errors During Runtime

Replacement libraries are not accepted during migration.
Update the bundle version.
Multiple selections on Results List return an array of values but

values appear as single value in xCP Designer
If the Results List widget has Allow selection of multiple items checkbox selected, then
in any expression where the selected row node of this results list widget is used, the
data type of all child attributes are changed to multivalue (with repeating =true)
instead of a single value. If there are expressions that use these child nodes, the
expressions would start showing up as errors in the Problems tab.
You must fix these expressions manually to resolve the error.
Model Type Session Parameter Throws Error

Whenever you migrate a xCP 2.1 application or xCP 2.2 application with string data
type mapped to a model type session parameter to the current release, the system
throws an error in the problems tab.
You must fix this manually to resolve the error.

7.2. Type Adoption
7.2 Type Adoption

Type adoption feature enables you to adopt data types from the Documentum
repository to the xCP application. Using type adoption, xCP application can read or
write data instances created through Documentum clients, such as previous versions
of xCP, Documentum Administrator, Documentum Webtop, and TaskSpace, and
adopted in the xCP Designer. Similarly, Documentum clients can read or write new
instances of adopted types created in an xCP application. Thus, the type adoption
feature provides interoperability between Documentum clients and xCP
applications accessing data instances.
Limitations
The following limitations apply to the adopted data types:
• You can adopt only subtypes of dm_sysobject, dm_document, and dm_folder

data types.
• If you adopt data types inherited from another data type, the system adopts all
their super types.
• You can adopt the data types only once. The system does not list the data types
for adoption again.
The OpenText Documentum xCelerated Composition Platform Developer Guide provides

details on how the system adopts the data types and their runtime behavior.
7.2.1 Adopting Data Types

Ensure the repository endpoint is configured to perform this activity.
1. In the Object Models navigator, click New > Adopt Data Types.
2. In the Adopt Data type(s) dialog box, select a design-time environment. The
system populates all the fields as configured in the selected design-time
environment. Click Next.
3. Specify the required business objects, content, and folder types you want to
adopt.
4. Select the name of a project to which you want to import the types from the
repository.
5. Click Finish and then click OK.
On successful operation, the system displays the adopted data types. Once the data
type is adopted to a specific application, the system does not allow the same type to
be adopted again.

7.3 Type Migration

Use Type Migration to import object types created using the Composer application
to the xCP Designer. You can modify the imported data type and the system treats
like any other data type.
7.3.1 Importing Types from Composer

This procedure applies to Business Object, Folder, and Content models.
1. In the Object Models navigator, click New > Import Types From Composer.
2. In the Import Types From Composer dialog box, specify the properties as
Field Description
Composer project root Click Browse to navigate to the project
folder on your file system and click OK.
This project is created using the Composer
application.
Import Into Select the application you want to import
the Types into.
Types to Import Select the checkbox next to each Type that
you wish to import.
3. Click Next.
4. Review the Types. You can see the Name and Data Type of the selected Types.
5. Click Finish. The system imports all the Types in the Object Models navigator
under Business Objects, Content, and Folders respectively.
7.4 Interoperability
Interoperability is the ability of Documentum Clients to work with xCP.
For instance - You can design an xCP application by adopting the object types used
by 1.x Documentum Clients like Documentum Webtop, Taskspace, or DAC and test
whether xCP 16.7 applications can create, read and write data instances created
through these clients.
Refer the OpenText Documentum xCelerated Composition Platform Release Notes about
the interoperability of Documentum Clients with xCP 16.7 and Documentum
platform combinations.
Limitations
xCP 2.x does not support the data dictionary, which includes value assistance,
attribute label internationalization, and constraints.

7.5. Reverse Interoperability
7.5 Reverse Interoperability

Reverse interoperability is the ability of xCP to work with Documentum Clients.
For instance - You can design an xCP application by defining xCP object types and
test whether 1.x Documentum Clients such as DocumentumWebtop, D2, Taskspace,
or DAC can create, read and write data instances for the xCP object types created
through xCP 2.x and later applications.
Limitations
The following limitations exist with some of the 1.x Documentum Clients:
• D2 does not support business events and process variables.

• D2 and 1.x Documentum Clients does not execute processes initiated from xCP.
• Process interoperability is not supported. xCP 2.x processes are not interoperable
with 1.x Documentum Clients.
• Aspects defined for an xCP data type are not supported in 1.x Document Clients.

Chapter 8
xCP Process Manager
8.1 Overview
xCP Process Manager is an out-of-the-box production-ready application that you can
use to view, monitor, and manage all the tasks assigned to a user. It provides
functionality to start, view, and manage process instances and tasks. You can
customize the xCP Process Manager application based on your business
requirements and add business processes using simple steps. It also provides basic
content management capabilities.
xCP Process Manager covers the basic functional requirements for most businesses;
enabling you to deploy and extend its functionality in a seamless manner.
This application is bundled along with the xCP Designer and you can import the
application into your xCP Designer environment and leverage the basic
functionality for faster deployment. The xCP Process Manager application has the
following default tabs that provide basic functionality:
• Inbox – My Task: Lists all the tasks assigned to a user in the xCP Process
Manager.
• Process Instances: Enables you to access and manage the processes initiated in
the xCP application.
• Process Template: Lists all the processes available in the xCP Process Manager
application.
• Search: Enables you to search documents, folders, and cabinets in the
Documentum repository.
• Repository Browser: Displays all the content in hierarchical order under the root
folder in the repository.
8.2 Prerequisites
The hardware and software requirements for xCP Process Manager are same as for
xCP 20.2. xCP Process Manager requires a minimum of xCP 20.2 release build.

Chapter 8 xCP Process Manager
8.3 Importing the xCP Process Manager application

The xCP Process Manager application is bundled along with xCP Designer. The
xCPProcessApplication folder contains the xCP Process Manager application and
the corresponding project.
To import the xCP Process Manger application into the xCP Designer:
1. Launch xCP Designer.

2. Navigate to xCPProcessApplication folder and select both the folders,
xCPProcessApplication (application) and xCPProcessManager (project).
3. Select Import to import the application. You can also import a copy of the
application using the Import as copy option. Using the Import as copy option
allows you to create a backup of the application in case of a failure.
4. Click Finish.
8.4 Inbox – My Task

The Inbox – My Task page lists all the tasks assigned to a user in the xCP Process
Manager. It provides information such as task name, task creation date, sender, and
priority for the tasks assigned to a user. The task information is displayed on the
application’s default landing page. You can change the scope of task list from
application-specific to Documentum repository in the Task-List query editor. For
more information about how to change the scope of a task-list query, see
Documentum xCelerated Composition Platform Designer Help.
To view all the tasks assigned to a user in the Documentum repository, change the
Filter by processes option to All Documentum processes.
You can filter the task-list result in the Inbox – My Task page using the following
fields:
• Task Name: Name of the task.

• Sender: Name of the task assigner.
• Status: Status of the task. A task can be in Dormant, Acquired, Ready, or Paused
state.
• Sent Date From: Start date for filtering the task-list.
• To: End date for filtering the task-list.
The Inbox – My Task page provides the following details about each task:
• Task Name: Name of the task.

• Due Date: Date by which task needs to be completed.
• Status: Current status of the task. A task can be in Dormant, Acquired, Ready, or
Paused state.

8.5. Task Details
• Priority: Priority of a task. Valid value ranges between 0 to 5, where 0 has least
priority.
• Sender: Name of the task assigner.
• Process Name: Name of the process to which this task belongs.
• Sent Date: Date when the task was assigned to current owner.
The task details are displayed in tabular format and by default 10 tasks are
displayed on a page. You can change the default number of tasks displayed on a
page using the Page size drop-down list. If the task list spans multiple pages, you
can navigate using the page navigation bar at the bottom of the task-list page.
8.5 Task Details

You can open a task from the Inbox – My Task page to view the task details and
perform various actions on a task. The following task details are displayed on the
task detail page:
• Activity Name: Name of the activity.

• State: State of the selected task.
• Started on: Start date for the selected task.
• Assigned to: Name of the current task owner.
• Due On: Expected task completion date.
• Task Details: Provides information about variables and packages related to the
task. You can add or remove a package or variable here.
– Packages: You can add and remove packages from the Task Details tab. You
must select the package from the selector result list based on the type of
package.
○ Mandatory packages: Packages that must be attached to a task before

performing any task action.
○ Non-mandatory packages: Optional packages.
– Variables: You can view and update the variables.
• Attachments: Lists all the attachments related to a task. The Attachments tab
provides the following options:
– Add: Adds a supporting document from repository as an attachment to a

task.
– Add (Local): Adds a supporting document from local system as an
attachment to a task.
– Remove: Removes an attachment.

Note: You cannot attach custom type objects that are not part of the xCP
Process Manager application. The attachments section lists all the available
objects in the repository. However, you can only add objects that are part of
the xCP Process Manager as an attachment.
• History: Provides information about all the actions performed on a task. This tab
provides the following details related to a task:
– Activity name: Name of the activity and action performed.

– Date: Date when the action was performed.
– Performer: User that performed this action.
– Status: Current status of the task.
You can perform the following actions on a task:
• Update: Updates the task details.

• Complete: Changes the status of the task to complete.
• Delegate: Delegates the task to another user.
• Repeat: Repeats the task.
• Hold/Unhold: Toggles the state of the task between hold and unhold.
• Reject: Rejects the task.
• Rerun: Reruns the task.
Notes
• Delegate action is available only for the tasks that are enabled for delegation.
• Reject action is available only for the tasks that are enabled for rejection.
• Rerun action is available only for failed automatic tasks.
The xCP Process Manager Task Details page is available only for processes that are
not created in xCP application. For xCP processes that are not part of xCP Process
Manager, you need to import the process into the xCP Process Manager and create
the task details page for the process. Similar requirements apply to a new process
created in the application. For more information about how to import a process and
create a task detail page for a process, see OpenText Documentum xCelerated
Composition Platform Designer Help.

8.6. Context Menu
8.6 Context Menu

The following context menu options are available for the tasks listed in the Inbox –
My Task page:
• View: Opens the task details page.
• Acquire: Acquires a task in dormant state. This option is available for tasks that
are in dormant state.
• Complete Task: Changes the task status to complete. Note: If a dialog box
prompts you to confirm the password, click Finish to change the task status to
complete. Enter the password only for tasks that require signoff.
• Repeat Task: Repeats the task.
• Delegate: Delegates the task to another user.
• Hold/Unhold: Toggles the state of the task between hold and unhold.
8.7 Process Instances

The Process Instances page enables you to access and manage the processes initiated
in the xCP Process Manager application. The page lists all the process instances
currently available in the xCP application based on the login credentials (Role). The
following table lists the processes that are available for each role:
User All the Processes Processes initiated by or

assigned to the Supervisor
System Administrator Y
Super User Y
Supervisor or User Y
The Process Instances page provides the following fields of information for each
process:
• Workflow Name: Name of the process instance workflow.
• Runtime State: Runtime state of the process instance workflow.
• Start Time: Time when the process instance workflow was started.
• Process Name: Name of the parent process.
• Supervisor Name: Name of the supervisor for the process instance.
The Process Instances page allows you to perform the different actions on a process
based on the Role.

Actions
User Change Resume Halt Workflow Terminate
Supervisor Workflow Workflow
System Y Y Y Y
Administrator or
Super User
Supervisor or Y Y Y Y
User
Notes
• A terminated process is removed from the Process Instances list.

• A Supervisor with the delete permission can terminate a Process Instances
list.
• If a user is not a supervisor for any process, the Process Instances list is
empty.
The Process Instances utility allows you to filter the processes based on the
following fields:
• Supervisor Name: Name of the supervisor for the process instance.

• Runtime State: Current state of the process instance.
• Workflow Name: Name of the workflow to which the process instance belongs.
• Process Name: Name of the process to which the process instance belongs.
8.8 Sorting Results List

You can sort the results list based on the following columns:
• Workflow Name
• Runtime State
• Start Time
• Process Name
• Supervisor Name
To enable sorting of results, update the process instance configuration code as

follows:
SELECT object_name ,r_runtime_state,r_start_date ,process_name ,
wf_r_object_id ,supervisor_name from (SELECT wf.object_name ,
wf.r_runtime_state,wf.r_start_date ,p.object_name as process_name,
wf.r_object_id as wf_r_object_id,wf.supervisor_name
FROM dm_workflow wf, dm_process (ALL) p, xcp_artifact_bundle a
where any a.installedobjectid = p.r_object_id
and (wf.process_id=p.r_object_id)
AND (wf.r_runtime_state!=2
AND wf.r_runtime_state!=4

8.9. Process Template
AND ( UPPER(wf.object_name) LIKE $Workflow Name$

AND UPPER(wf.supervisor_name) LIKE $Supervisor Name$
AND wf.r_runtime_state = $Runtime State$
AND UPPER(p.object_name) LIKE $Process Name$))
and a.namespace in ('xcpproj'))ORDER BY ?
Change to
SELECT object_name ,r_runtime_state,r_start_date ,process_name ,
wf_r_object_id ,supervisor_name from (SELECT wf.object_name ,
wf.r_runtime_state,wf.r_start_date ,p.object_name as process_name,
wf.r_object_id as wf_r_object_id,wf.supervisor_name
AND (wf.r_runtime_state!=2 AND wf.r_runtime_state!=4
AND (UPPER(wf.object_name)
LIKE $Workflow Name$
and a.namespace in ('xcpproj','new_xcp_proj_namespace'))ORDER BY ?
You can also configure the Process Instances and Process Instance Count ARQs to
view all the process instances within the Documentum repository with sorting
enabled. The following is an example of updated Process Instance.
ARQ to include the Process Instances within the Documentum repository:

SELECT object_name ,r_runtime_state,r_start_date,
process_name ,wf_r_object_id ,supervisor_name from
(SELECT wf.object_name ,wf.r_runtime_state,
wf.r_start_date ,p.object_name as process_name,
wf.r_object_id as wf_r_object_id,wf.supervisor_name FROM dm_workflow wf,
dm_process (ALL)p, xcp_artifact_bundle a
AND (UPPER(wf.object_name) LIKE $Workflow Name$
AND UPPER(p.object_name) LIKE $Process Name$)))ORDER BY ?
8.9 Process Template

The Process Template page lists all the processes available in the xCP Process
Manager application. The page provides information about the process name,
version, and owner. It allows you to initiate any process from the list if there is a
Process Initiate page associated with it.
You can sort the result list based on the following columns:
• Process Name
• Owner
To enable sorting the result list, you need to update the ARQ for process template:
Select p.r_object_id, p.system_name, p.object_name,
p.r_version_label, p.owner_name
from dm_process (all)p, xcp_artifact_bundle a

and p."r_definition_state"=2
AND UPPER(p.object_name) like $Process Name$
AND p.system_name not in ('xcpproj_terminate_workflow',
'xcpproj_resume_workflow','xcpproj_halt_workflow',
'xcpproj_checkloggedinuserrole','xcpproj_change_supervisor')
and a.namespace in ('xcpproj') Order by ?, p.system_name
change to
'xcpproj_resume_workflow', 'xcpproj_halt_workflow',
and a.namespace in ('xcpproj','new_xcp_proj_namespace')
Order by ?, p.system_name
8.10 Search
The Search utility allows you to search documents in the Documentum repository.
You can search a document using the following fields:
• Name: Document name.

• Owner: Owner of the document.
• Type: Type of the document.
• Modified Date From: Date from which you started modifying the document.
• To: Date when you stopped modifying the document.
To search a folder or a cabinet in the Documentum repository, use the following

fields:
• Name: Folder or cabinet name.

• Owner: Owner of the folder or cabinet.
• Type: Type of the folder or cabinet.
The results are listed in a tabular format and you can perform context-specific tasks
on a result entry based on the role.

8.11. Enabling search for custom types
8.11 Enabling search for custom types

You can configure the search for custom types created in the xCP Process Manager
application Search tab. Complete the following steps to configure search operation
for custom types:
1. Create a RTQ for the Custom Business Object created with the following details:
• Project: xCPProcessmanager
• Primary Model: Business Objects
2. Select the required output columns from the Dataset tab.
3. Select Return hit count option.
4. Select Enable Sorting option for each output column.
5. Configure the required user inputs and Save.
6. Create a new Page Fragment.
7. Add the RTQ you created to the interactions of the page fragment.
8. Add the result list to the Fragment and bind the RTQ as data source.
9. Select the Display Record count option for the result list.
10. Select When an Input value changes and On Page Load options under Refresh
on the RTQ.
11. Go to the Search page and add a Page Fragment Container widget.
12. Map the newly created page fragment to the container widget.
13. Modify the Search for Picklist to add the custom type to the dropdown in the
search page.
14. Modify the Behavior of each page fragment container in the Properties tab, so
that the Search page shows only the selected search results.
15. Save and deploy the Application, the dropdown in the Search tab is refreshed
with the entry for the custom type and search result returns the list of the
custom type.

8.12 Full text search

You can integrate full text search or query (FTQ) in the xCP Process Manager
application. Using xPlore, you can search documents, folders, and cabinets as full
text faceted search. By default, the full text search is not available in the xCP Process
Manager application. To configure full text search in xCP Process Manager
application:
1. Create a full text search menu item on the Master page.
2. Link the full text search menu item to the static FTQ search page.
By default, not all the search attributes are configured as facets. You need to
configure a facet in the indexserverconfig.xml file(xPlore) with returning-contents
attribute set to true to make it available in the application for full text search. For
example, you can configure the following attributes for full text search:
• object_name
• owner_name
• r_modify_date
• r_creator_name
• r_creation_date
• a_content_type
• r_content_size
Note: For more information, see xPlore Administration and Development Guide.
You can also create FTQ for custom business object.
To create FTQ for custom business objects, complete the following steps:
1. Define the FTQ with the following details:
• Project: xCPProcessManager
• Primary Model: Business Objects
2. Select the required output columns from the Dataset tab.
3. Select Return hit count option.
4. Select Enable Sorting option for each output column.
5. Configure the required facets from the Facets tab and save the settings.
6. Create a new page fragment.
7. Add the new FTQ to the interactions under the page fragment.

8.13. Repository Browser
8. Add the result list to the fragment and bind the FTQ as the corresponding data
source.
9. Select Display Record count option for the result list.
10. Select When an Input value changes and On Page Load options under Refresh
tab on the FTQ.
11. Open the FTQ search page and add a Page Fragment Container widget.
12. Map the newly created page fragment to the container widget.
13. Modify the FTQ search for Picklist to add the entry for the new search.
14. Modify the behavior of each page fragment container in the Properties tab, so
that the FTQ search page shows only the selected search results.
15. For each custom type attribute that is used as a facet, ensure that a subpath is
configured in indexserverconfig.xml file in xPlore. For more information, see
xPlore Administration and Development Guide.
16. Save and deploy the application. The drop-down menu in the FTQ search tab is
refreshed with the custom type and search result returns the list of the custom
types.
8.13 Repository Browser

The Repository Browser page displays all the content in a hierarchical order under
the root folder in the repository. You can perform all the valid ECM operations such
as creating new folder, importing a file, and deleting content from this page. By
default, the Repository Browser page displays the content of the root folder. You can
configure the default folder in the properties section of the Folder View widget.
8.14 Customizing xCP Process Manager

This section explains how to customize the xCP Process Manager. You can
customize various xCP Process Manager components such as processes, roles,
process templates, and process instances based on the business requirement.
8.14.1 Creating or adding a process to xCP Process Manager

You can create or add a new process in the xCP Process Manager to define new
activities, process flows, and process data. A process is basically an instance of a
process model at runtime. You can create multiple processes of the same model to
run concurrently in an application. You can import a process model or create your
own process model.
Using xCP Designer, you can customize the xCP Process Manager application to suit
organization-specific use cases such as HR hiring operation or Financial approval
process. For more information about how to add or import a new process to xCP
Process Manager application, see Documentum xCelerated Composition Platform
Designer Help.

8.14.2 Adding Roles or Groups to xCP Process Manager

A role defines a specific job function within an application. You create a role and
map it to a permission level to manage access to the application and data. You can
also create a group and add multiple users and assign permissions to the group.
Using xCP Designer, you can create roles and assign role-based access to the
application and specific functionality to the users. You can also create groups to
distribute process tasks to a set of users to distribute the work. For more information
about how to create roles or groups, and add them as activity performers, see
Documentum xCelerated Composition Platform Designer Help.
8.14.3 Configuring Process Template

The Process Template page lists all the processes available in the xCP Process
Manager application. By default, the Process Templates page returns no results. You
must create a process and process initiate page in the xCP Process Manager
application for this page to list processes. Initiating a process without creating the
process initiation page results in error with the following error message:
The page you requested was not found.
To create a process and process initiate page, see OpenText Documentum xCelerated
Note: Starting with xCP 22.2 release, the process initiate page provides
functionality to select a default alias tied to the process at the runtime.
If you import, create, or update a project, you must modify the Process Template
and Process Template Count Advanced Repository Queries (ARQs) in xCP Process
Manager application to list the process from the new or updated project. For
example, if you have imported or created a new project in the xCP Process Manager
application, update the Process Template ARQ as follows:
'xcpproj_resume_workflow','xcpproj_halt_workflow',
and a.namespace in ('xcpproj')ORDER BY p.object_name
change to
'xcpproj_resume_workflow', 'xcpproj_halt_workflow',

8.14. Customizing xCP Process Manager

ORDER BY p.object_name
Note: If you are updating the xCP Process Manager project namespace, you
must update the ARQ accordingly.
8.14.4 Configuring Process Instance

The Process Instances page enables you to access and manage the processes initiated
in the xCP Process Manager. If you import, create, or update a project, you must
modify the Process Instances and Process Instance Count ARQs in xCP Process
Manager application to list the process instances from the new/updated project. For
example, if you have imported or created a new project in the xCP Process Manager
application, update the Process Instances ARQ as follows:
SELECT p.object_name AS workflow_name,
wf.r_runtime_state AS runtime_state,
wf.r_start_date AS start_time,
p.object_name AS process_name,
wf.r_object_id AS wf_r_object_id,
wf.supervisor_name AS supervisor_name
AND (wf.r_runtime_state!=2
AND wf.r_runtime_state!=4
AND ( UPPER(wf.object_name) LIKE $Workflow Name$
and a.namespace in ('xcpproj')
ORDER BY wf.r_start_date desc
change to
wf.supervisor_name AS supervisor_name
AND (UPPER(wf.object_name)
LIKE $Workflow Name$
Note: If you are updating the xCP Process Manager project namespace, you
must update the ARQs accordingly.
You can also configure the Process Instances and Process Instance Count ARQs to
view all the process instances within the Documentum repository. The following is
an example of updated Process Instance ARQ to include the Process Instances
within the Documentum repository:


wf.supervisor_name AS supervisor_name FROM dm_workflow wf,
dm_process (AL)p, xcp_artifact_bundle a
The following is an example of updated Process Instance count ARQ to include the
process instances count within the Documentum repository:
SELECT count(wf.process_id) AS row_count
For more information about how to configure process instances, see Documentum
xCelerated Composition Platform Designer Help.
8.14.5 Preserving the result list page filter

You can configure the input fields on the result list page to preserve the result list
page results while navigating to and from the result list page. A session parameter
must be attached to the input field that stores the input field value while navigating
away from the result list page.
To configure an input field to preserve its value:
1. Create a session parameter.
2. Attach the session parameter to the input field.
3. Navigate to the Subscribe UI events tab on the UI events tab.
4. Attach the session parameter to an input field.
5. Set Behavior to Set Value for the input field and type the session parameter
name in the text-field or select the session parameter.
6. Save the configuration.
Note: For more information about how to create and attach session
parameters, see OpenText Documentum xCP Designer Help.

8.15. Deploying xCP Process Manager
8.15 Deploying xCP Process Manager

Follow these steps to deploy the xCP Process Manager in xCP Designer:
1. Add a deployment environment.
2. Add a design-time environment.
3. Create a running configuration.
4. Run the xCP Process Manager application in the deployment environment.
Note: For more information about deployment environment, design-time

environment, running configuration, and how to run an application in the
deployment environment, see OpenText Documentum xCelerated
8.16 Resolving DQL failure

The DQL count query fails with NumberFormat exception while accessing Process
Instances and Process Templates tab in the Oracle database. When you open the
Process Instances or Process Templates tab, the following error message is
displayed:
An error occurred while performing the requested operation. Please try again.
Complete the following steps to resolve this issue:
1. Validate the DQL query for the Process Instance Count and Process Template
Count ARQs, click Edit Query -> Execute -> Finish to change the Type for
row_count from integer to decimal in the Output Column.
2. Refresh the application.
3. Apply the floatToInt function to the expression in the Result List Properties for
the Process Instances and Process Template tabs. For example:
floatToInt(dataservices.process_instance_co.outputs[0].row_count)
8.17 Resolving xCP Process Manager deployment

failure
The xCP Process Manager application fails to deploy in xCP 20.3 release build with
the following error message:
[ERROR] com.emc.documentum.core.fulltext.indexserver.admin.controller.ServiceException:
Incompatible type change for the subpath [dmftmetadata//r_content_size] detected. Data
type cannot be changed from xdb type [1024] to [integer].
The data type of variable, <r_content_size>, is configured as double in the

indexserverconfig.xml leading to type mismatch. Complete the following steps to
resolve this issue:

1. Update the <r_content_size> variable definition in the indexserverconfig.xml

file as described:
sub-path path="dmftmetadata//r_content_size" type="integer" full-text-
search="false" value-comparison="true"
2. Restart all the xPlore instances.
3. Open the xPlore administration UI, select the domain or collection in the Data
Management tree and click Rebuild Index.
Note: For more information, see OpentText Documentum xPlore

Administration and Development Guide.

Chapter 9
Setting up xCP in Kubernetes Environment
9.1 Introduction
Kubernetes is a portable, extensible open-source platform for managing
containerized workloads and services, which facilitates both declarative
configuration and automation. For more inforamation about how to set up xCP in
Kubernetes environment, see OpenText Documentum xCelerated Composition Platform
Cloud Deployment Guide.
Note: Documentum xCP components in Kubernetes environment support

Readiness and Liveness probes.

Chapter 10
Troubleshooting Manually-provisioned
Environments
10.1 Environment Status Registration Incomplete

Problem
You have provisioned an environment manually and you have registered that
environment in the xDA Management Center, but the status of the environment
remains as Registration Incomplete.
Cause
For the enabled services in the registered environment, you have not provided all
required endpoint details.
Resolution
Examine the list of services for the environment in the xDA Management Center. For
each enabled service:
• If that service is available in your environment, update the environment to

specify the required endpoint details.
• If that service is not available in your environment, disable that service in the
environment.
10.2 Application Deployment Problems

Problem
Deployment of an application to an xCP environment fails with an error.
Resolution
Use the following table to resolve problems with deploying an application:
Error Description
Version mismatch (in a manual Update the versions of service components
environment) in the xDA Management Center to match
your environment. “Synchronizing a
manually provisioned environment”

Chapter 10 Troubleshooting Manually-provisioned Environments
10.3 Page Modification and Display

Problem
You encounter issues with the page modification operations in all viewers. You also
encounter issues in the page display operations of all viewers except the xCP
Content Viewer and the xCP Media Viewer.
Cause
The DAR Installer did not correctly install DIS.
Resolution
Verify that the DAR Installer installed the following items:
• annotationconfig.xml, located in System/Modules/

ImagingServiceAnnotationPluginModules
• In System/Modules/SBO, verify that the installation created the following

folders:
– com.documentum.pageaware.pdf.IPdfPageHandlerService
– com.documentum.pageaware.tiff.ITiffPageHandlerService
– com.documentum.services.imaging.annotationservice.IAnnotationService
– com.documentum.services.imaging.pageaccess.IPageAccess
• PageModificationModule, located in System/Modules/ImageServiceModule
Reinstall the DIS DAR if any item is missing.
10.4 Privileged DFC Problems

Problem
You encounter error messages associated with operations that require privileged
DFC.
Resolution
Use the following table to resolve issues associated with privileged DFC.
Error Description
[DM_SESSION_E_CLIENT_AUTHENTICAT The DFC client is not known to the server.
ION_FAILURE]error: “Could not Configure and enable the client for
authenticate the client installation for reason: privileged DFC operations.
Not applicable”.

10.4. Privileged DFC Problems
Error Description
[DM_SESSION_E_CLIENT_AUTHENTICAT The DFC client does not match what is
ION_FAILURE]error: “Could not registered in the docbase (certificate).
authenticate the client installation for reason: Configure and enable the client for
Digital Signature verification failed”. privileged DFC operations.
[DM_SESSION_E_CLIENT_AUTHENTICAT Your DFC client does not match what is
ION_FAILURE]error: “Could not registered in the docbase (hostname).
authenticate the client installation for reason: Configure and enable the client for
Client hostname in authentication string privileged DFC operations.
doesn't match value in the registry”.
[DM_SESSION_E_CLIENT_AUTHENTICAT The client and server times are not
ION_FAILURE]error: “Could not synchronized.
authenticate the client installation for reason:
Timestamp in authentication string has
expired”.
[DM_GROUP_E_PROTECTED_ROLE_UNK The client is not privileged. Configure and
NOWN_CLIENT]error: “The requested enable the client for privileged DFC
role(role_name) is marked protected and the operations.
requesting application was either not known
in this docbase's dm_client_rights table or its
credentials did not match those in the
dm_client_rights table”.
[DM_GROUP_E_PROTECTED_ROLE_PRIV The client is not privileged. Configure and
]error: “The requesting application is not enable the client for privileged DFC
privileged to use role (role_name).”. operations.
[DM_SESSION_E_ADD_DYNAMIC_ROLE Validate that the group exists in the
]error: “Error adding dynamic role repository and that it is dynamic.
<dm_superusers_dynamic>”.
[DM_GROUP_E_NOT_DYNMAIC_MEMBE Add the user to the dm_superusers_dynamic
R]error: “User is not a potential dynamic role.
member of group role_name.”
AccessControlException The DAR Installer did not install
PageModificationModule as privileged.

instructions on enabling privileged DFC clients.

10.5 Cannot Save Annotations

Problem
You cannot save annotations in the viewer.
Resolution
Check the repository to verify that the DAR Installer installed the following
components:
• AnnotationService SBO
• annotationconfig.xml
Reinstall the DIS DAR if any component is missing.
10.6 Document is not Available for Viewing

Problem
In the xCP Viewer, when you try to view a recently-imported document, a message
appears stating that content is not available and suggests that you try again
afterwards. In the application server where the xCP application is deployed, a
RealTimeRenditionException error message is recorded in the log file specified in
the log4j2.properties file. The log4j2.properties file specifies the name of a log file as
in the following example:
log4j2.appender.fileAppender.File=C:/temp/documentum/xCPApplication.log
While running the application, the system creates and populates this
xCPApplication.log file. If the CTS configuration file transformation.properties is
missing from the classpath, the following errors are recorded in the
xCPApplication.log file:
transformation.properties or preferences.xml file is expected under
<expected_path>\transformation.properties
Failed to read the config file : transformation.properties or preferences.xml
Where <expected_path> is the path where the system expects to find the
transformation.properties file.
Cause
The xCP Viewer was not configured properly for CTS real-time calls and therefore
no real-time calls ever reached CTS. The client project cannot find
transformation.properties file or preferences.xml file in the expected path.

10.7. xCP Viewer is not Displaying a Document
Resolution
If the RealTimeRenditionException error appears, implement the steps required by
CTS to enable real-time invocations. “Configuring xCP to Interact with CTS”
10.7 xCP Viewer is not Displaying a Document

Problem
A rendition is a copy of a file in a different format. For example, a rendition can be a
copy of an image in a different file format or in a different resolution. CTS is
generating renditions but the xCP Viewer is not displaying a document. A rendition
in this context is a low-resolution JPEG representation (storyboard) of each page of
the document which is used to view the document content.
Cause
The most likely cause is that the Accelerated Content Services (ACS) server is not
running.
Resolution
Verify that the ACS server is running. Use a browser to access the ACS test URL:
http://<repository-host-name>:<port>/ACS/servlet/ACS
Where <repository-host-name> and <port> depend on your current ACS

configuration. The default port is 9080. You can examine this configuration by
issuing a DQL command against the ACS object in the repository You can also check
the base_url.
If a message appears stating that the ACS server is not running, restart the ACS
server. If restarting the ACS server does not resolve the problem, perform
Documentum Server troubleshooting. The OpenText Documentum Platform and
Platform Extensions Installation Guide provides more information on ACS.

10.8 Specific Document Formats are Never Available

for Viewing
Problem
Documents of specific formats (such as DOCX) are never available for viewing.
Cause
CTS does not generate renditions for specific formats because the CTS Configurator
richmedia enables a limited number of formats out-of-the-box.
Resolution
Run a DQL command to make the additional formats rich media enabled. “Setting
the richmedia_enabled Flag” on page 242 provides instructions.
10.8.1 Setting the richmedia_enabled Flag

If CTS does not generate renditions for documents of registered formats that have
been imported into the repository, check the following on the CTS instance:
1. Check the richmedia_enabled flag for the dm_format object corresponding to

the format that you want to use. For example, for a Microsoft Word 2007
document, run the following DQL query:
Select richmedia_enabled from dm_format where name='msw12'
2. If the richmedia_enabled flag is set to 1, CTS generates renditions for that

format. It is possible that the asynchronous request is still in the queue and CTS
is yet to process it.
3. If the richmedia_enabled flag is set to 0, the OpenText Documentum Content

Transformation Services Administration Guide describes how to enable it.
10.9 Delayed Document Display

Problem
When you attempt to view a document in the xCP application, the time required for
the document to appear in the viewer is more than expected.
Cause
CTS is overloaded with transformation requests.

10.10. Retrieving a List of Namespaces
Resolution
Improve the load balancing by dedicating CTS instances for handling each type of
request, asynchronous requests and real-time requests. The OpenText Documentum
Content Transformation Services Installation Guide provides details.
10.10 Retrieving a List of Namespaces

In xCP Designer, each application has a namespace. Namespaces prevent conflicts
between projects that have artifacts with the same labels. You cannot deploy
applications and projects with the same namespace to the same environment. To
make sure that a namespace is not already used in an environment, retrieve a list of
namespaces from Documentum Server.

2. Select Tools > Dql Editor.
3. On the Dql - Enter Query page, type the following command in the text box:
select distinct(namespace) from xcp_artifact_bundle (all)
4. Click Execute.
5. In the Results area, select to show additional items in the Show Items field to
view the complete list of namespaces.
6. Click OK.
7. Log out of Documentum Administrator.
10.11 Incorrect URL Appears After Deploying an

Application
Problem
The following table describes the expected and problem behavior when using xCP
Designer or xDA Tools to deploy applications:
Application deployment xCP Designer xDA Tools

using
Expected behavior After a successful After a successful
deployment, the web deployment, the console
browser must appear with shows a URL address with
the xCP application host IP the xCP application host IP
address and port number in address and port number.
the URL address.

Application deployment xCP Designer xDA Tools

using
Problem behavior A web browser appears with The console shows a URL
the xCP Deployment Agent address with the xCP
IP address in the URL Deployment Agent IP
address with the port set to address and the port set to
8000. 8000.
Cause
Multiple issues can cause an incorrect URL, including the following:
• The xCP application host and the xCP Deployment Agent are not installed on the
same machine.
• The xCP application host is not set to port 8000.
Resolution
The resolution depends on the method of deployment:
• For deploying from xCP Designer, configure the xcpdesigner.ini file.

“Configuring xCP Designer to Show the Correct URL” on page 244 provides
instructions.
• For deploying from xDA Tools, if the xCP application host is not installed on the
same machine as xCP Deployment Agent, or if it is not on port 8000, then the
URL returned is always incorrect. You must revise this URL address when you
use it by replacing the IP address and port with the IP address and port number
of the xCP application host.
For development environments where installation of components and setting of

ports may be more flexible, you can also resolve this problem by installing both
components on the same machine and installing the xCP application host on port
8000. “Configuring the Application Server for xCP applications” on page 31 and
“Installing the xCP Deployment Agent” on page 75 provide instructions.
10.11.1 Configuring xCP Designer to Show the Correct URL

If you are using multiple deployment environments, repeat this procedure each time
you deploy to a different environment.
1. In the folder where you have installed xCP Designer, edit the xcpdesigner.ini
file. Find the following parameters:
-Dxcp.application.url.host=
-Dxcp.application.url.port=8000
These are the default settings. When rest.application.url.host is set to nothing,

the system uses the IP address of xCP Deployment Agent.
2. Set the rest.application.url.host parameter to the IP address of the xCP
application host.

10.12. xCP Viewer is not displaying document for application with CAS
3. If the xCP application host is not installed on port 8000, then set the
xcp.application.url.port parameter to the correct port number.
4. Restart the xCP Designer.
If you do not do this, then you need to revise the URL address in the web browser
each time you deploy an xCP application by replacing the IP address and port
number with that of the xCP application host.
10.12 xCP Viewer is not displaying document for

application with CAS
Problem
When xCP application with SSL is enabled with CAS authentication, the xCP Viewer
in Chrome or Firefox browser displays the content but xCP Viewer in Internet
Explorer browser blocks the content at runtime.
Cause
Depending on the browser settings, the content is either blocked or displayed.
Resolution
You must access the content either by loading over HTTPS or a proxy server.
10.13 Process Integrator Fails to Start Listener

Problem
Process Integrator fails to start the listener for JMS inbound activity configured to
JMS.
Resolution
Add a custom JMS vendor-specific InitialContext. Create a standard BOF module
that contains the following:
• ClassName: SampleJMSInitialContextModule
• Primaryclass: com.documentum.bps.jms.SampleJMSInitialContexModule
• Interfaceclass: com.documentum.bps.JMSInitialContext
• ImplementationJar: The Jar containing the specified implementation and any
vendor-specific .jar files.
Note: The bpm_commons.jar file contains the package com.documentum.bps.*

Example 10-1: Sample code for providing initial contexts for JMS activity
templates
/**
* Interface for providing Initial Contexts for JMS Activity Templates.
*/
public interface JMSInitialContext {
/**
* Initial Content Factory name that would be shown in the Activity template UI.
* @return InitialContext Factory Name.
*/
public String getInitialContextFactoryName();
/**
* URL hint that would be shown in the Activity template UI.
* @return Provider URL Format hint.
*/
public String getProviderURLFormat();
}
Example 10-2: Sample code for Tibco support

/*
** Confidential Property of Documentum, Inc.
** (c) Copyright Documentum, Inc. 1991-2002
** All Rights reserved.
** May not be used without prior written agreement
** signed by a Documentum corporate officer.
*/
public class TIBCOJMSInitialContexModule implements IDfModule, JMSInitialContext {
public TIBCOJMSInitialContexModule() {
public String getInitialContextFactoryName(){

return "com.tibco.tibjms.naming.TibjmsInitialContextFactory";
}
public String getProviderURLFormat() {

return "tibjmsnaming://<hostname>:<port>";

10.14. Multi-Select Result List Unable to Send Data to a Stateless Process
10.14 Multi-Select Result List Unable to Send Data to a

Stateless Process
Problem
If a stateless process has an input parameter, a multi-select Result List widget cannot
send data to this process during migration.
Cause
If Allow selection of multiple items is selected in a Results List widget, then in any
expression where the selected row node of this Results List widget is used, the
system changes the data type of all child attributes to multi-value instead of single
value. Expressions using these child nodes show as errors in Problems tab.
Resolution
You must manually correct the errors in Problems tab.
10.15 FAST 11 hint on SQL query results in

performance issue
Problem
The FAST 11 hint added to a SQL query, originating in xCP components, results in
application performance issues.
Resolution
To enable this fix, perform following steps:
1. Go to:
<xCP_Designer_path>\maven\com\emc\xcp\xcpdatalist-impl\2.3.x
2. Unzip the xcpdatalist-impl-x.jar file.

3. Edit the Factory.properties file by setting the value of
SKIP_OPTIMIZE_TOP_ROW as true and ZIP the file again.
4. Delete the.m2 folder from the home directory (e.g. C:\Users\<user>\.m2).
5. Start xCP Designer and redeploy the application.
6. Clear the browser cache on the client machine and test the scenario again.

10.16 BPS conflicts with DFS deployed on the same

Tomcat instance
Problem
When BPS is deployed to the same Tomcat instance as DFS or any other DFS-based
application, the functionality fails with ClassCastException due to the classloading
conflicts.
Resolution
Add the following in the dfc.properties file located at bps.war/WEB-INF/lib:dfc.
bof.classloader.enable_extension_loader_first = false
10.17 xCP Viewer with HTTPS mode

Problem
If an xCP application is using SSL, xCP viewer fails.
Resolution
The xCP Viewer delivers only secure content when the request is made over a secure
channel. If the application server receives a request over HTTPS for viewing the
content, only HTTPS URL from ACS is retrieved. This HTTPS ACS URL is used to
get the corresponding content and display the same on the viewer. For more
information about configuring SSL, refer the OpenText Documentum Platform and
Platform Extensions Installation Guide.

OpenText Documentum XCelerated Composition Platform CE 22.2 - Deployment Guide English (EDCPKL220200-IGD-En-01)

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OpenText Documentum XCelerated Composition Platform CE 22.2 - Deployment Guide English (EDCPKL220200-IGD-En-01)

Uploaded by

Copyright:

Available Formats

OpenText™ Documentum™ xCelerated

This guide describes how to provision Documentum xCelerated

Open Text Corporation

275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1

Copyright © 2023 Open Text. All Rights Reserved.

No Warranties and Limitation of Liability

2 Manually provisioning an xCP environment ......................... 15

EDCPKL220200-IGD-EN-01 Deployment Guide iii

2.14.3 Deploying the BAM server ............................................................... 49

iv OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

2.18.9 Service endpoint configuration ......................................................... 89

EDCPKL220200-IGD-EN-01 Deployment Guide v

2.25.3.3 Install and configure LDAP Data Adapter ........................................ 133

3 Deploying an xCP Application ............................................. 149

vi OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

3.15 Integrating the PHS into xCP ......................................................... 175

4 Deploying and Configuring xCP Designer and Runtime

5 Uninstalling an Application .................................................. 191

6 Administering the xCP System ............................................ 199

EDCPKL220200-IGD-EN-01 Deployment Guide vii

7 Migrating Applications .......................................................... 209

8 xCP Process Manager ........................................................... 219

9 Setting up xCP in Kubernetes Environment ....................... 235

10 Troubleshooting Manually-provisioned Environments ..... 237

viii OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

10.2 Application Deployment Problems .................................................. 237

EDCPKL220200-IGD-EN-01 Deployment Guide ix

1.1 Deployment environments overview

Note: The information in this guide is for application and system

• Common Documentum components include:

– Documentum Content Intelligence Services (CIS)

EDCPKL220200-IGD-EN-01 Deployment Guide 11

1.2 Deployment methods

1.3 Managing environments

1. Provision environments: To provision environments manually, install

2. Deploy applications. “Overview of Deploying an xCP Application” on page 149

1.4 Upgrading an environment

xCelerated Management System to xCP Deployment Agent

12 OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

to deploy the application package to a staging or production environment, instead of

1.5 Updated attributes for REST API properties

Old attribute name New attribute name

Note: The attribute, xcp.security.logon.challenge.suffix, has been

1.6 Security configuration

Security Configuration Details or Instructions

EDCPKL220200-IGD-EN-01 Deployment Guide 13

Security Configuration Details or Instructions

14 OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

Deploying an xCP application includes configuring application deployment

EDCPKL220200-IGD-EN-01 Deployment Guide 15

2.2 Manual provisioning

1. Download and install Documentum components and third-party software into a

Prerequisites for Source of information

16 OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

2.4 Installing and configuring xCP components and

Required/Optional Component Source of Information

EDCPKL220200-IGD-EN-01 Deployment Guide 17

Required/Optional Component Source of Information

2. Record your environment information. You may need the following

• xCP application host username and password

18 OpenText™ Documentum™ xCelerated Composition Platform EDCPKL220200-IGD-EN-01

• xCP application port

Use this information to deploy applications using xCP Deployment Agent.

3. The following files are available for your reference:

1. Download the ImageServices_BOCS_..zip file from the OpenText MySupport