Posted Apr 30 by Edmund Clayton.
Updated Nov 23.

Learn how to upgrade the OpenText AppWorks Gateway to version 16.4

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

Chapter 2 – Upgrading the OpenText AppWorks Gateway

You can upgrade the AppWorks Gateway to 16.4 from all previous 16.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 need to remove AppWorks Gateway 1.2.x, then install AppWorks Gateway 16.4. For further details, see 2.2 – Upgrading from AppWorks Gateway 1.2.x.

After upgrading to 16.4 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 2.3 – Adding a URL Rewrite to AppWorks Gateway 16.4.

2.1 – Upgrading AppWorks Gateway 16.x

Use this procedure to upgrade from an AppWorks Gateway 16.x version to AppWorks Gateway 16.4.

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

  3. Back up the Apache Tomcat directory where AppWorks is installed.

  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.xmlfile. The upgrade overwrites the server.xml file in the <Tomcat_Home> /confdirectory.

  5. Navigate to the <Tomcat_Home> directory and do the following:

    a. Delete the gateway folder.

    b. Delete the contents of the following folders:

    • work\Catalina\localhost

    • temp

    • tmp

    • logs

  6. Extract the contents of the otag-gateway-16.4.zip file to the root of the Apache Tomcat folder. For example, C:\\Program Files\Apache Software Foundation\Tomcat 8.0.

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

  8. Start the Apache Tomcat service.

  9. In a browser, type https://<Tomcat_Host:port>/gateway and sign in to AppWorks Gateway. All of your applications and settings should be present.

2.2 – Upgrading from AppWorks Gateway 1.2.x

Use this procedure to upgrade to AppWorks Gateway 16.4 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 16.4.
  2. Uninstall AppWorks Gateway 1.2.x.
  3. Install and configure AppWorks Gateway 16.4.

Note: When you upgrade from AppWorks Gateway 1.2.x to 16.4, 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 16.4 will not complete and you will need to repeat the process, supplying new values.

To create a new database schema for AppWorks Gateway 16.4:

  1. Sign in to your database management tool and create a new database schema for AppWorks Gateway 16.4 to use.

    Note: If you created a database schema for AppWorks Gateway 1.2.x, do not delete the schema until your 16.4 installation is complete and you have confirmed that it works as expected.

To uninstall AppWorks Gateway 1.2.x:

  1. Stop the Apache Tomcat service.

  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 16.4. For details, see Chapter 1 - Installing the OpenText AppWorks Gateway. However, if you have other software installed in 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 that is located in the <Tomcat_Home>\webapps folder.

    • opentext.properties that is 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 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 16.4

2.3 – Adding a URL Rewrite to AppWorks Gateway 16.4

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

  1. Stop the Apache Tomcat service.

  2. Go to the UrlRewriteFilter web site.

  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>
    
  7. Start the Apache Tomcat service.

    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.

2.4 – Upgrading 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 release, without making any changes to AppWorks Gateway. Or, you might want to upgrade both Apache Tomcat and the AppWorks Gateway at the same time. There are different steps to take, depending on the version of Apache Tomcat you are upgrading to. The following upgrade paths are addressed:

  • Upgrading from 8.0.x to a later 8.0.x version, for example, from 8.0.20 to 8.0.49, for Windows and Linux.
  • Upgrading from 8.0.x to 8.5.x, or 9.0.x, for Windows and Linux.

To upgrade from 8.0.x to a later 8.0.x version (Windows)

  1. Download the latest version of the Apache Tomcat 8.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 8.0.x Windows Installer to install the updated version of Tomcat as a Windows Service.

    Note: 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. For details, see “Configuring Apache Tomcat for the AppWorks Gateway” in Chapter 1 - Installing the OpenText AppWorks Gateway.

  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 changes 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 folder structure along with the backups taken during the above process.

To upgrade from 8.0.x to a later 8.0.x version (Linux)

  1. Download the latest version of the Apache Tomcat 8.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-8.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.

To upgrade from 8.0.x to 8.5.x or 9.0.x (Windows)

  1. Download the latest version of the Apache Tomcat 8.5.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 8.5.x Windows Installer to install the updated version of Tomcat as a Windows Service.

    • 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” 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 changes 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 folder structure along with the backups taken during the above process.

To upgrade from 8.0.x to 8.5.x or 9.0.x (Linux)

  1. Download the latest version of the Apache Tomcat 8.5.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-8.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.

2.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“ for details.

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.

Top of page



Table of Contents

Your comment

To leave a comment, please sign in.