Limited support

 

This version of the product is in limited support. However, the documentation is available for your convenience. You will not be able to leave comments. Click here to view the documentation for the current version.

Identifying the origin of environmental issues by running diagnostic checks

In a  BMC Digital Workplace  environment, issues with different components such as BMC Remedy Action Request System (BMC Remedy AR System),  BMC Digital Workplace  server, database server, and social server, might prevent  BMC Digital Workplace  from functioning normally. You can identify the origin of such issues in your working  BMC Digital Workplace  environment by running the diagnostic utility.

The diagnostic utility performs checks and provides a detailed report about the status of the environment components. The utility does not require the  BMC Digital Workplace  server to be running, as it has a built-in Apache Tomcat runner that is initialized after you run the utility. In both clustered and non-clustered  BMC Digital Workplace  environments, you can run the diagnostic utility by using the web interface, by running the utility from CLI, or by running a script.

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

Note

The following videos show an older version of BMC Digital Workplace . The previous product name was MyIT. Although there might be minor changes in the UI, the overall functionality remains the same.

The following videos demonstrate different methods to run diagnostic checks:

VideoDescription

https://youtu.be/GaRi8V5k4B4

This video (4:05) provides an overview and demonstration of running the diagnostic utility from the web interface

https://youtu.be/7CoKUzrnvdA

This video (3:52) provides an overview and demonstration of running the diagnostic utility from CLI.

https://youtu.be/y34_Fi5IyJE

This video (3:37) provides an overview and demonstration of running the diagnostic utility by using scripts.

Before you begin

  • Ensure that you can access the computer where BMC Digital Workplace  is hosted.  
  • Ensure that you can access the MYIT_HOME\Smart_IT_MyIT\ directory, where MYIT_HOME is the directory where BMC Digital Workplace  is installed. The default installation location is as follows:
    • (Windows) C:\Program Files\BMC Software\Smart_IT_MyIT\
    • (Linux) /opt/bmc/Smart_IT_MyIT/
  • Ensure that the diagnostic utility files are available in MYIT_HOME\Smart_IT_MyIT\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.

  1. Open the command prompt and navigate to the directory where the diagnostic-agent-version.jar file is located.
  2. 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.

  3. Ensure that Apache Tomcat server started on the port.   
  4. Access the web interface using a web browser; enter the URL in following format:
    http://hostName:portNumber/

Example and output

Example command
  • Command to initialize the diagnostic utility:

    java –jar diagnostic-agent-3.3.00.000.jar --tomcat="C:\Program Files\Apache Software Foundation\Tomcat8.0" --port=80
  • URL to access the web interface:

    http://myserver.abc.com:80/

Output

Results are presented on a web page.

For information about diagnostic checks and their results, see Interpretation of diagnostic check results later in this topic..

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.

  1. Open the command from and navigate to the directory where the diagnostic-runner-version.jar file is located.
  2. 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"
OutputResults are presented in the following ways:
  • On the CLI
  • In the diagnostic.log file, located in the MYIT_HOME\Smart_IT_MyIT\diagnostic directory

The debug.log file located in the MYIT_HOME\Smart_IT_MyIT\diagnostic directory provide additional details in case there are any issues 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 later in this topic.

To run the utility by using a script

Run the diagnostic-runner.bat or diagnostic-runner.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.

Warning

Do not update any code in the script, other than the specified parameters. Doing so might result in script failure.

  1. Navigate to the diagnostic directory, and edit the diagnostic.bat (Windows) or diagnostic.sh (Linux) file by using a text editor such as Notepad.  
  2. Define the value of tomcat_dir parameter, which specifies the location of the Apache Tomcat home directory.  
  3. Save and close the file
  4. 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:

  • On the CLI.
  • In the diagnostic.log file, located in the MYIT_HOME\Smart_IT_MyIT\diagnostic directory.

The debug.log file located in the MYIT_HOME\Smart_IT_MyIT\diagnostic directory provide additional details in case there are any issues 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 later in this topic.

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

Important

Use the corrective actions with caution. This is not an exhaustive list of causes of failure, and there might be other reasons of failure that require in-depth analysis. For further help, contact BMC Support Open link .

The following table lists the diagnostic checks, provides possible causes of failure, and first-line corrective actions:

Check typeDescriptionCorrective actions in case of failure

Checks for the connect.properties file

The checks succeed if following conditions are met:

  • The connect.properties file is present in the  <Tomcat_home>/external_conf directory.
  • The connect.properties file is not empty
Ensure that the location of connect.properties file is correct and the file is readable.
Social checks

The checks succeed if following conditions are met:

  • Social is configured in the connect.properties file
  • The Social API token (api.token.value = encrypted password ) is present in the connect.properties file
  • Ensure that the values of Social connection settings are correct and the Social service is running.
  • Ensure that the Social API token (api.token.value = encrypted password ) is present in the connect.properties file. It can be located at the bottom of the file. Value of the token and the encrypted password must match the values defined in the SHR:SHR_KeyStore form in BMC Remedy IT Service Management (BMC Remedy ITSM).
SMTP checkThe check succeeds if SMTP is configured in the connect.properties file.
  • On the server defined in the connect.properties file, ensure that SMTP service is running
  • In the connect.properties file, ensure that the SMTP parameters in the file are set.

Webapp check

The check succeeds if the version.properties file is present in the \ux\WEB-INF\classes\ directory.

  • Ensure that the version.properties file is present at the specified location.
Logs checkThe check succeeds if the logback.xml file is present in the <Tomcat_home>\external_conf directory. 
  • Ensure that the logback.xml file is present at the specified location.
Database checks

The following database checks are run:

  • Business database is reachable check—Succeeds if the diagnostic utility can login to the business database
  • System database is reachable check—Succeeds if the diagnostic utility can login to the system database
  • ux.xml file contains DB configuration check—Succeeds if the ux.xml file contains configuration for business and system database schemas
  • Load JDBC driver check—Succeeds if the diagnostic utility can load the JDBC driver specified in ux.xml file
  • Ensure that the database services are running.
  • From the BMC Digital Workplace host, verify database connectivity using database clients such as SQL Server Management Studio or Oracle SQL Developer.
  • If databases are reachable and the services are running, ensure that the database configuration in ux.xml file is correct.
BMC Remedy AR System configuration checks

The following checks verify BMC Remedy AR System configuration:

  • AR configuration is present check—Succeeds if CONFIGURATION_PARAMETER table in the system database contains shared AR System server hostname, port, and password
  • Login to shared AR check—Succeeds if the diagnostic utility is able to log in or log out from the shared AR System server by using the credentials from the CONFIGURATION_PARAMETER table
  • Metadata is reachable check Succeeds if the application settings of BMC Digital Workplace and BMC Remedy ITSM for the tenant, and the BMC Remedy ITSM data store configurations are present in the BMC Digital Workplace Admin console
  • Category metadata queries are available check— Succeeds if metadata contains the following queries:
    • MYIT_ALL_CATEGORIES
    • MYIT_CATEGORY_BY_ID
    • MYIT_ALL_CATEGORIES
      _DEFAULT_LOCALE
  • AR configuration is present check— In the CONFIGURATION_PARAMETER table, ensure that the AR System server or AR System server group load balancer details are correct:
    • connect.arsystem.hostName
    • connect.arsystem.port
    • connect.arsystem.password
  • Login to shared AR check—Ensure that you can log in to the AR System server; By using telnet or ping command from the BMC Digital Workplace host, check the connectivity with AR System server.
  • Metadata is reachable check—Ensure that the application settings and data store configuration for BMC Remedy ITSM are present in the BMC Digital Workplace Admin console.
  • Category metadata queries are available check—Look for any exceptions or errors in the ux-metadata.log file, which is located in the C:\Program Files\BMC Software\Smart_IT_MyIT\Smart_IT_MyIT\Logs directory, and contact  BMC Support Open link for further assistance .
Tenant-specific checks

Tenant specific checks run for every tenant in the BMC Digital Workplace environment. The following checks verify whether the respective database tables contains valid number of rows:

  • Tenant configured check—verifies whether the TENANT table contains tenant configuration.
  • Push notification certificates are present in DB check

  • FEATURE_SETTINGS table contains valid number of rows check—The valid values is 15 rows. 

  • AVAILABLE_LOCALES table contains valid number of rows check—The valid values is 22 rows.

  • Ensure that tenant configuration is correct .
  • Ensure that push notification certificates are present in the database.
  • Ensure that the FEATURE_SETTINGS and AVAILABLE_LOCALES tables contain valid number of rows.
Google Maps API check

Params for google_maps_api are present in DB check—Succeeds if Google Maps API key is specified CONFIGURATION_PARAMS table in the SmartIT_Business schema . The check fails if the value of googleMapsApiKey property is not specified.

  • Request for Maps license from Google.For more information, see Enabling a maps license.

  • Ensure that you have provided the correct BMC Digital Workplace host name and details to obtain the googleMapsApiKey.
  • Ensure that the database CONFIGURATION_PARAMS table contains googleMapsApiKey.
Single Sign-On configuration checks

The following checks verify single sign-on configuration:

  • In the TENANT table, value of SAML_AUTHENTICATION is set to true for the current tenant.
  • RSSO libs are present and properties configured—Succeeds if the BMC Remedy Single Sign-On configuration files are present and the RSSO server is available.
  • ASSO libs are present and properties configured—Succeeds if the BMC Atrium Single Sign-On configuration files are present and the ASSO server is available.
In case of failure, the checks provide an additional message to indicate missing configuration files or incorrect configuration.
  • The value of SAML_AUTHENTICATION is set to true for the current tenant.
  • The required configuration files are present in the respective directories and the properties are set correctly.
  • The BMC Remedy Single Sign-On or BMC Atrium Single Sign-On server is accessible.

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Comments