Posted May 10 by Edmund Clayton.
Updated May 13.

Learn how to install the OpenText AppWorks Gateway version 16.6

Last activity May 13 by Edmund Clayton.
645 views. 0 comments.

Chapter 1 – Installing the OpenText AppWorks Gateway

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

Before you start, review the AppWorks Gateway Release Notes for 16.6 The Release Notes contain important information on supported environments, language support, and the compatibility of release 16.6 with other OpenText products, such as Content Server.
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 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.

  2. Apache Tomcat 8.5.x, or 9.0.x.
    If your database is 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 Apache Derby database is not suitable in a production environment.

  4. An OTDS Installation.

    OTDS centralizes user and group identity information and manages single sign on (SSO) between OpenText components. AppWorks Gateway 16.6 requires OpenText Directory Services 16 for OAuth 2.0 and 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 installed the required software For details, see 1.1 - Prerequisites.

  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:

    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.

    '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

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.6.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 you have specified a database and completed the installation, you cannot choose a different database for AppWorks Gateway. Therefore, ensure that you connect 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. This recommendation refers to when you connect AppWorks Gateway to an existing instance of OTDS, not when you install the built-in OTDS instance.

Connecting to an existing OTDS installation

To connect to an existing OTDS installation::

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

    Connect to an existing OTDS server

    Figure 1-4: Connect to an existing OTDS service

  2. Complete the required information, as follows.

    The Gateway Admin Username and Password credentials are for the AppWorks Gateway administrative user account that will be created in Directory Services. The default Gateway Admin Username is otag. The password you choose depends on your OTDS global password policy. By 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 are 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.