×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

 

This documentation supports the 20.08 version of BMC Digital Workplace Basic, which is available only to BMC Helix subscribers (SaaS).
To view an earlier version, select the version from the Product Version menu.

BMC Digital Workplace Basic 20.08 Troubleshooting

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, the BMC Digital Workplace server, and a database 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.

Related topics

Identifying connectivity and configuration issues by running health checks

Troubleshooting

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

Important

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

  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.

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 DWP_HOME\DWP\diagnostic directory

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.

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 DWP_HOME\DWP\diagnostic directory

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

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-dwp.properties file

The checks succeed if following conditions are met:

  • The connect-dwp.properties file is present in the TomcatHome/external_conf directory.
  • The connect-dwp.properties file is not empty.
Ensure that the location of connect-dwp.properties file is correct and the file is readable.
SMTP checkThe check succeeds if SMTP is configured in the connect-dwp.properties file.
  • On the server defined in the connect-dwp.properties file, ensure that SMTP service is running
  • In the connect-dwp.properties file, ensure that the SMTP parameters in the file are set.

Webapp check

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

  • Ensure that the version-dwp.properties file is present at the specified location.
Logs checkThe check succeeds if the logback.xml file is present in the TomcatHome\external_conf directory. 
  • Ensure that the logback-dwp.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 log in to the business database
  • System database is reachable check—Succeeds if the diagnostic utility can log in to the system database
  • dwp.xml file contains DB configuration check—Succeeds if the dwp.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 dwp.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 the dwp.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 the CONFIGURATION_PARAMETER table in the system database contains the shared AR System server host name, port, and password.
  • Login to shared AR check—Succeeds if the diagnostic utility can 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
    • MYIT_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 dwp-metadata.log file, which is located in the DWP_HOME\DWP\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 contain 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 value is 15 rows.

  • AVAILABLE_LOCALES table contains valid number of rows check—The valid value 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 the Google Maps API key is specified in the CONFIGURATION_PARAMS table in the SmartIT_Business schema. The check fails if the value of googleMapsApiKey property is not specified.

  • Request for a Maps license from Google.

  • 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, the value of SAML_AUTHENTICATION is set to true for the current tenant.
  • RSSO libs are present and properties are configured—Succeeds if the Remedy Single Sign-On configuration files are present and the Remedy Single Sign-On 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 Remedy Single Sign-On or BMC Atrium Single Sign-On server is accessible.

Was this page helpful? Yes No Submitting... Thank you
Last modified by Olha Horbachuk on Jul 01, 2021
utilities diagnostic_checks videos errors ts_network

Comments

Log in or register to comment.

Identifying connectivity and configuration issues by running health checks
Troubleshooting data transfer issues
© Copyright 2013 - 2022 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2023 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.