How to create help files for custom BMC Performance Managers

All this is documented in the Controlled Availability release of the BMC Performance Manager Software Development Kit (SDK), but I thought I’d write it up here as well, hoping it’s helpful. Contact your sales rep if you want more information about the SDK for BMC Performance Manager.

BMC Performance Manager is a product with the ability to be extended, allowing you to write your own custom monitoring tools, called Performance Managers. If you write a custom Performance Manager, you’re going to want a help system to go with it, so that your users know which parameters are monitored with your tool. And if you want your custom Performance Manager to be certified by BMC Software, a help system is required. Here’s an overview of writing that custom help system including sample files.

1. Write an HTML file for each application class and the parameters within that class, nested like this set of sample HTML files for the BMC Performance Manager for Citrix Presentation Server . For example, the farm application class contains parameters like “logged in users” and “disconnected sessions,” with each parameter documented in separate HTML files. These files contain Dreamweaver template code but should be useable with any HTML editor.
2. Place your Help content files in your Performance Manager Maven project in the following location: …/META-INF/help/browser_help/.
3. Open your application definition XML file and add these Help elements in the application definition: help-group-definition or help-group-reference, and help-item. You need unique attributes msgkey and name on both these elements. Here is an example code snippet:

4.  <application-definition name="patsdk-ri-service">
   
   <display-name>Reference Implementation Application</display-name>
   
   <description> Instances of this application-definition can be used
   
   to monitor the availability of many common network services
   
   such as HTTP, Telnet, FTP, etc.</description>
   
   <help-group-definition msgkey="riapp.intro.displayName" name="intro">
   
   <display-name>Patsdk RI Application</display-name>
   
   <help-item msgkey="riapp.intro.about.displayName" name="about">
   
   <display-name>About</display-name>
   
   <file>riapp/about.htm</file>
   
   </help-item>
   
   </help-group-definition> <help-group-definition
   
   msgkey="DRCIT-Farm-Container.desc.book"
   
   name="DRCIT-Farm-Containerbook">
   </help-group-definition>

5. Add Help-related fields to your project.properties file (located in your Maven project folder). There are a couple of commented lines that you can uncomment by deleting the # sign at the beginning of the line. Set solution.product.code equal to your PAR file name (without the .par extension), and use a sample category such as database, networking, etc.

6. solution.product.code=PRD
   
   solution.help.category=networking

7. When you build and deploy your Performance Manager, the .htm files that you created are compiled into cross-platform browser-based help. These files and the Help content are packaged in a .jar file which is then put into the .par file and deployed to the BMC Portal Help repository server. Automagically.

Sounds pretty straightforward, and we’ve done this internally for a few Performance Managers already, which is why I wanted to share some sample files with you. Let us know how it works for you.