Identifying connectivity and configuration issues by running health checks

Introduction to the BMC Digital Workplace Health Check utility

The section introduces the BMC Digital Workplace Health Check utility and describes how you can use it to run health checks. It also provides a comparison of different ways to run the utility.

The following information is provided:

• Need for running health checks
• Solution offered by the  Health Check utility
• Permissions required to run the utility
• Example scenario of using the utility

Need for running health checks

A BMC Digital Workplace environment contains several components such as Apache Tomcat, MongoDB, and Node.js (MyITSocialService). BMC Digital Workplace can be integrated with BMC Digital Workplace Catalog and other BMC products such as BMC Cloud Lifecycle Management and BMC HR Case Management. Occasionally, connectivity or configuration issues can affect accessibility of BMC Digital Workplace or other integrated products.

Solution offered by the BMC Digital Workplace Health Check utility

The BMC Digital Workplace Health Check utility provides an interface to identify connectivity and configuration issues in your BMC Digital Workplace environment. By using the utility, you can narrow down the possible causes for such issues and check the overall health of your BMC Digital Workplace environment. You can run the utility in clustered and non-clustered MyIT environments.

The following table provides additional details about the utility, when the utility is run by using the web interface, script, or CLI.

Permissions required to run the utility

To run the utility, you must belong to the MyIT Super Admin permission group.

Example scenario of using the utility

Allen, a MyIT Super Admin, discovers that BMC Digital Workplace users are unable to use the Social features such as the timeline. He runs the BMC Digital Workplace Health Check utility to find out the possible reasons. When analyzing the results, Allen notices that the Social Server Connection check has failed and the result of MongoDB Database Connection check is UNKNOWN. Allen checks the status of the MyITSocialService service and sees that the service has stopped. Allen restarts the MyITSocialService service to resolve the issue. So, by using the MyIT Health Check utility, Allen can narrow down on possible causes of issues in the BMC Digital Workplace environment.

Video assistance

The following videos demonstrate different methods of running the BMC Digital Workplace Health Check utility:

Running the BMC Digital Workplace Health Check utility

This section provides procedures to run the utility using different interfaces. The following information is provided:

• Before you begin
• To run the  Health Check utility from the web interface
• Example and output of running the utility from the web interface
• To run the  Health Check utility from CLI
• Parameters for running the utility from CLI
• Example and output of running the utility from CLI
• To run the  Health Check utility script
• Parameters for running the utility script
• Examples and output of running utility by using a script

Before you begin

• Ensure that you have the MyIT Super Admin permission.
• Ensure that the BMC Digital Workplace server is running, and is accessible via http or https.
• (For running the script or running the utility using CLI) Ensure the following points:
  • You can access the computer where BMC Digital Workplace is installed.
  • The MYIT_HOME\Smart_IT_MyIT\health-check directory is available and accessible.
    Here MYIT_HOME is the directory where BMC Digital Workplace is installed.The default BMC Digital Workplace installation location is as follows:
    • (Windows) C:\Program Files\BMC Software\Smart_IT_MyIT\
    • (Linux) /opt/bmc/Smart_IT_MyIT/
  • The health-check directory contains the following utility files:
    • health-runner-version.jar, where version is BMC Digital Workplace version
      
    • healthcheck.bat
    • healthcheck.sh
  • The computer on which you run the utility has Java Runtime Environment (JRE) version 8 or later.
  • JAVA_HOME or Java bin directory is present in the executable file path. Run the java -version command to verify of Java is configured correctly.

To run the BMC Digital Workplace Health Check utility from the web interface

1. Enter the URL in a web browser. Use the appropriate URL format:
   
   • (Non-clustered environment) http://bmcMyITHostName:port/ux/healthcheck/
   • (Clustered environment) http://loadBalancerHostName:port/ux/healthcheck/
2. Enter your BMC Digital Workplace credentials and click Log in.
   The utility runs the checks and presents the results.

Example and output of running the utility from the web interface

To run the BMC Digital Workplace Health Check utility from CLI

1. (When running the utility from a non-host computer) Copy the health-check directory to the non-host computer.
2. At the command prompt on the computer where you are running the utility, navigate to the health-check directory.
3. Run the utility by using the appropriate command. The command is same for Windows and Linux computers.
   For details about the parameters, see Parameters for running the utility from CLI.

   • Use the following command, when running the utility directly on a BMC Digital Workplace host:

     java -jar health-runner-<version>.jar -s http://localhost:9000/ux -u <userName> -p <password>

   • Use the following command, when running the utility from a non-host computer, for a BMC Digital Workplace host:

     java -jar health-runner-<version>.jar -s http://<bmcMyITHostName>:9000/ux -u <userName> -p <password>

   • Use the following command, when running the utility for a load balancer host:

      java -jar health-runner-<version>.jar -s http://<loadBalancerHostName>:9000/ux -u <userName> -p <password>

Parameters for running the utility from CLI

All parameters in the command are mandatory. The following table describes the parameters:

Example and output of running the utility from CLI

To run the BMC Digital Workplace Health Check utility script

1. (When running the utility from a non-host computer) Copy the health-check directory to the non-host computer.
2. On the computer where you are running  the utility, navigate to the health-check directory and edit the healthcheck.bat file (Windows) or healthcheck.sh file (Linux) by using a text editor such as Notepad.
3. Define values for the server_url, username, and password parameters, which are mandatory. Optionally, define the value for use_untrusted_cert parameter.
   For details about these parameters, see Parameters for running the utility script.
4. Save and close the file.
5. Run the utility by double-clicking the script file.

Parameters for running the utility script

The following table describes the parameters you must define:

Examples and output of running utility by using a script

Interpretation of health check results

This section provides the information about the checks run by the utility, result statuses and description of each check. The section also provides information about corrective actions in case of failures. The following information is provided:

• Health check statuses
• Health check descriptions and corrective actions

Health check statuses

The result of each health check is presented by using the following statuses:

• PASSED—When no connectivity or configuration issues with the integrated application are found.
• FAILED—When there is a connectivity or configuration issue with an integrated application, or if BMC Digital Workplace is not integrated with an application.
• UNKNOWN—When BMC Digital Workplace is integrated with a particular application, but the service is disabled.

Health check descriptions and corrective actions

The table that follows lists the checks run by the BMC Digital Workplace Health Check utility and provides possible reasons of failure and the corrective actions.

Troubleshooting

When you run the BMC Digital Workplace Health check utility scripts or run the utility from CLI, the utility records information in the debug.log file, located in the MYIT_HOME\Smart_IT_MyIT\health-check directory. See that file for detailed information about errors that might occur while running the utility and the associated checks and results.