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 base reports are contained in /usr/tideway/data/installed/reports/00reports.xml.

This data layout has changed in Tideway Foundation 7.2. Upgrades from previous versions of Tideway Foundation move the /usr/tideway/data/customer/reports.xml configuration file to /usr/tideway/data/custom/reports/00reports.xml.

The configuration is read when the UI process starts. Changes to the report configuration files require a UI restart. If either configuration file contains errors, the appserver service is unlikely to start.

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

The root element of each reports.xml file must be <reports> with no attributes. The <reports> element can have the following optional child elements:

• <report> – the configuration for a report. See <report> elements.
• <extrareport> – the configuration for an extra report. See <extrareport> elements.
• <chart> – the configuration for a chart. See <chart> elements.
• <report-channel> – the configuration for a simple channel. See <report-channel> elements.
• <page> – the selection of channels on one page. See <page> elements.

<report> elements

The <report> element requires the following attributes:

• name – a unique name for the report.
• title – the report title.
• description – a free text description of the report.
• kinds – the node kinds to use in the search.

Multiple kinds can be specified in a comma separated list or by using the * wildcard. The immediate child elements of the <report> element must not have attributes. The <report> element can have the following optional child elements:

• <where> – the where clause of the search string.
• <order> – the order by clause of the search string.
• <show> – the show clause of the search string.
• <parameters> – has zero or more <parameter> child elements.

Interactive parameters are defined using <parameter> elements. These have the following attributes:

• name – a name for the parameter. This must be unique in the report.
• title – a label for the parameter shown when it is rendered in a form.
• type – the type of control widget to use for the parameter in the form.

Report parameters add fragments to the where clause of the search string. The fragment is defined by the content of a <where> child element of the <parameter> element. The reports system inserts the value of the parameter using string substitution with a key of value.

For example, if the where fragment for a parameter is name HAS SUBSTRING '%(value)s' and you enter a value of foo then name HAS SUBSTRING 'foo' is added to the where clause of the search string.
The type parameter can have one of the following values:

• TextField – a text entry field.
• SelectField – a drop-down list.
• RelationshipSearchField – a popover node-selection field.

If the type attribute is SelectField, the <parameter> element requires an <options> child element containing one or more <option> elements. Each <option> element contains the text used to label that option in a drop-down control and an optional value attribute that supplies the value to be used in the where clause. If the value attribute is not supplied the text content is used.

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

Alternatively, SelectField parameter elements can have a <query> child element surrounding a search query string that, when executed, provides the set of options for the parameter.

<parameter
   name="Library_report_SPTByName_type"
   title="Type"
   type="SelectField">
<where>
#ModelNode:OntologyLink:OntologyNode:OntoSoftwareProductType.#ElementInCategory:ElementCategory:Category:OntoSoftwareCategory.name='%(value)s'
</where>
<query>
SEARCH OntoSoftwareCategory WHERE name IS DEFINED ORDER BY name SHOW name
</query>
</parameter>

SelectField parameters automatically have an All choice added to the top of the list.
If the type attribute is RelationshipSearchField, the <parameter> element has a <kind> child element with a value attribute that specifies a node kind to search for and a <size> child element which limits the number of values returned.

<extrareport> elements

The <extrareport> elements are similar in function to report elements but enable you to create more sophisticated reports. Each <extrareport> element has the following attributes:

• name – specifies a unique name for the report.
• title – specifies a title to be shown with the report's results.
• description – a description for the report.
• query – specifies a template for constructing the query from.
  The query attribute defines the search string that is executed on the search service, with special constructs which are replaced according to the tags nested inside the <extrareport> element.
  Replacements in the query string begin with a percent sign %, have a name in brackets, and finish with an s. Examples of valid replacements are:
• %(name)s
• %(from)s
  The format and legal values for the name of the replacement follow the rules of Python's string formatting.
  The names of replacements refer to <parameter> elements defined as descendents of the <extrareport> element, with the exception of the following reserved names:
• %(cond)s – replaced by the conditions specified by descendent <parameter> elements, concatenated with AND between each condition, except for those parameters that have a key attribute.
• %(WHERE)s – replaced by the literal text WHERE in the query if there are any parameters with values. That is, if %(cond)s produces output, %(WHERE)s produces WHERE. Otherwise it is replaced with an empty string.
• %(AND)s – replaced by the literal text AND in the query if there are any parameters with values. That is, if %(cond)s produces output, %(AND)s produces AND. Otherwise it is replaced with an empty string.
  The <extrareport> element has the following child elements:
• <parameters> – with zero or more <parameter> child elements
• <imports> – with zero or more <import> child elements
• <defaults> – with zero or more <default> child elements
  No attributes are expected on the immediate children of <extrareport> elements. The <parameters> element is required. The <imports> and <defaults> elements are optional. They are described in the following sections.

<parameter> element

Extra reports' interactive parameters are defined using <parameter> elements. These have the following attributes:

• name – defines a name for the parameter. This must be unique in the report
• title – defines a title for the parameter that is shown as the label for the parameter when it is rendered in a form.
• type – defines the type of control widget to use for the parameter in the form.
• key – an optional parameter that references a replacement construct in the query attribute of the <extrareport> element.

The result of this parameter is substituted into the query where its replacement construct appears. If the key parameter is not present, the result is substituted, with other parameters with no key attribute, where the %(cond)s construct appears.

• optionQuery – an optional parameter that specifies a search string to use to find the values selectable for this parameter. Valid with a parameter type of SelectField.
• all – an optional Boolean parameter that specifies whether a select all option is provided in the results (True) or not (False).
• default – an optional Python expression which specifies the default value of the parameter. This is filled in when the form is first rendered.

The context in which it is evaluated makes certain functions and constants available, including the contents of common.timeutil, which includes: currentTime(), convertToUnix(), and ONE_DAY. It is valid for parameter types that are not SelectField. The Python function eval should be able to evaluate the expression.
The <parameter> element has the following child elements:

• <template> – the <template> element has one attribute, type, whose value must either be function or string.
  If the type is function, then the characters inside the <template> element reference a Python function. The function is called with the value of the field in the UI and translates this value into the form that goes into the query. For example, the function could be common.timeutil.convertFromUnix. When applied to the value of the field in the UI, 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 <import> elements, described below.
  Note that functions are referenced rather than called so do not need parentheses.

The function can also be a lambda function taking one parameter, for example lambda n: "name HAS SUBSTRING '%s'" % n, in this case, the value is substituted into the relevant place in the string.

If the type is string, then the characters inside the <template> element should be a string that contains a single %s. This string is applied to the value of the field using the % operator. This is a shorthand for the previous example that used a lambda.

• <options> – the <options> element is an optional element having zero or more <option> elements, which are the same as the <option> elements described for normal report parameters.
• <validators> – the <validators> element is an optional element having a single <validator> element. The <validator> element can only take one value: NotEmpty. If this construction is used, the report will not be run unless the user enters a non-null value for that parameter. For example, to ensure a report is not run unless a user enters a non-null value for the RequiredInformation parameter, use the following construction:

  <parameter name="RequiredInformation">
     <validators>
        <validator>NotEmpty</validator>
     </validators>

<import> element

The <import> element defines an import needed to reference a function used in the <template> child element of the <parameter> element. The package and/or module is specified between the opening and closing tag of the element. All packages and modules in Tideway Foundation are available, along with the standard libraries.

<default> element

The <default> element defines a default value that is global to the <extrareport>. This appears as a condition in the query if a parameter does not provide a value. The attribute key is used to match against the key attribute in the <parameter> elements. The characters between opening and closing tag define the string value.

<chart> elements

The <chart> element requires the following attributes:

• name – a unique name for the chart.
• report – the report used as the data source for the chart.
• type – the chart type.
• title – the chart title.

Adding Drill-Down to Custom Charts

When viewing a chart, you can drill-down into any part of that chart to see the details for that particular section.
To add drill-down to a custom chart, you can add an attribute called drilldown to the chart element that defines the chart in reports.xml. The attribute specifies the columns shown in the drill-down table and has the same format as the SHOW clause in a search query.
For example, below is the definition of the Windows Version [Edition] Distribution pie chart before the drilldown attribute is added:

  <chart name="DataCentreStand.Reports.WindowsVersionEditionPie"
         report="DataCentreStand.Reports.WindowsVersionEditionChart"
         type="pie"
         title="Windows Version [Edition] Distribution">
    <x-axis>_|Windows Version [Edition]|_</x-axis>
    <y-axis>_|Hosts|_</y-axis>
  </chart>

Below, the drilldown element has been added that shows the SUMMARY for the nodes in the set:

  <chart name="DataCentreStand.Reports.WindowsVersionEditionPie"
         report="DataCentreStand.Reports.WindowsVersionEditionChart"
         type="pie"
         title="Windows Version [Edition] Distribution"
         drilldown="SUMMARY">
    <x-axis>_|Windows Version [Edition]|_</x-axis>
    <y-axis>_|Hosts|_</y-axis>
  </chart>

For more information see Using Chart Reports.

The <chart> element has the following child elements:

• <x-axis> – the data source column for the x-axis data.
• <y-axis> – the data source column for the y-axis data.
  The type attribute can have any one of the following values: pie, bar (horizontal bars), column (vertical columns), or line. For every chart type, the x-axis data specify the labels for each slice, bar, column, or point drawn on the chart. The y-axis data specify the size of the slice, bar, column, or point that relates to the associated label.

<chart
   name="Infrastructure.Chart.HostOSType"
   report="Infrastructure.Report.HostOSTypeChart"
   type="column"
   title="Hosts by OS Type Chart">
<x-axis>_|OS|_</x-axis>
<y-axis>_|Hosts|_</y-axis>
</chart>

<report-channel> elements

The <report-channel> element requires the following attributes:

• name – a unique name for the channel.
• title – the channel title.
• description – the channel description.
  Each <report-channel> element can have a mixture of <report> and <chart> child elements. Each <report> child element has a name attribute that identifies the report to be included in the channel. Each <chart> element has a name attribute that identifies by name the chart to be included in the channel.

<page> elements

The <page> element requires the following attribute:

• name – a unique name for the page.
  The <page> element has the following child element:
• <channel> – the report channel that is shown on the page. The <page> element can have one or more <channel> child elements.
  The <channel> elements have a name attribute that identifies a channel that is shown on the page. A page can have a mixture of built-in channels and user defined report channels.
  The order in which channels appear on pages is governed by the order attribute of the channel. The channel order attribute is not currently configurable.

Built-in Channels

The following built-in channels are defined:

In addition, there is a built-in channel called Reports.Channel.CustomReports that links to all the reports defined in the customer reports.xml file. This channel is only intended for development and testing purposes.

Built-in Page Names

The following are the identifiers for pages with configurable content: