Professional Documents
Culture Documents
Open Text
Open Text
CCMSYS160400-AGD-EN-01
OpenText™ Exstream
Communications Server Administration Guide
CCMSYS160400-AGD-EN-01
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.
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
Disclaimer
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
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
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
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.
Note: This figure does not show all the components required in the
Exstream environment.
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.
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.
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 repository
This repository stores tenant specific information which includes:
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-
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.
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.
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.
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.
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.
The image below shows how Linda and Bob have access to the management
gateway, but no access to either tenant’s applications or data.
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.
• 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.
Note: The Exstream multi-tenant OTDS and tenant OTDS are written in italics
throughout this section to distinguish these components from OTDS components.
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.
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.
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).
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 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.
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
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.
After OTDS is set up for Exstream, tenants can use the OTDS web administration
client to manage their users and assign access roles.
You can also assign one user, group, or organizational unit to several roles.
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.
High-level steps
Step: See:
1. Install OTDS. “Example: Installing OTDS” on page 35
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).
5. Restart Tomcat.
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.
Application Server
Apache Tomcat.
Installation Type
Do not check the replication server option.
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.
Note: Self-signed certificates are only suitable for use in development and testing
environments.
3. Enter a password, your user, organizational, location details and then enter YES
to confirm.
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
<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.
• strs.role partition
• Exstream resource
• 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
https://<OTDS host>:<port>/otds-admin/
• On the Partitions page, click Add > New non-synchronized User Partition,
enter strs.role, and then click Save.
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.
To create a user:
1. On the Partitions page, select the strs.role partition, and then click Actions >
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:
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).
1. On the Partitions page, select the strs.role partition, and then click Actions >
View Members.
2. Click the Users tab, select the user, and then click Actions > Edit Membership.
4. Select the appropriate group to add the user to, click Add Selected, and then
click Close.
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.
https://<otds_host>:<port>/otdsws/api/index.html?rest#!
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. 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.".
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.
2. Click Add > New user, and then enter the user details.
Example user ID:
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.
2. Enter https://localhost.
3. Click Save.
Notes
• strs.role partition
• Exstream resource
• 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
https://<OTDS host>:<port>/otdstenant/<tenantname>/otds-admin/
• On the Partitions page, click Add > New non-synchronized User Partition,
enter strs.role, and then click Save.
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.
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.
In this example, the password policy is set to User cannot change password and
Password never expires for convenience.
To create a user:
1. On the Partitions page, select the strs.role partition, and then click Actions >
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:
4. Enter a password.
5. Click Save.
1. On the Partitions page, select the strs.role partition, and then click Actions >
View Members.
2. Click the Users tab, select the user, and then click Actions > Edit Membership.
4. Select the appropriate group to add the user to, click Add Selected, and then
click Close.
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.
http://<otds_host>:<port>/otdstenant/<tenant_name>/otdsws/api/index.
html?rest#!
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.".
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.
2. Click Add > New user, and then enter the user details.
Example user ID:
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.
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.
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.
1. Specify the following database server parameter before you create the database:
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.
• nls_length_semantics: char
Note: The char value requires more space in the database than the
default byte value.
• 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.
STRS_LOCATION=/usr/Exstream/Exstream-16.3.0.GA.<Build>
export STRS_LOCATION
<Exstream_Installation_directory>\<version>\Server\bin
ss_tenantadmin.exe <arguments>
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.
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
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_multitenant_repository
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_multitenant_repository
Argument descriptions
-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.
-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.
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_multitenant_otds
-otdsusername strsbrowser@strs.role -otdspassword strs
-otdsresource 71953643-a163-4123-b312-4fe225c34f08
-otdsresourcepassword "Z0yWzfu8UeDge6ZBlxiDLw=="
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
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"
Argument descriptions
-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.
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 in the OTDS web client. For more information about disabling HTTPS
communication in OTDS, see the following documentation:
-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.
For information about the general arguments that can be used with
ss_tenantadmin, see “ss_tenantadmin additional (optional) arguments”
on page 70.
Syntax
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action create_multitenant_repository
-multitenantdbprofile "C:\MyConnectionProfiles\
multitenant_respository_profile.xml" -dbadminusername sa
-dbadminpassword Changeoninstall2000
Argument descriptions
-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>
(OPTIONAL) 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.
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_mgw -multitenantdbprofile
"C:\MyConnectionProfiles\multitenant_respository_profile.xml"
-multitenantotdsprofile "C:\MyConnectionProfiles\
multitenant_otds_profile.xml"
Argument descriptions
-multitenantdbprofile <path_file>
The path to and name of the XML file containing the connection profile for the
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>
(OPTIONAL) 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.
Unix
• On UNIX, start the management gateway with the command:
./launcher [<options>] management
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).
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
Syntax
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_tenant_repository
Tip: For information about the default values, see ss_tenantadmin help (-h).
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
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"
Argument descriptions
-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.
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_tenant_otds -otdsusername
strsbrowser@strs.role -otdspassword strs -otdsresource
f9b7fbf3-dc85-4ca1-8046-b0e987b3d4c3 -otdsresourcepassword
"cWMahqHTXxSFdRcVrnsE2g=="
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
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"
Argument descriptions
-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.
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 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.
-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.
For information about the general arguments that can be used with
ss_tenantadmin, see “ss_tenantadmin additional (optional) arguments”
on page 70.
This example creates the tenant repository based on the connection profile in
the file C:\MyConnectionProfiles\tenant_respository_profile.xml
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
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>
The path to and name of the XML file containing the connection profile for the
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
-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.
-env <path_file>
(OPTIONAL) 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.
• C:\MyConnectionProfiles\tenant_respository_profile.xml
• C:\MyConnectionProfiles\tenant_otds_profile.xml
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
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
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 <path_file>
The path to and name of the XML file containing the connection profile for the
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>
(OPTIONAL) 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.
-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).
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.
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:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action configure_mgw -multitenantdbprofile
"C:\NewMGWConnectionProfiles\multitenant_respository_profile.xml"
-multitenantotdsprofile "C:\NewMGWConnectionProfiles\
multitenant_otds_profile.xml"
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.
<Exstream_Installation_directory>/<version>/Server/bin
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
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
Argument descriptions
-r <repository_type>
The type of repository. This must be one of the following:
-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.
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
<Exstream_Installation_directory>\global\security\keystore
\private
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).
<Exstream_Installation_directory>\<version>\Server\global
\security\certificatestore\trusted\authorities
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.
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.
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.
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.
Syntax
ss_tenantadmin.exe -action get_all_tenants -mtauser <user_name> -
mtapassword <password> -env <path_file>
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action get_all_tenants -mtauser
multitenantadmin@strs.role -mtapassword mtapass
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.
-env <path_file>
(OPTIONAL) The path and file name of the environment 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.
Syntax
ss_tenantadmin.exe -action get_tenant -tenantname <tenant_name> -
mtauser <user_name> -mtapassword <password> -env <path_file>
This example returns the ID of a tenant (if found), when receiving a tenant
name.
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
ss_tenantadmin.exe" -action get_tenant -tenantname tenant_AB
-mtauser multitenantadmin@strs.role -mtapassword mtapass
Argument descriptions
-tenantname <tenant_name>
The name of the tenant.
-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.
-env <path_file>
(OPTIONAL) The path and file name of the environment 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.
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
This example changes the connection profile to the tenant OTDS, the
connection profile to the tenant repository, and the tenant name.
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
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
Argument descriptions
-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.
-tenantname <tenant_name>
(CONDITIONAL) The name of the tenant you want to modify.
-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 <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>
(OPTIONAL) The path and file name of the environment 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.
For each tenant, you can add one connection profile for OTMM and one connection
profile for Content Server.
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
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"
Argument descriptions
-tenantID <tenant_ID>
(CONDITIONAL) The ID of the tenant. See “Obtaining the tenant ID ”.
Either the -tenantID or the -tenantname command is required.
-tenantname <tenant_name>
(CONDITIONAL) The name of the tenant.
Either the -tenantID or the -tenantname command is required.
-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.
-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.
-env <path_file>
(OPTIONAL) The path and file name of the environment 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.
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.
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.
...
</ws>
</configuration>
</connectionprofile>
<authenticationprofile type="..." name="..." guiname="OTMM
User" tenantID="...">
<configuration>
<simple xmlns="...">
<name>strsOtmmUser</name>
<password>strsOtmmUserPass</password>
</simple>
</configuration>
</authenticationprofile>
</securityprofiles>
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.
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.
</authenticationprofile>
</securityprofiles>
Syntax
Command:
"<Exstream_Installation_directory>\16.3.0\Server\bin\
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
Argument descriptions
-tenantID <tenant_ID>
(CONDITIONAL) The ID of the tenant. See “Obtaining the tenant ID ”.
Either the -tenantID or the -tenantname command is required.
-tenantname <tenant_name>
(CONDITIONAL) The name of the tenant.
Either the -tenantID or the -tenantname command is required.
-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"
-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.
-env <path_file>
(OPTIONAL) The path and file name of the environment 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.
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:
Note: The Exstream online help consists of one helpset for configuration and
another helpset for administration.
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:
• 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.
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
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:
<Context aliases="/docs/pi_hosted=C:/ot_docs/docs/pi_hosted">
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:
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>.
ccmprj
ccmevt
ccmpto
ccmstt
ccmsys
# <PRODUCT CODE>
ccmevt=ccmevt
ccmpto=ccmpto
ccmstt=ccmstt
ccmsys=ccmsys
Important
Verify that Tomcat services are not running when you complete these tasks.
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.
4. Start Tomcat.
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.
1. Extract the Test Help Page - Private Help Server.zip file to a working
directory.
Note: Always use the Extract all option when you extract OpenText online
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.
1. Stop Tomcat.
2. Extract the additional help files to the help root folder you created in “To create
the <help_root> directory:“.
Note: Always use the Extract all option when you extract OpenText online
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.
<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.
product: 'ccmprj',
version: 'v160200',
type: 'ofh',
module: 'ccmprj-h-cgd'
product: 'ccmsys',
version: 'v160200',
type: 'ofh',
module: 'ccmsys-h-agd'
• 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.
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.
2. In Server URL, enter the Private Help Server URL (see below).
2. In Server URL, enter the Private Help Server URL (see below).
http://docsapi.opentext.com/mapperpi
http://<host>:<port>/docsapimapper/mapperpi
For example:
http://dochost:8080/docsapimapper/mapperpi
• 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.
3. To make the license file available to the application, you need to restart the
application in Control Center.
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.
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.
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.
• 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:
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 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.
This shows the FastCopy source and destination pairs for the selected
Communications Server application.
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
When the host nodes are hidden, the applications are sorted by domain.
Creating a domain
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
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.
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.
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 WorkShop, users only have access to the templates, themes, images, texts and
rules in the domain they sign in to.
In StoryBoard and ReTouch, users only have access to the image, text and rule
resources in the domain they sign in to.
In Supervisor, users only have access to jobs and documents in the domains they
sign in to.
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.
Note: The multi-tenant, tenant, and document tracking repositories are outside
the scope of the domain.
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.
in ReTouch, Supervisor (from the Review view), and StoryBoard do not work
either.
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.
To create a 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.
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.
When you delete a domain, the repositories connected to the domain are not deleted.
To delete a domain
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.
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>"/>
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"/>
</cascadeapprovestate>
Example 12-3: Cascading approval used for all domains except one
<cascadeapprovestate defaultEnabled="false">
<applicationdomainexception name="development"/>
</cascadeapprovestate>
5. From Control Center, restart the service gateway(s) for the affected domains.
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.
This example shows a custom role that has access to the development
domain, but cannot access the testing and production 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)
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.
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.
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.
1. In Control Center, right-click the Repositories node, click New Repository, and
then click the repository type:
• Collector Archive
• Content Server
2. Enter a name and description for the repository and then click OK.
4. Click OK.
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
The port used for communication with the database server.
• 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.
• If SAP HANA is installed in single-container mode, you must leave this field
empty.
• 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
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.
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.
• 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.
Arguments
suffix
The suffix added to the authentication profile user name when logging on.
options
Custom JDBC connection string options.
options=EncryptionMethod=SSL;VALIDATESERVERCERTIFICATE=false;
suffix=u7zaf2wibw
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
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.
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.
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.
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.
3. Select the repository from the drop-down list.
4. Click Start to generate the scripts. When the scripts are generated, you can save
a local copy of the scripts.
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
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
• Do a sanity check to make sure the repository was created according to your
configurations.
• Since the scripts contain passwords, we recommend that you delete the scripts
after you have created the repository.
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.
Post requisites
• Do a sanity check to make sure the repository was created according to your
configurations.
• Since the scripts contain passwords, we recommend that you delete the scripts
after you have created the repository.
1. Connect to the database server as the user with ADMIN and SUPERUSER
privileges.
7. Create the “uuid-ossp” extension, for example with the command CREATE
EXTENSION "uuid-ossp".
Post requisites
• Do a sanity check to make sure the repository was created according to your
configurations.
• Since the scripts contain passwords, we recommend that you delete the scripts
after you have created the repository.
1. Open the appropriate SAP HANA tool. For example, SAP HANA HDBSQL.
Post requisites
• Do a sanity check to make sure the repository was created according to your
configurations.
• Since the scripts contain passwords, we recommend that you delete the scripts
after you have created the repository.
Prerequisites
• The repository must be created in the Repositories folder.
Post requisites
• After connecting a repository to a domain, you must restart the Exstream
applications (Communications Server applications, service gateways, etc.) in the
domain.
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.
In this section
• “Indexing” on page 135
• “Partitioning” on page 135
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.
• 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.
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.
<Base directory>\<Version>\root\config\database\<Version>\oracle
Where <Base directory> is the path specified for Exstream Projects during the
Communications Server installation. For example: C:\ManagementGateway
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
Communications Server application.
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.
You can add applications on your local host or on remote hosts that are part of the
site.
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.
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:
Where:
• <Base directory> – Is the path specified for Exstream Projects during the
Communications Server installation. For example: C:\ManagementGateway
• <Application name> – Is the name of the Communications Server application.
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
2. In the All Hosts list, select the host or hosts with the Communications Server
applications you want to deploy the Project to.
4. Select Deploy an export file from the file system, browse to the export file for
the Project, and click Next.
8. Click Finish.
See also
• “Starting, stopping, and restarting applications” on page 157
1. Right-click the domain for the Project and click Deploy export file.
3. In the Deploy wizard, click Deploy export file from CAS, and then click
Browse.
• 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.
8. Click Finish.
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.
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.
Redeploying a Project
You need to redeploy the export file or release package in the following scenarios:
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.
2. Follow the wizard. See “Deploying a Project from the CAS ” on page 141.
2. Click the (Item list) field and then click the button to the right of the field.
4. Click Add.
2. In the Source and Destination dialog box, specify the paths to the source and
destination directories, and click OK.
2. In the Source and Destination dialog box, specify the paths to the source and
destination directories and click OK.
To use FastCopy
1. Right-click the Source/Destination pair and select Edit Source. The source file
opens in an editor.
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).
Note: The services exposed by the application have the same version number
as the Project.
2. Select Application > Properties view, and the Project version number is
displayed.
Note: The version of a service is identical to the Project version specified when
exporting the Project.
3. In the Services view, the application's services are listed with their version
numbers.
Note: The service version is identical to the Project version deployed to the
Communications Server application.
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.
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.
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.
2. Click Go to.
• 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.
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).
<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>
<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>.
To use the Exstream web applications, you must add a service gateway. For failover
and load balancing reasons, you can add more service gateways.
When being accessed, a web client sends a request to the management gateway,
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
Related sections
• “Starting, stopping, and restarting applications” on page 157
• “Service gateway secure mode” on page 223
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.
3. In the Edit Value dialog box, update the port range start, and then click OK.
1. Right-click the service gateway, and then click Change Application Domain.
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).
7. Click OK.
To start an application
To stop an application
To restart an application
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.
• 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.
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.
The MGW Explorer dialog box opens when you select Host > Explore.
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:
You can add Task Scheduler applications on your local host or on remote hosts that
are part of the site.
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.
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.
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.
3. In the Service Configuration dialog box, add the task, see Tasks on page 159.
• 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.
Related sections
• “Starting, stopping, and restarting applications” on page 157
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.
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.
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.
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.
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.
In this example, a schedule is configured that triggers the action once every
second Monday to Wednesday, and once every hour Thursday to Sunday.
To delete an application
2. Click OK.
You can save the properties (name, description, version, etc.) for an application as a
text file.
To rename an application
• 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.
• Working directory
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
• Mini dump
See “Generating dump files for applications on Windows” on page 171.
Startup types
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.
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)
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:
For example:
• Name: verbose
• Value: jni
• Java System Property
A Java system property.
For example:
• Name: java.library.path
• Value: c:\mylibs
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.
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.
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.
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.
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.
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.
Note: The Log level option in the Configuration dialog box for Task Scheduler
applications is not applicable.
4. Click the Delete option and select Yes from the drop-down list.
2. In the Control Center tree view, right-click the application and select Log
Configuration. The Log Configuration dialog box opens.
4. Click the Time restrictions option and select Yes from the drop-down list.
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.
• Log console
• Log file
• Log database
2. In the Control Center tree view, right-click the application and select Log
Configuration. The Log Configuration dialog box opens.
3. Expand the Provider setting for the provider you want to configure.
Provider
Console Type=Console
File Type=File
Database Type=Database
Enabled
• Yes – Enables the provider.
• No – Disables the provider.
Type
• The provider type (read-only)
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
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.
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.
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.
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
3. In the Properties view, double-click Debug mode. The Edit Debug Mode dialog
box opens.
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).
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.
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.
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.
• In the Control Center tree view, right-click the host and select View Installed
Versions.
From the command line utilities you can administer Exstream applications, create
repositories, and add new tenants to Exstream.
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.
STRS_LOCATION=/usr/Exstream/Exstream-16.3.0.GA.<Build>
export STRS_LOCATION
<Exstream_Installation_directory>\<version>\Server\bin
<utility>.exe <arguments>
-servicename <name>
Where <name> is the service name.
-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.
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.
setstartuptype
Changes the startup type of the services.
Requires additional argument:
-startuptype <startuptype>
setstartupuid
Changes the server login user name.
-uid <username>
setservicetype
Sets the service type. Requires additional argument:
-servicetype <type>
setdescription
Sets the service description.
Requires additional argument:
-description <description>
create
Creates a new service instance.
Requires additional arguments:
-binpath <path>
-description <description>
-servicetype <servicetype>
-startuptype <startuptype>
setbinpath
Sets path to the service executable.
Requires additional argument:
-binpath <path>
getbinpath
Gets path to the service executable.
delete
Deletes the service.
Note: This can corrupt the system if important services are removed.
setarg
Sets a startup argument.
newarg
Creates a new startup argument for specified service.
Requires additional arguments:
-argname <argname>
-argvalue <argvalue>
argexist
Checks if a startup argument exists and returns the value of the argument (if it
exists).
Requires additional argument:
-argname <argname>
delsinglearg
Delete a single startup argument e.g. -demo. (A single argument is an argument
without a value).
Requires additional argument:
-argname <argname>
delbinaryarg
Deletes a binary argument, for example -wd /home/user/projects/
myproject/wd
Requires additional argument:
-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.
printarguments
Prints startup argument values for the service.
Requires additional argument:
-argname <argname>
getarg
Gets startup argument value.
Requires additional argument:
-argname <argname>
uninstall
Uninstalls all applications of the specified type. Also unregisters the applications
from the application domain.
Requires additional arguments:
-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.
-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:
-description <description>
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:
-argname <name>
The name of the startup argument.
-argvalue <value>
The value of the startup argument.
-applicationtype <type>
The type can be one of:
-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.
-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.
create
Creates a domain.
Requires additional arguments:
-territoryid <territoryid> or -territoryname <territoryname>
-territoryversion <version>
-territorydescription <description>
add_application
Adds an application to the domain.
Requires additional arguments:
-territoryid <territoryid> or -territoryname <territoryname>
-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.
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.
Requires additional argument:
-territoryid <territoryid> or -territoryname <territoryname>
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.
Requires additional argument:
-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.
Requires additional argument:
-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:
-territoryversion <version>
join
Moves an application between domains.
Requires additional arguments:
-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
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.
Requires additional arguments:
-jobid <jobid>
-frompos <pos>
-maxlen <max_bytes>
rename_territory
Renames the domain.
Requires additional argument:
-territoryname <territoryname>
deploy_domain_info
Exports the domain configuration to the specified application. You can only
specify applications on the management gateway machine.
Requires additional argument:
-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.
Requires additional arguments:
-db_user <user>
-db_pass <pass>
-db_type <dbrokerplus|tracker|queue|messagestore|statistics|
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.
Requires additional arguments:
-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
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.
Requires additional arguments:
-id <resource_id>
-idto <domain_id>
remove_resource_to_territory_relation
Removes the link from the domain to the resource.
Requires additional arguments:
-id <resource_id>
-idto <domain_id>
remove_resource
Removes a resource from the repository.
Requires additional argument:
-resource_id <ID>
get_resource_data
Retrieves the resource data.
Requires additional arguments:
-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.
Requires additional arguments:
-id <resource_id>
-idto <domain_id>
remove_resource_to_application_relation
Removes the link from the application to the resource.
Requires additional arguments:
-id <resource_id>
-idto <domain_id>
list_hotfixes
Lists hotfixes installed for the repository specified by the -db_type argument.
Requires additional arguments:
-db_user <user>
-db_pass <pass>
-db_type <dbrokerplus|tracker|queue|messagestore|statistics|
databaselog|tempstorage|archive>
db_apply_hotfixes
Applies available hotfixes to the specified repository.
Requires additional arguments:
-db_user <user>
-db_pass <pass>
-db_type <dbrokerplus|tracker|queue|messagestore|statistics|
databaselog|tempstorage|archive>
set_physicallayer
Selects the physical layer.
get_physicallayer
Retrieves the physical layer.
input_connectors
Pauses or resumes the input connectors of the specified application.
Requires additional arguments:
-appname <application>
-data <pause|resume>
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.
Requires additional arguments:
-appname <application>
-filename <path>
-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:
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:
-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
-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.
-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.
-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.
http://schemas.streamserve.com/uid/resource/property/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.
http://schemas.streamserve.com/uid/resource/property/application/
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
For more optional arguments available in all the utilities, see “Optional arguments
(all utilities)” on page 207.
-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.
Required arguments
-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.
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.
Requires additional argument:
-projectname <Project_Name>
Optional argument:
-verbose
-physicalplatform <physicalplatform>
The physical platform to deploy.
-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.
-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
For more optional arguments available in all the utilities, see “Optional arguments
(all utilities)” on page 207.
-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.
-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>
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.
For more optional arguments available in all the utilities, see “Optional arguments
(all utilities)” on page 207.
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.
-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.
-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.
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
Prerequisites
• A domain must be created.
Tip: To create a node for another type of repository (for example queue or
Document Broker) change the -content_type and -filename arguments.
Command
ss_territory.exe -user USERID -tenant TENANTNAME -pass PASSWD
-action add_application -territoryname MYAPPDOMAIN -appname
MYAPPLICATION -appvers <version> -apptype STRSCS
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:
\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>
Command
ss_scm.exe -user USERID -tenant TENANTNAME -pass PASSWD
-servicename MYSTRSSERVICE -action newarg -argname "-wd" -argvalue
"C:\Management Gateway\<version>\root\Applications\myapp"
Command
ss_scm.exe -user USERID -tenant TENANTNAME -pass PASSWD
-servicename MYSTRSSERVICE -action start
Command
ss_scm.exe -user USERID -tenant TENANTNAME -pass PASSWD
-servicename MYSTRSSERVICE -action newarg -argname "-
disableinconnectors" -action start
Command
ss_territory.exe -action input_connectors -appname "my_app" -data
"pause" -user "Administrator" -tenant TENANTNAME -pass "strs"
Command
ss_territory.exe -action input_connectors -appname "my_app" -data
"pause" -user "Administrator" -tenant TENANTNAME -pass "strs"
Command
ss_scm.exe -user USERID -tenant TENANTNAME -pass PASSWD
-servicename MYSTRSSERVICE -action isrunning
Command
ss_scm.exe -user USERID -tenant TENANTNAME -pass PASSWD
-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.
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.
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.
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.
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. 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.
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.
• 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.
<base>\<version>\root\applications\<SGWname>\wd
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.
sgw.allowedOrigins=<protocol>://
<webAppHost>:<port>,...,<protocol>://
<webAppHost>:<port>,<protocol>://<otdsHost>:<port>
sgw.allowedOrigins=http://10.168.166.56:8080,https://
10.169.156.66:8443,https://10.175.112.56:8443
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>
xFrame.options.allowFrom=http://10.168.166.56:8080 http://
10.148.146.45:8080
logging.level.=DEBUG
logging.level.com.streamserve=DEBUG
logging.file=servicegateway_rest.log
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.
4. Add the properties needed to enable a secure channel. For detailed information,
see the Apache Tomcat user documentation.
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):
server.ssl.key-store: keystore.p12
server.ssl.key-store-password: myPassword
server.ssl.keyStoreType: PKCS12
server.ssl.keyAlias: tomcat
6. Save application.properties and restart the service gateway.
<base>\<version>\root
sgw.allowedOrigins=<protocol>://
<webAppHost>:<port>,...,<protocol>://
<webAppHost>:<port>,<protocol>://<otdsHost>:<port>
sgw.allowedOrigins=http://10.168.166.56:8080,https://
10.169.156.66:8443,https://10.175.112.56:8443
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.
xFrame.options.allowFrom=<protocol>://<host>:<port>
xFrame.options.allowFrom=http://10.168.166.56:8080 http://
10.148.146.45:8080
logging.level.=DEBUG
logging.level.com.streamserve=DEBUG
logging.file=mgw_rest.log
Note: You must restart your Java application server each time you update the
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">
<!-- Management gateway URL(s) -->
<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>
<!-- Application URLs -->
<storyboard-url>http://10.168.166.56:8080/storyboard</
storyboard-url>
<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 -->
<analytics-url>http://10.168.166.56:8080/iportal/apps/
OTCCE16/Dashboards/OTCCE16.dashboard</analytics-url>
<!-- Friendly URLs -->
<url-mappings>
<url-mapping>
<url-pattern>t1</url-pattern>
<tenant>tenant1</tenant>
<domain>Dev</domain>
</url-mapping>
</url-mappings>
<!-- Deployment type -->
<deployment-type>dev</deployment-type>
</cc-web-app>
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
-Dcom.opentext.strs.config.path=C:/config/cc-webapp-config.xml
• 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.
<portalRoot>\<webAppName>\config
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.
}
},
"ObjectTree": {
"Enabled": true,
"Display": {
"Version": true,
"AllDropAreas": 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>
}
"Design": {
"Display": {
"Version": true|false,
"AllDropAreas": true|false
}
}
"ObjectTree": {
"Enabled": true|false,
"Display": {
"Version": true|false,
"AllDropAreas": true|false
}
}
• Enabled - Determines whether to display the object tree. Note that the object tree
in the Tools side bar is not affected.
• Version - Determines whether to display the version of the resources.
• 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.
"Sidebar": {
"Edit": {
"Default": "resources"|"preview"|"objectTree"
}
}
25.4.3 configuration_ipad.json
This file contains configuration keys for StoryBoard and ReTouch running on iPad
devices.
"Design": {
"Display": {
"Version": true,
"AllDropAreas": true
}
},
"ObjectTree": {
"Enabled": true,
"Display": {
"Version": true,
"AllDropAreas": 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>
}
"useTouchMode": true|false
"Design": {
"Display": {
"Version": true|false,
"AllDropAreas": true|false
}
}
"ObjectTree": {
"Enabled": true|false,
"Display": {
"Version": true|false,
"AllDropAreas": true|false
}
}
• Enabled - Determines whether to display the object tree. Note that the object tree
in the Tools side bar is not affected.
• Version - Determines whether to display the version of the resources.
• 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.
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.
{
"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 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.
"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"
},
...
"myunit": {
"systype": "float",
"units": [
{
"value": "pt",
"localizationkey": "UNIT.LABEL.PT"
},
{
"value": "px",
"localizationkey": "UNIT.LABEL.PX"
}
],
"validator": "positiveFloat"
}
"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.
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.
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.
"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"
},
...
"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).
"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"
},
...
"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
You must use either localizationkey or displayName to set the labels for the
properties.
Notes
• You can use localizationkey also for custom labels.
• displayName overrides localizationkey.
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.
"spacebefore": {
"type": "unit",
"localizationkey": "PROPERTY.LABEL.SPACE_BEFORE",
"processes": ["storyteller"]
},
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>",
"localizationkey": <localizationKey>,
}
Configuration keys
• <attributeName> - The name of the attribute.
• type - A type specified in the types section.
• localizationkey - Localized label for the attribute.
"type": "string",
"localizationkey": "ATTRIBUTE.LABEL.NAME"
},
"description": {
"type": "string",
"localizationkey": "ATTRIBUTE.LABEL.DESCRIPTION"
},
"type": {
"type": "string",
"localizationkey": "ATTRIBUTE.LABEL.TYPE"
},
...
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.
{ "attribute": "name" },
{ "attribute": "description" },
{ "attribute": "version" },
{ "attribute": "latestversion" },
{ "attribute": "lastModificationTime", "processes":
["storyteller"]}
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>": {
"localizationkey": <localizationKey>,
"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).
}
}
"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
You must use either localizationkey or displayName to set the labels for the
categories.
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.
"category": "flowcontrol",
"processes": ["storyteller"],
"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.
"objects": {
"theme": [
{
"category": "general",
"list": [
{ "attribute": "name" },
{ "attribute": "description" },
{ "attribute": "version" },
{ "attribute": "createdBy" },
{ "attribute": "creationTime" },
{ "attribute": "lastModificationTime" },
{ "attribute": "lockedBy" }
]
},
{
"category": "defaults",
"list": [
{ "property": "spacebefore" },
{ "property": "spaceafter" },
{ "property": "leftindent" }
]
}
],
...
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.
Process filter
If you want to hide a property or attribute for a specific template process you
can use the "processes": ["<processtype>"] key.
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.
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.
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.
"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).
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.
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.
"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"
},
...
"maximumNumber" : {
"max" : 150,
"errorMessage": "Enter a number less than 150"
},
"myNameValidator": {
"regex": "^\d\d\d[a-Z]+$",
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.
"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>",
...
]
},
{
"name": "<groupName>",
"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.
"templates": {
"TravelInsurance": {
"groups": [
{
"name": "Customer",
"settings": [
"customerName",
"customerEmail"
]
}
]
},
"EmailBody": {
"groups": [
{
"name": "Customer",
"settings": [
"customerName",
"customerEmail"
]
}
]
}
}
"EmailBody": {
"versions": [
{
"version": "1",
"groups": [
{
"name": "WebDoc",
"settings": [
"customerName",
"customerEmail"
]
}
]
},
{
"version": "2",
"groups": [
{
"name": "WebDoc",
"settings": [
"customerName"
]
}
]
}
],
"groups": [
{
"name": "WebDoc",
"settings": [
"customerEmail"
]
}
]
}
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": [
{
"name": "<groupName>",
"settings": [
"<property>",
...
]
},
{
"name": "<groupName>",
"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.
Note: If several themes configurations have the same <identifier>, the last
defined theme configuration is used.
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.
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.
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.
This section contains information about accessing and running the web applications.
Tip: Use a Java profiling tool to monitor and tune the Java memory settings
on a running Java application server.
• <port> – The port the Java application server listens to. Default is 8080.
• <workshop> – The WorkShop application name. Default is workshop.
<baseURL>[/hosted][/<view>]/tenant/<tenantKey>/domain/<domainKey>
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.
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.
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 &.
http://10.168.166.56:8080/workshop/resources/tenant/strs/
domain/Dom1%3Fheader=false%26navigation=false%26language=de_DE
Where:
• tenant – Leave as is.
• <tenantKey> – The tenant name or tenant ID.
• domain – Leave as is.
• <domainKey> – The domain name or domain ID.
<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.
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:
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 &.
http://10.168.166.56:8080/supervisor/jobs/tenant/strs/domain/
Dom1%3Fheader=false%26navigation=false%26language=de_DE
<baseUrl>/tenant/<tenantKey>/domain/<domainKey>/<appMode>.html%23/
<viewMode>/<themeId>/<previewFormat>/<simulationId>
%3Flanguage=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<storyboard>
• <host> – The host name or IP address of the computer that runs the Java
application server.
• <port> – The port the Java application server listens to. Default is 8080.
• <storyboard> – The StoryBoard application name. Default is storyboard.
• tenant – Leave as is.
• <tenantKey> – The tenant name or tenant ID.
• domain – Leave as is.
• <domainKey> – The domain name or domain ID.
• <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
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 &.
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
<baseUrl>/tenant/<tenantKey>/domain/<domainKey>/<appMode>.html%23/
<viewMode>/<documentTypeId>:<documentId>/<previewFormat>
%3Flanguage=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<retouch>
• <host> – The host name or IP address of the computer that runs the Java
application server.
• <port> – The port the Java application server listens to. Default is 8080.
• <retouch> – The ReTouch application name. Default is retouch.
• tenant – Leave as is.
• <tenantKey> – The tenant name or tenant ID.
• domain – Leave as is.
• <domainKey> – The domain name or domain ID.
• <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).
• 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 &.
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
<baseUrl>/[hosted]/tenant/<tenantKey>/domain/<domainKey>/resource/
<resourceID>?language=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<writer>
• <host> – The host name or IP address of the computer that runs the Java
application server.
• <port> – The port the Java application server listens to. Default is 8080.
• <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.
• tenant – Leave as is.
• <tenantKey> – The tenant name or tenant ID.
• domain – Leave as is.
• <domainKey> – The domain name or domain ID.
• resource – Leave as is.
• <resourceID> – The resource 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.
http://10.168.166.56:8080/writer/hosted/tenant/strs/domain/
Dom1/resource/Y3hyOi8_a...g5ZQ==?language=de_DE
<baseUrl>/[hosted]/tenant/<tenantKey>/domain/<domainKey>/resource/
<resourceID>?language=<langCode>
Where:
• <baseUrl> – http://<host>:<port>/<ruleeditor>
• <host> – The host name or IP address of the computer that runs the Java
application server.
• <port> – The port the Java application server listens to. Default is 8080.
• <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.
• tenant – Leave as is.
• <tenantKey> – The tenant name or tenant ID.
• domain – Leave as is.
• <domainKey> – The domain name or domain ID.
• resource – Leave as is.
• <resourceID> – The resource 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.
http://10.168.166.56:8080/ruleeditor/hosted/tenant/strs/
domain/Dom1/resource/Y3hyOi8_a...g5ZQ==?language=de_DE
http://<host>:<port>/<control>
Where:
• <host> – The host name or IP address of the computer that runs the Java
application server.
• <port> – The port the Java application server listens to. Default is 8080.
• <control> – The Control application name. Default is control.
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.
This section contains information about the services and the log files to be monitored
when running the web applications.
<baseDirectory>\<Version>\root\applications\<serviceGateway>\wd\
servicegateway_rest.log
Where:
logging.level.=INFO
logging.level.com.streamserve=INFO
logging.file=servicegateway_rest.log
<baseDirectory>\<Version>\root\mgw_rest.log
logging.level.=INFO
logging.level.com.streamserve=INFO
logging.file=mgw_rest.log
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
1. Go to the following directory in the portal root on the Java application server:
<deployed Supervisor folder>\WEB-INF\classes\log4j.properties
log4j.appender.file.File=C:/Users/<User name>/strswebapp_logs/
supervisor.log
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.
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
Server\bin\solr-integration-utility-16.4.0
• Linux
solutions/management/web/solr-integration-utility-16.4.0
cd <ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\setupSolr
a. createconfigs.cmd
b. createcores.cmd
c. runinitialimport.cmd
Note: Do not close the command prompt. If you do, Solr server will stop.
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.
• setProperties.cmd
Path: <ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\setupSolr
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.
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
cd <ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\scheduler
• To create a scheduler service for all tenants, run the following command:
solrindexer create -all (Windows) or sh solrindexer.sh create
-all (Linux).
To disable scheduling
Server\bin\solr-integration-utility-16.4.0\scaffold\conf
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
<mgwRoot>\applications\<appName>\wd\securityprofiles
...
<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
cd <ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\setupSolr
• Windows
Open Windows Services and restart solr_<GUID>_indexer.
• Linux
Run sh solrindexer.sh delete -all followed by sh solrindexer.sh
create.
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
Path: <ExstreamInstallation>\Server\bin\solr-integration-
utility-16.4.0\scaffold\conf
• solr_configuration-securityprofile.xml
Path: <mgwRoot>\applications\<appName>\wd\securityprofiles
Specify the proper username and password.
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
• Linux
solutions/management/web/solr-integration-utility-16.4.0
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.
When the installation is done you must copy the following jar files to solrHome\
dist\solrj-lib on each machine:
• 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.
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
For example:
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
• 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).
To disable scheduling
<solrUtility>\scaffold\conf
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.
<mgwRoot>\applications\<appName>\wd\securityprofiles
...
<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>
...
• Windows
Open Windows Services and restart solr_<GUID>_indexer.
• Linux
Run sh solrindexer.sh delete -all followed by sh solrindexer.sh
create.
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.scheduler.properties
Path: <solrUtility>\scaffold\conf
Edit the following properties:
• 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>...
To enable security
• Windows
Open Windows Services and restart solr_<GUID>_indexer.
• Linux
Run sh solrindexer.sh delete -all followed by sh solrindexer.sh
create.
• 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.
• solr.scheduler.properties
Path: <solrUtility>\scaffold\conf
Edit the following properties:
• solr.zkdigest.username: Proper username.
• solr.zkdigest.password: Proper password.
• solr_configuration-securityprofile.xml
Path: <mgwRoot>\applications\<appName>\wd\securityprofiles
Specify the proper username and password.
<solrUtility>\setupSolr
Note: It is only possible to display logs for applications in domains that are
linked to the log database.
3. In Control Center, make sure the applications have database logging enabled.
<portalRoot>\<webAppName>\config
Supervisor keys
"supervisor": {
"url": "https://mytomcathost:8443/supervisor",
"tenant": "cce",
"domain": "Testdomain"
}
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.
<Exstream_Installation_directory>\<version>\Server\solutions
\managament
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.
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 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.
• 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.
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.
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.
<?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>
<!-- ProcessingState -->
<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>
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.
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.
• 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).
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).
<Base directory>\<Version>\root\config\database\<Version>\sqlserver\
maintenance
Where <Base directory> is the path specified for Exstream Projects during the
Communications Server installation. For example: C:\ManagementGateway
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.
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.
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.
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.
coalesce_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
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.
• 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.
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:
BEGIN
maintenance.coalesce_indexes (
v_indexname_regexp=>'META_.*',
v_parallel_mb_breakpoint=>50,
v_maxrunhours=>12,
v_sort_area_size_mb=>100
);
END;
/
In this example, the indexes for all tables in the repository are coalesced
using the default options:
BEGIN
maintenance.coalesce_indexes ();
END;
/
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.
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.
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 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.
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 (
v_online=>false,
v_indexname_regexp=>'META_.*',
v_parallel_mb_breakpoint=>50,
v_maxrunhours=>12,
v_sort_area_size_mb=>100
);
END;
/
In this example, the indexes for all tables in the repository are rebuilt using
the default options:
BEGIN
maintenance.rebuild_indexes ();
END;
/
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.
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,
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;
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.
• 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.
...
<securityprofiles xmlns="..." owner="...">
<connectionprofile type="..." name="...">
<configuration>
<sql xmlns="...">
<vendor>sqlserver</vendor>
<hoststring>myhost</hoststring>
<port>1433</port>
<dbname>StrsQueue</dbname>
...
</sql>
</configuration>
</connectionprofile>
<authenticationprofile type="..." name="...">
<configuration>
<simple xmlns="...">
...
<securityprofiles xmlns="..." owner="...">
<connectionprofile type="..." name="...">
<configuration>
<sql xmlns="...">
<!--
<vendor>sqlserver</vendor>
<hoststring>myhost</hoststring>
<port>1433</port>
<dbname>StrsQueue</dbname>
-->
<!--Oracle settings-->
<vendor>oracle</vendor>
<hoststring>myhost</hoststring>
<port>1521</port>
<servicename>StrsQueue</servicename>
<schemaowner>SchemaOwner</schemaowner>
...
...
</sql>
</configuration>
</connectionprofile>
<authenticationprofile type="..." name="...">
<configuration>
<simple xmlns="...">
<name>User</name>
<password>MyPassword</password>
</simple>
</configuration>
</authenticationprofile>
</securityprofiles>
Post requisites
• You can check the Platform log in Control Center to verify that the maintenance
task works as expected.
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:
• 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.
In this example, the gather sample size is 5%, letting Oracle decide on the
parallelism.
BEGIN
maintenance.gather_stats (
v_estimate_pct=>5
);
END;
/
In this example, Oracle decides the sample size and the degree of
parallelism.
BEGIN
maintenance.gather_stats ();
END;
/
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.
The following parameters are available:
• 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.
• delete_stats
The procedure deletes optimizer statistics for the schema.
This section gives an example of how to gather system statistics via DBMS_STATS.
GATHER_SYSTEM_STATS.
END;
/
-- 2. Export old system stats from dictionary to created
stattable
BEGIN
DBMS_STATS.EXPORT_SYSTEM_STATS (
statown => 'XXMYOWNER',
stattab => 'XXMYTABLENAME',
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,
statown => 'XXMYOWNER',
stattab => 'XXMYTABLENAME',
statid => 'XXMYSTATID_NEW');
END;
/
-- 4. Import the gathered system stats from stattable to
dictionary
BEGIN
DBMS_STATS.IMPORT_SYSTEM_STATS (
statown => 'XXMYOWNER',
stattab => 'XXMYTABLENAME'
statid => 'XXMYSTATID_NEW');
END;
/
To explore an execution plan, you can use the SQL statement EXPLAIN PLAN.
• 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:
You must make regular backups of your Exstream repositories to protect the
repositories from data loss.
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.
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.
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.
Exstream-<Version>.GA.<Build>-<Platform>.tar.gz
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:
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:
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
Preparations
• UNIX - You must manually set STRS_JAVA_HOME to a suitable JRE (only if the
Exstream Setup has not been run previously).
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>
This example checks if there is a hotfix available for the tenant repository for
the tenant with the name strs.
Command:
"<Exstream_Installation_directory>\<version>\Server\bin
\ss_tenantadmin.exe" -action list_tenant_repository_hotfix
-tenantname strs -mtauser multitenantadmin@strs.role
-mtapassword mtapwd -dbadminusername sa -dbadminpassword
Changeoninstall2000
Command:
"<Exstream_Installation_directory>\<version>\Server\bin
\ss_tenantadmin.exe" -action apply_tenant_repository_hotfix
-tenantname strs -mtauser multitenantadmin@strs.role
-mtapassword mtapwd -dbadminusername sa -dbadminpassword
Changeoninstall2000
-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.
-dbadminusername <user_name>
On SAP HANA, Oracle, and Postgres, this is the schema owner.
On SQL Server you use the system administrator.
-dbadminpassword <password>
The password for the database administration user.
-env <path_file>
(OPTIONAL) The path and file name of the environment file.
-tenantID <tenant_ID>
(CONDITIONAL) The ID of the tenant. See “Obtaining the tenant ID ”.
Either the -tenantID or -tenantname is required.
-tenantname <tenant_name>
(CONDITIONAL) The name of the tenant.
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).
Note: You cannot use Control Center to apply hotfixes to the multi-tenant
repository or the tenant repositories.
• 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.
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.
3. Select the repository from the drop-down list.
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.
8. Click Close.
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:
-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.
In a command line window, browse to the directory with the script file (path
described above) and run the following command:
In a command line window, browse to the directory with the script file (path
described above) and run the following command:
F10C-484D-8A6F-6AA009DC1375}-securityprofile.xml" -u sa -p
password
1. Find the model file with the next revision corresponding to your present
database schema version in the following directory:
Windows - <Base directory>\<Version>\root\config\database\
UNIX - <Project location>/config/database/
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.
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.
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.
• 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.
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.
Installation steps
Prerequisites
• These steps assume the Exstream 16.3.x runtime and design components are
already installed and running.
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.
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.
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.
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).
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.
2. In the properties view, double-click the Profiler property, and then click
enabled.
• 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.
To configure 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.
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.
<provider value="http://schemas.streamserve.com/uid/component/
fileprofilerprovider/2.0">
<configuration>
<fileprofilerprovider xmlns="http://
schemas.streamserve.com/uid/component/fileprofilerprovider/
2.0">
Namespaces
You can filter on the namespaces and their sub-events.
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>
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.
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.
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.
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.
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.
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.
After the contents of the ZIP file are unpacked, the directory should contain the
following folders:
For more information about the database tables, see “Table descriptions”
on page 373.
After you make changes to the configuration files, you must restart the
Communications Server application for the changes to take effect.
• 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.
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>
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.
2. From the Value drop-down list, select ORACLE or IBM, depending on the vendor
of the installed JRE or JDK.
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.
• 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.
This image shows the tracking data for a job that generates one document
that contains two resources and is sent via two output connectors.
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.
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.
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.
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.
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.
• 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.
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.
-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.
-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.
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.
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.
1. Stop any running applications in the domains on the system you want to secure.
To disable security
1. Stop any running applications in the domains on the system you want to secure.
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.
• 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.
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:
Example 49-2: Generating a key with an alias name, and exporting the
key to a file
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.
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.
-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.
-keyfile
The name of the file created using the -export parameter.
-verbose
Enables detailed output.
-?
Displays help text with examples.
To enable security
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.
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.
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.
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 disable security
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.
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.
• 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.
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.
Example 50-2: Generating a key with an alias name, and exporting the
key to a file
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.
1. Browse to the directory that contains the certificate file you want to replace.
• 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.
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
<Installation directory>\<version>\Server\solutions\management\
mgmgateway.xml
<Installation directory>\<version>\Server\solutions\management\
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)
Solution on UNIX/Linux
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
<Installation directory>/<version>/Server/solutions/management/
mgmgateway.xml
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.
Solution on Windows
1. Run the security tool with the -disable command. See “To disable security“
on page 384.
2. Enable security with correct parameters. See “To enable security“ on page 383.
Solution on UNIX
1. Run the security tool with the -disable command. See “To disable security“
on page 390.
2. Enable security with correct parameters. See “To enable security“ on page 389.