How to Deploy IBM Support Assistant 5 to Store and Analyze Diagnostic Data

Share this post:

When you have a problem with an app that you’ve deployed in IBM Bluemix, you want to make it as easy as possible to diagnose and resolve the problem. Ideally, you’d be able to automatically capture the failure data, and be able to store and analyze the data in Bluemix, without having to download it. One way to do this is to deploy IBM Support Assistant Team Server as a Bluemix application.

IBM Support Assistant and Bluemix
IBM Support Assistant 5 is designed to be used as a Team Server. A team server is a remote deployment that allows teams to collaborate on troubleshooting and analyzing problems, including tools that can be run against the data directly on the server. By deploying IBM Support Assistant Team Server as an application by using the Liberty build pack, you can take advantage of diagnostic data storage and tools for initial problem analysis for your apps.

The process includes following 5 steps:

  1. Download the IBM Support Assistant 5 Team Server
  2. Repackage IBM Support Assistant for use in Bluemix
  3. Enable user accounts to secure the IBM Support Assistant deployment (Optional)
  4. Create the Liberty Server package and deploy to Bluemix
  5. Create cases for your apps in IBM Support Assistant

1) Download IBM Support Assistant 5 “Team Server”

To download, go to the IBM Support Assistant Team Server page at, and click Download.
Sign in with your IBM credentials, and ensure that you select the Linux compressed zip.

ISA5 download

2) Repackage IBM Support Assistant for use in Bluemix

Before you can run IBM Support Assistant as a Bluemix application, you must repackage it as a Liberty server package. This can be achieved using the following steps:

    1. Download and unpack the Liberty profile runtime from the download link on the WASdev Liberty profile download page.
    2. Run "wlp/bin/server create defaultServer" to create a new server profile called “defaultServer”
    3. Copy the contents of the ISA5/wlp/usr/servers/isa/apps/ISA5.ear file from the downloaded IBM Support Assistant package into the wlp/usr/servers/defaultServer/apps/myapp directory. The myapp directory should then contain the following files:
    1. Copy the ISA5/ToolBox directory to wlp/usr/servers/defaultServer/resources so that there is a ToolBox directory in the “resources” directory.

IBM Support Assistant now needs to have some configuration changes so that it knows where to find the new resources, by modifying the wlp/usr/servers/defaultServer/apps/myapp/ file as follows:

    1. Set the following values:
    1. Add the following value:

The following is a zip file containing a file with the necessary changes made:

3) (Optional) Enabling user accounts to secure the IBM Support Assistant deployment

    1. Add the following entries to the <featuremanager> clause in the wlp/usr/servers/defaultServer/server.xml file:
    1. Add application security for your application by adding the following to the wlp/usr/servers/defaultServer/server.xml file (where “myapp” is the name of your application):
        &lt;application context-root="/" location="myapp" name="myapp" type="ear"&gt;
&lt;security-role name="admin-role"&gt;
&lt;!-- Use the 'adminGroup' group to secure the ISA administration pages --&gt;
&lt;group name="adminGroup" /&gt;
&lt;security-role name="unsecured"&gt;
&lt;special-subject type="EVERYONE" /&gt;
&lt;security-role name="user-role"&gt;
&lt;group name="userGroup" /&gt;
    1. Add a keystore and a basic registry of user IDs and passwords to the wlp/usr/servers/defaultServer/server.xml file:

    &lt;keyStore id="defaultKeyStore" password="{xor}Fgweah06Kz5s" /&gt;
&lt;basicRegistry id="basic" realm="ISABasicRealm"&gt;
&lt;user name="admin" password="admin" /&gt;
&lt;user name="user1" password="user1password" /&gt;
&lt;user name="user2" password="user2password" /&gt;
&lt;group name="adminGroup"&gt;
&lt;member name="admin" /&gt;
&lt;member name="user1" /&gt;
&lt;group name="userGroup"&gt;
&lt;member name="admin" /&gt;
&lt;member name="user1" /&gt;
&lt;member name="user2" /&gt;

The following is a server.xml file with the necessary changes made:

As Bluemix doesn’t allow SSL to the end applications, but terminates it at the proxy tier, the use of the following element must be removed from the web.xml files that use them:


The following files include the element:

4) Creating the Liberty Server package and deploying to Bluemix

    1. Create the server package, by running the following command:

wlp/bin/server package --include=usr

This creates a package in the following directory:

    1. Configure a manifest.yml file for the application to enable additional configurations required for the Liberty buildpack. :

Set a PATH to allow IBM Support Assistant to run Java based tools by adding an env entry to the manifest.yml file:

PATH: $PATH:/home/vcap/app/.java/jre/bin

Enable IBM Support Assistant to create




directories during startup by adding another env entry to the manifest.yml file:

IBM_JAVA_OPTIONS: -Xdump:tool:events=vmstart,exec="mkdir -p /home/vcap/app/ISA5/isa/cases/0000;mkdir -p /home/vcap/app/ISA5/isa/log/tools"

    1. Large memory and disk quota sizes are assigned to allow the tools to run and data to be stored by adding memory and disk_quota values to the manifest.yml file:

  memory: 1024M
disk_quota: 2048M

The following is a manifest.yml file that sets all of these for a deployment called “myISA5TeamServer”:


  1. Push your application using cf push from the directory that contains the manifest.yml and the files.

5) Creating cases for your applications in IBM Support Assistant

Once you’ve deployed your IBM Support Assistant instance, you can create case repositories for each of your deployed applications so that any data created by those applications can be transferred into IBM Support Assistant for storage and analysis. This is done using the following steps:

    1. Log into your IBM Support Assistant instance using the host name from the manifest.yml, appended with “isa5”. For example, for the myISA5TeamServer value used in the sample manifest.yml, this would be:

If you enabled login security, you will need to use your ID and password to log in.

    1. Select Cases > Add and add a case summary such as the name of the application the case is for:

ISA5 Create Case

  1. Take note the Case ID value that is created for the case. This is needed if you want to upload files to the case by using the REST interfaces.
  2. At this point you can add files to the case by selecting the Upload button, or by dragging and dropping files into the Navigator view.


You now have an IBM Support Assistant instance running in Bluemix that’s ready to accept diagnostic data, and let you run tools and analysis!
ISA5 in Bluemix
In my next posting, I’ll show you how to configure applications that use the Liberty build pack to automatically transfer data to a case in your IBM Support Assistant deployment when certain error conditions occur.

More stories
May 7, 2019

We’ve Moved! The IBM Cloud Blog Has a New URL

In an effort better integrate the IBM Cloud Blog with the IBM Cloud web experience, we have migrated the blog to a new URL:

Continue reading

May 1, 2019

Two Tutorials: Plan, Create, and Update Deployment Environments with Terraform

Multiple environments are pretty common in a project when building a solution. They support the different phases of the development cycle and the slight differences between the environments, like capacity, networking, credentials, and log verbosity. These two tutorials will show you how to manage the environments with Terraform.

Continue reading

April 29, 2019

Transforming Customer Experiences with AI Services (Part 1)

This is an experience from a recent customer engagement on transcribing customer conversations using IBM Watson AI services.

Continue reading