Opentext™ Appworks™ Gateway: Installation and Administration Guide

OpenText™ AppWorks™ Gateway
Installation and Administration Guide
This guide explains how to install and configure the AppWorks

Gateway, and how to install and deploy AppWorks apps.
This guide does not replace the guides for OpenText products
that include AppWorks Gateway as part of their deployment,
such as eDOCS InfoCenter, Content Server Mobile and Tempo
Box. The installation guides for these products are available in
their respective product directories at OpenText My Support
(https://knowledge.opentext.com). These guides may include
additional or modified steps for installing the AppWorks
Gateway.
OTAG210300-IGD-EN-1
OpenText™ AppWorks™ Gateway
Installation and Administration Guide
OTAG210300-IGD-EN-1
Rev.: 2021-June-23
This documentation has been created for OpenText™ AppWorks™ Gateway CE 21.3.
It is also valid for subsequent software releases unless OpenText has made newer documentation available with the product,
on an OpenText website, or by any other means.
Open Text Corporation
275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1
Tel: +1-519-888-7111
Toll Free Canada/USA: 1-800-499-6544 International: +800-4996-5440
Fax: +1-519-888-0677
Support: https://support.opentext.com
For more information, visit https://www.opentext.com
Copyright © 2021 Open Text. All Rights Reserved.

Trademarks owned by Open Text.
One or more patents may cover this product. For more information, please visit https://www.opentext.com/patents.
Disclaimer
No Warranties and Limitation of Liability
Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However,
Open Text Corporation and its affiliates accept no responsibility and offer no warranty whether expressed or implied, for the
accuracy of this publication.
Table of Contents
1 OpenText AppWorks Gateway Overview ................................ 7
2 Installing the OpenText AppWorks Gateway .......................... 9

2.1 Prerequisites .................................................................................. 10
2.2 Configuring Apache Tomcat for the AppWorks Gateway .................... 10
2.3 Installing the AppWorks Gateway ..................................................... 12
2.4 Connecting the AppWorks Gateway to a Database ........................... 13
2.5 Connecting the AppWorks Gateway to OTDS ................................... 15
2.5.1 Connecting to OTDS ....................................................................... 15
2.5.2 Deploying AppWorks Gateway and OTDS in a Non-SSL
Environment ................................................................................... 17
3 Upgrading the OpenText AppWorks Gateway ...................... 19

3.1 Upgrading from AppWorks Gateway 16.x and 21.x ............................ 19
3.2 Upgrading from AppWorks Gateway 1.2.x ........................................ 22
3.3 Adding a URL Rewrite to AppWorks Gateway 16.x ............................ 23
3.4 Upgrading Apache Tomcat .............................................................. 24
3.5 Uninstalling AppWorks Gateway ...................................................... 27
4 Securing the AppWorks Gateway .......................................... 29

4.1 Configuring the AppWorks Gateway for HTTPS ................................ 30
4.1.1 Create a Java Keystore File ............................................................. 31
4.1.2 Generate a Certificate Signing Request (CSR) .................................. 34
4.1.3 Sign the CSR File using Active Directory Certificate Services ............. 35
4.1.4 Add the Root CA Certificate to the AppWorks Gateway Server ........... 35
4.1.5 Add the Keystore to the AppWorks Gateway ..................................... 36
5 Getting Started with the AppWorks Gateway ....................... 37

5.1 Installing Apps, Services, Components and Connectors .................... 37
5.2 Enabling Apps, Services, Components and Connectors ..................... 38
5.3 Viewing Details and Downloading Apps, Services, and Components .. 39
5.4 Filtering the Runtime and User Audience .......................................... 39
5.5 Distributing the Mobile Clients .......................................................... 42
5.6 Distributing the Desktop Clients ....................................................... 42
5.7 Connecting to the AppWorks Gateway Server URL for Mobile and
Desktop .......................................................................................... 45
5.8 Configuring a Desktop Client for HTTPS ........................................... 46
5.8.1 Export the Root CA Certificate of the AppWorks Gateway Server ....... 46
5.8.2 Convert the CRT file to a PEM File ................................................... 47
5.8.3 Add the PEM file to the Application Data folder ................................. 47
5.9 Uninstalling the Desktop Clients ....................................................... 48
5.10 Configuring the AppWorks Desktop Client to use an HTTP Proxy ....... 49
OTAG210300-IGD-EN-1 Installation and Administration Guide iii

Table of Contents
6 AppWorks Gateway Settings .................................................. 51

6.1 General Settings ............................................................................. 51
6.2 MDM Settings ................................................................................. 53
6.3 Mail Settings ................................................................................... 54
6.4 Temp File Settings .......................................................................... 55
6.5 Notifications Settings ....................................................................... 55
6.6 Audit Settings ................................................................................. 56
7 Creating a Proxy Rule ............................................................. 57
8 Enabling Push Notifications for Firebase Cloud

Messaging ................................................................................ 59
8.1 Sending a Test Notification .............................................................. 61
9 Adding, Editing, and Deleting Users ..................................... 63

9.1 Adding Users in the AppWorks Gateway .......................................... 63
9.2 Editing Users in the AppWorks Gateway ........................................... 65
9.3 Updating the AppWorks Gateway Admin User Information ................. 65
9.4 Updating the AppWorks Gateway Admin User Password ................... 66
9.5 Deleting Users in OTDS .................................................................. 66
10 Monitoring and Managing User’s Access ............................. 67

10.1 Monitoring Client Management ......................................................... 67
10.2 Performing a remote wipe ................................................................ 68
11 Deploying the AppWorks Gateway in a Cluster ................... 69
12 Deploying AppWorks Gateway for Multi-Tenancy ............... 71
13 Deploying AppWorks Gateway as a Container ..................... 73

13.1 Before You Start ............................................................................. 73
13.2 Deploying AppWorks Gateway with Docker ...................................... 74
13.3 Deploying AppWorks Gateway with Helm ......................................... 76
13.3.1 Building an AppWorks Gateway Init Container Image for App
Deployment .................................................................................... 77
13.3.2 Deploying the AppWorks Gateway Container .................................... 78
13.3.3 About the values.yaml file ................................................................ 79
13.3.3.1 Updating the Image Settings ............................................................ 79
13.3.3.2 Updating the Postgres Settings ........................................................ 80
13.3.3.3 Updating the OTDS Settings ............................................................ 81
13.3.3.4 Updating the AppWorks Gateway (awg) Settings .............................. 81
13.3.3.5 Updating the replicaCount setting ..................................................... 83
13.3.3.6 Updating the Proxy Settings ............................................................. 83
13.3.3.7 About the System and Resource Settings ......................................... 83
iv OpenText™ AppWorks™ Gateway OTAG210300-IGD-EN-1

Table of Contents
13.3.4 Upgrading a Deployed AppWorks Gateway Container ....................... 84

13.3.5 Checking the AppWorks Gateway Deployment Status ....................... 84
14 Frequently Asked Questions .................................................. 87
OTAG210300-IGD-EN-1 Installation and Administration Guide v

Chapter 1
OpenText AppWorks Gateway Overview
The OpenText AppWorks Gateway is an Enterprise Application Development and

Management platform. The AppWorks Gateway allows you to quickly and easily
build purpose-specific apps for the Enterprise using familiar Web technologies. The
AppWorks Gateway uses OpenText™ Directory Services to manage your users.
The OpenText AppWorks Gateway (OTAG) engine component is the single point of
contact between all clients and your production server, for example, Content Server.
It forwards all incoming operation requests, queues data requests to reduce server
load, and handles notifications to all registered client applications.
Communication between the AppWorks Gateway engine and your production

server is done through HTTP or HTTPS.
During the installation process, you connect the AppWorks Gateway to a database
such as Microsoft SQL Server or Oracle, and to OpenText Directory Services (OTDS)
to manage and authenticate your users. As a final step, you connect to your
production server and install the applications, components, and services in the
AppWorks Gateway.
The AppWorks Gateway can also be run in a containerized environment. OpenText

provides Docker images that can be downloaded with Docker YAML files and
Kubernetes Helm charts and scripts.
OTAG210300-IGD-EN-1 Installation and Administration Guide 7

Chapter 2
Installing the OpenText AppWorks Gateway
In a production environment, we recommend the following setup, where OTDS, the

AppWorks Gateway and the OpenText product are all installed on separate servers.
Mobile Client
Your Production Server

Desktop Client
Apache Tomcat
(OpenText AppWorks Gateway)
OpenText Directory
Active Directory/LDAP
Services
Figure 2-1: AppWorks Gateway Architecture
Active Directory/LDAP
The Active Directory or LDAP server that you may be using to manage your
users. This is optional.
OpenText Directory Services

The OpenText Directory Services server that manages your users.
Your production server

The server hosting an OpenText product, for example, Content Server or
eDOCS.

Chapter 2 Installing the OpenText AppWorks Gateway
Apache Tomcat
The server hosting Apache Tomcat, with AppWorks Gateway deployed and
configured, and your apps installed and enabled.
Mobile Client
An Apple® or Android™ device.
Desktop Client
A computer running a Windows or macOS® operating system.
2.1 Prerequisites
Before you start, review theAppWorks Gateway Release Notes, available from My
Support (https://knowledge.opentext.com/knowledge/llisapi.dll/open/58916144) The
Release Notes contain important information about supported environments and the
compatibility of AppWorks Gateway with OpenText products, such as Content
Server.
The AppWorks Gateway requires the following software.
• Java Development Kit.

• Apache Tomcat
Important
Install the AppWorks Gateway and Apache Tomcat on a dedicated server.
Do not install OTDS, or an OpenText product, such as Content Server on
the same server as the AppWorks Gateway.
• A database to connect to. Create a schema and an associated schema admin user
in your Microsoft SQL Server, MySQL, Oracle, Oracle RAC, PostgreSQL, or SAP
HANA database.
• An OTDS installation. OTDS centralizes user and group identity information and
manages single sign on (SSO) between OpenText components.
2.2 Configuring Apache Tomcat for the AppWorks

Gateway
To configure Apache Tomcat for the AppWorks Gateway:
1. Ensure you have installed the required software. For details, see “Prerequisites”
on page 10.
2. Stop the Apache Tomcat service.
3. Navigate to the <Tomcat_Home>\bin folder.
4. Double-click the Tomcat executable file, for example, Tomcat9w.exe and do the
following:
10 OpenText™ AppWorks™ Gateway OTAG210300-IGD-EN-1

2.2. Configuring Apache Tomcat for the AppWorks Gateway
a. Click the Java tab.

b. In the Initial memory pool box, type 0 or leave blank.
c. In the Maximum memory pool box, type 4096.
d. Click OK.
Figure 2-2: Apache Tomcat Java options
5. Start the Apache Tomcat service to make sure your Tomcat installation starts
correctly with these new settings.

2.3 Installing the AppWorks Gateway

Before you start, read the “Prerequisites” on page 10 and complete the “Configuring
Apache Tomcat for the AppWorks Gateway” on page 10 section.
To install the AppWorks Gateway:
2. Navigate to the <Tomcat_Home>\conf folder and back up the server.xml and

context.xml files.
Important
The AppWorks Gateway installation package includes modified versions
of the server.xml and context.xml files. If you have customized the
server.xml or context.xml files, and you want to retain those changes,
you must add them to the versions of the files supplied by the AppWorks
Gateway.
3. Download the AppWorks Gateway installation package from AppWorks

Gateway Downloads (https://developer.opentext.com/webaccess/#url=%2Fawd
%2Fresources%2Fdownloads&tab=501).
4. Extract the contents of the otag-gateway–21.3.zip file to the root of the

Apache Tomcat folder, for example, C:\Program Files\Apache Software
Foundation\Tomcat 9.0.
5. Optional If you plan on running SSL, comment out or remove the following tag in
the server.xml file.
<Listener className="org.apache.catalina.core.AprLifeCycleListener" SSLEngine="on"/>
6. Start the Apache Tomcat service.
Tip: Navigate to the <Tomcat_Home>\logs folder and open the

catalina.<yyyy-mm-dd> file. When you see a line containing INFO:
Server startup in <55278> ms, you can start to configure the AppWorks
Gateway.

2.4. Connecting the AppWorks Gateway to a Database
2.4 Connecting the AppWorks Gateway to a

Database
In a browser, type http://<Tomcat_Host>:<port>/gateway. Use the IP address or
fully qualified domain name of the server on which you are running Apache Tomcat
for the Gateway. Do not use http://localhost:8080.
A configuration page is displayed to enable you to connect AppWorks Gateway to a

database.
Important
After you have specified a database and completed the installation, you cannot
choose a different database for AppWorks Gateway. Therefore, ensure that you
are connecting to the database you intend to use for your environment.
To connect to a database:
1. In Step 1: Database Configuration you connect AppWorks Gateway to a

database. The database that you use must be created prior to completing the
steps below. Create a blank database and AppWorks Gateway will create the
required tables.
Figure 2-3: Connecting to a database
2. From the Select Database Vendor drop down, choose from the following
database options:
• Microsoft SQL Server

• MySQL – In the MySQL Workbench, select the Options File from the
Navigator panel and choose the Networking tab. Locate the max_allowed_
packet_length variable and change to 1024 MB. You may need to install the
JDBC driver (Connector/J) and place it in your <Tomcat_Home>\lib folder.
After adding the driver, restart the Apache Tomcat service.
• Oracle – You may need to download a JDBC driver JAR file and place it in
your <Tomcat_Home>\lib folder. After adding the driver, restart the Apache
Tomcat service.
• Oracle RAC – You may need to download a JDBC driver JAR file and place
it in your <Tomcat_Home>\lib folder. After adding the driver, restart the
Apache Tomcat service.
• PostgreSQL – To connect the AppWorks Gateway to a PostgreSQL database,
you need to add the following line to the C:\Program Files\PostgreSQL\
11\data\pg_hba.conf file.
# TYPE DATABASE USER ADDRESS METHOD
host all all 0.0.0.0/0 md5
• SAP HANA
• Custom Connection String
Caution
The Custom Connection String option is intended for experienced
database administrators only and must be used with caution.
3. In the Username and Password boxes, type the credentials for an admin user of
your database.
4. When connecting to an Oracle Real Application Clusters database, complete the

following:
• In the Load Balance area, choose if you would like to enable client side load
balancing.
• In the Cluster Host box, type the virtual cluster name that you chose when
you created the RAC database.
• In the Port box, type the port. The default port for Oracle is 1521.
• In the Service Identifier box, type the virtual service name that you chose
when you created the RAC database.
See Figure 2-3. This information is added to the opentext.properties file, in

the <Tomcat_Home>\conf folder. The details are encrypted in this file.
5. Click Configure Database Connection and wait for a confirmation that the
connection is established.

2.5. Connecting the AppWorks Gateway to OTDS
2.5 Connecting the AppWorks Gateway to OTDS

After you have connected AppWorks Gateway to a database, the next step is to
connect to OTDS.
Important
• Once you have defined the connection to OTDS, you cannot make changes
to it. This means that you cannot switch from one OTDS instance to
another.
• We recommend that you do not install OTDS on the same server as
AppWorks Gateway. Also, OTDS should be on a separate server to an
OpenText product such as Content Server or eDOCS DM.
2.5.1 Connecting to OTDS

To connect to OTDS:
1. In Step 2: OTDS Configuration, you connect AppWorks Gateway to an

existing instance of OTDS.
Figure 2-4: Connecting to OTDS
2. Complete the required information, as follows:
• Gateway Admin Username and Password – Defines the AppWorks

Gateway administrative user account that will be created in Directory
Services. The default username is otag. The password requirements depend
on your OTDS global password policy. By default, the password must be
alphanumeric with 8 characters.

• OTDS server url – The URL of the Tomcat server that is running OTDS. Do
not use http://localhost:8080.
• OTDS Administrative Account Username and Password – The credentials
for an OTDS Admin user.
• Resource Name and Gateway User Partition Name – Creates an AppWorks
Gateway Resource and User Partition in OTDS with the names provided.
The default values are OTAG and otag respectively.
Note: If you have other AppWorks Gateway installations that connect

to the OTDS service, the values for Gateway Admin Username,
Gateway User Partition Name, and Resource Name must be unique
for each installation.
3. Click Configure OTDS. The configuration is complete when you are prompted
to sign in to the AppWorks Gateway.
Before you sign in, open a second browser window and go to the Directory
Services web client at http://<Tomcat_Host>:<port>/otds-admin/.
4. Sign in as the OTDS admin user using “[email protected]” as the username

and the OTDS Administrative Account Password you defined in step 2.
5. From the SETUP menu, click Partitions.
6. For the otag partition, select View Members from the Actions menu. Next,
select the Groups tab.
7. Select the otagadmins group, then select Edit Membership, and click Add
Member.
8. Search for the [email protected] member and from the search results box,
click Add Selected to add the member to the otagadmins group.
9. Sign in to the AppWorks Gateway as the OTAG administrative user.

The OTAG administrative user is the user you defined in the Gateway Admin
Username and Password fields in step 2.

2.5. Connecting the AppWorks Gateway to OTDS
2.5.2 Deploying AppWorks Gateway and OTDS in a Non-SSL

Environment
Where both OTDS and the AppWorks Gateway are running in a non-SSL
environment, you need to make a change in OTDS so that Directory Services no
longer checks for SSL.
If you deployed the AppWorks Gateway in a non-SSL environment, you will see the
following error in the gateway.log file in the <Tomcat_Home>\logs folder:
** HTTP 403 encountered during resource authentication. This is
likely to be because OTDS is not configured to permit
authentication traffic across unsecured (non-SSL/TLS) transports.
If this is a development environment, you may work around this
security feature by ensuring OTDS has the System Attribute
"directory.auth.EnforceSSL=false". **
To configure OTDS and AppWorks Gateway for non-SSL environments
1. Sign in to the Directory Services web client at http://<Tomcat_Host>:<port>/

otds-admin/.
2. From the SETUP menu, click System Attributes.
3. Click Add.
4. Type directory.auth.EnforceSSL in the Name field, and false in the Value field.
5. Click Save.

Chapter 3
Upgrading the OpenText AppWorks Gateway
You can upgrade to AppWorks Gateway 21.3 from all previous 16.x and 21.x
versions.
If your AppWorks Gateway installation is prior to 16.0, for example, 1.2.1, there is no
migration procedure to preserve your current environment. You must remove
AppWorks Gateway 1.2.x, then install AppWorks Gateway 21.3. For further details,
see “Upgrading from AppWorks Gateway 1.2.x” on page 22.
After upgrading to 21.3 from AppWorks Gateway 1.2.x, you may want to ensure
that users continue to access any configured services with the URL they used prior
to the upgrade. For further details see “Adding a URL Rewrite to AppWorks
Gateway 16.x” on page 23.
3.1 Upgrading from AppWorks Gateway 16.x and

21.x
Use this procedure to upgrade from an AppWorks Gateway 16.x or 21.x version to
AppWorks Gateway 21.3.
Note: When upgrading to AppWorks Gateway 21.3, from 16.x,or 21.x you
must decrypt then re-encrypt the opentext.properties file in the
<Tomcat_Home>\conf folder. The steps to do this are described in the following
procedures.
To upgrade the AppWorks Gateway:
1. Stop the Apache Tomcat service that hosts the AppWorks Gateway installation.
2. Back up the database that is associated with the AppWorks Gateway

installation. This is the database that you connected to when you installed
AppWorks Gateway.
3. Back up the Apache Tomcat directory where AppWorks is installed. This

directory contains various folders and files, for example the conf, gateway,
otds and webapps folders.
4. Navigate to the <Tomcat_Home>\conf directory, and rename the server.xml

file to, for example, server.bak.
This step is only required if you have made custom changes to the server.xml
file. The upgrade overwrites the server.xml file in the <Tomcat_Home> \conf
directory.
5. Navigate to the <Tomcat_Home> directory and do the following:

Chapter 3 Upgrading the OpenText AppWorks Gateway
a. Delete the gateway folder.

b. Delete the contents of the following folders:
• work\Catalina\localhost
• temp
• tmp
• logs
6. Open the webapps folder and remove any folders and .war files that belong to
AppWorks Gateway services. For example, if there is an AppWorks Gateway
service named gateway-service, delete the /webapps/gateway-service
folder, and the /webapps/gateway-service.war file if it exists.
After completing the upgrade, when you start the AppWorks Gateway, the
folders and .war files for the services will be recreated.
If you have made any custom modifications or if any custom configuration files
exist in the /webapps/<service>/ folders, these must be manually recreated
from the /webapps folder that you backed up in Step 3.
If you do not complete this step when upgrading, you will see a message
indicating that app migration has failed in the gateway-otag.log file. To
resolve this, you must undeploy then redeploy the service. To do this:
a. In the AppWorks Gateway that is running the service, click the Services
section of the Admin Menu.
b. Disable, then re-enable the service.
You can download the .zip service deployment file from the AppWorks
Gateway prior to disabling it.
7. Configure Redirect URLs for OAuth clients in OTDS, as follows:
a. Log in to OTDS as an administrator.

b. Search for the OAuth client created for the partition during installation.
c. Click Properties from the Actions menu option.
d. Click the Redirect URLs tab.
e. On the button bar click Add.
f. In the Redirect URLs text box, type http.* and click Save.
g. On the button bar click Add.
h. In the Redirect URLs text box, type https.* and click Save.
i. On the button bar click Save. For further information, see the chapter on
OAuth Clients in the OpenText Directory Services - Installation and
Administration Guide (OTDS-IWC).


3.1. Upgrading from AppWorks Gateway 16.x and 21.x
9. If you have made custom changes to the server.xml file, use the server.bak
back up file to retain those changes in your upgraded installation.
10. Encrypt the opentext.properties file in the <Tomcat_Home>\conf folder,
using the Database Encryption Tools available from My Support (https://
knowledge.opentext.com/knowledge/llisapi.dll/open/58916144). The opentext.
properties file in the <Tomcat_Home>\conf folder stores the details of the
database for the AppWorks Gateway Installation. Proceed as follows:
• If you know the database details, encrypt the opentext.properties file

using the 21.3 Database Encryption Tool. See the Readme file supplied with
the 21.3 Database Encryption Tool for details.
• If you do not know the database details, decrypt the opentext.properties
file, using the Database Decryption Tool and re-encrypt the file using the
Encryption Tool, as described below.
11. To decrypt and re-encrypt the opentext.properties file take the following
steps:
a. Take a backup of the opentext.properties file.

b. Download the Database Decryption and Database Encryption Tools from
My Support:
• If you are upgrading from AppWorks Gateway 16.x, use the Database
Decryption tool in the 16.7 software folder in My Support. If you are
upgrading from 21.1, use the Database Decryption Tool in the 21.1
folder in My Support.
• Use the Database Encryption Tool in the 21.3 software folder in My
Support.
c. Decrypt the opentext.properties file using the decrypter.jar file in the
Database Decryption Tool, as follows:
i. Expand the appworks–gateway–<Version No>–decryptor-tool.zip

file.
ii. Copy the opentext.properties file from <Tomcat_Home>\conf folder
to the root of the AppWorks-Gateway–<Version No>-decryptor-tool
folder.
iii. Decrypt the opentext.properties file using the decrypter jar file:
$ java -jar awg-support-tool-decrypter-<Version No>.jar -d
opentext.properties
This decrypts the opentext.properties file and outputs a
decrypted.properties file.
d. Encrypt the decrypted.properties file using the 21.3 Database
Encryption Tool, as follows:
i. Expand the appworks–gateway–21.3–encryptor-tool.zipfile.

ii. Copy the decrypted.properties file to the root of the AppWorks-
Gateway–21–3-encryptor-tool folder.

iii. Rename the decrypted.properties to opentext.properties.

iv. Encrypt the opentext.properties file using the encrypter jar file:
$ java -jar awg-support-tool-encrypter-21.3.jar -e
opentext.properties
This encrypts the opentext.properties file and outputs an
encrypted.properties file.
v. Rename the encrypted.properties file to opentext.properties.
vi. Place the opentext.properties file in the <Tomcat_Home>\conf
folder, overwriting the existing file.
13. In a browser, type http://<Tomcat_Host>:<port>/gateway and sign in to the

AppWorks Gateway. All of your applications and settings should be present.
3.2 Upgrading from AppWorks Gateway 1.2.x

Use this procedure to upgrade to AppWorks Gateway 21.3 from a release prior to
16.0, for example, 1.2.1. The steps are as follows:
1. Create a new database schema for AppWorks Gateway.

2. Uninstall AppWorks Gateway 1.2.x:
3. Install and configure AppWorks Gateway 21.3.
Note: When you upgrade from AppWorks Gateway 1.2.x to 21.3, you cannot
reuse the existing values for Resource Name, Gateway User Partition Name,
Gateway Admin Username and OTDS Administrative Account Username.
Step 2: OTDS Configuration of the installation of AppWorks Gateway 21.3
will not complete and you will need to repeat the process, supplying new
values.
To create a new database schema for AppWorks Gateway 21.3:
• Sign in to your database management tool, and create a new database schema
for AppWorks Gateway 21.3.
Note: If you created a database schema for AppWorks Gateway 1.2.x, do

not delete the schema until your 21.3 installation is complete and you have
confirmed that it works as expected.
To uninstall AppWorks Gateway 1.2.x:
2. The safest way to uninstall the AppWorks Gateway 1.2.x is to reinstall Apache
Tomcat. If you reinstall Apache Tomcat, make sure you reconfigure Tomcat for
the AppWorks Gateway 21.3. For details, see “Configuring Apache Tomcat for

3.3. Adding a URL Rewrite to AppWorks Gateway 16.x
the AppWorks Gateway” on page 10. However, if you have other software
running Tomcat and you would prefer not to uninstall it, do the following:
a. Make sure you have a backup of the following files:
• gateway.war – located in the <Tomcat_Home>\webapps folder.

• opentext.properties – located in the <Tomcat_Home>\conf folder.
b. Navigate to the <Tomcat_Home>\conf folder and delete the existing
opentext.properties file.
c. Navigate to the <Tomcat_Home>\webapps folder and delete the existing
gateway.war file and gateway folder.
d. Navigate to the <Tomcat_Home>\temp folder and delete all of the files in the
folder.
e. Navigate to the <Tomcat_Home>\tmp folder and delete all of the files in the
folder.
f. Navigate to the <Tomcat_Home>\lib folder and delete any AppWorks
Gateway 1.2.x libraries.
g. Navigate to the <Tomcat_Home>\work\Catalina\localhost folder and
delete all of the files in the folder.
To install AppWorks Gateway 21.3:
• For details, see “Installing the AppWorks Gateway” on page 12.
3.3 Adding a URL Rewrite to AppWorks Gateway

16.x
In AppWorks Gateway 16.x both the Gateway and the Administration Console are
accessed via the root context of the Apache Tomcat installation.
This is a change from AppWorks Gateway 1.2.x, where users were taken to /
webaccess from https://[appworksurl]/, from where they could access the
services that were configured there, for example, Tempo Box or Tempo Social.
When upgrading to 16.xfrom AppWorks Gateway 1.2.x, you may want to ensure
that users continue to access any configured services with the URL they used prior
to the upgrade. To do this, you can use URL rewriting to perform a URL redirect to
the /content folder. The following steps describe how to redirect your users
from http://host.opentext.com to http://host.opentext.com/content by
downloading and configuring a Java Web filter for the Apache Tomcat installation.

2. Go to the http://www.tuckey.org/urlrewrite/ website.
3. Click the urlrewritefilter-4.0.3.jar link in Step 1 of the Install process. To review
the documentation for the Web Filter, click Documentation at the top of the
page, then click the link to the 4.0 User Manual.

4. Save the .jar file to <Tomcat_Home>/gateway/WEB-INF/lib.

5. Add the following to the <Tomcat_Home>/gateway/WEB-INF/web.xml file:
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
<async-supported>true</async-supported>
</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
Note: The UrlRewriteFilter must be the first filter in the web.xml file.
6. Create a urlrewrite.xml file in <Tomcat_Home>/gateway/WEB-INF/, with the

following contents:
<urlrewrite>
<rule>
<name>redirect from root</name>
<condition name="host" operator="equal">host.opentext.com</condition>
<from>^/$</from>
<to type="permanent-redirect" last="true">http://host.opentext.com/content/</to>
</rule> </urlrewrite>
Note: This configuration will redirect from http://host.opentext.com to

http://host.opentext.com/content, which will mask the Gateway
Administration Console. To access the console, the host's IP address, or
some other alias must be entered into the browser address bar.
3.4 Upgrading Apache Tomcat

This section provides details on upgrading to various versions of Apache Tomcat.
This assumes that you have installed AppWorks Gateway with Apache Tomcat, and
now wish to upgrade the version of Apache Tomcat. This might be because you
wish to upgrade just Apache Tomcat to a later version, without making any changes
to AppWorks Gateway. Or, you might want to upgrade both Apache Tomcat and
the AppWorks Gateway at the same time. The following procedure describes how to
upgrade from 8.x to 9.0.x, for Windows and Linux. See the AppWorks Gateway Release
Notes for details of the supported version of Apache Tomcat.
To upgrade from 8.x to 9.0.x (Windows)
1. Download the latest version of the Apache Tomcat 9.0.x Service Installer for
Windows from https://tomcat.apache.org/download-80.cgi.
2. Stop the Apache Tomcat service via the Windows Services Control Panel.
3. Run the downloaded Tomcat 9.0.x Windows Installer to install the updated
version of Tomcat as a Windows Service.

3.4. Upgrading Apache Tomcat
Notes
• Choose a different installation location to the existing Tomcat

Installation and a different service name.
• Do not start the new Tomcat service yet.
4. Set the required JAVA_OPTIONS for the new Tomcat service. See
“Configuring Apache Tomcat for the AppWorks Gateway” on page 10 for
details.
5. Make a backup copy of the <Tomcat_Home> folder as well as the new

<Tomcat_Home> installation folder.
6. Copy the following folders and or files from the existing <Tomcat_Home> folder
to the new <Tomcat_Home> installation folder:
• From the existing <Tomcat_Home>\conf\ folder to the new <Tomcat_Home>

\conf\ folder:
– awg-keystore
– awg-node.properties
– server.xml
– opentext.properties
• From the existing <Tomcat_Home> folder, copy the entire webapps\ folder to
the new <Tomcat_Home>. When asked, accept to merge the directories.
• From the existing <Tomcat_Home> copy the entire gateway\ folder to the
new <Tomcat_Home> location.
Note: If you have made any edits to your existing server.xml, for
example for SSL connectors, copy across your key store and update the
path in the server.xml in the new Tomcat install location.
7. Start the Apache Tomcat service and examine the logs for successful startup.
8. Carry out a full regression test of your upgraded Tomcat installation.
9. Once your regression testing has been successfully completed, uninstall the old
Tomcat service and delete the old <Tomcat_Home> folder structure along with
the backups taken during the above process.
To upgrade from 8.x to 9.0.x (Linux)
1. Download the latest version of the Apache Tomcat 9.0.x Service Installer for
Linux from https://tomcat.apache.org/download-80.cgi.
2. Make a new directory in /tmp:

bash mkdir /tmp/tc.
3. Extract the new Tomcat installation into a directory in /tmp:

bash tar -zxvf apache-tomcat-9.0.<x>.tar.gz -C /tmp/tc
4. Back up the following files and directories:
• From the current <Tomcat_Home>:
– setenv.sh in the bin/ directory

– conf/ directory
– gateway/ directory
– otds/ directory
• In the lib/ directory:
– otag-tomcat-listener-16.<x>.jar
5. Delete the bin/ and lib/ directories from <Tomcat_Home>
6. In the <Tomcat_Home>/webapps/ directory, delete the following directories:
• docs/
• manager/
• ROOT/
• examples/ (if installed)
• host-manager/ (if installed)
7. Copy the following directories from the temporary directory of the new Tomcat
to the following directories:
• bin/
• lib/
• webapps/
8. Copy the backed up setenv.sh file to the bin/ directory.
9. Copy the saved files from the lib/ directory into the <Tomcat_Home>/lib/
directory.
10. Check file permissions.
11. Start the Apache Tomcat service and examine the logs for successful startup.

3.5. Uninstalling AppWorks Gateway
3.5 Uninstalling AppWorks Gateway

This section describes how to uninstall AppWorks Gateway 16.x. The assumptions
are that you are removing AppWorks Gateway from a server, and there is no
requirement for you to retain any of the components of the installation. You do not
need to retain the OTDS partition for the installation or the database that you
configured for use with the installation. If you are upgrading the AppWorks
Gateway, or the version of Apache Tomcat, see “Upgrading the OpenText
AppWorks Gateway“ on page 19 for details.
Important
The following description does not include any steps to back up the installation
you are removing. When you take these steps you are removing the AppWorks
Gateway, the otag partition in OTDS, and any AppWorks data in the database
that you created for use with the installation.
To uninstall AppWorks Gateway
1. Navigate to the <Tomcat_Home> folder and delete the gateway folder.
2. Navigate to the <Tomcat_Home>\conf folder and delete the opentext.

properties file.
3. Navigate to the <Tomcat_Home>\webapps folder and contents of the folder,

except for the ROOT folder.
4. Navigate to the <Tomcat_Home>\temp folder and delete all of the files in the
folder.
5. Navigate to the <Tomcat_Home>\tmp folder and delete all of the files in the
folder.
6. Navigate to the <Tomcat_Home>\lib folder and delete any AppWorks Gateway

libraries.
7. Navigate to the <Tomcat_Home>\work\Catalina\localhost folder and delete

all of the files in the folder.
8. Sign in to the Directory Services web client at <http://Tomcat_Host>:<port>/

otds-admin/.
9. Delete the otag partition. This is the default partition name. You may have
supplied a different name when you installed the AppWorks Gateway.
10. Delete the database schema that you created for use with the AppWorks
Gateway.

Chapter 4
Securing the AppWorks Gateway
Using the AppWorks Gateway in debug mode
The AppWorks Gateway can be run in debug mode. Debug mode allows for more
detailed error information to be returned to clients. The AppWorks Gateway should
not be left running in debug mode during production use, to avoid the
communication of detailed error messages.
Troubleshooting the AppWorks Gateway at debug or trace logging level
When troubleshooting the AppWorks Gateway, you can adjust the logging level to
debug or trace. See “Frequently Asked Questions“ on page 87.
When debug-level or trace-level logging is enabled, sensitive configuration data may

be written to the log files. Ensure that debug-level and trace-level logs are securely
disposed of when they are no longer required.
Terminating AppWorks Gateway at the connector layer
Always terminate the AppWorks Gateway with SSL/TLS at the Apache Tomcat
connector layer.
Without SSL/TLS at the Tomcat layer, the Want Secure Cookies setting will not
work correctly. If the Want Secure Cookies setting is enabled, cookies issued by the
AppWorks Gateway will contain the “secure” flag if possible, providing SSL/TLS
termination is performed on the Tomcat connection. The Want Secure Cookies is on
the General Settings page (Settings > General Settings).
Security considerations for Apache Tomcat
Follow industry best practices for securing the Apache Tomcat server. Consider the
following resources:
• https://tomcat.apache.org/tomcat-9.0-doc/security-howto.html
• https://www.owasp.org/index.php/Securing_tomcat
• https://geekflare.com/apache-tomcat-hardening-and-security-guide
Protection against Malicious File Uploads
Protection against malicious file upload must use a layered approach – the
environment and the application must be protected. Protection should be enforced
on the server side and – very importantly - on the client side of the application. At
infrastructure level, ensure the following:
• Virus protection is active and up-to-date on all client systems

Chapter 4 Securing the AppWorks Gateway
• Client systems are using a supported browser with the latest updates. Older
browsers have fewer protections. To protect against issues with file locking
OpenText recommends that you use the following settings:
– Antivirus scanning is performed “scan-on-write” for files and directories not

excluded from antivirus scans.
– If on-demand or scheduled scanning occurs when the system is operating,
files may be locked by the antivirus application. As a result, OpenText
recommends that the following folders are not scanned:
○ The External File Store (EFS)

○ Log and tmp folders
○ Folder(s) where the DBMS database and log files are located
○ Search functionality directories
○ The volume in the search administration section.
4.1 Configuring the AppWorks Gateway for HTTPS

OpenText recommends using SSL to increase the security of the system. This section
explains how to configure SSL on Apache Tomcat to allow the AppWorks Gateway
to work with the HTTPS protocol. The steps are as follows:
1. Create a Java keystore file.

2. Create a Certificate Signing Request (CSR).
3. Sign the CSR File using Active Directory Certificate Services
4. Add the Root CA Certificate to the AppWorks Gateway Server
5. Add the Keystore to the AppWorks Gateway.
Important
In this procedure we are using Active Directory Certificate Services (ADCS).
ADCS allows you to build, in-house, a public key infrastructure, with public
key cryptography, digital certificates, and digital signature capabilities, using
Microsoft technology. There are many alternative services that you can use,
and which may be more appropriate for your organization. The use of ADCS
here is for the purpose of providing an “end-to-end” example to explain the
procedures for enabling the AppWorks Gateway for HTTPS. There is no
requirement to use ADCS. The implementation and maintenance of security
protocols at your organization can be complex and should only be attempted
by experienced personnel.

4.1. Configuring the AppWorks Gateway for HTTPS
4.1.1 Create a Java Keystore File

You can use the Java keytool.exe command line utility to complete these steps.
However, to present the required changes as clearly as possible, we are using
KeyStore Explorer. KeyStore Explore is an open source utility that provides a
graphical user interface for the keytool key and certificate management
functionality. KeyStore Explorer is available from http://keystore-explorer.org.
To create a Java keystore file:
1. Start KeyStore Explorer, click File > New and select JKS for the keystore type.
2. Click OK.
3. Click Tools > Generate Key Pair, and select RSA for the encryption algorithm.

4. Click OK.
5. In the Generate Key Pair Certificate dialog box, select the required Validity
Period.
6. Click Add Extensions.
7. Click to display the Add Extension Type dialog box.
a. Select Subject Alternative Name.

b. Select the Critical Extension check box.

8. Click OK.
9. In the Subject Alternative Name Extension dialog box, click and do the
following:
a. For General Name Type, select DNS Name.

b. In the General Name Value field, enter the fully-qualified domain name of
the server that you want to deploy.
c. Click OK until the Generate Key Pair Certificate dialog box is re-
displayed.
10. Click the Edit Name button and complete the Name dialog box with
details relevant to your Active Directory Certificate Server.
11. Click OK until you are prompted for an alias name. You can leave the alias
name unchanged and click OK.
12. In the New Key Pair Entry Password dialog box, type a password.

You now have a functioning keystore for your required host. Next, you need to
generate a Certificate Signing Request (CSR) that you can submit to your Certificate
Authority (CA) for signing.
4.1.2 Generate a Certificate Signing Request (CSR)

To generate a Certificate Signing Request (CSR)
1. Right-click on the generated key pair, and select Generate CSR to create a
certificate signing request file.
2. In the Generate CSR dialog box, select the Add certificate extensions to
request check box.
3. Click Browse and choose a name and location for the CSR file and click Save.
4. In the Generate CSR dialog box, click OK.
The next step is to sign the CSR that you have created, and this guide describes how
to do this using Active Directory Certificate Services. This process can be used if you
are building an internal system and do not have access to an external CA, such as
VeriSign. If you submit the CSR to an external CA, you should receive both the
signed certificate for your server and also the root CA certificate from the Certificate
Authority that was used to sign the new certificate. If the CA uses intermediate
chain certificates, you will also need these.
Caution
It is crucial that you have the full chain of certificates used to sign your new
certificate. Without the complete chain, SSL communication will fail.

4.1.3 Sign the CSR File using Active Directory Certificate

Services
Note: These steps offer a worked example using Active Directory Certificate
Services. Your organization may use a third-party Certificate Authority to
return a signed certificate file.
To sign the CSR file using ADCS:
1. In a text editor, open the certreq.csr file that you created in the previous
section.
2. On your ADCS server, open a web browser and navigate to https://<domain_

name>/certsrv/certrqxt.asp. The Submit a Certificate Request or Renewal
Request page is displayed.
3. Copy and paste the contents of the CSR file from your text editor into the Saved
Request box for Base-64–encoded certificate request (CMC or PKCS #10 file or
PKCS #7).
4. Click Submit.
5. In the Certificate Issued page, click Download certificate chain and save the
file to your hard disk.
6. Return to KeyStore Explorer, right-click on the generated key pair and select
Import CA Reply > From File.
7. Browse to the downloaded certificate.
8. Save the keystore as a JKS file.
4.1.4 Add the Root CA Certificate to the AppWorks Gateway

Server
In this step, you update the Java certificate store for the Apache Tomcat instance that
is hosting the AppWorks Gateway.
To add the root CA certificate to the Java certificate store:
1. On the ADCS server, open a web browser and go to https://<domain_name>/

certsrv/certrqxt.asp. The Download a CA Certificate, Certificate Chain, or
CRL page is displayed.
2. Click the Download CA certificate chain link.
3. On the AppWorks Gateway server, navigate to the cacerts file in the <Java_
Home>\lib\security folder.
4. Open the cacerts file in KeyStore Explorer. The default password for the
cacerts file is “changeit”.

5. Select Tools > Import Trusted Certificate.
6. Navigate to your downloaded CA certificate chain.
7. Save the cacerts file.
8. Copy the cacerts file back into the <Java_Home>\lib\security folder on the
AppWorks Gateway server.
4.1.5 Add the Keystore to the AppWorks Gateway

The Apache Tomcat instance that will host the AppWorks Gateway needs to be
configured to use the chain of certificates from the new keystore so that the runtimes
can communicate using SSL to the AppWorks Gateway.
By following these steps, your Apache Tomcat server can still run in normal mode at
the same time on port 8080 with HTTP.
To add the new keystore to AppWorks Gateway:
1. Stop the Apache Tomcat server.
2. Place your generated JKS file in the <Tomcat_Home>\conf folder on the

AppWorks Gateway server.
3. In the <Tomcat_Home>\conf folder, open the server.xml file in a text editor.
4. Locate the <Connector> element with port=”<8443>” as seen below.



5. Uncomment the property and add the name of the JKS keystore file, and the
password you provided when you created it. The following is the new section
with the additional line highlighted:

<Connector port=”<8443>” protocol="org.apache.coyote.http11.Http11NioProtocol"

maxThreads=”150” SSLEnabled="true" scheme=”https” secure=”true”
keystoreFile="/conf/keystore.jks" keystorePass="opentext123!"
clientAuth=”false” sslProtocol=”TLS” />
6. Save and close the file, and then restart the Apache Tomcat server.
7. To check the setting, in a browser, type https://<Tomcat_Host>:<8443>.

Chapter 5
Getting Started with the AppWorks Gateway
The AppWorks Gateway is a deployment and management tool for applications,

components, and their associated services and connectors.
5.1 Installing Apps, Services, Components and

Connectors
The AppWorks Gateway offers flexibility over the apps and components that your
users can access. Apps are separate, independent features in the app runtime client.
Because apps are independent from one another, you can allow access to some apps
and disable the others. For example, with OpenText ECM Everywhere you can allow
access to the Personal Workspace, Enterprise Workspace, and Favorites apps, and
hide the Feeds app from your users.
Apps may rely on an associated service. Therefore, you need to make sure all of the
services are installed and enabled in the AppWorks Gateway. If you want to prevent
your users from accessing a particular app, you must disable the app in the
AppWorks Gateway. If you disable a service and not the associated app, users will
still be able to see the app on their mobile device or desktop computer. However,
users will not be able to use the app.
Components offer additional functionality for apps. For example, with ECM
Everywhere, the Object Details Viewer component allows users the ability see the
properties, categories, and audit information for objects in the Enterprise Workspace
app.
Each app, component, and service in the AppWorks Gateway shows summary,
settings, statistics, and history details. Altering the settings might negatively impact
performance. Only experienced administrators should modify these settings.
To install an app, service, component or connector:
1. Download the app, service, component or product bundle. A product bundle is

a ZIP file of several apps, services, components, and/or connectors. Product
bundles typically have a file extension of .otagbundle. For example, tempo_
16.2.otagbundle.
2. Sign in to the AppWorks Gateway as an admin user.
3. In the Admin Menu, click Install an app.
4. Click Browse and navigate to the app, component, service, or product bundle.
Tip: You can also drag and drop the file onto the indicated region.

Chapter 5 Getting Started with the AppWorks Gateway
5. Click Install Package and follow the on-screen instructions. By default, all apps,
services, and components are disabled. In order to give your users access to an
app, you need to enable the app as well as the associated service.
5.2 Enabling Apps, Services, Components and

Connectors
Once you have installed an app or service and their associated components and
connectors, you enable it, to make it available to the clients.
To enable an app, service, component or connector:
• In the AppWorks Gateway, select one of the following from the Admin Menu:
• Click Apps in the Installed section, and then click Enable for the apps you
want your users to have access to. When an app is disabled, users will not
see the app in the runtime client on their mobile devices.
• Click Desktop Apps in the Installed section, and then click Enable for the
apps you want your users to have access to. When an app is disabled, users
will not see the app in the runtime client on their desktop computers.
• Click Components in the Installed section, and then click Enable for all of
the components you installed.
• Click Services in the Installed section, and then click Enable for all of the
services that you installed. When a service is disabled, your users will not be
able to access their content. If the associated app is still enabled, users will
still see the app in the runtime client on their mobile devices. However, it
will be unusable.
• Click Connectors in the Installed section, and then click Enable for all of the
connectors that you installed.
To enable all installed apps, services, components and connectors:
• To enable all the apps, services, components and connectors that you have
installed, click All from the Installed section of the Admin Menu, and then
click Enable All at the top of the page.

5.3. Viewing Details and Downloading Apps, Services, and Components
5.3 Viewing Details and Downloading Apps,

Services, and Components
To view details and download apps, services, and components:
1. In the Admin Menu, click the required type from the Installed section, for
example, Apps or Components.
2. Click the Show settings for this app icon for the item.
3. Click the Summary, Settings or Audience tabs to display relevant information,
as follows:
• Summary – View the version number, installed date, and the date the
feature was last updated.
You can also download the feature by clicking the Download link. Some
apps have associated components and services that you also need to
download for the app to work in another AppWorks
Gateway. Click Components or Services in the Admin Menu and verify if a
service or component is present. Based on the name and description of the
component or service, it may not be obvious if they affect the downloaded
app.
• Settings – These are settings that are specific to the app or service. Use
caution when changing and always check the documentation for the app or
service.
• Audience – Filter the app based on runtime, user, or group. For details, see
“Filtering the Runtime and User Audience” on page 39.
5.4 Filtering the Runtime and User Audience

By default, all enabled apps will appear in every runtime that is connected to the
AppWorks Gateway. One example of a runtime is the OpenText AppWorks app that
you can download from the Apple App Store (http://www.apple.com/ca) or Google
Play (https://play.google.com). In addition to this, all enabled apps will be available
to every user or group that is present in your database. To prevent this, you can
filter each app to only appear in the runtime that you specify. You can also specify
that an app is only available to select users or groups.
To filter the runtime audience:
1. In the Admin Menu, click Apps from the Installed section.
2. Click the Show settings for this app icon for the app that you want to filter.
3. Click the Audience tab and do one of the following:
• To display the app in all runtimes installed on the user’s client, select the
Available in all runtimes check box.

• To display the app in a certain runtime client only, clear the Available in all
runtimes check box and select the check box next to the appropriate
runtime.
• To display the app in a runtime that is not displayed, click Runtimes from
the Management section of the Admin Menu. Complete the displayed fields
and click Add. Repeat steps 2 – 3, only this time select the check box next to
the new runtime.
Figure 5-1: Filtering the Runtime Audience
4. Click Save.
To filter the users and groups who can see an app:
1. In the Admin Menu, click Installed > Apps.
2. Click the Show settings for this app icon for the app that you want to filter.
3. Click the Audience tab.
4. Click the User/Group/Partition Audience link and do one of the following:
• To display the app in the runtimes of all users, select the Available to all
users check box.

5.4. Filtering the Runtime and User Audience
Figure 5-2: Filtering Users and Groups
• To display the app in the runtimes of a specific user, group or partition, clear
the Available to all users check box. In the Search for Users/Groups/
Partitions box, type the first few letters of the name of the user, group or
partition. Select one or more check boxes for the users, groups or partitions
that you want to be able to access the app.
Figure 5-3: Selecting from the results of a search

5. Click Save.
5.5 Distributing the Mobile Clients

You can inform your users of the mobile client they need to install for your product
by emailing them a link to the app. Before attempting this procedure, make sure you
have an SMTP mail server properly configured in your AppWorks Gateway. For
details, see “Mail Settings” on page 54.
Note: AppWorks Gateway 21.3 requires the 16.6 versions of the iOS and
Android mobile clients. The 16.6 mobile clients are compatible with 16.x
versions of the AppWorks Gateway. However, push notifications, including
remote wipe, are only available when both the AppWorks Gateway and the
mobile clients are on release 16.5 or later. This is due to the replacement of
Google Cloud Messaging (GCM) with Firebase Cloud Messaging (FCM).
AppWorks Gateway 16.5 and later supports FCM only.
To distribute mobile clients:
2. In the Admin Menu, click Mobile Client Distribution from the Management
section.
3. In the Send Distribution Email region, select a runtime that will be included in
the email.
4. In the same region, you can choose to send an email to one or more groups in
OTDS, to specific users by entering their email address, or to a list of users that
are in a CSV file.
5. Click Send Email.
5.6 Distributing the Desktop Clients

The AppWorks Gateway desktop clients for Windows and macOS® are available
from the Downloads page of the AppWorks Developer web site (https://
developer.opentext.com).
To install the Desktop Client using the MSI Windows installer
1. Download and run the Windows MSI installation file.
2. Confirm that you have read the OpenText End User License Agreement, and
click Next to display the Custom Setup dialog.

5.6. Distributing the Desktop Clients
Figure 5-4: Installing the Desktop Client – Custom Setup
3. Click Next to confirm that you want to install the Desktop Client and the
Desktop Client shortcuts in the default location, or click Browse to choose an
alternative location.
4. Click Install to complete the installation.

Figure 5-5: Installing the Desktop Client – Ready to Install
5. Click the OpenText AppWorks Gateway shortcut from the Windows Start menu
to display the Setup page, and define the following:
• Server Address – The address of the AppWorks Gateway Server URL.

When you installed the AppWorks Gateway, you entered this URL in the
General Settings page.
• Enable SSO – Select the check box if you are using SSO.
6. Click Save.
To perform an unattended install of the Windows Desktop Client:
You can run the Desktop Client Windows installer silently from a Command Prompt
program, passing the filename in a Command Prompt line option. The Command
Prompt must be run with administrator level privileges, also known as an elevated
prompt.
1. From the Command Prompt, navigate to the location of the MSI installer that
you have downloaded.
2. The following command will silently install the AppWorks Gateway Desktop
Client for Windows, and set the Server Address to http://localhost:8080.

5.7. Connecting to the AppWorks Gateway Server URL for Mobile and Desktop
MSIEXEC /i "OpenText AppWorks Desktop-16.2.0.71.msi" /qn /log log.txt

GATEWAY_URL="http://localhost:8080"
Note: Ensure that the above command is on one line.
To install the Desktop Client on macOS®:
1. Mount the macOS® Disk Archive.
2. Read and accept the OpenText End User License Agreement.
3. Drag the AppWorks Gateway Desktop App file to your Applications folder.
4. Launch the OpenText AppWorks Gateway Desktop Client to display the Setup
page. Define the Server Address, Enable SSO and Debug Mode fields, as
described above.
5. Click Save.
5.7 Connecting to the AppWorks Gateway Server

URL for Mobile and Desktop
When using the OAuth 2.0 or OTDS non OAuth 2 authentication flow in the
AppWorks Gateway, ensure that the AppWorks Gateway Server URL is resolvable
from clients running the mobile or desktop clients. The AppWorks Gateway Server
URL is specified in Settings > General Settings.
If you receive an Unable to connect error message, when the desktop connects to the
AppWorks Gateway Server URL, you can troubleshoot the issue by taking the
following steps:
1. On the machine where the desktop client is installed, or on a mobile device, open
a browser and navigate to http://<appworks-server-url:port>/v3/admin/
auth/loginurl.
2. The response displays a value for loginUrl. This is the URL that the desktop
client must be able to resolve to, for the InfoCenter Desktop client to connect to
the AppWorks Gateway.
3. Enter the loginUrl value in a browser on the desktop or mobile device and check
the response. You should get the OpenText login page proxied via the
AppWorks Gateway. If the OpenText login page is not displayed, check the
format of the AppWorks Gateway Server URL, and change to be a fully qualified
domain name.

5.8 Configuring a Desktop Client for HTTPS

To configure a desktop client for HTTPS, you add a PEM file to the machine on
which the desktop client is installed. You can then change the server address in the
client to HTTPS and connect to an AppWorks Gateway server that is enabled for
HTTPS. See “Securing the AppWorks Gateway“ on page 29.
The steps to enable the desktop client for HTTPS are as follows:
1. Export the root CA certificate of the AppWorks Gateway server.

2. Convert the CRT file to a PEM File.
3. Add the PEM file to the Application Data folder.
Note: The process for installing the desktop client for specific OpenText
products may differ from the steps shown here. Refer to the installation guide
for each product to check for additional or modified steps.
5.8.1 Export the Root CA Certificate of the AppWorks

Gateway Server
In this step, you export the root CA certificate from the AppWorks Gateway server
as a CRT file, using a browser. In this description, we are suing Mozilla Firefox.
To export the root CA certificate on the AppWorks Gateway server:
1. Open Firefox and navigate to the HTTPS address of the AppWorks Gateway
login page at https://<Tomcat_Host>:<port>/gateway. In “Securing the
AppWorks Gateway“ on page 29 you enabled the AppWorks Gateway server
for HTTPS.
2. Click the padlock icon next to the address bar.
3. Click the chevron icon to the right of the web site address.
4. Click More Information and in the Security tab, click View Certificates.
5. In the Details tab, examine the certificate chain in the Certificate Hierarchy box.
6. Select the root CA certificate and click Export.
7. Save the root CA certificate as a CRT file to your local drive.

5.8. Configuring a Desktop Client for HTTPS
5.8.2 Convert the CRT file to a PEM File

In this step, you convert the CRT file to a PEM file using OpenSSL commands.
To convert the CRT file to a PEM file:
1. Open a command prompt window and navigate to the location of the root CA
CRT file that you exported in “Export the Root CA Certificate of the AppWorks
Gateway Server” on page 46.
2. Type the following OpenSSL command to convert the CRT file to a DER file.
Replace the CRT input and DER output values in the example below with your
file names.
openssl x509 -in appworks-AW-EXAMPLE-CA-2.crt -out appworks-AW-EXAMPLE-CA-2.der -
outform DER
3. Type the following OpenSSL command to convert the DER input file to a PEM
output file. Replace the DER input value with your file name.
openssl x509 -in appworks-AW-DEV-OTDS2-CA-2.der -inform DER -out ca.cert.pem -
outform pem
Important
The output file must be called ca.cert.pem.
5.8.3 Add the PEM file to the Application Data folder

In this step, you add the PEM file that you created in “Convert the CRT file to a PEM
File” on page 47 to the Application Data folder on the machine where you installed
the desktop client.
To add the PEM file to the Application Data folder:
1. Navigate to the \AppData\Roaming\appworks-desktop\<app-type>\ folder.
2. Create a folder called certs.
3. Add the ca.cert.pem file to the certs folder.
4. Open the desktop client and ensure that the server address in the Settings page
is the HTTPS address of your AppWorks Gateway server.
5. Restart the client. The OpenText login page is now displayed over HTTPS.
Notes
• On a Mac, create the certs folder in ~/Library/Application/Support/

appworks-desktop/<app-type>/.

• These steps assume that there are no intermediate certificates in the

certificate chain. If there are intermediate certificates, then you need to
combine the PEM files for the root CA certificate and the intermediate
certificates into a single file, called ca.cert.pem. For example, if you have a
root CA certificate and two intermediate certificates, assemble the ca.cert.
pem file as follows:
-----BEGIN CERTIFICATE-----
<Certificate for INTERMEDIATE CERTIFICATE AUTHORITY 2>
-----END CERTIFICATE-----
<Certificate for INTERMEDIATE CERTIFICATE AUTHORITY 1>
<Certificate for ROOT CERTIFICATE AUTHORITY>
5.9 Uninstalling the Desktop Clients

To uninstall the Windows Desktop Client:
1. Using the Windows uninstall functionality, remove the Desktop Client, as

follows:
• For Windows 8.1, navigate to Programs and Features, select the OpenText
AppWorks Desktop application and click Uninstall.
• For Windows 10, navigate to Apps & features, select the OpenText
AppWorks Desktop application and click Uninstall.
2. Open Windows Explorer, navigate to the following folder and delete the
contents:
C:\Users\<your user name>\AppData\Roaming\appworks-desktop\standard
Note: For the eDOCS InfoCenter desktop client, navigate to the following
folder and delete the contents:
C:\Users\<your user name>\AppData\Roaming\appworks-desktop\edocs-infocenter
To uninstall the macOS Desktop Client
1. Drag the Application from the Applications folder to the Trash folder.
2. Use the Finder or Terminal to navigate to the following folder and delete the
contents:
~/Library/Application\ Support/appworks-desktop/standard
Note: For the eDOCS InfoCenter desktop client, navigate to the following
folder and delete the contents:
~/Library/Application\ Support/appworks-desktop/edocs-infocenter

5.10. Configuring the AppWorks Desktop Client to use an HTTP Proxy
5.10 Configuring the AppWorks Desktop Client to use

an HTTP Proxy
To enable the AppWorks Desktop Client to use an HTTP proxy, you must be aware
of the two ways in which the AppWorks Desktop Client picks up HTTP forward
proxy configurations. In the diagram below, the Renderer process is a repackaged
Chromium browser, while the Main process is repackaged NodeJS runtime.
Both the Renderer process and the Main process must make outgoing HTTP
connections. The Renderer process uses HTTP connections provided by the
Chromium framework, while the Main process uses HTTP connections provided
under the NodeJS framework.
To pick up HTTP forward proxy configuration, the Renderer process uses the built-
in proxy configuration of the host operating system. The Main process picks up its
HTTP configuration from HTTP_PROXY and HTTPS_PROXY environment
variables. You must ensure that both configuration methods are employed at the
same time to configure the AppWorks Desktop Client to use an HTTP proxy.

Chapter 6
AppWorks Gateway Settings
This chapter describes the settings that are available for the following categories:
• General – Specify the URL of the AppWorks Gateway server and the OTDS
server, and choose from various authentication options.
• MDM – Specify the settings for mobile device management, for example,
whether to enable or disable client tracking.
• Mail – Specify the SMTP settings to use when sending emails from the Gateway.
• Temp File – Specify where to store temporary data files, and how long to leave
files on the system.
• Notifications – Determine the settings to use when sending messages to client
applications.
6.1 General Settings

To define the general settings:
2. In the Admin Menu, click Settings > General Settings.
3. Define the following:
• AppWorks Gateway Server URL – The URL that clients and providers use
to reach this server. Use the fully qualified host name of the server. Do not
use http://localhost:8080. This URL is also needed for links in external
invitations and for auto-configuration of the OTSync Connector. The
OTSync Connector provides a connection, authentication handling, proxy
mappings and trusted provider key registration for OpenText Tempo Box.
Note: If you change the AppWorks Gateway Server URL, stop and
restart the Apache Tomcat service.
• Want Secure Cookies – When enabled, cookies issued by the AppWorks
Gateway will have their “secure” flag set. This setting has no effect for
responses on a non-secure transport, for example HTTP. The Want Secure
Cookies setting is selected by default.
• Session Token Cleanup Interval (s) – Timed out OTAG session tokens will
be cleared from memory periodically given this duration.
• Session Token Timeout (s) – Session tokens generated by the OTAG layer
will become invalid after this period of inactivity.

Chapter 6 AppWorks Gateway Settings
• Enable automatic sign-out – Enables automatic sign-out. Enter a period of

inactivity in the Auto Sign-Out Inactivity Period (s) field.
• Auto Sign-Out Inactivity Period (s) – Users will be automatically signed out
after this period of inactivity. Enter a value in seconds of at least 120. The
value must not have a decimal point, for example 900.5. The value must be
less than the period entered in the Session Token Timeout (s) field. A
period of inactivity is where the user makes no input into the
Administration User Interface by keyboard or mouse. One minute before the
user’s session is due to end, a dialog box is displayed enabling the user to
extend the session.
• OpenText Directory Services (OTDS) URL – The URL of the OTDS service
that is used by OTAG for authentication and identity information. When
you installed AppWorks Gateway, you connected to an OTDS service. You
cannot change to a different OTDS service after installation, and this field is
therefore read-only.
• Do Not Proxy OTDS – The proxy server will not be used by the client to
obtain an OTDS login URL. Instead, the client will use the URL specified in
the AppWorks Gateway.
• Cookie Domain for Generated OTDS Cookies – Enter a cookie domain for
generated OTDS cookies generated by OTAG to be used across subdomains.
For example, enter “.example.com” to allow subdomain app2.example.com
to use cookies generated for subdomain app1.example.com.
• Anonymous Access Enabled – Enable or disable anonymous

(unauthenticated) access for mobile clients.
Note: Contact your OpenText Support representative before enabling

anonymous access. There are a number of steps to take to implement
this functionality and your representative will discuss the process with
you.
• Force password based (non-OAuth) authentication – Asks the mobile client
to use form-based authentication. There will be no OTDS single sign on
regardless of whether OTDS supports OAuth. Ensure that this check box is
selected when you install the AppWorks Gateway with the following
OpenText products:
– AppWorks Suite
– Tempo Box
– Content Server Mobile
• Disable OTDS OAuth – Disables the use of OAuth within AppWorks

Gateway. By default, the mobile client shows the OTDS login page and uses
OAuth for login. If you choose to select Disable OTDS OAuth, the mobile
client will show the AppWorks Gateway login page but will not use OAuth
for login.

6.2. MDM Settings
• OTDS SSO Disable by IP (Comma Separated List, CIDR Notation) –

Allows the administrator to disable the single sign on dialog for users
outside the network. For example, with Tempo Box external users.
• List of Tenants, Comma Separated, or * to Permit All – Type the names of
one or more tenants. Tenant names may be comprised of the characters 'a' to
'z', '0' to '9'. Invalid entries will be ignored. When you click Update Settings,
you can install each tenant by entering the details for a database and an
OTDS instance. See “Deploying AppWorks Gateway for Multi-
Tenancy“ on page 71.
• AppWorks Gateway Console Developer Mode – When selected, this adds
User Management to the Management section of the Admin Menu. It also
increases the level of detail in the gateway.log error responses.
• Limit Concurrent Sessions – Enables you to apply a limit to the number of
concurrent sessions for administrator users and regular users. Enter the
required limits in the Concurrent Session limit for administrators and
Concurrent Session limit for normal users fields. When the maximum
number of sessions is reached, the user can choose to end an existing session
to enable them to start a session on a new device, for example.
• Concurrent Session limit for administrators – When Limit Concurrent
Sessions is enabled, enter the maximum number of concurrent sessions for
an administrator user.
• Concurrent Session limit for normal users – When Limit Concurrent
Sessions is enabled, enter the maximum number of concurrent sessions for a
regular user.
4. Click Update Settings.
6.2 MDM Settings

To define the mobile device management settings:
1. In the Admin Menu, click Settings > MDM Settings.
• Client Tracking Enabled – If enabled, you can track the clients that a user
has used and perform a remote wipe of any applications on the mobile
client.
• Remote Wipe Timeout (s) – An email is sent to the recipients in the Remote
Wipe Failure Email Recipients field if a remote wipe was not successful
before the timeout period expires.
• Remote Wipe Failure Email Recipients – The email addresses listed in this
field will be emailed if a remote wipe action did not occur before the Remote
Wipe Timeout (s) period expires. If you receive a remote wipe email failure
notification, the wipe did not take place and you must reset the user
password to prevent the user from signing into their account.

• Permit Storage of Password (On Device) – After a user signs in for the first
time, this setting allows your users to close and reopen the app without
typing their password. This functionality is only available when the mobile
clients are using the default oAuth 2.0 flow.
Notes
– If the user signs out of the app, they must re-enter their password to
sign back in.
– If you set a value in seconds in he Password on Device Expiry (s)
field, the user must sign back in to the app if the duration is
exceeded.
• Password on Device Expiry (s) – The duration in which a password is
stored on a device.
• Permit Offline Access on Device – When selected, users can access
information on a device when it is offline.
• Notify Devices of Offline Policy Change – When selected, users will be
notified if the value of the Permit Offline Access on Device field changes.
6.3 Mail Settings

To define the mail settings:
1. In the Admin Menu, click Settings > Mail Settings.
• SMTP Return Address – The email that is generated by the AppWorks

Gateway will be sent from this email address.
• SMTP Host – The host name or IP for the SMTP mail server.
• SMTP Port – The port for connecting to the SMTP mail server. The default
port is 25.
• SMTP Username – The username for connecting to the SMTP mail server.
This setting is optional.
• SMTP User Password – The password for connecting to the SMTP mail
server. This setting is optional.
• SMTP Use SSL – If enabled, communication with the SMTP mail server will
be secured using SSL.
4. To test these settings, do the following:
a. In the Send Test Email section, enter an email address in the To field.

6.4. Temp File Settings
b. Optional Enter information in the Subject and Message fields.
c. Click Send Email.
6.4 Temp File Settings

To define the temp file settings:
1. In the Admin Menu, click Settings > Temp File Settings.

• Temporary Directory Path – The absolute path to a directory that is writable

by the AppWorks Gateway, which will be used for temporary data. This
directory should already exist on disk.
• Temporary File Cleanup Interval (s) – Temporary files will be checked for
freshness and stale files discarded periodically with this duration.
• Temporary File Lifetime (s) – Old temporary files will be cleared from disk
when they have been untouched for at least this time in seconds.
6.5 Notifications Settings

To define notifications settings:
1. In the Admin Menu, click Settings > Notifications.

• Notification Purge Interval (s) – The interval at which the notifications table
will be purged of notification records.
• Maximum Notifications Table Size – The maximum number of notification
records retained before a purge is triggered by the table monitor.
• Back-channel Stale Connection Cleanup Period (s) – The interval at which
back-channel connections will be checked for freshness and stale connections
discarded.
• Notification Refresh Interval (s) – The interval at which fresh notification
sequence data is published to clients. This affects how often a client will ask
for new notifications based on the last known sequence value.
• Back-channel Timeout (ms) – The time in which a client long poll
connection for notifications will remain open.
• Max Long-poll Connections per User – This is used to prevent DoS attacks.
When a user connects more than this number of clients simultaneously, the
oldest connection will be dropped.
• Back-channel Stale Connection Cleanup Age (s) – Back-channel
connections will be cleared from memory when they have been idle for at
least this long.

• Permitted Get Request Interval (s)— The interval at which notifications

clients are permitted to request notifications before being throttled. Client
requests will be dropped in favour of a Denial of Service at the Gateway.
• Activate Push Notification Logging – Specifies whether push notification
activity is logged to fcm.log.
Note: Logging the push notification activity results in a large log file
that must be actively managed.
To run a manual notifications purge:
1. Select the Use Cutoff Date check box and enter a date.
2. Click Send Purge Request to remove notifications that were created before the
Use Cutoff Date.
If you have not entered a cutoff date, the current, completed notifications will
be purged. The number of notification is shown next to Current notifications
row count. This value is updated after the period specified in the Notification
Purge Interval (s).
6.6 Audit Settings

You can determine the audit information that will be captured for updates and
changes made to the system, as well as sign in and sign out activities. The details are
stored in the otagaudit table, which you can query with a database administration
tool.
To configure the audit information to store
1. In the Admin Menu, click Settings > Audit.
2. Select the check boxes next to the settings you require. The settings are grouped
under a main heading, for example, Authentication, Runtimes and so on. You
can deselect the main heading to choose more specific settings. For example,
you might want to identify when a runtime is created or deleted, but not when
a runtime is updated, or when the list of runtimes is displayed in the
Administration User Interface.
3. Click Update Settings. Only the actions that you have specified will be reported
in the otagaudit table.

Chapter 7
Creating a Proxy Rule
In the Proxy Settings page, complete the details for any proxy rules that you want to
create for AppWorks Gateway. OpenText supplies various template proxy rules for
use with OpenText products such as eDOCS InfoCenter and Content Server.
Creating a proxy rule for your OpenText product is part of the installation process
for the product, and further details are available in the specific installation
documentation.
Note: The proxy is intended as an API proxy for AppWorks services and apps,
and is not to be seen as a general purpose replacement for another proxy
service, such as mod_proxy for the Apache HTTP Server.
To define a proxy rule:
2. In the Admin Menu, click Proxy.
3. Click New Rule or New Rule From Template. The New Rule From Template
option provides some default settings for when you are installing the
AppWorks Gateway with other OpenText products. For example, the OpenText
eDOCS RestAPI template includes URL mappings and Whitelist details that
help you to install OpenText eDOCS with InfoCenter.
4. Select the Continue check box, next to the URL Mappings fields to execute the
URL rewrite in a top-to bottom order. For any matched URL rewrite rule, the
Continue option signifies whether to stop at this match, or continue applying
the rules below it.
5. In the Configure Rule page, complete the required fields and click Save Rule.

Chapter 8
Enabling Push Notifications for Firebase Cloud
Messaging
The AppWorks Gateway uses the public Firebase Cloud Message (FCM) service to
enable native push notifications. Push notifications are configured for each mobile
runtime using the Google developer console. A Firebase Project model is used for
working with Firebase projects in the AppWorks Gateway.
To set up push notifications

2. In the Admin Menu, click FCM Configuration.
3. Click Add Entry and complete the following fields:
• Project Private Key File – A service account JSON file also used to call
Firebase APIs.
• Project ID – A globally unique identifier for the project
• Server Key – A key to authorize AppWorks Gateways calls against the
Firebase APIs
• Sender ID – The ID used by the AppWorks Gateway for itself as a sender of
push notifications, push clients ask to be sent notifications from a sender
• Web Push Certificate Public Key – A public key used by, the now
supported, in browser push clients.
• Web Push SDK Configuration – A JSON configuration String to allow in-
browser web clients to easily make use of the Firebase JavaScript client
library, see here (https://github.com/firebase/firebase-js-sdk).
The following section assumes you have a valid Google developer account and can
access the console at https://console.firebase.google.com. Select the cog wheel in the
left-hand menu at the Project Overview level, and select Project settings to view the
Firebase Project Settings.
This tabbed view provides access to the general project's details and the cloud
messaging configuration, which includes any number of apps and their access files
(google-services.json, GoogleService-Info.plist), and service accounts.
Project ID
The general project identifier found on the General tab under Settings.
Server Key
A server key that authorizes our app server, the AppWorks Gateway, to access
Google services. It is available on the Cloud Messaging under Settings.

Chapter 8 Enabling Push Notifications for Firebase Cloud Messaging
Project Private Key File

This is a service account file generated for the project. It is used by the
AppWorks Gateway when communicating with the Google APIs involved in
sending push notifications to mobile and web clients.
In the Service Account tab of the Settings we can generate a new file using the
Generate new private key. This file should be uploaded in the Firebase Project
creation form in the AppWorks Gateway.
Web Push Notifications
Firebase Cloud Messaging supports web clients as well as Android and iOS
clients. The following two fields on the Firebase Project support web-based
clients that contact the AppWorks Gateway for such messages.
• Web Push Certificate Public Key – The public key of any Web Push
certificate generated in the Web Configuration found at the bottom of the
Cloud Messaging tab under Settings for the project.
• Web Push SDK Configuration – The public configuration code block for a
JavaScript app that will use the FCM client exposed by the AppWorks
Gateway. The value can be copied directly from the Firebase console as
described below. JavaScript applications may use the Firebase JavaScript
SDK to receive push notifications in the browser. From the Firebase projects
overview page, do the following:
1. Click + Add App below the project name.
2. Select the web application, depicted by angled brackets.
3. Copy the content of the config variable is JSON block out of the provided
<script> tags, for example:
{
apiKey: "AIzaSyBgXYFblWR5_IE2zfYeARydmjVdTLXljGI",
authDomain: "a-customer-project.firebaseapp.com",
databaseURL: "https://a-customer-project.firebaseio.com",
projectId: "a-customer-project",
storageBucket: "a-customer-project.appspot.com",
messagingSenderId: "944462086369"
}
4. Paste the JSON block into the Web Push Notifications field in the
AppWorks Gateway:

8.1. Sending a Test Notification
Figure 8-1: Firebase Project Details
8.1 Sending a Test Notification

You can send a test notification to connected mobile devices. A mobile client must
have connected to the AppWorks Gateway successfully at least once to receive a
notification. When you complete the details of the notification, you specify the target
app and the users that you want to notify.
To send a test notification:

2. In the Admin Menu, click Push Notification > Notification Test.
3. In the Native Alert region, enter a Title and Notification Summary. The data
provided here will be shown in the alert seen on the receiving devices operating
system, as opposed to within the AppWorks mobile client.
Depending on the device version and platform this may mean the data will be
visible in a notification centre, on a banner or in an interactive alert.
4. In the AppWorks Data region, enter the Data Summary and Data Payload. The
data provided is used by the AppWorks mobile client, and will feature on the
notifications seen therein. Notification data can be passed directly into a target
AppWorks app running within the AppWorks client via a JSON payload. This
payload is used in conjunction with the AppWorksJS framework provided for
mobile developers to create reactive hybrid applications.
5. In the Target AppWorks App box, click Search App and search for the app to
which you want to send the notification.

Chapter 8 Enabling Push Notifications for Firebase Cloud Messaging
6. In the Username/First Name/Last Name field, search for the user to whom you
want to send this notification.
7. Select the required user from the search results.
8. Click Send.

Chapter 9
Adding, Editing, and Deleting Users
The AppWorks Gateway uses OpenText Directory Services to manage and

authenticate users. When installing the AppWorks Gateway, you chose to connect to
an existing OTDS installation. You can now add or edit your users within the
AppWorks Gateway. All of these changes will sync to your OTDS installation. If you
would like to synchronize users from an LDAP or Active Directory partition, you
must do this in OTDS. For more information on OpenText Directory Services, see
OpenText Directory Services - Installation and Administration Guide (OTDS-IWC) on the
OpenText My Support (https://knowledge.opentext.com/knowledge/cs.dll?func=ll&
objId=50107027&objAction=browse&viewType=1).
9.1 Adding Users in the AppWorks Gateway

To add users in the AppWorks Gateway:
2. In the Admin Menu, click User Management.
Note: User Management is only available when the AppWorks Gateway

Console Developer Mode check box is selected in the General Settingstab
(Settings > General Settings).
3. Click Add User and provide the user information. Passwords are based on the
Directory Services global password policy. The default policy requires at least 8
characters in length with at least one capital letter and one number. The title,
email, phone, and location fields are not required.
To add an AppWorks Gateway administrative user, click Administrative User.

Chapter 9 Adding, Editing, and Deleting Users
Figure 9-1: Adding Users
4. Click Create User.

9.2. Editing Users in the AppWorks Gateway
9.2 Editing Users in the AppWorks Gateway

To edit users in the AppWorks Gateway:
1. In the Admin Menu, click User Management.
Note: User Management is only available when the AppWorks Gateway

Console Developer Mode check box is selected in the General Settings
tab (Settings > General Settings).
2. Type the username, first name, last name or group name in the Search for users
and groups box and press ENTER.
3. Next to the user or group whom you want to edit, click the Edit icon ,
edit the information, and then click Update user.
Notes
• You cannot update the OTDS Administrator user information from this
page. You need to update this user information in the Directory Services
web client at <http://Tomcat_Host>:<port>/otds-admin/.
• You cannot update any users that were added using OTDS. You need to
update these users in the Directory Services web client.
• You cannot delete users from this page. You also need to perform this
action in the Directory Services web client.
9.3 Updating the AppWorks Gateway Admin User

Information
To update the AppWorks Gateway Admin User information:

otds-admin/. From the SETUP menu, click Users & Groups.
2. Locate the otag user. This is the default user name. You may have supplied a
different name when you installed the AppWorks Gateway.
3. Click Actions and then Properties for the otag user.
4. Click General and update the information for User ID, First Name, Last Name,
and so on.
5. Click Save.

Chapter 9 Adding, Editing, and Deleting Users
9.4 Updating the AppWorks Gateway Admin User

Password
To update the AppWorks Gateway Admin user password:

otds-admin/. From the SETUP menu, click Users & Groups.
2. Locate the otag user. This is the default user name. You may have supplied a
different name when you installed the AppWorks Gateway.
3. Click Actions and then Reset Password for the otag user.
4. Type the new password in the fields provided and click Reset Password.
9.5 Deleting Users in OTDS

You cannot delete users from the AppWorks Gateway. You need to perform this
task in the Directory Services web client.
To delete users in OTDS:

otds-admin/. From the SETUP menu, click Partitions.
2. If you added users using the AppWorks Gateway, locate the otag partition. This
is the default partition name. You may have supplied a different name when
you installed the AppWorks Gateway.
3. Click Actions and then View Members.
4. Select the check box next to the user whom you want to delete and then click
Delete.
Important
Do not delete the otag or otdsadmin users.

Chapter 10
Monitoring and Managing User’s Access
Using Client Management, you can see and wipe the runtimes from your user’s
devices that your users have used to access their account. Wiping deletes all local
copies of server data from the runtime and prevents the user from signing in. If the
runtime was accidentally wiped, the user can re-enter the AppWorks Gateway URL,
sign in and continue to access their account. The user will need to reinstall all of the
apps and download their favorite files again. Assuming the wipe was intentional,
you should change the user's password or delete their account altogether to prevent
the user from signing in again.
10.1 Monitoring Client Management

To monitor client management:
2. In the Admin Menu, click Client Management from the Management section.
3. Type the username, first name, or last name of a user and then press ENTER.
Tip: If you are unable to search for a user, verify that Client Tracking
Enabled is selected on the MDM Settings page.
You will see the username, runtime, device information, and connection times
for every client the user has used to access their account.
Figure 10-1: Admin Menu – Client Management

Chapter 10 Monitoring and Managing User’s Access
10.2 Performing a remote wipe

To perform a remote wipe of the applications on a client, the Client Tracking
Enabled setting in the MDM Settings page must be selected.
Note: This functionality is only available for the Mobile Client.
To perform a remote wipe of the applications on a client:
1. In the Admin Menu, click Client Management from the Management section.
2. Type the username, first name, or last name of a user and then press ENTER. If
you are unable to search for a user, verify that Client Tracking Enabled is
selected on the MDM Settings page.
3. Click the Wipe link for the client that you want to wipe.
4. Click Ok to confirm the action. The next time the user attempts to access their
account using the client ID you wiped, the runtime wipe will take place.

Chapter 11
Deploying the AppWorks Gateway in a Cluster
You can deploy and configure additional AppWorks Gateway servers to use an
existing AppWorks Gateway database. Any applications, services, and components
that are installed on one node in the cluster are automatically installed on all of the
other nodes. All settings changes are also propagated to all of the nodes. You do not
need to perform any manual steps on any other node or restart the Apache Tomcat
service. However, you must restart the Apache Tomcat service if you change any of
the following settings in the AppWorks Gateway:
• On the Notifications page, changes to the Back-channel Stale Connection

Cleanup Period (s) only take effect when the current period elapses or when the
Apache Tomcat servers are restarted.
• On the General Settings page, changes to the Session Token Cleanup Interval
(s) and the Session Token Timeout (s) will only take effect once the current
interval elapses or when the Apache Tomcat servers are restarted.
• On the Temp File Settings page, changes to the Temporary Directory Path
should be made when the servers are off-line, because some services may lose
temporary data. Changing the Temporary Directory Path may leave old
temporary files in the former location. The Temporary Directory Path location
must exist on disk before changing the path in the AppWorks Gateway. The
location on disk must be the same on all nodes in the cluster. The default location
is C:\Program Files\Apache Software Foundation\Tomcat 9.0\tmp.
Note: The location of the Temporary Directory Path must be exclusive to

each node on the cluster. It must not be physically accessible or shared by
any other node in the cluster.
• On the Temp File Settings page, changes to the Temporary File Cleanup
Interval (s) only take effect when the current interval elapses or when the
Apache Tomcat servers are restarted.
Note: In most cases, you should not change these settings.
Clients that are connected to one node can also switch to another node and continue
functioning.
To deploy AppWorks Gateway on additional nodes:
1. Install Apache Tomcat on the new node. For details, see “Installing the
OpenText AppWorks Gateway“ on page 9.

Chapter 11 Deploying the AppWorks Gateway in a Cluster

Tip: Navigate to the <Tomcat_Home>\logs folder and open the

catalina.<yyyy-mm-dd> file. When you see a line containing INFO:
Server startup in <55278> ms, you can start to configure the AppWorks
Gateway.
5. Complete the database configuration steps to connect to the database you are
using for all nodes in the cluster.
6. Configure a load-balancer in front of the AppWorks Gateway nodes. When

complete, sign in to the AppWorks Gateway, click Settings, and edit the
AppWorks Gateway Server URL to point to the load-balancer's address.
Note: Repeat this procedure at any time to add nodes to the cluster. They
must also be added to the load-balancer.

Chapter 12
Deploying AppWorks Gateway for Multi-Tenancy
A multi-tenant AppWorks Gateway installation enables you to create multiple

AppWorks Gateway instances on the same server, each with their own database and
OTDS configuration details. Each tenant installation can have a separate
adminstrator, with the administrator of the primary AppWorks Gateway having
overall control.
To create a new tenant for a primary AppWorks Gateway installation:
1. Install AppWorks Gateway on a server, as described in “Installing the OpenText

AppWorks Gateway“ on page 9.
2. In the Admin Menu, click Settings > General Settings.
3. In the List of Tenants field, type one or more tenants. Tenant names can include
the characters 'a' to 'z', and '0' to '9'. Upper case characters are not valid.
4. Click Update Settings. A URL is created for each tenant name. For example, if
you type "tenant001" in the List of Tenants field, the URL http://host:port/
awtenant/tenant001/ is created.
5. To complete the installation, enter the URL for the tenant into a browser address
bar. A configuration page appears with options to specify a database and an
OTDS instance. This is the same page that you use to complete the configuration
of any AppWorks Gateway installation.
6. For Step 1: Database Configuration, specify a database, and click Configure

Database Connection. The database for each tenant must be unique. It must not
be the same as the database for the primary AppWorks Gateway installation.
7. For Step 2: OTDS Configuration, enter the OTDS server details that you used
for your primary AppWorks Gateway installation.
8. For each tenant, provide details for the Gateway Admin Username/Password,
and OTDS Administrative Account/Username. You can use the same
administrator as your primary installation, or you can create different
administrators for each tenant.
9. For each tenant, provide a Resource Name and Gateway User Partition Name.
10. Click Configure OTDS.

Chapter 13
Deploying AppWorks Gateway as a Container
This chapter contains information about setting up, supporting, installing,

configuring, and deploying the AppWorks Gateway on certified cloud
environments. Migration to the cloud can convey the following benefits:
• Reduce the high operating costs to develop, manage and maintain on-premises
applications
• Avoid end user adoption issues caused by slow performance and lengthy
deployment timelines
• Gain access to extensive resources to support enterprise information
management applications
• Deploy enterprise information management applications and grow as needed to
scale to your business needs
AppWorks Gateway provides Docker images that can be downloaded from

OpenText with Docker YAML files and Kubernetes Helm charts and scripts. You can
modify the Docker images to add the desktop and mobile apps that you want to
deploy with the AppWorks Gateway. If you deploy your product using the default
parameters, AppWorks Gateway will use Apache Tomcat as its web server,
PostgreSQL as its database, and OpenText Directory Services (OTDS) to manage
user and group identity information.
Note: Apache Tomcat and OpenJDK are installed as part of the AppWorks
Gateway container deployment. You do not have to install this software
separately. OTDS and PostgreSQL require separate installations.
13.1 Before You Start

To perform the steps outlined in this document, you will need the items listed
below. Refer to the AppWorks Gateway Release Notes for information on supported
platforms and versions.
A PostgreSQL installation
The AppWorks Gateway container deployment process connects to the database
and creates a database instance.
Note: PostgreSQL is the only supported database for a container

deployment of AppWorks Gateway.
OpenText Directory Services (OTDS)
The AppWorks Gateway container deployment process checks for an existing
instance of OTDS.

Chapter 13 Deploying AppWorks Gateway as a Container
Helm
Helm is used to deploy the Docker images.
Docker
You tag the Docker image files and push them to your registry.
Kubernetes
You use Kubernetes to run various commands during the deployment of the
AppWorks Gateway containers. Normally, you should have a local installation
of Kubernetes, but it is also possible to run Kubernetes commands on certain
cloud platforms. For example, on the Google Cloud Platform, you can use the
Google Cloud Shell to run Kubernetes commands.
13.2 Deploying AppWorks Gateway with Docker

Use this procedure to deploy the AppWorks Gateway in Docker.
To install AppWorks Gateway in a Docker container:
1. Go to My Support (https://knowledge.opentext.com/knowledge/llisapi.dll/open/
58916144) and download the docker-compose.zip file.
2. Extract the docker-compose.zip file to a location, for example, C:\OpenTextCE

\docker. The contents of the docker-compose folder are as follows:
• .env: Contains details of the AppWorks Gateway OTDS and PostgreSQL

installations. In this file, you also configure the General, MDM and Mail
settings for the AppWorks Gateway deployment.
• docker-compose.yml
• install: Add the mobile and desktop apps that you want to deploy with
the container to this folder.
• pg: Contains config, env and secrets folders. The pg folder enables you to
add the details of your PostgreSQL database.
3. Navigate to the pg\secrets folder, and update the PGPASSWORD and

PGNEWPASSWORD files.
a. Update the PGPASSWORD file, replacing postgresadminpassword with the

password for your database administrator.
Note: The file starts with a sequence of asterisks and colons

*:*:*:*:. Do not remove or alter this sequence.
b. Update the PGNEWPASSWORD file, replacing postgresuserpassword with the
password for a new user who will deploy the AppWorks Gateway
database.
4. Navigate to the pg\config folder, and update the PGNEWDATABASE and

PGNEWUSER files.

13.2. Deploying AppWorks Gateway with Docker
a. Update the PGNEWDATABASE file, replacing postgresdatabase with the

username of your database administrator.
b. Update the PGNEWUSER file, replacing postgresuser with the username for
a user who will deploy the AppWorks Gateway database.
5. In the env folder, update the pg.env file with the details of the PostgreSQL
installation, for example, hostname, port and so on.
6. In the .env file, enter the details for the following sections:
• Image and port details

Do not change the PG-INIT-IMAGE details.
Update the OTAWG_PORT used by the Apache Tomcat installation, if required.
• Gateway Setup related environment variables
Update the AppWorks Gateway and OTDS settings. See “Updating the
OTDS Settings” on page 81 and “Updating the AppWorks Gateway (awg)
Settings” on page 81 for details.
• Environment variables to set various settings values
These are the General, MDM and Mail settings that appear in the
AppWorks Gateway Administration UI. If you change the defaults here, you
cannot change them in the Administration User Interface of the deployed
Gateway. See “Updating the AppWorks Gateway (awg) Settings”
on page 81for details.
7. Open a PowerShell session as an administrator and navigate to the docker.

compose installation folder, for example, C:\OpenTextCE\docker.
8. Run the command docker-compose up -d to build the container.
9. Run docker container ls to list the docker containers, and check that the
container is available and running. The name of the container is docker-
compose_otawg_1.
10. In a browser, type http://<hostname of the server>:<port number> and

sign in to the AppWorks Gateway Administration UI, using the credentials that
you supplied in the .env file.
11. To view the logs run the command docker logs container <container name>
—f.
12. To remove the container deployment, run the command docker-compose down.

13.3 Deploying AppWorks Gateway with Helm

To install the AppWorks Gateway as a container through Helm, you require the
following:
• The appworks-gateway.zip file containing Helm charts. You download this from
My Support.
• Access to the AppWorks Gateway container image: This installs the AppWorks
Gateway software. This image is available from the OpenText Container
Repository.
• Access to the PostgreSQL container image: This creates a database with a name
you have supplied in your PostgreSQL installation.
• An AppWorks init container image: This initializes the AppWorks Gateway
container. By default no mobile or desktop apps are installed with the container.
You can customize init container to include the mobile and desktop apps that
you want to include with the AppWorks Gateway deployment. This image is
available from the OpenText Container Repository.
To download the appworks-gateway.zip file
1. Go to My Support (https://knowledge.opentext.com/knowledge/llisapi.dll/open/
58916144) and download the appworks-gateway.zip file.
2. Extract the appworks-gateway.zip file to a location, for example,
C:\OpenTextCE\appworks-gateway. The contents of the appworks-gateway
folder are as follows:
• Sample-Proxy-Rules: Contains proxy rule templates to support the

integration of various OpenText products. You can add the templates to the
Ruletemplate.JSON file. When you deploy the AppWorks Gateway
container, these rules appear in the Proxy section of the AppWorks Gateway
• templates
• trustCertificates: Add a certificate to this folder if you want to connect
to a PostgreSQL database in Amazon RDS using SSL. See “Updating the
Postgres Settings” on page 80 for further details.
• .helmignore
• Chart.yaml
• Ruletemplate.json: Contains the proxy rules to add to the AppWorks
Gateway container deployment. The Ruletemplate.JSON file contains
several default rules. You can add further rules to the Ruletemplate.JSON
file to include them in the AppWorks Gateway container deployment.
• values.yaml: Contains the General, MDM and Mail settings to use when
deploying an AppWorks Gateway container. The values.yaml file also
includes the details of the OTDS and PostgreSQL installations, and various
other settings.

13.3. Deploying AppWorks Gateway with Helm
To confirm access to the container images
1. The image section of the values.yaml file contains the registry and
repository details of the AppWorks Gateway and PostgreSQL images in the
OpenText Container repository. See “Updating the Image Settings” on page 79.
2. Confirm that you can access the repository by entering the registry address in a
browser. You must supply credentials to view the contents of the repository.
Check with your Customer Support Representative for details.
13.3.1 Building an AppWorks Gateway Init Container Image for

App Deployment
In this section, you add your desktop and mobile apps to the AppWorks Gateway
init container image, to deploy the apps with the AppWorks Gateway container
through Helm.
Note: You can choose to deploy an AppWorks Gateway container without any
desktop or mobile apps. See “Deploying the AppWorks Gateway Container”
on page 78.
To update the AppWorks Gateway image with your apps
1. Extract the awg-init-container.zip file to a location, for example,

C:\OpenTextCE\awg-init-container. The contents of the awg-init-
container folder are as follows:
• apps: This is the folder in which you place the desktop and mobile apps that
you want to deploy with the AppWorks Gateway
• Dockerfile: You modify this file to include the names of the apps that you
want to deploy
• README: This text file provides an explanation of the environment variables
and exit codes used by the init container.
2. Copy your desktop and mobile apps to C:\OpenTextCE\awg-init-container\

apps\.
3. Edit the Dockerfile to add the names of the apps that you added to the apps
folder. For example, if your apps are called starterApp1_0.0.1.zip, and
starterApp2_0.0.2.zip, then the Dockerfile will be as follows, with a
separate Copy command for each file: Dockerfile:
FROM artifactory.otxlab.net/otag/awg:21.3.0-22122020010729
MAINTAINER OpenText Corp.
ENV AWG_UNATTENDED_SETUP="true"
ENV WG_EXIT_ON_SETUP_COMPLETE="true"
# Unzip to auto-install location

RUN mkdir -p ./conf/install
COPY apps/starterApp1_0.0.1.zip ./conf/install
COPY apps/starter1App2_0.0.2.zip ./conf/install

4. Save the Dockerfile.
5. Open a PowerShell session as an administrator and navigate to the root folder

of the awg-init-container.
6. Run the following command to build the image.

docker build -t <imagename>
7. Run the docker image ls command to check that the container has been built:
8. Provide a tag number for the image, using the following command:
docker tag <imagename> <registryname>/<repositoryname>/awg-init-
container:<imagename>.<tagnumber>
where <registryname>/<repositoryname> are the details of your own
registry.
9. Run the docker image ls command to check that the tagging has been
successful.
10. Run the following command to push the new image to your registry:
docker push <registryname>/<repositoryname>/awg-init-
container:<imagename>.<tagnumber>
11. Confirm that the image now appears in your registry.
13.3.2 Deploying the AppWorks Gateway Container

To deploy the AppWorks Gateway container image with the desktop and mobile
apps, you modify the parameters in a Helm chart file, then deploy the product using
a Helm command.
To deploy the AppWorks Gateway container:
1. Locate the values.yaml file that you extracted from the appworks-gateway.
zip file. See “Deploying AppWorks Gateway with Helm” on page 76 for details.
2. Update the values.yaml file as required. See“About the values.yaml file”

on page 79 for details.
3. Open a PowerShell administrator session and navigate to the root directory, for
example, C:\OpenTextCE.
4. Run the following command to install the AppWorks Gateway container.

helm install <deployment name> appworks-gateway
5. Run the following command to monitor the status of the deployment:

kubectl get pods -w
A status of 1/1 Ready indicates that the deployment is complete.

6. Open a browser and access the AppWorks Gateway using the URL specified in
the values.yaml file. If you have enabled ingress, use the value you entered in
the host setting.
7. Sign in to the AppWorks Gateway using the Username and Password details
that you supplied in the awg section of the values.yaml file.
8. Check the Installed section of the Admin Menu to confirm that the desktop and
mobile apps that you included in your deployment are present.
13.3.3 About the values.yaml file

The values.yaml file contains the following settings for deploying the AppWorks
Gateway as a container:
13.3.3.1 Updating the Image Settings
Initial registry and repository settigns

Do not alter the values for registry, repository and tag. These values refer to
the AppWorks Gateway image in the OpenText registry.
pgInitContainer
The settings for pgInitContainer create the PostgreSQL database in your
PostgreSQL installation. Do not update the values for registry, repository
and tag for pgInitContainer.
awgInitContainer
To deploy the AppWorks Gateway software without any desktop or mobile
apps, keep the default settings for registry, repository and tag.
To deploy AppWorks Gateway with your desktop and mobile apps, do the
following:
1. Create an awgInitContainer image and push it to your registry. See
“Building an AppWorks Gateway Init Container Image for App
Deployment” on page 77
2. Update the awgInitContainer section with the registry, repository and
tag values for the image in your registry.
pullpolicy, imagepullsecrets
OpenText recommends that you do not modify these settings. If the images are
not available locally they will be deployed from the OpenText registry according
to the settings for registry, repository and tag.

13.3.3.2 Updating the Postgres Settings

AppWorks Gateway supports on premises and cloud deployments of a PostgreSQL
database.
The cloud deployment is available for the Amazon Relational Database Service
(Amazon RDS). For the cloud deployment you must first create the database in
Amazon RDS, as follows:
1. In Amazon RDS, establish a PostgreSQL database with a version of PostgreSQL

that is supported by AppWorks Gateway. Refer to the AppWorks Gateway Release
Notes for details.
2. Using a PostgreSQL database administration tool, such as pgAdmin, create a
database instance to use with the AppWorks Gateway. See the settings required
below.
server
Enter the server host and port details of an on premises PostgreSQL database
or a PostgreSQL database in Amazon RDS.
admin
Enter the user, password and database details for the database that will be
created by pgInitContainer. You can keep the defaults or update with new
values.
appworksdb
Enter a username, password, and database name. For an on premises
PostgreSQL database, deploying the container will create an instance with these
credentials in the PostgeSQL installation. Make sure that the username and
database details are in lower case characters.
Note: For a cloud deployment of PostgreSQL in Amazon RDS, you must

first create the database using a PostgreSQL database administration tool.
useSSL
The default value is false. Enter true if you want to connect to Amazon RDS over
SSL.
trustDbCerts
The default value is false. Set trustDbCerts to true if you want the certificate to
be downloaded automatically when connecting with Amazon RDS over SSL.
Notes
• If useSSL is true and trustDbCerts is false, place the certificate inside the
appworks-gateway\trustCertificates folder to connect over SSL.

13.3.3.3 Updating the OTDS Settings
server, admin, password

Enter the details for the OTDS installation that you want to use with the
AppWorks Gateway container deployment.
partition, resource
Enter the names of the OTDS partition and resource to be used for the
AppWorks Gateway container deployment.
13.3.3.4 Updating the AppWorks Gateway (awg) Settings
admin
Enter values for the newadminuser and newadminpassword. You use these
values to sign in to the AppWorks Gateway Administration User Interface.
externalurl
Enter the URL that will be used to access the AppWorks Gateway
logging
The default setting for logging is info. You can change to trace, debug, warn or
error.
settings
This section enables you to determine the values for the General, MDM and Mail
settings that are available in the AppWorks Gateway Administration User
Interface. If the setting is not specified here. you can update it in the
Administration User Interface. If you choose to set a value for a setting here, you
cannot update it in the Administration User Interface of the deployed
AppWorks Gateway. To update a setting, after you have deployed AppWorks
Gateway as container, see “Upgrading a Deployed AppWorks Gateway
Container” on page 84.
The following table lists the settings. For an explanation of each setting, see
“AppWorks Gateway Settings“ on page 51.
Table 13-1: General, MDM and Mail Settings
Setting Data Value if Required

Type
wantSecureCookies Binary true or false
doNotProxyOTDS Binary true or false
anonymousAccessEnabled Binary true or false
forcePasswordBasedNonOauthAuthe Binary true or false
ntication
disableOTDSAuth Binary true or false
otdsSSODisableByIP String Enter an IP address

Setting Data Value if Required

Type
listOfTenants String Enter a comma-separated list of tenants or
* to permit all.
awgDeveloperMode Binary true or false
clientTrackingEnabled true true or false
remoteWipeTimeoutSeconds String 300 seconds is the default value
remoteWipeFailureEmailRecipients String Enter an email address.
permitStorageOfPasswordsOnDevice Binary true or false
passwordOnDeviceExpirySeconds Integer 604800 seconds is the default value
notifyDevicesOfOfflinePolicyChange false true or false
smtpReturnAddress String The email that is generated by the
AppWorks Gateway will be sent from this
email address
smtpHost String Enter the host name or IP for the SMTP
mail server
smtpPort Integer 25 is the default value
smtpUsername String The username for connecting to the SMTP
mail server
smtpPassword String The password for connecting to the SMTP
mail server
smtpUseSSL Binary true or false
enableAutoLogout Binary true or false
autoLogoutTimeIntervalSeconds Integer The minimum recommended value is 120
seconds
enableConcurrentSessionLimit Binary true or false
concurrentSessionLimitAdmin Integer The maximum number of concurrent
administrator users
concurrentSessionLimitUser Integer The maximum number of concurrent
regular users

13.3.3.5 Updating the replicaCount setting

This setting determines the number of AppWorks Gateway pods that you want to
deploy. You may want to deploy multiple pods for the purposes of load balancing.
Review the ingress settings if you set replicaCount to more than 1.
13.3.3.6 Updating the Proxy Settings

The proxy setting refers to the proxy rules that you can create in the AppWorks
Gateway Administration User Interface. To add the proxy rules to the container
deployment, update the Ruletemplate.JSON file, as follows:
1. Open the Ruletemplate.JSON file in a text editor. The Ruletemplate.JSON

contains OTDS and eDOCS templates by default.
a. To include the Sample OTDS rule, add the hostname of your OTDS server to
the replace setting, under urlRules.
b. To include the Sample eDOCS RestAPI rule, add the hostname of your
eDOCS REST API Server to the replace setting, under urlRules.
2. Additional rules are available in the Sample-Proxy-Rules folder. To install a
rule from this folder, open the file and copy the content into the Ruletemplate.
JSON file
3. Change the value for automate to true.
4. Save the Ruletemplate.JSON file.
13.3.3.7 About the System and Resource Settings
readiness probe
OpenText recommends that you leave the readiness probe settings
unchanged. They relate to the Kubernetes architecture and perform checks to
determine when a container is ready to start accepting traffic.
liveness probe
OpenText recommends that you leave the liveness probe settings unchanged.
They relate to the Kubernetes architecture and perform checks to determine
when to restart a container.
service
OpenText recommends that you leave the service settings unchanged.
ingress
Ingress provides load balancing functionality where you have deployed
multiple pods by setting replicaCount to a number greater than 1. Update the
enabled setting for load balancing. Also, if you want to access multiple
AppWorks Gateway pods with a single URL, set enabled to true and enter a
URL in the host setting.
tls
To use HTTPS, set enabled to true, then provide values for the secretName
settings.

resources
OpenText recommends that you leave the default settings unchanged. However,
if you want to provide customer settings, uncomment the lines for limits and
requests, and enter your preferred values.
13.3.4 Upgrading a Deployed AppWorks Gateway Container

You can upgrade a AppWorks Gateway deployment to update the General, MDM
and Mail settings. You can also increase the value for replicaCount to add further
pods to the deployment and update the ingress settings to add load balancing.
To update a deployed AppWorks Gateway container
1. Update the settings in the values.yaml file, as required. A setting that you
specify in the values.yaml file cannot be altered in the AppWorks Gateway
2. Run the following upgrade command:

helm upgrade <deployment name> appworks-gateway
3. Run the following command to delete the pod. You must run the command for
all pods in the cluster. The pod is automatically recreated.
kubectl delete pod <pod name>
Tip: The command kubectl get pods -w displays the pod name and the
status of the pod.
13.3.5 Checking the AppWorks Gateway Deployment Status

The AppWorks Gateway container deployment consists of two processes:
• pginit container: Creates the database for the AppWorks Gateway

• init container: Deploys the AppWorks Gateway with any desktop and mobile
apps.
To check the status of a deployed AppWorks Gateway container, use the following
commands.
If the deployment fails to initialize pginit container, the status shows 1/2 Error.
Run the following command to see the log files:
kubectl logs <podname> -c awg-pg-init-container
If the deployment fails to initialize init container, the status shows Error or
CrashloopBack. Run the following command to see the log files:
kubectl logs <podname> -c awg-init-container
Run the following command to show the standard container log files:

kubectl logs <podname> -f

Chapter 14
Frequently Asked Questions
The following FAQs provide advice on additional setup options, and basic
troubleshooting information.
How do I set the debug log level in the AppWorks Gateway?

The AppWorks Gateway provides information in the gateway.log file, which is
located in the <Tomcat_Home>\logs directory. The log level for the AppWorks
Gateway is set via a log4j2.xml file in the gateway\web-inf\classes folder.
To set the log level to a higher level, for example, debug, take the following steps:

2. Open the log4j2.xml file in the gateway\web-inf\classes folder.
3. Search for the following entry in the file:
<Root level="info">
<AppenderRef ref ="OTAG"/>
</Root>
4. Change the Root level setting from info to debug.

5. Save the log4j2.xml file.
In an AppWorks Gateway multi-tenant environment, the log file includes
information for the primary installation and all tenants.
Important
When debug-level or trace-level logging is enabled, sensitive configuration
data may be written to the log files. Debug-level and trace-level logs should be
securely disposed of when they are no longer required. Return the log level to
its lower level when you have completed any troubleshooting tasks.
How can I troubleshoot the AppWorks Gateway?

The AppWorks Gateway provides information in the gateway.log file, which is
located in the <Tomcat_Home>\logs directory. Set the log level to a higher level, as
described above.
The AppWorks Gateway proxy also logs information in the gateway.log file when
the log level is set to debug.
Information is also available in the default Catalina logs such as

catalina_<date>_.log and localhost-access_logs.<date>.txt.

Chapter 14 Frequently Asked Questions
For debugging, first check the Catalina log for errors, and if necessary check the
localhost-access_logs.<date>.txt because they record each request. This
allows you to confirm timing and response codes for each request when nothing
appears in the logs.
Commonly reported issues revolve around OpenText Directory Services (OTDS)

configuration. On the initial AppWorks Gateway configuration, there is a chance
that the OTDS configuration will fail either due to port conflicts, memory issues,
resource conflicts with existing OTDS data, or failure to communicate with an
external OTDS due to firewall blocking requests or mistyped configuration
information. The Catalina logs will show exceptions in the OTDS configuration. For
more information, review the OTDS logs which can provide additional information.
These logs can be found in the <Tomcat_Home>\logs directory on the Tomcat server
used to host your OTDS installation. The OTDS log files are also available in the
Directory Services web client. Errors relating to port conflicts and resource name
conflicts will be clearly indicated in the logs. Other error cases may require further
investigation.
Beyond initial configuration of the AppWorks Gateway, there are very few error
scenarios that would be indicated in the logs. The primary issue that can occur
relates to authentication errors. If the user has entered a correct password, but
cannot authenticate, these issues will not be captured in the log files. The following
steps are recommended to troubleshoot authentication errors.
1. Review the AppWorks Gateway node information to verify the database and
OTDS connections. Sign in to the AppWorks Gateway and click Overview from
the About section of the Admin Menu.
2. Double check that the credentials and server URL were typed correctly. This is
often the problem.
3. Try connecting using a different client.
4. Try using the fully qualified name. For example. <username>@otag for internally
created users, <username>@<domain> for OTDS synced users.
5. Sign in to the Directory Services web client and check that the user’s account has
not expired or been locked.
6. Add a new user in the AppWorks Gateway. Then, sign in to the Directory
Services web client and verify that the new user was added to the otag partition.
How can I check the status of the AppWorks Gateway

connections?
Open a browser window and navigate to http://gateway:port/v3/admin/
status. The following information is returned, showing the status of the connection
to OTDS and to the database:
{"dbSetup":true,"dbConnected":true,"otdsSetup":true,"otdsConnected":true,"developerMode":
true}

How can I troubleshoot the status of my apps, services,
components, or connectors?
The AppWorks Gateway provides information in the gateway.log file which is
located in the <Tomcat_Home>\logs directory. Your feature might also have a
service log that is also located in this directory.
How can I configure AppWorks Gateway to use an HTTP forward

proxy?
In AppWorks Gateway 16.1 and above, the Gateway is capable of making external
HTTP calls via an HTTP forward proxy, using JAVA_OPTS.
A good example of this is for the routing of Firebase Cloud Messaging (FCM)
communications when the environment within which the Gateway is installed only
permits outbound HTTP communication to the public Internet via an HTTP proxy.
The example settings shown below are from a Linux installation of the AppWorks
Gateway.

2. Open the setenv.sh script in a text editor.
3. Add the following values and edit the hostnames and ports to match your
environment.
• export CATALINA_OPTS="$CATALINA_OPTS -Dhttp.proxySet=true"

• export CATALINA_OPTS="$CATALINA_OPTS -Dhttp.proxyHost=proxy-
syd.cloud.opentext.com"
• export CATALINA_OPTS="$CATALINA_OPTS -Dhttp.proxyPort=80"

• export CATALINA_OPTS="$CATALINA_OPTS -Dhttps.proxyHost=proxy-
syd.cloud.yourserver.com"
• export CATALINA_OPTS="$CATALINA_OPTS -Dhttps.proxyPort=80"

• export CATALINA_OPTS="$CATALINA_OPTS -Dhttp.nonProxyHosts=
\"localhost|127.*|syd-awgw-p01|syd-awgw-p01.appworks.cloud.
yourserver.com|syd-awdba-p01.appworks.cloud.yourserver.com\""
Where:
• Dhttp.proxyHost is the address of the HTTP Proxy Server

• Dhttp.proxyPort is the HTTP listening port for the HTTP Proxy
• Dhttps.proxyPort is the HTTPS listening port for the HTTP Proxy
• Dhttp.nonProxyHosts contains the short name and FQDN of the AppWorks
Server syd-awgw-p01 and syd-awdba-p01.appworks.cloud.yourserver.
com is the OTDS Server used by AppWorks

Chapter 14 Frequently Asked Questions
We must NOT proxy requests via the HTTP Forward Proxy to:
• The Gateway itself.

• OpenText Directory Services (OTDS).
4. Save the setenv.sh file and start the Apache Tomcat service.
Tips
• Select the Activate Push Notification Logging check box in the

Notifications section of the AppWorks Gateway, and then check the fcm.
log to confirm that Firebase Cloud Messaging communications are being
sent correctly.
• Use cURL, via a terminal session. to check the server host itself can connect
to FCM via the HTTP Forward proxy. This should return an HTTP 200
response (adjust the proxy address and port to match your environment)
curl -v -I -x proxy-syd.cloud.opentext.com:80 https://fcm-
http.googleapis.com.
How can the AppWorks Desktop Client authenticate the user

when the environment includes a Web proxy server?
When you install an AppWorks Desktop Client, such as eDOCS InfoCenter, an
initial authentication request is made from the client machine to OTDS. If your
environment includes a Web proxy server to handle web requests, you need to set
the HTTP_PROXY and HTTPS_PROXY environment variables for the operating system
to the address of the proxying server, for example, HTTP_PROXY=<http://proxy.
mycompany.com:8080/>.
If you do not set the environment variables, then the authentication request from the
AppWorks Desktop Client to OTDS will fail.
Note: For further details of the AppWorks platform and technologies, see the
Technical White Paper, available from the AppWorks Quick Start page of the
AppWorks Developer web site (https://developer.opentext.com).
Issue with creating users in AppWorks Gateway with Directory

Services 16.4.3
This issue relates to the creation of users in the User Management section of the
AppWorks Gateway. The User Management menu item is available from the
Admin Menu, when the Gateway Console Developer Mode check box is selected in
the General Settings page
The message “Can’t create a user. Consult OTDS logs” is displayed when creating
users in the User Management section of the AppWorks Gateway.
The issue is only encountered when running specific combinations of AppWorks

Gateway and Directory Services (OTDS). Support for OTDS 16.4.3 was introduced in
AppWorks Gateway 16.6. However, customers may have installed OTDS 16.4.3 with

previous versions of AppWorks Gateway and as a result you may experience this
issue while running the following combinations:
• AppWorks Gateway 16.5 or earlier and OTDS 16.4.3
• After upgrading to AppWorks Gateway 21.3, from a combination of AppWorks

Gateway 16.5 or earlier and OTDS 16.4.3.
Note: The issue is not present when you perform a clean install of AppWorks
Gateway 21.3 with any supported version of OTDS, including 16.4.3.
To correct the issue, do the following:
1. In the OTDS Administration UI, search for the OTAG partition. This is
automatically created by the AppWorks Gateway installation process, when you
connect the AppWorks Gateway to an instance of OTDS.
2. Click the Actions link, and select Edit Administrators.
3. Click Add Administrator.
4. In Member Selection, search for the OTAG partition and add the resource
principle for the OTAG resource.
5. Click Add Administrator.
Issue with logging in to desktop and mobile clients after

upgrading Directory Services
To use OAuth 2.0 with Directory Services (OTDS), an OAuth client must be
registered in OTDS.
By default, the AppWorks Gateway adds an OAuth client to OTDS, with the Grant
refresh token (when protocol permits) check box selected. When you upgrade
OTDS to 16.6, we recommend that you confirm that the Grant refresh token (when
protocol permits) check box is still selected. If the check box is not selected a desktop
or mobile client does not receive the refresh token on login and the user will
therefore be asked to log in again, once they have logged out.
To check the Grant refresh token (when protocol permits) setting, do the following:
1. In OTDS, from the web administration menu, click OAuth Clients .
2. Select the OAuth Client for OTAG and click Advanced.
3. Select the Grant refresh token (when protocol permits) check box and click
Save.
For further information, see the chapter on OAuth Clients in the OpenText Directory
Services - Installation and Administration Guide (OTDS-IWC).

Opentext™ Appworks™ Gateway: Installation and Administration Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Opentext™ Appworks™ Gateway: Installation and Administration Guide

Uploaded by

Copyright:

Available Formats

OpenText™ AppWorks™ Gateway

Installation and Administration Guide

This guide explains how to install and configure the AppWorks

Open Text Corporation

275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1

Copyright © 2021 Open Text. All Rights Reserved.

No Warranties and Limitation of Liability

2 Installing the OpenText AppWorks Gateway .......................... 9

3 Upgrading the OpenText AppWorks Gateway ...................... 19

4 Securing the AppWorks Gateway .......................................... 29

5 Getting Started with the AppWorks Gateway ....................... 37

OTAG210300-IGD-EN-1 Installation and Administration Guide iii

6 AppWorks Gateway Settings .................................................. 51

7 Creating a Proxy Rule ............................................................. 57

8 Enabling Push Notifications for Firebase Cloud

9 Adding, Editing, and Deleting Users ..................................... 63

10 Monitoring and Managing User’s Access ............................. 67

11 Deploying the AppWorks Gateway in a Cluster ................... 69

12 Deploying AppWorks Gateway for Multi-Tenancy ............... 71

13 Deploying AppWorks Gateway as a Container ..................... 73

iv OpenText™ AppWorks™ Gateway OTAG210300-IGD-EN-1

13.3.4 Upgrading a Deployed AppWorks Gateway Container ....................... 84

14 Frequently Asked Questions .................................................. 87

OTAG210300-IGD-EN-1 Installation and Administration Guide v

The OpenText AppWorks Gateway is an Enterprise Application Development and

Communication between the AppWorks Gateway engine and your production

The AppWorks Gateway can also be run in a containerized environment. OpenText

OTAG210300-IGD-EN-1 Installation and Administration Guide 7

Installing the OpenText AppWorks Gateway

In a production environment, we recommend the following setup, where OTDS, the

Your Production Server

Figure 2-1: AppWorks Gateway Architecture

OpenText Directory Services

Your production server

OTAG210300-IGD-EN-1 Installation and Administration Guide 9

The AppWorks Gateway requires the following software.

• Java Development Kit.

2.2 Configuring Apache Tomcat for the AppWorks

2. Stop the Apache Tomcat service.

3. Navigate to the <Tomcat_Home>\bin folder.

10 OpenText™ AppWorks™ Gateway OTAG210300-IGD-EN-1

a. Click the Java tab.

Figure 2-2: Apache Tomcat Java options

OTAG210300-IGD-EN-1 Installation and Administration Guide 11

2.3 Installing the AppWorks Gateway

To install the AppWorks Gateway:

1. Stop the Apache Tomcat service.

2. Navigate to the <Tomcat_Home>\conf folder and back up the server.xml and

3. Download the AppWorks Gateway installation package from AppWorks

4. Extract the contents of the otag-gateway–21.3.zip file to the root of the

6. Start the Apache Tomcat service.

Tip: Navigate to the <Tomcat_Home>\logs folder and open the

12 OpenText™ AppWorks™ Gateway OTAG210300-IGD-EN-1

2.4 Connecting the AppWorks Gateway to a

A configuration page is displayed to enable you to connect AppWorks Gateway to a

1. In Step 1: Database Configuration you connect AppWorks Gateway to a

Figure 2-3: Connecting to a database

• Microsoft SQL Server

OTAG210300-IGD-EN-1 Installation and Administration Guide 13

4. When connecting to an Oracle Real Application Clusters database, complete the

See Figure 2-3. This information is added to the opentext.properties file, in

14 OpenText™ AppWorks™ Gateway OTAG210300-IGD-EN-1

2.5 Connecting the AppWorks Gateway to OTDS