Creating custom reports

You customize the reports and channels in the BMC Discovery which provides easier access to the information that you need to make decisions.

Reports are defined in an XML file that you upload to BMC Discovery through the UI.

Although channels can be created using this method, you might find doing so simpler by using the Channels page.

Naming your XML files

Naming the files is important as it specified the order in which the files are processed. This order is important as later definitions for a named report override those loaded earlier.

The directories are parsed in alphabetical order, with numbers before letters. The standard reports are contained in a file called 00reports.xml.

You cannot add context-sensitive reports to the discovery status page.

You cannot customize the Host Profile report.

Writing the custom reports files

The custom reports are defined in simple XML files, the elements of which are described in this topic.

Elements of the XML files

The root element of each reports.xml file must be <reports version="2.0">. The <reports> element can have several types of elements:

Standard reports:
- - <report>: a report. See <report> elements.
  - <chart>: a chart. See <chart> elements.
Channels:
- <chart-channel>: a simple chart channel. See <chart-channel> elements.
- <chart-multi-channel>: a chart channel with multiple values per column. See <chart-multi-channel> elements.
- <report-channel>: a channel containing a list of charts and reports. See <report-channel> elements.
- <summary-channel>: a channel containing node kind counts. See <summary-channel> elements.
- <time-series-channel>: a chart channel containing values over time. See <time-series-channel> elements.
- <video-channel>: a video channel. See <video-channel> elements.
- <web-channel>: a channel containing a web feed. See <web-channel> elements.
Page information:
- <page>: the selection of channels on one page. See <page> elements.

<report> elements

A <report> element requires a name attribute giving a unique name to the report.

<parameter> element

Interactive parameters are defined using <parameter> elements. They must have a name, representing the name of the parameter, that is unique in the report.

When the query is built from parameters all the parameters are evaluated as specified by <type>. If a parameter has a where clause it is substituted into the where clause with a key of value. All parameters without a key are then joined together using AND and inserted either at the beginning (<where start="True"> specified) or end of the where clause in the report. The complete query is then constructed. If there are any parameters with a key the completed query has those parameters inserted using string substitution with the specified key of the parameter.

The <type> tag must have a name attribute which specifies the type of the parameter. It should have one of the following values:

TextField: a text entry field.
SelectField: a list.
RelationshipSearchField: a popover node-selection field.
DateTimeField: a time field.

The tags that can be used with <type> depend upon these values.

Bringing all this together, the following element defines a parameter that appears in the UI labeled Type as a list with three specified values and no All entry. The <where> tag means that should the user choose Host then kind(#) = 'Host' will be added to the report query.

<parameter name="DQ_Report_Global_type">
   <title>Type</title>
   <type name="SelectField">
      <all>False</all>
      <options>
         <option value="Host">Host</option>
         <option value="SoftwareProductVersion">Software Product Version</option>
         <option value="BusinessApplicationInstance">Application Instance</option>
      </options>
   </type>
   <where>kind(#)='%(value)s'</where>
</parameter>

The following report will count the number of instances of software instances on the host optionally limiting the software instances to a particular type chosen by the user from a list.

<report name="Software.Report.InstanceSummary">
   <title>Software Inventory</title>
   <description>Shows summary of distribution of a piece of software</description>
   <kind>SoftwareInstance</kind>
   <show>
      type AS "_|Type|_",
      product_version AS "_|Product Version|_"
      PROCESS WITH
         countUnique(1,0)
  </show>
  <parameters>
     <parameter name="Software_Report_InstanceSummary_type">
        <title>Product type</title>
        <type name="SelectField">
           <options>
              <query>
                 SEARCH SoftwareInstance
                 ORDER BY type
                 SHOW type
                 PROCESS WITH unique()
              </query>
           </options>
        </type>
        <where>type = %(value)s</where>
     </parameter>
  </parameters>
</report>

<chart> elements

The <chart> element in fundamentally the same as the <report> element with the following changes:

the default type of chart can be specified by adding the default attribute to <chart>,
the <show> tag is used to determine the click-through columns of the chart.

Additional tags are:

For single columns the supported charts are:

pie (default)
bar
column

For two columns the supported charts are:

line (default)
column

The following chart will show a count of different OS classifications. By default a pie chart will be shown and when clicked through a summary report for the appropriate hosts. When displaying bar and column charts the y-axis will be labeled Hosts.

<chart name="Infrastructure.Chart.OSClassification" default="pie">
   <title>Host OS Classification</title>
   <description>Show count of Hosts for each OS Classification</description>
   <kind>Host</kind>
   <order-by>os_class</order-by>
   <split>os_class AS "_|OS Class|_"</split>
   <y-axis-title>_|Hosts|_</y-axis-title>
   <show>SUMMARY</show>
</chart>

<chart-channel> elements

Important

The following points must be considered when creating channels for upload through the BMC Discovery UI, or migration. Reports with channels cannot be uploaded by using the REST API.

The file must have the same name as the <report-channel> name attribute and must contain only one channel.
If you do not do so, you will see:
- Problems previewing and saving the channel
- Messages about Internal errors and only the current channel being saved
Ordering is important. For example, if you edit the 'Discovery Option' channel to add custom reports, these custom reports must appear in the custom reports list BEFORE the newly created Discovery.Channel.DiscoveryReportChannel, otherwise the custom 'Discovery Option' channel will not be able to find the custom reports.
- This will work as '0' (zero) comes before 'D'.

- This will not work as 'D' comes before 'r'.
If you remove a custom channel that is in use, the UI displays a banner with an error.
If you delete custom report(s) used in a custom channel, then that custom channel cannot be loaded, and:
- An error is displayed in the channel if it is being used.
- The channel is not shown in the channels list.

The <chart-channel> element requires a name attribute giving a unique name to the chart channel. An optional default attribute gives the initial chart type.

The following channel shows a pie chart of software product categories:

<chart-channel name="Channel.SWCategory" default="pie">
   <title>Software Products By Category</title>
   <description>Shows a list of the Software by Category</description>
   <split>explode(#Element:Maintainer:Pattern:Pattern.categories) AS 'Software Category'</split>
   <kind>SoftwareInstance</kind>
   <show>
      summary,
      #Element:Maintainer:Pattern:Pattern.categories AS 'Software Category'
   </show>
</chart-channel>

<chart-multi-channel> elements

The <chart-multi-channel> element requires a name attribute giving a unique name to the chart multi-channel. An optional default attribute gives the initial chart type; default="column" displays the legend, default="column_nolegend" hides the legend.

The following channel shows a column chart of database versions with a column for each product type. Each column contains a list of found versions.

<chart-multi-channel name="Channel.SWDBVersion" default="column_nolegend">
   <title>Database versions</title>
   <description>Number and version of all the Database instances</description>
   <split>type</split>
   <split>(product_version or 'Unknown')</split>
   <kind>Pattern</kind>
   <where>
      'Relational Database Management Systems' in categories
      TRAVERSE Pattern:Maintainer:Element:SoftwareInstance
   </where>
   <show>SUMMARY</show>
</chart-multi-channel>

<report-channel> elements

The <report-channel> element requires a name attribute giving a unique name to the report channel.

The following channel contains a link to a report and chart.

<report-channel name="Infrastructure.Channel.NetworkPolicy">
   <title>Network Policies</title>
   <description>Shows a list of Network Infrastructure Reports</description>
   <report>Infrastructure.Report.NetworkMismatchSummary</report>
   <chart>Infrastructure.Chart.IPAddressDistribution</chart>
</report-channel>

<summary-channel> elements

The <summary-channel> element requires a name attribute giving a unique name to the summary channel.

The following channel shows the number of Business Application Instance and Software Instance nodes.

<summary-channel name="Applications.Channel.Summary">
   <title>Application Summary</title>
   <description>_|Shows a summary of Applications|_</description>
   <image>applications</image>
   <kind-count>BusinessApplicationInstance</kind-count>
   <kind-count>SoftwareInstance</kind-count>
</summary-channel>

<time-series-channel> elements

The <time-series-channel> element requires a name attribute giving a unique name to the time series channel.

This is identical to <chart-channel> with two exceptions:

It performs a historical search and partitions the result into a number of buckets. By default, this is 5 but can be overridden by specifying the time-series attribute on the <time-series-channel> element.
<split> is optional and if not present the chart will be based on the number of the specified node kind rather than the value of the specified attribute.

The following channel shows the number of Hosts for each UNIX OS over time.

<time-series-channel name="Channel.OSUNIX" time-series="7" default="line">
   <title>UNIX Operating Systems</title>
   <description>Shows a count of Hosts for each UNIX OS</description>
   <split>os_type as "OS Version"</split>
   <kind>Host</kind>
   <where>os_class = "UNIX"</where>
   <order-by>os_type</order-by>
   <show>SUMMARY</show>
</time-series-channel>

<video-channel> elements

The <video-channel> element requires a name attribute giving a unique name to the video channel.

The following channel shows a video feed for creating host profiles.

<video-channel name="Channel.Video.HostProfiles">
   <title>Feature Tutorial: Host Profiles</title>
   <description>Video Tutorial that explains the Host Profiles feature</description>
   <src>/videos/HostProfiles.swf</src>
</video-channel>

<web-channel> elements

The <web-channel> element requires a name attribute giving a unique name to the web channel.

Tag	Details
Title	Channel title. This tag is mandatory. <title>Google</title>
Description	Shown when editing the channels. This tag is mandatory. <description>Shows the Google search engine.</description>
URL	URL for the web feed. This tag is mandatory. <url>http://www.google.com</url>

The following channel shows a web feed for the BMC Discovery Community forum.

<web-channel name="Channel.Web.Community">
   <title> Tideway Community Update</title>
   <description>Shows the Tideway Community update.</description>
   <url>http://www.tideway.com/widgets/foundation-forum/</url>
</web-channel>

<page> elements

The <page> element requires a name attribute giving a unique name to the page.

Built-in channels

The following built-in channels are defined:

Built-in page names

The following are the identifiers for pages with configurable content:

Built-in Page Name	Description
ApplicationHome	The front page of the applications module.
DiscoveryReports	Reports in the discovery module.
Home	The appliance home page.
InfrastructureHome	The front page of the infrastructure module.
Reports	The front page of the reports module.