Identifying the origin of environmental issues by running diagnostic checks
Example scenario
In Calbro Services, after making some BMC Remedy AR System configuration changes, Allen (a BMC Digital Workplace administrator) notices issues in the working BMC Digital Workplace environment. Allen uses the diagnostic utility to find out the origin of the issues. The BMC Remedy AR System checks fail, which indicate that the diagnostic utility cannot log in to BMC Remedy AR System by using the configuration stored in the CONFIGURATION_PARAMETER table. Allen updates the BMC Remedy AR System configuration information, which resolves the issue.
Video demonstrations
The following videos demonstrate different methods to run diagnostic checks:
Before you begin
- Ensure that you can access the computer where BMC Digital Workplace is hosted.
- Ensure that you can access the DWP_HOME\DWP\ directory, where DWP_HOME is the directory where BMC Digital Workplace is installed. The default installation location is as follows:
- (Windows) C:\Program Files\BMC Software\DWP
- (Linux) /opt/bmc/DWP/DWP
Ensure that the diagnostic utility files are available in DWP_HOME\DWP\diagnostic\ directory. The diagnostic utility file names are as follows:
- (Web interface) diagnostic-agent-version.jar
- (Command-line interface) diagnostic-runner-version.jar
- (Scripts) diagnostic.bat (Windows) or diagnostic.sh (Linux)
Here, version is the BMC Digital Workplace version.
To run diagnostic utility from the web interface
You must initialize the utility by running the diagnostic-agent-version.jar file directly on the BMC Digital Workplace host. You can view the results by accessing the web interface from the BMC Digital Workplace host or from a non-host computer. You can view the results multiple times by using the web interface, until you manually close the diagnostic-agent-version.jar file.
In clustered BMC Digital Workplace environments, to diagnose issues on individual nodes, you must run the utility separately on every node in the cluster.
- Open the command prompt and navigate to the directory where the diagnostic-agent-version.jar file is located.
Initialize the diagnostic utility by running the following command:
java -jar diagnostic-agent-<version>.jar --tomcat="path_to_tomcat_home" --port=<port number>If you do not specify any port number, the default 8080 port will be used.
- Ensure that Apache Tomcat server started on the port.
- Access the web interface using a web browser; enter the URL in following format:
http://hostName:portNumber/
Example and output
Example command |
|
|---|---|
Output | Results are presented on a web page. For information about diagnostic checks and their results, see Interpretation of diagnostic check results. |
To run the diagnostic utility from CLI
Run the diagnostic-runner-version.jar file directly on a BMC Digital Workplace host. In clustered BMC Digital Workplace environments, to diagnose issues on individual nodes, you must run the utility separately on every node in the cluster.
- Open the command from and navigate to the directory where the diagnostic-runner-version.jar file is located.
Run the following command:
java -jar diagnostic-runner-<version>.jar --tomcat="path_to_tomcat_home"
Example and output
Example command | java –jar diagnostic-runner-3.3.00.000.jar --tomcat="C:\Program Files\Apache Software Foundation\Tomcat8" |
|---|---|
Output | Results are presented in the following ways:
The debug.log file located in the DWP_HOME\DWP\diagnostic directory provides additional details in case issues occur while running utility. The file also provides the stack trace of failed checks. For information about diagnostic checks and their results, see Interpretation of diagnostic check results. |
To run the utility by using a script
Run the diagnostic.bat or diagnostic.sh file directly on a BMC Digital Workplace host. In clustered BMC Digital Workplace environments, you must run the utility separately on every node in the cluster.
- Navigate to the diagnostic directory, and edit the diagnostic.bat (Windows) or diagnostic.sh (Linux) file by using a text editor such as Notepad.
- Define the value of tomcat_dir parameter, which specifies the location of the Apache Tomcat home directory.
- Save and close the file
- Run the diagnostic.bat or diagnostic.sh file.
Example and output
Example parameter | set tomcat_dir=C:\Program Files\Apache Software Foundation\Tomcat8 |
|---|---|
Output | Results are presented in the following ways:
The debug.log file located in the DWP_HOME\DWP\diagnostic directory provide additional details in case issues occur while running utility. The file also provides the stack trace of failed checks. For information about diagnostic checks and their results, see Interpretation of diagnostic check results. |
Interpretation of diagnostic check results
This section provides information about the checks run by the diagnostic utility, result statuses, and a description of each check, along with corrective actions in case of failures:
Diagnostic check statuses
The result of each health check is presented using the following statuses:
- PASSED—When no configuration issues are found.
- FAILED—When failure occurs. The reason for failure could be different for each check, for example, missing configuration, missing files, and connection issues.
Diagnostic check descriptions and corrective actions
The following table lists the diagnostic checks, provides possible causes of failure, and first-line corrective actions: