Posted Nov 23 by Edmund Clayton.
Updated Nov 23.

Learn how to install and enable your mobile and desktop apps, services and components.

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

Chapter 4 - Getting Started with the OpenText AppWorks Gateway

The AppWorks Gateway is a deployment and management tool for applications, components, and their associated services.

4.1 - Installing Apps, Services, and Components

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, and component:

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

  2. Sign in to the AppWorks Gateway as an admin user.

  3. In the left pane, 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.

  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.

4.2 - Enabling Apps, Services, and Components

To enable an app, service or component:

  1. In the AppWorks Gateway, do one of the following:

    • In the left pane, click Apps 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.

    • In the left pane, click Desktop Apps 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.

    • In the left pane, click Components and then click Enable for all of the components you installed.

    • In the left pane, click Services and then click Enable for all of the services 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.

    Tip: You can also enable all of the Apps, Components, and Services by clicking All in the left pane and then Enable All.

  2. Repeat step 1 for all of the apps, services, and components that you would like your users to access.

4.3 - Viewing Details and Downloading Apps, Services, and Components

To view details and download apps, services, and components:

  1. In the left pane of the AppWorks Gateway, click Apps, Services, or Components.

  2. Click the Settings icon for the app, component, or service for which you want to view property details.

  3. Do one of the following:

    • Summary - View the version number, install 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 in order for the app to work in another AppWorks Gateway. Click Components or Services in the left pane 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.

  4. Audience - Filter the app based on runtime, user, or group. For details, see 4.4 - Filtering the Runtime and User Audience.

    • Deployments - View the deployment status of the feature.

4.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 or Google Play. 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 left pane of the AppWorks Gateway, click Apps.

  2. Click the Settings 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 in the left pane. Complete the displayed fields and click Add. Repeat steps 2 – 3, only this time select the check box next to the new runtime.

      enter image description here

    Figure 4-1: Filtering the Runtime Audience

  4. Click Save.

To filter the users and groups who can see an app:

  1. In the left pane of the AppWorks Gateway, click Apps.

  2. Click the Settings icon for the app that you want to filter.

  3. Click the Audience tab.

  4. Click the User/Group/Partitions 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.

    • To display the app in the runtimes of only a specific user or group, clear the Available to all users check box. In the Search for Users/Groups/Partitions box, type the first few letters of the username, first name, last name, or group name to whom you want to grant access to this app. A list of users or groups displays. Select one or more check box for the user or group.
      enter image description here

    Figure 4-2: Filtering Users and Groups

  5. Click Save.

4.5 - Distributing 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 Chapter 10 - AppWorks Gateway Settings.

To distribute mobile clients:

  1. In the left pane of the AppWorks Gateway, click Mobile Client Distribution.

  2. In the Send Distribution Email region, select a runtime that will be included in the email.

  3. In the same region, you can choose to send an email to a specific group(s) in OTDS, to specific users by entering their email address, or to a list of users that are in a CSV file.

  4. Click Send Email.

4.6 - Distributing Desktop Clients

The AppWorks Gateway desktop clients for Windows and macOS® are available from the AppWorks Gateway Downloads page.

To install the Desktop Client using the MSI Windows installer:

  1. Download and run the MSI Windows installation file.

  2. Confirm that you have read the OpenText End User License Agreement, and click Next to display the Custom Setup dialog.

  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.

  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.

    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.

4.7 - Connecting to the AppWorks Gateway Server URL for Mobile and Desktop

When using the OAuth 2 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. The OpenText login page shoudl be 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.

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

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.

To export the root CA certificate on 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.

  1. Open Firefox and navigate to the HTTPS address of the AppWorks Gateway login page at https://<Tomcat_Host>:<port>/gateway.

  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.

To convert the CRT file to a PEM file:

In this step, you convert the CRT file to a PEM file using OpenSSL commands.

  1. Open a command prompt window and navigate to the location of the root CA CRT file that you exported.

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

    Note: The output file must be called ca.cert.pem.

To add the PEM file to the Application Data folder:

In this step, you add the PEM file that you created earlier to to the Application Data folder on the machine where you installed the desktop client.

  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.

    Note: 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-----
    -----BEGIN CERTIFICATE-----
    <Certificate for INTERMEDIATE CERTIFICATE AUTHORITY 1>
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    <Certificate for ROOT CERTIFICATE AUTHORITY>
    -----END CERTIFICATE-----`

4.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 and click Uninstall.

    • For Windows 10, navigate to Apps & features, select the OpenText AppWorks Desktop and click Uninstall.

  2. Open Windows Explorer and take one of the following options:

    • If you have the eDOCS Info Center client installed, navigate to the following
      folder and delete the contents:

      C:\Users\<your user name>\AppData\Roaming\appworks-desktop\edocs-infocenter

    • If you do not have the eDOCS Info Center client installed, navigate to the following
      folder and delete the contents:

      C:\Users\<your user name>\AppData\Roaming\appworks-desktop\standard

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 do one of the following:

    • If you have the eDOCS Info Center client installed, navigate to the following
      folder, and delete the contents:

      ~/Library/Application\ Support/appworks-desktop/edocsinfocenter

    • If you do not have the eDOCS Info Center client installed, navigate to the
      following folder, and delete the contents:

      ~/Library/Application\ Support/appworks-desktop/standard

4.10 - 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:

  1. Sign in to the AppWorks Gateway as an admin user.

  2. In the Admin menu, click Notification Test from the Push Notification section.

  3. In the Native Alert region, enter a Title and Notification Summary.

  4. In the AppWorks Data region, enter the Data Summary and Data Payload. 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.

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

  6. In the Target AppWorks App box, click Search App and search for the app to which you want to send the notification.

  7. In the Username/First Name/Last Name field, search for the user to whom you want to send this notification.

  8. Select the required user from the search result.

  9. Click Send.

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

enter image description here

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

Top of page



Table of Contents

Your comment

To leave a comment, please sign in.