Open Text

OpenText™ Exstream
Communications Server Administration

Guide
This guide contains information about how to set up and

maintain the components and repositories used to run
Communications Server, service gateway, and task scheduler
applications as well as how to deploy and run web applications,
such as WorkShop, StoryBoard, ReTouch, and Supervisor.
CCMSYS160400-AGD-EN-01
OpenText™ Exstream
Communications Server Administration Guide
Rev.: 2018-Apr-13
This documentation has been created for software version 16.4.
It is also valid for subsequent software versions as long as no new document version is shipped with the product or is
published at https://knowledge.opentext.com.
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 © 2018 Open Text. All Rights Reserved.

Trademarks owned by Open Text.
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
Part 1 Getting started 11
1 Tenancy concept ..................................................................... 13
2 What components are required to get started? .................... 15
3 Steps checklist – Setting up the Exstream environment ..... 19
4 Setting up OTDS for Exstream ............................................... 21

4.1 Access control concepts .................................................................. 21
4.2 Options and recommendations ......................................................... 24
4.2.1 Option 1 – Separate OTDS backends ............................................... 25
4.2.2 Option 2 – Single OTDS backend ..................................................... 26
4.2.3 Option 3— Single-tenant Exstream environments .............................. 27
4.3 OTDS configuration requirements .................................................... 28
4.4 Assigning access roles .................................................................... 31
4.5 Examples – Setting up OTDS for Exstream ....................................... 34
4.5.1 Example: Installing OTDS ................................................................ 35
4.5.2 Example: Configuring a multi-tenant OTDS ....................................... 37
4.5.3 Example: Adding a tenant OTDS ...................................................... 45
4.5.4 Example: Configuring a tenant OTDS ............................................... 45
4.6 Troubleshooting .............................................................................. 52
5 Preparing the database ........................................................... 53
6 Setting up the Exstream environment ................................... 57

6.1 About the ss_tenantadmin utility ....................................................... 57
6.2 Configuring the management gateway and creating the multi-tenant
repository ....................................................................................... 57
6.3 Adding a tenant ............................................................................... 64
6.4 Adding a management gateway ....................................................... 71
6.5 Creating the multi-tenant or tenant repository manually ...................... 72
6.6 Setting up a secure channel for management gateway ...................... 73
6.7 Configuring the management gateway for a virtual host ..................... 75
7 Managing tenants .................................................................... 77

7.1 Listing the tenants ........................................................................... 77
7.2 Obtaining the tenant ID .................................................................... 78
7.3 Changing the tenant name, description, or connection profiles ........... 79
7.4 Adding an OTMM or Content Server connection profile to a tenant ..... 80
8 Implementing OpenText Private Help Server ........................ 87

8.1 Implementing the OpenText Private Help Server for Exstream ........... 87
OpenText Exstream – Communications Server Administration Guide iii

Table of Contents
8.1.1 Downloading the OpenText Private Help Server Kit and product
online help files ............................................................................... 88
8.1.2 Deploying the Private Help Server .................................................... 88
8.1.2.1 Troubleshooting the Private Help Server ........................................... 95
8.1.3 Redirecting help calls to Private Help Server ..................................... 96
Part 2 License management 97
9 Managing license files ............................................................ 99
10 Measuring transactions and MicroMessages for

licensing purposes ................................................................ 101
Part 3 Managing applications with Control Center 103
11 Getting started in Control Center ......................................... 105

11.1 Steps checklist in Control Center .................................................... 105
11.2 Connecting to a tenant environment from Control Center ................. 106
11.3 Understanding the Control Center user interface ............................. 107
11.4 Changing the font and language options ......................................... 108
11.5 Tenant and host property descriptions ............................................ 109
12 Creating a domain ................................................................. 111

12.1 Understanding domains ................................................................. 111
12.2 What repositories does a domain require ........................................ 115
12.2.1 About processing statistics ............................................................ 117
12.2.2 Tracking repository usage notes ..................................................... 117
12.2.3 About job tracking ......................................................................... 118
12.3 Creating a domain ......................................................................... 119
12.3.1 Updating the repository connection profiles ..................................... 120
12.3.2 Deleting a domain ......................................................................... 120
12.4 Approval options for theme resources ............................................. 120
12.5 Controlling access to domains ....................................................... 122
13 Creating repositories ............................................................ 125

13.1 Configuring repository settings ....................................................... 125
13.1.1 Specifying custom arguments for the database driver ...................... 129
13.2 Creating a repository in Control Center ........................................... 129
13.3 Creating a repository manually ....................................................... 130
13.4 Linking a repository to a domain ..................................................... 134
13.5 Adjusting repositories .................................................................... 134
14 Setting up Communications Server applications ............... 139

14.1 Setting up a Communications Server application ............................. 139
14.2 Deploying a Communications Builder Project .................................. 140
iv OpenText Exstream – Communications Server Administration Guide

Table of Contents
14.3 Setting up startup parameters for an Exstream production engine .... 143
14.4 Testing a Communications Server application using FastCopy ......... 144
14.5 Versioning of services in Communications Server applications ......... 145
14.5.1 Searching for services ................................................................... 146
14.6 Configuring the thread pool for the queues ..................................... 147
15 Setting up a service gateway ............................................... 151
16 Archiving documents ............................................................ 153

16.1 Adding an Archiver application ....................................................... 153
16.2 Configuring a task for Archiver ....................................................... 154
16.3 Adding a Content Server repository ................................................ 154
16.4 Configuring the Content Server repository ...................................... 154
17 Managing applications .......................................................... 157

17.1 Starting, stopping, and restarting applications ................................. 157
17.2 Administering applications on remote hosts .................................... 158
17.3 Exploring the management gateway base directory ......................... 158
17.4 Scheduling tasks in a domain ......................................................... 158
17.4.1 Setting up schedules ..................................................................... 161
17.5 Deleting applications ..................................................................... 163
17.6 Updating and exporting application properties ................................. 164
17.6.1 Communications Server application properties ................................ 164
17.6.2 Service gateway and task scheduler application properties .............. 167
17.7 Startup options and accounts for applications ................................. 168
17.8 Configuring Java parameters for applications .................................. 169
17.9 Generating dump files for applications on Windows ......................... 171
18 Logging in Control Center .................................................... 173

18.1 About the logs ............................................................................... 173
18.2 Specifying the log level .................................................................. 174
18.3 Creating a new log file at startup .................................................... 174
18.4 Log file truncation .......................................................................... 175
18.5 Editing log providers – reference .................................................... 175
18.5.1 General provider settings ............................................................... 176
18.5.2 Console provider specific settings .................................................. 176
18.5.3 Log file provider specific settings .................................................... 177
18.5.4 Log database provider specific settings .......................................... 178
18.6 Debugging applications ................................................................. 178
18.7 Using database logging ................................................................. 179
19 Maintaining Exstream components ..................................... 181

19.1 Finding installed components ......................................................... 181
OpenText Exstream – Communications Server Administration Guide v

Table of Contents
Part 4 Managing applications with command line utilities 183
20 About the command line utilities ......................................... 185

20.1 Getting started with the command line utilities ................................. 186
20.2 Scenarios for the command line utilities .......................................... 186
21 Arguments and descriptions ................................................ 189

21.1 ss_scm utility arguments and descriptions ...................................... 189
21.2 ss_territory utility arguments and descriptions ................................. 194
21.3 ss_deploy utility arguments and descriptions ................................... 204
21.4 ss_rcp utility arguments and descriptions ........................................ 206
21.5 Optional arguments (all utilities) ..................................................... 207
22 Examples and troubleshooting ............................................ 209

22.1 Examples ..................................................................................... 209
22.1.1 Creating a domain ......................................................................... 209
22.1.2 Creating a repository ..................................................................... 209
22.1.3 Creating a Communications Server application ............................... 210
22.1.4 Creating a service for a Communications Server application ............ 210
22.1.5 Deploying a release package to a Communications Server .............. 211
22.1.6 Modifying a Communications Server service ................................... 211
22.1.7 Starting a Communications Server service ...................................... 212
22.1.8 Starting a Communications Server service and disable its input
connectors .................................................................................... 212
22.1.9 Disabling input connectors of a running Communications Server
service ......................................................................................... 212
22.1.10 Enabling input connectors of a running Communications Server
service with paused input connectors ............................................. 212
22.1.11 Checking if a Communications Server service is running ................. 213
22.1.12 Stopping a Communications Server service .................................... 213
22.2 Troubleshooting ............................................................................ 213
Part 5 Administering web applications 215
23 About the web applications .................................................. 217
24 Deploying the web applications ........................................... 219
25 Editing web application properties ...................................... 221

25.1 Service gateway properties ............................................................ 221
25.1.1 Service gateway secure mode ....................................................... 223
25.2 Management gateway properties ................................................... 224
25.3 Connection properties ................................................................... 226
25.4 Properties for StoryBoard, ReTouch, Writer and CAS browser ......... 229
vi OpenText Exstream – Communications Server Administration Guide

Table of Contents
25.4.1 Managing configuration file resources ............................................. 229

25.4.2 configuration.json .......................................................................... 230
25.4.3 configuration_ipad.json .................................................................. 233
25.4.4 devicesConfiguration.json .............................................................. 237
25.4.5 properties.json .............................................................................. 238
25.4.5.1 Types ........................................................................................... 239
25.4.5.2 Validators ..................................................................................... 241
25.4.5.3 Properties ..................................................................................... 244
25.4.5.4 Attributes ...................................................................................... 246
25.4.5.5 Categories .................................................................................... 248
25.4.5.6 Objects ......................................................................................... 250
25.4.5.7 Filtering attributes and properties ................................................... 251
25.4.6 simulationSettings.json .................................................................. 252
25.4.6.1 Types ........................................................................................... 252
25.4.6.2 Validators ..................................................................................... 254
25.4.6.3 Settings ........................................................................................ 256
25.4.6.4 Templates .................................................................................... 257
25.4.6.5 Themes ........................................................................................ 259
25.5 Text editor properties .................................................................... 261
26 Running the web applications .............................................. 263

26.1 Accessing WorkShop .................................................................... 263
26.2 Accessing Supervisor .................................................................... 266
26.3 Accessing StoryBoard ................................................................... 269
26.4 Accessing ReTouch ...................................................................... 270
26.5 Accessing Writer ........................................................................... 271
26.6 Accessing Rule Editor ................................................................... 272
26.7 Accessing Control ......................................................................... 273
27 Monitoring the web applications .......................................... 275

27.1 Service gateway REST log ............................................................ 275
27.2 Management gateway REST log .................................................... 276
27.3 Application logs ............................................................................. 277
28 Solr integration in WorkShop and Supervisor .................... 279

28.1 Standalone mode implementation .................................................. 279
28.2 Cloud mode implementation .......................................................... 286
28.3 Updating Collect cores after meta model changes ........................... 297
29 Additional Control configuration ......................................... 299
Part 6 Maintaining the repositories 301
30 About maintaining Exstream repositories .......................... 303
OpenText Exstream – Communications Server Administration Guide vii

Table of Contents
31 Deleting expired content ....................................................... 305

31.1 Recommendations for scheduling the deletion tasks ........................ 306
31.2 Scheduling a Task Scheduler to delete or expire content ................. 306
31.3 DBQ example ............................................................................... 308
32 Running index maintenance (Microsoft SQL Server) ........ 309

32.1 Index maintenance recommendations (Microsoft SQL Server) ......... 309
32.2 Running index maintenance via SQL Server Agent (Microsoft SQL
Server) ......................................................................................... 310
33 Rebuilding or coalescing indexes (Oracle Database) ........ 313

33.1 Coalescing indexes with coalesce_indexes procedure (Oracle
Database) ..................................................................................... 313
33.2 Rebuilding indexes (Oracle Database) ............................................ 314
33.2.1 Ensuring sufficient free space (Oracle Database) ............................ 316
34 Scheduling index maintenance or coalescing via task

scheduler ................................................................................ 319
35 Gathering statistics (Oracle Database) ............................... 323

35.1 Gathering sample statistics (Oracle Database) ................................ 323
35.2 Gathering system statistics (Oracle Database) ................................ 325
36 Troubleshooting performance via EXPLAIN PLAN

(Oracle Database) .................................................................. 327
37 Backing up the repositories ................................................. 329
Part 7 Installing and applying hotfixes 331
38 About installing and applying hotfixes ............................... 333
39 Installing a hotfix ................................................................... 335
40 Applying a hotfix to the repositories ................................... 337

40.1 Applying a hotfix to the tenant repository ........................................ 338
40.2 Applying a hotfix to the repositories with Control Center ................... 340
40.3 Applying a hotfix to the repositories with the hotfix-repo script .......... 341
40.4 Applying a hotfix to the repositories manually .................................. 343
41 Applying a hotfix to the web applications ........................... 345
Part 8 Running parallel versions 347
42 Running parallel versions ..................................................... 349
Part 9 Profiling and tuning your environment 351
viii OpenText Exstream – Communications Server Administration Guide

Table of Contents
43 About profiling ....................................................................... 353
44 Setting up Profiler ................................................................. 355

44.1 Enabling Profiler ........................................................................... 355
44.2 Configuring Profiler ....................................................................... 356
44.2.1 Configuring a Profile provider ......................................................... 356
44.2.2 Applying event filters ..................................................................... 359
44.2.3 Flushing Profiler data to the output file ............................................ 360
44.2.4 Scheduling the Profiler counter events ............................................ 360
44.3 Analyzing profiler output ................................................................ 360
Part 10 Using the document tracking framework 361
45 About the document tracking framework ........................... 363
46 Setting up the document tracking framework .................... 367

46.1 Steps checklist .............................................................................. 367
46.2 Installing the document tracking framework ..................................... 367
46.3 Creating the document tracking repository ...................................... 368
46.4 Configuring the document tracking framework ................................. 369
47 Analyzing the tracking data .................................................. 371
48 Maintaining the document tracking framework .................. 377
Part 11 Encryption tool 379
49 Using the security tool on Windows .................................... 381
50 Using the security tool on UNIX/Linux ................................ 387
51 Replacing certificate files ..................................................... 393
52 Troubleshooting Encryption tool ......................................... 395

52.1 Lost key ........................................................................................ 395
52.2 Management Gateway does not start ............................................. 396
OpenText Exstream – Communications Server Administration Guide ix

Part 1
Getting started
Chapter 1
Tenancy concept
Exstream supports both single-tenant and multi-tenant environments. In single-

tenant environments, a company or organization runs the Exstream components on
one or more computers or hosts. The company develops and manages its own
Communications Server and repositories.
In multi-tenant environments, several client organizations (or tenants) share one or

more instances of the framework and management gateway. Each tenant in the
Exstream environment has a unique ID and runs its own Communications Server
applications. All the applications and data in the environment are separated by
tenant IDs. This allows tenants to share databases or schemas or to use separate
databases or schemas.
Each tenant has its own users in OTDS, which controls who can access the tenant’s
applications and data. When users log on to WorkShop, StoryBoard, Control Center,
Describer, etc. they can only view and access the data and resources that belong to
their tenant. For example, if an Exstream environment has two tenants, tenant 1
and tenant 2, then when a user from Tenant 1 logs on to Control Center, only the
applications and repositories that belong to Tenant 1 are displayed.
Example environment (two tenants)

The Exstream components, repositories, and OTDS servers can be set up in a
number of ways. The image below shows an example environment with two
tenants who share a single framework and management gateway instance.
Each tenant has its own set of:
• Communications Server applications, which run on the shared framework
and management gateway.
• Users in OTDS who can access the tenant’s environment.
• Repositories for storing design resources, queue data, processing statistics,
etc. In this example, these reside in a database server in the central
environment.
OpenText Exstream – Communications Server Administration Guide 13

Chapter 1 Tenancy concept
Figure 1-1: Tenants with separate users, applications, and repositories
Note: This figure does not show all the components required in the
Exstream environment.
Role based access control

Roles control the access and permissions in the Exstream environment. The overall
environment has a group of multi-tenant administrators who manage the tenants via
the command line utilities. Each tenant has its own users who are assigned to roles
such as, tenant administrators, tenant users, reviewers, and on demand users. These
roles have access to WorkShop, StoryBoard, Control Center, Supervisor, Describer,
Communications Builder, etc. Access levels to CAS resources and types in the
metadata model can also be tied to the roles.
Metadata model
Each tenant in the Exstream environment has its own metadata model, which
contains all the properties used in the tenant’s Exstream solutions. The metadata
model is versioned and is stored centrally. This allows the central model to be
accessed by solution developers at design time and by the Exstream applications at
runtime in development, testing, and production environments.
14 OpenText Exstream – Communications Server Administration Guide

Chapter 2
What components are required to get started?
After you install Exstream, you must set up the following underlying components:
• Multi-tenant repository
• Management gateway
• Multi-tenant OTDS
You must also set up the following components for each tenant:
• Tenant repository
• Tenant OTDS
This section describes each component and how the components can be arranged in
environments with single tenants and multiple tenants. For information about the
steps to set up the components, see “Steps checklist – Setting up the Exstream
environment“ on page 19.
In this section
• “Underlying components” on page 15
• “Tenant related components” on page 16
• “Components in single-tenant environments” on page 17
• “Components in multi-tenant environments” on page 17
Underlying components
Multi-tenant repository
This repository stores information about the entire Exstream environment,
which includes the following:
• Tenants names, descriptions, etc.
• Hosts in the environment.
• Mappings between each tenant in Exstream, the tenant OTDS, and the tenant
repository.
All information in the multi-tenant repository is assigned a tenant ID ensuring

that one tenant cannot access another tenant’s applications or data.
Management gateway
The management gateway connects the Exstream applications on the computer
to OTDS, the tenant and multi-tenant repositories, and the Exstream desktop
tools, such as Control Center and Communications Builder.

Chapter 2 What components are required to get started?
The management gateway is part of the Communications Server installation

component. On Windows, the management gateway service uses the local
administrator account and requires local administrator access to create and
remove other Windows services. The management gateway Windows service is
called StreamServe Management Gateway <version>. The management
gateway process is called ManagementGateway.
The management gateway uses three ports. The default port numbers are:
• 28700 – This port is used for communications between the Exstream

applications, OTDS, repositories, and desktop tools.
• 28701 – This port is used for communication made via the REST API.
• 28702 – This port is used for internal notifications.
On Linux, you can change the default ports used for communications and for
internal notifications during the Communications Server installation. It is not
possible to change the default port used for the REST API, that port will always
be the communications port +1. On Windows, you cannot change the ports.
Multi-tenant OTDS
This contains the multi-tenant administrators for the overall environment.
Multi-tenant administrators have access to the ss_tenantadmin tool, which is
used to set up the management gateways and add tenants to the overall
environment. This component is always created in OTDS.
Tenant related components

Each tenant requires access to a tenant repository and a tenant OTDS.
Tenant repository
This repository stores tenant specific information which includes:
• The metadata model for the tenant.

• Applications, domains, and computers or hosts that are part of the
environment.
• Resources available via the common asset service, such as templates, images,
and Communications Builder Project files.
• Security information.
All information in the tenant repository is assigned a tenant ID.

In multi-tenant environments, it is possible for several tenants to share a tenant
repository. In this scenario, each tenant has its own metadata model, resources,
etc., in the repository. Because all the information is assigned a tenant ID, one
tenant cannot access or view another tenant’s information.
Tenant OTDS
This contains the users with access to the tenant’s environment, who are
assigned roles such as tenant administrators, tenant users, reviewers, and on-

demand users. These are the users who access the Exstream design and
administration tools and the web applications.
The tenant OTDS is always created in OTDS.
Components in single-tenant environments

In single tenant environments there is one multi-tenant repository and one multi-
tenant OTDS. One or more management gateways can be used for running the
Exstream applications. If several management gateways are used, they all connect to
the same multi-tenant repository. There is one tenant repository and one tenant
OTDS.
Figure 2-1: Single-tenant environment
Components in multi-tenant environments

In Exstream environments with multiple tenants there is one multi-tenant
repository. One or more management gateways can be used for running the
Exstream applications. If several management gateways are used, they all connect to
the same multi-tenant repository.
There are two options for setting up the tenant repository – tenants can share a
single tenant repository or use separate tenant repositories. Using separate tenant
repositories is suitable for environments where each tenant requires a high level of
data isolation or where you expect a high load on the tenant repositories.
There is one multi-tenant OTDS for the users that manage the overall environment.
Each tenant is connected to a tenant OTDS. For more information about the options
for setting up OTDS, see “Options and recommendations” on page 24.

Chapter 2 What components are required to get started?
Figure 2-2: Example multi-tenant environment: Tenants sharing a tenant

repository
Figure 2-3: Example multi-tenant environment: Tenants using separate tenant

repositories

Chapter 3
Steps checklist – Setting up the Exstream
environment
This section lists the high-level steps required to set up the Exstream environment.
Steps: See:
Step 1 – Set up OTDS for Exstream “Setting up OTDS for Exstream“
on page 21
Step 2 – Prepare the database for the “Preparing the database“ on page 53
Exstream repositories
Step 3 – Configure the management gateway “Configuring the management gateway and
and create the multi-tenant repository creating the multi-tenant repository”
on page 57
Step 4 – Add a tenant and set up the tenant “Adding a tenant” on page 64
repository
Step 5 – (Optional) – Add more management “Adding a management gateway”
gateways to the Exstream environment on page 71
Step 6 – (Optional) – Set up a secure channel “Setting up a secure channel for management
for management gateway gateway” on page 73
Step 7 – (Optional) – Configure the “Configuring the management gateway for a
management gateway for a virtual host virtual host” on page 75
Next steps
After the environment is set up, users assigned the appropriate roles can log on to
Control Center, Communications Builder, and Describer.
For information about logging on to a tenant environment and preparing to run

Exstream applications in Control Center, see “Steps checklist in Control Center”
on page 105.

Chapter 4
Setting up OTDS for Exstream
4.1 Access control concepts

This section describes some key concepts relating to how the access control in
Exstream works.
Concept: Each Exstream tenant has its own users

One Exstream environment can have a single tenant or can have multiple tenants. A
tenant can be a customer, company, or organizational unit that has its own set of
users. When users log on as a tenant, their view of the system is based on their
tenant. Users from one tenant cannot see or access another tenant’s applications or
data.
In the image below, John, Robert, and Amy from Tenant A have access to the
applications, repositories, and data that belong to Tenant A. While Mary, Sam, and
Fiona have access to the applications, repositories, and data that belong to Tenant B.
Concept: Roles control access and permissions

The users for each Exstream tenant are assigned to one or more roles. The roles
control the following:
• Which desktop applications and web applications users can access.
• Which permissions users have in each application.
For example, if John is assigned to the tenant administrator role, John can access
Control Center, Communications Builder, Describer, and the web applications.
Whereas, if Robert is assigned to the Reviewer role, Robert can only access the web
applications.

Chapter 4 Setting up OTDS for Exstream
Concept: Tenant OTDS

The users for one tenant are created in a component called the tenant OTDS. This
component is created in OTDS.
When a tenant is added to the Exstream environment, it is connected to its tenant

OTDS (see “Adding a tenant”). This connection controls who can log on to the
tenant’s Exstream environment.
The following image shows how Tenant A is connected to the tenant OTDS for
Tenant A, which contains the users John, Robert, and Amy. While Tenant B is
connected to the tenant OTDS that contains the users Mary, Sam, and Fiona.
Concept: Multi-tenant users manage the overall environment

In order to manage the overall environment, there is a group of users who can add
tenants via the management gateway. These users cannot see or access any of the
applications, repositories, or data that belong to the tenants.
The image below shows how Linda and Bob have access to the management
gateway, but no access to either tenant’s applications or data.

4.1. Access control concepts
The group of users who manage the overall environment are assigned the multi-
tenant administrator role. Multi-tenant administrators only have access to the
Exstream ss_tenantadmin utility.
Concept: Multi-tenant OTDS

The multi-tenant administrator users are created in a component the multi-tenant
OTDS.
When the management gateway is configured, it is connected to the multi-tenant

OTDS. After this, users assigned to the multi-tenant administrator group can use the
ss_tenantadmin utility.

4.2 Options and recommendations

To set up OTDS for Exstream you need to configure the following components:
• Multi-tenant OTDS
This contains the users who are assigned the multi-tenant administrators role
and who manage the overall environment.
• Tenant OTDS
This contains the users for each Exstream tenant. These users have access to the
tenant’s environment in Exstream via Communications Builder, Control Center,
the web applications, etc.
Options for setting up these components
There are different ways you can configure these components:
• Option 1 – Use Separate OTDS backends

You can configure each of these components in a separate OTDS backend. This
means each Exstream tenant has its own OTDS backend with its own users,
groups, partition, and resource.
This approach has the highest level of security, as the users for each tenant are in
separate OTDS backends. It also allows the OTDS server for each tenant to be
managed separately.
For more details, see “Option 1 – Separate OTDS backends ” on page 25.
• Option 2 – Use a single OTDS backend with a partition for each tenant
You can configure all these components in one OTDS backend that is shared by
multiple Exstream tenants. With this approach, each Exstream tenant has its own
partition and own resource in the OTDS backend.
This approach allows the OTDS server to be managed centrally by a single OTDS
administrator.
For more information, see “Option 2 – Single OTDS backend ” on page 26.
• Option 3 – Single OTDS backend with all Exstream users and groups (Only
applies to single-tenant Exstream environments)
In an Exstream environment with a single tenant, you can use a single OTDS
server or backend that contains all the Exstream groups.
For more information, see “Option 3— Single-tenant Exstream environments ”
on page 27.
OTDS Requirements for Exstream tenants

• There are many ways you can set up OTDS for Exstream. However, each
Exstream tenant can only be connected to one OTDS backend. It is not possible to
connect an Exstream tenant to several different OTDS backends or OTDS servers.

4.2. Options and recommendations
Note: The Exstream multi-tenant OTDS and tenant OTDS are written in italics
throughout this section to distinguish these components from OTDS components.
Understanding the OTDS tenancy concept

OTDS supports running multiple tenant backends in a single OTDS server. Each
backend has its own set of OTDS data: resources, user partitions, access roles,
authentication handlers, and system attributes. The default installation of OTDS
includes a default backend. Tenant backends can be added to OTDS via the
command line interface.
See OpenText Directory Services - Tenant Management Guide (OTDS-CCS) for more
information about tenants in OTDS and the concepts around the OTDS default
backend and tenant backends.
4.2.1 Option 1 – Separate OTDS backends

If you want to use a separate OTDS backend for each Exstream tenant, OpenText
recommends that you use an OTDS installation with multiple backends and that you
configure OTDS in the following way:
• Configure the multi-tenant OTDS in the default OTDS backend. This backend has
its own Exstream partition, resource and users. It will only contain the group for
the multi-tenant administrators (OTDS group name: strsmultitenantadmins).
• Configure the tenant OTDS for each Exstream tenant in a separate OTDS tenant
backend. This requires that you add a tenant to OTDS for each tenant in your
Exstream environment. Each Exstream tenant then has its own OTDS backend
with an Exstream partition, resource, users, and groups (i.e. tenant
administrators, tenant users, customized groups, etc. with the OTDS group
names: strstenantusers, strstenantadmins, <customized groups>, etc.).
Figure 4-1: Example configuration – Exstream multi-tenant environment

Figure 4-2: Example configuration – Exstream single tenant environment
It is also possible to use separate OTDS servers for each Exstream tenant. In this
scenario, each Exstream tenant will still have its own Exstream resource, user
partition, groups, etc., but these are created in separate OTDS servers.
4.2.2 Option 2 – Single OTDS backend

If you want to use a single OTDS server that is shared by multiple Exstream tenants,
OpenText recommends that you configure OTDS in the following way:
• In OTDS, create one partition for each Exstream tenant and one resource for each
Exstream tenant.
• Assign the partition for each Exstream tenant to the resource for each Exstream
tenant.
• Assign the users or groups from each Exstream tenant partition to the Exstream
groups in the strs.role partition.
• Create the users who are assigned to the strsmultitenantadmins group in the
strs.role partition. Note the multi-tenant administrators are the only users that
should be created in the strs.role partition.
• Create a separate resource that is assigned to the strs.role partition.

4.2. Options and recommendations
Figure 4-3: Example configuration: Two Exstream tenants in a single OTDS

backend
This example shows a single OTDS backend that is shared by two Exstream tenants
– Tenant A and Tenant B. Each Exstream tenant has its own partition and own
resource for Exstream. The users from the groups in each tenant’s partition are
assigned to the Exstream groups in the strs.role partition.
The users assigned to the strsmultitenantadmins group are created in the strs.
role partition. The strs.role partition is assigned to a separate resource, which is
connected to the management gateway when you set up the environment (see
“Configuring the management gateway and creating the multi-tenant repository”
on page 57).
4.2.3 Option 3— Single-tenant Exstream environments

In an Exstream environment with a single tenant, you can use a single OTDS server
or backend that contains all the Exstream groups.

Figure 4-4: Example OTDS configuration: Single-tenant Exstream

environments
4.3 OTDS configuration requirements

This section describes the configurations that are required in OTDS for Exstream.
Supported OTDS versions

• For information about the supported OTDS versions, see OpenText Exstream 16.4
Release Notes.
Installing OTDS
You can download OTDS from OpenText My Support.
For information about installing OTDS, see OpenText Directory Services - Installation
and Administration Guide (OTDS-IWC).
For information about adding tenant backends to OTDS, see section 1.1 “To add a
tenant” in OpenText Directory Services - Tenant Management Guide (OTDS-CCS)
Required OTDS backend configurations for Exstream

You need to make the OTDS configurations for Exstream in each OTDS backend or
OTDS server separately. You can use the OpenText Administration Client or the
OTDS web administration client to make these configurations in the default OTDS
backend. You must use the web administration client to make these configurations
in an OTDS tenant backend. You activate the resource via the OTDS API.

4.3. OTDS configuration requirements
Required configurations
• strs.role partition
You must create a partition with the name: strs.role
• Exstream groups
You must create the appropriate Exstream groups in the strs.role partition.
• If the OTDS backend will be connected to the management gateway, create
the group:
Multi-tenant strsmultitenantadmins
administrators
(MTA)
• If the OTDS backend will be connected to a tenant, create the groups:
Tenant strstenantadmins
administrators
Tenant users strstenantusers
Reviewers strsreviewers
On-demand strsondemandusers
users
Content Author strsbcausers
users
<Customized <customized group>
group>
• Assign users to the groups
You must assign users or groups to the Exstream groups.
We recommend that the user or users assigned to the strsmultitenantadmins
group have Never expire as a password policy in OTDS.
Tip: The user name and password for the user assigned to the
strsmultitenantadmins group is required to configure the Exstream
environment.
• Exstream resource
You must create and activate a resource for Exstream. The resource can have any
name.
Tip: The resource ID and secret key are required to configure the Exstream
environment.
• Assign partitions, groups, or users to the resource
You must add the partitions, groups, and users that require access to Exstream to
the default access role of the resource.
• Create a browser user

You must create a user with read access to OTDS. This user must be created in
the strs.role partition but does not need to be a member of any group. This
user must have Never expire as a password policy in OTDS.
Tip: The browser user name and password are required to configure the
Exstream environment.
Design and Production and CAS Browser requirements

For information about how to add users and groups from OTDS to Design and
Production and the CAS Browser, see Adding External Users to a Design Group in
OpenText Exstream Design and Production System Administration in the Exstream
Design and Production documentation set.
OTDS security requirements for the web applications

If you are planning to run Supervisor, WorkShop, or other Exstream web
applications, OpenText recommends you make the following configurations in
OTDS and Tomcat:
• Set the OTDS system attribute directory.auth.XFrameOptions to SAMEORIGIN
to protect against clickjacking vulnerabilities. For more information, see section
12.1 “System Attributes” in OpenText Directory Services - Installation and
Administration Guide (OTDS-IWC).
• Turn off the Tomcat Access Log Valve option in the Tomcat server.xml file to
prevent the OTDS login page from sending the OTDS password parameter as a
query parameter. For more information, see the Apache Tomcat documentation.
• OTDS may attempt to use Windows Integrated Authentication single sign-on
(SSO) by default. If you don't want to use native Windows native SSO, turn off
the OTDS http.negotiate authentication handler. For more information, see
section 4.1 “Using authentication handlers” in OpenText Directory Services -
Installation and Administration Guide (OTDS-IWC).
HTTPS and HTTP communication

By default, Exstream uses HTTPS to communicate with OTDS. To use unsecure
HTTP communication, you must disable HTTPS in both OTDS and in Exstream.
To disable HTTPS communication in Exstream, you use the -unsecure flag when
configuring the connection profiles for OTDS. For more information, see the
following sections:
• “Step 2 – Create the connection profile to the multi-tenant OTDS with the
configure_multitenant_otds action” on page 60
• “Step 2 – Create the connection profile to the tenant OTDS with the
configure_tenant_otds action” on page 66
To disable HTTPS in OTDS, you must add the system attribute

directory.auth.EnforceSSL and set the value to false on the System Attributes page

4.4. Assigning access roles
in the OTDS web client. For more information about disabling HTTPS
communication in OTDS, see the following documentation:
• Section 12.1 “System Attributes” in OpenText Directory Services - Installation and
Administration Guide (OTDS-IWC)
• Section 3.5.1.2 “Using encryption” in OpenText Directory Services - Installation and
Administration Guide (OTDS-IWC)
Note: HTTP communication is only suitable in development and testing
environments.
4.4 Assigning access roles

You assign users and groups to the Exstream access roles in OTDS.
After OTDS is set up for Exstream, tenants can use the OTDS web administration
client to manage their users and assign access roles.
About assigning roles

The Exstream access roles are represented as groups in OTDS. In OTDS, it is possible
to assign one or more users, groups, or organizational units to each Exstream group.
For example, you can assign both the user Bob and the organizational unit Quality
Assurance to the tenant administrator group.
Figure 4-5: Several members assigned to one role
You can also assign one user, group, or organizational unit to several roles.
Permissions are exclusive for each role

The permissions for the access roles are exclusive to the roles. Permissions are not
inherited by other access roles. For example, tenant user permissions are only
available to users with the tenant user role, and tenant administrator permissions are
only available to users with the tenant administrator role.
If a user is assigned several roles, the user has permissions according to all the
assigned roles.
In WorkShop (in the Unversioned resources view), you can control which domains
the OTDS group behind a role can access. For example, you can provide a group
access to the development domain, but prevent the group from accessing the
production domain. When a user logs in to a domain, the user will have the sum of

the permissions according to all the assigned roles with access to the current
domain.
Role descriptions
This section describes the default Exstream roles and their permissions.
Note: If you have added customized groups to the strs.role partition in the
tenant OTDS, you must use the Supervisor application to create the
corresponding roles and assign the roles the appropriate permissions. In
Supervisor, you can also change the permissions for the default Exstream roles
for the tenant.
For detailed information, see Section 10 “Managing roles” in OpenText Exstream

- Supervisor User Guide (CCMWEBRETR-UGD).
• Multi-tenant administrator (MTA)
Full access to the ss_tenantadmin command line utility for adding tenants and
updating tenant information, etc.
No access to Communications Builder, Control Center, Describer, or the web
applications.
• Tenant administrator
Full access to Communications Builder, Control Center, Describer, and the
ss_territory, ss_scm, ss_deploy, and ss_rcp command line utilities.
Access to web applications:
• WorkShop – Access to all views. For example, can publish themes and delete
resources in the Resources view.
• Supervisor – Access to all views, but cannot edit documents in the Review
view.
• StoryBoard – For example, can preview themes.
• ReTouch – For example, can preview documents.
• Tenant user
Full access to Communications Builder.
Some access to the following applications:
• Control Center – For example, starting and stopping applications, and
viewing properties and logs.
• Describer – Viewing models.

• WorkShop – Access to all views. For example, can edit and check in themes in
the Resources view.
• Supervisor – Access to all views except the Roles view.

4.4. Assigning access roles
• StoryBoard – Full access.

• ReTouch – Full access.
• Reviewer
No access to Communications Builder, Control Center, Describer, or the
command line utilities.
• WorkShop – Some access to the Resources view. For example, can review and
approve resources, but cannot edit or delete resources.
• Supervisor – Some access to the Review view. For example, can review and
approve documents, but cannot edit or delete documents.
• StoryBoard – For example, can preview themes.
• ReTouch – For example, can preview documents.
• Content Author user
This group has the same access permissions in the web applications as the tenant
user, however it can only view approved resources in the CAS Browser.
• On-demand user
No access to Communications Builder, Control Center, Describer, or the
command line utilities.
• WorkShop – Some access to the Resources view. For example, can examine
images and texts.
• Supervisor – No access.
• StoryBoard – No access.
• ReTouch – Full access.
Notes about roles and access

• For information about how to add users and groups from OTDS to Design and
Production and the CAS Browser, see Adding External Users to a Design Group in
OpenText Exstream Design and Production System Administration in the Exstream
Design and Production documentation set.
• No log on is required for StoryTeller.

4.5 Examples – Setting up OTDS for Exstream

This section provides examples that describe one way of setting up OTDS for
Exstream in a scenario where separate backends are used for the multi-tenant OTDS
and tenant OTDS.
In these examples, the following type of configuration is made:
• OTDS is installed using Apache Tomcat as the application server.

• HTTPS communication is set up for OTDS with a self-signed certificate.
• The Exstream multi-tenant OTDS is configured in the default OTDS backend.
• The Exstream tenant OTDS is configured in an OTDS tenant backend.
• In both backends, a non-synchronized partition is used and all the users are
manually added.
• In both backends, the strs.role partition is assigned to the Exstream resource.
Figure 4-6: OTDS configuration
Note: The Content group is not configured in this example.
High-level steps
Step: See:
1. Install OTDS. “Example: Installing OTDS” on page 35

4.5. Examples – Setting up OTDS for Exstream
2. In the default backend, configure the multi- “Example: Configuring a multi-tenant

tenant OTDS. OTDS” on page 37
3. Add a tenant backend to OTDS. “Example: Adding a tenant OTDS”
on page 45
4. Configure the tenant OTDS. “Example: Configuring a tenant OTDS”
on page 45
4.5.1 Example: Installing OTDS

This example describes how to configure Tomcat 8 for use with OTDS, how to install
OTDS with Tomcat as the application server, and how to configure HTTPS
communication for OTDS.
This example assumes the following software is already installed on the computer:
• Tomcat 8
• Java Runtime Environment version 1.8.x
For more information about the installation of OTDS, see OpenText Directory Services
- Installation and Administration Guide (OTDS-IWC).
Step 1 – Configure Tomcat for use with OTDS

1. Open the Tomcat Properties dialog box. For example, using the command "C:
\Program Files\Apache Software Foundation\Tomcat8.5\apache-
tomcat-8.5.11\bin\tomcat8w.exe" //ES/<TomcatServiceName>
2. On the Java tab, configure the following settings:
• Initial memory pool

256
• Maximum memory pool

1024
Note: In this example, the minimum settings are used.
3. Open the server.XML file from:

<TomcatInstallationDirectory>\conf
4. Add a new attribute maxHttpHeaderSize="65536" to the following element:
<Connector port="8080" protocol="HTTP/1.1"

connectionTimeout="20000"
redirectPort="8443" maxHttpHeaderSize="65536" />
5. Restart Tomcat.

Step 2 – Install OTDS

Important
Verify Tomcat is running before you begin the installation.
1. Download the OTDS Windows installer from the Directory Services area on
OpenText My Support.
2. Start the installer, click Next on the Welcome page, and accept the License
Agreement.
3. Follow the wizard to install OTDS with the following options:
Application Server
Apache Tomcat.
Installation Type
Do not check the replication server option.
Java Virtual Machine

The path to the Java Runtime Environment.
Directory Services Parameters

Use the default ports.
OTDS Administrator
Select the option to enforce a complex password and enter a password for
the administrator user.
Tip: Make a note of the user name and password. These are required
to log on the OTDS web client.
OTDS Data Import

Select No import.
Step 3 – Set up HTTPS communication for OTDS

In this example, a self-signed certificate is used.
Note: Self-signed certificates are only suitable for use in development and testing
environments.
1. Open a command prompt and navigate to C:\Program Files\Java\<Java

version>\bin.
2. Run the command: keytool -genkey -alias tomcat -keyalg RSA

-keystore C:\mycerts\mykey.keystore
3. Enter a password, your user, organizational, location details and then enter YES
to confirm.
4. Enter the key password for tomcat.

5. Open Windows Explorer and then open the server.XML file from the following
directory:
C:\Program Files\Apache Software Foundation\Tomcat 8.0\conf
6. Uncomment the element below and add the following attributes to the element:
• keystoreFile - This is the path to the keystore file created in step 2. .i.e. C:
\mycerts\mykey.keystore
• keystorePass - The password entered in step 3.
<Connector
protocol="org.apache.coyote.http11.Http11NioProtocol"
port="8443" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="C:\mycerts\mykey.keystore" keystorePass="MyPass16!"
clientAuth="false" sslProtocol="SSL" />
7. Restart Tomcat.
4.5.2 Example: Configuring a multi-tenant OTDS

This example describes how to configure the multi-tenant OTDS with the following:
• strs.role partition assigned to the Exstream resource
• One group for the multi-tenant administrators
• One user assigned to the multi-tenant administrators group
• Read-only (browser) user
Accessing the OTDS web client

Open the web client for the default backend via the following URL:
https://<OTDS host>:<port>/otds-admin/
Step 1 – Create a partition called strs.role

In this example, a non-synchronized partition is created.
• On the Partitions page, click Add > New non-synchronized User Partition,
enter strs.role, and then click Save.

Step 2 – Create the strsmultitenantadmins group

Create one group called: strsmultitenantadmins.
To create a group:
1. On the Partitions page, select the strs.role partition, and then click Actions >
View Members.
2. Click the Groups tab, and then click Add > New Group.
3. In the Group Name box, enter the appropriate <group name>, and then click
Save.
Where <group name> is strsmultitenantadmins.
Step 3 – Create a user and assign the user to a group

In the default backend, create one user and assign the user to the
strsmultitenantadmins group. In this example, the password policy is set to User
cannot change password and Password never expires for convenience.

To create a user:
View Members.
2. Click the Users tab, and then click Add > New User.
3. Enter a name for the user, click Next, and configure the following Password
options:
• Do not require password change on reset

• User cannot change password – Select
• Password never expires – Select
4. Enter a password.
5. Click Save.
Tips
• Make note of the user name and password.
The user assigned to the strsmultitenantadmins group is required to use
the ss_tenantadmin tool (-mtauser and -mtapassword arguments).
To assign the user to a group:
View Members.
2. Click the Users tab, select the user, and then click Actions > Edit Membership.
3. Click Add To Group.
4. Select the appropriate group to add the user to, click Add Selected, and then
click Close.
5. Click Back to return to the previous page.

Step 4 – Create a resource for Exstream

1. On the Resources page, click Add.
2. In the Resource name box, enter a name for the resource. Note: The resource
can have any name.
3. In the Display name box, enter a display name for the resource.
4. Click Save and then click OK in the Resource Activation dialog box.
5. Select the Exstream resource, click Actions, Properties, and then copy the
Resource ID from the Resource identifier box.

Tip: Make a note of the resource ID. It is required to activate the resource and
to set up the Exstream environment.
Step 5 – Activate the resource

The OTDS Rest API for the default backend can be accessed via the following URL:
https://<otds_host>:<port>/otdsws/api/index.html?rest#!
To activate the resource:
1. Open the OTDS Rest API.

2. In the list, click resources: Operations on resources
The list is expanded.
3. Click /resources/{resource_id}/activate Activate a resource
4. In the resource_id field, paste the resource ID, and then click Try it out!

Tip: Make a note of the secret key that is returned.
The resource ID (e.g. 71953643-a163-4123-b312-4fe225c34f08) and secret

key (e.g. "Z0yWzfu8UeDge6ZBlxiDLw==") are required to set up the Exstream
environment. These are the -otdsresource and -otdsresourcepassword
arguments entered during “Step 2 – Create the connection profile to the multi-
tenant OTDS with the configure_multitenant_otds action” on page 60.
To verify the activation:
1. In the OTDS web client, on the Resources page, select the Exstream resource,
click Actions, Activation Status, and then click Verify Activation.
A message appears "The resource is activated".
2. Click OK to close the dialog box.
Step 6 – Assign the strs.role partition to the resource

1. On the Access Roles page, select the resource, then click Actions > View Access
Role Details.
2. On the User Partitions tab, click Add, select the strs.role partition, and then
click Add Selected Items to Access Role.
A message appears "strs.role added to the Access Role.".

3. Click Close Dialog and then click Save.
4. Optional Verify the strs.role partition is assigned to the resource by clicking the
resource, clicking Actions > View Access Role Details. Here strs.role should
be listed on the User Partitions tab.
Step 7 – Add a user with read access

View Members.
2. Click Add > New user, and then enter the user details.
Example user ID:
• User ID: strsbrowser
3. Click Next and enter the password.
Notes
• This user must have Never expire as a password policy in OTDS.
• This user does not need to be a member of any group.

4. Click Save.
Tip: Make a note of this user name and password. These are the -
otdsusername and -otdspassword arguments entered during “Step 2 – Create
the connection profile to the multi-tenant OTDS with the
configure_multitenant_otds action” on page 60.
Step 8 – Add the trusted sites

In this example, access is only granted for the local host.
1. On the Trusted Sites page and click Add.
2. Enter https://localhost.
3. Click Save.

4.5.3 Example: Adding a tenant OTDS

This example describes how to create a tenant in OTDS.
1. Run the following command from the directory <OTDS installation

directory>\install:
Command:
C:\OpenText\Directory Services <version>\install>otdstenant
-addtenant <tenantname> <password>
Notes
• The <tenantname> must be lower-case.

• You need operating system administrator privileges to run this
command.
• The password you enter is for the tenant specific administration account
i.e. otadmin@otds.admin. This is required to log on to the web
administration client.
4.5.4 Example: Configuring a tenant OTDS

This example describes how to configure the tenant OTDS with the following:
• strs.role partition assigned to the Exstream resource
• Groups for the tenant administrators, tenant users, reviewers, and on demand
users
• Four users – one assigned to each of the groups
• Read-only (browser) user
Accessing the OTDS web client

Open the web client for the tenant backend via the following URL:
https://<OTDS host>:<port>/otdstenant/<tenantname>/otds-admin/
Step 1 – Create a partition called strs.role

In this example, a non-synchronized partition is created.
• On the Partitions page, click Add > New non-synchronized User Partition,
enter strs.role, and then click Save.

Step 2 – Create the groups

In the tenant OTDS, create the groups listed below.
To create a group:
View Members.
2. Click the Groups tab, and then click Add > New Group.
3. In the Group Name box, enter the appropriate <group name>, and then click
Save.
Where <group name> is one of the following:

• strstenantadmins
• strstenantusers
• strsreviewers
• strsondemandusers

Tips
• Make note of the user names and passwords. These are the users that have
access to Communications Builder, Control Center, Describer, and the web
applications.
Step 3 – Add the users and assign each user to a role

In the tenant OTDS, create the following four users and then assign each user to the
respective group.
User name: Group assignment:

tenantadmin strstenantadmins
tenantuser strstenantusers
reviewer strsreviewers
ondemanduser strsondemandusers
In this example, the password policy is set to User cannot change password and
Password never expires for convenience.
To create a user:
View Members.
2. Click the Users tab, and then click Add > New User.
3. Enter a name for the user, click Next, and configure the following Password
options:

• Do not require password change on reset

• User cannot change password – Select
• Password never expires – Select
4. Enter a password.
5. Click Save.
To assign a user to a group:
View Members.
2. Click the Users tab, select the user, and then click Actions > Edit Membership.
3. Click Add To Group.
4. Select the appropriate group to add the user to, click Add Selected, and then
click Close.
5. Click Back to return to the previous page.
Step 4 – Create a resource for Exstream

1. On the Resources page, click Add.
2. In the Resource name box, enter a name for the resource. Note: The resource
can have any name.
3. In the Display name box, enter a display name for the resource.
4. Click Save and then click OK in the Resource Activation dialog box.

5. Select the Exstream resource, click Actions, Properties, and then copy the
Resource ID from the Resource identifier box.
Tip: Make a note of the resource ID. It is required to activate the resource and
to set up the Exstream environment.
Step 5 – Activate the resource

The OTDS Rest API for the tefault backend can be accessed via the following URL:
http://<otds_host>:<port>/otdstenant/<tenant_name>/otdsws/api/index.
html?rest#!
To activate the resource:

1. Open the OTDS Rest API.
2. In the list, click resources: Operations on resources
The list is expanded.
3. Click /resources/{resource_id}/activate Activate a resource
4. In the resource_id field, paste the resource ID, and then click Try it out!

Tip: Make a note of the secret key.
The resource ID (e.g. f9b7fbf3-dc85-4ca1-8046-b0e987b3d4c3) and secret

key (e.g. "cWMahqHTXxSFdRcVrnsE2g==") are the -otdsresource and -
otdsresourcepassword arguments entered during “Step 2 – Create the
connection profile to the tenant OTDS with the configure_tenant_otds action”
on page 66).
Step 6 – Assign the strs.role partition to the resource

1. On the Access Roles page, select the resource, then click Actions > View Access
Role Details.
2. On the User Partitions tab, click Add, select the strs.role partition, and then
click Add Selected Items to Access Role.
A message appears "strs.role added to the Access Role.".
3. Click Close Dialog and then click Save.
4. Optional Verify the strs.role partition is assigned to the resource by clicking the
resource, clicking Actions > View Access Role Details. Here strs.role should
be listed on the User Partitions tab.
Step 7 – Add a user with read access

View Members.
2. Click Add > New user, and then enter the user details.
Example user ID:

• User ID: strsbrowser

3. Click Next and enter the password.
Notes
• This user must have Never expire as a password policy in OTDS.
• This user does not need to be a member of any group.
4. Click Save.
Tip: Make a note of this user name and password. These are the -
otdsusername and -otdspassword arguments entered during “Step 2 – Create
the connection profile to the tenant OTDS with the configure_tenant_otds
action” on page 66.
Step 8 – Add the trusted sites

In this example, access is only granted for the local host.
1. On the Trusted Sites page and click Add.
2. Enter https://localhost.
3. Click Save.

4.6 Troubleshooting
• If you get the error message "OTDSProviderSupportServices: Failed to
validate ticket against OTDS. Error=Cannot map Otds user:
strsuser@otds.admin to resource: 7ac319d2-bfbf-44d9-ad26-
d27ba2ad1dbb..", your resource may be invalid. The work around for this is to
recreate the resource.

Chapter 5
Preparing the database
This section describes how to prepare the database for use with the Exstream
repositories and the required database configurations. How to carry out
configurations in third party products is not included. For this information, see user
documentation from the database vendor.
In this section
• “Software requirements” on page 53
• “Hardware requirements” on page 53
• “Database configuration: Microsoft® SQL Server®” on page 53
• “Database configuration: Oracle® Database” on page 54
• “Database configuration: PostgreSQL” on page 55
• “Database configuration: SAP® HANA” on page 56
Software requirements
For information about supported database vendors and versions, see OpenText
Exstream 16.4 Release Notes.
Note: All the Exstream repositories in the same Exstream environment must
use the same database vendor. In a multi-tenant environment, this constraint
applies to all repositories across all client organizations or tenants.
When selecting database edition, you should follow the guidelines from the
database vendor. Note that it is not supported to run express editions, such as
Microsoft SQL Server Express, in a production environment.
The Exstream repositories are logical databases. This means all the repositories can
reside in a single Oracle schema or SQL Server database, or each repository can
reside in a separate schema or database.
Hardware requirements
You should follow the hardware guidelines provided by the database vendor when
setting up Exstream repositories.
Database configuration: Microsoft® SQL Server®

The database must be configured according to the following:
• Enable TCP/IP.

Chapter 5 Preparing the database
• Specify Mixed Mode authentication.

• Specify a static TCP port number for accessing the database from all IP
addresses.
• Select the collation to be used. To avoid conflicts in different Exstream
repositories, you must set the same collation for all databases where you install
Exstream repositories. For information and recommendations, see Microsoft SQL
Server Books Online.
The collation specifies rules for how character strings are sorted and compared,
based on the norms of particular languages and locales. The default setting is the
collation from the computer where SQL Server is installed. For example, if you
install SQL Server in Finland, a Finnish collation is suggested.
When you search for items in the Exstream repositories, the collation decides
how the search result is sorted. For example, when you search for resources via
the common asset service. If the collation is case sensitive, this also affects the
search result.
Database configuration: Oracle® Database

The database must be configured according to the following:
1. Specify the following database server parameter before you create the database:
db_block_size: 8192 (minimum)

If the database server has more than 4 GB memory, you can increase this
value to 16384.
2. Create a UTF database with:
• Character set: AL32UTF8

• National character set: AL16UTF16
3. Make all tablespaces locally managed.
4. Where applicable, make sure the tablespaces are automatic segment space
managed.
5. If the database character set uses a multi-byte character encoding scheme and
the default Unicode support is not enough, you can increase the Unicode
support as described below.
Oracle Database 12c configurations

• Create a service name in the tnsnames.ora file for every PDB (pluggable
database) you want to use for an Exstream repository.
• If using Oracle Database 12c Release 2, insert these lines into the sqlnet.ora file:
• SQLNET.ALLOWED_LOGON_VERSION_SERVER=11
• SQLNET.ALLOWED_LOGON_VERSION=11

• SQLNET.ALLOWED_LOGON_CLIENT=11"
Increasing Unicode support for Oracle Database
• By default, Exstream uses NVARCHAR2, which normally offers enough Unicode

support. To achieve a more general Unicode support, you can specify the
database server parameter below. The parameter must be specified before the
Exstream repositories are created.
• nls_length_semantics: char
Note: The char value requires more space in the database than the
default byte value.
Changing non-default database parameters for Oracle Database
• If you are not satisfied with your Oracle installation, you may have to change the
following non-default database server parameters (values recommended by
OpenText):
• job_queue_processes: <default>
The Communications Server application does not use any database jobs.
However, the database administrator may need the job_queue_processes
parameter for administrative jobs.
• processes: 300 (minimum)
For larger environments, where several Communications Server applications
are used, you may need a higher value.
• pga_aggregate_target: <Machine RAM> - <Non Oracle RAM> - sga_target
The relationship between pga_aggregate_target and sga_target depends
on the number of users. Start with sga_target = pga_target.
• sga_target: <Machine RAM> - <Non Oracle RAM> - pga_aggregate_target
The relationship between pga_aggregate_target and sga_target depends
on the number of users. Start with sga_target = pga_target.
• After changing the parameters, you may have to restart the Oracle database.
Database configuration: PostgreSQL

In the postgresql.conf file, configure the following parameters:
• shared_buffers: This must be a minimum of 2 GB.

• autovacuum = off. This setting is only required to avoid contention failures
while installing and setting up the Exstream repositories.
• max_prepared_transactions and max_connections must have the same value.

Chapter 5 Preparing the database
Note: The Postgres database parameter configuration and database server

configuration will vary depending on the estimated transactions, load, and
repository size.
Database configuration: SAP® HANA

• Exstream supports SAP HANA installed in single-container or multiple-
container mode.
Note: In multiple-container mode, OpenText recommends that the

Exstream schemas are installed in one or several SAP HANA Tenant
databases (that is, not in the SYSTEMDB database). A SAP HANA Tenant
database must be created in the database system before any Exstream
schemas can be created in the database.
• SAP HANA Client must then be downloaded from SAP Service Marketplace and
installed on all computers that will access the SAP HANA system. Provided the
client is installed in the default location suggested during the installation, no
further actions are required for the client.
If SAP HANA Client is installed in a location other than the default one, you
must manually update the path to the ngdbc.jar file in the Exstream scripts
below. For UNIX, you must also update the path to the libodbcHDB.so file.
Windows - <Exstream_Installation_directory>\<version>\Server\bin\
create-repo.bat|list-hotfix-repo.bat|hotfix-repo.bat
Open each script and update the path in the following line:
set CP="../lib/repoadm.jar;C:\Program Files\sap\hdbclient\ngdbc.
jar"
UNIX - .../Exstream-<Version>.GA.<Build>/<version>/Server/bin/
create-repo.sh|list-hotfix-repo.sh|hotfix-repo.sh
Open each script and update the path in the following line:
classPath="lib/repoadm.jar:/usr/sap/hdbclient/ngdbc.jar"
UNIX - .../Exstream-<Version>.GA.<Build>/platform/odbcinst.ini
Open the script and update the path in the following line:
Driver=/usr/sap/hdbclient/libodbcHDB.so

Chapter 6
Setting up the Exstream environment
6.1 About the ss_tenantadmin utility

The ss_tenantadmin command line utility is used to configure the management
gateway, set up and manage Exstream tenants, and create the multi-tenant and
tenant repositories.
To use the ss_tenantadmin utility on UNIX
1. Set the $STRS_LOCATION environment variable to where you installed the

Exstream software, for example:
STRS_LOCATION=/usr/Exstream/Exstream-16.3.0.GA.<Build>
export STRS_LOCATION
2. Run the utility:
./launcher solutions/sstools/start ss_tenantadmin <arguments>
To use the ss_tenantadmin utility on Windows
1. In the command line window, browse to the following directory:
<Exstream_Installation_directory>\<version>\Server\bin
2. Run the following command:
ss_tenantadmin.exe <arguments>
6.2 Configuring the management gateway and

creating the multi-tenant repository
To set up a new Exstream environment, you need to create the multi-tenant
repository, and then connect the management gateway to the multi-tenant
repository and to the multi-tenant OTDS.
To do this, you use the ss_tenantadmin utility to do the following:
1. Create a connection profile for the multi-tenant repository.

2. Create a connection profile for the multi-tenant OTDS.
3. Create the multi-tenant repository in the database (based on the connection
profile created earlier).
TIP: If you do not want to create the multi-tenant repository directly from the
ss_tenantadmin.exe utility, you can generate scripts used to create the repository

Chapter 6 Setting up the Exstream environment
and then run the scripts using an external tool. See “Creating the multi-tenant or
tenant repository manually” on page 72.
4. Configure the management gateway to use the connection profiles. This step
connects the management gateway to the multi-tenant OTDS and multi-tenant
repository.
After these steps, you can start the management gateway.
Prerequisites
• There is a Communications Server installation on the computer where you will
run the commands.
• The database is prepared for use with Exstream.
You have the database administration user name and password.
• The multi-tenant OTDS is configured in OTDS.
You have the following information for the multi-tenant OTDS:
• URL and port
• Resource ID and resource password
• User name and password for a user with read access to the OTDS server
Step 1 – Create the connection profile to the multi-tenant

repository with the configure_multitenant_repository action
Syntax
ss_tenantadmin.exe -action configure_multitenant_repository
Example 6-1: configure_multitenant_repository using the default values
This example creates the connection profile in the file

multitenant_respository_profile.xml in the directory where you run
the command.
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_multitenant_repository
Example 6-2: configure_multitenant_repository
This example creates the connection profile in the file C:

\MyConnectionProfiles\multitenant_respository_profile.xml
Command:
ss_tenantadmin.exe" -action configure_multitenant_repository

6.2. Configuring the management gateway and creating the multi-tenant repository
-dbhost WIN-53RDK69N3DN\SQLEXPRESS -dbport 1433 -dbvendor

sqlserver -dbname StrsMultiTenantDb -dbusername MultiTenUsr123
-dbpassword MultiTenPwd123 -output "C:\MyConnectionProfiles\
multitenant_respository_profile.xml"
Argument descriptions
All the arguments are optional.
-dbhost <database_host>
The IP address or host name of the database server. If you use a named instance
of SQL Server, you must specify the host name and instance name using the
syntax <hostname>\<instance name>. For example: gbg5000\instance1.
-dbport <database_port_number>
The port used for communication with the database server.
-dbvendor <vendor>
The database vendor for the repository. This can be sqlserver, oracle,
postgres, or hana.
-dbname <database_name>
Applicable for SQL Server, Postgres, and SAP HANA – The name of the database
for the repository.
• If SAP HANA is installed in single-container mode, you must omit the -

dbname argument.
• If SAP HANA is installed in multiple-container mode, the assigned SAP
HANA Tenant database must be set up in the database system before you run
ss_tenantadmin.
-dbservicename <SID>
Applicable for Oracle – The Oracle Service name for the repository.
-dbusername <user_name/schema_owner>
The database administration user that the management gateway uses to connect
to the repository. The user is automatically created when the repository is
created. You cannot use the system administrator as user name (for example,
sa).
On Oracle and SAP HANA, this will be the schema owner.
-dbpassword <password>
A password to access the repository.
-output <path_file>
A path and file name where the XML file with the connection profile will be
saved. If this is not specified, the file is created in the directory where the
command is run with the default name.

-env <path_file>
The path and file name of the environment file.
For information about the general arguments that can be used with
ss_tenantadmin, see “ss_tenantadmin additional (optional) arguments”
on page 70.
Step 2 – Create the connection profile to the multi-tenant OTDS

with the configure_multitenant_otds action
Syntax
ss_tenantadmin.exe -action configure_multitenant_otds -otdsusername
<user_name> -otdspassword <password> -otdsresource <resource_ID> -
otdsresourcepassword <password>
Example 6-3: configure_multitenant_otds using the default values
This example creates the connection profile in a file called

multitenant_otds_profile.xml in the directory where you run the
command.
Command:
ss_tenantadmin.exe" -action configure_multitenant_otds
-otdsusername strsbrowser@strs.role -otdspassword strs
-otdsresource 71953643-a163-4123-b312-4fe225c34f08
-otdsresourcepassword "Z0yWzfu8UeDge6ZBlxiDLw=="
Example 6-4: configure_multitenant_otds

\MyConnectionProfiles\multitenant_otds_profile.xml
Command:
ss_tenantadmin.exe" -action configure_multitenant_otds -otdsURL
wsautogbg.streamserve.com -otdsport 8443 -otdsusername
strsbrowser@strs.role -otdspassword pwd -otdsresource 71953643-
a163-4123-b312-4fe225c34f08-otdsresourcepassword
"Z0yWzfu8UeDge6ZBlxiDLw==" -output "C:\MyConnectionProfiles\
multitenant_otds_profile.xml"
-otdsURL <host>
(OPTIONAL)

For the default OTDS backend, this is the host and domain name of the
computer with the OTDS server. This can be specified as either an IP address or
a host name. When using the host name, OpenText recommends to use a fully
qualified domain name (FQDN) so all clients accessing Exstream can resolve the
host name. For example: myhostname.mydomain.com
For an OTDS tenant backend, this must also include the name of the OTDS
tenant in the format <IPAddress/HostName>/otdstenant/<otdstenantname>.
For example myhostname.mydomain.com/otdstenant/myotdstenantname
-otdsport <port>
(OPTIONAL) The port used for communication with OTDS.
-otdsusername <user_name>
The OTDS user name. This user requires read access to the Exstream partition in
OTDS. Exstream applications use this user to browse OTDS.
-otdspassword <password>
The OTDS password.
-otdsresource <resource_ID>
The OTDS resource ID.
-otdsresourcepassword <password>
The password for the OTDS resource.
-unsecure
(OPTIONAL) Flag to indicate that unsecure HTTP communication is used with
OTDS. If omitted, HTTPS is used.
To use unsecure HTTP communication, HTTPS must also be disabled in OTDS.
directory.auth.EnforceSSL and set the value to false on the System Attributes
page in the OTDS web client. For more information about disabling HTTPS
• Section 12.1 “System Attributes” in OpenText Directory Services - Installation

and Administration Guide (OTDS-IWC)
• Section 3.5.1.2 “Using encryption” in OpenText Directory Services - Installation
environments.
-output <path_file>
(OPTIONAL) A path and file name where the XML file with the connection
profile will be saved. If this is not specified, the file is created in the directory
where the command is run with the default name.
-env <path_file>
(OPTIONAL) The path and file name of the environment file.

on page 70.
Step 3 – Create the multi-tenant repository with the

create_multitenant_db action
Syntax
ss_tenantadmin.exe -action create_multitenant_repository -

multitenantdbprofile <path_file> -dbadminusername <user_name> -
dbadminpassword <password>
Example 6-5: create_multitenant_repository
This example creates the multi-tenant repository based on the connection

profile in the file C:\MyConnectionProfiles\
multitenant_respository_profile.xml
Command:
ss_tenantadmin.exe" -action create_multitenant_repository
-multitenantdbprofile "C:\MyConnectionProfiles\
multitenant_respository_profile.xml" -dbadminusername sa
-dbadminpassword Changeoninstall2000
-multitenantdbprofile <path_file>
The path to and name of the XML file containing the connection profile for the
multi-tenant repository.
-dbadminusername <user_name>
The database administration user that is used to create the repository. For
example, the system administrator sa.
-dbadminpassword <password>
The password for the database administration user.
-MGWRoot <path>
(OPTIONAL) Specifies the location of the management gateway root directory.
-env <path_file>
on page 70.

Step 4 – Configure the management gateway to use the

connection profiles with the configure_mgw action
Syntax
ss_tenantadmin.exe -action configure_mgw -multitenantdbprofile

<path_file> -multitenantotdsprofile <path_file>
Example 6-6: configure_mgw
This example configures the management gateway to use the following

connection profiles created in the previous examples.
Command:
ss_tenantadmin.exe" -action configure_mgw -multitenantdbprofile
"C:\MyConnectionProfiles\multitenant_respository_profile.xml"
-multitenantotdsprofile "C:\MyConnectionProfiles\
-multitenantdbprofile <path_file>
multi-tenant repository.
-multitenantotdsprofile <path_file>
The path to and name of the file containing the connection profile for the multi-
tenant OTDS.
-MGWRoot <path>
(OPTIONAL) Specifies the location of the management gateway root directory.
-env <path_file>
on page 70.
Step 5 – Start the management gateway service or process

Windows
• On Windows, you start the management gateway from Windows Control Panel.
Unix
• On UNIX, start the management gateway with the command:
./launcher [<options>] management

For example: ./launcher -background management

For information about the options, enter ./launcher --help
To stop the management gateway, enter ./launcher shutdown management
6.3 Adding a tenant

You must add at least one tenant in every Exstream environment.
Adding a tenant to the Exstream environment involves connecting the tenant to the
appropriate tenant OTDS, and either creating a new tenant repository or connecting
to the tenant to an existing repository (shared tenant repository scenario).
To do this, you use the ss_tenantadmin utility to do the following:
1. Create a connection profile for the tenant OTDS.
2. Create a connection profile for the tenant repository.
3. If required, create the tenant repository in the database.

TIP: If you do not want to create the tenant repository directly from the
ss_tenantadmin.exe utility, you can generate scripts used to create the repository
and then run the scripts using an external tool. See “Creating the multi-tenant or
tenant repository manually” on page 72.
4. Add the tenant to Exstream environment. This step connects the tenant to the
tenant OTDS and tenant repository.
After a tenant is added, you can (optionally) use the ss_tenantadmin utility to obtain
the tenant ID.
Prerequisites
• There is a Communications Server installation on the computer where you will

run the commands.
• You have the multi-tenant administrator user name and password.
• The database is prepared for use with Exstream.
You have the database administration user name and password.
• The tenant OTDS is configured in OTDS.
You have the following information for the tenant OTDS:
• URL and port

• Resource ID and resource password
• User name and password for a user with read access to the OTDS server

6.3. Adding a tenant
Step 1 – Create the connection profile to the tenant repository

with the configure_tenant_repository action
You must save the connection profile file and make a note of the location. This file is
required to apply a hotfix to the tenant repository.
Syntax
ss_tenantadmin.exe -action configure_tenant_repository
Example 6-7: configure_tenant_repository using the default values
This example creates the connection profile in the file

tenant_respository_profile.xml in the directory where you run the
command.
Command:
ss_tenantadmin.exe" -action configure_tenant_repository
Tip: For information about the default values, see ss_tenantadmin help (-h).
Example 6-8: configure_tenant_repository

\MyConnectionProfiles\tenant_respository_profile.xml
Command:
ss_tenantadmin.exe" -action configure_tenant_repository -dbhost
WIN-53RDK69N3DN\SQLEXPRESS -dbport 1433 -dbvendor sqlserver
-dbname StrsTenant_ABC -dbusername StrsTenABC123 -dbpassword
StrsTenPwd123 -output "C:\MyConnectionProfiles\
tenant_respository_profile.xml"
All the arguments are optional.
-dbhost <database_host>
The IP address or host name of the database server. If you use a named instance
of SQL Server, you must specify the host name and instance name using the
syntax <hostname>\<instance name>. For example: gbg5000\instance1.
-dbport <database_port_number>

-dbvendor <vendor>
The database vendor for the repository. This can be sqlserver, oracle,
postgres, or hana.
-dbname <database_name>
Applicable for SQL Server, Postgres, and SAP HANA – The name of the database
for the repository.
• If SAP HANA is installed in single-container mode, you must omit the -
dbname argument.
HANA Tenant database must be set up in the database system before you run
ss_tenantadmin.
-dbservicename <SID>
Applicable for Oracle – The Oracle Service name for the repository.
-dbusername <user_name/schema_owner>
The database administration user that the management gateway uses to connect
to the repository. The user is automatically created when the repository is
created. You cannot use the system administrator as user name (for example,
sa).
On Oracle and SAP HANA, this will be the schema owner.
-dbpassword <password>
A password to access the repository.
-output <path_file>
A path and file name where the XML file with the connection profile will be
saved. If this is not specified, the file is created in the directory where the
command is run with the default name.
-env <path_file>
The path and file name of the environment file.
on page 70.
Step 2 – Create the connection profile to the tenant OTDS with

the configure_tenant_otds action
Syntax
ss_tenantadmin.exe -action configure_tenant_otds -otdsusername
<user_name> -otdspassword <password> -otdsresource <resource_ID> -
otdsresourcepassword <password>
Example 6-9: configure_tenant_otds using the default values
This example creates the connection profile in a file called

tenant_otds_profile.xml in the directory where you run the command.

Command:
ss_tenantadmin.exe" -action configure_tenant_otds -otdsusername
strsbrowser@strs.role -otdspassword strs -otdsresource
f9b7fbf3-dc85-4ca1-8046-b0e987b3d4c3 -otdsresourcepassword
"cWMahqHTXxSFdRcVrnsE2g=="
Example 6-10: configure_tenant_otds

\MyConnectionProfiles\tenant_otds_profile.xml
Command:
ss_tenantadmin.exe" -action configure_tenant_otds -otdsURL
wsautogbg.streamserve.com/otdstenant/t1 -otdsport 8443
-otdsusername strsbrowser@strs.role -otdspassword strs
-otdsresource f9b7fbf3-dc85-4ca1-8046-b0e987b3d4c3
-otdsresourcepassword "cWMahqHTXxSFdRcVrnsE2g==" -output "C:
\MyConnectionProfiles\tenant_otds_profile.xml"
-otdsURL <host>
(OPTIONAL)
For the default OTDS backend, this is the host and domain name of the
computer with the OTDS server. This can be specified as either an IP address or
a host name. When using the host name, OpenText recommends to use a fully
qualified domain name (FQDN) so all clients accessing Exstream can resolve the
host name. For example: myhostname.mydomain.com
For an OTDS tenant backend, this must also include the name of the OTDS
tenant in the format <IPAddress/HostName>/otdstenant/<otdstenantname>.
For example myhostname.mydomain.com/otdstenant/myotdstenantname
-otdsport <port>
(OPTIONAL) The port used for communication with OTDS.
-otdsusername <user_name>
The OTDS user name. This user requires read access to the Exstream partition in
OTDS. Exstream applications use this user to browse OTDS.
-otdspassword <password>
The OTDS password.
-otdsresource <resource_ID>
The OTDS resource ID.

-otdsresourcepassword <password>
The password for the OTDS resource.
-unsecure
(OPTIONAL) Flag to indicate that unsecure HTTP communication is used with
OTDS. If omitted, HTTPS is used.
To use unsecure HTTP communication, HTTPS must also be disabled in OTDS.
directory.auth.EnforceSSL and set the value to false on the System Attributes
page in the OTDS web client. For more information about disabling HTTPS
• Section 12.1 “System Attributes” in OpenText Directory Services - Installation
• Section 3.5.1.2 “Using encryption” in OpenText Directory Services - Installation
environments.
-output <path_file>
(OPTIONAL) A path and file name where the XML file with the connection
profile will be saved. If this is not specified, the file is created in the directory
where the command is run with the default name.
-env <path_file>
on page 70.
Step 3 (optional) – Create a tenant repository with the

create_tenant_repository action
Syntax
ss_tenantadmin.exe -action create_tenant_repository -mtauser

<user_name> -mtapassword <password> -tenantdbprofile <pathandfile> -
dbadminusername <user_name> -dbadminpassword <password>
Example 6-11: create_tenant_repository
This example creates the tenant repository based on the connection profile in
the file C:\MyConnectionProfiles\tenant_respository_profile.xml
Command:
ss_tenantadmin.exe" -action create_tenant_repository -mtauser
multitenantadmin@strs.role -mtapassword mtapwd -tenantdbprofile

"C:\MyConnectionProfiles\tenant_respository_profile.xml"
-dbadminusername sa -dbadminpassword Changeoninstall2000
Argument descriptions:
-mtauser <user_name>
The multi-tenant administrator user name. This user must be a member of the
multi-tenant administrator group.
-mtapassword <password>
The password for the multi-tenant administrator user.
-tenantdbprofile <pathandfile>
tenant repository.
TIP: After you create a service gateway application, you can find this file in the
securityprofiles folder in the working directory. Example location: C:
\ManagementGateway\16.3.0\root\applications\servicegateway\wd
\securityprofiles\tenantser-{5A8BD911-281F-
A64D-9BEF-5A3CFC9F9657}-securityprofile.xml
The database administration user that is used to create the repository. For
example, the system administrator sa.
-env <path_file>
on page 70.
Step 4 – Create a tenant that uses the connection profiles with

the create_tenant action
Syntax
ss_tenantadmin.exe -action create_tenant -mtauser <user_name> -

mtapassword <password> -tenantdbprofile <path_file> -
tenantotdsprofile <path_file> -tenantname <tenant_name>
Example 6-12: create_tenant
This example adds a tenant with the connection profiles:
• C:\MyConnectionProfiles\tenant_respository_profile.xml

• C:\MyConnectionProfiles\tenant_otds_profile.xml
Command:
ss_tenantadmin.exe" -action create_tenant -mtauser
multitenantadmin@strs.role -mtapassword mtapass
-tenantdbprofile "C:\MyConnectionProfiles\
tenant_respository_profile.xml" -tenantotdsprofile "C:
\MyConnectionProfiles\tenant_otds_profile.xml" -tenantname
tenant_AB
-tenantdbprofile <path_file>
tenant repository.
-tenantotdsprofile <path_file>
The path to and name of the file containing the connection profile for the tenant
OTDS.
-tenantname <tenant_name>
A name for the tenant. This name is needed by tenant administrators and tenant
users, etc., to log on to the Exstream tools, such as Control Center and Describer.
-tenantdesc <description>
(OPTIONAL) A description of the tenant.
-env <path_file>
on page 70.
ss_tenantadmin additional (optional) arguments

-mgwhost <host>
(OPTIONAL) The management gateway host where the command is run.
-mgwport <host>
(OPTIONAL) The port for the management gateway.

6.4. Adding a management gateway
-mgwtimeout <host>
(OPTIONAL) The time the utility waits for a response from the management
gateway. This is specified in milliseconds.
Tip: For information about the default values, see ss_tenantadmin help (-
h).
6.4 Adding a management gateway

To add a management gateway to an Exstream environment, you need to connect
the management gateway to the multi-tenant repository and to the multi-tenant
OTDS.
To do this, you copy the XML files with the connection profiles to the multi-tenant
repository and multi-tenant OTDS to the computer with the management gateway
you want to add to the environment, and then configure the new management
gateway to use the connection profiles.
To add a management gateway
1. Copy the XML files with the connection profiles to the multi-tenant repository
and multi-tenant OTDS from the existing locations.
For example, copy these files:
• C:\MyConnectionProfiles\multitenant_respository_profile.xml
• C:\MyConnectionProfiles\multitenant_otds_profile.xml
2. On the computer with the management gateway that you want to add to the
environment, paste the XML files into any directory. For example into a
directory with the name C:\NewMGWConnectionProfiles
3. From the computer with the management gateway you want to add, run
ss_tenantadmin.exe with the configure_mgw action. In this command, you
point out the location of the two connection profiles. Example command:
ss_tenantadmin.exe" -action configure_mgw -multitenantdbprofile
"C:\NewMGWConnectionProfiles\multitenant_respository_profile.xml"
-multitenantotdsprofile "C:\NewMGWConnectionProfiles\
For a description of this syntax, see “Step 4 – Configure the management
gateway to use the connection profiles with the configure_mgw action”
on page 63.
4. Start the management gateway service or process.

6.5 Creating the multi-tenant or tenant repository

manually
If you do not want to create the multi-tenant or tenant repository directly from the
ss_tenantadmin.exe utility, you can generate scripts used to create the repositories
and then run the scripts using an external tool.
To generate the scripts you use create-scripts.bat on Windows or create-

scripts.sh on UNIX. This file is located in:
<Exstream_Installation_directory>/<version>/Server/bin
This creates a ZIP file that contains two scripts:

• load_as_sys.sql script to create the database.
• load.sql script to create the tables etc. for the repository.
For information about how to run the scripts, see the following sections:
• “Executing database scripts: Microsoft SQL Server” on page 131
• “Executing database scripts: Oracle Database” on page 131
• “Executing database scripts: PostgreSQL” on page 132
• “Executing database scripts: SAP HANA” on page 133
Windows – Syntax to generate the scripts

create-scripts.bat -r <repository_type> -s <script_directory> -t
<respository_connection_profile> -z <ZIP_file_location>
UNIX – Syntax to generate the scripts

create-scripts.sh -r <repository_type> -s <script_directory> -t
<respository_connection_profile> -z <ZIP_file_location>
Example 6-13: Generating the scripts on Windows
This example saves the scripts used to create the tenant repository under C:/
Documents/tenant.zip.
"<Exstream_Installation_directory>\16.3.0\Server\bin\create-
scripts.bat" -r StrsTenantModel -s "C:\ManagementGateway\16.3.
0\root\config\database\" -t "C:\MyConnectionProfiles\
tenant_respository_profile.xml" -z C:\Documents\tenant.zip
-r <repository_type>
The type of repository. This must be one of the following:

6.6. Setting up a secure channel for management gateway
• StrsMultiTenantModel – for the multi-tenant repository.

• StrsTenantModel – for the tenant repository.
-s <script_directory>
Path to the directory with the database scripts:
Windows - <Base directory>\<Version>\root\config\database\
UNIX - <Project location>/config/database/
-t <respository_connection_profile>
The connection profile to the multi-tenant or tenant repository. For more
information about how this connection profile is generated, see:
• “Step 1 – Create the connection profile to the multi-tenant repository with the
configure_multitenant_repository action” on page 58
• “Step 1 – Create the connection profile to the tenant repository with the
configure_tenant_repository action” on page 65
-z <ZIP_file_location>
The location where the scripts will be saved.
6.6 Setting up a secure channel for management

gateway
To set up or change a secure channel for management gateway you must generate a
private keystore file (*.pfx) to be used by management gateway and a certificate file
(*.crt) to be used by Control Center and all command line utilities (ss_<utility>).
When you have generated the private keystore and certificate you must update the
configuration file mgw-trustedcommunicationchannel.xml with the new private
keystore and corresponding password. This file is located in the following directory:
<Exstream_Installation_directory>\<version>\Server\solutions
\management
To generate the private keystore
1. Open a command prompt and go to:
<Exstream_Installation_directory>\global\security\keystore
\private

keytool -genkey -alias tomcat -storetype PKCS12 -keyalg RSA
-keysize 2048 -keystore <keystore>.pfx -validity 3650
Where <keystore> is the name of the private keystore (you can use any name
for this).
TIP: You may need to enter the path to the Java keytool for example: C:
\Program Files\Java\<Java version>\bin

Example 6-14: Command example (private keystore)
"C:\Program Files\Java\jre.<verion>\bin\keytool.exe" -genkey

-alias tomcat -storetype PKCS12 -keyalg RSA -keysize 2048
-keystore mgwkey.pfx -validity 3650
When you run the command you must answer a couple of questions, including
which password to use for the private keystore. Make a note of the password (you
will need it later).
To generate the certificate
1. In the command prompt, go to:
<Exstream_Installation_directory>\<version>\Server\global
\security\certificatestore\trusted\authorities

keytool -export -alias tomcat -file <newcert>.crt -keystore
"<Exstream_Installation_directory>\<version>\Server\global
\security\keystore\private\<keystore>.pfx"
Where <newcert> is the name of the certificate (you can use any name for this)
and <keystore> is the name of the private keystore you created before.
Example 6-15: Command example (certificate)
"C:\Program Files\Java\jre.<verion>\bin\keytool.exe" -export

-alias tomcat -file mgwcert.crt -keystore "C:\Program Files
\OpenText\Exstream\16.3.0\Server\global\security\keystore\
private\mgwkey.pfx"
To update the configuration file
1. Open mgw-trustedcommunicationchannel.xml in a text editor.
2. Scroll down to the <file> tag (child of the <keystores> tag) and edit the
attributes:
• href – change demo.pfx to the name you specified when you generated the
private keystore.
• password – change the password to the password you specified when you
generated the private keystore.
3. Save mgw-trustedcommunicationchannel.xml and close the editor.

6.7. Configuring the management gateway for a virtual host
6.7 Configuring the management gateway for a

virtual host
When running a management gateway on a virtual host or in an environment where
the DNS (Domain Name System) is unstable, you must configure the virtualhost
attribute in the mgmgateway.xml file.
By default (i.e. when the virtual host setting is not used), the management gateway
queries the operating system to get the host name or IP address and then uses this
information to register itself during startup. If the virtual host setting is added, the
management gateway does not query the operating system. Instead it uses the
explicit host name (or IP address) that is specified in the mgmgateway.xml.
To configure the virtual host attribute for the management gateway
1. Open the mgmgateway.xml file from:

\management
2. Add the element <virtualhost name= "<MyMGWMachine>"/> directly after the

<implementation module="mgmgateway"> element.
Where:
• <MyMGWMachine> is the IP address or name of the management gateway

host. You can use any name providing the client can resolve the IP address
or name.
Example 6-16: Management gateway virtual host configuration

<implementation module=<mgmgateway>><virtualhost name=
"MyHostName"/>
3. Save and close the mgmgateway.xml file.
4. Restart the management gateway.
5. If running the web applications, verify that the nslookup query works for the
virtual host name on both the computer with the service gateway and the on the
computer with the web browser.

Chapter 7
Managing tenants
7.1 Listing the tenants

You use the get_all_tenants command to list the names and IDs of all the tenants
in the environment.
Syntax
ss_tenantadmin.exe -action get_all_tenants -mtauser <user_name> -
mtapassword <password> -env <path_file>
Example 7-1: get_all_tenants
ss_tenantadmin.exe" -action get_all_tenants -mtauser
multitenantadmin@strs.role -mtapassword mtapass
-env <path_file>
For information about the -mgwhost, -mgwport, and -mgwtimeout arguments that
can be used with this command, see “ss_tenantadmin additional (optional)
arguments” on page 70.

Chapter 7 Managing tenants
7.2 Obtaining the tenant ID

You can use the get_tenant command to find the ID of a tenant.
Syntax
ss_tenantadmin.exe -action get_tenant -tenantname <tenant_name> -
mtauser <user_name> -mtapassword <password> -env <path_file>
Example 7-2: get_tenant
This example returns the ID of a tenant (if found), when receiving a tenant
name.
Command:
ss_tenantadmin.exe" -action get_tenant -tenantname tenant_AB
-mtauser multitenantadmin@strs.role -mtapassword mtapass
The name of the tenant.
-env <path_file>

7.3. Changing the tenant name, description, or connection profiles
7.3 Changing the tenant name, description, or

connection profiles
You use the modify_tenant command to change the tenant name, description, the
connection profile to the tenant repository, or the connection profile to the tenant
OTDS.
To change the connection profile to the tenant OTDS or tenant repository, you must
create the new connection profile(s) before you run the modify_tenant command.
For information about how to create the connection profiles, see the following
sections:
• “Step 1 – Create the connection profile to the tenant repository with the
configure_tenant_repository action” on page 65.
• “Step 2 – Create the connection profile to the tenant OTDS with the
configure_tenant_otds action” on page 66
Syntax
ss_tenantadmin.exe -action modify_tenant -mtauser <user_name> -

mtapassword <password> -tenantID <tenant_ID> -tenantname
<tenant_name> -tenantdbprofile <path_file> -tenantotdsprofile
<path_file> -newtenantname <tenant_name>
Example 7-3: modify_tenant
This example changes the connection profile to the tenant OTDS, the
connection profile to the tenant repository, and the tenant name.
Command:
ss_tenantadmin.exe" -action modify_tenant -mtauser
multitenantadmin@strs.role -mtapassword mtapass -tenantname
strs -tenantdbprofile "C:\MyConnectionProfiles\
MyNew_tenant_respository_profile.xml" -tenantotdsprofile "C:
\MyConnectionProfiles\MyNew_tenant_otds_profile.xml"
-newtenantname MyNewName
-tenantID <tenant_ID>
(CONDITIONAL) The ID of the tenant you want to modify. See “Obtaining the
tenant ID ”.
Either the -tenantID or the -tenantname command is required.
(CONDITIONAL) The name of the tenant you want to modify.

-tenantdbprofile <path_file>
(OPTIONAL) The path to and name of the XML file containing the new
connection profile for the tenant repository.
-tenantotdsprofile <path_file>
(OPTIONAL) The path to and name of the file containing the new connection
profile for the tenant OTDS.
-newtenantname <tenant_name>
(OPTIONAL) A new name for the tenant. This name is needed by tenant
administrators and tenant users, etc., to log on to the Exstream tools, such as
Control Center and Describer.
-tenantdesc <description>
(OPTIONAL) Adds a description of the tenant.
-env <path_file>
7.4 Adding an OTMM or Content Server connection

profile to a tenant
In this section
• “Adding a connection profile to a tenant” on page 80

• “Removing a connection profile from a tenant” on page 85
Adding a connection profile to a tenant

To connect to OpenText™ Media Management (OTMM) or to OpenText™ Content
Server from the tenant, you must add the OTMM/Content Server profile to the
tenant with the add_connectionprofile command.
For each tenant, you can add one connection profile for OTMM and one connection
profile for Content Server.

7.4. Adding an OTMM or Content Server connection profile to a tenant
Note: Make sure that the API version specified in the file
<Exstream_Installation_directory>\<version>\Server\global
\repositoryotmm.xml corresponds to the API version supported by the
OTMM server.
Syntax
ss_tenantadmin.exe -action add_connectionprofile -mtauser <user_name>

-mtapassword <password> -tenantID <tenant_ID> -tenantname
<tenant_name> -connectionprofile <path_file> -connectionprofiletype
<type>
Example 7-4: add_connectionprofile
This example adds an OTMM connection profile to the tenant.
Command:
"<Exstream_Installation_directory>\<version>\Server\bin
\ss_tenantadmin.exe" -action add_connectionprofile -tenantname
"tenant1" -connectionprofile "C:\MyConnectionProfiles\
profile_configuration-OTMM-securityprofile.xml"
-connectionprofiletype application/x-streamserve.com-otmm
-mtauser multitenantadmin -mtapassword Streamserve11.0 -env
"<Exstream_Installation_directory>\<version>\Server\solutions
\management\.environment"
(CONDITIONAL) The ID of the tenant. See “Obtaining the tenant ID ”.
(CONDITIONAL) The name of the tenant.
-connectionprofile <path_file>
The path to and name of the file containing the connection profile. See “To create
an unsecure XML connection profile file for OTMM“ on page 82.
-connectionprofiletype <type>
The type of the connection profile. This can be one of the following:
application/x-streamserve.com-otmm
application/x-streamserve.com-contentserver
There can only be one connection profile of each type for each tenant.

-env <path_file>
To create an unsecure XML connection profile file for OTMM
1. To create the file with the connection profile, open the file called
otmmconnection_16.4.0.default from the following location:
<Management_Gateway_root_directory>\<version>\root\config
\<version>\Otmmconnection.
2. Save a copy of the file in any directory. For example under C:

\MyConnectionProfiles\profile_configuration-OTMM-securityprofile.
xml.
3. In the copy, update the following attributes and elements:
tenantID
The GUID of the tenant. See “Obtaining the tenant ID ”.
URL
The address of the Media Management repository web service.
port
The port used for communication with OTMM. The default HTTP port is
11090.
name
The user name to access OTMM.
password
The password to access OTMM.
Example 7-5: OTMM unsecure connection profile example

<securityprofiles xmlns="..." owner="Otmmconnection"
guiroot="true">
<connectionprofile type="..." name="..."
tenantID="tenantGUID">
<configuration>
<ws xmlns="...">
<url>http://localhost</url>
<port>11090</port>
...

...
</ws>
</configuration>
</connectionprofile>
<authenticationprofile type="..." name="..." guiname="OTMM
User" tenantID="...">
<configuration>
<simple xmlns="...">
<name>strsOtmmUser</name>
<password>strsOtmmUserPass</password>
</simple>
</configuration>
</authenticationprofile>
</securityprofiles>
To create a secure XML connection profile file for OTMM
1. To create the file with the connection profile, open the file called
otmmconnection_16.4.0.secure from the following location:
<Management_Gateway_root_directory>\<version>\root\config
\<version>\Otmmconnection.
2. Save a copy of the file in any directory. For example under C:

\MyConnectionProfiles\profile_configuration-OTMM-securityprofile.
xml.
3. In the copy, update the following attributes and elements:
tenantID
The GUID of the tenant. See “Obtaining the tenant ID ”.
certificate
Specify the certificate file to use when setting up the secure connection, and
the applicable passwords and alias.
URL
The address of the Media Management repository web service.
port
The port used for communication with OTMM. The default HTTPS port is
11443.
name
The user name to access OTMM.
password
The password to access OTMM.
4. Add the specified certificate file to the directory:

<Exstream installation directory>\<version>\Server\global\security
\certificatestore\trusted\authorities\.

Example 7-6: OTMM secure connection profile example

<securityprofiles xmlns="..." owner="Otmmconnection"
guiroot="true">
<configuration>
...
...
<certificates>
<certificate ref="file://otmm.cer pwd="PASSWORD"
alias="otmm" aliaspwd="PASSWORD"/>
</certificates>
...
...
</configuration>

<configuration>
...
...
<securechannel>
<protocol>TLSv1</protocol>
<authentication>Mandatory</authentication>
<verification>Disabled</verification>
<certificatestoreprofile value="..."/>
</securechannel>
...
...
</configuration>

<configuration>
<ws xmlns="...">
<url>https://localhost</url>
<port>11443</port>
...
...
</ws>
</configuration>
<authenticationprofile type="..." name="..." guiname="OTMM
User" tenantID="...">
<configuration>
<name>strsOtmmUser</name>
<password>strsOtmmUserPass</password>
</simple>
</configuration>

</securityprofiles>
Removing a connection profile from a tenant

You can remove an OTMM or Content Server connection profile from a tenant with
the remove_connectionprofile command.
Syntax
ss_tenantadmin.exe -action remove_connectionprofile -mtauser

<user_name> -mtapassword <password> -tenantID <tenant_ID> -
tenantname <tenant_name> -logicalID <profile_name>
Example 7-7: remove_connectionprofile
This example removes an OTMM connection profile from the tenant.
Command:
ss_tenantadmin.exe" -action remove_connectionprofile -tenantid
F924655A-2883-4546-8184-859BF5CAB898 -logicalid http://schemas.
streamserve.com/uid/resource/mediamgmtrepo-otmm-web-service-
connection-profile/1.0 -mtauser multitenantadmin -mtapassword
Streamserve11.0 -env C:\ManagementGateway\16.3.0\root
\.environment_16_3_0_debug
-logicalID <profile_name>
The name of the profile. This is found in the connection profile file in the XML
element called connectionprofile name.
For example "http://schemas.streamserve.com/uid/resource/
mediamgmtrepo-otmm-web-service-connection-profile/1.0"

-env <path_file>

Chapter 8
Implementing OpenText Private Help Server
8.1 Implementing the OpenText Private Help Server

for Exstream
The Exstream online help is delivered using the OpenText Global Help Server
system, which provides users with live access to the latest version of the online help.
If you do not want to use the OpenText Global Help Server system, you can choose
to download a copy of the online help files and host them on a local server by
deploying OpenText Private Help Server.
Note: The Private Help Server can support multiple OpenText products. If the
Private Help Server has already been installed within your organization to
support another OpenText product, you can add the Exstream online help to
that installation.
Setting up the Private Help Server requires you to complete the following general
tasks:
1. Prepare a server with the following:

• Apache Tomcat 7 or 8 application server.
• Java 1.6 or later.
2. Download and extract a copy of the product help files from OpenText My
Support.
3. Deploy the Private Help Server, which includes a web application that can locate
and return the locally deployed help files.
4. Configure the product to direct help requests to the Private Help Server.
Note: The Exstream online help consists of one helpset for configuration and
another helpset for administration.

Chapter 8 Implementing OpenText Private Help Server
8.1.1 Downloading the OpenText Private Help Server Kit and

product online help files
The first step in setting up the OpenText Private Help Server Kit is gathering the
required files. These include the following:
• The OpenText Private Help Server Kit is available on OpenText My Support:
https://knowledge.opentext.com/go/62360624
• A copy of the product online help files that the Private Help Server will host.
8.1.2 Deploying the Private Help Server

You can install the Private Help Server application by completing the tasks
described below.
Extracting the files

Extract the Private Help Server Kit to a temporary directory. You will modify the
files in this working directory and then deploy them to your site in later steps.
Notes
• The Private Help Server Kit contains two similarly named files, one
compatible with Apache Tomcat 7.x and the other with Apache Tomcat 8.x.
During the setup process, you will need to rename these files by removing
the version information for the file that is compatible with your version of
Apache Tomcat.
• The Private Help Server Kit supports two help file branches, help and
pi_hosted, and contains support files for each branch. Exstream uses the
pi_hosted branch.
After you extract the files, you should see an Private Help Server Kit directory
that includes the following:
• application directory: Contains docsapimapper.war, the Private Help Server
Web application file.
• help_support directory: Contains support files for the help branch:
• docsapimapper.xml.tomcat<version>: The Web application descriptor file.

• docsapimapper.properties: The configuration properties file declaring the
installed product help under the help branch and the installation path.
• pi_hosted_support directory: Contains support files for the pi_hosted branch:
• docsapimapper.xml.tomcat<version>: The Web application descriptor file.

• pidocsapimapper.properties: The configuration properties file declaring
the installed product help under the pi_hosted branch and the installation
path.

8.1. Implementing the OpenText Private Help Server for Exstream
• Sample directory: Contains sample descriptor and configuration files taken from
a working sample deployment for each branch. Do not use these files in your
deployment.
• _readme.txt: A summary description of the files intended for users without
access to the information in this guide.
• docs.zip: Sample help files used to verify your Private Help Server deployment.
• Test Help Page - OT Private Help Server.zip: A sample page you can use to
connect to your Private Help Server deployment.
Creating the local help directory

You must create the <help_root> directory, which is the directory where you will
deploy the help files you want to make available through the Private Help Server
and then add the test files used to verify your deployment.
To create the <help_root> directory:
1. Create the directory where you will extract the online help files, for example C:
\ot_docs.
The <help_root> directory can exist on any local drive, but its path must not
contain any names with spaces.
2. Extract the sample help files in the docs.zip file into the <help_root> directory.
Note: Always use the Extract all option when you extract OpenText online
help files.
3. After you extract the files, open the <help_root>/docs/pi_hosted/test/
v160200/test-h-ugd/en/ofh directory and verify that the following files were
extracted:
• context.properties
• index.html
Creating a help folder alias

You need to define an alias that the Private Help Server application can use to locate
the online help files.
To create the help folder alias:
1. In the pi_hosted_support folder where you extracted the zip file, rename the
docsmapperapi.xml.tomcat<version> file for your version of Tomcat to
docsmapperapi.xml.
2. Open the docsmapperapi.xml file in a text editor, and then locate the
<Context> element.
3. Replace the <help_root> with the full path to the help file directory you created
in “To create the <help_root> directory:“.

For example, using the folder created above, the setting for Apache Tomcat 7.x
on Windows is:
<?xml version="1.0" encoding="UTF-8"?>

<Context aliases="/docs/pi_hosted=C:\ot_docs\docs
\pi_hosted
</Context>
Note: On non-Windows operating systems, use appropriate slashes,

double quotes, and brackets, for example:
<Context aliases="/docs/pi_hosted=C:/ot_docs/docs/pi_hosted">
The same example for Apache Tomcat 8.x is:
<?xml version="1.0" encoding="UTF-8"?>

<Context>
<Resources
className="org.apache.catalina.webresources.StandardRoot" >
<PreResources webAppMount="/docs/pi_hosted" base="C:/
ot_docs"
className="org.apache.catalina.webresources.DirResourceSet" />
</Resources>
</Context>
Creating a configuration properties directory

You must create a properties file that contains the setting required to locate your
help files.
To create a configuration properties directory and file:
1. Create a folder where the configuration properties file will be stored, known as
the properties root directory. For example C:\ot_docsconfig\properties
\docsmapper.
Note: You can create the properties root directory on any local drive, but
the directory path must:
• Not contain any spaces or special characters.

• Contain the subdirectories \properties\docsmapper. For example, if
the properties root directory is C:\ot_docsconfig, the full path is C:
\ot_docsconfig\properties\docsmapper.
2. In the pi_hosted_support folder, copy the pidocsapimapper.properties file

from the extracted files to the <properties_root>\properties\docsmapper
directory.
3. Open the pidocsapimapper.properties file in a text editor and define the

webserverHelpRoot and techDocs Root settings as follows:

webserverHelpRoot
The Tomcat root URL for the local help. The URL contains the following
information:
http://<host>:<port>/docsapimapper/docs/pi_hosted
where <host> is the server where Tomcat is deployed and <port> is the port
on which Tomcat listens. For example, on a server named host.
mycompany.com listening on port 8080, the setting is:
http://host.mycompany.com:8080/docsapimapper/docs/pi_hosted
Note: Specify the full server name or IP address as the <host> value.
Do not use localhost. Also, the value you use must be used in all
<host> settings, including URLs. IP address will not resolve to host
names and host names will not resolve to IP address.
techDocs Root
The path to the directory where the help files are stored. For example C:/
ot_docs/docs/pi_hosted.
<product_code>
Each OpenText product online help is identified by a specific product code.
In the <PRODUCT CODE> section of the file, create a new line and specify
your product code as <product_code>=<product_code>.
Note: The Exstream help includes the following product codes:
ccmprj
ccmevt
ccmpto
ccmstt
ccmsys
Example 8-1: Sample pidocsapimapper.properties file
# All values marked by < > must be updated.

# This file should be on the app server class path.
# URL and directory mappings

# helproot server MUST match JS setting
webserverHelpRoot=http://host.mycompany.com:8080/
docsapimapper/docs/pi_hosted
#Path to the help folder root

techDocsRoot=C:/ot_docs/docs/pi_hosted
# <PRODUCT CODE>

# Product directory mapping - will be the same as the

OpenText product name setting in the live Private Help Server
implementation.
# See your product documentation for the specific value for
your product.
# Some OpenText product codes are:
# Media Management: medmgt=medmgt
# InfoFusion: inf=inf
# Web Experience Management: wcmgt=wcmgt
# NOTE: test=test is required to verify the initial set up.
test=test
ccmprj=ccmprj
ccmevt=ccmevt
ccmpto=ccmpto
ccmstt=ccmstt
ccmsys=ccmsys
# Default locale to use

defaultLocale=en
# Parameter names - DO NOT MODIFY UNLESS INSTRUCTED

product=product
version=version
locale=locale
context=context
module=module
type=type
securityKey=security
Installing the descriptor and application files

The final step before testing the Private Help Server is deploying the application
files.
To install the files and start the application:
Important
Verify that Tomcat services are not running when you complete these tasks.
1. Copy the docsapimapper.war file into the <Tomcat_home>\webapps directory.

If there is an existing docsapimapper directory or docsapimapper.war file in
the folder, delete them.
2. Copy the docsapimapper.xml file from the working directory into the
<Tomcat_home>\conf\Catalina\localhost directory. If the Catalina\
localhost directory does not exist, create it.

3. Add the <properties_root> you created in “To create a configuration properties

directory and file:“ on page 90 (for example C:\ot_docsconfig) to the Tomcat
Java classpath.
For example, on Windows run the tomcat<x>w.exe file in the <Tomcat_home>
\bin folder, click the Java tab, and then append the properties root path to the
Java Classpath field. On non-Windows, set the path using the setenv.sh
command.
4. Start Tomcat.
Testing the Private Help Server

After Tomcat starts, you can test the deployment by submitting URL requests to it
through the Private Help Server Test Page. The Test Page contains a simple
JavaScript function that simulates an online help button that can call the test help
pages that are included with the Private Help Server.
Note: The Test Page is intended to verify that your Private Help Server is
installed and configured correctly. The page uses a simple method to request
the help files that may not work with all online help formats. Do not attempt to
modify the page to access other online help files or beyond the tasks described
in the procedure below.
To test the Private Help Server:
1. Extract the Test Help Page - Private Help Server.zip file to a working
directory.
help files.
2. In the extracted Test Help Page - OT Private Help Server folder, locate the
pi_hosted\TestPage.html file, and then open it in a text editor.
3. Locate the urlRoot: setting, and then replace the <host> and <port> values with
your Tomcat server name and the port on which it listens.
4. Save the file and then open it in a browser.
Note: We recommend that you use a recent release of the Firefox or

Chrome browsers.
5. Click Test Your Local Server to test your deployment.

The page displays the URL it will attempt to open based on the settings you
made to the HTML file.
If the Private Help Server is deployed correctly, the URL will be processed and
return a help page that confirms that the deployment is working.

Deploying additional help files

Once you have successfully set up the Private Help Server, you can deploy other
product help files in addition to the test file.
To deploy additional help files:
1. Stop Tomcat.
2. Extract the additional help files to the help root folder you created in “To create
the <help_root> directory:“.
help files.
3. Update the Private Help Server help registry by executing the following
command at a command line prompt:
java -jar <tomcat_home>\webapps\OTHelpServer\WEB-INF\lib
\HelpServer-<version>.jar -d <help_dir> -s
where <tomcat_home> is the path to your Tomcat installation, <version> is an
optional version number in the jar file name and <help_dir> is the help root
folder. For example, the following command updates the help registry for a
help root folder C:\ot_docs\docs\pi_hosted:
java -jar C:\PROGRA~1\APACHE~1\TOMCAT~1.0\webapps\OTHelpServer
\WEB-INF\lib\HelpServer-16.0.0.jar -d C:\ot_docs\docs\pi_hosted -s
4. Edit the pidocsapimapper.properties file and add the product code for your
help on the line below the test setting test=test. For more information, see
“Creating a configuration properties directory” on page 90.
5. Restart Tomcat.
To access the help files, you can use the TestPage.html file as long as you modify
the settings to reflect the values for your help. You can gather these settings from the
file path after you extract the help files to the help folder.
The help file path uses the following convention:
<helproot>/docs/pi_hosted/<product>/<version>/<module>/<language>/
<type>
For example, the OpenText Web Experience Management - Content Workspaces Help
(WCMGT-H-UGD) version 16.4 online help extracts to the following path:
<helproot>/docs/pi_hosted/wcmgt/v160400/wcmgt-h-ugd/en/ofh
So, to use the TestPage.html file, the JavaScript settings must be updated as
follows:
product: 'wcmgt',
version: 'v160400',

type: 'ofh',
module: 'wcmgt-h-ugd'
Note: Exstream has one helpset for configuration and another helpset for
administration. When you update the JavaScript you can set the connection to
one module in each helpset.
To test the configuration helpset, update the JavaScript as follows:
product: 'ccmprj',
version: 'v160200',
type: 'ofh',
module: 'ccmprj-h-cgd'
To test the administration helpset, update the JavaScript as follows:
product: 'ccmsys',
version: 'v160200',
type: 'ofh',
module: 'ccmsys-h-agd'
Modify your installed product to use the Private Help Server

After you have successfully deployed and tested the Private Help Server and added
your copy of the product online help to it, you are ready to modify your installation
of Exstream to redirect help requests from the OpenText Global Help Server to your
Private Help Server. For more information, see “Redirecting help calls to Private
Help Server” on page 96.
8.1.2.1 Troubleshooting the Private Help Server

If you get an error when you attempt to set up the Private Help Server, check the
following common issues:
• Verify that you are using the correct slashes in any folder paths you must specify
in settings. The direction of slashes in folder paths can matter for some operating
systems.
• Verify that the Tomcat classpath is set correctly. The path you specify should not
include the properties\docsmapper folders; it should specify the path to the
folder where you created those subfolders. For more information about setting
the Tomcat classpath, see “Installing the descriptor and application files”
on page 92.
• Analyze the log files in the <Tomcat_home>\logs folder, including the
hosteddocslog.<date> file for more information.

8.1.3 Redirecting help calls to Private Help Server

The default help URL leads to the Global Help Server system. To use the Private
Help Server system you must edit the help Server URL.
The helps for Communications Builder, Control Center and tools are running on the
same help server and have the same Server URL. You can edit the Server URL in
either Communications Builder or Control Center. If you edit the URL in
Communications Builder it is automatically applied to Control Center and tools and
vice versa.
To edit the URL in Communications Builder
1. In Communications Builder, click Tools > Communications Builder Settings.
2. In Server URL, enter the Private Help Server URL (see below).
To edit the URL in Control Center
1. In Control Center, click File > Settings.
2. In Server URL, enter the Private Help Server URL (see below).
Global Help Server URL
http://docsapi.opentext.com/mapperpi
Private Help Server URL
http://<host>:<port>/docsapimapper/mapperpi
For example:
http://dochost:8080/docsapimapper/mapperpi

Part 2
License management
Chapter 9
Managing license files
Unlicensed Communications Server applications run in demo mode by default. In

demo mode, texts in the output are randomly removed and replaced by the text
string “Demo”. To license Communications Server applications, you must get a
license file and connect the license file to the Communications Server applications.
Expired, invalid, damaged or removed license files
• If a license file is expired, invalid or damaged, the Communications Server

application will not start.
• If the license file is removed, the Communications Server application will revert
to Demo mode. This means texts in the output is randomly removed and
replaced by the text string “Demo”.
Requesting a license file

To get your license file you must fill in a license request form. This can be done from
OpenText My Support (https://support.opentext.com/portal/site/css?
customView=newTicketLicenseKey).
Uploading a license file

To connect a license file to your Communications Server applications, you must
upload the license file (strs.lic) to the management gateway base directory of the
host, or to the working directories of the Communications Server applications. If you
upload the license file to both the management gateway base directory and to a
Communications Server application working directory, the license file in the
working directory overrides the license file in the management gateway base
directory.
You can upload a license file in four ways:
• Upload on site level – the license file is uploaded to the management base
directories for all hosts on the site.
• Upload on application domain level – the license file is uploaded to the working
directories for all Communications Server applications in the domain.
• Upload on host level – the license file is uploaded to the management base
directory for the selected host.
• Upload on Communications Server application level – the license file is uploaded
to the working directory for the selected Communications Server application.

Chapter 9 Managing license files
To upload a license file
1. In Control Center, right-click the appropriate node (site, domain, host or

Communications Server application node) and select Upload License.
2. Browse to and open the license file.
3. To make the license file available to the application, you need to restart the
application in Control Center.
Viewing license file details

To examine the license file, you can right-click the Communications Server
application node and select View License.
License file for Exstream production engine

To run Exstream production engine you need a separate licence file (in addition to
strs.lic). This license file, or license key, must be referenced in the Java/Server
Configuration for the Communications Server application. See “Setting up startup
parameters for an Exstream production engine” on page 143 for details.

Chapter 10
Measuring transactions and MicroMessages for
licensing purposes
The Statistics view part of the Supervisor application provides functionality to

analyze the number of transactions that have been processed by Exstream during a
certain time period down to the level of a day and output or input connector.
A transaction is a single instance of any document, writing, records created, adapted

or processed by Exstream. Typical examples include, but are not limited to, the
processing of an invoice, account statement, or sales order confirmation.
Transactions that are smaller than 300 bytes will be flagged as MicroMessages and
might be subject to differentiated licensing terms compared with transactions. These
MicroMessages can also be measured separately in the Statistics view.
Measuring transactions
To measure the number of transactions processed during a certain time period,
such as a calendar year, you need to set up a number of filters:
• Set a date range filter on the column Triggering date for the start and end
date to measure between.
• Select type Event or Process depending on how you have configured
Exstream to deliver output:
• Event based transactions count the number of incoming data records
processed, e.g. Customers in an Exstream Processing Engine, or Events in
a Communications Server Message.
• Process based transactions count the number of Process invocations for
generating output. If you have configured Processes to output in Job
mode or using Document Broker, then one single Process transaction
might contain multiple output documents. In this case you must use
Event based transactions for license measurement.
• Count the overall number of transactions processed by summing up the
daily transaction count. For larger data sets, you normally use the Export
function to get a *.csv file extract that can be analyzed further in external
tools.
Measuring MicroMessages
To measure number of processed MicroMessages, proceed as for transactions
above but select type Custom instead of Event or Process. Set a filter on Name
equals MicroMessage. Sum up the transaction count for the entries on the
selected date range.
For larger data sets, you normally use the Export function to get a *.csv file
extract that can be analyzed further in external tools.

Chapter 10 Measuring transactions and MicroMessages for licensing purposes
More information
See Section 8 “Monitoring statistics” in OpenText Exstream - Supervisor User Guide
(CCMWEBRETR-UGD) for more details on how to use the Statistics view user
interfaces.

Part 3
Managing applications with Control Center
Chapter 11
Getting started in Control Center
Control Center is an administration tool used to deploy, run, and administer

Exstream applications on both Windows and UNIX hosts. From Control Center you
can manage Exstream applications, which include Communications Server
applications, service gateways, and Task Scheduler applications. You can also use
Control Center to create the Exstream repositories.
11.1 Steps checklist in Control Center

This section lists the high-level steps required to get started in Control Center,
prepare to run a Communications Builder Project, and prepare to run the Exstream
web applications.
To get started: See:

Step 1 – Open Control Center, create a connection to a tenant “Connecting to a tenant environment from Control Center”
environment, and log on. on page 106
Step 2 – If required, switch to the tenant administrator role. “To switch roles“ on page 107
To prepare to run Communications Builder Projects: See:

Step 1 – Create a domain. “Creating a domain“ on page 111
Step 2 – Configure the repository settings and create the “Configuring repository settings” on page 125
repositories required for the domain.
“Creating a repository in Control Center” on page 129
“Creating a repository manually” on page 130

Step 3 – Link the repositories to the domain. “Linking a repository to a domain” on page 134
Step 4 – Add one or more Communications Server “Setting up a Communications Server application”
applications to the domain. on page 139
Step 5 – Deploy a Communications Builder Project to a “Deploying a Communications Builder Project” on page 140
Communications Server application.
To prepare to run the Exstream web applications: See:

Step 1 – Verify you have the repositories required to run the “What repositories does a domain require” on page 115
web application(s).
Step 2 – Create a service gateway application. “Setting up a service gateway “ on page 151
Step 3 – Deploy the web applications “Deploying the web applications“ on page 219

Chapter 11 Getting started in Control Center
11.2 Connecting to a tenant environment from Control

Center
Before you can log on to Control Center, you need to set up a connection for your
tenant to a management gateway.
You only need to set up one tenant connection to manage Exstream applications on
the other management gateways in your environment. If you work with several
tenants, you need to set up one connection for each tenant. You can use the same
management gateway to connect to each tenant, but with different tenant names.
In cases where the management gateway you are connected to is no longer available,
you can remove the tenant node in Control Center. Removing the tenant node does
not remove the tenant or management gateway from the overall Exstream
environment.
Before you begin

• You need the address and port for the management gateway, your tenant name,
user name, and password.
To set up a connection for a tenant
1. Open Control Center.

2. Right-click the root node and then click New Tenant Connection.
3. In the Select Management Gateway dialog box, click Add.
Note: Because Control Center, Communications Builder, and Describer

use the same connection settings, you may already have a connection
available.
4. Enter a name for the connection, and the host and port for the management
gateway:
• Host
The address of the computer or host with the management gateway you
want to connect to. For example https://localhost
• Port
The port used for communication with the management gateway. The
default port is 28700.
5. Optional Change the default time-out settings:
• Connect time-out (milliseconds)

The time Communications Builder, Describer, and Control Center wait when
trying to establish a new connection to the management gateway.
• Send and receive time-out (milliseconds)

11.3. Understanding the Control Center user interface
The time Communications Builder, Describer, and Control Center wait for
responses from the management gateway after the initial connection is
established.
6. Click OK.
7. If the login dialog does not display automatically, double-click the new tenant
connection to open it. Then enter the tenant name, user name, and password.
A node for the tenant is added to the Control Center tree view. You cannot
change the node name.
Tip: You can change or remove the management gateway connection settings
in the Select Management Gateway dialog box by clicking Edit or Delete.
To connect to the tenant environment
1. Right-click the tenant node and click Connect.

2. Enter your user name, and password, and then click OK.
To switch roles
When working in Control Center, you can only access the functionality available to
your active role, which is either the tenant administrator or tenant user. If you have
several roles, you are logged on as the tenant user by default. You can then change
between the tenant administrator and tenant user roles.
1. Click the tenant node and then in the Properties view, double-click
Management Gateway user role.
2. Click the appropriate role.
To remove a tenant node from the tree view
1. Right-click the tenant node and select Remove.

2. Click Yes to confirm the removal.
11.3 Understanding the Control Center user interface

The following views are available in the Control Center user interface:
• Tree view
This is the top left frame in Control Center. The tree view displays applications
by domain and host. If the same host is used to run applications in several
domains, the host is shown under each domain. The view also displays the
available repositories and connection profiles in the Repositories folder.
• Properties view
This shows the properties for the selected object (domain, applications, etc.).
• FastCopy view

Chapter 11 Getting started in Control Center
This shows the FastCopy source and destination pairs for the selected
To display the FastCopy view, right-click the Communications Server application
and select FastCopy view. To return to the Properties view, right-click the
Communications Server application and select Properties view.
• Service view
This shows the service names and the service version numbers for the services
that are run by the selected Communications Server application.
• Log view
This shows the logs for the selected application.
To display/hide the log view in Control Center, right-click the application and
select View Log.
To display or hide the status bar at the bottom of the Control Center window
• Click View > Status Bar.
To display or hide the log view
• Click View > Log Window.
To display or hide the Service view
• Right-click the Communications Server application and click Services View.
To display or hide the management gateways in the tree view
When the host nodes are hidden, the applications are sorted by domain.
• Click View > Show Gateways.
11.4 Changing the font and language options

To wrap the log messages text displayed in the log view
• Click Format > Word Wrap.
To change the font size in the log view
• Click Format > Font Size.
To display large or small icons in the Control Center tree view
• Click View > Large Tree Icons.
To specify the language of the Control Center user interface
• Click Language > Select.

11.5. Tenant and host property descriptions
11.5 Tenant and host property descriptions

These properties are available for the tenant node and each host node in the tree
view.
• Management gateway host

The host name or IP address of the computer with the management gateway.
• Gateway port
The port used for communication with the management gateway. The default
port is 28700.
• Management gateway send and response time-out (ms)
The time Control Center waits for responses from the management gateway after
the initial connection to the management gateway is established. This is specified
in milliseconds.
• Management gateway connection time-out (ms)
The time Control Center waits when trying to establish a new connection to the
management gateway. This is specified in milliseconds.
• Management gateway user name
The user connected to the management gateway.
• Management gateway user role
The role(s) assigned to the user. See also “To switch roles“ on page 107.
• Application domains
The domains that the applications on the host belong to.
• OS platform (host level only)
The operating system of the computer running the Exstream applications.
• Tenant repository vendor
The domains that the applications on the host belong to.
• Tenant repository name
The name of the tenant repository database.
• Tenant repository host
The host name of the computer with tenant repository.
• Tenant repository port
The port used for communication with the repository.

Chapter 12
Creating a domain
12.1 Understanding domains

A domain is a logical grouping of Exstream applications. A common scenario for
using multiple domains is to separate the applications used for development,
testing, and production. Domains can also be used to separate applications that are
used for different business processes or geographical regions. The number of
domains used in your environment and the grouping of applications depends on the
individual requirements of the tenant, company, or organization.
To help you decide how set up the domains, this section describes how domains
work with the repositories, the service gateway, and the Exstream web applications.
In this section
• “Repositories and domains” on page 111

• “Hosts and domains” on page 113
• “Service gateways, the web applications, and domains” on page 113
Repositories and domains

All the applications in one domain share the same set of statistics, queue, message,
tracking, logging, document broker, and temporary data repositories. You can
connect each application domain to one repository of each type. The types of
repositories that are required in the domain depends on what kind of solutions the
Exstream applications in the domain will run. For more information, see “What
repositories does a domain require” on page 115.
Shared or separate repositories
In environments with multiple domains, there are different options for setting up
the repositories.
You can use separate repositories, use shared repositories, or use combinations of
shared and separate repositories. Because all information in the repositories is
assigned a domain ID, the data can be filtered by domain even in environments with
shared repositories.
• Option 1 – Separate repositories

With this option, each domain has its own set of repositories. This approach is
suitable for environments where a higher level of data isolation is required or
where you expect a high load on the repositories.

Chapter 12 Creating a domain
• Option 2 – Shared repositories

With this option, several domains share the same set of repositories.
• Option 3 – Combinations of shared and separate repositories

Each domain can also have some of its own repositories and share some
repositories. For example, two domains may share a central tracking repository
and a central statistics repository, but use separate queue repositories.

12.1. Understanding domains
It is also possible to have an environment where some domains share

repositories and other domains use separate repositories.
Logical databases
Each repository (statistics, queue, message, etc.) is a logical database. This means
you can set up the repositories in the following ways:
• Create all the repositories in a single Oracle schema or SQL Server database.
• Create each repository in a separate schema or database.
• Create some repositories in separate schemas or databases, and create others in a
single schema or database.
Hosts and domains

Domains are independent from hosts. This means you can use different hosts to run
the applications in the same domain, or you can use the same host to run
applications in different domains.
Service gateways, the web applications, and domains

The Exstream web applications use the service gateway application to access the
repositories, the common asset service, and the metadata model.
Each domain requires its own service gateway with unique port numbers. For load
balancing and failover, it is possible to set up several service gateways in a domain.
When being accessed, a web client sends a request to the management gateway,
asking for a service gateway endpoint. The request includes information about the
tenant and the domain to be used.
In environments with multiple application domains, the service gateway used

controls which domain’s data, design resources, and services are accessed. The
following images provide some examples of which data users can access from each
domain.

Figure 12-1: WorkShop and domains
In WorkShop, users only have access to the templates, themes, images, texts and
rules in the domain they sign in to.
Figure 12-2: StoryBoard, ReTouch, and domains

12.2. What repositories does a domain require
In StoryBoard and ReTouch, users only have access to the image, text and rule
resources in the domain they sign in to.
Figure 12-3: Supervisor and domains
In Supervisor, users only have access to jobs and documents in the domains they
sign in to.
In Control Center, you can assign different domains to each repository. In

Supervisor in the Domain column, which is available in all views, you can find all
assigned domains listed and can perform a cross-domain filtering e.g., to see
documents, statistics, messages of the selected domains.
12.2 What repositories does a domain require

This section describes the scenarios when each repository is required and what
information is stored in the repository.
Repository type: Required when: Stores:

Statistics For every domain that runs Communications Processing statistics about the usage of
Server applications. Communications Server applications. See
also, “About processing statistics ”
The statistics is presented using counters, on page 117.
which can be monitored in the Statistics view
in Supervisor.

Queue If queues are used in any of the Input jobs, output jobs, and job
Communications Builder Projects that are run information in queues as specified in the
in the domain. Communications BuilderProject
configuration.
The jobs can be managed in the Queue view
in Supervisor.
Tracking If your company or organization wants to use Tracker IDs and status information for
the Track view in Supervisor or implement top jobs.
another method of tracking top jobs for the
Communications Server applications in the
domain.
See also “Tracking repository usage notes”

on page 117 and “About job tracking”
on page 118.
Message If any of the applications in the domain will Documents created in ReTouch,
run a Communications Builder Project with a Messages that are paused by exceptions
service-enabled message. Examples include: rules, and Message or Document
properties.
• Communications Server applications used
with Supervisor (the Review view),
ReTouch, or StoryBoard
• Communications Server applications with
a Template Engine Process
• Communications Server applications that
store properties for the Message
Logging If you want to use database logging for any of Log messages, etc. See also “Using
the applications in the domain. database logging” on page 179.
The logs can be monitored in the Log view in

Supervisor.
Document Broker To run a Communications Server application Document Broker Documents. See also
that is part of a Document Broker Plus Section 35 “Document Broker” in
solution. OpenText Exstream - Communications
Builder Configuration Guide (CCMPRJ-
The documents can be administered in the CGD).
Produce view in Supervisor.
Temporary data Optional. If you want to temporarily cache Images used in StoryBoard and ReTouch
repository images used in previews. previews.
Collector Archive If you want to store documents in a Collector Documents stored by an Archiver
repository Archive repository, and be able view and application
delete these documents in the Supervisor web
application.
Note: The multi-tenant, tenant, and document tracking repositories are outside
the scope of the domain.

12.2. What repositories does a domain require
12.2.1 About processing statistics

To consolidate processing statistics from Communications Server applications in
several domains, you can link all these domains to the same statistics repository.
Processing statistics
Processing statistics contain information about the usage of Communications
Server and data on key objects, such as:
• Connectors, for example Email, Spool, FTP.
• Processes, for example PageOUT.
• Drivers, for example PDF, PCL, AFP.
• Total number of physical pages produced as output.
Defining custom counters

In addition to the objects above, you can use custom counters in scripts in the
Communications Builder Project to count other objects and transactions that are
significant for your solution. You can use the IncProcStatCounter script
function to define counters for objects and to increase the value of the counters.
For example, you can count specific XML elements, specific StreamOUT fields,
and information retrieval from databases.
When using custom counters, the name of the object to be counted must not
exceed 255 characters.
12.2.2 Tracking repository usage notes

In scenarios where a central Document Broker repository and tracking repository are
used, all the application domains linked to the central Document Broker repository
must also be linked to a central tracking repository.
In environments where there is no tracking repository, notifications, script functions,

and log messages relating to top jobs are not available or return unexpected results.
For example:
• Java notifications relating to top jobs are not available.
• Log messages relating to top job completion are not available.
• Script functions relating to top jobs, such as GetTopJobID, return 0 values.
• Internal job IDs, such as the one returned from GetIntJobID(), are only unique
within one Communications Server application and working directory. The IDs
restart from 1 for each application. If the working directory is deleted, then the
ID also restarts from 1.
• HTTP Response and Java Response connectors do not deliver responses.
• The Service Request input connector does not deliver responses. This means that
the jobsubmit web services only work if FireAndForget is used and none of the
WSDocument preview methods work (getDocumentsContent, etc.). The preview

in ReTouch, Supervisor (from the Review view), and StoryBoard do not work
either.
12.2.3 About job tracking

This section describes how top job tracking works when a tracking repository is
used.
Input and output jobs

When a Communications Server application receives input, for example from an
ERP system, it creates an input job. When the input job is processed, it can
generate several output items. Output items may include:
• Documents delivered by the output connectors
• Messages that are paused and stored in the Message repository
• Documents stored in a Document Broker repository
• Resources stored in the common asset service by the Resource filter or
Resource output connector
Top jobs
When a tracking repository is used, a top job is also created when a
Communications Server application receives input. The top job is assigned a
tracker ID, and is connected to the input job and each of the output items.
How status tracking for top jobs works

Each top job has a counter that tracks the status of the job. Each time an output
item is added to the top job the counter increases by 1. When each output item is
completed, either successfully or with errors, the counter is decreased by 1.
When the counter returns to 0, the top job is marked as either:
• Successfully completed – if all the output items were successfully completed.
• Completed with errors – if one or more of the output items were completed
with errors.

12.3. Creating a domain
When a top job that is connected to Document Broker documents or Messages in

the message repository is marked as completed (either successfully or with
errors), a new top job is generated. The new top job can be used if Document
broker needs the document again or the message is released from the message
repository again. During repository maintenance the initial top job can be
deleted from the repository.
12.3 Creating a domain

Naming requirements for domains
• The name must only include ASCII characters (a-z, A-Z, 0-9).
• The name must not include any white spaces.
Associating a physical layer with the domain (optional)

You can tie a physical platform layer to a domain. For example, if you have the
physical layers Dev, Test and Prod, and tie an application domain to the
physical layer Prod, you can only deploy the Prod layer to the domain. This will
prevent users from deploying the wrong layer by mistake.
To create a domain
1. Right-click the tenant node and select New Application Domain.
2. Click OK. The New Application Domain dialog box opens.
3. Enter a name for the domain.
4. Select the version of the domain.
5. Optional Enter the name of the physical layer you want to tie to the domain.
The name of the physical layer must be the same as the name of the physical
layer specified in Communications Builder.
6. Click OK.
Next steps
• After you create the domain, you must create and link the appropriate
repositories to the domain.

12.3.1 Updating the repository connection profiles

If you make changes to the repository connection profiles linked to the domain, you
must manually update the domain information for the applications. Changes are
applied when the applications are restarted.
To update the domain information for an application, right-click the application and
click Update Application Domain Information.
You can also update the domain information for all the applications in a domain or
all the applications on a host by right-clicking the domain or host and then clicking
Update Application Domain File.
12.3.2 Deleting a domain

Before you can delete a domain, you must delete all applications from the domain. If
you do not have access to the computer (host) where an application was created, you
cannot delete the application. You must then remove the application from the
domain. See “Deleting applications” on page 163.
When you delete a domain, the repositories connected to the domain are not deleted.
To delete a domain
1. Right-click the domain and select Delete Application Domain.

2. Click OK to confirm.
12.4 Approval options for theme resources

There are two ways design resources used in themes can be approved in WorkShop:
• (The default) Cascading approval of resources
With this option, the design resources used in a theme are automatically set to
the approved state when someone approves the theme.
• Individual approval of each resource
With this option, every resource in the theme must have the state approved
before the theme can be approved. This requires that someone sends each
resource used in the theme for review, and that someone with the necessary
permissions approves each resource. If someone tries to approve a theme that
contains resources that are not approved, they will receive an error message and
cannot approve theme.
Configuring the approval method

Using different approval methods in different domains
WorkShop is set up to use cascading approval in all application domains by
default. You can switch off cascading approval for all domains, which includes
both existing domains and any domains that you create in the future. It is also

12.4. Approval options for theme resources
possible to make exceptions for specific domains. For example, you may want to
use cascading approval in the development domain, but not in the testing
domain.
Where to configure the approval options

You configure the approval options in the cascadeapprovestate element in the
mgmgateway.xml file.
Syntax
<cascadeapprovestate defaultEnabled="<true/false>">
<applicationdomainexception name="<domain_name/GUID>"/>
</cascadeapprovestate>
Where:
• defaultEnabled="<true/false>"
Indicates whether cascading approval is switched on (true) or off (false).
This applies to all domains unless you configure an exception in the
applicationdomainexception element.
• <applicationdomainexception name="<domain_name/GUID>"/>
Allows you to switch on/off cascading approval in a single domain. If

defaultEnabled="false", this element switches on cascading approval in a
single domain. If defaultEnabled="true", this element switches off
cascading approval in a single domain.
You can use either the domain name or GUID to identify the domain. We
recommend that you use the GUID, so the configuration applies even if the
domain name changes.
Example 12-1: Cascading approval switched off for every domain
In this example, cascading approval is switched off in all domains.
<cascadeapprovestate defaultEnabled="false"> </

cascadeapprovestate>
Example 12-2: Cascading approval switched off in two domains
In this example, cascading approval is used for all domains except the
staging and production domains.
<cascadeapprovestate defaultEnabled="true">
<applicationdomainexception name="staging"/>
<applicationdomainexception name="production"/>

Example 12-3: Cascading approval used for all domains except one
In this example, cascading approval is only used in the development

domain.
<cascadeapprovestate defaultEnabled="false">
<applicationdomainexception name="development"/>
Environments with multiple management gateways

If there are several management gateways in your environment, you must
configure the approval settings for all the management gateways at the same
time.
To configure cascading approval

\management
2. Edit the cascadeapprovestate element as required.
4. Restart the management gateway(s).
5. From Control Center, restart the service gateway(s) for the affected domains.
12.5 Controlling access to domains

You can control which roles can access each domain via the web applications, such
WorkShop, StoryBoard, and Supervisor.
It is possible to control which domains each of the built-in Exstream roles (tenant
administrators, tenant users, etc.) can access. You can also create custom roles and
grant or deny these roles access to specific domains.
Example 12-4: Configuring roles access to domain
This example shows a custom role that has access to the development
domain, but cannot access the testing and production domains.

12.5. Controlling access to domains
Figure 12-4: Configuring roles access to domain
Table 12-1: Where to set up roles and access to domains
To See
• Set up a custom role Section 10 “Managing roles” in OpenText
Exstream - Supervisor User Guide
(CCMWEBRETR-UGD)
• Configure which domain each role can Section 3.10 “Controlling access to resources”
access in OpenText Exstream - WorkShop User Guide
(CCMWEBRMG-UGD)

Chapter 13
Creating repositories
You can either create the Exstream repositories directly in Control Center, or you
can generate the database scripts in Control Center and then run the scripts using an
external tool. For example, if the company security policy prevents Control Center
from connecting to the database, or if you want to have full traceability of the
repository creation.
If Control Center is not available, you can carry out the corresponding procedures
using the command line utilities. For more information, see “Managing applications
with command line utilities” on page 183.
For production or testing environments, you should review the information in

“Adjusting repositories” on page 134 and, if necessary, adjust the created
repositories.
Tip: When handling Exstream repositories, OpenText recommends that you

use the tools, applications, and scripts provided by OpenText. For example,
Communications Builder, Control Center (or command line utilities), and the
Exstream web applications.
Use the appropriate tool from the database vendor only for tasks which cannot
be performed using the tools provided by OpenText. When running external
tools, you should primarily use the database scripts provided by OpenText.
13.1 Configuring repository settings

All the Exstream repositories (queue, tracking, etc.) must use the same database
vendor.
Recommendations
• OpenText recommends that you change the default repository users that are
suggested in Control Center.
• In production and testing environments, after you create the repository, you
should review the information in “Adjusting repositories” on page 134 and
make any necessary changes to the repository.
To configure the settings for a repository
1. In Control Center, right-click the Repositories node, click New Repository, and
then click the repository type:
• Collector Archive
• Content Server

Chapter 13 Creating repositories
• Document Broker Repository

• EasyLink Reports
• Logging Repository
• Messagestore Repository
• Queue Repository
• Statistics Repository
• Temporary Data Repository
• Tracking Repository
2. Enter a name and description for the repository and then click OK.
3. Configure the database settings, see:
• “Database settings: Microsoft SQL Server/PostgreSQL/SAP HANA”

on page 126
• “Database settings: Oracle Database” on page 127
4. Click OK.
5. If required, specify additional arguments to send to the database driver. See

“Specifying custom arguments for the database driver” on page 129.
Database settings: Microsoft SQL Server/PostgreSQL/SAP HANA
Note: The Database name, User name, and Password settings must follow the
naming standards of the database server.
• Database vendor
SQL Server, Postgres, or HANA.
• Host name
The IP address or host name of the database server.
If you use a named instance of SQL Server, you must specify the host name and
instance name using the syntax <hostname>\<instancename>. For example:
gbg5000\instance1
• Port
• For SQL Server the default is 1433.
• For Postgres the default is 5432.
• For SAP HANA the default is 30015.
• Database name
A name for the repository.

13.1. Configuring repository settings
• If SAP HANA is installed in single-container mode, you must leave this field
empty.
HANA Tenant database must be set up in the database system before you
create the repository.
• Recovery Settings > On lost repository connection
Specifies how the application should reconnect to the repository in case of a lost
connection.
• Attempt recovery a limited number of times – The application tries to make
<x> number of reconnection attempts to the repository.
• Attempt recovery an unlimited number of times – The application tries to
reconnect to the repository until a connection has been successfully
established.
• Do not attempt recovery – The application does not try to reconnect to the
repository.
• Recovery Settings > If reconnection attempts fail
The action to take if the reconnection fails.
• Stop processing on the affected Repository – The current job is aborted and
the application is stopped.
• Ignore the failure and continue processing – The application continues to
process the current job.
• Recovery Settings > Reconnection attempts
The number of times the application attempts to reconnect the repository.
• Recovery Settings > Time between attempts
The time (in seconds) between the reconnection attempts.
• User name
The user name to access the repository. For example, the data administration
user that the management gateway uses to connect to the repository. The user is
automatically created when the repository is created. You cannot use the system
administrator as user name (for example, sa).
On SAP HANA, this will be the schema owner.
• Password
The password to access the repository.
Database settings: Oracle Database
Note: The User name and Password settings must follow the naming
standards of the database server.
• Database vendor

Oracle
• Host name
The IP address or host name of the database server.
• Port
The port used for communication with the database server (by default, 1521).
• Service name (SID)
The name of the Oracle service to connect to.
• Recovery Settings > On lost repository connection
Specifies how the application should reconnect to the repository in case of a lost
connection.
• Attempt recovery a limited number of times – The application tries to make

<x> number of reconnection attempts to the repository.
• Attempt recovery an unlimited number of times – The application tries to
reconnect to the repository until a connection has been successfully
established.
• Do not attempt recovery – The application does not try to reconnect to the
repository.
• Recovery Settings > If reconnection attempts fail
The action to take if the reconnection fails.
• Stop processing on the affected Repository – The current job is aborted and
the application is stopped.
• Ignore the failure and continue processing – The application continues to
process the current job.
• Recovery Settings > Reconnection attempts
The number of times the application attempts to reconnect the repository.
• Recovery Settings > Time between attempts
The time (in seconds) between the reconnection attempts.
• User name
The user name to access the repository. For example, the data administration
user that the management gateway uses to connect to a tenant repository. This is
also used as the schema owner. The user is automatically created when the
repository is created. You cannot use the system administrator as user name.
• Password
The password to access the repository.

13.2. Creating a repository in Control Center
13.1.1 Specifying custom arguments for the database driver

You can send additional options to the database driver by configuring these as
arguments in a file called cl.properties.
This file must be saved in C:\Users\<user_name>\dbadmintool-files.
Arguments
suffix
The suffix added to the authentication profile user name when logging on.
options
Custom JDBC connection string options.
Example 13-1: cl.properties
This example shows the arguments for a DataDirect JDBC driver.
options=EncryptionMethod=SSL;VALIDATESERVERCERTIFICATE=false;
suffix=u7zaf2wibw
Example 13-2: cl.properties
This example shows the arguments for a Microsoft ODBC Driver and
Microsoft SQL Server named streamserve.database.windows.net
options=encrypt=true;hostNameInCertificate=*.database.windows.
net;loginTimeout=30;
suffix=streamserve
13.2 Creating a repository in Control Center

Prerequisites (SQL Server)
• The login details for the system administration user (sa) are available.
Note: You cannot create the repository directly from Control Center if the
password contains certain characters. For example: [] {}() , ; ? * ! @
For more information, see http://msdn.microsoft.com/en-us/library/
ms161962.aspx
• If you use a named instance of SQL Server, the SQL Server Browser service must
be started before you create the repositories.
Prerequisites (Oracle)
• The login details for the database administration user are available.

Prerequisites (SAP HANA)

• The login details for the SYSTEM user of the SAP HANA Tenant database
(multiple-container mode) or SYSTEMDB database (single-container mode) are
available.
To create a repository in Control Center
1. In Control Center, right-click the node for the repository and select Create
Database.
2. In the Operation area, select Create now.
3. Select the repository from the drop-down list.
4. Click Start to run the scripts.
5. In the Connect dialog box, enter the logon details for the administration user.
6. Click OK.
7. Optional Click Open Log File to open the full log in the default text editor.
Post requisites
• Do a sanity check to make sure the repository was created according to your
configurations.
13.3 Creating a repository manually

To create a repository manually, you must first generate the database scripts for the
repository in Control Center and then execute the scripts in an external tool.
When you generate the database scripts, the scripts are saved as a ZIP the following
directory:
<Base directory>\<Version>\root\config\database\<Name>-<GUID>.zip
Where:
• <Base directory> – Is the path specified for Exstream Projects during the
Communications Server installation. For example: C:\ManagementGateway
• <Name> – Is the name of the repository.
• <GUID> – Is a globally unique identifier for the zip file.
To generate database scripts
1. In Control Center, right-click the node for the repository and select Create
Database.
2. In the Operation area, select Create scripts for later use.

13.3. Creating a repository manually
4. Click Start to generate the scripts. When the scripts are generated, you can save
a local copy of the scripts.
The ZIP file contains two scripts:

• load_as_sys.sql script to create the database.
• load.sql script to create the tables etc. for the repository.
For information about how to run the scripts, see the following sections:
• “Executing database scripts: Microsoft SQL Server” on page 131
• “Executing database scripts: Oracle Database” on page 131
• “Executing database scripts: PostgreSQL” on page 132
• “Executing database scripts: SAP HANA” on page 133
Executing database scripts: Microsoft SQL Server

Prerequisites
• The login details for the system administrator user are available. For example the
sa user for SQL Server.
• The ZIP file with the database scripts is generated in Control Center and
unpacked using an archiving application, such as WinZip.
To execute the scripts
1. Open the appropriate SQL Server tool. For example, Microsoft SQL Server
Management Studio or SQLCMD.
2. Log in as the system administrator user. For example for SQL Server sa.
3. Run the load_as_sys.sql script.
4. Run the load.sql script in the database created in Step 3 above.
Post requisites
configurations.
• Since the scripts contain passwords, we recommend that you delete the scripts
after you have created the repository.
Executing database scripts: Oracle Database

Prerequisites
• The login details for the SYSDBA user and the schema owner are available.

1. Since the password of the schema owner is the same as the schema owner user
name, it is recommended to change the password in the load_as_sys.sql
script.
2. Open the appropriate Oracle tool. For example, Oracle SQL Developer or
SQL*Plus.
3. Log in as the SYSDBA user.
4. Run the load_as_sys.sql script.
5. Log in as the schema owner configured for the repository.
6. Run the load.sql script.
Post requisites
configurations.
Executing database scripts: PostgreSQL

Prerequisites
• The login details are available for a user with the ADMIN and SUPERUSER
privileges.
1. Connect to the database server as the user with ADMIN and SUPERUSER
privileges.
2. Run the load_as_sys.sql script to create the database.
3. Create a new user with the appropriate privileges to the database.
4. Alter the new user to give the SUPERUSER privilege.
5. Connect as the new user.
6. Run the load.sql script to create the schema.
7. Create the “uuid-ossp” extension, for example with the command CREATE
EXTENSION "uuid-ossp".
8. Alter the new user to remove the SUPERUSER privilege.

13.3. Creating a repository manually
Post requisites
configurations.
Executing database scripts: SAP HANA

Prerequisites
• The login details for the SYSTEM user of the SAP HANA Tenant database
(multiple-container mode) or SYSTEMDB database (single-container mode) are
available.
• The login details for the schema owner are available.
1. Open the appropriate SAP HANA tool. For example, SAP HANA HDBSQL.
2. Run the load_as_sys.sql script as the SYSTEM user. For example:

"<Path to hdbsql>" -n <Host>[:<Port>] -i <Instance number> -u SYSTEM
-p <Password> [-d <SAP HANA TENANT DATABASE>] -c "/" -I "<Path to
load_as_sys.sql>"
3. Run the load.sql script as the schema owner. For example:

"<Path to hdbsql>" -n <Host>[:<Port>] -i <Instance number> -u
<SCHEMA OWNER> -p <Password> [-d <SAP HANA TENANT DATABASE>] -c "/"
-I "<Path to load.sql>"
Post requisites
configurations.

13.4 Linking a repository to a domain

This section describes how to link an Exstream repository to a domain.
Prerequisites
• The repository must be created in the Repositories folder.
To connect the repository to a domain
1. In the Repositories folder, right-click the repository and select Link

Application Domain.
2. In the Link Application Domain dialog box, in the Available Application
Domains area, select the domains you want to connect the repository to.
3. Click the arrow button to connect the repository to the domain.
4. Click OK.
Post requisites
• After connecting a repository to a domain, you must restart the Exstream
applications (Communications Server applications, service gateways, etc.) in the
domain.
13.5 Adjusting repositories

Before using an Exstream repository in a testing or production environment, you
should review the information in this section and make any necessary adjustments
to the repository. How to carry out the adjustments in third party products is not
described. For such information, see user documentation from the database vendor.
Which adjustments are necessary depend on the amount of data in the repository.
The queue repository, Message repository, and Document Broker repository are
examples of repositories that usually include large amounts of data.
If the company has any performance requirements on the repository, this also affect
the adjustments. For example, if there are specific performance requirements on the
tenant repository.
Tip: Exstream repositories on Oracle Database use SecureFiles LOBs by

default. When using the SecureFiles functionality, there are many Oracle
options you can use to improve performance of the database server. For
example, LOB deduplication and LOB compression. For more information, see
the Oracle user documentation.
In this section
• “Indexing” on page 135
• “Partitioning” on page 135

13.5. Adjusting repositories
• “Estimating sizes of database and transaction log” on page 135

• “Editing tablespaces (Oracle Database)” on page 136
Indexing
For most tables, performance is improved if you index one or several of the database
columns.
If the Exstream repository contains dynamically created database columns with user
defined properties configured in Describer, these columns are usually suitable for
indexing. The tenant repository, Message repository, and Document Broker Plus
repository are examples of repositories that contain dynamically created database
columns.
Tip: In the database, the names of the tables that include dynamically created
columns start with cx. You can find out the column names via the
relDocumentTypeMetaDataName table.
You should also adjust your indexes to the queries being used. For example, if a
column is frequently accessed from an Exstream web application, you should
consider indexing this column.
You index columns using the appropriate tool from the database vendor. For
example, SQL Server Management Studio or Oracle SQL Developer.
Note: Indexing columns improves the speed of the data retrieval operations,
but at the cost of increased storage space and possibly decreased insert
performance.
Partitioning
If the Exstream repository contains large tables, performance might be improved if
you partition tables and indexes. The tables and indexes are then split into smaller
components, where each component can be managed and manipulated individually.
You partition tables and indexes using the appropriate tool from the database
vendor. For information about which database editions support partitioning, see the
user documentation from the database vendor.
Note: If the tables contain data, conversion to partitioning is an extensive

operation that requires recreating and reloading of data into the tables.
Estimating sizes of database and transaction log

To prevent the disks from running out of space, you should specify maximum sizes
for the database file and the transaction log for the Exstream repository.
• Database file

You can estimate the size of the database file based on the sizes of the included
database tables. If the database vendor provides a tool with a reporting function,
you can use this tool to find out the actual size of each table.
• Transaction log
The transaction log size should be 20-25% of the database size. However, the
smaller the size of the database, the greater the size of the transaction log, and
vice versa. For example, if the estimated database size is 10 MB, you set the size
of the transaction log to 4-5 MB. If the estimated database size is over 500 MB,
you set the size of the transaction log to 50 MB.
OpenText recommends that you store the transaction log on a separate physical
disk.
Note: Underestimating the sizes of the database file and the transaction logs
may result in automatic file growth and decreased performance.
Editing tablespaces (Oracle Database)

When the Exstream repository is created, all segments (tables, indexes, etc.) are by
default created in a tablespace called USERS.
At runtime, any dynamically created tables and indexes are created in the first found
tablespace called <Name>_DATA (for tables) and <Name>_INDEX (for indexes) in which
the repository owner has a quota. If no such tablespaces are found, the segments are
created in the default tablespace for the repository owner.
You should edit the default tablespace to fit the actual conditions. By using different
tablespaces you can control the disk layout. For example, you can place a heavily
used index on a fast disk and a rarely accessed database table on a less expensive,
but slower disk.
OpenText provides a database script which you can use to edit the tablespaces. You
run the script using the appropriate Oracle tool, for example Oracle Enterprise
Manager or Oracle SQL*Plus.
To edit the tablespaces
1. Create the required tablespaces (locally managed, automatic segment space

management). For example:
• <Name>_DATA for data.

• <Name>_INDEX for index.
• <Name>_LOB for blobs.
2. Give quotas to the repository owner in the created tablespaces.
3. Open the build_move_segments.sql script, located in:
<Base directory>\<Version>\root\config\database\<Version>\oracle

13.5. Adjusting repositories
Where <Base directory> is the path specified for Exstream Projects during the
4. Run the build_move_segments.sql script as the schema owner. The script

spools the DDL (Data Definition Language) move commands to a text file.
5. Check/verify the created text file move_streamserve_segments_TEMP.sql and

run the script.
For example: running build_move_segments.sql:
• Enter current index tablespace: USERS

• Enter current LOB tablespace: USERS
• Enter new data tablespace: <Name>_DATA
• Enter new index tablespace: <Name>_INDEX
• Enter new LOB tablespace: <Name>_LOB
6. Verify that there are no errors in the log file

move_streamserve_segments_TEMP.log.

Chapter 14
Setting up Communications Server applications
14.1 Setting up a Communications Server application

A Communications Server application runs an exported Communications Builder
Project. Each Project is deployed to and run by a separate Communications Server
application. You can use several Communications Server applications, running
different deployed Projects, in the same domain.
For failover reasons, you can deploy a Project to more than one Communications
Server application and let the Communications Server applications share queues.
This means that jobs can be reallocated if the Communications Server application
processing the job goes down or loses connection to the repositories.
If you run several versions of a Project, each Project version requires a separate
Logical names
You can assign logical names to Communications Server applications. You can,
for example, use the name of the corresponding Communications Builder
Project as logical name. The logical name is used as identifier when deploying a
Project to a Communications Server application. For example, if a domain
includes two Communications Server applications with the same logical name
(for example. for load balancing), when you deploy you can select whether to
deploy to both applications or to one Communications Server application only.
To add a Communications Server application
You can add applications on your local host or on remote hosts that are part of the
site.
1. Right-click the domain and select New Application.
2. In the Application type list, click Communications Server.
3. Enter a name for the application and a description (optional).
4. Optional Enter the Application logical name.
5. Optional To add an application on a remote host, select Show all hosts, and then
click the host in the Application host list.
6. Optional Change the startup type and the account that is used to run the
application. See “Startup options and accounts for applications” on page 168.
7. Click OK.

Chapter 14 Setting up Communications Server applications
14.2 Deploying a Communications Builder Project

To run a Communications Server application, you must deploy an export file for a
Project to the application. Each time you export a new version of the Project in
Communications Builder, you must redeploy the export file in Control Center. You
can deploy an export file from the file system or deploy an export file from the CAS.
When you deploy the export file, the content of the file is extracted to the working
directory for the application. The path for this directory is:
<Base directory>\<Version>\root\applications\<Application name>
Where:
• <Base directory> – Is the path specified for Exstream Projects during the
• <Application name> – Is the name of the Communications Server application.
Clearing the data folder when you deploy

You can remove the data folder from the working directory when you deploy a
Project:
<Base directory>\<Version>\root\applications\<Application_Name>
\data
Do not clear this folder if you have stored non-Project related data in this folder.
In this section
• “Deploying a Project from the file system” on page 140
• “Deploying a Project from the CAS ” on page 141
• “Comparing an export file with the deployed export file” on page 141
• “Redeploying a Project” on page 142
Deploying a Project from the file system

1. Right-click the domain for the Project and select Deploy Export File.
2. In the All Hosts list, select the host or hosts with the Communications Server
applications you want to deploy the Project to.
3. In the Available applications area, select the Communications Server

application(s) to deploy the export file to, or create a new application by
clicking New Application..., and then click Next.
4. Select Deploy an export file from the file system, browse to the export file for
the Project, and click Next.
5. Click the physical layer to deploy.
6. Optional Disable Clear data folder on deploy.

14.2. Deploying a Communications Builder Project
7. Optional Select Compare export packages on deploy, which creates a comparison

report that shows the differences between the export file you select and the
deployed export file.
8. Click Finish.
See also
• “Starting, stopping, and restarting applications” on page 157
Deploying a Project from the CAS

You can deploy export files that have been checked in to the CAS in
Communications Builder. Each time a release is created in Communications Builder,
a new export file for the Project is added to the CAS. When you deploy from the
CAS in Control Center, you must select which release of the Project to deploy.
1. Right-click the domain for the Project and click Deploy export file.
2. In the Deploy wizard, select the Communications Server application(s) to

deploy the export file to, and then click Next.
3. In the Deploy wizard, click Deploy export file from CAS, and then click
Browse.
4. In the Select release dialog box, do the following:
• In the Select Project area, click the Project you want to deploy.
• In the Available releases for selected project area, click the release you
want to deploy, and then click OK and Next.
5. Click the physical layer to deploy.
6. Optional Disable Clear data folder on deploy.
7. Optional Enable Compare export packages on deploy, which creates a

comparison report that shows the differences between the export file you select
and the deployed export file.
8. Click Finish.
Comparing an export file with the deployed export file

Before you redeploy an export file, you can compare the file with the export file that
is already deployed to see what impact the deployment will have. For example, you
can see if scripts, fonts, or other resources have been changed.
When you compare export files, a comparison report is displayed, which shows the
following:
• Files that have been added to the new export file.
• Files that exist in the deployed export file but not in the new export file.

• Files that exist in both export files but with differences.
To compare export files (no redeploy)
1. Right-click the Communications Server application and click Compare Export....
2. Browse to and select the export file. A comparison report opens.
3. Optional Click Save to save the report to disk.
To compare export files (at redeploy)
1. Right-click the domain and click Deploy export file.
2. Click the Communications Server application(s) to deploy the export file to and
click Next.
3. Click Deploy an export file from the file system, browse to the export file, and
click Next.
4. Click the physical layer to deploy, click Compare export packages on deploy,
and click Next.
5. Review the comparison report and do one of the following:
• Click Cancel to cancel the deployment.

• Click Finish to continue and deploy the export file.
Redeploying a Project
You need to redeploy the export file or release package in the following scenarios:
• If you changed the Communications Builder Project and want the

Communications Server application to use the new configuration.
• If you have linked new repositories to the domain where the application resides.
If the redeployment fails, none of the Project updates are deployed and the export
file used before the failed redeployment remains on the Communications Server
application.
To redeploy an export file from the file system to an application
• Right-click the Communications Server application and select Redeploy.
To redeploy a release package from the CAS to an application
1. Right-click the Communications Server application and select click Deploy

export file.
2. Follow the wizard. See “Deploying a Project from the CAS ” on page 141.

14.3. Setting up startup parameters for an Exstream production engine
14.3 Setting up startup parameters for an Exstream

production engine
Startup parameters that you set up for the Communications Server application in
Control Center are used for all the Exstream engine plugins in the application.
Exstream Engine Version

The path to and name of the executable file for the Exstream production engine.
For performance reasons, we recommend that the production engine resides on
the same host or computer as the Communications Server application.
Tip: If you specify a custom executable for the Exstream engine in

Communications Builder, it overrides the argument in Control Center.
Exstream Engine License file

The path to and name of the license file for the Exstream production engine.
You must specify either the license file or the license key.
Exstream Engine License key

The license key for the Exstream production engine.
You must specify either the license file or the license key.
Exstream Engine Message Source File

The path to and name of the message resource file for the Exstream production
engine.
To set up the startup parameters for the Exstream production engine
1. Right-click the application and select Java/Server Configuration.
2. Click the (Item list) field and then click the button to the right of the field.
3. In the drop-down list, click the appropriate argument:
• Exstream Engine Version
• Exstream Engine License file
• Exstream Engine License key
• Exstream Engine Message Source File
4. Click Add.
5. In the Value field, enter the argument value.
6. Click OK to complete the configuration and exit the dialog box.

14.4 Testing a Communications Server application

using FastCopy
You can use FastCopy to test Communications Server applications with one or more
Directory input connectors. FastCopy copies files from a source directory to a
destination directory. The source and destination directories can be located on a
local drive or on a remote host.
To open the FastCopy view
• Right-click the application and select FastCopy View.
To create a new Source/Destination pair
1. Right-click the FastCopy view and select Create Pair.
2. In the Source and Destination dialog box, specify the paths to the source and
destination directories, and click OK.
To duplicate an existing Source/Destination pair
• Right-click the Source/Destination pair and select Duplicate.
To edit a Source/Destination pair
1. Right-click the Source/Destination pair and select Edit Pair.
2. In the Source and Destination dialog box, specify the paths to the source and
destination directories and click OK.
To use FastCopy
1. Make sure the Communications Server application is started.
2. Right-click the Source/Destination pair and select Transfer files.
To edit the source file
1. Right-click the Source/Destination pair and select Edit Source. The source file
opens in an editor.
2. Edit and save the source file.
To delete a Source/Destination pair
1. Right-click the Source/Destination pair and select Delete Pair.
2. Click OK to save the changes.

14.5. Versioning of services in Communications Server applications
14.5 Versioning of services in Communications

Server applications
Communications Server applications can expose services for several reasons, for
example:
• To receive requests from Exstream web applications to preview or publish
documents.
• To receive requests from the jobsubmit web service.
To expose services, one of the following must be fulfilled:

• The Message you configure in Communications Builder must be service enabled
• A Service Request input connector must be used.
If you want to make changes to a Project that already has been deployed to a
Communications Server application, you can let separate Communications Server
applications run different versions of the Project, where the services exposed by each
application have the same version as the Project. This means that:
• The web application (or an application using the jobsubmit web service) can
send requests to the correct version of the exposed services, and render
documents using the correct version of the Communications Server application.
• Paused Messages in the Message repository can be previewed and published
with correct output even if you have changed and redeployed the Project,
because the specific service version used when storing the message is still
exposed by one version of the Communications Server application.
To deploy a new version of the same Project, you increase the version number when
exporting the Project, and deploy the new export file. See Section 2.7 “Increasing the
Project version number” in OpenText Exstream - Communications Builder Configuration
Guide (CCMPRJ-CGD).
Viewing the Project version number deployed to a

Communications Server application
You can view which Project version is deployed to a specific Communications
Server application.
Note: The services exposed by the application have the same version number
as the Project.
To view the Project version
1. In Control Center, select a Communications Server application.
2. Select Application > Properties view, and the Project version number is
displayed.

Viewing exposed services

For each Communications Server application, you can view which services are
exposed by the application, including the corresponding version numbers.
Note: The version of a service is identical to the Project version specified when
exporting the Project.
To view the Project version
1. In Control Center, select a Communications Server application.
2. Select Application > Services view.
3. In the Services view, the application's services are listed with their version
numbers.
14.5.1 Searching for services

You can search for services that are exposed by Communications Server
applications.
Note: The service version is identical to the Project version deployed to the
Search criteria
You can search based on name or version, or leave as default to search for all
services and service versions.
• Name – The name for the service to search for. If you know parts of the service
name, you can combine it with a wildcard, for example myservices_* or
*invoice to search for all services ending with invoice
To search for all services, enter the wildcard * symbol (Default).
• Version – The service version number to search for, or leave the wildcard symbol
to search for all versions. You can combine numbers with the wildcard, for
example 2* to search for all service versions starting with a 2.
To search for services
1. In Control Center, right-click the tenant node or domain where you want to
search for services, and select Search.
2. In the Search dialog, enter the search criteria in the Criteria table, or leave as
default to search for all services and service versions.
3. If you want to search in another scope, see “To select search scope“
on page 147.
4. Click Search to search for available services matching the criteria.

14.6. Configuring the thread pool for the queues
Note: Currently the Search for list only shows Services.
To select search scope
1. In the Search dialog, click the button to the right of the Scope field.
2. In the Select Scope dialog, select the nodes where you want to perform the
search.
3. Close the Select Scope dialog.
To go to the application exposing the found service
1. In the Search dialog, select one of the search results.
2. Click Go to.
3. In Control Center, the Communications Server application exposing the service

is highlighted.
14.6 Configuring the thread pool for the queues

All the input and output queues for a single Communication Server share the same
thread pool. The thread pool is only used by one Communications application and is
not shared between applications.
You can configure the thread pool in the jobdispatchqueue element of

threadmanager.xml.
Central or application specific threadmanager.xml configuration
There are two ways you can configure threadmanager.xml:
• Central threadmanager.xml
You can update the common threadmanager.xml file under:
<ExstreamRuntime_installation_folder>\<version>\Server\global
\threadmanager.xml.
Changes made in this file are applied to all the Communications Servers that
don’t have an application-specific threadmanager.xml in the working directory.
• Application-specific threadmanager.xml
You can copy threadmanager.xml to the working directory of a specific
Communications Server and update that file. This applies the configuration to
the single application.
How the thread pool works

By default the thread pool is allocated 4 threads, can grow up to 32 threads at
high loads, and can shrink to a minimum of 4 threads at low loads. Every few
seconds, a temporary scheduler checks if the thread pool needs to grow or
shrink based on the current load.

When running automatic spooling, a maximum of 2000 work items are allowed
in the pool queue in order to avoid memory exhaustion. When more than 2,000
work items are in the queue, redundant queue items are thrown away. For more
information about automatic spooling, see Section 11.6 “Setting up the queue
spooling options” in OpenText Exstream - Communications Builder Configuration
Guide (CCMPRJ-CGD).
Profile counters
You can use the following profile counters to find the number of active threads
and work items in the queue:
• streamserve.notification.profiler.profilerevent.threadpool.
threadcount — The context shows the name of the thread pool. The count
represents the current number of active threads in the pool.
• streamserve.notification.profiler.profilerevent.threadpool.
queuesize – The context shows the name of the thread pool. The count
represents current number of work items in queue.
Recommendations
• The default settings in the threadmanager.xml file should suit most
environments. Because the thread pool adapts to the load, leave the
<maxthreads> setting at a relatively high value to allow the thread pool to grow.
It is also possible to allocate more threads on start up by increasing the value of
the <minthreads> element. OpenText does not recommend decreasing the
<minthreads> element below the default setting of 4.
• When upgrading a 5.x Project, you should consider that the thread pool in
version 16.x is shared for all queues, which means jobs must be distributed
between the connectors appropriately. Best performance is achieved when
running all jobs without sorting. However, if you need to enable sorting, you
should also set the priority for the connectors. For more information about how
to enable/disable sorting and set the connector priority, see Section 8 “Input
connector management” in OpenText Exstream - Communications Builder
Configuration Guide (CCMPRJ-CGD) and Section 9 “Output connector
management” in OpenText Exstream - Communications Builder Configuration Guide
(CCMPRJ-CGD).
Example 14-1: Thread pool settings for the queues
This example shows how to configure a thread pool which is allocated a

minimum of 20 threads instead of the default of 4.
<dispatchqueue type="http://schemas.streamserve.com/uid/
component/dispatchqueueex/1.0" name="http://
schemas.streamserve.com/ uid/resource/jobdispatchqueue/
1.0">
<configuration>
<threadpoolex>
<properties>
<minthreads>20</minthreads>

14.6. Configuring the thread pool for the queues
<maxthreads>32</maxthreads>
<queuelimit>2000</queuelimit>
<minqueuethreshold>4</minqueuethreshold>
<maxqueuethreshold>16</
maxqueuethreshold>
<queuethresholdcheckinterval>1000</
queuethresholdcheckinterval>
</properties>
</threadpoolex>
</configuration>
</dispatchqueue>
Note: <maxqueuethreshold> must be the same size or have a larger value than
<minthreads>.

Chapter 15
Setting up a service gateway
To use the Exstream web applications, you must add a service gateway. For failover
and load balancing reasons, you can add more service gateways.
asking for a service gateway endpoint. The management gateway checks the tenant
repository for available service gateways, and then returns the connection
information for one of the service gateways. The web client uses the returned service
gateway to access the Exstream repositories, the common asset service, and the
metadata model.
In this section
• “ Adding a service gateway” on page 151
• “Updating service gateway ports” on page 151
• “Changing the domain for a service gateway” on page 152
Adding a service gateway

You can add service gateways to your local host or to remote hosts that are part of
the site.

2. In the Application type list, click Service Gateway.
3. Enter a name for the service gateway.
4. Optional Enter a description for the application.
7. Click OK.
Related sections
• “Service gateway secure mode” on page 223
Updating service gateway ports

Each service gateway has two ports, one for communication made via the web
service API and one for communication made via the REST API. In Control Center,

Chapter 15 Setting up a service gateway
the port numbers are set as a range, where the port range start is used by the web
services and the port range start increased by one is used by the REST services. By
default, 2718 is used as port range start.
The port numbers must be unique on each application host. This means you must
update the port range start if you add more than one service gateway to the same
host.
To update the service gateway port range
1. In Control Center, select the service gateway.
2. In the Properties view, right-click Service gateway port range start.
3. In the Edit Value dialog box, update the port range start, and then click OK.
4. Restart the service gateway for the changes to take effect.
Changing the domain for a service gateway

You can change the domain used by the service gateway.
To change the domain
1. Right-click the service gateway, and then click Change Application Domain.
2. Restart the service gateway in the new domain.

Chapter 16
Archiving documents
You can archive documents either to the Collector Archive or to the Content Server.
• Collector Archive – You must set up an Archiver application to store documents
in a Collector Archive repository. You can then use the Supervisor web
application to view and delete documents.
You must:
• Adding an Archiver application
• Configuring a task for the Archiver application
For more information on what is required to use the Archiver application and
Collector Archive repository for viewing and deleting documents via the
Supervisor, see Section 9.9 “Storing documents in Collector Archive database or
Content Server” in OpenText Exstream - Communications Builder Configuration
Guide (CCMPRJ-CGD)
• Content Server – You must set up a Content Server repository.
You must:
• Add a Content Server repository
• Configuring the Content Server repository
For more information on archiving documents and the Content Server repository
to view and delete documents via the Supervisor, see Section 9.9 “Storing
documents in Collector Archive database or Content Server” in OpenText
Exstream - Communications Builder Configuration Guide (CCMPRJ-CGD).
16.1 Adding an Archiver application

You can add Archiver applications to your local host or to remote hosts that are part
of the site.

2. In the Application type list, click Archiver.
3. Enter a name for the Archiver.
4. Optional Enter a description for the application.

Chapter 16 Archiving documents
7. Click OK.
16.2 Configuring a task for Archiver
1. Right-click the Archiver application and select Configuration.

2. Click on the Tasks property and the browse button to the right.
3. In the Service Configuration dialog, select Continuous and click Add. This
means that documents are archived continuously as soon they are ready to be
transferred to the Collector Archive repository.
4. Leave the other properties as default or select another interval at which the
Archiver should archive documents. For more information, see Section 3.5
“Scheduling” in OpenText Exstream - Communications Builder Configuration Guide
(CCMPRJ-CGD)
16.3 Adding a Content Server repository

You can archive documents to the Content Server. For this you have to create a
repository with the type Content Server.
1. Right-click Repository and select New Repository....

2. From the Type list select Content Server.
3. Enter a name for the repository.
4. Optional Enter a description.
5. Click OK.
16.4 Configuring the Content Server repository

In the Profile Configuration Editor for the Content Server repository, the following
settings can be made.
• Name – This field is filled automatically.
• URI – This field is filled automatically.
• Profile sup-type – This field is filled automatically.
• Content Server URL – Enter your Content Server IP address.
• Port – Enter your port number for your Content Server IP address.
• Attempt recovery – Setting for recoveries can be set to Never, Limited times or
Forever. Default is Limited times
• Number of Retries – This field is only available when Limited times has been
selected. Here, you can set the value for retries. Default is 1.
• Retry interval – Value in seconds. Default is 1.

16.4. Configuring the Content Server repository
• Recovery action – Can be set to Abort or Ignore. Default is Abort.

• Authentication profile – The supplied authentication profile has to contain the
user name and password for the Content Server.
• Secure channel profile – The supplied secure channel profile has to contain the
channel type and the Content Server certificate file.
• Secondary connection profile – Empty.
• Content Server folder – None. Path and folder name of the folder in which the
documents should be archived is added here.
• Enable Folder Creation – Empty. In case the supplied folder does not exist on
Content Server yet, activating this check box creates this folder.
• Document name – Empty. Name of the document to be archived.
• Description – Empty. Description for the file.
• Content type – Empty. Information is either entered manually or it is derived
from the document stream.
• Allow multiple version – Empty. Allows to create multiple versions of the
specified document.
• Mapping file – Empty. The supplied mapping file maps metadata from
Describer to Content Server.
• Cache size – By default it is set to 0.
• CS Virtual Path – Path that is appended to the Content Server URL.

Chapter 17
Managing applications
17.1 Starting, stopping, and restarting applications

You can start, stop, restart, or refresh all the applications for a domain or host, by
right-clicking the host or domain, and select the appropriate option. You can also
start, stop, restart, or refresh each application individually.
Hot start of Communications Server applications: - A Communications Server

application that is stopped will start automatically, for example when the
application receives a job or a preview request in ReTouch, StoryBoard, or another of
the web applications. An application that is started automatically continues to run so
long as there is activity, such as further preview requests. After a period of 5
minutes with no activity, the application is stopped again.
To start an application
• Right-click the application and select Start.
To stop an application
• Right-click the application and select Stop.
To restart an application
• Right-click the application and select Restart.
To update the status information displayed for an application
• Right-click the application and select Refresh.
To specify a refresh interval for all applications
1. Select File > Settings.
2. In the Refresh rate in seconds text box, enter the interval to refresh the status of
the applications. For example, if you enter 5, the status information is updated
every 5 seconds.
3. Select the nodes to change the refresh interval for:
• Only selected node and visible subnodes – Refreshes the status information
for applications in the node selected and the subnodes of that node.
• All visible nodes – Refreshes the status information for all the nodes of the
host.
4. Click OK.

Chapter 17 Managing applications
17.2 Administering applications on remote hosts

Remote hosts are displayed in the Control Center tree view after you create an
application on the host.
To administer applications on a remote host, the management gateway on the host

must be connected to the Exstream environment. For more information, see “Adding
a management gateway” on page 71.
To connect to a remote host
1. From the tree view in Control Center, right-click the host node and select
Connect.
2. If prompted, enter the user name and password and click OK.
After you connect to the host, the Exstream applications configured on the host
are visible in Control Center.
17.3 Exploring the management gateway base

directory
You can use the MGW Explorer dialog box to manage files and directories. The files
and directories can be located on the local host or any remote host with a
management gateway that is connected to the same environment, both on Windows
and UNIX.
You can, for example:

• Create and delete directories.
• Cut, copy, and paste single files from one location to another.
The MGW Explorer dialog box opens when you select Host > Explore.
To access the working directory for a Communications Server application directly,

right-click the application and select Explore.
17.4 Scheduling tasks in a domain

You can add a Task Scheduler application to a domain and schedule repository
maintenance tasks such as deleting expired content from the Exstream repositories
each night at 1:00 a.m.
Each Task Scheduler can run several tasks. To ensure that the tasks are executed
even if the Task Scheduler application goes down, you can add several Task
Scheduler applications.
Tasks
You can set up the following types of tasks in each Task Scheduler application:

17.4. Scheduling tasks in a domain
• Run system command

Create a system command task to be executed according to the specified
schedule.
• Run database maintenance
For more information, see “Scheduling index maintenance or coalescing via task
scheduler“ on page 319.
• Delete expired content
For more information, see “Deleting expired content “ on page 305.
• Delete expired tracking information
• Expire content
• EasyLink reports
For more information, see Section 10.5 “EasyLink connectors” in OpenText
Exstream - Communications Builder Configuration Guide (CCMPRJ-CGD).
Setting up a Task Scheduler

To add a Task Scheduler
You can add Task Scheduler applications on your local host or on remote hosts that
are part of the site.
2. In the Application type list, click TaskScheduler.
3. Enter a name for the Task Scheduler.
Note: You cannot use the name Task Scheduler if you run the application
on a Windows host, since this name is used by a Windows service.
4. Optional Enter a description.
7. Click OK.
To set up the log level and tasks for the Task Scheduler
1. Enter the log level for the application. See Log levels on page 174.
2. In the Tasks box, click ....

3. In the Service Configuration dialog box, add the task, see Tasks on page 159.
4. Enter the settings for the task:
• Name
A name for the task.
• Description
A description of the task (optional).
• Schedule
The interval at which the application performs the task.
See “Setting up schedules” on page 161.
Additional settings for Run system command tasks

• Logical task name
The logical name of the system command, to be used in the log file. This
parameter is optional.
• Command
The system command, including parameters, to be executed by the application.
The command must follow the syntax of the operating system where the
application is run. For example, on Windows, use backslash (\) as a directory
separator and quotes ("") for arguments containing spaces. For example, the
following command runs a batch file that triggers reports according to the
specified schedule:
"c:\My Reports\TriggerReport.bat -type ReportType -SortOrder
Alpabethical"
• Working directory
The name and path of the working directory for the system command task. For
example, for the command above you can specify the following working
directory for the reports:
c:\My Maintenance Reports
If you leave this option empty, the working directory for the application is used:
<Base directory>\<Version>\root\applications\<Task Scheduler name>
\wd
Where:
• <Base directory>– Is the path specified for Exstream Projects during the
• <Task Scheduler name> – Is the name of the Task Scheduler application.
Related sections

17.4. Scheduling tasks in a domain
17.4.1 Setting up schedules

This section describes how to set up schedules, for example for Tasks Scheduler
applications. You can set up a single time interval or create more complex schedules.
To open the Scheduler Configuration dialog box
1. Right-click the application and select Configuration. The Configuration dialog

box opens.
2. If no tasks are configured, select the (Item list) field and click the button to the
right of the field. The Service Configuration dialog box opens.
Note: You can edit schedules for already existing tasks directly in the
Configuration dialog box.
3. Create a new task.
4. Select the Schedule field and click the button to the right of the field. The
Scheduler Configuration dialog box opens.
To add an interval
1. In the Scheduler Configuration dialog box, click New (Intervals area). A new
item is added to the list.
2. In Define Interval, select a time unit (Year, Month, etc.) and a frequency for the
action.
For example, by adding an interval and selecting Seconds and 30 in the Define
interval area, you specify that the action should be triggered every thirty
seconds.
Tip: You can move the intervals up or down in the list by clicking Move
up or Move down.
Click Delete to delete an interval.
To set a time frame for a specific interval (optional)
You can select a time unit (Year, Month, Week of Year, etc.), start value, and stop
value for the time frame. For example, by adding a time frame and selecting Day of
Week, and specifying the start value 1 and stop value 3, you specify that the selected
interval should be applied Monday to Wednesday each week.
1. Select the interval.
2. Click New (Apply selected interval area). A new item is added to the area.
3. Select a unit (Year, Month, etc.) for the item and enter a Start and, optionally, an
End value for the time frame.

Tip: If you want to trigger an action at a specific time, you must set both
the Start and End value. If you leave the End value empty, the Scheduler
can start any time after the Start value.
You can move the time frames up or down in the list by clicking Move up
or Move down.
Click Delete to delete a time frame.
To set a time frame for all intervals (optional)
You can add a start date and time and stop date and time for all scheduled intervals
within the configuration. For example, by selecting Start and specifying the current
day and time and selecting Stop and specifying a day and time next year, you
specify that all listed intervals should be ran from today until the specified stop date
and time.
• You can set a time frame for when to apply all intervals in the list. In the Apply
all intervals area, use Date and Time for Start and Stop to set the frame for all
intervals.
Example 17-1: Schedule polling intervals
In this example, a schedule is configured that triggers the action once every
second Monday to Wednesday, and once every hour Thursday to Sunday.

17.5. Deleting applications
Figure 17-1: Schedule example
17.5 Deleting applications

You can delete applications from the tree view in Control Center. This does not
delete the configuration files from the working directory. You must manually delete
these files.
To delete an application
1. Right-click the application and select Delete.
2. Click OK.

17.6 Updating and exporting application properties

You can update the properties of applications, such as the name, description, and
startup options.
It is possible to update some properties, such as the application description and

startup type, while the application is running. To update other properties, you must
stop the application.
To update an application property
1. Select the application.

2. In the Properties view, right-click the property and select Edit Property. The
Edit Value dialog box opens.
3. Enter the new property value and click OK.
To save property information for an application as a text file
You can save the properties (name, description, version, etc.) for an application as a
text file.
1. Select the application.

2. Select File > Export list. The Save As dialog box opens.
3. Browse to the location to save the file, and enter a name for the file.
To rename an application
1. Right-click the application and click Rename.

2. Enter a new name.
17.6.1 Communications Server application properties

• Name
The name of the Communications Server application.
• Logical name
A logical name for the Communications Server application (e.g. the name of the
corresponding Communications Builder Project). The logical name is used as
identifier when deploying to a Communications Server application. All
Communications Server applications in a domain that have the same logical
name are treated as the same Communications Server application.
• Description
The description of the Communications Server application.
• Application type
The type of application, that is Communications Server.

17.6. Updating and exporting application properties
• State
The status of the application, for example running or stopped.
• Application Domain
The domain of the Communications Server application and status of the domain
configuration.
• Current – The most recent version of the domain configuration is used for the
application.
• Out of date – The domain configuration has been updated, but the new
configuration has not been applied to the application.
• Communications Server version
The version of the Communications Server used to run the application.
• Startup type
How the Communications Server application is started. For example, automatic,
manual, or disabled.
• Log on
The account used to run the Communications Server application.
• Export file
The name of the export file deployed to the Communications Server application.
The path to the working directory for the Communications Server application.
• Log files
The name of the log files for the Communications Server application.
• Management gateway host
The computer used to run the Communications Server application.
• Deployment timestamp
The date and time the export file was deployed.
• Project name
The name of the Project deployed to the application.
• Project export timestamp
The date and time the last export was made in Communications Builder.
• Project label
If the Project is deployed from the file system, this is the creation date and time of
the export file.
If the Project is deployed from a version control system, this is the label of the
export file.
• Physical layer

The physical layer of the Platform that is deployed to the Communications

Server application.
• Temp directory
The directory (relative to the working directory) containing temporary files for
the Communications Server application and the platform.
• Debug mode
Enables or disables debug mode for the Communications Server application. For
example, disabled, enabled, or enabled verbose.
• Cache size (KB)
Not applicable.
• Profiler
Enables or disables the Profiler service, used to investigate how the Exstream
software behaves during processing. For more information, see “Profiling and
tuning your environment” on page 351.
• Project version number
The version number of the exported Project deployed to the application. The
version number is specified when exporting the Project from Communications
Builder.
Applications with deployed Projects exported from old releases of
Communications Builder, without the version property, have version number 1.
• Input connectors
Enables or disables the input connectors used by the Communications Server
application the next time it is started. If you run several versions of the same
Project in parallel and they use shared resources for input data (folder, HTTP
port, email account etc.), it can be useful to disable the input connectors for the
old Communications Server application versions. The old application versions
are still running, enabling documents stored in Message store to e.g. be
submitted. However, no input data is picked up by these applications, which
potentially can cause erroneous output.
Also, regardless of whether you version your services or not, it can be suitable to
temporarily disable input connectors of specific Communications Server
applications. For example, if you want to increase performance for other
Communications Server applications.
Note: Service Request connectors cannot be disabled.
• Mini dump
See “Generating dump files for applications on Windows” on page 171.

17.6. Updating and exporting application properties
17.6.2 Service gateway and task scheduler application

properties
• Name
The name of the application.
• Description
The description of the application.
• Application type
The type of application.
• State
The status of the application, for example running or stopped.
• Application Domain
The domain of the application and status of the domain configuration.
• Current – The most recent version of the domain configuration is used for the
application.
• Out of date – The domain configuration has been updated, but the new
configuration has not been applied to the application.
• Service Gateway version
Only applies to service gateways
The version of the service gateway used to run the application.
• Startup type
How the application is started. For example, automatic, manual, or disabled.
• Log on
The account used to run the application.
The working directory for the application.
• Log files
The log files for the application.
• Service gateway secure mode
Indicates if the service gateway runs in secure mode.
• Service gateway port range start
The start of the port range for the service gateway.
• Service gateway port (web service)


The port used for communication with the service gateway via the web services.
• Service gateway port (web service)
The port used for communication with the service gateway via the REST
interface .
• Temp directory
The directory (relative to the working directory) containing temporary files for
the platform.
• Debug mode
Enables or disables debug mode for the application. For example, disabled,
enabled, or enabled verbose.
• Profiler
Enables or disables the Profiler service, used to investigate how the Exstream
software behaves during processing. For more information, see “Profiling and
tuning your environment” on page 351.
• Mini dump
See “Generating dump files for applications on Windows” on page 171.
17.7 Startup options and accounts for applications

This section describes the startup options and account settings for Communications
Server, service gateway, and Task Scheduler applications.
Startup types
This specifies how the application is started.

• Automatic
Starts the application automatically when the management gateway starts. You
must start the database server before you start the management gateway.
• Manual
Starts the application manually.
• Disabled
Disables the application.
Account to run the application on Windows
On Windows, you can specify the account that is used to run the application:
• Log on as: Local System account
Runs the application under the local system account. This is the default option.

17.8. Configuring Java parameters for applications
• Log on as: This account

Specifies the user name and password for another account, and runs the
application under that account.
17.8 Configuring Java parameters for applications

You can configure Java parameters, such as the target JRE (Java Runtime
Environment) vendor and the Java class paths, for each Exstream application
(Communications Server application, or service gateway).
Name/value pairs
You configure the parameters as a name/value pair. The name/value pair must
follow the standard syntax for Java properties (name<Delimiter>value). For
example, for the Java system property -Djava.library.path=c:\mylibs:
• Name: java.library.path
• Value: c:\mylibs
To configure a parameter with a non-standard syntax, you must enter the full
parameter in the name field and leave the value field empty. For example, for the
Java option -Xdebug:
• Name: Xdebug
• Value: (empty)
To configure Java parameters
1. Right-click the application and select Java/Server Configuration.

2. If required, edit the default parameters directly in the list.
3. To add new parameters or configure parameters, select the (Item list) field and
click the button to the right of the field.
4. Add and configure the required Java parameters.
5. Click OK to update the list in the Java Configuration dialog box.
6. Click OK to complete the configuration and exit the dialog box.
Java parameters
• Java Vendor
The JRE (Java Runtime Environment) vendor.
• Name: Java Vendor
• Value: none (default), Oracle, or IBM
The option none means that the Java support is disabled. No JVM (Java
Virtual Machine) will be loaded.

• File encoding
Only used for service gateway applications
The character encoding used by the JVM (Java Virtual Machine) when it is
loaded.
• Name: file.encoding
• Value: UTF-8
• Java Class Path
A semicolon separated list of directories, JAR (Java ARchive) files, and ZIP
archives to search for class files.
If all class files are located in one of the following directories, you do not have to
specify the Java class path:
• <Working directory>\java
• <Working directory>\..\data\java (only for Communications Server
applications)
For example:
• Name: Java Class Path

• Value: c:\jndi.jar; c:\myjavaclasses
• Java Option
A Java option.
Note: Do not include “-” in the name.
For example:
• Name: verbose
• Value: jni
• Java System Property
A Java system property.
Note: Do not include “D” in the name.
For example:
• Name: java.library.path
• Value: c:\mylibs

17.9. Generating dump files for applications on Windows
17.9 Generating dump files for applications on

Windows
When a Communications Server application, service gateway, or Task Scheduler
stops because of a runtime error that is not handled, it generates a dump file to help
you identify where the problem occurred.
Dump files are created in the working directory with the file name <date>-<time>-
StreamServe-<PID>.mdmp, where <PID> is the process ID of the application.
Note: When Java is configured for an application (see “Configuring Java

parameters for applications” on page 169), the Java runtime environment
controls runtime error handling and the creation of dump files.
Types of dump files
Exstream applications generate a full dump file by default. You can change this to a
mini dump file or disable the dump file for the application.
• Mini - Contains stack information from the time the application went down.
• Full (default) - Contains stack information and the memory content of the
application from the time the application went down.
To change the type of dump file or disable the dump file
1. In the Control Center tree view, select the application.
2. In the Property view, double-click Mini Dump, and select the type of report:
• Disabled
• Mini
• Full
3. Click OK.
Tip: At the command line, use the -minidump <report type> argument to set
the report type. Where <report type> is mini, full, or disable.

Chapter 18
Logging in Control Center
18.1 About the logs

From Control Center you can view the log for each application and change the log
levels. You can also enable database logging for each application and store the log
information in a logging repository. See “Using database logging” on page 179.
Log files and paths

Each Communications Server, service gateway, and Task Scheduler application
has two log files, which are found in the working directory of the application:
• Boot log – which contains early startup messages. File name <application
wd>/strsboot.log
• Application log – which contains runtime log messages. File name
<application wd>/log.txt
In addition to the boot and application logs, the service gateway has a Java log
file (servicegateway_rest.log). For information about the log file entries and
using the service gateway Java log file, see “Service gateway REST log”
on page 275.
Control Center log view

The log view in Control Center contains the same information as the
corresponding platform.txt log file for Communications Server, task
scheduler, and service gateway applications. If you want to, you can clear the
information displayed for the application (right-click the log view and select
Clear). This action clears the log displayed in Control Center, but does not affect
the corresponding log file.
Log file entries

Each entry in a log file consists of the following:
<date> <time> (<logMessageID>) <logLevel> <logMessage>
Where:
• <date> – Is the date the log entry was created.
• <time> – Is the time the log entry was created.
• <logMessageID> – Is the log message ID. Each type of log message has a
unique ID.
• <logLevel> – Is the severity level of the log message.
• <logMessage> – Is the log message.

Chapter 18 Logging in Control Center
Example 18-1: Log entry

0309 033344 (0260) 3 SCF started.
18.2 Specifying the log level

The log level determines which type of messages to include in the log. The log level
spans from 0 to 4. The higher the number, the more details are added to the log.
You specify the log level for each application separately.
Log levels
• 0 – Severe errors only.
• 1 – As level 0 plus all other types of errors.
• 2 – As level 1 plus warnings.
• 3 – As level 2 plus information messages.
• 4 – As level 3 plus extended information messages.
Specifying the log level for an application

To change the log level for an application
1. Stop the application.

2. In the Control Center tree view, right-click the application and select Log
Configuration. The Log Configuration dialog box opens.
3. Change Log level to the appropriate level and click OK.
4. Start the application.
Note: The Log level option in the Configuration dialog box for Task Scheduler
applications is not applicable.
18.3 Creating a new log file at startup

The Communications Server application normally appends log messages to the
same log file after it is restarted. You can specify that a new log file is created each
time the Communications Server application is restarted. The old log file is deleted,
and not stored anywhere.
To delete old log file at startup


18.4. Log file truncation
3. Expand the Type=File provider
4. Click the Delete option and select Yes from the drop-down list.
18.4 Log file truncation

The Communications Server application normally appends log messages to the
same log file. This means more and more messages will be appended to the log file.
To prevent the log file from becoming to large, you can truncate the log file using
time and file size as trigger. The old log file is then closed and saved, and the
Communications Server application starts writing to a new log file.
To use time as trigger
3. Expand the Type=File provider.
4. Click the Time restrictions option and select Yes from the drop-down list.
5. Click the Time limit option and enter a number of days.
6. Click the Move time option and enter at what time during the day the log file
should be closed and moved.
7. Click the Savepath option and enter a path to a folder to which the log file is
moved.
18.5 Editing log providers – reference

There are three log providers that you can configure:
• Log console
• Log file
• Log database
To configure log providers
3. Expand the Provider setting for the provider you want to configure.
4. Edit the provider and click OK.

18.5.1 General provider settings

The following settings are available for all providers:
Provider
By default the provider have the following names:
Console Type=Console
File Type=File
Database Type=Database
Enabled
• Yes – Enables the provider.
• No – Disables the provider.
Type
• The provider type (read-only)
18.5.2 Console provider specific settings

Message Info
• A value that represents the amount of information that is displayed in the log.
The value is a sum of the values starting from the top in the following list:
(Default value is 7 which will display time, message ID and log level.)
001 Time
002 Message ID
004 Log level
008 Application ID
010 User ID
020 Thread ID
040 Job ID
080 Source code information
100 Top level (only valid if log level is present)
200 Year (only valid if time is present)
400 External job ID
800 Receiver
1000 Tenant ID

18.5. Editing log providers – reference
2000 Application domain ID

4000 Milliseconds (only valid if time is present)
Example 18-2: Message info value
Consider you want time, message ID, log level and application ID to be
displayed in the log message. Then you sum up 001 + 002 +004 +008 = 15
which is the value you specify for this option.
18.5.3 Log file provider specific settings

Message Info
• See “Console provider specific settings” on page 176
Delete
• Yes – Log file is deleted after restart of the application.
• No – Log file is not deleted after restart of the application.
Size Restrictions
• Yes – Select to specify maximum log file size.
• No – No log file size restrictions.
Size limit (MB)

• If Size Restrictions has been set to Yes, specify the maximum size of the log file in
megabytes
Time Restrictions
• Yes – Select to specify maximum number of days to use the log file.
• No – No log file time restrictions.
Time limit
• If Time Restrictions has been set to Yes, specify the number of days the log
messages are kept in the logging repository.
Move Time
• At which time during the day the log should be moved.
Savepath
• The path to a folder where the log is saved. The folder is created if it does not
exist.

18.5.4 Log database provider specific settings

Time limit
• The number of days the log messages are kept in the logging repository.
18.6 Debugging applications

You can enable debugging to include more log information in the logs.
The following options are available:

• Disabled – Disables debugging.
• Enabled – Enables debugging to include extended log information. For example,
for ODBC calls, SQL statements are included in the logs.
• Enabled verbose – Enables verbose debugging to include all available log
information. For example, for ODBC calls, SQL statements and parameters are
included in the logs.
Note: The formats of the parameters presented in the logs may not
correspond to the formats actually used in the SQL statements. For
example, timestamps are presented differently in the logs.
The configured option applies to all logs (boot log, platform log, and application
log), for the selected application.
To enable debugging
1. Select the application node in the tree view.
3. In the Properties view, double-click Debug mode. The Edit Debug Mode dialog
box opens.
4. Select the appropriate debug option and click OK.

18.7. Using database logging
18.7 Using database logging

You can enable database logging for each application (Communications Server,
service gateway, and Task Scheduler) and store the log information (platform.txt)
in a logging repository.
The database logs include the same information as the log files (see Log file entries
on page 173), but also additional information such as <year>, <job ID>, <external
job ID>, and <thread ID>. Using database logging enables you to examine the logs
from several applications using, for example, <date> and <job ID> as search
criteria.
Tip: To examine the database logs, you can use the command line tool
LogWebServiceClient.exe located in:
<Exstream_Installation_directory>\Platform\Core\<version>\bin\
See the tool help text for information on how to use this tool (enter
LogWebServiceClient.exe -h in a command prompt).
Enabling database logging

You enable database logging separately for each application.
To enable database logging
2. In the Control Center tree view, right-click the application, and then select Log
Configuration.
3. In the Log Configuration dialog box, change Database logging to Enabled, and
then click OK.
Setting up a logging repository

You must create a logging repository, and link the repository to the domains that
contain the applications for which database logging is enabled. Several domains can
be linked to the same logging repository.
The default database name for the logging repository is StrsDataBaseLog.
Steps to create a logging repository

Follow the steps in these sections to create a logging repository:
1. “Configuring repository settings” on page 125.
2. “Creating a repository in Control Center” on page 129 or “Creating a
repository manually” on page 130.
3. “Linking a repository to a domain” on page 134.

Removing old log messages from the logging repository

By default, log messages are kept one day in the logging repository, and then
removed. You can change this time limit for each application separately.
To set a time limit for log messages
2. In the Control Center tree view, right-click the application, and then select Log
Configuration.
3. In the Log Configuration dialog box, change Time limit to the appropriate
number of days, and then click OK.

Chapter 19
Maintaining Exstream components
19.1 Finding installed components

You can view the components and version information installed on a computer. This
information is required when you report an incident to OpenText Support.
OpenText Support may also need the schema versions and hotfixes applied to the
Exstream repositories. In Control Center, you can list all repositories that belong to a
site, together with their current schema versions.
To find the components installed on a computer
• In the Control Center tree view, right-click the host and select View Installed
Versions.

Part 4
Managing applications with command line
utilities
Chapter 20
About the command line utilities
The command line utilities can be used in a UNIX environment or in environments

where it is not possible to connect to Exstream components from a computer
running Microsoft Windows. The command line utilities also provide the possibility
to automate or script certain tasks.
From the command line utilities you can administer Exstream applications, create
repositories, and add new tenants to Exstream.
Access control for the command line utilities is provided by OTDS.
About the utilities
ss_tenantadmin
For creating the connection profiles for OTDS and the multi-tenant repository.
This utility can also be used for adding tenants, updating tenant details, etc. See
“Setting up the Exstream environment“ on page 57.
ss_territory
For creating and administrating domains, repositories, and applications (for
example service gateway, Communications Server, and Task Scheduler).
ss_scm
For administering (starting, stopping, setting startup arguments, etc.) and
creating services for applications including Communications Server
applications, service gateways, and Task Schedulers.
ss_deploy
For deploying Communications Builder export files to Communications Server
applications.
ss_rcp
Remote copy tool for copying files or folders to and from remote hosts, or for
copying folders on a remote host.

Chapter 20 About the command line utilities
20.1 Getting started with the command line utilities

The command line utilities must be run from a computer with the Communications
Server installed.
To use the command line utilities on UNIX
1. Set the $STRS_LOCATION environment variable to where you installed the

Exstream software, for example:
STRS_LOCATION=/usr/Exstream/Exstream-16.3.0.GA.<Build>
export STRS_LOCATION
2. Run the utility:
./launcher solutions/sstools/start <utility> <arguments>
To use the command line utilities on Windows
1. In the command line window, browse to the following directory:
<Exstream_Installation_directory>\<version>\Server\bin
<utility>.exe <arguments>
For examples, see “Examples” on page 209.
20.2 Scenarios for the command line utilities

Scenario – Create a domain and run a Communications Server application
1. Use ss_territory to create a domain.
2. Use ss_territory to create a Communications Server application and link it to

the domain.
3. Use ss_scm to create a Communications Server service.
4. Use ss_deploy to deploy an export package.
5. Use ss_scm to start the Communications Server service.
Scenario – Redeploy a Communications Server service
1. Use ss_scm to stop the Communications Server service
2. Use ss_deploy to deploy an export package.
3. Use ss_scm to start the Communications Server service.

20.2. Scenarios for the command line utilities
Scenario – Create a Task Scheduler
1. Use ss_territory to add an application.
2. Use ss_territory to create a resource for the application.
3. Use ss_territory to assign the application resource to the application.
4. Use ss_scm to create a service for the application.
Scenario – Create a tracking repository, queue repository, Document Broker

repository, Message repository, statistics repository, or logging repository
1. Use ss_territory to create a resource for the repository.

2. Use ss_territory to create the database for the repository.
3. Use ss_territory to assign the repository resource to a domain.

Chapter 21
Arguments and descriptions
21.1 ss_scm utility arguments and descriptions

Required arguments
-servicename <name>
Where <name> is the service name.
Note: The -servicename <name> argument is not required if -action

<action> argument is -action uninstall or -action printservices.
-action <action>
Where <action> is one of the actions listed below.
-user <username>
The user name for authentication. To use this utility you must have the tenant
administrator role. If the –tenant argument is not used, then pass -user as
"<tenantname>\<username>".
-tenant <tenantname>
The tenant name for authentication. This can be passed with the -user
argument.
-pass <password>
The password for authentication.
Actions and required action dependent arguments

start
Starts a service, which can be a Communications Server application, service
gateway, or Task Scheduler.
stop
Stops a service.
isrunning
Checks whether a service is running or not.
pause
Pauses a service.
resume
Resumes a service.
newname
Renames a service.

Chapter 21 Arguments and descriptions
Requires additional argument:

-newname <name>
setstartuptype
Changes the startup type of the services.
-startuptype <startuptype>
setstartupuid
Changes the server login user name.
Note: A prompt "New password for service" is displayed where you

specify the password for -uid <username>
-uid <username>
setservicetype
Sets the service type. Requires additional argument:
-servicetype <type>
setdescription
Sets the service description.
-description <description>
create
Creates a new service instance.
Requires additional arguments:
-binpath <path>
-servicetype <servicetype>
-startuptype <startuptype>
setbinpath
Sets path to the service executable.
-binpath <path>
getbinpath
Gets path to the service executable.
delete
Deletes the service.
Note: This can corrupt the system if important services are removed.

21.1. ss_scm utility arguments and descriptions
setarg
Sets a startup argument.
Note: The argument must exist.

-argname <argname>
-argvalue <argvalue>
newarg
Creates a new startup argument for specified service.
-argname <argname>
-argvalue <argvalue>
argexist
Checks if a startup argument exists and returns the value of the argument (if it
exists).
-argname <argname>
delsinglearg
Delete a single startup argument e.g. -demo. (A single argument is an argument
without a value).
-argname <argname>
delbinaryarg
Deletes a binary argument, for example -wd /home/user/projects/
myproject/wd
-argname <argname>
getstartuptype
Gets the service startup type.
getstartupuid
Gets the service startup uid/username.
getservicetype
Gets the service type.
getdescription
Gets the service description.
printservices
Gets installed services. If -servicetype <servicetype> is specified, only
services of that type are returned.

Note: The Name column is truncated at the 20th character.
printarguments
Prints startup argument values for the service.
-argname <argname>
getarg
Gets startup argument value.
-argname <argname>
uninstall
Uninstalls all applications of the specified type. Also unregisters the applications
from the application domain.
-applicationtype <type>
-applicationversion <version> (Optional if action is uninstall)
updateappbinpath
Updates the executable path of all applications to match the path specified in the
-binpath argument.
Action dependent arguments

-newname <name>
A new name of a service.
-startuptype <type>
The startup type can be one of:
• auto
• manual
• disabled
-uid <username>
The user name to use for a service.
-servicetype <type>
The type can be one of the following:
• STRSCS – a Communications Server service

• STRSSG – a service gateway service.
• STRSCI – an Archiver application.
• STRSTS – a Task Scheduler application

21.1. ss_scm utility arguments and descriptions
A description of the service.
-binpath <path>
Path to the executable file for the application.
UNIX example:
• /var/streamserve/streamserve-<version>/applications/
streamserve/start
Windows examples:
• Archiver application – <Exstream installation dir>\<version>\Server\

bin\ss_storage.exe
• Task Scheduler application – <Exstream installation dir>\<version>
\Server\bin\TSApplication.exe
• Communications Server application – <Exstream installation dir>
\<version>\Server\bin\CommunicationServer.exe
-argname <name>
The name of the startup argument.
-argvalue <value>
The value of the startup argument.
-applicationtype <type>
The type can be one of:
• STRSCS – a Communications Server application.

• STRSSG – a service gateway application.
• STRSTS – a Task Scheduler application
-applicationversion <version>
The application version number.
-repeat <number>
Number of times to repeat the command. Default is 1. Use only where it makes
sense, for example with the action -getarg -argname <argname> argument.
Optional arguments
For more optional arguments available in all the utilities, see “Optional arguments
(all utilities)” on page 207.

21.2 ss_territory utility arguments and descriptions

Required arguments
-action <action>
-user <username>
argument.
-pass <password>

delete
Deletes a domain.
-territoryid <territoryid> or -territoryname <territoryname>
create
Creates a domain.
-territoryversion <version>
-territorydescription <description>
add_application
Adds an application to the domain.
-appname <name>
-apptype <type>
-appvers <vers>
get_application_property
Retrieves the value of a property.
Required additional argument:
-appname <application_name>
-propertyid <property_name> – For a list of the properties you can get, see -
propertyid <property_name> on page 203.

21.2. ss_territory utility arguments and descriptions
set_application_property
Sets the value of a property. For example the logical name of a Communications
Server application or the port range for the service gateway.
Required additional arguments:
-appname <application_name>
-propertyid <property_name> – For a list of the properties you can set, see -
propertyid <property_name> on page 203.
-value <property_value>
list_applications
Lists applications in a domain.
del_application
Deletes an application if it resides on the same machine as the management
gateway. You can delete an application on a remote machine if you specify the
application ID stored in the repository.
-appname <name>
rename_application
Renames an application on the same machine as the management gateway.
You must also run ss_scm -action newname <name> to synchronize the
application name with the service name.
-appname <name>
display_node_info
Displays information on the current host.
display_all_info
Displays information on all hosts that are registered in the environment.
display_all_domain_names
Displays all domains on the host.
Optional argument:
join
Moves an application between domains.
-applicationid <id>
-territoryid <id>

get_db_scripts
Generates the database scripts used to create a repository. The scripts are zipped
in a file and stored in:
• <Project location>/config/database on UNIX/Linux, where <Project
location> is the Project location specified during the Communications
Server installation.
• <Base directory>\<Version>\root\config\database on Windows,
where <Base directory> is the path specified for Exstream Projects during
the Communications Server installation. For example: C:
\ManagementGateway

-territoryid <resource ID> The ID given when creating the repository
security profile resource.
-db_type <dbrokerplus|tracker|queue|messagestore|statistics|
databaselog|tempstorage|archive>
get_job_status
Displays the job status, e.g. if a database was created with
create_appdomain_db.
When everything in a log has been retrieved by a client, this action with the
same job ID will fail.
-jobid <jobid>
-frompos <pos>
-maxlen <max_bytes>
rename_territory
Renames the domain.
-territoryname <territoryname>
deploy_domain_info
Exports the domain configuration to the specified application. You can only
specify applications on the management gateway machine.
-appname <name>
create_appdomain_db
Creates a repository.
To check that the database was created, you must run the get_job_status
action with the job ID that the create_appdomain_db action returned.
-db_user <user>
-db_pass <pass>

databaselog|tempstorage|archive> If you specify tracker, scripts for the
tracking repository are created, if you specify queue, scripts for the queueing
repository are created, etc.
-territoryid <resource ID> The ID given when creating the repository
security profile resource.
create_resource
Creates a resource in the tenant repository. For example, a tracking repository,
queue repository, Document Broker repository, statistics repository, logging
repository, or Task Scheduler resource.
-resource_version <version>
-filename <path to resource file>
-resource_name <name> – For repository nodes this is a name for the resource.
For a Task Scheduler application this is taskscheduler.config.xml.
and for an Archiver application this is archiver.config.xml
-content_type <type>
-strs_type <type>
Optional arguments:
-resource_description <description>
-territoryid <ID>
-nodeid <ID>
-content_encoding <encoding>
update_resource
Updates a property for an existing resource. You can update the following
properties:
• Territory ID
• Node ID
• Resource name
• Resource description
• Content encoding
• The resource data

-resource_id <ID>
assign_resource_to_territory_relation
Link a resource to a domain. By using this action, you can assign the same
resource to several application domains.
-id <resource_id>
-idto <domain_id>

remove_resource_to_territory_relation
Removes the link from the domain to the resource.
-id <resource_id>
-idto <domain_id>
remove_resource
Removes a resource from the repository.
-resource_id <ID>
get_resource_data
Retrieves the resource data.
-resource_id <ID>
-filename <name>
assign_resource_to_application_relation
Links a resource to an application. For example, to link a Task Scheduler
application to a resource.
-id <resource_id>
-idto <domain_id>
remove_resource_to_application_relation
Removes the link from the application to the resource.
-id <resource_id>
-idto <domain_id>
list_hotfixes
Lists hotfixes installed for the repository specified by the -db_type argument.
-db_user <user>
-db_pass <pass>
db_apply_hotfixes
Applies available hotfixes to the specified repository.
-db_user <user>
-db_pass <pass>

-territoryid <resource ID >(The ID of the repository)
set_physicallayer
Selects the physical layer.
get_physicallayer
Retrieves the physical layer.
input_connectors
Pauses or resumes the input connectors of the specified application.
-appname <application>
-data <pause|resume>
Note: If -data argument is omitted, the current status of the connectors is

only displayed.
set_config_file
Copies a file to the application working directory. This way you can update any
configuration file, e.g. a Task Scheduler configuration file, in an application
working directory.
To use this for task scheduling, a taskscheduler.config.xml file must be
created locally first.
-appname <application>
-filename <path>

-territoryid <id>
The application domain ID, or the resource ID of the repository. Optionally use
-territoryname. You can use the display_all_info action to find the ID for a
domain or repository.
-territoryname <name>
The domain name. Optionally use -territoryid.
The domain version.
-territorydescription <description>
A domain description.
-force
Required for update action only if the last modification time is out of sync.
-modtime <modtime>
The last modification time returned by the get action.
-applicationid <id>
The application id.

-filename <filename>
For the create_resource , get_resource_data, and get_resource_data
actions, this is the path to the file containing the resource data. The resource files
are found in the directory <ManagementGateway_root_directory>\<version>
\root\config\version\<type_of_resource>\<file_name>
Where <file_name> is one of the following:
• Tracking repository (SQL Server) – tracker_<version>.default.xml

• Queue repository (SQL Server) – queue_<version>.default.xml
• Message repository (SQL Server) – messagestore_<version>.default.xml
• Document Broker repository (SQL Server) –
docbrokerplus_<version>.default.xml
• Statistics repository (SQL Server) –
statisticsrepository_<version>.default.xml
• Logging repository (SQL Server) – DataBaseLog_<version>.default.xml
• Temporary data repository (SQL Server) –
tempstorage_<version>.default.xml
• Task Scheduler – taskscheduler_<version>.default.xml
• Archiver application – archiver_<version>.default.xml
Note: The repository resource files found in this directory are only suitable
for SQL Server. To create the resource file for a repository in Oracle, you
can create the repository in Control Center and link it to a domain. The
resource file is then created in the working directory of an application in
the application domain. The file is prefixed with the same name as the
repository node in Control Center.
-appname <appname>
The application name.
-appvers <version>
The application version.
-apptype <type>
The application type. The type can be one of:
• STRSCS – a Communications Server application

• STRSSG – a service gateway application.
• STRSTS – a Task scheduler application.
-jobid <jobid>
The job ID.

-db_user <user>
Database administrator user.
-db_pass <pass>
Database administrator user password.
-frompos <pos>
Position in log file from which to retrieve content of the file. To get all content
specify 0.
-maxlen <maxbytes>
Max number of bytes to retrieve from the log file. To get all content specify a
high number, for example 60000.
-resource_version <version>
A string of your choice that represents the version of the resource, for example
1.0 or Alpha 0.1.
-resource_name <name>
The name of the resource.
-content_type <type>
The general content type. This can be one of the following:
• Tracking repository – application/x-streamserve.com-tracker
• Message repository – application/x-streamserve.com-messagestore
• Queue repository – application/x-streamserve.com-queue
• Document Broker repository – application/x-streamserve.com-
documentbrokerplus
• Statistics repository – application/x-streamserve.com-
statisticsrepository
• Logging repository – application/x-streamserve.com-databaselog
• Temporary data repository – application/x-streamserve.com-
tempstorage
• Task Scheduler – application/x-streamserve.com-configuration
• Archiver application – application/x-streamserve.com-generic-app-
configuration
-strs_type <type>
A specific content type. This can be one of the following:
• Tracking repository – application/x-streamserve.com-
securityprofiles
• Queue repository – application/x-streamserve.com-securityprofiles
• Message repository – application/x-streamserve.com-
securityprofiles

• Document Broker repository – application/x-streamserve.com-

securityprofiles
• Statistics repository – application/x-streamserve.com-
securityprofiles
• Logging repository – application/x-streamserve.com-
securityprofiles
• Temporary data repository – application/x-streamserve.com-
securityprofiles
• Task Scheduler – application/x-streamserve.com-generic-app-
configuration
• Archiver application – application/x-streamserve.com-generic-app-
configuration
-resource_id <id>
The resource ID given when creating the resource.
-id <id>
The resource ID when assigning and removing resources to and from domains
and applications.
-idto <domain_id>
The application domain when assigning and removing resources to and from it.
-cmd_name <file>
A command file without extension (*.bat can be used for Windows).
-territoryname <name>
The domain name from which the management gateway gets information so it
can replace the predefined variable regarding the database related to the current
domain.
Note: You must also specify -db_type <type>.
-db_type <type>
The type of the repository:
• tenant – the tenant repository.
• dbrokerplus – the Document Broker repository.
• tracker– the tracking repository.
• messagestore– the Message repository.
• queue– the queue repository.
• statistics– the statistics repository.
• databaselog– the logging repository.
• tempstorage– the temporary data repository.

• archive – the Collector archive.
-territoryid <ID>
The ID for a repository.
-cmd_file_path
A relative path to the management gateway. This value overrides the %FILEPATH
% variable.
-propertyid <property_name>
The name of a property to get or set.
You can use the following property names:
http://schemas.streamserve.com/uid/resource/property/application/
logicalname – for the logical name of a Communications Server application.
securemode – for enabling and disabling web service security for the service
gateway web clients. When enabled, the web client will use HTTPS when calling
the service gateway. When disabled (default), the web client will use HTTP.
portrange – for the start of the port range for the service gateway.
-value <property_value>
The value for the property.
For the property http://schemas.streamserve.com/uid/resource/
property/application/securemode this can be true or false.
Optional arguments
-resource_description <description>
A description of the resource.
-nodeid <ID>
The physical server hosting the resource.
-content_encoding <encoding>
Specifies if the data is compressed, for example application/x-gzip. Leave
empty for plain data.

21.3 ss_deploy utility arguments and descriptions

To use the ss_deploy utility you must have the tenant administrator role.
Required arguments
-action <action>
-user <username>
argument.
-pass <password>
deploy
Deploys a package with a specified platform to an application. Requires
additional arguments:
-physicalplatform <platform>
-package <fileName> or -releaselabelid <casId>
-appname <name>
deploy_application_config_files
Use for service gateway applications. This action requires that a working
directory has been created for the application. The action copies all template files
the application depends on to the working directory. For example, if you want
application specific log settings, a specific logmanager.xml is required in the
application's working directory. Requires additional argument:
-appname <name>
get_release_labels
Lists all the release labels for a Communications Builder Project. A release label
is created when the Project is checked in to the CAS in Communications Builder.
-projectname <Project_Name>
Optional argument:
-verbose

21.3. ss_deploy utility arguments and descriptions

-appname <name>
The Communications Server application to deploy to.
-physicalplatform <physicalplatform>
The physical platform to deploy.
Note: A physical platform must exist in the export package.
-package <fileName>
Package file to deploy. This package file is exported from Communications
Builder. This argument is required when deploying from file, and -
releaselabelid is required when deploying from CAS.
-releaselabelid <casId>
Package to deploy from CAS. The <casId> is a reference to the release label for
the package in CAS. This argument is required when deploying from CAS, and
-package is required when deploying from file.
-wd <working directory>

The working directory, only a folder name should be specified, which is
typically the physicalplatform to use. If not specified, the physicalplatform
is used.
-projectname <Project_Name>
The name of the Communications Builder Project.
-verbose
This argument can be used with the get_release_labels action to display
detailed information about each release label, such as the description and
creator.
Optional arguments
-projectname <name>
The name of the Project, normally the export file without the extension. If this
argument is not specified, the name of the export file is used.
-projectlabel <label>
Project label to use (revision or other label).
-start
Starts the application after a successful deploy.
-keep-data
Keeps the data folder, the default is to clear it.

21.4 ss_rcp utility arguments and descriptions

Required arguments
-src <source_name>
The path to the file or folder to copy.
-dst <name>
The path to the file or folder to copy to.
-user <username>
argument.
-pass <password>

-copydir
Copies a folder recursively locally on the remote host where the management
gateway is running.
Note: On UNIX/Linux, any symbolic links and named pipes are also
copied.
-onremote
-R
Copies a folder recursively to or from a remote host.
Note: On UNIX/Linux, any symbolic links and named pipes are also
copied.
-fromremote
Copy a file from the remote host to the local host. If you do not specify -
fromremote, a file is copied from the local host to the remote host.
-onremote <remotehost/ip>
Copy locally on the remote host.

21.5. Optional arguments (all utilities)
-startrange <pos>
The position in the file where copying starts, specified in number of bytes from
start of file. Ignored for -R or -copydir.
-stoprange <pos>
The position in the file where copying stops, specified in number of bytes from
start of file. Ignored for -R or -copydir.
-unpack
Only valid if copying a file to a remote host. The file is unpacked as a .tgz file.
21.5 Optional arguments (all utilities)

-host <host>
The host name or IP address. If you do not specify this argument, localhost is
used.
-ipport <ipport>
The IP port number. If you do not specify this argument, 28700 is used.
-timeout <ms>
The time-out in milliseconds. If you do not specify this argument, 5000 ms is
used.
-v
Displays version information and exits.
-h
Displays help and exit.
-l
Use a long listing format.
-xml
Extended information in XML format.

Chapter 22
Examples and troubleshooting
The following examples are for Windows where the commands are run from
<Exstream_installation_directory>\<version>\Server\bin
For UNIX, instead of running the .exe files, you browse to $STRS_LOCATION/bin
and run for example ./start ss_territory <args>
22.1 Examples
22.1.1 Creating a domain
Command
ss_territory.exe -action create -territoryname MYAPPDOMAIN
-territoryversion <version> -territorydescription Production -user
USERID -tenant TENANTNAME -pass PASSWD
22.1.2 Creating a repository

These steps in this example can be used to create a tracking repository, Message
repository, Document Broker repository, queue repository, statistics repository, or
logging repository.
Prerequisites
• A domain must be created.
To create a tracking repository
1. Create a node for the tracking repository:

ss_territory.exe -action create_resource -resource_name
"TrackingRepository" -filename "C:\ManagementGateway\<version>
\root\config\<version>\tracker\tracker_<version>.default.xml"
-resource_version "16.3.0" -content_type "application/x-
streamserve.com-tracker" -strs_type "application/x-streamserve.
com-securityprofiles" -host "localhost" -ipport "28700" -user
"Administrator" -tenant TENANTNAME -pass "pass" -timeout 60000
The resource ID of the repository is displayed. This is used for the -
territoryid in the next step.
Tip: To create a node for another type of repository (for example queue or
Document Broker) change the -content_type and -filename arguments.
2. Create the database for the tracking repository:

Chapter 22 Examples and troubleshooting
ss_territory.exe -action create_appdomain_db -territoryid

"D355C5CA-D5B5-564C-B879-4A56DCDDED2C" -db_user "sa" -db_pass
"pass" -db_type "tracker" -host "localhost" -ipport "28700" -user
"Administrator" -tenant TENANTNAME -pass "pass" -timeout "600000"
Tip: To create another type of repository (for example, queue or Document

Broker) change the -db_type argument.
3. Find the IDs required to link the resource and the domain:
ss_territory.exe -action display_all_info -host "localhost"
-ipport "28700" -user "Administrator" -tenant TENANTNAME -pass
"pass" -timeout "600000"
4. Link the node to the domain:

ss_territory.exe -action assign_resource_to_territory_relation -id
"D355C5CA-D5B5-564C-B879-4A56DCDDED2C" -idto "AB962AD0-E7F5-DE4F-
A171-A33E3A5F7B76" -host "localhost" -ipport "28700" -user
"Administrator" -tenant TENANTNAME -pass "pass" -timeout 60000
22.1.3 Creating a Communications Server application

Prerequisites
• A domain must be created.
Command
ss_territory.exe -user USERID -tenant TENANTNAME -pass PASSWD
-action add_application -territoryname MYAPPDOMAIN -appname
MYAPPLICATION -appvers <version> -apptype STRSCS
Note: Make a note of the application ID that is returned, you need it to

create the service.
22.1.4 Creating a service for a Communications Server

application
Four commands are required as below, the first is to create the service and the other
three to add arguments to the service, which make it possible to start from command
line.
Note: When you specify the service name, make sure it is the same name as the
application you created with the ss_territory command.
Prerequisites
• A Communications Server application must be created.
Commands
ss_scm.exe -user USERID -tenant TENANTNAME -pass PASSWD -action
create -servicename MYSTRSSERVICE -startuptype manual -binpath "C:

22.1. Examples
\Program Files\OpenText\Exstream\<version>\Server\bin
\CommunicationServer.exe" -servicetype STRSCS -description "My
Communications Server Service"
ss_scm.exe -action newarg -argname "-kernel" -argvalue file://
kernel_5_6_1.xml -servicename <servicename>
ss_scm.exe -action newarg -argname "-env" -argvalue "file://<path to
the .environment file used by the Communications Server>"
-servicename <servicename>
ss_scm.exe -action newarg -argname "-applicationid" -argvalue
"<applicationid>" -servicename <servicename>
22.1.5 Deploying a release package to a Communications

Server
Prerequisites
• A service for a Communications Server application must be created.
• A release package for the Project must exist in the CAS.
To find the release package IDs for a Project

ss_deploy.exe -action get_release_labels -projectname
InteractiveStatement -user USERID -pass PASSWRD -tenant TENANTNAME
To deploy a release package to the Communications Server

ss_deploy.exe -action deploy -appname MYSTRSSERVICE
-physicalplatform MYPHYSICALPLATFORM -releaselabelid
7F3B89A2-32C7-D942-B9F7-3F5CD591FD91 -user USERID -tenant
TENANTNAME -pass PASSWD
22.1.6 Modifying a Communications Server service

Prerequisites
• A Communications Server service with a deployed export package must exist.
Command
ss_scm.exe -user USERID -tenant TENANTNAME -pass PASSWD
-servicename MYSTRSSERVICE -action newarg -argname "-wd" -argvalue
"C:\Management Gateway\<version>\root\Applications\myapp"

22.1.7 Starting a Communications Server service

Prerequisites
Command
-servicename MYSTRSSERVICE -action start
22.1.8 Starting a Communications Server service and disable

its input connectors
Prerequisites
Command
-servicename MYSTRSSERVICE -action newarg -argname "-
disableinconnectors" -action start
22.1.9 Disabling input connectors of a running

Communications Server service
Prerequisites
• A Communications Server service with a deployed export package must exist

and be started.
Command
ss_territory.exe -action input_connectors -appname "my_app" -data
"pause" -user "Administrator" -tenant TENANTNAME -pass "strs"
22.1.10 Enabling input connectors of a running

Communications Server service with paused input
connectors
Prerequisites
• A Communications Server service with a deployed export package must exist

and be started.
Command
ss_territory.exe -action input_connectors -appname "my_app" -data
"pause" -user "Administrator" -tenant TENANTNAME -pass "strs"

22.2. Troubleshooting
22.1.11 Checking if a Communications Server service is

running
Prerequisites
Command
-servicename MYSTRSSERVICE -action isrunning
22.1.12 Stopping a Communications Server service

Prerequisites
Command
-servicename MYSTRSSERVICE -action stop
22.2 Troubleshooting
The utilities do not start
Solution
Check that there is an environment variable called STRS_LOCATION (in
uppercase letters) that points to the Communications Server installation
directory. In many UNIX dialects you must export the variable after you have
defined it.
Prompt displayed for realm user name

(or for example Error: System specific error code:146)
This is probably because the management gateway connection is not working.
Solution
Check that:
• You have specified the correct user name and password.
• The management gateway is started.
• The -ipport argument specifies the correct port for your management gateway.
HTTP listener error displayed

Error: HTTPListener(scm): The file or a script interpreter is not a
regular file, execute permission is denied for the file or ascript or ELF

interpreter, the file system is mounted noexec or search permission is

denied on a component of the path prefix of filename or the name of a script
interpreter.
Solution
Make sure you specify the correct -binpath value when creating the service, i.e.
the path to the start binary.
Note: The file must be included in the path, not just the path to the
directory where the file is stored.

Part 5
Administering web applications
Chapter 23
About the web applications
The web applications are intended for many different scenarios, such as campaign
management and correspondence management scenarios. Each of the web
applications, as well as the web application views, are available as standalone
applications or can be hosted in an existing business application or part of a
workflow. The web applications and the views are loaded via URL invocations.
A user is assigned one or more roles. The roles control which views, features, and
items (resources, views, etc.) are available to the user in the web applications. For
detailed information about the roles, see “Assigning access roles” on page 31.
Communication
The web applications access the Exstream repositories (common asset service,
message repository, tracking repository, etc.) using either the REpresentational State
Transfer Services API (REST API) or the Web Service API (WS API). The REST
services and the web services are hosted by a service gateway. The service gateway
is linked to the repositories via the domain.
asking for a service gateway endpoint. The request includes information about the
tenant and the domain to be used. The management gateway checks the tenant
repository for service gateways that fulfills the request, and returns the connection
information for the service gateway to be used. The web client then uses the
provided information to connect to the service gateway.
Figure 23-1: Web application communication

Chapter 24
Deploying the web applications
If you did not deploy the Web application ARchive (WAR) files when you installed
Exstream, you must deploy the WAR files to a supported Java application server, for
example to Apache Tomcat.
Prerequisites and recommendations

• You have access to the folder where the WAR files were installed.
• The connection details for the management gateway must be available.
• The service gateway to be used for communication must be set up.
Copying WAR files to the Java application server

To deploy the WAR files, you copy the WAR files from the installation folder to the
Java application server.
To copy a WAR file to the Java application server
• Copy the WAR file from the installation folder to the portal root on the Java
application server. For example <TOMCAT_HOME>\webapps for Apache Tomcat.
Note: Make sure that the WAR file is deployed as an exploded WAR,
resulting in a separate folder for the web application in the portal root.
Connection properties for web applications

You must create a configuration file for web application connection properties and
specify the path (Java Options) to this file. See “Connection properties” on page 226.

Chapter 25
Editing web application properties
25.1 Service gateway properties

You must specify properties such as allowed origins, secure mode properties, etc. for
each service gateway application you have. These properties are specified in the file
application.properties located in the working directory of the service gateway
application:
<base>\<version>\root\applications\<SGWname>\wd
where <base> is specified during the installation (default is C:

\ManagementGateway) and <SGWname> is the name of the service gateway
application.
The template for application.properties is located in the following directory

relative to the Exstream installation directory:
solutions\management\config\<version>\STRSSG
This template is copied to the working directory when you create a new service
gateway application. If you edit this file, the changes will be applied to all new
service gateway applications you create, but existing service gateway applications
are not affected by the changes.
Allowed origins for service gateway

You must edit the sgw.allowedOrigins property in the applications.
properties file. This property specifies the origins (protocol, host and port)
allowed to interact with service gateway. You must add the origins (comma
separated) for the web applications and OTDS as values to this property:
sgw.allowedOrigins=<protocol>://
<webAppHost>:<port>,...,<protocol>://
<webAppHost>:<port>,<protocol>://<otdsHost>:<port>
Example 25-1: Allowed origins
sgw.allowedOrigins=http://10.168.166.56:8080,https://
10.169.156.66:8443,https://10.175.112.56:8443
Secure mode properties

If secure mode is enabled for a service gateway, you must add secure mode
properties to the applications.properties file.

Chapter 25 Editing web application properties
Example 25-2: Secure mode properties when using a self-signed

certificate
server.ssl.key-store: keystore.p12
server.ssl.key-store-password: myPassword
server.ssl.keyStoreType: PKCS12
server.ssl.keyAlias: tomcat
Note that you must use colon to separate the property and value, and the values
should not be within quotes. For more information about secure mode
properties, see “Service gateway secure mode”.
Running web applications in iframes
A web application in hosted mode can be run in an iframe in a hosting
application. To allow the web application to run in the hosting application you
must do the following:
• In the OTDS web client, on the System Attributes page, add the X-Frame-
Options Header system attribute for the OTDS tenant that will access the
web application.
• In the applications.properties file, make sure you have the property
xFrame.options.setHeader=true.
• In the applications.properties file, add the origin (<protocol>://
<host>:<port>) of the web application as value to the xFrame.
options.allowFrom property:
xFrame.options.allowFrom=<protocol>://<host>:<port>
If you have several web applications (different origins) running in hosting

applications, you must add all origins as values (space separated) to xFrame.
options.allowFrom. For example:
xFrame.options.allowFrom=http://10.168.166.56:8080 http://
10.148.146.45:8080
Thumbnails for images in StoryBoard and ReTouch

The property sgw.enableThumbnailGeneration=true|false specifies whether
to enable thumbnails for image resources in StoryBoard and ReTouch. This
property is set to true by default, but you can change it to false to disable
thumbnails.
Debug level in service gateway log
To verify a successful service gateway configuration, and to allow for easier
troubleshooting, you can enable debugging level for the service gateway log (see
“Service gateway REST log” on page 275). Change the logging properties in the
applications.properties file as follows:
logging.level.=DEBUG
logging.level.com.streamserve=DEBUG
logging.file=servicegateway_rest.log

25.1. Service gateway properties
The log file servicegateway_rest.log is located in the working directory of

the service gateway. If the service gateway can successfully read the keystore
and initialize the https port, log entries similar to the following will be shown in
servicegateway_rest.log:
DEBUG 2556 --- [Thread-24] o.a.t.util.net.jsse.JSSESocketFactory:

The SSL protocol [SSLv2Hello] which is enabled by default in
this JRE was excluded

Truststore = null

TrustPass = null

trustType = PKCS12

trustProvider = null
INFO 2556 --- [Thread-24]

s.b.c.e.t.TomcatEmbeddedServletContainer:
Tomcat started on port(s): 2719 (https)
25.1.1 Service gateway secure mode

In Control Center you can enable secure mode for a service gateway. If secure mode
is enabled, HTTPS is activated for communication via the REST API, and the web
clients will use HTTPS when calling the service gateway. If secure mode is disabled
(default), the web clients will use HTTP.
The service gateway includes an integrated Java application server from Apache
Tomcat, used internally for business logic. To configure secure mode properties for
the service gateway you edit the file application.properties in the working
directory of the service gateway.
To enable secure mode for a service gateway
1. In Control Center, select the service gateway.
2. In the Properties view, double-click Service gateway secure mode, click

Enabled, and then click OK.
3. Open application.properties in a text editor.
4. Add the properties needed to enable a secure channel. For detailed information,
see the Apache Tomcat user documentation.
5. Save and close the file.
6. Restart the service gateway for the changes to take effect.

Example 25-3: Configuring secure mode properties
The following example illustrates how to configure secure mode properties

for a service gateway when using a self-signed certificate.
1. Open a command prompt and navigate to the working directory of the

service gateway.
2. Enter the following command:
keytool -genkey -alias tomcat -storetype PKCS12 -keyalg RSA
-keysize 2048 -keystore keystore.p12 -validity 3650
3. Define a password and accept default values for all other questions.
4. Verify that the file keystore.p12 is created in the working directory of
the service gateway.
5. Add the following entries to application.properties (use the
password defined in step 3 above):
6. Save application.properties and restart the service gateway.
25.2 Management gateway properties

If you intend to use the web application Control, you must specify properties such
as allowed origins, secure mode properties, etc. for each management gateway
application you have. These properties are specified in the file application.
properties located in the working directory of the management gateway
application:
<base>\<version>\root
where <base> is specified during the installation (default is C:

\ManagementGateway).
Allowed origins for management gateway

You must edit the sgw.allowedOrigins property in the applications.
properties file. This property specifies the origins (protocol, host and port)
allowed to interact with the management gateway. You must add the origins
(comma separated) for the web applications and OTDS as values to this
property:
sgw.allowedOrigins=<protocol>://
<webAppHost>:<port>,...,<protocol>://
<webAppHost>:<port>,<protocol>://<otdsHost>:<port>

25.2. Management gateway properties
Example 25-4: Allowed origins
sgw.allowedOrigins=http://10.168.166.56:8080,https://
10.169.156.66:8443,https://10.175.112.56:8443
Secure mode properties

If secure mode is enabled for the management gateway, you must add secure
mode properties to the applications.properties file.
Example 25-5: Secure mode properties when using a self-signed

certificate
Note that you must use colon to separate the property and value, and the values
should not be within quotes.
Running Control in iframes

A web application in hosted mode can be run in an iframe in a hosting
application. To allow Control to run in the hosting application you must do the
following:
• In the OTDS web client, on the System Attributes page, add the X-Frame-
Options Header system attribute for the OTDS tenant that will access
Control.
• In the applications.properties file, make sure you have the property
xFrame.options.setHeader=true.
• In the applications.properties file, add the origin (<protocol>://
<host>:<port>) of Control as value to the xFrame.options.allowFrom
property:
xFrame.options.allowFrom=<protocol>://<host>:<port>
If you have several web applications (different origins) running in hosting

applications, you must add all origins as values (space separated) to xFrame.
options.allowFrom. For example:
xFrame.options.allowFrom=http://10.168.166.56:8080 http://
10.148.146.45:8080
Debug level in management gateway log

To verify a successful management gateway configuration, and to allow for
easier troubleshooting, you can enable debugging level for the management
gateway log (see “Management gateway REST log” on page 276). Change the
logging properties in the applications.properties file as follows:

logging.level.=DEBUG
logging.level.com.streamserve=DEBUG
logging.file=mgw_rest.log
The log file mgw_rest.log is located in the working directory of the

management gateway. If the management gateway can successfully read the
keystore and initialize the https port, log entries similar to the following will be
shown in mgw_rest.log:

The SSL protocol [SSLv2Hello] which is enabled by default in
this JRE was excluded

Truststore = null

TrustPass = null

trustType = PKCS12

trustProvider = null
INFO 2556 --- [Thread-24]

s.b.c.e.t.TomcatEmbeddedServletContainer:
Tomcat started on port(s): 2719 (https)
25.3 Connection properties

You must create a configuration file for web application connection properties and
specify the path (Java Options) to this file.
Note: You must restart your Java application server each time you update the
configuration file.
Example 25-6: Configuration file
<?xml version="1.0"?>
<cc-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"
xsi:noNamespaceSchemaLocation="../xsd/cc-webapp-config.xsd">

<mgw-urls>
<mgw-url>https://10.168.166.56:28700/management/rest/v1/
servicegateways</mgw-url>
<mgw-url>https://10.168.166.56:29600/management/rest/v1/
servicegateways</mgw-url>
</mgw-urls>

<storyboard-url>http://10.168.166.56:8080/storyboard</
storyboard-url>

25.3. Connection properties
<retouch-url>http://10.168.166.56:8080/retouch</retouch-url>
<workshop-url>http://10.168.166.56:8080/workshop</workshop-
url>
<supervisor-url>http://10.168.166.56:8080/supervisor</
supervisor-url>
<ruleeditor-url>http://10.168.166.56:8080/ruleeditor</
ruleeditor-url>
<writer-url>http://10.168.166.56:8080/writer</writer-url>
<bca-url>http://10.168.166.56:8080/contentauthor</bca-url>

<analytics-url>http://10.168.166.56:8080/iportal/apps/
OTCCE16/Dashboards/OTCCE16.dashboard</analytics-url>

<url-mappings>
<url-mapping>
<url-pattern>t1</url-pattern>
<tenant>tenant1</tenant>
<domain>Dev</domain>
</url-mapping>
</url-mappings>

<deployment-type>dev</deployment-type>
</cc-web-app>
The entries in the configuration file are described below:

• Management gateway URL(s) - The URL to the management gateway that
provides the service gateway connection information. You can specify several
management gateways if necessary.
• Application URLs - URLs to the web applications (StoryBoard, ReTouch,
WorkShop, Supervisor, Rule Editor, Writer and Content Author).
• Analytics URL - See Communications Analysis iHub Dashboard below.
• Friendly URLs
Enables the use of friendly URLs (<baseUrl>/frdurl/<pattern>) to access
WorkShop and Supervisor.
• <url-pattern> - Pattern to include in the friendly URL.
• <tenant> - Tenant name or ID.
• <domain> - Domain name or ID.
• Deployment type - Can be either dev or prod. Use dev if the management
gateway has a self signed certificate. If not, use prod.
Tip: You can use the cc-webapp-config.xml template when you create the
configuration file. After updating the file you can use the schema cc-webapp-
config.xsd to validate the configuration file. These files are available in the
following directory:

• Windows path
<Installation directory>\<version>\Server\solutions\management
\web
• UNIX path
<Installation directory>/<version>/Server/solutions/
management/web
Communications Analysis iHub Dashboard

If you specify the URL to the Communications Analysis iHub Dashboard
(<analytics-url>) a new link Analytics will be added to the application
switcher in the web applications. The Communications Analysis Dashboard
provides an overview about produced communications, number of failed output
jobs, CAS text or image resource usage in themes and average job performance.
Users can also access detailed reports to track individual communications or
resources used in a particular document instance delivered to a particular end
recipient. This solution depends on the Data Collector product and OpenText
Big Data Analytics and iHub technology. See the Data Collector documentation
for more details.
Path to configuration file

You must add the configuration file path to the Java Options of your Java
application server. For example:
-Dcom.opentext.strs.config.path=C:/config/cc-webapp-config.xml
Note: The path must not include space.
Additional configurations for virtual hosts

If you configure a virtual host name for the management gateway in the
mgmgateway.xml file, you must also do the following:
• For the service gateway, configure the virtual host name in the sgw.
allowedOrigins property in the application.properties file (see “Service
gateway properties” on page 221).
• If you run Tomcat, the service gateway, and management gateway on the
same host, you must also use the virtual host name in the cc-webapp-
config.xml file.
For more information about configuring a virtual host for the management
gateway, see “Configuring the management gateway for a virtual host”
on page 75.

25.4. Properties for StoryBoard, ReTouch, Writer and CAS browser
25.4 Properties for StoryBoard, ReTouch, Writer and

CAS browser
StoryBoard, ReTouch, Writer and CAS browser have a set of configuration files:
• configuration.json - Contains configuration keys for StoryBoard, ReTouch,

Writer and CAS browser running in desktop browsers (see “configuration.json”
on page 230).
• configuration_ipad.json - Contains configuration keys for StoryBoard and
ReTouch running on iPad devices (see “configuration_ipad.json” on page 233).
• devicesConfiguration.json - Contains configuration keys for the Device preview
in StoryBoard and ReTouch (see “devicesConfiguration.json” on page 237).
• properties.json - Contains configuration keys for the Properties panel in
StoryBoard and ReTouch (see “properties.json” on page 238).
• simulationSettings.json - Contains configuration keys for simulation parameters
in StoryBoard (see “simulationSettings.json” on page 252).
The default configuration files are located in the following directories:
<portalRoot>\<webAppName>\config
To enable versioning and persistence of these configuration files, they are

automatically uploaded to CAS and read by the web applications from there. See
“Managing configuration file resources” on page 229.
25.4.1 Managing configuration file resources

All configuration files in the config folders are uploaded as resources to CAS the
first time the web applications are started. These resources are available in the
Resources view in WorkShop, and have the following names by default:
• _<appName>Configuration.json - configuration.json for <appname>

(StoryBoard, ReTouch, Writer and CASBrowser).
• _<appName>Configuration_ipad.json - configuration_ipad.json for
<appname> (StoryBoard and ReTouch).
• _<appName>Properties.json - properties.json for <appname> (StoryBoard and
ReTouch).
• _DevicesConfiguration.json - devicesConfiguration.json. The same resource
is shared by StoryBoard and ReTouch.
Note: A user that starts an application before the resources are uploaded to
CAS, or after a resource is deleted from CAS, must be a member of the
tenantuser or tenantadmin group. If not, the resources are not uploaded and
the application will not start.

Versioning
The configuration file resources are versioned, and the web applications will
always use the latest versions of the resources. A WorkShop administrator can
promote older versions, and let the web applications use the promoted versions.
Persistence
Since the web applications first try to read the configuration file resources in
CAS, and not in the config folder, the configuration settings are persisted when
deploying new versions of the web applications.
Editing
A WorkShop administrator can download a configuration file resource, edit the
content in an external editor (for example Visual Studio Code), and then update
the resource with the new content in the edited file.
Deleting
If a WorkShop administrator deletes a configuration file resource, all versions of
the resource are deleted. The first time the web application is started it tries to
read the configuration settings from the deleted resource. When no resource is
found, the configuration file in the config folder is automatically uploaded to
CAS and then read by the web application.
Multi-domains
When using multi-domains the configuration resources must be associated to all
domains. A configuration resource is created on first access of the web
application in the first domain (for example Dev). To make the configuration
resources available in the next domain (for example Test), the configuration
resources must first be reviewed and approved in Dev, and then associated to
Test.
Note: The web applications always use the latest version regardless of the
approval state.
25.4.2 configuration.json
This file contains configuration keys for StoryBoard and ReTouch running in
desktop browsers.
Example 25-7: configuration.json for StoryBoard

{
"caching": {
"doNotReloadResourceLatestVersionIdForSeconds": 1,
"doNotReloadViewsForSeconds": 10
},
"DevicePreview": {
"Enabled": true
},
"Design": {
"Display": {
"Version": true,
"AllDropAreas": true

}
},
"ObjectTree": {
"Enabled": true,
"Display": {
"Version": true,
}
},
"Sidebar": {
"Edit": {
"Default": "resources"
}
},
"Mode": {
"SelectionOnly": false
},
"Resources": {
"Text": {
"AutoEdit": true,
"DefaultContent" : "<p></p>",
"Embed" : true
},
"STL": {
"AutoEdit": true,
"DefaultContent" : ""<stl:stl><stl:document></
stl:document></stl:stl>",
"Embed" : false
},
"Image": {
"Embed" : true
}
}
}
Cache keys
"caching": {
"doNotReloadResourceLatestVersionIdForSeconds": <num>,
"doNotReloadViewsForSeconds": <num>
}
• doNotReloadResourceLatestVersionIdForSeconds - Sets the number of seconds

to wait before reloading the latest version of a resource. Affects the check if a
resource is the latest version, and is done to ensure that only the latest version of
a text resource can be edited. Use 0 or negative number to deactivate the cache.
• doNotReloadViewsForSeconds - Sets the number of seconds to wait before
reloading views. Affects the reloading of both the list of available views and the
contents of the current view. Use 0 or negative number to deactivate the cache.

Key for device preview in StoryBoard and ReTouch
"DevicePreview": {"Enabled": true|false}
• Enabled - Determines whether to display the device preview.
Keys for the design view in StoryBoard and ReTouch
"Design": {
"Display": {
"Version": true|false,
"AllDropAreas": true|false
}
}
• Version - Determines whether to display the version of the resources.

• AllDropAreas - Determines the default mode for displaying areas in the design
where a resource can be dropped. When using true all drop areas are displayed
and when using false, the user must first position the pointer over a resource or
empty section to have the drop areas displayed. The user can use a menu to
override this default setting.
Keys for the object tree view in StoryBoard
"ObjectTree": {
"Enabled": true|false,
"Display": {
}
}
• Enabled - Determines whether to display the object tree. Note that the object tree
in the Tools side bar is not affected.
• AllDropAreas - Determines the default mode for displaying areas in the object
tree where a resource can be dropped. When using true all drop areas are
displayed and when using false, the user must first position the pointer over a
resource or empty section to have the drop areas displayed. The user can use a
menu to override this default setting.
Key for default tab in StoryBoard and ReTouch Tools sidebar
"Sidebar": {
"Edit": {
"Default": "resources"|"preview"|"objectTree"
}
}
• Default - Determines which tab (Resources, Preview or Object Tree) to display as

default in the Tools sidebar in StoryBoard and ReTouch .

Key for mode selection in StoryBoard and ReTouch

"Mode": {"SelectionOnly": true|false}
• SelectionOnly - Determines when to activate insertion of resources. When using

true insertion is activated only for dragging and dropping resources. When
using false insertion is activated as soon as the user selects a resource. The user
can use a menu to override this setting.
Keys for resources in StoryBoard

"Resources": {
"Text": {
"AutoEdit": true|false,
"DefaultContent" : "<defaultContent>",
"Embed" : true|false
},
"STL": {
},
"Image": {
}
}
• AutoEdit - Determines whether to automatically start editing when creating a

new text/STL resource in StoryBoard.
• DefaultContent - Determines the default content of new text/STL resources in
StoryBoard.
• Embed - Determines whether to embed resources created in StoryBoard (for
example new text resources and images uploaded inside text resources). An
embedded resource is only available in the context of the theme where it is
created.
25.4.3 configuration_ipad.json
This file contains configuration keys for StoryBoard and ReTouch running on iPad
devices.
Example 25-8: configuration_ipad.json for StoryBoard

{
"caching": {
"doNotReloadResourceLatestVersionIdForSeconds": 1,
"doNotReloadViewsForSeconds": 10
},
"useTouchMode": true,
"DevicePreview": {
"Enabled": true
},

"Design": {
"Display": {
"Version": true,
}
},
"ObjectTree": {
"Enabled": true,
"Display": {
"Version": true,
}
},
"Sidebar": {
"Edit": {
"Default": "resources|preview|objectTree"
}
},
"Mode": {
"SelectionOnly": false
},
"Resources": {
"Text": {
"AutoEdit": true,
"DefaultContent" : "<p></p>",
"Embed" : true
},
"STL": {
"AutoEdit": true,
"DefaultContent" : ""<stl:stl><stl:document></
stl:document></stl:stl>",
"Embed" : false
},
"Image": {
"Embed" : true
}
}
}
Cache keys
"caching": {
"doNotReloadResourceLatestVersionIdForSeconds": <num>,
"doNotReloadViewsForSeconds": <num>
}
• doNotReloadResourceLatestVersionIdForSeconds - Sets the number of seconds

to wait before reloading the latest version of a resource. Affects the check if a
resource is the latest version, and is done to ensure that only the latest version of
a text resource can be edited. Use 0 or negative number to deactivate the cache.

• doNotReloadViewsForSeconds - Sets the number of seconds to wait before

reloading views. Affects the reloading of both the list of available views and the
contents of the current view. Use 0 or negative number to deactivate the cache.
Key for touch device styling in StoryBoard and ReTouch
"useTouchMode": true|false
• useTouchMode - Determines whether to apply a more “iPad friendly” styling in

StoryBoard and ReTouch. This key is, for example, applied to the print preview
zoom and navigation toolbar to increase the size of the toolbar and toolbar
buttons.
Key for device preview in StoryBoard and ReTouch
"DevicePreview": {"Enabled": true|false}
• Enabled - Determines whether to display the device preview.
Keys for the design view in StoryBoard and ReTouch
"Design": {
"Display": {
}
}

• AllDropAreas - Determines the default mode for displaying areas in the design
where a resource can be dropped. When using true all drop areas are displayed.
Note that false will not work on iPad devices since the user cannot use a pointer
to have the drop areas displayed.
Keys for the object tree view in StoryBoard
"ObjectTree": {
"Enabled": true|false,
"Display": {
}
}
• Enabled - Determines whether to display the object tree. Note that the object tree
in the Tools side bar is not affected.
• AllDropAreas - Determines the default mode for displaying areas in the object
tree where a resource can be dropped. When using true all drop areas are
displayed. Note that false will not work on iPad devices since the user cannot
use a pointer to have the drop areas displayed.

Key for default tab in StoryBoard and ReTouch Tools sidebar

"Sidebar": {
"Edit": {
"Default": "resources"|"preview"|"objectTree"
}
}
• Default - Determines which tab (Resources, Preview or Object Tree) to display as

default in the Tools sidebar in StoryBoard and ReTouch .
Key for mode selection in StoryBoard and ReTouch

"Mode": {"SelectionOnly": true|false}
• SelectionOnly - Determines when to activate insertion of resources. When using

true insertion is activated only for dragging and dropping resources. When
using false insertion is activated as soon as the user selects a resource. The user
can use a menu to override this setting.
Keys for resources in StoryBoard

"Resources": {
"Text": {
},
"STL": {
},
"Image": {
}
}
• AutoEdit - Determines whether to automatically start editing when creating a

new text/STL resource in StoryBoard.
• DefaultContent - Determines the default content of new text/STL resources in
StoryBoard.
• Embed - Determines whether to embed resources created in StoryBoard (for
example new text resources and images uploaded inside text resources). An
embedded resource is only available in the context of the theme where it is
created.

25.4.4 devicesConfiguration.json
This configuration file contains configuration keys for the Device preview in
StoryBoard and ReTouch.
There are two groups of devices, Phone and Tablet, and each group contains all the
phone/tablet devices to be available for preview. You can remove devices from, or
add new devices to, this file.
Example 25-9: devicesConfiguration.json
{
"defaultUrl": "",
"defaultDevice": "3",
"groups": [
{
"id": "1",
"name": "Phone",
"devices": [
{
"id": 2,
"name": "Apple iPhone 5S / SE",
"width": 640,
"height": 1136,
"ratio": 2,
"image": "images/phone.png",
"frameSizeTop": 15,
"frameSizeLeft": 15,
"frameColor": "#ffffff",
"frameBorderColor": "#cccccc",
"frameBorderSize": 3,
"orientation": 2,
"displaySize": 4
},
...
{
"id": "27",
"name": "Tablet",
"devices": [
{
"id": "28",
"name": "Apple iPad mini 4",
"width": 2048,
"height": 1536,
"ratio": 2,
"image": "images/tablet.png",
"frameSizeTop": 10,
"frameSizeLeft": 70,
"frameColor": "#ffffff",
"frameBorderColor": "#cccccc",
"frameBorderSize": 3,
"orientation": 1,
"displaySize": 7.9

},
...
Comments
• All id properties must be unique, but the devices do not need to be ordered
based on the id.
• The ratio property refers to the CSS pixel ratio. This property depends on the
device and defines how physical pixels are reported to applications. For example,
retina displays usually have a ratio = 2, meaning that the CSS only has half of
the physical resolution available.
• The width and height properties refer to the physical resolution of the device.
• The image property is currently unused.
• The orientation property (optional) specifies the default rotation for a device. 1
= Landscape and 2 = Portrait.
• The frameSizeTop property (optional) specifies the size in pixels of the frame at
the top and bottom of the device.
• The frameSizeLeft property (optional) specifies the size in pixels of the frame at
the left and right of the device.
• The displaySize property (optional) specifies the size of the display as a
number. This is shown in the description of the device, and is also used to
calculate the PPI value. This value can be used to verify that the data is correct
(you will usually find the physical resolution, the display size, and the PPI value
on a vendors page).
Tip: If you have a physical device, and want to get values like ratio, you can
use services like mydevice.io (http://mydevice.io/) to get the necessary
information for your physical device.
25.4.5 properties.json
This file contains configuration keys for the Properties panel in StoryBoard and
ReTouch. Since there are separate files for StoryBoard and ReTouch you can define
one property set for StoryBoard, and another set for ReTouch.
The default properties are prepared for StoryTeller, but can be applied to Template
Engine if implemented in the Template Engine template. You can also implement
custom properties in StoryTeller and Template Engine templates, and to make these
properties available in the Properties panel you must configure them in
properties.json.
The file is divided into the following sections:

• The types section contains the types used in property and attribute definitions.
See “Types” on page 239.

• The validators section contains all validators that can be applied to types. See
“Validators” on page 241.
• The properties section contains all editable properties to be available. See
“Properties” on page 244.
• The attributes section contains all attributes to be available. See “Attributes”
on page 246.
• The categories section contains all categories (list dividers) to be available. See
“Categories” on page 248.
• The objects section ties categories, properties and attributes together for the
different types of objects (Theme, Section, etc.). See “Objects” on page 250.
25.4.5.1 Types
The types section contains the types used in property and attribute definitions.
Types can be specified as follows:
"<typeName>": {
"systype": "<sysType>",
"units": [{"value": "<value>","localizationkey"|"displayName":
"<localizationKey>"|"<displayName>"},...],
"enum": [{"value": "<value>","localizationkey"|"displayName":
"<localizationKey>"|"<displayName>"},...],
"validator": "<validator>"
}
Configuration keys
• <typeName> - The name of the type.
• systype - The system type of the type.
• units - Optional units list. Used for unit types.
• enum - Optional enum list.
• value - Value for options in the units and enum lists.
• localizationkey - Localized label for options in the units and enum lists (see
Labels on page 241).
• displayName - Custom label for options in the units and enum lists (see Labels
on page 241).
• validator - Optional validator for the type.
Example 25-10: Types
"types": {
"string": {
"systype": "string"
},
"datetime": {
"systype": "datetime"

},
"integer": {
"systype": "integer",
"validator": "positiveInteger"
},
"boolean": {
"systype": "boolean",
"enum": [{"value": "1","localizationkey": "LABEL.TRUE"},
{"value": "0","displayName": "False"}
]
},
"unit": {
"systype": "numericwithunit",
"units": [{"value": "pt","displayName": "Points"},
{"value": "px","localizationkey": "UNIT.LABEL.PX"}
],
"validator": "positiveFloat"
},
...
Defining new types

You cannot add new arbitrary types, but you can define new types based on
existing system types (systype). For example, the types alignment, placement,
and start_position are all based on the enum system type.
Example 25-11: Defining a new unit type

This example shows the definition of the new type myunit. This type is
based on the existing unit type, which in turn is based on the float
system type. The new type has two units available (pt and px), and these
units are defined as keys in the units list.
The type myunit generates two properties in the theme: one that
contains the numeric value (float) and another that contains the key.
This type also uses a validator to validate the numeric values.
First you define the new type in the types section:
"myunit": {
"systype": "float",
"units": [
{
"value": "pt",
"localizationkey": "UNIT.LABEL.PT"
},
{
"value": "px",
"localizationkey": "UNIT.LABEL.PX"
}
],
"validator": "positiveFloat"
}

Then you update the appropriate properties (only spacebefore in this

example) to use the new type:
"spacebefore": {
"type": "myunit",
"localizationkey": "PROPERTY.LABEL.SPACE_BEFORE"
},
Labels
You must use either localizationkey or displayName to set the labels for the
options in the units and enum lists.
• localizationkey is a key, for example UNIT.LABEL.PT, that references a
predefined localized label. Localized labels cannot be edited, and you cannot
create new localization keys.
• displayName is used for custom labels (no localization is applied).
Notes
• You can use localizationkey also for custom labels.
• displayName overrides localizationkey.
Type unit
Properties of the type unit will generate two properties in the theme. For
example the property width has this type and will generate the properties width
for the numeric value and width.unit for the unit (pt, px, etc.).
25.4.5.2 Validators
The validators section contains the validators assigned to type definitions in order
to validate property and attribute values entered by StoryBoard and ReTouch users.
Validators can be specified as follows:
"<validatorName>": {
"regex": "<regularExpression>",
"min": <num>,
"max": <num>,
"errorMessageKey": "<localizationKey>"
"errorMessage": "<errorMessage>"
}
Configuration keys
• <validatorName> - The name of the validator.
• regex - JavaScript regular expression (do not use for numeric data types). See
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/
Global_Objects/RegExp.
• min - Lower limit for numeric data types.

• max - Upper limit for numeric data types.

• errorMessageKey - Localized error message (see Error message on page 243).
• errorMessage - Custom error message (see Error message on page 243).
Default validators for numeric input
The default numeric validators are used to validate numeric input under the
following circumstances:
• No validator is assigned to the type.
• A validator with a regex is assigned to the type.
• An “empty validator” with no regex or min/max is assigned to the type. This
means you cannot assign an “empty validator” to a type to disable the default
numeric validators.
Note: A validator with min only sets no upper limit, and a validator with max
only sets no lower limit.
The following default validators are implemented (min - max):

• byte: 0 - 255
• int: 0 - 215-1
• long: 0 - 253-1
• uint: 0 - 216-1
• ulong: 0 - 253-1
Order of precedence
• If a regex is defined for a validator, then the regex is used for validation and
any min/max defined are ignored. These validators will be ignored for numeric
data types.
• If no regex is defined, but min and/or max is defined, then min/max is used for
numeric validation.
Example 25-12: Validators
"validators" : {
"positiveInteger" : {
"min" : 0,
"errorMessageKey": "VALIDATION_ERROR.POSITIVE_INTEGER"
},
"negativeInteger" : {
"max" : -1,
"errorMessageKey" : "VALIDATION_ERROR.NEGATIVE_INTEGER"
},
"rangeOfNumbers" : {
"min" : 0,

"max" : 150,
"errorMessage": "Enter a number between 0 and 150"
},
"integer" : {
"min" : -32767,
"max" : 32767,
"errorMessageKey" : "VALIDATION_ERROR.INTEGER"
},
...
Defining new validators

You can define new validators if you need to. First you define the validator in
the validators section and then you add it (case sensitive) as "validator":
"<validatorName>" to the appropriate types in the types section.
Example 25-13: Validator checking upper limit

"maximumNumber" : {
"max" : 150,
"errorMessage": "Enter a number less than 150"
},
Example 25-14: Validator allowing a specific sequence

This validator only allows sequence of exactly three numbers followed
by at least one lowercase letter.
"myNameValidator": {
"regex": "^\d\d\d[a-Z]+$",
"errorMessage": "Enter a sequence of three digits
followed by a lowercase letter)"
},
Error message
You must use either errorMessageKey or errorMessage to set error messages
for invalid input.
• errorMessageKey is a key, for example VALIDATION_ERROR.
POSITIVE_FLOAT, that references a predefined localized error message.
Localized error messages cannot be edited, and you cannot create new error
message keys.
• errorMessage is for custom error messages (no localization is applied).
Notes
• You can use errorMessageKey also for custom error messages.
• errorMessage overrides errorMessageKey.

25.4.5.3 Properties
The properties section contains all editable properties to be available. Properties
can be specified as follows:
"<propertyName>": {
"type": "<type>",
"localizationkey": <localizationKey>,
"displayName": <displayName>
}
Configuration keys
• <propertyName> - The name of the property.
• type - A type specified in the types section.
• localizationkey - Localized label for the property (see Labels on page 245).
• displayName - Custom label for the property (see Labels on page 245).
Example 25-15: Properties
"properties": {
"alt": {
"type": "string",
"localizationkey": "PROPERTY.LABEL.ALTERNATIVE_TEXT"
},
"keep_together": {
"type": "boolean",
"localizationkey": "PROPERTY.LABEL.KEEP_TOGETHER"
},
"keep_with_next": {
"type": "boolean",
"localizationkey": "PROPERTY.LABEL.KEEP_WITH_NEXT"
},
...
Properties of type unit

Properties of type unit will generate two properties in the theme. For example
the property width will generate the properties width for the numeric value and
width.unit for the unit (pt, px, etc.).
Defining new properties

You can define new properties if you need to. First you define the property in
the properties section and then you add it (case sensitive) to the appropriate
property list in the objects section.
Example 25-16: Custom property for line height

In this example the property line-height is implemented in a Template
Engine template and should be defined in properties.json. First you
add lineheight to the properties section:

"lineheight": {
"type": "numeric",
"displayName": "Line height"
}
Then you add it (case sensitive) to the appropriate property list under
the textfragment object:
"category": "spacing",
"list": [
{ "property": "spacebefore" },
{ "property": "spaceafter" },
{ "property": "leftindent" },
{ "property": "alignment" },
{ "property": "lineheight" }
]
Labels
properties.
• localizationkey is a key, for example PROPERTY.

LABEL.ALTERNATIVE_TEXT, that references a predefined localized label.
Localized labels cannot be edited, and you cannot create new localization
keys.
• displayName property is used for custom labels (no localization is applied).
Notes
Filters
If you want to hide a property for a specific template process you can use the
"processes": ["<processtype>"] key, and if you want to hide a property for
a specific context you can use the "contexts": ["<storagetype>"] key. See
“Filtering attributes and properties” on page 251.
You can use a filter key in the properties section or in the objects section.
When you use it in the properties section it will be applied to all objects where
the property is used, and when you use it in the objects section it will only be
applied to that specific object. In the objects section you can use it for
individual properties or whole property lists.
Example 25-17: Using the processes key in the properties section
"spacebefore": {
"type": "unit",
"localizationkey": "PROPERTY.LABEL.SPACE_BEFORE",

"processes": ["storyteller"]
},
Example 25-18: Using the processes key in the objects section

(individual property)
"category": "spacing",
"list": [
{ "property": "spacebefore",
"processes": ["storyteller"] },
{ "property": "leftindent" },
{ "property": "alignment" }
]

(property list)
"category": "flowcontrol",
"processes": ["storyteller"],
"list": [
{ "property": "start_position" },
{ "property": "keep_with_next" }
]
}
25.4.5.4 Attributes
An attribute is related to the physical object, for example an attribute of a CAS
resource. The attributes section contains all attributes to be available. Attributes
can be specified as follows:
"<attributeName>": {
"type": "<type>",
}
Configuration keys
• <attributeName> - The name of the attribute.
• type - A type specified in the types section.
• localizationkey - Localized label for the attribute.
Example 25-20: Attributes

"attributes": {
"name": {

"type": "string",
"localizationkey": "ATTRIBUTE.LABEL.NAME"
},
"description": {
"type": "string",
"localizationkey": "ATTRIBUTE.LABEL.DESCRIPTION"
},
"type": {
"type": "string",
"localizationkey": "ATTRIBUTE.LABEL.TYPE"
},
...
Defining new attributes

You cannot define new attributes. You can however add validators to existing
attributes if you need to.
Example 25-21: Adding a validator to an attribute

"name": {
"type": "string",
"localizationkey": "ATTRIBUTE.LABEL.NAME",
"validator" : "myNameValidator"
},
Filters
If you want to hide an attribute for a specific template process you can use the
"processes": ["<processtype>"] key, and if you want to hide an attribute for
a specific context you can use the "contexts": ["<storagetype>"] key. See
“Filtering attributes and properties” on page 251.
You can use a filter key in the attributes section or in the objects section.
When you use it in the attributes section it will be applied to all objects where
the attribute is used, and when you use it in the objects section it will only be
applied to that specific object. In the objects section you can use it for
individual attributes or whole attribute lists.
Example 25-22: Using the processes key in the attributes section

"lastModificationTime": {
"type": "datetime",
"localizationkey": "ATTRIBUTE.LABEL.MODIFICATIONTIME",
"processes": ["storyteller"]}

(individual attribute)
"category": "general",
"list": [

{ "attribute": "name" },
{ "attribute": "description" },
{ "attribute": "version" },
{ "attribute": "latestversion" },
{ "attribute": "lastModificationTime", "processes":
["storyteller"]}

(attribute list)
"list": [
{ "attribute": "latestversion" },
{ "attribute": "lastModificationTime"}
25.4.5.5 Categories
The categories section contains all categories to be available. Categories are used
to group properties and attributes, and can be specified as follows:
"<categoryName>": {
"displayName": <displayName>
}
Configuration keys
• <categoryName> - The name of the category.
• localizationkey - Localized label for the category (see Labels on page 249).
• displayName - Custom label for the category (see Labels on page 249).
Example 25-25: Categories

"categories": {
"general": {
"localizationkey": "CATEGORY.LABEL.GENERAL"
},
"defaults": {
"localizationkey": "CATEGORY.LABEL.DEFAULTS"
},
"flowcontrol": {
"localizationkey": "CATEGORY.LABEL.FLOWCONTROL"
},
"spacing": {
"localizationkey": "CATEGORY.LABEL.SPACING"

}
}
Defining new categories

You can define new categories if you need to. First you define the category in the
categories section and then you add it (case sensitive) to the appropriate
objects in the objects section.
Example 25-26: Defining a new category

In this example a new category mycategory is defined. First you add
mycategory to the categories section:
"mycategory": {
"displayName": "My category"
}
Then you add it (case sensitive) to the appropriate objects in the objects
section:
{"category": "mycategory",}
Finally you add a list of properties and attributes to group under the
category:
{
"category": "mycategory",
"list": [
{ "property": "someProperty" },
{ "attribute": "someAttribute" },
...
]
},
Labels
categories.
• localizationkey is a key, for example CATEGORY.LABEL.DEFAULTS, that

references a predefined localized label. Localized labels cannot be edited, and
you cannot create new localization keys.
• displayName is used for custom labels (no localization is applied).
Notes


Filters
If you want to hide a category, and all its properties and attributes, for a specific
template process you can use the "processes": ["<processtype>"] key, and
if you want to hide it for a specific context you can use the "contexts":
["<storagetype>"] key. See “Filtering attributes and properties” on page 251.
Example 25-27: Hiding the flowcontrol category
"category": "flowcontrol",
"list": [
{ "property": "start_position" },
{ "property": "keep_together" },
{ "property": "keep_together_first" },
{ "property": "keep_together_last" },
{ "property": "keep_with_next" }
]
25.4.5.6 Objects
The objects section ties categories, properties and attributes together for the
different object types, and specifies which attributes and properties to display in the
Properties panel for the active object. Each object contains a logical name, categories
and lists of properties and attributes.
Object types
• theme - The base object in StoryBoard and ReTouch.
• section - A section in a theme that can contain groups, text fragments, images,
and stories.
• group - A group in a section. A group can contain text fragments, images, and
stories.
• textfragment - A text resource that can contain html, plain text, or xml. A text
fragment is a resource coming from CAS or the MessageStore repository.
• image - An image is a resource coming from CAS or the MessageStore
repository.
• story - An exposed story from a StoryTeller template.
Example 25-28: The theme object
"objects": {
"theme": [
{
"list": [

{ "attribute": "createdBy" },
{ "attribute": "creationTime" },
{ "attribute": "lastModificationTime" },
{ "attribute": "lockedBy" }
]
},
{
"category": "defaults",
"list": [
{ "property": "spacebefore" },
{ "property": "leftindent" }
]
}
],
...
25.4.5.7 Filtering attributes and properties

All properties and attributes in properties.json can be applied to all contexts and
template processes (StoryTeller or Template Engine) by default. The attributes and
properties are directly related to an object (Theme, Section, Resource, etc.), and the
list of properties and attributes shown in the Properties panel is first determined by
the selected object. This list can be filtered by context and process.
Context filter
The context of an attribute or property is related to the storage type of the object,
where the storage type is either cas or messagestore. If you want to hide a
property or attribute for a specific context you can use the "contexts":
["<storagetype>"] key.
A property or attribute that includes the contexts key is only available to the
storage type specified. For example, a property with "contexts": ["cas"] is
only available to objects stored in CAS. You can specify several storage types in
the value list. For example, a property with "contexts": ["cas",
"messagestore"] is available to objects stored both in CAS and the
MessageStore repository.
Example 25-29: Context filter

Resources edited in ReTouch are stored in the MessageStore repository,
and do not have all the attributes that are available for the corresponding
resource in CAS. To hide these attributes in ReTouch you can add the
"contexts": ["cas"] key to the corresponding attributes.
Process filter
If you want to hide a property or attribute for a specific template process you
can use the "processes": ["<processtype>"] key.

A property or attribute that includes the processtype key is only available to

the template process specified. For example, a property with "processes":
["storyteller"] is only available to StoryTeller. You can specify several
Process types in the value list. For example, a property with "processes":
["storyteller", "templateengine"] is available to both StoryTeller and
Template Engine.
25.4.6 simulationSettings.json
This file contains configuration keys for simulation parameters exposed in
StoryBoard. Available simulation parameters are the properties in the custom meta
types assigned to the Message connected to the template Process.
By default, a theme exposes all available properties as simulation parameters. The

simulation parameters are grouped per meta type, and the group labels have the
same names as the corresponding meta type name.
In this file you can limit the number of simulation parameters exposed to individual
themes as well as to all themes based on the same template.
The file is divided into the following sections:

• The types section contains the data types for the properties declared in the
settings section of the configuration file. See “Types” on page 252.
• The validators section contains all validators that can be applied to types. See
“Validators” on page 254.
• The settings section contains the properties in the metadata model to make
available as simulation parameters. See “Settings” on page 256.
• The templates section is where you specify which simulation parameters to
expose to all themes based on the same template. See “Templates” on page 257.
• The themes section is where you specify which simulation parameters to expose
individual themes. See “Themes” on page 259.
Note: If you have configurations for both the template and a theme, the theme
configuration overrides the template configuration.
25.4.6.1 Types
The types section contains the data types for the properties declared in the
settings section of the configuration file. Types can be specified as follows:
"<typeName>": {
"systype": "<sysType>",
"enum": [{"value": "<value>","displayName": "<displayName>"},...],
"validator": "<validator>"
}
Configuration keys
• <typeName> - The name of the type.

• systype - The system type of the type.

• enum - Optional enum list.
• value - Value for options in the enum list.
• displayName - Custom label for options in the enum list.
• validator - Optional validator for the type.
Example 25-30: Types

"types": {
"string": {
"systype": "string"
},
"integer": {
"systype": "integer"
},
"double": {
"systype": "float"
}
}
Defining new types

You cannot add new arbitrary types, but you can define new types based on
existing system types (systype).
Types for listed properties

You can define additional types to be used as pre-populated lists of properties in
StoryBoard. To do this you must define the new type as an enum system type
and then reference the type in the settings section of the configuration file. The
following example shows a new type with two options:
"gender": {
"systype": "enum",
"enum": [
{"value": "female","displayName": "female"},
{"value": "male","displayName": "male"}
]
}
Each option contains a value and a displayName where value is the property
value and displayName is the property label in the list in StoryBoard. The
property list will also contain a (default) option which resets to the property
value in the simulation selected in StoryBoard.
Labels
You must use displayName to set the labels for the options in the enum list.

25.4.6.2 Validators
The validators section contains the validators assigned to type definitions in order
to validate simulation parameter values entered by StoryBoard users. Validators can
be specified as follows:
"<validatorName>": {
"regex": "<regularExpression>",
"min": <num>,
"max": <num>,
"errorMessageKey": "<localizationKey>"
"errorMessage": "<errorMessage>"
}
Configuration keys
• <validatorName> - The name of the validator.
• regex - JavaScript regular expression (do not use for numeric data types). See
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/
Global_Objects/RegExp.
• min - Lower limit for numeric data types.
• max - Upper limit for numeric data types.
• errorMessageKey - Localized error message (see Error message on page 243).
• errorMessage - Custom error message (see Error message on page 243).
Default validators for numeric input
The default numeric validators are used to validate numeric input under the
following circumstances:
• No validator is assigned to the type.
• A validator with a regex is assigned to the type.
• An “empty validator” with no regex or min/max is assigned to the type. This
means you cannot assign an “empty validator” to a type to disable the default
numeric validators.
Note: A validator with min only sets no upper limit, and a validator with max
only sets no lower limit.
The following default validators are implemented (min - max):

• byte: 0 - 255
• int: 0 - 215-1
• long: 0 - 253-1
• uint: 0 - 216-1
• ulong: 0 - 253-1

Order of precedence
• If a regex is defined for a validator, then the regex is used for validation and
any min/max defined are ignored. These validators will be ignored for numeric
data types.
• If no regex is defined, but min and/or max is defined, then min/max is used for
numeric validation.
Example 25-31: Validators
"validators" : {
"positiveInteger" : {
"min" : 0,
"errorMessageKey": "VALIDATION_ERROR.POSITIVE_INTEGER"
},
"negativeInteger" : {
"max" : -1,
"errorMessageKey" : "VALIDATION_ERROR.NEGATIVE_INTEGER"
},
"rangeOfNumbers" : {
"min" : 0,
"max" : 150,
"errorMessage": "Enter a number between 0 and 150"
},
"integer" : {
"min" : -32767,
"max" : 32767,
"errorMessageKey" : "VALIDATION_ERROR.INTEGER"
},
...
Defining new validators

You can define new validators if you need to. First you define the validator in
the validators section and then you add it (case sensitive) as "validator":
"<validatorName>" to the appropriate types in the types section.
Example 25-32: Validator checking upper limit
"maximumNumber" : {
"max" : 150,
"errorMessage": "Enter a number less than 150"
},
Example 25-33: Validator allowing a specific sequence

This validator only allows sequence of exactly three numbers followed
by at least one lowercase letter.
"myNameValidator": {
"regex": "^\d\d\d[a-Z]+$",

"errorMessage": "Enter a sequence of three digits

followed by a lowercase letter)"
},
Error message
You must use either errorMessageKey or errorMessage to set error messages
for invalid input.
• errorMessageKey is a key, for example VALIDATION_ERROR.
POSITIVE_FLOAT that references a predefined localized error message.
Localized error messages cannot be edited, and you cannot create new error
message keys.
• errorMessage is for custom error messages (no localization is applied).
Notes
• You can use errorMessageKey also for custom error messages.
• errorMessage overrides errorMessageKey.
25.4.6.3 Settings
The settings section contains the properties in the metadata model to make
available as simulation parameters. Each property is specified as follows:
"<property>": {
"guid": "<guid>",
"name": "<logicalName>",
"displayName": "<displayName>",
"type": "<dataType>"
}
Configuration keys
• <property> - Unique label for the property in simulationSettings.json.
• guid - The property key. You can obtain this key in Describer by right-clicking
the property and selecting Copy key.
• name - The logical name for the property. We recommend you to use the same
name as defined in Describer.
• displayName - The display name for the property. If not specified, the logical
name is used as display name.
• type - The data type of the property. The available types are defined in the types
section of the configuration file.
Example 25-34: Settings

"settings": {
"customerName": {

"guid": "F441E9B9-CBEE-42F0-98F0-1FA59E083088",
"name": "name",
"displayName": "Name",
"type": "string"
},
"customerAge": {
"guid": "7534D224-DEEA-446D-9692-C6EDB9BA120F",
"name": "age",
"displayName": "Age",
"type": "integer"
},
"orderTotal": {
"guid": "0B38EA7C-37FA-474E-A191-CB051355F65B",
"name": "total",
"displayName": "Total",
"type": "double"
},
...
}
Note: If several properties have the same property name, for example if there
are two "customer": {...} properties, the last defined property is used.
25.4.6.4 Templates
The templates section is where you specify which simulation parameters to expose
to all themes based on the same template. You can group the parameters into labeled
groups, and you can also specify different simulation parameters for different
template versions. Each template is configured as follows:
"<templateName>": {
"groups": [
{
"name": "<groupName>",
"settings": [
"<property>",
...
]
},
{
"settings": [
"<property>",
...
]
}
...
]
}

Configuration keys
• <templateName> - The name of the template to expose the simulation
parameters to.
• name - Each group has a name. The name you enter here will be displayed as
group label for all simulation parameters in the group.
• settings - List of all simulation parameters to have in each group.
Example 25-35: Templates
"templates": {
"TravelInsurance": {
"groups": [
{
"name": "Customer",
"settings": [
"customerName",
"customerEmail"
]
}
]
},
"EmailBody": {
"groups": [
{
"name": "Customer",
"settings": [
"customerName",
"customerEmail"
]
}
]
}
}
Parameters for different versions

You can specify different simulation parameters for different template versions.
To do this you add a versions list where you specify the groups to have for
each version.
You can also add default groups outside the versions list to have a limited set
of parameters for versions not defined in the versions list. If you do not,
themes based on undefined versions will expose all available properties as
simulation parameters.
Example 25-36: Different simulation parameters for different

template versions
"EmailBody": {
"versions": [
{

"version": "1",
"groups": [
{
"name": "WebDoc",
"settings": [
"customerName",
"customerEmail"
]
}
]
},
{
"version": "2",
"groups": [
{
"name": "WebDoc",
"settings": [
"customerName"
]
}
]
}
],
"groups": [
{
"name": "WebDoc",
"settings": [
"customerEmail"
]
}
]
}
Note: If several template configurations have the same <templateName>, the

last defined template configuration is used.
25.4.6.5 Themes
The themes section is where you specify which simulation parameters to expose to
individual themes. You can group the parameters into labeled groups. Each theme is
configured as follows:
"<identifier>": {
"groups": [
{
"settings": [
"<property>",
...
]
},

{
"settings": [
"<property>",
...
]
}
...
]
}
Configuration keys
• <identifier> - The name or GUID of the theme to expose the simulation
parameters to.
• name - Each group has a name. The name you enter here will be displayed as
group label for all simulation parameters in the group.
• settings - List of all simulation parameters to have in each group.
Example 25-37: Themes

"themes": {
"TravelInsurance": {
"groups": [
{
"name": "Customer",
"settings": [
"customerName",
"customerEmail"
]
}
]
},
"EmailBody": {
"groups": [
{
"name": "Customer",
"settings": [
"customerName",
"customerEmail"
]
}
]
}
}
Note: If several themes configurations have the same <identifier>, the last
defined theme configuration is used.

25.5. Text editor properties
25.5 Text editor properties

You can configure style and font properties for editing texts in Writer, StoryBoard
and ReTouch. To do this you must edit the file config.js located in the following
folder relative to the deployed Writer, StoryBoard and ReTouch application folders:
3rdparty\ckeditor
Both the Communications Builder Project and the style and font properties must be
configured properly to make the styles and fonts work in the context of the Project.
The default style and font configuration that comes with the installation may contain
properties that do not work out of the box. In such a case config.js or the Project
must be adapted.
Using rewrite rules
When a web application is updated and redeployed, config.js is overwritten with

the default style and font properties. You should therefore make sure to have a copy
of the customized config.js.
OpenText recommends that you define rewrite rules in your application server for
3rdparty\ckeditor in each web application (Writer, StoryBoard and ReTouch). By
doing this you will redirect the configuration to an external folder that is not affected
by the deployment process. Note that the ckeditor content may be updated after
deploying a new version of the web applications. This means you must make sure
the same changes are applied to the external folder.
See https://tomcat.apache.org/tomcat-8.5-doc/rewrite.html for more information

about rewrite rules.
Configuring style properties

The list of styles available when editing texts must be supported in the Project
configuration, i.e. the template of a theme. To adapt the styles list to styles
supported by the template you can override the default styles by adding the
config.stylesSet parameter to config.js and specifying the styles to be
available. See stylesSet in https://docs.ckeditor.com/ckeditor4/docs/#!/api/
CKEDITOR.config (https://docs.ckeditor.com/ckeditor4/docs/#!/api/
CKEDITOR.config-cfg-stylesSet) for more information.
Configuring font properties

The fonts available when editing texts must be supported by the template of a
theme. All these fonts must also be included in the export package deployed to the
Communications Server application that exposes the template. You must make sure
that only supported fonts are available in the font list.

To override the default font set you add the config.font_names parameter to
config.js and specify the fonts to be available. See font_names in https://
docs.ckeditor.com/ckeditor4/docs/#!/api/CKEDITOR.config (https://
docs.ckeditor.com/ckeditor4/docs/#!/api/CKEDITOR.config-cfg-font_names) for
more information.

Chapter 26
Running the web applications
This section contains information about accessing and running the web applications.
Prerequisites and recommendations

• The service gateway to be used for communication must be running.
• To enable a user to log in to a web application, OTDS must be installed and
configured for Exstream, and a role must be assigned to the user.
• There must be enough memory allocated for the web applications on the JVM
(Java Virtual Machine). The required amount of memory depends on installation
environment, number of deployed web applications, and the load on the Java
application server. As a rule of thumb, OpenText recommends the following JVM
memory setting when deploying a single web application to a separate Java
application server:
-Xmx1024m
Tip: Use a Java profiling tool to monitor and tune the Java memory settings
on a running Java application server.
Recommended screen resolution

• Recommended desktop screen resolution – 1920 x 1080 pixels.
• Minimum desktop screen resolution – 1280 x 1024 pixels.
• Run the application in a maximized desktop browser window.
• Recommended tablet screen resolution – 1024 x 768 pixels.
26.1 Accessing WorkShop

WorkShop can be run as a standalone application or embedded in a hosting
application. You can use two types of URL:s to access WorkShop:
• Friendly URL (if enabled, see “Connection properties” on page 226).
• Tenant and domain information.
Base URL used in instructions

The following base URL (<baseUrl>) is used in the instructions below:
http://<host>:<port>/<workshop>
Where:
• <host> – The host name or IP address of the computer that runs the Java
application server.

Chapter 26 Running the web applications
• <port> – The port the Java application server listens to. Default is 8080.
• <workshop> – The WorkShop application name. Default is workshop.
Using friendly URL

You can use friendly URL:s to access WorkShop if friendly URL:s are enabled in
the configuration file:
<baseUrl>/frdurl/<pattern>
Where:
• frdurl – Leave as is.
• <pattern> – The <url-pattern> element defined in the configuration file.
Example 26-1: Friendly URL

http://10.168.166.56:8080/workshop/frdurl/t1
Using tenant and domain information

You can use tenant and domain information in the URL to access WorkShop:
<baseUrl>/tenant/<tenantKey>/domain/<domainKey>
Where:
• tenant – Leave as is.
• <tenantKey> – The tenant name or tenant ID.
• domain – Leave as is.
• <domainKey> – The domain name or domain ID.
Example 26-2: Tenant and domain name

http://10.168.166.56:8080/workshop/tenant/tenant1/domain/
Dev
Example 26-3: Tenant and domain ID

http://10.168.166.56:8080/workshop/tenant/9B4AAD3B-
E870-1E45-A5A8-B28A3A62C3A7/domain/0D415B48-6825-B845-99FD-
A7B3EC6A5DBA
Additional WorkShop path elements and query strings

Path elements
Additional path elements can be applied to a tenant and domain information
URL:
<baseURL>[/hosted][/<view>]/tenant/<tenantKey>/domain/<domainKey>

26.1. Accessing WorkShop
Where:
• hosted – Run WorkShop in hosted mode (embedded in a hosting
application).
• <view> – Access one of the following views directly:
• resources – Access the Resources view.
• templates – Access the Templates view.
• services – Access the Services view.
Example 26-4: Additional path elements

http://10.168.166.56:8080/workshop/hosted/templates/tenant/
strs/domain/Dom1
Query strings
Additional query strings can be applied to a tenant and domain information
URL:
<baseUrl>/<view>/tenant/<tenantKey>/domain/<domainKey>?
[header=true|false][&navigation=true|false][&actions=true|false]
[&OTDSTicket=<ticket>][&language=<langCode>]
Where:
• header=true|false – Show/hide the WorkShop header bar (with the
application branding and top level actions) when accessing the view directly.
N/A for hosted mode.
• navigation=true|false – Show/hide the WorkShop navigation bar (with
the view tabs) when accessing the view directly. N/A for hosted mode.
• actions=true|false – Show/hide the WorkShop function toolbar (with the
actions for a selected resource) when accessing the view directly. N/A for
hosted mode.
• OTDSTicket=<ticket> – Authenticates the user, if already logged in. If not
specified, the user is redirected to the OTDS log in page.
Note: Single-sign on is supported via the ticket. When a user is logged

in, the ticket is stored for the web browser session. As long as the
session is not terminated, the user can access the same or another web
application in the same browser without having to log in again.
• language=<langCode> – Optional language code (two or four letter code)
that determines which locale to apply. If not set, the language code set in the
browser is used. You can use either underscore (_) or dash (-) as separator in
four letter codes. For example, you can use either de_DE or de-DE.
URL encoding
When using a full URL, with tenant and domain in the URL, the characters #, ?
and & must be URL encoded. Use %23 for #, %3F for ? and %26 for &.

Fallback language for language codes

If an invalid language code is set, en is used as fallback. If a requested four letter
code is not available, the corresponding two letter code is used as fallback, and if
the two letter code is not available, en is used as fallback.
Example 26-5: Additional query strings
http://10.168.166.56:8080/workshop/resources/tenant/strs/
domain/Dom1%3Fheader=false%26navigation=false%26language=de_DE
26.2 Accessing Supervisor

Supervisor can be run as a standalone application or embedded in a hosting
application. You can use two types of URL:s to access Supervisor:
• Friendly URL (if enabled, see “Connection properties” on page 226).
• Tenant and domain information.
Base URL used in instructions

The following base URL (<baseUrl>) is used in the instructions below:
http://<host>:<port>/<supervisor>
Where:
application server.
• <supervisor> – The Supervisor application name. Default is supervisor.
Using friendly URL

You can use friendly URL:s to access Supervisor if friendly URL:s are enabled in
the configuration file:
<baseUrl>/frdurl/<pattern>
Where:
• frdurl – Leave as is.
• <pattern> – The <url-pattern> element defined in the configuration file.
Example 26-6: Friendly URL

http://10.168.166.56:8080/supervisor/frdurl/t1
Using tenant and domain info

You can use tenant and domain information in the URL to access Supervisor:
<baseUrl>/tenant/<tenantKey>/domain/<domainKey>

26.2. Accessing Supervisor
Where:
Example 26-7: Tenant and domain name

http://10.168.166.56:8080/supervisor/tenant/tenant1/domain/
Dev
Example 26-8: Tenant and domain ID

http://10.168.166.56:8080/supervisor/tenant/9B4AAD3B-
E870-1E45-A5A8-B28A3A62C3A7/domain/0D415B48-6825-B845-99FD-
A7B3EC6A5DBA
Additional Supervisor path elements and query strings

Path elements
Additional path elements can be applied to a tenant and domain information
URL:
<baseURL>[/hosted][/<view>]/tenant/<tenantKey>/domain/<domainKey>
Where:
• hosted – Run Supervisor in hosted mode (embedded in a hosting
application).
• <view> – Access one of the following views directly:
• messages – Access the Review view.
• jobs – Access the Track view.
• produce – Access the Produce view.
• queuemanager – Access the Queue view.
• statistics – Access the Statistics view.
• logs – Access the Log view.
• roles – Access the Roles view.
Example 26-9: Additional path elements

http://10.168.166.56:8080/supervisor/hosted/jobs/tenant/
strs/domain/Dom1

Query strings
Additional query strings can be applied to a tenant and domain information
URL:
<baseUrl>/<view>/tenant/<tenantKey>/domain/<domainKey>?
[header=true|false][&navigation=true|false][&actions=true|false]
[&OTDSTicket=<ticket>][&language=<langCode>]
Where:
• header=true|false – Show/hide the WorkShop header bar (with the

application branding and top level actions) when accessing the view directly.
N/A for hosted mode.
• navigation=true|false – Show/hide the WorkShop navigation bar (with
the view tabs) when accessing the view directly. N/A for hosted mode.
• actions=true|false – Show/hide the WorkShop function toolbar (with the
actions for a selected resource) when accessing the view directly. N/A for
hosted mode.
• OTDSTicket=<ticket> – Authenticates the user, if already logged in. If not
specified, the user is redirected to the OTDS log in page.
Note: Single-sign on is supported via the ticket. When a user is logged

in, the ticket is stored for the web browser session. As long as the
session is not terminated, the user can access the same or another web
application in the same browser without having to log in again.
• language=<langCode> – Optional language code (two or four letter code)
that determines which locale to apply. If not set, the language code set in the
browser is used. You can use either underscore (_) or dash (-) as separator in
four letter codes. For example, you can use either de_DE or de-DE.
URL encoding

Example 26-10: Additional query strings
http://10.168.166.56:8080/supervisor/jobs/tenant/strs/domain/
Dom1%3Fheader=false%26navigation=false%26language=de_DE

26.3. Accessing StoryBoard
26.3 Accessing StoryBoard

StoryBoard can be launched as a standalone application or run embedded in a
hosting application. You can use the following URL to access StoryBoard:
<baseUrl>/tenant/<tenantKey>/domain/<domainKey>/<appMode>.html%23/
<viewMode>/<themeId>/<previewFormat>/<simulationId>
%3Flanguage=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<storyboard>
application server.
• <storyboard> – The StoryBoard application name. Default is storyboard.
• <appMode> – index for running StoryBoard standalone and hosted for running
StoryBoard embedded in a hosting application.
• <viewMode> – preview for view-only and edit for editing themes.
• <themeId> – The theme ID returned from the REST API.
• <previewFormat> – The preview format (WEB for unpaginated preview or PRINT
for paginated preview).
• <simulationId> – The simulation ID returned from the REST API.
• language=<langCode> – Optional language code (two or four letter code) that
determines which locale to apply. If not set, the language code set in the browser
is used. You can use either underscore (_) or dash (-) as separator in four letter
codes. For example, you can use either de_DE or de-DE.
URL encoding


Example 26-11: StoryBoard URL hosted mode
http://10.168.166.56:8080/storyboard/tenant/strs/domain/Dom1/
hosted.html%23/preview/Y3hyOi8_a...g5ZQ==/WEB/
Y3hyOi8_a...AyMA==%3Flanguage=de_DE
26.4 Accessing ReTouch

ReTouch can be launched as a standalone application or run embedded in a hosting
application. You can use the following URL to access ReTouch:
<baseUrl>/tenant/<tenantKey>/domain/<domainKey>/<appMode>.html%23/
<viewMode>/<documentTypeId>:<documentId>/<previewFormat>
%3Flanguage=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<retouch>
application server.
• <retouch> – The ReTouch application name. Default is retouch.
• <appMode> – index for running ReTouch standalone and hosted for running
ReTouch embedded in a hosting application.
• <viewMode> – preview for view-only and edit for editing documents.
• <documentTypeId> – The document type ID in the Message repository.
• <documentId> – The document ID in the Message repository.
• <previewFormat> – The preview format (WEB for unpaginated preview or PRINT
for paginated preview).
URL encoding

26.5. Accessing Writer

Example 26-12: ReTouch URL hosted mode
http://10.168.166.56:8080/retouch/tenant/strs/domain/Dom1/
hosted.html%23/edit/
477A7F3B-0DC9-5B89-51D7-6B7D1BF5B107:6D650CD4-95D7-CB4B-A1E7-
AB61EEB4BED2/WEB%3Flanguage=de_DE
26.5 Accessing Writer

Writer can be launched as a standalone application or run embedded in a hosting
application. You can use the following URL to access Writer:
<baseUrl>/[hosted]/tenant/<tenantKey>/domain/<domainKey>/resource/
<resourceID>?language=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<writer>
application server.
• <writer> – The Writer application name. Default is writer.
• hosted – Optional parameter for running Writer embedded in a hosting
application. If not used, Writer is run as a standalone application.
• resource – Leave as is.
• <resourceID> – The resource ID returned from the REST API.


Example 26-13: Writer URL hosted mode
http://10.168.166.56:8080/writer/hosted/tenant/strs/domain/
Dom1/resource/Y3hyOi8_a...g5ZQ==?language=de_DE
26.6 Accessing Rule Editor

Rule Editor can be launched as a standalone application or run embedded in a
hosting application. You can use the following URL to access Rule Editor:
<baseUrl>/[hosted]/tenant/<tenantKey>/domain/<domainKey>/resource/
<resourceID>?language=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<ruleeditor>
application server.
• <ruleeditor> – The Rule Editor application name. Default is ruleeditor.
• hosted – Optional parameter for running Rule Editor embedded in a hosting
application. If not used, Rule Editor is run as a standalone application.
• resource – Leave as is.
• <resourceID> – The resource ID returned from the REST API.

Example 26-14: Rule Editor URL hosted mode
http://10.168.166.56:8080/ruleeditor/hosted/tenant/strs/
domain/Dom1/resource/Y3hyOi8_a...g5ZQ==?language=de_DE

26.7. Accessing Control
26.7 Accessing Control

Control is accessed by entering the following URL in a web browser:
http://<host>:<port>/<control>
Where:
application server.
• <control> – The Control application name. Default is control.
When accessing Control, the Connect to Management Gateway dialog is displayed,

where you select the management gateway and tenant to connect to.
In the Host field, enter the host in the following format:
http(s)://<host>:<port>
Where:
• <host> – The host name or IP address of the computer that runs the management
gateway.
• <port> – The REST API port of the management gateway. Default is 28701.
Once you have set up a management gateway connection from Control, you will be
able to select that host from the drop-down menu in the Host field.
In the Tenant Name field, enter the name of the tenant you want to access, and click
Connect.
Note: If you are not logged in to the OTDS, you will be redirected to the OTDS
login page, and may need to enter the management gateway connection
settings again.

Chapter 27
Monitoring the web applications
This section contains information about the services and the log files to be monitored
when running the web applications.
Checking status of services

To start a web application, the following must be fulfilled:
• The service gateway to be used for communication must be running. In Control

Center, right-click the service gateway and select Refresh. Verify that the State
property is Running.
• The services required by the web application must be started. In your operational
system, verify that the service for the service gateway and the service for the Java
application server are started.
Checking log files

• The service gateway includes an embedded Java application server from Apache
Tomcat, used internally for providing the REST API. For log information
regarding this embedded Tomcat, check the service gateway Java log file. See
“Service gateway REST log” on page 275.
• For log information regarding the WorkShop and Supervisor applications, check
the application-specific log files. See “Application logs” on page 277.
• For log information regarding the service gateway, check the service gateway log
in Control Center. See “Logging in Control Center“ on page 173.
• For log information regarding the Communications Server application, check the
Communications Server application log in Control Center. See “Logging in
Control Center“ on page 173.
27.1 Service gateway REST log

The service gateway includes an embedded Java application server from Apache
Tomcat, used internally for providing the REST API. The corresponding log for the
REST API calls are located in:
<baseDirectory>\<Version>\root\applications\<serviceGateway>\wd\
servicegateway_rest.log
Where:
• <baseDirectory> – Is the path to Exstream applications specified during

installation. Default path is C:\ManagementGateway

Chapter 27 Monitoring the web applications
• <serviceGateway> – Is the name of the service gateway.
Changing the log level

You can change the log level in the application.properties file for service
gateway (see “Service gateway properties” on page 221). The default log settings are
as follows:
logging.level.=INFO
logging.level.com.streamserve=INFO
logging.file=servicegateway_rest.log
Available log levels

• ERROR – Severe error.
• WARN – Non-fatal error that needs investigation.
• INFO – Informational message. This is the default log level.
• DEBUG – Detailed information for support and developers.
• TRACE – Even more fine-grained information, for developers only.
To change the log level
1. Open the application.properties file.
2. Update the log level as required.
4. In Control Center, restart the service gateway.
27.2 Management gateway REST log

The management gateway includes an embedded Java application server from
Apache Tomcat, used internally for providing the REST API. The corresponding log
for the REST API calls are located in:
<baseDirectory>\<Version>\root\mgw_rest.log
Where <baseDirectory> – Is the path to Exstream applications specified during

installation. Default path is C:\ManagementGateway
Changing the log level

You can change the log level in the application.properties file for management
gateway (see “Management gateway properties” on page 224). The default log
settings are as follows:
logging.level.=INFO
logging.level.com.streamserve=INFO
logging.file=mgw_rest.log

27.3. Application logs
Available log levels

• ERROR – Severe error.
• WARN – Non-fatal error that needs investigation.
• INFO – Informational message. This is the default log level.
• DEBUG – Detailed information for support and developers.
• TRACE – Even more fine-grained information, for developers only.
To change the log level
1. Open the application.properties file.

2. Update the log level as required.
27.3 Application logs

The WorkShop and Supervisor applications have their own log files. You can
configure where the log files are located on your disk.
To configure the location of the WorkShop log file
1. Go to the following directory in the portal root on the Java application server:
<deployed WorkShop folder>\WEB-INF\classes\log4j.properties
For example:
2. Update the location of the log file in the following property.
log4j.appender.file.File=${user.home}/strswebapp_logs/
workshop.log
For example, to locate the log file in your home directory:
log4j.appender.file.File=C:/Users/<User name>/strswebapp_logs/
workshop.log
To configure the location of the Supervisor log file
1. Go to the following directory in the portal root on the Java application server:
<deployed Supervisor folder>\WEB-INF\classes\log4j.properties
2. Update the location of the log file in the following property.

log4j.appender.file.File=${user.home}/strswebapp_logs/
supervisor.log
For example, to locate the log file in your home directory:

Chapter 27 Monitoring the web applications
log4j.appender.file.File=C:/Users/<User name>/strswebapp_logs/
supervisor.log
4. Restart the Java application server.

Chapter 28
Solr integration in WorkShop and Supervisor
Solr is a standalone enterprise search server that enables search capabilities such as
free text search. Content (for example resources and log messages) is added to an
index, and this index is used by Solr when searching for content.
• Supported databases
Solr integration is supported for all databases supported by the Exstream
platform except for SAP HANA.
Note: Collect view integration is only supported for SQL Server and Oracle.
• Supported operating systems

Solr integration is supported for Windows and Linux.
• Solr modes
Solr can be implemented in two different modes:
• Standalone mode. See “Standalone mode implementation” on page 279.
• Cloud mode. See “Cloud mode implementation” on page 286.
• Solr searches in WorkShop
In WorkShop, Solr searches can be enabled for the Resources views. The
WorkShop user can enter a search key to search for Text and Sample file
resources where the key matches text content in the resource, the resource name
or the resource description.
• Solr searches in Supervisor
In Supervisor, Solr searches can be enabled for the Log and Collect views. The
Supervisor user can take advantage of the full Solr search capabilities to search
for specific log messages and documents.
28.1 Standalone mode implementation

Note: Most of the information in this section and sub sections describes the
Windows implementation. The Linux implementation is similar, but you must
use the proper Linux path properties and run/edit the *.sh equivalents of the
*.cmd commands and files described here.
In standalone mode, a single Solr server handles all requests, and there is no support
for load-balancing and failover. The configuration files and scripts are located in the
following <solrUtility> directory relative to the Exstream installation directory
• Windows

Chapter 28 Solr integration in WorkShop and Supervisor
Server\bin\solr-integration-utility-16.4.0
• Linux
solutions/management/web/solr-integration-utility-16.4.0
Standalone mode implementation steps
1. Install Solr server. See “Installing Solr server ” on page 280.

2. Edit conf.properties and setPropertiesCloud.cmd in solr-integration-
utility-16.4.0. See “Editing Solr properties” on page 281.
3. As an administrator, open a command prompt and change to the

<solrUtility>\setupSolr directory:
cd <ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\setupSolr
4. Run the following commands:
a. createconfigs.cmd
b. createcores.cmd
c. runinitialimport.cmd
Note: Do not close the command prompt. If you do, Solr server will stop.
5. In a web browser, go to http://<solrHost>:<solrPort>/solr to verify that

Solr server is running and that cores are created.
6. Enable scheduling. See “Enabling scheduling” on page 282.
7. Optional Enable security. See “Enabling security” on page 284.
8. Edit the properties for each service gateway application. See “Editing service
gateway properties” on page 284.
9. Restart the service gateway applications.
If Solr server is stopped for some reason, for example if you close the command
prompt, you can use the solr start command to start Solr server.
To start Solr server
1. As an administrator, open a command prompt and change to the solrHome\bin

directory, for example:
cd c:\Program Files\OpenText\solr-6.6.0\bin
2. Run the following command: solr start -p <solrPort>
Installing Solr server

Solr server is not included in the Exstream setup or on My Support, so you must
download the package from archive.apache.org.

28.1. Standalone mode implementation
To install Solr server on Windows
1. Download solr-6.6.0.zip from http://archive.apache.org/dist/

lucene/solr/6.6.0/.
2. Extract solr-6.6.0.zip to Program Files\OpenText.
To install Solr server on Linux
1. Download solr-6.6.0.tgz from http://archive.apache.org/dist/

lucene/solr/6.6.0/.
2. Extract solr-6.6.0.tgz to <exstreamHome>.
The Solr server home directory solr-6.6.0 is referred to as solrHome in the

following sections.
Editing Solr properties

To make the integration work as expected you must edit the files conf.properties
and setProperties.cmd.
• conf.properties
Path: <ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\scaffold\conf
Verify that the multitenantrepository.path property is pointing to the
correct multitenantrepository.xml.
Example 28-1: multitenantrepository.path

multitenantrepository.path = C:\\ManagementGateway\\16.4.0\
\root\\securityprofiles\\multitenantrepository.xml
• setProperties.cmd
Edit the following properties:
• SOLR_DIR: The solrHome directory (see “Installing Solr server ” on page 280).
• MGW_APPS_DIR: The management gateway application path.
• SOLRHOST: The Solr host.
• SOLRPORT: The Solr port.
Example 28-2: Solr properties

SET CURRENT_DIR=%CD%
SET OPENTEXT_DIR=C:\Program Files\OpenText
SET SOLR_DIR=%OPENTEXT_DIR%\solr-6.6.0

SET MGW_APPS_DIR=C:\ManagementGateway\16.4.0\root
\applications
SET SOLRHOST=localhost
SET SOLRPORT=8984
Enabling scheduling
Scheduling is used for delta import of newly created resources and to remove
deleted resources from the Solr index. It is also used to remove expired logs and
collect documents from the Solr index.
To enable scheduling
1. Edit solr.scheduler.properties. See Solr scheduler properties on page 283.

<solrUtility>\scheduler directory:
utility-16.4.0\scheduler
3. Create scheduler services:
• To create a scheduler service for all tenants, run the following command:
solrindexer create -all (Windows) or sh solrindexer.sh create
-all (Linux).
• To create a scheduler service for a specific tenant, run the following

command: solrindexer create -tenant <tenantGuid> (Windows) or sh
solrindexer.sh create -tenant <tenantGuid> (Linux).
4. In Windows services, verify that there is a service solr_<GUID>_indexer and

that this service is running.
To test the scheduler service
1. In WorkShop, upload some text resources for testing.
2. After a couple of minutes, test if content search works.
3. Delete the uploaded test resources in WorkShop.
4. In a web browser, go to http://localhost:<port>/solr and check if the

index is removed from Solr (wait a couple of minutes before checking).
To disable scheduling
1. In Windows services, stop the services to disable.
2. Delete the scheduler services:
• To delete all services, run the following command: solrindexer delete

-all (Windows) or sh solrindexer.sh delete -all (Linux).

• To delete a service for a specific tenant, run the following command:

solrindexer delete -tenant <tenantGuid> (Windows) or sh
solrindexer.sh delete -tenant <tenantGuid> (Linux).
Solr scheduler properties
solr.scheduler.properties is located in the following directory relative to the

Exstream installation directory:
Server\bin\solr-integration-utility-16.4.0\scaffold\conf

• solr.enable: true.
• solr.cloudmode: false.
• solr.host: The Solr host.
• solr.port: The Solr port.
• Scheduler and delete scheduler properties: Proper time interval (milliseconds).
Example 28-3: Properties

#solr boolean properties
solr.enabled=true
solr.cloudmode=false
#solr properties
solr.host=localhost
solr.port=8983
...
#solr cloud properties
...
#solr scheduler properties
solr.resources.deltaimport.interval=60000
solr.logs.deltaimport.interval=60000
solr.collect.deltaimport.interval=60000
#solr delete scheduler properties

solr.resources.delete.interval=60000
solr.logs.deleteexpired.interval=86400000
solr.collect.deleteexpired.interval=
Scheduler logs
• Scheduler logs on Windows
solr_<GUID>.log and stdout_<GUID>.txt are available in the following
directory:
<ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\scheduler\log
• Scheduler logs on Linux

solr_<GUID>.out is available in /tmp.
Editing service gateway properties

To make the integration work as expected you must edit the file
solr_configuration-securityprofile.xml in the following directory for each
service gateway:
<mgwRoot>\applications\<appName>\wd\securityprofiles
Edit the following element and attribute values:

• url: The Solr host.
• port: The Solr port.
• solr_isenabled: true.
• solr_iscloudmode: false.
Example 28-4: Element and attribute values
...
<configuration>
<ws xmlns="http://schemas.streamserve.com/...">
<url>localhost</url>
<port>8983</port>
<security type="http://schemas.streamserve.com/...">
...
</security>
<properties>
<property id="solr_isenabled">true</property>
<property id="solr_iscloudmode">false</property>
...
</properties>
</ws>
</configuration>
...
Enabling security
To enable security
1. Edit SOLRUSERNAME and SOLRPASSWORD in setProperties.cmd. See Setting

username and password on page 285.

<solrUtility>\setupSolr directory:
3. Run the following command: secureSolr.cmd

4. Uncomment SOLR_AUTH_TYPE and SOLR_AUTHENTICATION_OPTS insolr.

in.cmd and specify the proper username and password. See Setting username
and password on page 285.
5. Set solr.username and solr.password in solr.scheduler.properties (see

Setting username and password on page 285) and restart the scheduler
services:
• Windows
Open Windows Services and restart solr_<GUID>_indexer.
• Linux
Run sh solrindexer.sh delete -all followed by sh solrindexer.sh
create.
6. Set username and password in solr_configuration-securityprofile.xml

for each service gateway application. See Setting username and password
on page 285.
Setting username and password

• setProperties.cmd
Specify the proper SOLRUSERNAME and SOLRPASSWORD.
Example 28-5: Username and password
SET SOLRUSERNAME=mySolrUser
SET SOLRPASSWORD=mySolrPwd
• solr.in.cmd
Path: <solrHome>\bin (see “Installing Solr server ” on page 280).
Uncomment the SOLR_AUTH_TYPE and SOLR_AUTHENTICATION_OPTS properties
and specify the proper username and password.
set SOLR_AUTH_TYPE=basic
set SOLR_AUTHENTICATION_OPTS="-
Dbasicauth=mySolrUser:mySolrPwd"
• solr.scheduler.properties
utility-16.4.0\scaffold\conf


• solr.username: Proper username.
• solr.password: Proper password.

solr.username=mySolrUser
solr.password=mySolrPwd
• solr_configuration-securityprofile.xml
Path: <mgwRoot>\applications\<appName>\wd\securityprofiles
Specify the proper username and password.

...
<authenticationprofile type="..." name=".../solr-auth/1.0"
tenantID="...">
<configuration>
<simple xmlns="http://schemas.streamserve.com/...">
<name>mySolrUser</name>
<password>mySolrPwd</password>
</simple>
</configuration>
</authenticationprofile>...
28.2 Cloud mode implementation

Note: Most of the information in this section and sub sections describes the
Windows implementation. The Linux implementation is similar, but you must
use the proper Linux path properties and run/edit the *.sh equivalents of the
*.cmd commands and files described here.
In Cloud mode requests are handled by multiple Solr nodes supporting load-
balancing and failover. Cloud mode requires a Zookeeper ensemble to maintain a
centralized configuration, manage the Solr cluster and set the Leader for the Solr
cluster. Each Solr node must be started in cloud mode, using the Zookeper address,
to make it part of the Solr cluster.
Cloud mode includes one machine where the actual Solr integration is done and
several Solr nodes running on different machines. The configuration files and scripts
are located in the following <solrUtility> directory relative to the Exstream
installation directory on the machine where the Solr integration is done:
• Windows
Server\bin\solr-integration-utility-16.4.0

28.2. Cloud mode implementation
• Linux
solutions/management/web/solr-integration-utility-16.4.0
Note: In Windows you must copy the solr-integration-utility-16.4.0

directory to a path that has no spaces (for example C:\) , and then edit the
configuration files and run the scripts from this <solrUtility> directory.
Cloud mode implementation steps
1. On the “integration machine”:
a. Extract solr-6.6.0.zip/tgz to solr-integration-utility-16.4.0. See

“Installing Solr server” on page 288.
b. Set up Zookeeper ensemble. See “Setting up Zookeeper ensemble”
on page 289.
c. Edit conf.properties and setPropertiesCloud.cmd in solr-
integration-utility-16.4.0. See “Editing Solr properties” on page 289.
Note: Do not edit SOLRHOST and SOLRPORT in setPropertiesCloud.

cmd yet.
d. As an administrator, open a command prompt from the <solrUtility>
\setupSolrCloud directory and run creatCloudConfigs.cmd followed by
uploadZookeeperConfigs.cmd.
2. On each “node machine”:
a. Install Solr server. See “Installing Solr server” on page 288.

b. Run the solr start command to start the Solr node and add it to the
cluster. See “Adding Solr nodes to the cluster” on page 290.
3. In a web browser, go to http://<solrHost>:<solrPort>/solr and check the

cloud tab. Check that there are sufficient number of Solr nodes running before
creating cores/collections.
4. On the “integration machine”:
a. Edit SOLRHOST and SOLRPORT in setPropertiesCloud.cmd. “Editing Solr

properties” on page 289.
b. As an administrator, open a command prompt from the <solrUtility>
\setupSolrCloud directory and run the command createCollections.
cmd followed by runinitialCloudimport.cmd.
c. Enable scheduling. See “Enabling scheduling” on page 290.
d. Edit the properties for each service gateway application. See “Editing
service gateway properties” on page 292.
e. Restart the service gateway applications.
f. Optional Enable security. See “Enabling security (basic authentication)”
on page 293 or “Enabling security (Zookeeper authentication)”
on page 295.

Terminology
• Collection - A complete logical index in a SolrCloud cluster. A collection may
have multiple Solr cores in multiple Solr nodes.
• Shard - A logical piece of a collection containing a subset of the documents in the
collection. Every document in a collection is contained in one shard only.
• Replica - One copy of a shard. Each replica exists within Solr as a core.
• Leader - All write requests are redirected to the leader (per shard) to maintain
data consistency.
Installing Solr server

Solr server is not included in the Exstream setup or on My Support, so you must
download the package from archive.apache.org.
To install Solr server on Windows
1. On each machine (Solr node), download solr-6.6.0.zip from http://

archive.apache.org/dist/lucene/solr/6.6.0/.
2. Extract solr-6.6.0.zip to any directory.
To install Solr server on Linux
1. On each machine (Solr node), download solr-6.6.0.tgz from http://

archive.apache.org/dist/lucene/solr/6.6.0/.
2. Extract solr-6.6.0.tgz to any directory.
The Solr server home directory solr-6.6.0 is referred to as solrHome in the

following sections.
When the installation is done you must copy the following jar files to solrHome\
dist\solrj-lib on each machine:
• All files in solr-integration-utility-16.4.0\jdbc-lib

• All files in solr-integration-utility-16.4.0\transform\lib
Solr runtimefor Solr integration utility

In Cloud mode you must also download and extract solr-6.6.0.zip/tgz on
the machine where the actual Solr integration is done. This Solr runtime is used
only for creating cores and uploading zookeeper configurations, and should not
be started in Cloud mode as it is used only for internal purpose. We recommend
you to extract solr-6.6.0.zip/tgz to the solr-integration-utility-16.
4.0 directory.
Note: In Windows you must copy the solr-integration-utility-16.

4.0 directory to a path that has no spaces (for example C:\).

Setting up Zookeeper ensemble

Before integrating Solr and Exstream platform you must set up Zookeeper ensemble
in SolrCloud mode. Any Zookeeper ensemble can be used since a new znode will be
created for Solr usage. See https://lucene.apache.org/solr/guide/6_6/setting-up-an-
external-zookeeper-ensemble.html for information about how to set up a Zookeeper
ensemble.
Editing Solr properties

To make the integration work as expected you must edit the files conf.properties
and setPropertiesCloud.cmd.
• conf.properties
Path: <solrUtility>\scaffold\conf
Verify that the multitenantrepository.path property is pointing to the
correct multitenantrepository.xml.
Example 28-9: multitenantrepository.path

multitenantrepository.path = C:\\ManagementGateway\\16.4.0\
\root\\securityprofiles\\multitenantrepository.xml
• setPropertiesCloud.cmd
Path: <solrUtility>\setupSolrCloud
Edit the following properties
• SOLR_DIR: The directory for the extracted internal solr-6.6.0.zip/tgz (see
“Installing Solr server” on page 288).
• MGW_APPS_DIR: The management gateway application path.
• SOLRHOST: The Solr host of any of the Solr nodes in the cloud.
• SOLRPORT: The Solr port of any of the Solr nodes in the cloud.
• ZOOKEEPERHOSTS: List of Zookeeper hosts configured in Zookeeper ensemble
(see “Setting up Zookeeper ensemble” on page 289).
• ZOOKEEPERCHROOT: Unique znode for SolrCluster. Can be any value with
preceding forward slash, for example /solr.
• NUMBEROFSHARDS: Number of shards to be created.
• NUMBEROFREPLICA: Number of replica to be created per shard.
• MAXSHARDSPERNODE: Maximum number of replica per node.
Example 28-10: Solr properties

SET CURRENT_DIR=%CD%
SET OPENTEXT_DIR=C:\Program Files\OpenText

SET SOLR_DIR=C:\solr-integration-utility-16.4.0\solr-6.6.0
SET MGW_APPS_DIR=C:\ManagementGateway\16.4.0\root
\applications
SET SOLR_SERVER_DIR=%SOLR_DIR%\server
SET ZOOKEEPERHOSTS=localhost:2181,localhost:2182,localhost:
2183
SET ZOOKEEPERCHROOT=/solr
SET ZKHOSTSOLRPATH=%ZOOKEEPERHOSTS%%ZOOKEEPERCHROOT%
SET SOLRHOST=localhost
SET SOLRPORT=8984
SET NUMBEROFSHARDS=2
SET NUMBEROFREPLICA=2
SET MAXSHARDSPERNODE=2
Adding Solr nodes to the cluster

On each machine you must run the following command as an administrator to start
the Solr node and add it to the cluster:
solr start -c -z "<zookeeperHostList><znode>" -s "<solrHome>\server" -p

<port>
For example:
solr start -c -z "localhost:2182,localhost:2183,localhost:2184/solr"

-s "C:\solrNode\solr-6.6.0\server" -p 8983
This command must be run from <solrHome>\bin on each machine.
Note: <solrHome> is the solr-6.6.0 directory where solr-6.6.0.zip/tgz is

extracted.
Enabling scheduling
Scheduling is used for delta import of newly created resources and to remove
deleted resources from the Solr index. It is also used to remove expired logs and
collect documents from the Solr index.
To enable scheduling
1. Edit solr.scheduler.properties. See Solr scheduler properties on page 291.

2. As an administrator, open a command prompt from the <solrUtility>
\scheduler directory and create scheduler services:
• To create a scheduler service for all tenants, run the following command:
solrindexer create -all (Windows) or sh solrindexer.sh create
-all (Linux).
• To create a scheduler service for a specific tenant, run the following
command: solrindexer create -tenant <tenantGuid> (Windows) or sh
solrindexer.sh create -tenant <tenantGuid> (Linux).

3. In Windows services, verify that there is a service solr_<GUID>_indexer and

that this service is running.
To test the scheduler service
1. In WorkShop, upload some text resources for testing.
2. After a couple of minutes, test if content search works.
3. Delete the uploaded test resources in WorkShop.
4. In a web browser, go to http://localhost:<port>/solr and check if the

index is removed from Solr (wait a couple of minutes before checking).
To disable scheduling
1. Stop the services to disable.
2. Delete the scheduler services:
• To delete all services, run the following command: solrindexer delete

-all (Windows) or sh solrindexer.sh delete -all (Linux).
• To delete a service for a specific tenant, run the following command:

solrindexer delete -tenant <tenantGuid> (Windows) or sh
solrindexer.sh delete -tenant <tenantGuid> (Linux).
Solr scheduler properties
solr.scheduler.properties is located in the following directory:
<solrUtility>\scaffold\conf

• solr.enable: true.
• solr.cloudmode: true.
• solr.host: The Solr host of any of the Solr nodes in the cloud.
• solr.port: The Solr port of any of the Solr nodes in the cloud.
• Scheduler and delete scheduler properties: Proper time interval (milliseconds).
Example 28-11: Solr scheduler properties

#solr boolean properties
solr.enabled=true
solr.cloudmode=true
#solr properties
solr.host=localhost
solr.port=8983
...
#solr cloud properties
...

#solr scheduler properties

solr.resources.deltaimport.interval=60000
solr.logs.deltaimport.interval=60000
solr.collect.deltaimport.interval=60000
#solr delete scheduler properties

solr.resources.delete.interval=60000
solr.logs.deleteexpired.interval=86400000
solr.collect.deleteexpired.interval=
Scheduler logs
• Scheduler logs on Windows
solr_<GUID>.log and stdout_<GUID>.txt are available in the following
directory:
<solrUtility>\scheduler\log
• Scheduler logs on Linux
solr_<GUID>.out is available in /tmp.
Editing service gateway properties

To make the integration work as expected you must edit the file
solr_configuration-securityprofile.xml in the following directory for each
service gateway:
<mgwRoot>\applications\<appName>\wd\securityprofiles
Edit the following element and attribute values:

• url: The Solr host of any of the Solr nodes in the cloud.
• port: The Solr port of any of the Solr nodes in the cloud.
• solr_isenabled: true.
• solr_iscloudmode: true.
• solr_zkhosts: List of Zookeeper hosts configured in Zookeeper ensemble. Same
as ZOOKEEPERCHROOT in setPropertiesCloud.cmd.
• solr_zkchroot: Unique znode for SolrCluster. Same as ZOOKEEPERCHROOT in
setPropertiesCloud.cmd.
Example 28-12: Element and attribute values
...
<configuration>
<ws xmlns="http://schemas.streamserve.com/...">
<url>localhost</url>
<port>8984</port>

<security type="http://schemas.streamserve.com/...">
...
</security>
<properties>
<property id="solr_isenabled">true</property>
<property id="solr_iscloudmode">true</property>
<property id="solr_zkhosts">localhost:2181,localhost:
2182,localhost:2183</property>
<property id="solr_zkchroot">/solr</property>
</properties>
</ws>
</configuration>
...
Enabling security (basic authentication)

To enable security
1. Set SOLRUSERNAME and SOLRPASSWORD in setPropertiesCloud.cmd. See Setting


\setupSolrCloud directory and run the command secureSolrCloud.cmd
3. Uncomment SOLR_AUTH_TYPE and SOLR_AUTHENTICATION_OPTS in solr.

in.cmd and specify the proper username and password. See Setting username
and password on page 293.
4. Edit solr.username and solr.password in solr.scheduler.properties (see

Setting username and password on page 285) and restart the scheduler services:
• Windows
• Linux
create.

on page 293.

Specify the proper SOLRUSERNAME and SOLRPASSWORD.

SET SOLRUSERNAME=mySolrUser
SET SOLRPASSWORD=mySolrPwd
• solr.in.cmd
Path: <solrHome>\bin for the extracted internal solr-6.6.0.zip/tgz (see
“Installing Solr server” on page 288).
Uncomment the SOLR_AUTH_TYPE and SOLR_AUTHENTICATION_OPTS properties
and specify the proper username and password.
set SOLR_AUTH_TYPE=basic
set SOLR_AUTHENTICATION_OPTS="-
Dbasicauth=mySolrUser:mySolrPwd"
• solr.username: Proper username.
• solr.password: Proper password.
solr.username=mySolrUser
solr.password=mySolrPwd
...
<authenticationprofile type="..." name=".../solr-auth/1.0"
tenantID="...">
<configuration>
<name>mySolrUser</name>
<password>mySolrPwd</password>
</simple>
</configuration>

Enabling security (Zookeeper authentication)

Use Zookeeper authentication only if zookeeper ensemble is shared and used by
clients other than our solr cluster.
To enable security
1. Set ZKUSERNAME and ZKPASSWORD in setPropertiesCloud.cmd. See Setting

2. Uncomment the block below Settings for ZK ACL in zkcli.bat and specify
the proper DzkDigestUsername and DzkDigestPassword . See Setting
\setupSolrCloud directory and run uploadZookeeperConfigsSecure.cmd
4. Set solr.zkdigest.username and solr.zkdigest.password in solr.

scheduler.properties (see Setting username and password on page 293) and
restart the scheduler services:
• Windows
• Linux
create.

on page 293.

Specify the proper ZKUSERNAME and ZKPASSWORD.

SET ZKUSERNAME=admin-user
SET ZKPASSWORD=adminPassword
• zkcli.bat
Path: <solrHome>\server\scripts\cloud-scripts for the extracted internal
solr-6.6.0.zip/tgz (see “Installing Solr server” on page 288).
Uncomment the block below Settings for ZK ACL and specify the proper
DzkDigestUsername and DzkDigestPassword.


REM Settings for ZK ACL
set SOLR_ZK_CREDS_AND_ACLS=-
DzkACLProvider=org.apache.solr.common.cloud.VMParamsAllAndRe
adonlyDigestZkACLProvider ^
-
DzkCredentialsProvider=org.apache.solr.common.cloud.VMParams
SingleSetCredentialsDigestZkCredentialsProvider ^
-DzkDigestUsername=admin-user -
DzkDigestPassword=adminPassword ^
• solr.zkdigest.username: Proper username.
• solr.zkdigest.password: Proper password.

solr.zkdigest.username=admin-user
solr.zkdigest.password=adminPassword

...
<authenticationprofile type="..." name=".../solr-zkdigest/
1.0" tenantID="...">
<configuration>
<name>admin-user</name>
<password>adminPassword</password>
</simple>
</configuration>

28.3. Updating Collect cores after meta model changes
28.3 Updating Collect cores after meta model

changes
If the meta model has been changed after creating the Collect cores you must run the
updateCollectCores.cmd (Windows) or updateCollectCores.sh (Linux) script as
an administrator. These scripts are located in the following directory:
<solrUtility>\setupSolr
To update the Collect cores
1. Stop the service gateways.

\setupSolr directory and run the command updateCollectCores.cmd or
updateCollectCores.sh.
3. Start the service gateways.

Chapter 29
Additional Control configuration
No additional configuration is required to be able to run Control, but will enhance

the functionality.
Enabling application logs in Control

To be able to view log information for the applications in Control, you must copy a
LogDB XML file and enable database logging for the applications.
Note: It is only possible to display logs for applications in domains that are
linked to the log database.
To enable application logs in Control
1. Copy the file LogDB-{GUID}-securityprofile.xml located in <mgwRoot>

\applications\<ServiceGateway>\wd\securityprofiles\
2. Add the copied file to the folder <mgwRoot>\securityprofiles\
3. In Control Center, make sure the applications have database logging enabled.
Enabling link to Supervisor in Control

You can add a link to a Supervisor application in the Application Switcher in
Control. This is done by editing the Control configuration file, configuration.
json, located in the following directory:
<portalRoot>\<webAppName>\config
Example 29-1: configuration.json for Control

{
"supervisor": {
"url": "https://mytomcathost:8443/supervisor",
"tenant": "cce",
"domain": "Testdomain"
},
}
Supervisor keys
"supervisor": {
"url": "https://mytomcathost:8443/supervisor",
"tenant": "cce",
"domain": "Testdomain"
}

Chapter 29 Additional Control configuration
• url - Specify the URL to the Supervisor on the format
http://<host>:<port>/<supervisor>
Where <host> is the host name or IP adress of the computer that
runs the Java application server, <port> is the port the Java
application server listens to, and <supervisor> is the Supervisor
application name.
• tenant - Specify the name of the tenant the Supervisor is installed in.
• domain - Specify the name of the domain the Supervisor is installed on.
Note: The Supervisor you specify here is the Supervisor the Control user will
access when switching to Supervisor in the Application Switcher in Control,
regardless of which tenant or domain is displayed in Control.
Configuring the management gateway redirect timeout

When accessing Control, you connect to a specific management gateway and a
specific tenant. However, in the tenant you connect to, multiple management
gateways are used if the applications in the tenant are installed on different hosts.
When you interact with an application that is connected to another management
gateway than the one you connected Control to, a redirect is sent between the two
management gateways. By default, this redirect is timed out after ten minutes,
which is sufficient for starting and stopping applications. However, if you deploy
Communications Builder Projects to a Communications Server application that is
connected to the other management gateway, the redirect timeout may need to be
increased.
To increase the redirect timeout:
\managament
2. Locate the element <redirecttimeout value="600000"/> and increase the

value for the redirect timeout (in milliseconds).
Note: This must be done on all management gateways in your environment.

Part 6
Maintaining the repositories
Chapter 30
About maintaining Exstream repositories
Standard maintenance tasks

You maintain the Exstream repositories using standard maintenance procedures
provided by the database vendor. For recommended maintenance activities,
including error handling and performance improvement strategies, see the user
documentation from the vendor.
Exstream maintenance tasks

Running the maintenance tasks may affect database performance.
Important
This chapter contains some recommendations regarding setting up and
scheduling the maintenance tasks. These recommendations should be
considered as starting points for trying out the most optimal settings for
your specific job setup and environment.
Tuning of maintenance tasks is a continuous assignment. You must
monitor the Exstream repositories to ensure that the tasks are correctly
scheduled and that the database does not grow over time.
You should always schedule the maintenance tasks in a way that ensures
minimum impact on any other database activities.

Chapter 31
Deleting expired content
This section describes how to delete expired top jobs, queue items, resources,
Document Broker documents, stored Messages, log messages, and temporary data
from the repositories with the Exstream Task Scheduler.
Content expiry times

Content in the tracking repository, Message storage, and queue repository is expired
according to settings in Communications Builder. You can also manually expire this
content by using Task Scheduler.
Content in the Document Broker repository must be manually expired with Task
Scheduler, a process_and_delete PPQ, or a delete PPQ before it can be deleted.
Temporary data in the temporary data repository is automatically expired and no

manual configuration is required. You can also manually expire this content by
using Task Scheduler.
Recommended Communications Builder platform settings

• To delete successful jobs, the deletion process must be allowed to delete
successful jobs (Delete successful jobs is enabled in the Configure Platform
dialog box). We recommend a short expiry time for successfully processed jobs.
Keep the number of top jobs marked for deletion to a minimum.
• To delete failed jobs, the job deletion process must be allowed to delete failed
jobs (Delete failed jobs is enabled in the Configure Platform dialog box).
Task scheduler deletion and expiry events

Task Scheduler includes the following tasks for expiring and deleting content:
For deleting tracker jobs from the tracking repository.
• Expire contents
For expiring the following types the content:
• Queue items from the queue repository.
• Messages from the Message repository.
• Resources from the common asset service (which are stored in the tenant
repository), which includes resources created with the Resource filter or the
Resource output connector.
• Document Broker documents from a Document Broker repository.

Chapter 31 Deleting expired content
• Messages from the logging repository.

• Temporary data from the temporary data repository.
• Delete expired contents
For deleting expired content.
31.1 Recommendations for scheduling the deletion

tasks
We recommend that you schedule the Delete expired tracking information and the
Delete expired contents tasks in the following way:
• Primarily, you should run these tasks at a time period when the Communications
Server applications are idle or the job throughput is low. For example, after
scheduled batch jobs or when the average CPU usage for the database falls below
a specified value and remains below this level for a specified time period. You
must make sure that the available time period is longer than the time interval
required to complete the deletion after a peak load.
• If the available time periods are too short or if the workload is continuous, you
should start the deletion tasks at an available time period and then schedule
continuous deletion with a high frequency.
• Microsoft SQL Server - If a large number of jobs are deleted in each deletion,
any defragmentation or re-indexing should run after the deletion tasks in order
to avoid index fragmentation. See “Running index maintenance (Microsoft SQL
Server)“ on page 309 or “Rebuilding or coalescing indexes (Oracle Database)“
on page 313.
Note: For optimal performance, you should consider when the content is
expired (i.e. based on the Communications Builder settings or by Task
Scheduler) when scheduling the deletion tasks.
31.2 Scheduling a Task Scheduler to delete or expire

content
When using Task Scheduler applications, you must set up separate tasks for deleting
expired tracking information, deleting expired contents, and expiring contents. You
must also use one task for each repository that you want to delete or expire contents
from. To ensure the task runs even if the Task Scheduler goes down, you can add
several Task Schedulers.
The Expired contents task requires an XML file with the DBQ to select the items that
you want to expire, for example the Messages, Document Broker documents, and/or
queue items. You add the path the XML file in the Task Scheduler. For an example
of a DBQ, see “DBQ example” on page 308.

31.2. Scheduling a Task Scheduler to delete or expire content
To schedule a Task Scheduler to delete or expire content
1. In Control Center, right-click the domain and select New Application.
2. On the Application type list, click TaskScheduler and configure the settings for
the application. Note that you cannot use the name Task Scheduler if you run
the application on a Windows® host.
3. Click OK.
4. In the Configuration dialog box, select the (Item list) field and click the button
to the right of the field.
5. In the Service Configuration dialog box, add a task:
• Delete expired contents

• Expire contents
6. Enter the task settings:
• Name – (Mandatory) The name of the task.

• Description – (Optional) A description of the task.
• Schedule – (Mandatory) The schedule at which the task is run.
Additional settings for Delete expired contents tasks

• Repository – (Mandatory) The repository to delete the expired content from.
• Runtime in minutes – (Optional) The approximate maximum runtime in
minutes for the delete event to run. The delete event attempts to delete as much
content as possible during this time. The event stops after this time or when all
the content is deleted. Do not use decimals in this field.
Additional settings for Expire contents tasks

• Repository – (Mandatory) The repository to expire the content in.
• Query – (Mandatory) The file containing the DBQ to select the contents to expire.

Chapter 31 Deleting expired content
31.3 DBQ example

This DBQ selects all content (for example, Messages, Document Broker documents,
queue items, log messages) with a processing state of 5 (i.e. processed or
released).
<?xml version="1.0"?>
<docabs xmlns="http://schemas.streamserve.com/uid/resource/
documentabstraction/1.0">
<docab>
<command type="http://schemas.streamserve.com/uid/configuration/
documentabstractionquery/1.0">
<configuration>
<daq xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:strs="http://schemas.streamserve.com/public/1.0" xmlns="http://
schemas.streamserve.com/uid/resource/documentabstractionquery/1.0">
<query>
<filter>
<filterClause>
<conditions>

<condition>
<strs:id>
<strs:value>6B84E18B-F042-350C-
E040-007F0200026D</strs:value>
</strs:id>
<strs:values>
<strs:value>5</strs:value>
</strs:values>
<operatorValue>==</operatorValue>
</condition>
</conditions>
</filterClause>
</filter>
</query>
</daq>
</configuration>
</command>
</docab>
</docabs>

Chapter 32
Running index maintenance (Microsoft SQL Server)
When data is modified in indexed table columns, indexes become fragmented and
the speed of the data retrieval operations deteriorates. To preserve performance, you
should set up an index maintenance plan for the Exstream repositories.
This documentation describes two ways of running index maintenance:
• Running index maintenance via SQL Server

You can use the index maintenance functionality available for SQL Server when
setting up your index maintenance plan. The index maintenance plan must
include the following:
• Update of repository statistics.

• Defragmentation and rebuilding of indexes.
• Re-optimization of queries by recompiling the underlying stored procedures.
OpenText provides an index maintenance package which you can use when
setting up index maintenance via Microsoft SQL Server Agent. For more
information, see “Running index maintenance via SQL Server Agent (Microsoft
SQL Server)” on page 310.
We recommend that you always run index maintenance via SQL Server in
production environments.
• Running index maintenance via a Task Scheduler
You can use an Exstream Task Scheduler to run index maintenance on a
repository. For example, if SQL Server Agent is not available. For more
information, see “Scheduling index maintenance or coalescing via task
scheduler“ on page 319.
32.1 Index maintenance recommendations (Microsoft

SQL Server)
Maintenance plan recommendations
• When setting up the index maintenance plan, you must consider the overall
amount and frequency of data inserts and deletes.
The required index maintenance depends on the type of scenario you are
running. For example, a batch scenario (where multiple input files are sent to
the Communications Server applications in batches) needs different
maintenance compared to an on-demand scenario with ReTouch (where
multiple web service requests quickly populates previously empty tables).

Chapter 32 Running index maintenance (Microsoft SQL Server)
The type of the repository also affects the index maintenance. For example,
the data in the queue repository is generally highly volatile, which means
frequently modified tables with fragmentation as a result.
Scheduling recommendations
Running index maintenance charges the database and may affect the database
performance. We therefore recommend that you schedule the index
maintenance in the following way:
• When the Communications Server application is idle or when the job
throughput is low. For example, after scheduled batch jobs or when the
average CPU usage for the database falls below a specified value and
remains below this level for a specified time period.
• If the workload is continuous, without any periods of low throughput, the
indexes must be rebuilt online (that is, while other processes are accessing a
table).
• After deletion of expired jobs. In general, if you use a continuous job
deletion, you can run the index maintenance less frequently than the job
deletion (but still when the database activity on the repository is as low as
possible).
32.2 Running index maintenance via SQL Server

Agent (Microsoft SQL Server)
Via SQL Server Agent, you can run an OpenText index maintenance package on any
of the Exstream repositories.
The index maintenance package (Maintplan.bat) is located in:
<Base directory>\<Version>\root\config\database\<Version>\sqlserver\
maintenance
Where <Base directory> is the path specified for Exstream Projects during the
Index maintenance process

The steps below are included in the index maintenance package. The
maintenance plan runs daily at a time that you specify when running the batch
file. For each step, there are three retries (with an interval of one minute).
1. Update statistics - The statistics for any modified table columns is updated.
2. Rebuild indexes - The indexes are defragmented and rebuilt. Note that
rebuilding indexes online may not be supported on all SQL Server editions.
3. Drop and create the index - The indexes are dropped and recreated.
4. Recompile all stored procedures - Queries (based on stored procedures) are
optimized only when they are compiled. As a repository changes, for
example when an index is rebuilt, the compiled stored procedures lose
efficiency. By recompiling all stored procedures based on the updated
statistics, the queries are re-optimized.

32.2. Running index maintenance via SQL Server Agent (Microsoft SQL Server)
Prerequisites
• Make sure no other index maintenance runs on the repository.
• SQL Server Agent must be available and running.
• The sqlcmd utility must be available.
To set up SQL Server Agent to run index maintenance
1. Double-click Maintplan.bat to run the file.
2. When prompted for, enter the required parameters. For example, sysadmin,
dbname, scheduled time, etc.
Note: When you are prompted to enter the path and name to the
Microsoft SQL Server Query File, you must enter the path and name to
Maintplan.sql.
Post requisites
• When the maintenance plan is triggered, you can check the status in the log files
to verify that the maintenance task works as expected. For example, in the C:
\maintstep.log file on the computer where SQL Server runs.

Chapter 33
Rebuilding or coalescing indexes (Oracle Database)
When data is modified in indexed table columns, indexes become fragmented and
the speed of the data retrieval operations deteriorates. To preserve performance, you
should coalesce or rebuild your indexes.
In general, we recommend that you coalesce your indexes. For example, databases
that continuously grows and shrink may have large holes in indexes after delete has
run.
There are two ways to coalesce indexes:
• By using the coalesce_indexes procedure. See “Coalescing indexes with

coalesce_indexes procedure (Oracle Database)” on page 313.
• By using a Task Scheduler application. Running index maintenance via Task
Scheduler is only suitable in development and smaller testing environments. See
“Scheduling index maintenance or coalescing via task scheduler“ on page 319.
However, in certain scenarios, you could still benefit from rebuilding indexes. For
example, if rows have been removed from a previously large table to which no new
rows will be added.
33.1 Coalescing indexes with coalesce_indexes

procedure (Oracle Database)
We then recommend that you coalesce your indexes by using the
coalesce_indexes procedure.
coalesce_indexes
The procedure coalesces all Exstream indexes.
The following parameters are available:
• v_maxrunhours – The maximum hours to run (the time span within which a new
index rebuild loop iteration can be started). If not set, the time span is one year
(24 x 365).
• v_indexname_regexp – A POSIX regular expression string (case-insensitive) to
coalesce only a subset of indexes. For example, to coalesce all indexes starting
with letter A-H, you can use '^[A-H].*'$'. If not set, all indexes are coalesced.
• v_parallel_mb_breakpoint – An index size breakpoint (MB). Indexes larger
than this value are coalesced in parallel. If not set, indexes are not coalesced in
parallel.

Chapter 33 Rebuilding or coalescing indexes (Oracle Database)
• v_sort_area_size_mb – The sort area size (MB) for a session (that is, the
maximum amount of memory Oracle will use for a sort). If not set, default Oracle
initialization parameter settings are used.
Example 33-1: Coalescing indexes according to specification
In this example, the indexes for all search tables (that is, tables that begin
with "CX") in the repository archive are coalesced in the following way:
• Use parallel mode for all indexes larger than 50 MB.

• Break after first index done after 12 hours.
• Use custom sort_area_size of 100 MB per parallel thread.
BEGIN
maintenance.coalesce_indexes (
v_indexname_regexp=>'META_.*',
v_parallel_mb_breakpoint=>50,
v_maxrunhours=>12,
v_sort_area_size_mb=>100
);
END;
/
Example 33-2: Coalescing indexes using default options
In this example, the indexes for all tables in the repository are coalesced
using the default options:
BEGIN
maintenance.coalesce_indexes ();
END;
/
33.2 Rebuilding indexes (Oracle Database)

In general, we recommend coalescing indexes (see “Coalescing indexes with
coalesce_indexes procedure (Oracle Database)” on page 313). However, in certain
scenarios, you could still benefit from rebuilding your indexes. For example, if rows
have been removed from a previously large table to which no new rows will be
added. To rebuild indexes, you can use the rebuild_indexes procedure.
For performance reasons, we do not recommend that you rebuild an index when the
Exstream applications access the table. It is supported nevertheless, but only as long
as no database operation uses the index in question, or if the index rebuild
command is used together with the online option. Rebuilding indexes online may
only be available in some editions of Oracle Database. For more information
regarding index rebuild options, see the Oracle user documentation.

33.2. Rebuilding indexes (Oracle Database)
When rebuilding indexes, you must make sure there is sufficient free space in the
destination tablespaces. See “Ensuring sufficient free space (Oracle Database)”
on page 316.
• rebuild_indexes
The procedure rebuilds all Exstream indexes.
• v_maxrunhours – The maximum hours to run (the time span within which a
new index rebuild loop iteration can be started). If not set, the time span is
one year (24 x 365).
• v_indexname_regexp – A POSIX regular expression string (case-insensitive)
to rebuild only a subset of indexes. For example, to rebuild all indexes
starting with letter A-H, you can use '^[A-H].*'$'. If not set, all indexes are
rebuilt.
• v_tablespace_dest – A new tablespace to which the indexes are moved at
the rebuild. If not set, the indexes remains in the current tablespace.
• v_parallel_mb_breakpoint – An index size breakpoint (MB). Indexes larger
than this value are rebuilt in parallel. If not set, indexes are not rebuilt in
parallel.
• v_online – A parameter (true or false) to run rebuild commands with the
ONLINE clause. If not set, true is used.
• v_sort_area_size_mb – The sort area size (MB) for a session (that is, the
maximum amount of memory Oracle will use for a sort). If not set, default
Oracle initialization parameter settings are used.
Prerequisites
• Direct privilege CREATE TABLE is required for package owner.
Example 33-3: Rebuilding indexes according to specification
In this example, the indexes for all search tables (that is, tables that begin
with "CX") in the repository are rebuilt in the following way:
• Rebuild to the same tablespace (that is, v_tablespace_dest not set).
• Use offline mode (since this is faster than the online mode).
• Use parallel mode for all indexes larger than 50 MB.
• Break after first index done after 12 hours.
• Use custom sort_area_size of 100 MB per parallel thread.
Note that parallel or online rebuild may only be available in some editions of
Oracle Database.
BEGIN
maintenance.rebuild_indexes (

Chapter 33 Rebuilding or coalescing indexes (Oracle Database)
v_online=>false,
v_indexname_regexp=>'META_.*',
v_parallel_mb_breakpoint=>50,
v_maxrunhours=>12,
v_sort_area_size_mb=>100
);
END;
/
Example 33-4: Rebuilding indexes using default options
In this example, the indexes for all tables in the repository are rebuilt using
the default options:
BEGIN
maintenance.rebuild_indexes ();
END;
/
33.2.1 Ensuring sufficient free space (Oracle Database)

When rebuilding indexes, you must make sure there is sufficient free space in the
destination tablespaces. The sufficient free space must be at least as much as the
largest index.
You can run the SQL query in this section to check free space. You must run the
query as a DBA user, for example as SYSTEM.
Example 33-5: SQL to check free space
When running the query, you must make sure that smartfree_mb (free
space plus remaining auto extended space) is larger than maxindex_mb (size
of largest index in tablespace).
SELECT
tablespace_name tablespace,
ROUND(SUM(filesize)/1024/1024) filesize_mb,
ROUND((SUM(filesize)-SUM(filefree))/1024/1024) used_mb,
ROUND(SUM(autoextend_max)/1024/1024) autoextend_max_mb,
ROUND((SUM(filefree)+SUM(autoextend_max)-SUM(filesize))/
1024/
1024)
smartfree_mb,
ROUND(MAX(maxindexbytes)/1024/1024) maxindex_mb
FROM
(SELECT
tablespace_name,
0 filesize,
SUM(bytes) filefree,

33.2. Rebuilding indexes (Oracle Database)
0 autoextend_max,
0 maxindexbytes
FROM
dba_free_space
GROUP BY
tablespace_name
UNION ALL SELECT
tablespace_name,
SUM(bytes) filesize,
0 filefree,
sum(greatest(bytes,maxbytes)) autoextend_max,
0 maxindexbytes
FROM
dba_data_files
GROUP BY
tablespace_name
UNION ALL SELECT
tablespace_name,
0 filesize,
0 filefree,
0 autoextend_max,
MAX(bytes) maxindexbytes
FROM
dba_segments
WHERE
segment_type = 'INDEX'
GROUP BY
tablespace_name)
GROUP BY tablespace_name
ORDER BY tablespace_name;

Chapter 34
Scheduling index maintenance or coalescing via
task scheduler
Via a task scheduler, you can run index maintenance (SQL Server) or coalesce
indexes (Oracle) on the Exstream repositories.
• Index maintenance process on SQL Server
The index maintenance process includes rebuilding indexes, updating statistics,
and recompiling stored procedures.
• Index maintenance process on Oracle
The index maintenance process coalesces the indexes.
Each task scheduler application can only preform index maintenance on one
repository (for example, queue or message). A task scheduler in one domain can run
database maintenance on a repository in another domain (i.e. the repository does not
have to be connected to the domain where the task scheduler application resides).
To ensure that indexes are maintained even if the task scheduler application goes
down, you can add several applications.
Prerequisites
• Make sure no other unplanned index maintenance runs on the repository.
• On SQL Server, the executing user must have permissions at least corresponding
to the db_owner database role for the repository aimed for the maintenance.
• On Oracle, the executing user must be the schema owner.
To schedule a Task Scheduler to run index maintenance
1. In Control Center, right-click the domain and select New Application.

2. In the New Application dialog box, from the Application host drop-down list,
select the host.
3. Configure the application properties for the new Task Scheduler. Note that you
cannot use the name Task Scheduler if you run the application on a Windows
host.
4. Click OK.
5. In the Configuration dialog box, select the (Item list) field and click the button
to the right of the field.
6. In the Service Configuration dialog box, add and configure the required task:
Run database maintenance – Select to perform database maintenance on a
specified repository according to the specified schedule.

Chapter 34 Scheduling index maintenance or coalescing via task scheduler
Connection profile – The connection profile to use. The connection profile

describes which repository to connect to and as which user you will connect.
The default profile connects to the repository in the Task Scheduler domain.
To create a connection profile
1. Open maintenance.xml, located in:
• Windows
<Base directory>\<Version>\root\applications\<Task Scheduler
name>\wd\securityprofiles
Where <Base directory> is the path specified for Exstream Projects during
the Communications Server installation. For example: C:
\ManagementGateway
• UNIX
<Project location>/applications/<Task Scheduler name>/wd/
securityprofiles
Where <Project location>, which is the Project location specified during
the Communications Server installation. For example: /opt/streamserve/
root
2. Edit the connection information to the database server and which user to
connect as:
• For SQL Server, the user that you assign must have sufficient permissions to
perform database maintenance. See “Connection Settings SQL Server”
on page 320.
• For Oracle, the user that you assign must be the schema owner. See
“Connection settings Oracle” on page 321.
3. Start the Task Scheduler application.

• Connection Settings SQL Server
...
<securityprofiles xmlns="..." owner="...">
<connectionprofile type="..." name="...">
<configuration>
<sql xmlns="...">
<vendor>sqlserver</vendor>
<hoststring>myhost</hoststring>
<port>1433</port>
<dbname>StrsQueue</dbname>
...
</sql>
</configuration>
<authenticationprofile type="..." name="...">
<configuration>

<name>User</name>
<password>MyPassword</password>
</simple>
</configuration>
</securityprofiles>
• Connection settings Oracle
...
<securityprofiles xmlns="..." owner="...">
<connectionprofile type="..." name="...">
<configuration>
<sql xmlns="...">


<vendor>oracle</vendor>
<port>1521</port>
<servicename>StrsQueue</servicename>
<schemaowner>SchemaOwner</schemaowner>
...
...
</sql>
</configuration>
<authenticationprofile type="..." name="...">
<configuration>
<name>User</name>
<password>MyPassword</password>
</simple>
</configuration>
</securityprofiles>
Post requisites
• You can check the Platform log in Control Center to verify that the maintenance
task works as expected.

Chapter 35
Gathering statistics (Oracle Database)
35.1 Gathering sample statistics (Oracle Database)

As a complement to the Oracle automatic statistics gathering, we recommend that
you gather sample statistics for all Exstream schemas every night using the
gather_stats procedure. One sample per schema is sufficient.
You must gather sample statistics when there are rows in the Part and
QStatusReport tables. If the tables are frequently emptied, you can gather statistics
when the tables have a lot of data and then lock the statistics in the whole schema.
To gather statistics again, you must unlock the statistics.
• gather_stats
The procedure gathers optimizer statistics on an Exstream schema in the
following way:
• Gathers statistics for all objects in the schema.

• Gathers histograms (FOR ALL COLUMNS SIZE AUTO).
• Lets Oracle decide when to invalidate dependent cursors via DBMS_STATS.
AUTO_INVALIDATE.
• v_estimate_pct – The sample size (%). If not set, Oracle decides the sample
size via DBMS_STATS.AUTO_SAMPLE_SIZE.
• v_parallel_degree – The degree of parallelism. Set to NULL to use table
default value. Set to 1 to not use parallelism. If not set, Oracle decides the
parallelism via DBMS_STATS.AUTO_DEGREE.
Example 35-1: Gathering statistics according to specification
In this example, the gather sample size is 5%, letting Oracle decide on the
parallelism.
BEGIN
maintenance.gather_stats (
v_estimate_pct=>5
);
END;
/

Chapter 35 Gathering statistics (Oracle Database)
Example 35-2: Gathering statistics using default options
In this example, Oracle decides the sample size and the degree of
parallelism.
BEGIN
maintenance.gather_stats ();
END;
/
Gathering sample statistics - varying data

In general, we recommend that you use the statistics gathering as described in
“Gathering sample statistics (Oracle Database)” on page 323.
However, if the number of rows in the repository varies from zero to several
thousands, and then back to zero again after the delete, you may end up gathering
statistics when the tables are empty. This may result in sub-optimized SQL plans,
especially for small, heavily used tables like QStatusReport and
QStatusReportReady. In this scenario, you can run the gather_growing_stats
procedure instead, which enables you to optimize the gathering of statistics.
• gather_growing_stats
The procedure gathers optimizer statistics on an Exstream schema with growing
tables. Statistics is only gathered for tables that have more rows than in the last
call.
• v_gather_max_rows – The maximum number of rows for the table to be
included when gathering statistics. Set to NULL to run for all tables. If not set,
the table default value is used.
• v_tables_wildcard – If set, only tables that matches the wildcard are
checked.
• v_force_lock_gather – If not set to 0 and statistics is locked, the statistics is
unlocked, gathered, and locked again.
• v_parallel_degree – The degree of parallelism. Set to NULL to use table
default value. Set to 1 to not use parallelism. If not set, Oracle decides the
parallelism via DBMS_STATS.AUTO_DEGREE.
• v_debug – If not set to 0, messages about what is being executed is shown via
DBMS_OUTPUT.
• lock_stats
The procedure locks optimizer statistics for the schema.
• unlock_stats
The procedure unlocks optimizer statistics for the schema.

35.2. Gathering system statistics (Oracle Database)
• delete_stats
The procedure deletes optimizer statistics for the schema.
Example 35-3: Gathering statistics for varying data
In this example, the procedure gather_growing_stats is called every 15 s

when running the Communications Server application. Statistics is gathered
for tables that have more rows than in the last call, but not more rows than
20 000.
-- Show dbms_output from procedures

SET SERVEROUTPUT ON
-- Run this PL/SQL block every 15 s until the batch is done
BEGIN
-- Gather for all tables in schema,
-- only for tables less than 20000 rows
maintenance.gather_growing_stats (
v_gather_max_rows => 20000,
v_tables_wildcard => '%',
v_force_lock_gather => 1,
v_parallel_degree => 1,
v_debug => 1
);
END;
/
-- Lock statistics after the batch is done:
BEGIN
maintenance.lock_stats;
END;
/
35.2 Gathering system statistics (Oracle Database)

We recommend that you gather system statistics on one occasion under normal
system load using DBMS_STATS.GATHER_SYSTEM_STATS. For detailed information,
see the Oracle user documentation.
This section gives an example of how to gather system statistics via DBMS_STATS.
GATHER_SYSTEM_STATS.
Example 35-4: Gathering system statistics
You must change the XX* values before running.
-- 1. Create table to hold stats

BEGIN
-- Create table to hold stats
DBMS_STATS.CREATE_STAT_TABLE (
ownname => 'XXMYOWNER',
stattab => 'XXMYTABLENAME',
tblspace => 'XXMYTABLESPACE');

Chapter 35 Gathering statistics (Oracle Database)
END;
/
-- 2. Export old system stats from dictionary to created
stattable
BEGIN
DBMS_STATS.EXPORT_SYSTEM_STATS (
statown => 'XXMYOWNER',
statid => 'XXMYSTATID_OLD');
END;
/
-- 3. Gather new system stats for one hour under normal
system load
BEGIN
DBMS_STATS.GATHER_SYSTEM_STATS (
gathering_mode => 'INTERVAL',
interval => 60,
statid => 'XXMYSTATID_NEW');
END;
/
-- 4. Import the gathered system stats from stattable to
dictionary
BEGIN
DBMS_STATS.IMPORT_SYSTEM_STATS (
stattab => 'XXMYTABLENAME'
statid => 'XXMYSTATID_NEW');
END;
/

Chapter 36
Troubleshooting performance via EXPLAIN PLAN

(Oracle Database)
Reading or writing data in Oracle Database is done by issuing SQL statements.

When Oracle receives such a statement, a query execution plan is built. The
execution plan defines how Oracle finds or writes data and can be used when
troubleshooting performance issues.
To explore an execution plan, you can use the SQL statement EXPLAIN PLAN.
Exstream uses datatype RAW(16)

In Oracle, Exstream uses datatype RAW(16) for the majority of the GUIDs.
When a RAW column is used in the WHERE clause of a query, the value must also
be RAW. If not, Oracle will not use any index on that column.
The application code uses RAW bind variables, but any SQL statement that is
used to explain the SQL plan must be written correctly. You cannot use string
constants (for example 'my_raw_value') since this would not be the same SQL
statement as the one run by the Exstream applications.
To display an SQL explain plan for datatype RAW

To display the SQL explain plan that Oracle actually uses when a column is of
datatype RAW, you can do one of the following:
• For most correct result – Check the actual SQL statement run by the
application code (for example, by using Oracle Enterprise Manager).
• Put the SQL statement in a PL/SQL block, use a RAW(16) bind variable and
perform an SQL-trace while running the SQL statement, and then format the
trace file and check the plan. For example:
DECLARE
my_raw_value RAW(16):= ' <MYRAWVALUE>'
BEGIN
SELECT * FROM my_table
WHERE my_raw_field = my_raw_value;
END;
/
• Easiest during testing and development phases – Use the CAST function in
your SQL statement. Note that this is only for testing, it is not how it is done
in the application code (where RAW bind variables are used). For example:
SELECT * FROM my_table

WHERE my_raw_field = CAST(my_raw_value AS RAW(16));

Chapter 37
Backing up the repositories
You must make regular backups of your Exstream repositories to protect the
repositories from data loss.
Standard backup activities

You backup the repositories using standard backup procedures provided by the
database vendor. For recommended back up activities, see the user
documentation from the database vendor.
No Exstream backup package

OpenText does not provide a separate backup package for the Exstream
repositories.

Part 7
Installing and applying hotfixes
Chapter 38
About installing and applying hotfixes
This section describes how to install and apply hotfixes on OpenText Exstream.
Installing a hotfix means that files in the Exstream installation folder and the
management gateway base directory are replaced. If the hotfix includes database
changes, you must also apply the hotfix to your Exstream repositories. If the hotfix
includes changes to the web applications, you must deploy the updated Web
application ARchive (WAR) files to the Java application server.
Each hotfix incorporates all previously released bug fixes for the specific Exstream
release. You must install all fixes included in the hotfix package (that is, you cannot
install specific fixes only). All hotfixes for a specific release will be included in the
next service pack for the release.
Each hotfix is identified by the release to which it applies and a build number. When
you refer to a specific hotfix, you should use the release name and the build number.
Hotfixes are distributed by OpenText Customer Support. The support team keeps
track of all hotfixes distributed, and will provide any additional information you
may need to apply the hotfix. For information about the bug fixes related to a hotfix,
see the hotfix documentation.

Chapter 39
Installing a hotfix
This section describes how to install an Exstream hotfix on Windows and UNIX.
Prerequisites
• Read the hotfix documentation for any additional preparations for the specific
hotfix.
• If you have made customizations directly in any Exstream configuration files,
these files might be overwritten when the hotfix is installed. The following
applies:
Windows - To keep customizations, you must make backups of the files and
store them in a place where they cannot be overwritten. When you have installed
the hotfix, you can compare the old files with the new files and manually restore
your customizations.
UNIX - If you use the same management gateway root when you apply the
hotfix, any customizations made to the configuration files are automatically
identified. For each identified customization, a comment is issued and a copy of
the old file is stored. You can then compare the old file with the new file and
manually restore your customizations.
• An encrypted system environment must be decrypted before the hotfix
installation. After the hotfix installation, the Exstream installation can be re-
encrypted again.
Installing a hotfix on Windows

1. Close all Exstream programs and stop all Exstream applications.
2. Open the Hotfix Setup wizard by double-clicking the EXE file. For example,
<Version>_Hotfix_YYYY-MM-DD_Build_nnn.exe, where nnn is the hotfix build
number.
3. Follow the instructions in the wizard.
Installing a hotfix on UNIX

The hotfix setup files are archived in a gzipped file:
Exstream-<Version>.GA.<Build>-<Platform>.tar.gz
To extract the setup files
1. Copy the gzipped file to your directory for Exstream files.
2. From the Exstream directory, extract the gzipped file:

Chapter 39 Installing a hotfix
gunzip < Exstream-<Version>.GA.<Build>-<Platform>.tar.gz | tar xf -
To install the hotfix
1. Stop all Exstream services:

cd Esxtream-<Version>.GA.xxx
./shutdown all
Where xxx is the build number of the previous installation.
2. Optional Copy the.operatorInput file from the previous installation. This file
contains values, specified in the Exstream Setup, that are pre-selected when the
hotfix is installed.
cd Exstream-<Version>.GA.nnn
cp ../Exstream-<Version>.GA.xxx/.operatorInput ./
Where:
• nnn is the hotfix build number.

• xxx is the build number of the previous installation.
3. Install the hotfix:

./setup
4. Start the management gateway:

./launcher management

Chapter 40
Applying a hotfix to the repositories
If a hotfix includes database changes, you must apply the hotfix to the Exstream
repositories.
For the tenant repository, you apply the hotfix with ss_tenantadmin.
For the Tracking, Queue, Message, Document Broker, Statistics, Logging, Temporary
data repositories, you apply the hotfix in one of the following ways:
• Apply the hotfix with Control Center
• Apply the hotfix with the hotfix-repo script
• Apply the hotfix manually
Prerequisites
• Database user name and password
The login details for the appropriate database user must be available:
• On SAP HANA, Oracle, and Postgres, this is the schema owner.
• On SQL Server you use the system administrator.
• Database hotfixes available
The Hotfix Setup has been run, resulting in updated database hotfixes installed
in:
Where <Base directory> is the path specified for Communications Builder
Projects during the Communications Server installation. For example: C:
\ManagementGateway
Where <Project location> is the Project location specified during the
Communications Server installation. For example: /opt/streamserve/root
Preparations
Before applying a hotfix to a repository, OpenText recommends the following:

• Make sure that no other users are connected to the repository. If possible, set the
repository to single user mode.
• Stop all applications accessing the repository.
• For the queue and tracking repositories:
Make sure that all jobs running against the repository are completed.
• Perform a backup of the repository.

Chapter 40 Applying a hotfix to the repositories
• UNIX - You must manually set STRS_JAVA_HOME to a suitable JRE (only if the
Exstream Setup has not been run previously).
40.1 Applying a hotfix to the tenant repository

You use the ss_tenantadmin tool to apply a hotfix to the tenant repository. First you
find the available hotfixes with the list_tenant_repository_hotfix action. Then
you apply the latest available hotfix with the apply_tenant_repository_hotfix
action.
If several tenants share the same tenant repository, you only need to apply the hotfix
to one of the tenants. This will apply the hotfix to the entire repository.
Syntax list_tenant_repository_hotfix
ss_tenantadmin.exe -list_tenant_repository_hotfix -tenantname
<tenant_name> -tenantID <tenant_ID> -mtauser <user_name> -
mtapassword <password> -dbadminusername <user_name> -dbadminpassword
<password>
Syntax apply_tenant_repository_hotfix
ss_tenantadmin.exe -action apply_tenant_repository_hotfix -
tenantname <tenant_name> -tenantID <tenant_ID> -mtauser <user_name> -
mtapassword <password> -dbadminusername <user_name> -dbadminpassword
<password>
Example 40-1: list_tenant_repository_hotfix
This example checks if there is a hotfix available for the tenant repository for
the tenant with the name strs.
Command:
\ss_tenantadmin.exe" -action list_tenant_repository_hotfix
-tenantname strs -mtauser multitenantadmin@strs.role
-mtapassword mtapwd -dbadminusername sa -dbadminpassword
Changeoninstall2000
Example 40-2: apply_tenant_repository_hotfix
This example applies a hotfix to the tenant repository.
Command:
\ss_tenantadmin.exe" -action apply_tenant_repository_hotfix
-tenantname strs -mtauser multitenantadmin@strs.role
-mtapassword mtapwd -dbadminusername sa -dbadminpassword
Changeoninstall2000

40.1. Applying a hotfix to the tenant repository
Parameter descriptions list_tenant_repository_hotfix/

apply_tenant_repository_hotfix
On SAP HANA, Oracle, and Postgres, this is the schema owner.
On SQL Server you use the system administrator.
-env <path_file>
Either the -tenantID or -tenantname is required.
Either the -tenantID or -tenantname is required.
-mgwhost <host>
(OPTIONAL) The management gateway host where the command is run.
-mgwport <host>
(OPTIONAL) The port for the management gateway.
-mgwtimeout <host>
(OPTIONAL) The time the utility waits for a response from the management
gateway. This is specified in milliseconds.
Tip: For information about the default values, see ss_tenantadmin help (-
h).

40.2 Applying a hotfix to the repositories with Control

Center
In Control Center, you can list the repositories, their current schema versions, and
the latest available hotfixes. This gives you an overview of the current statuses and
helps you decide whether the repositories need to be upgraded. If an upgrade is
needed, you can apply the latest available database hotfixes directly in Control
Center.
Note: You cannot use Control Center to apply hotfixes to the multi-tenant
repository or the tenant repositories.
Prerequisites and preparations

• See Prerequisites on page 337 and Preparations on page 337.
To list schema versions and available database hotfixes
1. Open Control Center and connect to the site.

2. Right-click the site node and select Available Database Hotfixes.
3. In the Available Database Hotfixes dialog box:
• Click Get List (if the dialog box is opened for the first time).
• Click Update List (if the dialog box was previously opened).
4. In the Connect dialog box, enter the logon details for the user (see Prerequisites
on page 337).
5. Click OK.
6. In the Available hotfixes area, review the information.
7. Click Close.
To apply a hotfix to a repository
1. In Control Center, right-click the node for the repository, and then select Create
Database.
2. In the Create Database dialog box, in the Operation area, select Apply hotfix.
4. Click Start to apply the latest available database hotfix.
5. In the Connect dialog box, enter the logon details for the user (see Prerequisites
on page 337).
6. Click OK.
7. Optional Click Open Log File to open the full log in the default text editor.

40.3. Applying a hotfix to the repositories with the hotfix-repo script
8. Click Close.
9. Repeat for any other repositories that need to be upgraded.
40.3 Applying a hotfix to the repositories with the

hotfix-repo script
If Control Center is not available, you can list the available hotfixes for a repository
and apply the latest available hotfix by running scripts from a command prompt.
First you list the hotfixes by running the list-hotfix-repo script, and then you
apply the latest available hotfix by running the hotfix-repo script.
The script files reside in the following directories:

• Windows - <Exstream_Installation_directory>\<version>\Server\bin
• UNIX - .../Exstream-<Version>.GA.<build>/<version>/Server/bin/

To list the available database hotfixes
• List the available hotfixes by running the following command:

list-hotfix-repo.bat|list-hotfix-repo.sh -s <Script root> -r
<Repository name> -t <Path to connection file> -u <User name> -p
<Password>
To apply a hotfix to a repository
• Apply the latest available hotfix by running the following command:

hotfix-repo.bat|hotfix-repo.sh -s <Script root> -r <Repository
name> -t <Path to connection file> -u <User name> -p <Password>
Parameters
-s <arg>
Path to the directory with the scripts:
Windows - <Base directory>\<Version>\root\config\database
Where <Base directory> is the path specified for Communications Builder
Projects during the Communications Server installation. For example: C:
\ManagementGateway
UNIX - <Project location>/config/database
Where <Project location> is the Project location specified during the
Communications Server installation. For example: /opt/streamserve/root
-r <arg>
The type of the repository, this must be one of:

• StrsTrackerModel – Tracking repository

• StrsQueueModel – Queue repository
• StrsMessageStoreModel – Message repository
• StrsDocBrokerPlusModel – Document Broker repository
• StrsStatisticsModel – Statistics repository
• StrsDataBaseLogModel – Logging repository
• StrsTempStorageModel – Temporary data repository
• StrsArchive – Collector archive
-t <arg>
Path to the connection profile file:
Windows - <Basedirectory>\<Version>\root\applications\<Service
Gateway>\wd\securityprofiles\<Repository>-<GUID>-securityprofile.
xml
UNIX - <Projectlocation>/applications/<Service Gateway>/wd/
securityprofiles/<Repository>-<GUID>-securityprofile.xml
-u <arg>
User name to access the repository.
On SAP HANA, Oracle, and Postgres, this is the schema owner.
On SQL Server you use the system administrator.
-p <arg>
Password for the user.
Example 40-3: Windows – Applying a database hotfix to the queue

repository
In a command line window, browse to the directory with the script file (path
described above) and run the following command:
hotfix-repo.bat -s "<Base directory>\<Version>\root\config

\database" -r StrsQueueModel -t "Queue-{C7F05A7E-
F10C-484D-8A6F-6AA009DC1375}-securityprofile.xml" -u sa -p
password
Example 40-4: UNIX – Applying a database hotfix to the queue

repository
In a command line window, browse to the directory with the script file (path
described above) and run the following command:
hotfix-repo.sh -s "<Project location>/config/database" -r

StrsQueueModel -t "Queue-{C7F05A7E-

40.4. Applying a hotfix to the repositories manually
F10C-484D-8A6F-6AA009DC1375}-securityprofile.xml" -u sa -p
password
40.4 Applying a hotfix to the repositories manually

OpenText recommends that you apply a hotfix to the Exstream repositories using
Control Center or the hotfix-repo script. However, if this is not possible for some
reason (for example, due to internal company restrictions), you can apply the hotfix
manually as described below.

To apply the hotfix manually
1. Find the model file with the next revision corresponding to your present
database schema version in the following directory:
2. Open the model file and run all the scripts that are referenced inside.
3. Repeat Step 1 and Step 2 for the next model file, and continue until there is no
more model files for your database version.

Chapter 41
Applying a hotfix to the web applications
When you install a hotfix that includes changes to the web applications, the WAR
files in the Exstream installation directory are updated. To apply the hotfix, you
must replace the WAR files on the Java application server.
Prerequisites
• The Hotfix Setup has been run, resulting in updated template WAR files installed
in the Exstream installation directory.
• When you deploy the updated WAR files, any customizations made to the
configuration files in the unpacked application folders in the portal root are lost.
To keep your customizations, you must make backups of the unpacked
application folders, including all sub-folders, and store the backups in a place
where they cannot be overwritten (that is, not in the portal root). After
redeploying the WAR files, you can restore your customizations from the
backups.
To replace WAR files and folders
1. Delete the old WAR files from the portal root on the Java application server.
Make sure the corresponding application folders are deleted.
2. Copy the new WAR files from the installation directory and paste them into the
portal root. For information about the paths, see “Copying WAR files to the Java
application server” on page 219.
3. Make sure that each WAR file is deployed as an exploded WAR, resulting in a
separate folder for the web application in the portal root.
Note: Exploding WAR files might be time consuming.
To update the configuration file for web application properties
• Open your configuration file for web application properties and compare the
file to the cc-webapp-config.xml template in the installation directory to make
sure your file contains the properties required to run the updated web
applications. For information about the paths, see “Connection properties for
web applications” on page 219.

Part 8
Running parallel versions
Chapter 42
Running parallel versions
You can run Exstream 16.3.x in parallel with Exstream 16.4. This allows you to run
the version 16.3.x Communications Server, management gateway, and design tools
(Communications Builder, Control Center, etc.) in parallel with the version 16.4
Communications Server, management gateway, and design tools.
Important
• To run version 16.3.x and 16.4 in parallel, you must create a new multi-
tenant repository and tenant repository for the 16.4 installation.
• You cannot run several versions of the web applications, such as
WorkShop, StoryBoard, ReTouch, and Supervisor in parallel.
Separate repositories
You must use separate repositories for the 16.3.x and 16.4 installations. The
repositories for each version must reside in separate databases or schemas. For
example, for SQL Server, you must create the multi-tenant repository for the 16.4
installation in a different database from the multi-tenant repository for the 16.3.x
installation. While on Oracle, separate schemas must be used for the version 16.3.x
and version 16.4 multi-tenant repositories.
The same applies for the tenant, queues, statistics, message, tracker, and other
repositories. The repositories for the 16.3.x installation must reside in separate
databases or schemas than the repositories for the 16.4 installation.
For information about the database servers that are supported for each version, see
OpenText Exstream 16.3.x Release Notes and OpenText Exstream 16.4 Release Notes.
Managing the environments

When running Exstream 16.3.x in parallel with Exstream 16.4, the environments are
managed separately. This means you must use the version 16.3.x Communications
Builder and Control Center to manage the 16.3.x environment, and 16.4
Communications Builder and Control Center to manage the 16.4 environment.
Installation steps
Prerequisites
• These steps assume the Exstream 16.3.x runtime and design components are
already installed and running.

Chapter 42 Running parallel versions
To install Exstream 16.4 in parallel with 16.3.x
1. Install the Exstream 16.4 runtime tools on the computer including

Communications Server and Control Center. See OpenText Exstream - Installation
Guide (CCM-IGD).
2. Install the Exstream 16.4 design tools on the computer including

Communications Builder. See OpenText Exstream - Installation Guide (CCM-IGD).
3. Prepare the version 16.4 environment including the new 16.4 multi-tenant and
tenant repositories. See “Steps checklist – Setting up the Exstream environment“
on page 19.
4. Set up the version 16.4 domain, Communications Server applications, and
repositories (statistics, queue, tracker, etc.). See “Steps checklist in Control
Center” on page 105.

Part 9
Profiling and tuning your environment
Chapter 43
About profiling
When profiling, you investigate how the Exstream software behaves during
processing. The purpose is to determine the most critical performance bottlenecks
and the sections that may need optimization.
Profiling is an iterative process that should be done throughout all implementation

phases for the Communications Builder Project. It needs to be revisited as the Project
and the requests evolve.
After you reach a satisfactory level of performance in your test environment, you
can save the profile logs as a baseline. Then, if you experience problems in
production, you can compare the logs to investigate where problems exist.
Caution
When profiling, you should always strive to use real data. In a test
environment, you should use data and volumes that resemble production
data as closely as possible.
Since logging affects performance, it is recommended to minimize the

logging.
Exstream Profiler
Most likely, your company already uses third-party profiling tools and platform
specific commands to profile the environment.
As a complement, you can use the Exstream Profiler for the Exstream related
parts. Profiler enables you to monitor and measure times for the following:
• Processing events, such as collecting, preprocessing, and processing data.
• Database invocations to and from the Exstream repositories.
• Web service requests to and from the service gateway.
• Cache service operations (mainly for ADEP Designer Processes).

Chapter 44
Setting up Profiler
44.1 Enabling Profiler

When you start an application (Communications Server, Task Scheduler, or service
gateway), the Profiler service is loaded but no performance data is collected. To start
collecting performance data, you must enable Profiler in Control Center or via the
command line.
By default performance data is created in a file called profiler.data in the working

directory. For information about changing the type of data that is collected or how
the output is presented, see “Configuring Profiler ” on page 356.
Caution
Using Profiler to collect performance data affects Exstream processing
performance. In a production environment, you should only enable Profiler
and collect performance data when required.
To enable Profiler from Control Center
1. In Control Center, select the application to profile.
2. In the properties view, double-click the Profiler property, and then click
enabled.
3. Restart the application.

When you have sufficient performance data, disable Profiler and restart the
application.
To enable Profiler via the command line
• At the command line, use the -profiler enabled argument when you start the
application.
When you have sufficient performance data, restart the application without the
argument.

Chapter 44 Setting up Profiler
44.2 Configuring Profiler

You can change the default configuration for Profiler in the profilerservice.xml
file.
Some examples of the changes you can make include:

• Specify a Profile provider that suits an external tool that you want to use to
analyze the profile output.
• Configure the type of information the Profiler provider logs for each event.
• Configure filters that control which Exstream components the Profiler logs
events for.
Common or application-specific file

You can either:
• Update the common profilerservice.xml file, applicable for all profile-
enabled applications. On Windows, this file is found under
<Exstream_Installation_directory>\<version>\Server\global. On
UNIX, it is under <Exstream_Installation_directory>/<version>/
Server/global.
• Copy the file to the working directory of a specific application and apply
updates to this application only (recommended).
To configure Profiler
1. Open the profilerservice.xml file.
2. Configure the profile provider. See “Configuring a Profile provider”

on page 356 below.
3. Configure the filters. See “Applying event filters” on page 359.
5. Restart the application(s).
44.2.1 Configuring a Profile provider

The Profile provider provides an interface between the Profiler service and the tool
in which you intend to analyze the profile data.
By changing properties in the profilerservice.xml, you can configure the

behavior of the provider, such as where the output file is generated and the type of
information that is logged for each event. For an example configuration, see
“Example – Profile provider configuration” on page 358.
Profile provider properties

• source

44.2. Configuring Profiler
The name and location of the file where the performance data is saved. By
default, a profiler.data file is generated in the working directory of each
profiler-enabled application.
• codepage
The format of the profile data, which must be UTF–8.
• delete
Determines whether Profiler overwrites any existing profile data, for example in
profiler.data, when Profiler is enabled.
• TRUE – The file and any existing data is deleted and a new file is created.
• FALSE – The new profile data is appended to the existing file.
• buffersize
The size in KBs of the front and back buffers of the Profile provider.
• messageformat
The event properties that Profiler logs. The more events that are logged, the more
Profiler affects the performance of the Communications Server application. For a
list of the events properties, see “Specifying which event properties are logged”
on page 357.
Specifying which event properties are logged

By default, Profiler only logs some of the event properties and uses # as the
delimiter. You can use the event UID (%1) to look up the other event properties when
you import the profile data to the database.
You can include other event properties in the profile data and specify the delimiter
which separates the events by configuring the messageformat attribute. The
delimiter must match the tool in which you will analyze the profile output.
It is also possible to only log the event UID and look up all other properties when
you import the data to the database. Logging only one event reduces the size of the
profile output and improves Profiler performance.
Event properties
%1
The UID (Unique Identifier) for the event in numeric format.
%2
The UID for the event in string format.
%3
The UID for the event namespace in numeric format.
%4
The UID for the event namespace in string format.

%5
The context of the event.
%6
The ID of the thread that generated the event.
%7
The timestamp when the event was executed.
%8
The elapsed time for the event (in milliseconds).
%9
The sequence number of the event, which shows the order the events are logged
in.
%10
The ISO timestamp of the event.
Example – Profile provider configuration

Example 44-1: Profile provider
In this example, a profiler.data file is generated in the working directory.

Only one event property is logged, which is the event ID (%1).
<provider value="http://schemas.streamserve.com/uid/component/
fileprofilerprovider/2.0">
<configuration>
<fileprofilerprovider xmlns="http://
schemas.streamserve.com/uid/component/fileprofilerprovider/
2.0">
<provider source="profiler.data" codepage="utf8"

delete="yes" messageformat="%1"> </provider>
</fileprofilerprovider>
</configuration>
</provider>

44.2. Configuring Profiler
44.2.2 Applying event filters

By default all measured profile events are presented in the profile data, which
results in comprehensive output. You can apply filters to limit the number of events
that are passed down to the profile provider and included in the profile output.
Namespaces
You can filter on the namespaces and their sub-events.
Namespace filter syntax

In the profilerservice.xml file, you can add one or more filter elements, each
containing one or more namespace filter configurations. Use the following
syntax to combine the appropriate filters:
• include – Includes information from the namespace in the profile output.
Use * to include all namespaces, except the ones excluded.
• exclude – Excludes information from the namespace in the profile output.
Use * to exclude all namespaces, except the ones included.
Example 44-2: Filter configuration
The filter below excludes information in the profile output about detailed
events relating to StoryTeller processing.
<filters>
<filter type="http://schemas.streamserve.com/uid/resource/
profilerservice/namespacefilter/1.0">
<configuration>
<namespacefilters xmlns=
"http://schemas.streamserve.com/
uid/resource/profilerservice/namespacefilter/1.0">
<namespacefilter type="exclude">
streamserve.notification.storyteller.profiler.
profilerevent.timer.detailed</namespacefilter>
<namespacefilter type="exclude">
streamserve.notification.storyteller.profiler.
profilerevent.value</namespacefilter>
</namespacefilters>
</configuration>
</filter>
</filters>

44.2.3 Flushing Profiler data to the output file

By default profile data is flushed or written into the output file (for example,
profiler.data) every 5 minutes or when the memory buffer of the Profile provider
is full.
You can change the interval at which the profile data is flushed in the
flushschedule attribute of the profilerservice element in profilerservice.
xml. If you leave this string blank "", profile data is only flushed into the output file
when the memory buffer is full.
Tips
• Flushing too often affects the Profiler performance.
• Because the default Profile provider has a large memory buffer, we
recommend you use a flushing interval to ensure data is written to the
output file regularly.
44.2.4 Scheduling the Profiler counter events

The counter events are reported every 60 seconds by default. You can change this
interval in the resportschedule attribute of the counters element in
profilerservice.xml. If you do not want to report the counter events, leave this
string empty "". If you comment out this section, the counter events are reported
periodically.
44.3 Analyzing profiler output

You must stop the Communications Server application before you begin analyzing
the profiler output data. If you did not change the default settings, the performance
data is created in a file called profiler.data in the working directory.
You can use a third-party tool to analyze the profile output. For example, you can
import the output into a Microsoft Excel spreadsheet, or you can create a repository
and analyze the output via the Database Management System.

Part 10
Using the document tracking framework
Chapter 45
About the document tracking framework
The document tracking framework provides a way to track the lifecycle of Exstream
documents. It can provide statistics about the number of jobs sent, the resources
used in output documents, and show status information for individual jobs.
How it works
The document tracking framework collects data about Communications Server
application usage and stores the data in the document tracking repository. The
following image shows how the document tracking framework works.
1. Notifications generated
When the document tracking framework is used with a Communications Server
application, the application generates different types of notifications during job
processing relating to the job processing phases, resources usage, etc.
2. Notifications retrieved
The notification listener in the document tracking framework retrieves the
notifications relevant for document tracking, such as when job processing starts
and finishes, when resources are used in Processes, and when the output
connectors are invoked.
3. Notifications processed
Based on the configuration in the property files, the notification listener extracts
the relevant tracking attributes from the notifications and maps the metadata (or
property) values from the current job to internal data tracking keys.

Chapter 45 About the document tracking framework
4. Tracking data stored

The document tracking framework stores the tracking data in the document
tracking repository.
5. Tracking data analyzed
The data in the document tracking repository can be analyzed in different ways.
The document tracking framework installation includes database tables and
views allowing the data to be analyzed with reporting tools that can connect to
SQL databases. It is also possible to use OpenText Analytics (iHub) or another
third-party tool for analysis.
Data tracking attributes

The document tracking framework retrieves information around the following
dimensions and attributes from the notifications.
Table 45-1: Data tracking dimensions and attributes
Dimension Example attributes Example values

Application ID <GUID>
name Project 2
domain <GUID>
Time notification trigger time Java timing format
Document type Invoice
theme ID <GUID>
theme name Invoice_Christmas
Resource type application/xhtml+xml
theme ID <GUID>
name Embedded text
Output connector ID <GUID>
name PDF File
type http://schemas.streamserve.com/
uid/component/fileoutconnector/1.0
queue ID <GUID>
name Output
recipient ID ID of contact person
Job top job ID <GUID>
status succeeded = TRUE or ErrorCode
is provided
Tracking custom attributes -

In addition to the attributes listed above, you can also track other attributes in a
Communications Builder Project. For example, if you want to add an invoice ID,
customer ID, or another property used in the Project to the tracking data.
Exstream Notifications API

The document tracking framework is based on the Exstream Notifications API. It
uses the following Communications Server notifications for document tracking:
• BeginBatch and EndBatch – The BeginBatch notification is generated when the
top job starts and EndBatch is generated when the top job finishes.
• UsedCompCResources – This notification is generated each time a resource is
used in a theme-enabled Process.
• BeginOutputDelivery and EndOutputDelivery – The BeginOutputDelivery
notification is generated before the output connector is invoked and
EndOutputDelivery after the output connector has delivered the output job.
Related documentation
• OpenText Experience Analytics Data Collector - Installation and Configuration Guide
(CRA-IGD)
Contains information about OpenText Analytics (iHub) and the Experience
Analytics Data Collector.
• OpenText Exstream - Communications Builder Configuration Guide (CCMPRJ-CGD)
Contains the description of how to configure a Communications Builder Project
for use with the document tracking framework.

Chapter 46
Setting up the document tracking framework
46.1 Steps checklist

This table shows the steps required to set up the document tracking framework.
Steps See:
Step 1 – Install the document tracking “Installing the document tracking
framework framework” on page 367
Step 2 – Create the document tracking “Creating the document tracking repository”
repository on page 368
Step 3 – Configure the document tracking “Configuring the document tracking
framework framework” on page 369
Step 4 – Configure the Communications Part XI “Document tracking framework” in
Builder Project for use with the document OpenText Exstream - Communications Builder
tracking framework Configuration Guide (CCMPRJ-CGD)
Optional – Configure custom properties for Section 43 “Configuring custom tracking
tracking attributes (Optional) ” in OpenText Exstream -
Communications Builder Configuration Guide
(CCMPRJ-CGD)
After these steps, you can run some jobs and then look at the tracking data
generated. For more information about how to analyze the tracking data, see
“Analyzing the tracking data“ on page 371.
46.2 Installing the document tracking framework

The document tracking framework is delivered as a ZIP file (exstream-dtf-
<version>.zip) that you can download from OpenText My Support.
You must install and configure the document tracking framework on each
Communications Server application individually. In load balancing scenarios,
several Communications Server applications can generate notifications relating to
the same job. Because of this, OpenText recommends that you install the document
tracking framework on all the Communications Server applications in one domain
rather than on a single application.
To install the document tracking framework
• Extract the exstream-dtf-<version>.zip file in the application working

directory under <Management_gateway_home>\<application_name>
\<physical_layer>.

Chapter 46 Setting up the document tracking framework
Document tracking framework ZIP contents
After the contents of the ZIP file are unpacked, the directory should contain the
following folders:
• \java folder with all the runtime jar files.

• \package folder with the Exstream Notification Listener XML configuration file
(NotificationTrackingListener.xml).
• \sql folder with the SQL scripts for the database table creation on Microsoft SQL
Server or Oracle Database. It also contains sample SQL scripts for analyzing
views.
• Properties files for the notification and metadata mapping:
• metadata_mapping.properties: Metadata mapping configuration file

• notification_mapping.properties: Notification mapping configuration
file
46.3 Creating the document tracking repository

The document tracking framework installation includes scripts to create the tables
required in the document tracking repository. You can create the tables in an Oracle
schema or SQL Server database with other Exstream repositories. You can also
create the tables in a separate Oracle schema or SQL Server database.
The document tracking framework uses JDBC drivers located in the

<APPL_WORKING_DIR>/java folder to access the repository.
To create the document tracking repository
1. Create a database user with write access to the database.
2. Run the create-table-<database_type>.sql script to create the required

tables.
Make sure that you use the script that matches your database type:
• ./sql/mssql/create-tables-mssql.sql: Microsoft SQL Server script for

table creation.
For Microsoft SQL Server, the database and the creation of the tables is case-
sensitive. The create-db-mssql.sql script fulfills this requirement.
• ./sql/oracle/create-tables-oracle.sql: Oracle SQL script for tables

creation.
For more information about the database tables, see “Table descriptions”
on page 373.

46.4. Configuring the document tracking framework
46.4 Configuring the document tracking framework

The following steps are required to configure a Communications Server application
for use with the document tracking framework:
• Configure the notification listener

• Enable Java for the application
After you make changes to the configuration files, you must restart the
Communications Server application for the changes to take effect.
Considerations when tracking several applications
• If you are using a scenario where one application creates a job (i.e. generates the
beginbatch notification) and another application ends the job (i.e. generates the
endbatch notification), you must track all involved applications with the same
configuration and the same document tracking repository. To simplify
maintenance, you can store the metadata mapping file metadata_mapping.
properties in a central location and configure the path in the
NotificationTrackingListener.xml.
• In a high-availability scenario, you must have identical copies of the metadata
mapping file metadata_mapping.properties for each node.
Step 1 – Configure the notification listener

In the NotificationTrackingListener.xml file, you must edit the elements in the
<notificationlistener> node, which contain the parameters for the database
connection and the location of the property files.
This file is found in <APPL_WORKING_DIR>/packages/

NotificationTrackingListener.xml.
NotificationTrackingListener.xml elements
<configuration
type="com.opentext.sap.dp.strs.notification.impl.NotificationConfigur
ationReader">
<notificationlistener
xmlns="com.opentext.sap.dp.strs.notification.impl.NotificationConfigu
rationReader">
<dbUrl>dbUrl</dbUrl>
<dbUser>dbUser</dbUser>
<dbPassword>dbPassword</dbPassword>
<notificationConfigurationPath>notificationConfigurationPath</
notificationConfigurationPath>
<metadataConfigurationPath>metadataConfigurationPath</
metadataConfigurationPath>
</notificationlistener>
</configuration>

Chapter 46 Setting up the document tracking framework
Parameters
• <dbUrl>: JDBC connection string for your database.
Microsoft SQL Server example: jdbc:sqlserver://myComputer:1433;
databaseName=DocumentTracking
Microsoft SQL Server Express example: jdbc:sqlserver://myComputer:1433;
instance=SQLEXPRESS;databaseName=DocumentTracking
• <dbUser>: A dedicated database user with table write access permissions.
• <dbPassword>: The password for database user in plain text.
• <notificationConfigurationPath>: The path to and name of the
notification_mapping.properties file. This path is relative to the working
directory.
• <metadataConfigurationPath>: The path to and name of the metadata_mapping.
properties file. This path is relative to the working directory.
To track several applications on one node, you can store the metadata mapping
file in a central folder for all related applications. In this case, you must add the
new folder in the NotificationTrackingListener.xml files of all applications
either as a fully qualified path or in relation to the application working directory,
for example ..\..\TrackingConf\metadata_mapping.properties.
Step 2 – Enable Java for the Communications Server application

1. In Control Center, right-click the application, and select Java/Server
Configuration.
2. From the Value drop-down list, select ORACLE or IBM, depending on the vendor
of the installed JRE or JDK.
3. Restart the application.

Chapter 47
Analyzing the tracking data
To analyze the tracking data, you can use a third-party analysis tool, which can be
combined with the views included in the document tracking framework installation.
View script paths
• ./sql/mssql/samples/*.sql: Microsoft SQL Server views for analyzing

tracking data
• ./sql/oracle/samples/*.sql: Oracle SQL views for analyzing tracking data
About the tracking data

To help you interpret the tracking data, this section describes how the tracking data
for a job is created:
• Each top job processed by the Communications Server application creates one
entry in the TrackingJobs table.
• Each document generated by a theme-enabled Process in the job creates one
entry in the TrackingDocuments table.
• Each resource used in the document creates one entry in the
TrackingDocResources table. These resources are the texts, images, rules, etc.
that are defined in the Exstream theme.
• Each output connector that the document is sent to creates one entry in the
TrackingOutputs table. The only exception is when Job output mode is used on
the output connector. In job output mode, all the documents in the job are sent to
the output connector in one output job, which creates one entry in the
TrackingOutputs table for the entire job.
The following examples show the tracking data generated for a job with a single
document and for a job with multiple documents.
Note that these examples do not show the order in which the Communications
Server application generates the notifications, the order in which the tracking data is
stored in the repository, or the processing sequence of the Communications Server
application.
Example 47-1: Job with a single document
This image shows the tracking data for a job that generates one document
that contains two resources and is sent via two output connectors.

Chapter 47 Analyzing the tracking data
In this example, the job creates one entry in the TrackingJobs table and the
document creates one entry in the TrackingDocuments table. Two resources
are used in the document, which creates two entries in the
TrackingDocResources table. The single document is sent via two output
connectors, which creates two entries in the TrackingOutputs table.
Example 47-2: Job with multiple documents (Job output mode)
This image shows how the tracking data is generated for a job that creates
multiple documents that are delivered by an output connector in Job output
mode.
In this example, the job creates one entry in the TrackingJobs table. Each
document generated creates one entry in the TrackingDocuments table.
Each resource used in each document creates one entry in the
TrackingDocResources table. All the documents are delivered in one
output job by the output connector, which creates one entry in the
TrackingOutputs table.

Table descriptions
The document tracking repository contains the following tables.
Table name: Stores: Unique key consists of: Technical details:

TrackingJobs Top job information, • tenantID – Tenant Data for this table comes
which includes the start ID from the
and stop timestamps as • trackerID – Top job BeginBatchNotificat
well as the success flag, ID ion and the
error code, and message. EndBatchNotificatio
n.

Chapter 47 Analyzing the tracking data
TrackingDocuments Document relevant • tenantID – Tenant Data for this table comes
information. If custom ID from the first instance of
attributes are tracked, • trackerID – Top job the
they are stored in this ID UsedCompCResourceNo
table. tification for the
• docKey – document
document.
key
The document key
(docKey) is extracted
from the metadata based
on the Project
configuration.
TrackingDocResource Information about the • tenantID – Tenant Data for this table comes
s resources used in the ID from the resource array in
documents. • trackerID – Top job the
ID UsedCompCResourceNo
tification.
• resourceID –
Resource ID The document key
• docKey – Document (docKey) is the same as
key for the related document.
TrackingOutputs Information about the • tenantID – Tenant Data for this table comes
output connector(s) used ID from the
to deliver the • trackerID – Top job BeginOutputDelivery
document(s). It includes ID Notification and the
start and stop timestamps EndOutputDeliveryNo
as well as the success flag,
• docKey – Document
tification.
error code and message. key
• outConnectorID – The document key
Output connector ID (docKey) is the same as
• outID – Output job for the related document.
ID
Table relationships
The image below shows the relationships between the tables. Normally only jobs
related to documents are tracked. However, sometimes jobs unrelated to documents
may also be tracked (orphans). These jobs should be ignored when extracting data
for analytics.

Chapter 48
Maintaining the document tracking framework
Configuring Log4J logging

The document tracking framework uses the Apache Log4j classes for logging. The
\java\log4j.properties file included in the installation uses a notification.
log file in the working directory of the Communications Server application. This file
will rotate ten times for a maximum size of 10 MB. For information about changing
the log settings, see the Apache Log4j website (http://logging.apache.org/log4j).
Maintaining the document tracking repository

The document tracking framework provides a basis for document tracking of
Communications Server application usage. You must clean up old entries in the
document tracking repository based on the usage of the document tracking
framework in your company. You will also need to take the necessary actions to
avoid performance degradation.
To clean up the repository tables, you must remove related entries to keep data
consistency. For example, if the clean-up criterion is to remove all entries in the
TrackingDocuments table older than 2012–01–01, you must apply the same for all
other tables that have the same tenantID and trackerID.
Removing the document tracking framework

To uninstall the document tracking framework for a Communications Server
application
1. Remove the directories and files included in the exstream-dtf-<version>.zip

from the directory of each Communications Server application.
For a list of the folders and files, see Document tracking framework ZIP
contents on page 368.
2. If no longer necessary for other functions, disable Java on the Communications

Server application.
To deactivate the document tracking framework for a Communications Server

application
• Remove at least NotificationTrackingListener.xml and the complete \java

\ folder.

Part 11
Encryption tool
Chapter 49
Using the security tool on Windows
The security tool enables you to encrypt a set of XML files in your Communications
Server installation to ensure that passwords are not shown in clear text.
Note: Because you modify installed files using the tool, you may need
administrative privileges on Windows.
Preparations
Stop all applications in the domains, for example Communications Server,
service gateway, etc.
Note: The management gateway is automatically restarted by the security

tool.
Running the security tool

To encrypt files, you must:
• Have access to a PFX key. You can generate a key using the
strssecureinstall.bat script.
• Encrypt the files with the key by running the strssecureinstall.bat
script.
• Update domain information and restart applications.
The parameters to use with the script are listed below. The script is installed in:
<Exstream installation>\<version>\Server\bin
For examples of how to use the tool, see “Examples of running the script”
on page 385.
Tip: After you have run the script using the -genkey parameter, it is
important to store the key in a secure location. We recommend you to
generate the key as a file (using file:// protocol), rather than just an alias
name, and store the file on a secure medium. Then you refer to the file at
its secure location when encrypting/decrypting.
It is important that you do not loose the key, or overwrite it by generating
a new key with the same path and name, as that would make it impossible
to decrypt the files when needed.
Note that if the script fails to enable security, the script will automatically
perform a rollback. This is similar to running the script again with the -
disable parameter.

Chapter 49 Using the security tool on Windows
Strssecureinstall parameters
-genkey
Generates a key with a name specified in the -alias parameter and (optionally)
password protected via the -keypass parameter. You use this key to encrypt
and decrypt the files. If the specified alias name already exists, the script will
stop. You can use the -force parameter to overwrite the file.
-mgwroot
The path to the management gateway root directory, for example:
C:\ManagementGateway\16.3.0\root
-keysize
Use this together with -genkey to control the private key size. Specify a byte
length as argument. Default is 2048.
-validity
Use this together with -genkey to control the validity of the key. Specify a
number of days as argument. Default is 7300.
-force
Use this together with -genkey or -export. If the file already exists, this
parameter lets you overwrite the existing file.
-alias
The alias for the key. You can use the file:// protocol prefix to specify the key
path and file name, or you can specify an alias name for the key. If you specify
an alias name, you can export the key to a file with the -export and -keyfile
parameters.
Note: Specify an absolute path to the key file. The folder where you create
the file must exist.
-keyalias
Use this instead of -alias when restarting the encrypted application from a
command line.
Note: You must also supply the-keypass parameter if a password was

used when generating the key.
-keypass
A password for the key. Optional, but should be used for increased protection of
the key itself.
To limit availability of cleartext passwords you can use a file reference as the
password. The password is then read from the file when decrypting the alias
used to encrypt and decrypt the system.
Note: You must secure the password file using proper file system
permissions, or security will not be improved.

-dname
Optionally, you can specify a distinguished name that is included in the key.
-enable
Enables security on the Communications Server installation.
Note: If files already are encrypted, they will not be encrypted again.
-disable
Disables the security of the system and restores the original configuration.
-export
Exports a key with a specified alias to a file. The file to export to is specified with
the -keyfile parameter.
If the specified alias name already exists, the script will stop. You can use the -
force parameter to overwrite the file.
-keyfile
The name of the file created using the -export parameter.
-verbose
Enables detailed output.
-?
Displays help text with examples.
To enable security
1. Stop any running applications in the domains on the system you want to secure.
2. In a command line tool, browse to:

<Installation directory>\<version>\Server\bin

strssecureinstall.bat -genkey -mgwroot "<mgwroot path>" -alias
"file://<path to PFX file to generate>" -keypass "<password of your
choice>" [-dname "<Distinguished Name>"] [-verbose]
4. For each Communications Server installation to secure, run the following

command:
strssecureinstall.bat -enable -mgwroot "<mgwroot path>" -alias
"file://<path to the generated PFX file>" -keypass "<password used
when generating key>" [-verbose]
5. In Control Center, right-click the domain and select Update Application

Domain File.
6. Right-click the domain and select Restart All Applications.

Note: If you restart the applications from a command line, you must use the -
keyalias parameter instead of the -alias parameter. If password was used
when creating the key, the -keypass parameter must also be provided.
To enable security by using file reference to password
Note: When using a file reference to the password, the content of the file must
only be the password without any spaces or new lines etc.


"file://<path to PFX file to generate>" -keypass "file://<path to
password text file>" [-dname "<Distinguished Name>"] [-verbose]

command:
strssecureinstall.bat -enable -mgwroot "<mgwroot path>" -alias
"file://<path to the generated PFX file>" -keypass "file://<path to
password text file>" [-verbose]

Domain File.
To disable security


"file://<path to PFX file to generate>" -keypass "<password of your
choice>" [-dname "<Distinguished Name>"] [-verbose]
4. For each Communications Server installation to decrypt, run the following

command:
strssecureinstall.bat -disable -mgwroot "<mgwroot path>" -alias
"file://<path to the PFX file used when encrypting the system>"
-keypass "<password used when enabling security>" [-verbose]

Domain File.

To change keys used for encryption
• If you want to use another key than the one you used to encrypt your
installation, you must first disable security on the installation, and then enable
security with the new key.
Examples of running the script
Example 49-1: Generating a key and encrypting the files
The following command creates a key stored in c:\testkey.pfx
strssecureinstall.bat -genkey -mgwroot "C:\ManagementGateway\

16.3.0\root" -alias "file://c:\testkey.pfx" -keypass "mypass"
The following command uses the generated key to encrypt the files. You can
use the key on all Communications Server installations that you want to
secure. In this example, the management gateway on localhost, port 28000,
with a CA certificate in the default location, is invoked with the
Administrator user and password admin_pass. The management gateway
is automatically restarted after encryption:
strssecureinstall.bat -enable -mgwroot "C:\ManagementGateway\

Example 49-2: Generating a key with an alias name, and exporting the
key to a file
The following command creates a key stored with alias testkey:
strssecureinstall.bat -genkey -mgwroot "C:\ManagementGateway\

16.3.0\root" -alias "testkey" -keypass "mypass"
The key is exported to a file called testkey.pfx.
strssecureinstall.bat -export -mgwroot "C:\ManagementGateway\

16.3.0\root" -alias "testkey" -keypass "mypass" -keyfile
"testkey.pfx"
Example 49-3: Disabling security for a system
The following example disables the security by decrypting files, removing

startup arguments, and restarting the management gateway.

strssecureinstall.bat -disable -mgwroot "C:\ManagementGateway\


Chapter 50
Using the security tool on UNIX/Linux
The security tool enables you to encrypt a set of XML files in your Communications
Server installation to ensure that passwords are not shown in clear text. In addition,
the .operatorInput file located in the Communications Server installation root
folder is encrypted.
Preparations
Stop all applications in the domains, for example Communications Server,
service gateway etc.
Note: The management gateway is automatically restarted by the security

tool.
Running the security tool

To encrypt the files, you must:
• Have access to a PFX key. You can generate a key using the
strssecureinstall script.
• Encrypt the files with the key by running the strssecureinstall script.
• Update domain information and restart applications.
The parameters to use are listed below. The tool is installed in:
<Installation directory>/<version>/Server/bin
For examples of how to use the tool, see “Examples of running the script”
on page 390.
Tip: After you have run the script with the -genkey parameter, it is
important that you store the key in a secure location. We recommend you
to generate the key as a file (using file:// protocol), rather than just an
alias name, and store the file on a secure medium. Then you refer to the file
at its secure location when encrypting/decrypting.
It is important that you do not loose the key, or overwrite it by generating
a new key with the same path and name, as that would make it impossible
to decrypt the files when needed.
Strssecureinstall parameters
-genkey
Generates a key with a name specified in the -alias parameter and (optionally)
password protected via the -keypass parameter. You use this key to encrypt the
files. If the specified alias name already exists, the script will stop. You can use
the -force parameter to overwrite the file.

Chapter 50 Using the security tool on UNIX/Linux
-keysize
Use this together with -genkey to control the private key size. Specify a byte
length as argument. Default is 2048.
-validity
Use this together with -genkey to control the validity of the key. Specify a
number of days as argument. Default is 7300.
-force
Use this together with -genkey or -export. If the file already exists, this
parameter lets you overwrite the existing file.
-alias
The alias for the key. You can use the file:// protocol prefix to specify the key
path and file name, or you can specify an alias name for the key. If you specify
an alias name, you can export the key to a file with the -export and -keyfile
parameters.
Note: Specify an absolute path to the key file. The folder where you create
the file must exist.
-keyalias
Use this instead of -alias when restarting the encrypted application from a
command line.
Note: You must also supply a -keypass parameter if a password was used
when generating the key.
-keypass
A password for the key. Optional, but should be used for increased protection of
the key.
To limit availability of cleartext passwords you can use a file reference as the
password. The password is then read from the file when decrypting the alias
used to encrypt and decrypt the system.
Note: You must secure the password file using proper file system
permissions, or security will not be improved.
-dname
Optionally, you can specify a distinguished name that is included in the key.
-enable
Enables security for the Communications Server installation.
Note: If files already are encrypted, they will not be encrypted again.
-disable
Disables the security in the Communications Server installation and restores the
original configuration.

-export
Exports a key with a specified alias to a file. The file to export to is specified with
the -keyfile parameter.
If the specified alias name already exists, the script will stop. You can use the -
force parameter to overwrite the file.
-keyfile
The name of the file created using the -export parameter.
-verbose
Enables detailed output.
-?
Displays help text with examples.
To enable security
1. Stop all applications in the domains, for example Communications Server,

2. Browse to <Installation directory>

./launcher ./bin/strssecureinstall -genkey -alias "file://
<absolute path to PFX file to generate>" -keypass "<password of your
choice>" [-dname "<Distinguished name>"] [-verbose]

command:
./launcher ./bin/strssecureinstall -enable -alias "file://
<absolute path to the generated PFX file>" -keypass "<password used
when generating key>" [-verbose]
5. Update the domain information file and restart all services, either from a
Windows machine with Control Center or by using the command line utilities.
To enable security by using a file reference to the password


<absolute path to PFX file to generate>" -keypass "file://<absolute
path to password file>" [-dname "<Distinguished name>"] [-verbose]

Chapter 50 Using the security tool on UNIX/Linux

command:
./launcher ./bin/strssecureinstall -enable -alias "file://
<absolute path to the generated PFX file>" -keypass "file://<absolute
path to password file>" [-verbose]
To disable security

Service Gateway etc.

<absolute path to PFX file to generate>" -keypass "<password of your
choice>" [-dname "<Distinguished name>"] [-verbose]
4. For each Communications Server installation to decrypt, run the following

command:
./launcher ./bin/strssecureinstall -disable -alias "file://
<absolute path to the PFX file used when encrypting the system>"
-keypass "<password used when enabling security>" [-verbose]
To change keys used for encryption
• If you want to use another key than the one you used to encrypt your
installation, you must first disable security on the installation, and then enable
security with the new key.
Examples of running the script
Example 50-1: Generating a key and encrypting the files
The following command creates a key stored in /opt/streamserve/

testkey.pfx

./launcher ./bin/strssecureinstall -genkey -alias "file:///opt/
streamserve/testkey.pfx" -keypass "mypass"
The following command uses the generated key to encrypt the files. You can
use the key on all Communications Server installations that you want to
secure.
./launcher ./bin/strssecureinstall -enable -alias "file:///opt/

streamserve/testkey.pfx" -keypass "mypass"
Example 50-2: Generating a key with an alias name, and exporting the
key to a file
The following command creates a key stored with alias testkey:
./launcher ./bin/strssecureinstall -genkey -alias "testkey"

-keypass "mypass"
The key is exported to a file called testkey.pfx.
./launcher ./bin/strssecureinstall -export -alias "testkey"

-keypass "mypass" -keyfile "testkey.pfx"
Example 50-3: Disabling security on a management gateway
The following example disables the security by decrypting files, removing

startup arguments, and restarting the management gateway.
./launcher ./bin/strssecureinstall -disable -alias "file:///

opt/streamserve/testkey.pfx" -keypass "mypass"

Chapter 51
Replacing certificate files
You can replace the certificate files used by the management gateway and service
gateway. For example, when you have renewed a certificate file.
If you replace a certificate file, the new certificate must have the same name as the
old certificate.
The certificate files are located in the following directories:

• Trusted certificate authority file(s)
<Installation directory>\<version>\Server\global\security\
certificatestore\trusted\authorities
• Server identity file
<Installation directory>\<version>\Server\global\security\keystore
\private
To replace a certificate file
1. Browse to the directory that contains the certificate file you want to replace.
2. Copy the new certificate file to the directory.
3. Restart the following Windows services:
• Management Gateway
• Service Gateway
Note: The name you give the service gateway in Control Center is
specified in the Description field of the Services list in Windows.

Chapter 52
Troubleshooting Encryption tool
52.1 Lost key

If you no longer have access to the key that you used to encrypt your
Communications Server installation, you will not be able to decrypt files or restart
your applications.
Solution on Windows
1. Run the security tool with the -disable command. See “To disable security“
on page 384. At this stage, it does not matter what you specify as -alias and -
keypass as you only need to disable the management gateway startup
arguments.
2. From your backup, restore the following original files:
<Installation directory>\<version>\Server\solutions\management\
mgwconnections.xml
mgmgateway.xml
mgw-trustedcommunications.xml (if you use it)
<Management_gateway_root>\<Version>\root\securityprofiles
\multitenantrepository.xml
<Management_gateway_root>\<Version>\root\securityprofiles
\multitenantotds.xml (if you use it)
3. In Control Center, right-click the domain and select Update Domain

Information Files, or use the command line utilities for the corresponding
function.
4. Right-click the domain and select Restart All Applications, or use the
command line utilities for the corresponding function.
5. Generate a new key and re-run the encryption. see “Using the security tool on
Windows“ on page 381.
Solution on UNIX/Linux
on page 384. At this stage, it does not matter what you specify as -alias and -
keypass as you only need to disable the management gateway startup
arguments.
2. From your backup, restore the following original files:

Chapter 52 Troubleshooting Encryption tool
<Installation directory>/<version>/Server/solutions/management/
mgwconnections.xml
<Installation directory>/<version>/Server/solutions/management/
mgmgateway.xml
3. In Control Center on a Windows machine, right-click the domain and select

Update Domain Information Files, or use the command line utilities for the
corresponding function.
4. Right-click the domain and select Restart All Applications, or use the
command line utilities for the corresponding function.
5. Generate a new key and re-run the encryption. See “Using the security tool on
UNIX/Linux“ on page 387.
52.2 Management Gateway does not start

If the management gateway does not start correctly after you have run the -enable
command, it may be due to wrong -alias or -password was submitted.
Solution on Windows
on page 384.
2. Enable security with correct parameters. See “To enable security“ on page 383.
Solution on UNIX
on page 390.
2. Enable security with correct parameters. See “To enable security“ on page 389.

Open Text

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Open Text

Încărcat de

Drepturi de autor:

Formate disponibile

OpenText™ Exstream

Communications Server Administration

This guide contains information about how to set up and

Open Text Corporation

275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1

Copyright © 2018 Open Text. All Rights Reserved.

No Warranties and Limitation of Liability

1 Tenancy concept ..................................................................... 13

2 What components are required to get started? .................... 15

3 Steps checklist – Setting up the Exstream environment ..... 19

4 Setting up OTDS for Exstream ............................................... 21

5 Preparing the database ........................................................... 53

6 Setting up the Exstream environment ................................... 57

7 Managing tenants .................................................................... 77

8 Implementing OpenText Private Help Server ........................ 87

OpenText Exstream – Communications Server Administration Guide iii

Part 2 License management 97

9 Managing license files ............................................................ 99

10 Measuring transactions and MicroMessages for

Part 3 Managing applications with Control Center 103

11 Getting started in Control Center ......................................... 105

12 Creating a domain ................................................................. 111

13 Creating repositories ............................................................ 125

14 Setting up Communications Server applications ............... 139

iv OpenText Exstream – Communications Server Administration Guide

15 Setting up a service gateway ............................................... 151

16 Archiving documents ............................................................ 153

17 Managing applications .......................................................... 157

18 Logging in Control Center .................................................... 173

19 Maintaining Exstream components ..................................... 181

OpenText Exstream – Communications Server Administration Guide v

Part 4 Managing applications with command line utilities 183

20 About the command line utilities ......................................... 185

21 Arguments and descriptions ................................................ 189

22 Examples and troubleshooting ............................................ 209

Part 5 Administering web applications 215

23 About the web applications .................................................. 217

24 Deploying the web applications ........................................... 219

25 Editing web application properties ...................................... 221

vi OpenText Exstream – Communications Server Administration Guide

25.4.1 Managing configuration file resources ............................................. 229

26 Running the web applications .............................................. 263

27 Monitoring the web applications .......................................... 275

28 Solr integration in WorkShop and Supervisor .................... 279

29 Additional Control configuration ......................................... 299

Part 6 Maintaining the repositories 301

30 About maintaining Exstream repositories .......................... 303

OpenText Exstream – Communications Server Administration Guide vii

31 Deleting expired content ....................................................... 305

32 Running index maintenance (Microsoft SQL Server) ........ 309

33 Rebuilding or coalescing indexes (Oracle Database) ........ 313

34 Scheduling index maintenance or coalescing via task

35 Gathering statistics (Oracle Database) ............................... 323

36 Troubleshooting performance via EXPLAIN PLAN

37 Backing up the repositories ................................................. 329

Part 7 Installing and applying hotfixes 331

38 About installing and applying hotfixes ............................... 333

39 Installing a hotfix ................................................................... 335

40 Applying a hotfix to the repositories ................................... 337

41 Applying a hotfix to the web applications ........................... 345

Part 8 Running parallel versions 347

42 Running parallel versions ..................................................... 349

Part 9 Profiling and tuning your environment 351