Posted May 10 by Edmund Clayton.
Updated Oct 30.

Advice on additional setup options and basic troubleshooting in OpenText AppWorks Gateway.

Last activity Oct 30 by Edmund Clayton.
581 views. 0 comments.

Chapter 11 – OpenText AppWorks Gateway Frequently Asked Questions

11.1 – 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:

  1. Stop the Apache Tomcat service.

  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.

  6. Start the Apache Tomcat service.

    In an AppWorks Gateway multi-tenant environment, the log file includes information for the primary installation and all tenants.

    Note: Once you have completed any troubleshooting tasks, return the log level to its lower level to prevent excessive log file creation.

11.2 – 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.log and localhost-access_logs..txt.

For debugging, first check the Catalina log for errors, and if necessary check the localhost-access_logs..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 \logs directory on the Tomcat server
used to host your OTDS installation. The OTDS log files are also available in the OTDS 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 into the AppWorks Gateway and click Overview in the left pane.

  2. Double check that the credentials and server URL were typed correctly. This isoften 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. Log in to the OTDS Web client and check that the user’s account hasn’t expired or been locked.

  6. Add a new user in the AppWorks Gateway. Then, sign in to OTDS Web client and verify that the new user was added to the otag partition.

11.3 – How can I troubleshoot the deployment 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.

11.4 – 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 Google Cloud Messaging (GCM) communications when the environment within which AppWorks 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 AppWorks Gateway.

  1. Stop the Apache Tomcat service.

  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=proxysyd.cloud.yourserver.com"

    • export CATALINA_OPTS="$CATALINA_OPTS -Dhttp.proxyPort=80"

    • export CATALINA_OPTS="$CATALINA_OPTS -Dhttps.proxyHost=proxysyd.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

    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.

    Tip: Select the Active Push Notification Logging check box in the Notifications section of the AppWorks Gateway, and then check the gcm.log to confirm that GCM messages are being sent correctly.

    Tip: Use cURL, via a terminal session. to check the server host itself can connect to GCM 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 proxysyd. cloud.yourserver.com:80 https://gcm-http.googleapis.com

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

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

11.6 – 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 16.6, 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 the AppWorks Gateway 16.6 with any supported version of OTDS, including 16.4.3.

To correct the issue, do the following:

  1. In the OTDS Administration web client, 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.

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

Top of page


Table of Contents

Your comment

To leave a comment, please sign in.