Posted Nov 23 by Edmund Clayton.
Updated Nov 23.

Learn how to install the OpenText AppWorks Gateway version 16.5

Last activity Nov 23 by Edmund Clayton.
208 views. 0 comments.

Chapter 1 – Installing the OpenText AppWorks Gateway

The AppWorks Gateway is a simple Apache Tomcat application, which requires JDK 1.8.x and Apache Tomcat 8.0.x. It also needs to connect to a production database such as Microsoft SQL Server, MySQL, Oracle, Oracle RAC, PostgreSQL, or SAP HANA. You need to create a schema and an associated schema admin user before installing the AppWorks Gateway.

The AppWorks Gateway stores your users in OpenText Directory Services (OTDS). During the AppWorks Gateway configuration, you can choose to install OTDS or connect to an existing installation of OTDS.

Before you start, review the AppWorks Gateway Release Notes for 16.5 The Release Notes contain comprehensive information on supported environments, language support, and the compatibility of release 16.5 with other OpenText products.
The Release Notes are available from the Get Started section of the AppWorks Developer website.

Important: This article does not replace the documentation 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 on the OpenText My Support at OpenText Knowledge Center. These guides may include additional or modified steps for installing the AppWorks Gateway.

1.1 – Prerequisites

The AppWorks Gateway requires the following software.

  1. JDK 1.8.x.

    Important: If you choose to install AppWorks Gateway with the embedded OTDS option, you should use a JDK prior to JDK 8u181. Some changes were made in Java 8u181 that may affect OTDS installation and operation. Note that the embeded OTDS is not for use in a production environment.

  2. Apache Tomcat 8.0.x, 8.5.x, or 9.0.x.
    If your database iss Oracle, only Tomcat 9.0.x is supported.

    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.

  3. A database.

    For production environments, you will need to create a schema and an associated schema admin user in your Microsoft SQL Server, MySQL, Oracle, Oracle RAC, PostgreSQL, or SAP HANA production database.

    For evaluation or test purposes, you can connect to an Embedded Derby database, which is an open source relational database that is implemented entirely in Java. The Derby database is not suitable in a production environment.

  4. An OTDS Installation.

    AppWorks Gateway 16.5 requires OpenText Directory Services 16 for OAuth and two-factor authentication. OTDS 10.5 can be used if you do not require OAuth or two-factor authentication. Earlier versions of OTDS are not supported. For evaluation or test purposes, you can install a built-in instance of OTDS. This option is not suitable in a production environment.

1.2 – Configuring Apache Tomcat for the AppWorks Gateway

To configure Apache Tomcat for the AppWorks Gateway:

  1. Ensure you have met the prerequisite requirements. For details, see 1.1 - Prerequisites.

  2. Stop the Apache Tomcat service.

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

  4. Double-click Tomcat8w.exe and do the following:

    a. Click the Java tab.

    b. Type 4096 in the Maximum memory pool box.

    c. Click OK.

    'Apache Tomcat' Java options

    Figure 1-1: Apache Tomcat Java options

  5. Start the Apache Tomcat service to make sure your Tomcat installation starts correctly with these new settings.

1.3 – Installing the AppWorks Gateway

Important: OpenText strongly suggests installing the AppWorks Gateway and Apache
Tomcat on a dedicated server.

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 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 the AppWorks Gateway Downloads page.

  4. Extract the contents of the otag-gateway-16.5.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:

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

1.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 the AppWorks Gateway to a database.

Important: After the installation is complete, 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. 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 \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\ 9.4\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.

    • Embedded Derby - This database requires no configuration and can be used for testing and evaluation purposes. It is not appropriate to a production environment.

  2. In the Username and Password fields, type the credentials for an admin user of your database.

  3. When connecting to an Oracle Real Application Clusters database, do the following:

    a. In the Load Balance area, choose if you would like to enable client side load balancing.

    b. In the Cluster Host box, type the virtual cluster name that you chose when you created the RAC database.

    c. In the Port box, type the port. The default port for Oracle is 1521.

    d. In the Service Identifier box, type the virtual service name that you chose when you created the RAC database.

    See Figure 1-2. This information is added to the opentext.properties file, which is located in the <Tomcat_Home>\config folder. The information will appear encrypted in this file.

    Connecting to an Oracle Database

    Figure 1-2: Connecting to an Oracle RAC Database

  4. Click Configure Database Connection and wait for a confirmation that the connection is established.

1.5 – Connecting the AppWorks Gateway to OTDS

After you have connected AppWorks Gateway to a database, the next step is to
connect to OTDS. You can choose an existing, external OTDS instance, or a built-in
instance that will be automatically configured for you. The built-in OTDS instance
enables you to quickly install AppWorks Gateway for evaluation purposes, but it is
not suitable for a production environment.

Important: Once you have defined the connection to OTDS, you cannot make changes to it. For example, you cannot switch from the built-in OTDS instance to an existing, external one, and you cannot switch from one existing OTDS instance to another.

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

Connecting to an existing OTDS installation

To connect to an existing OTDS installation, do the following:

  1. From the Select OTDS Configuration drop down, select Connect to existing OTDS server.

    Connect to an existing OTDS server

    Figure 1-4: Connect to an existing OTDS server

  2. Complete the required information.

    The Gateway Admin Username and Password defines the AppWorks Gateway administrative user account that will be created in Directory Services. The default Gateway Admin Username is otag. The password you choose will depend on your OTDS global password policy. Be default, the password is alphanumeric with 8 characters.

    OTDS server url requires the URL of the Tomcat server that is running OTDS. Do not use http://localhost:8080.

    OTDS Administrative Account Username and Password require 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 names are OTAG and otag respectively.

    Note: If you have other AppWorks Gateway installations that connect to the OTDS installation, 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 again. Before you sign in to the AppWorks Gateway, open a second browser and go to the Directory Services Web Client at <https://Tomcat_Host:port>/otds-admin/.

  4. Sign in as the OTDS admin user using otadmin@otds.admin as the username and the password you defined in the OTDS admin user password box.

  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 otadmin@otds.admin 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.

Installing the AppWorks Gateway with Built-in OTDS

Before you begin the installation, ensure that the JAVA_HOME variable is pointing to the root of your Java install. Specifically, this variable should not point to the <Java_Home>/bin directory. Also, ensure that the PATH variable includes the location of the Java executable.

To install AppWorks Gateway with OTDS:

  1. From the Select OTDS Configuration drop-down, select Install with AWG.

    Install OTDS with AppWorks Gateway

    Figure 1-3: Install OTDS with AppWorks Gateway

  2. Complete the required information, as follows:

    Gateway Admin Username and Password - Defines the AppWorks Gateway administrative user account that will be created in OTDS. The default Gateway Admin Username is otag.

    OTDS admin user password - Defines the password for the OTDS administrative user. The password you choose must be alphanuermic. The OTDS administrative username is otadmin@otds.admin. During the OTDS configuration, an AppWorks Gateway Resource and User Partition are created and named OTAG and otag respectively.

  3. Click Configure OTDS. The configuration is complete when you are prompted to sign in to the AppWorks Gateway again. Before you sign in, open a second browser and go to the Directory Services Web Client at http://<Tomcat_Host:port>/otds-admin/.

  4. Sign in as the OTDS admin user using otadmin@otds.admin as the username and the password you defined in the OTDS admin user password box 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 otadmin@otds.admin 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.

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

Top of page



Table of Contents

Your comment

To leave a comment, please sign in.