Custom reporting
The custom reporting feature enables you to perform customization of the reports and channels on the appliance. Channels may be created more simply using the Channels page.
The following topics are covered in this section:
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:
/usr/tideway/data/installed/reports_content/
/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_content/00reports.xml
.
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 might cause various reports and channels to be missing.
To get the UI to update with your custom reports, do the following:
- Log out of the UI
- From the command-line, as the
tideway
user, run this command:tw_service_control --restart appserver
- Log back in to the UI.
On a cluster, you must update the 00reports.xml
file on the coordinator and restart the cluster. See Shutting down and restarting clusters for more information.
You cannot add context sensitive reports to the discovery status page.
You cannot customize the Host Profile report.
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.<rss-channel>
: a rss feed channel. See <rss-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.
Tag | Details |
---|---|
Title | Provides the main page title for the report. This tag is mandatory. |
Description | Populates the title attribute of the HTML link. Presented as a tool tip. Also shown as a subtitle in the following example the main page title. This tag is mandatory. |
Kind | Kind to use in search. Multiple kinds can be specified in a comma separated list or by using the |
Flags | Any flags to include in the search query. This tag takes an optional |
With | Any with functions to evaluate in the search query. |
Where | Any conditions in the search query. This tag takes a couple of options attributes:
|
Order-by | Sort results of query by specified order. |
Show | List of attributes to display. This tag takes an optional |
Url | Redirect browser when report is selected. |
Imports | List of |
Parameters | List of |
<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. |
Type | Type of control widget to use for the parameter in the form and is detailed in the following section. This tag is mandatory. |
Key | References a replacement construct in the constructed query. |
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 |
<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.
Tag | Details |
---|---|
All | If type is SelectField add an All option to the select list (the default). When given value False prevents the addition of the 'All' option. |
Convert | Function used to convert the default value and user-typed value for use in query. For example, the function could be |
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 |
Escape | Escape string value. By default string values are escaped. When given value False prevents the escaping. |
Kind | If type is RelationshipSearchField is used to determine which source kind when finding a list of relationships defined in taxonomy. |
Size | If type is TextField specifies the size of the text field otherwise specifies the number of visible options in the list. |
Options | If type is SelectField then there are several ways to specify the selection options:
|
Validate | How to validate the parameter. Currently supports:
|
<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 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, |
Y-axis-title | Indicates the title of the y axis column. This will default to Count unless the |
- 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. |
Description | Shown when editing the channels. This tag is mandatory. |
Kind | Kind to use in search. Multiple kinds can be specified in a comma separated list or by using the |
With | Any with functions to evaluate in the search query. |
Where | Any conditions in the search query. |
Order-by | Sort results of query by specified order. |
Split | Indicates the column to chart. The title of the column is used as the axis title. |
Show | List of attributes to display when click through chart. |
<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.
Tag | Details |
---|---|
Title | Channel title. This tag is mandatory. |
Description | Shown when editing the channels. This tag is mandatory. |
Kind | Kind to use in search. Multiple kinds can be specified in a comma separated list or by using the |
With | Any with functions to evaluate in the search query. |
Where | Any conditions in the search query. |
Order-by | Sort results of query by specified order. |
Split | Indicates the column to chart. The title of the column is used as the axis title. There must be 2 <split> tags. |
Show | List of attributes to display when click through chart. |
<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. |
Description | Shown when editing the channels. This tag is mandatory. |
Image | Image to show for channel. |
Chart | Chart name. The chart definition must appear before this reference. Multiple |
Report | Report name. The report definition must appear before this reference. Multiple |
<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. |
Description | Shown when editing the channels. This tag is mandatory. |
Render-description | Flag if to show RSS feed description, defaults to False. |
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. |
Description | Shown when editing the channels. This tag is mandatory. |
Image | Image to show for channel. |
Kind-count | Node kind for which to show count. Multiple |
<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. |
Description | Shown when editing the channels. This tag is mandatory. |
Image | Image to show for channel. |
Src | Video source. This tag is mandatory. |
<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. |
Description | Shown when editing the channels. This tag is mandatory. |
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.
Tag | Details |
---|---|
Channel | Reference a previously defined channel. There is an optional |
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. |
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. |
Comments
Log in or register to comment.