• Loading...
This documentation refers to a previously released version of BMC Atrium Discovery (other versions).

Custom Reporting

Skip to end of metadata
Go to start of metadata
Space Search

Searching TWF 7.3

Table of Contents

The Custom Reporting feature enables you to perform customization of the reports and channels on the appliance.

Configuration Files

The reporting facilities and selection of UI channels shown on each page are configured using xml configuration files which are held in the following directories:

  1. /usr/tideway/data/installed/reports/
  2. /usr/tideway/data/custom/reports/

The directories are parsed in the order given (installed before custom), and the files contained in these directories are parsed in alphabetical order, with numbers before letters. This order is important as later definitions for a named report override those loaded earlier. The standard reports are contained in /usr/tideway/data/installed/reports/00reports.xml.

The format of the xml file has changed in Tideway Foundation 7.3. Upgrades from previous version of Tideway Foundation convert from the old to new file format. If you add a file in the old format, the system will attempt to automatically convert the file format on start up. You can also use the tw_convert_reports tool to convert reports manually. This is described below.

The configuration is read when the UI process starts. Changes to the report configuration files require a UI restart. Errors in the configuration files do not prevent the Application server from starting but may cause various reports and channels to be missing.

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

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

<report> elements

The <report> element has been extended in Tideway Foundation 7.3 by merging in functionality from <extrareport> which no longer exists. A <report> element requires a name attribute giving a unique name to the report.

Tag Details
Title Provides the main page title for the report. This tag is mandatory.
<title>Hosts ordered by Host Owner</title>
Description Populates the title attribute of the HTML link. Presented as a tool tip. Also shown as a subtitle below the main page title. This tag is mandatory.
<description>Shows a list of all Discovery Hosts, ordered by their Owner</description>
Kind Kind to use in search. Multiple kinds can be specified in a comma separated list or by using the * wildcard.
<kind>Host</kind>
Flags Any flags to include in the search query. This tag takes an optional keyword attribute which, when given value False, prevents the addition of the FLAGS( prefix and ) postfix. The attribute is normally used if parameters are used control the flags.
<flags>include_destroyed</flags>
With Any with functions to evaluate in the search query.
<with>value(NODECOUNT(TRAVERSE Host:HostedSoftware:RunningSoftware:SoftwareInstance)) AS si_count</with>
Where Any conditions within the search query. This tag takes a couple of options attributes:
  • keyword which, when given value False, prevents the addition of the WHERE keyword when constructing the query. For example, TRAVERSE :::Host must not be prefixed by WHERE.
  • start which, when given value False, places the parameter conditions at the start of the query rather than the end. Normally parameter queries are added after the <where> text. However, if there is a need to perform tests before a traversal then they can be placed at the beginning.

    <where>version = ''</where>
Order-by Sort results of query by specified order.
<order-by>name</order-by>
Show List of attributes to display. This tag takes an optional keyword attribute which, when given value False, prevents the addition of the SHOW keyword.
<show>name, os</show>
Url Redirect browser when report is selected.
<url>NetworkMismatchSummaryReport</url>
Imports List of <import> each of which contains a Python module to import. These are used by the <parameters> for <convert>, <default> and <eval> described below.
<imports><import>common.timeutil</import></imports>
Parameters List of <parameter> each of which contains an interactive parameter filled in by the user. These are described in detail below.

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

Tag Details
Title Label of the parameter shown when it is rendered in a form. This tag is mandatory.
<title>Start date</title>
Type Type of control widget to use for the parameter in the form and is detailed below. This tag is mandatory.
Key References a replacement construct in the constructed query.
<key>from</key>
Where Query fragment to add to where clause of the parent element's search string. The reports system inserts the value of the parameter using string substitution with a key of value.
<where>name HAS SUBSTRING %(value)r</where>

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 drop-down list.
  • RelationshipSearchField – a popover node-selection field.
  • DateTimeField – a time field.

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

Tag Details
All If type is SelectField add an 'All' option to the select dropdown (the default). When given value False prevents the addition of the 'All' option.
<all>False</all>
Convert Function used to convert the default value and user-typed value for use in query. For example, the function could be common.timeutil.convertFromUnix. This will convert the value to UNIX form, which can then be added to the query. Referenced functions should be fully specified, and the packages and modules required should appear in <imports> elements, described above. Note that functions are referenced rather than called so do not need parentheses. The function can also be a lambda function taking one parameter.
<convert>common.timeutil.convertFromUnix</convert>
Default Expression that defines a default value for the parameter. Referenced functions should be fully specified, and the packages and modules required should appear in <imports> elements, described above.
<default>common.timeutil.convertToUnix(common.timeutil.currentTime())</default>
Escape Escape string value. By default string values are escaped. When given value False prevents the escaping.
<escape>False</escape>
Kind If type is RelationshipSearchField is used to determine which source kind when finding a list of relationships defined within taxonomy.
<kind>Host</kind>
Size If type is TextField specifies the size of the text field otherwise specifies the number of visible options in the dropdown list.
<size>2</size>
Options If type is SelectField then there are several ways to specify the selection options:
  • eval which evaluates the expression. Referenced functions should be fully specified, and the packages and modules required should appear in <imports> elements, described above. <eval>api.audit.getEvents()</eval>
  • option which contains the option text. The <option> takes an optional value attribute which is used when the option is selected. If no value attribute is present the option text is used. Multiple <option> values can be provided.
    <option value="21">FTP</option>
  • query which performs a search query the first column of which is used as selection values. <query>SEARCH Location SHOW name</query>

    Only one of the selection option forms may be specified.
Validate How to validate the parameter. Currently supports:
  • integer - value is an integer
  • number - value is a number
  • boolean - value is a boolean
  • NotEmpty - value is not empty

    If the value does not validate the form will present an error to the user.
    <validate>NotEmpty</validate>

Bringing all this together, the following element defines a parameter which appears in the UI labelled 'Type' as a dropdown 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 host optionally limiting the software instances to a particular type chosen by the user from a dropdown 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:

Tag Details
Split Indicates the column to chart. This tag takes an optional columns attribute which specifies the number of columns generated by the split. For example
<split columns="2">endtime PROCESSWITH bucket(3600, 3, 48)</split>
retrieves the endtime and puts the values into a list of buckets producing 2 columns, the time and the count. The title of the column is used as the axis title. A maximum of 2 <split> tags may be defined, the first for the x-axis, the second the y-axis.
<split>os AS 'Detailed OS'</split>
Y-axis-title Indicates the title of the y axis column. This will default to 'Count' unless the <split> provides a second column.
<y-axis-title>Hosts</y-axis-title>

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 labelled '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

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.

Tag Details
Title Channel title. This tag is mandatory.
<title>Operating Systems</title>
Description Shown when editing the channels. This tag is mandatory.
<description>Operating System Reports and Charts</description>
Kind Kind to use in search. Multiple kinds can be specified in a comma separated list or by using the * wildcard.
<kind>Host</kind>
With Any with functions to evaluate in the search query.
<with>value(NODECOUNT(TRAVERSE Host:HostedSoftware:RunningSoftware:SoftwareInstance)) AS si_count</with>
Where Any conditions within the search query.
<where>version = ''</where>
Order-by Sort results of query by specified order.
<order-by>name</order-by>
Split Indicates the column to chart. The title of the column is used as the axis title.
<split>os AS 'Detailed OS'</split>
Show List of attributes to display when click through chart.
<show>name, os</show>

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.

Tag Details
Title Channel title. This tag is mandatory.
<title>Operating Systems</title>
Description Shown when editing the channels. This tag is mandatory.
<description>Operating System Reports and Charts</description>
Kind Kind to use in search. Multiple kinds can be specified in a comma separated list or by using the * wildcard.
<kind>Host</kind>
With Any with functions to evaluate in the search query.
<with>value(NODECOUNT(TRAVERSE Host:HostedSoftware:RunningSoftware:SoftwareInstance)) AS si_count</with>
Where Any conditions within the search query.
<where>version = ''</where>
Order-by Sort results of query by specified order.
<order-by>name</order-by>
Split Indicates the column to chart. The title of the column is used as the axis title. There must be 2 <split> tags.
<split>os AS 'Detailed OS'</split>
Show List of attributes to display when click through chart.
<show>name, os</show>

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.

Tag Details
Title Channel title. This tag is mandatory.
<title>Operating Systems</title>
Description Shown when editing the channels. This tag is mandatory.
<description>Operating System Reports and Charts</description>
Image Image to show for channel.
<image>discovery</image>
Chart Chart name. The chart definition must appear before this reference. Multiple <chart> tags may be specified.
<chart>Infrastructure.Chart.OSClassificationPie</chart>
Report Report name. The report definition must appear before this reference. Multiple <report> tags may be specified.
<report>Virtualization.Reports.ContainedHosts</report>

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>

<rss-channel> elements

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

Tag Details
Title Channel title. This tag is mandatory.
<title>Operating Systems</title>
Description Shown when editing the channels. This tag is mandatory.
<description>Operating System Reports and Charts</description>
Render-description Flag if to show RSS feed description, defaults to False.
<render-description>True</render-description>
Url URL for RSS feed. This tag is mandatory.
{{<url> http://www.tideway.com/confluence/createrssfeed.action?types=page

</url>}}

The following channel shows an RSS feed for VMware.

<rss-channel name="Channel.RSS.VMware">
   <title>VMWare Feed</title>
   <description>Shows the latest info from VMware</description>
   <url>http://vmware.simplefeed.net/rss/?f=2fe7e950-01de-11de-3b40-003048605010</url>
</rss-channel>

<summary-channel> elements

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

Tag Details
Title Channel title. This tag is mandatory.
<title>Operating Systems</title>
Description Shown when editing the channels. This tag is mandatory.
<description>Operating System Reports and Charts</description>
Image Image to show for channel.
<image>discovery</image>
Kind-count Node kind for which to show count. Multiple <kind-count> entries can be specified.
<kind-count>Host</kind-count>

The following channel shows the number of BusinessApplicationInstance and SoftwareInstance 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 partition 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.

Tag Details
Title Channel title. This tag is mandatory.
<title>Operating Systems</title>
Description Shown when editing the channels. This tag is mandatory.
<description>Operating System Reports and Charts</description>
Image Image to show for channel.
<image>discovery</image>
Src Video source. This tag is mandatory.
<src>/videos/Prerelease3.swf</src>

The following channel shows an 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 Tideway Foundation 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.

Tag Details
Channel Reference a previously defined channel. There is an optional builtin attribute which must be specified if the channel is builtin. Multiple channel tags can be specified. The order in which the channels appear on a page is governed by the order of the <channel> tags.
<chart builtin="True">Discovery.Channel.Status</chart>

Built-in Channels

The following built-in channels are defined:

Built-In Channel Name Description
Discovery.Channel.Status Summary for Discovery status.
Infrastructure.Channel.Explore Summary for the Automatic Grouping.
LifecycleManagement.Channel.Status Summary for Lifecycle Management.

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.

Manual Conversion

The converter used to convert reports from the old to the new format on upgrade and system startup is also available as a standalone command line tool, tw_convert_reports. With this you can manually convert reports. The usage of this tool is

$TIDEWAY/bin/tw_convert_reports options reports_file

Where reports_file is the xml reports file to be converted.

The options are described in the Table below.

Command line option Description
--rename Rename the input file reports_file.old and save the converted file as reports_file. If there are errors, these are written to the terminal and the file is not converted.
--verbose Display errors and warning messages. If no errors are reported then the reports and charts will work as they did in the previous version. These messages are also written in the comments section of the converted file.

Example Usage (tw_convert_reports)

To convert a file called 30ListenerReports.xml:

$ cd /usr/tideway/data/custom/reports
$ ls
30ListenerReports.xml
$ tw_convert_reports 30ListenerReports.xml

Generated converted_30ListenerReports.xml (0 errors, 2 warnings)
$ ls
30ListenerReports.xml
converted_30ListenerReports.xml
$

The file is converted and saved with converted_ prepended. The original file is not changed.
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.