Configuring additional links

The external links feature provides links from objects modelled in BMC Discovery, to other web-based systems where additional information is stored. It is also used to create links to reports or charts specified for individual nodes or sets of nodes (result sets).

For example, if you are viewing a host in the BMC Discovery UI, you might see a link to that host in a change management application such as Remedy. For more information, see Dynamic Toolbox.

Search queries are used to construct the links. For more information, see Using-the-Search-and-Reporting-service.

The following link types are provided:

Links to external systems
Report for individual nodes
Chart for individual nodes
Report for result sets
Chart for result sets

Configuration files

Additional link configuration is a form of Custom-reporting. The xml configuration files 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 link override those loaded earlier. The standard additional links are contained in /usr/tideway/data/installed/reports_content/00additional_links.xml.

Links configured in the installed subdirectory are displayed beneath the default links, those from the custom subdirectory follow them. However, if a custom link overrides an installed link it will appear in place of the installed link.

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.

Notes

The link must be specified in valid XML. The XML equivalents of certain characters must be used (for example, &amp instead of &, &gt instead of >, and &lt instead of <).
The XML files are read when the Application server starts. Usually you would restart the whole tideway service.
Parse errors in the XML do not prevent the Application server starting but might cause one or all external link definitions to be ignored.
Failure to return a value for a requested attribute will be caught, resulting in the link being discarded for this particular node, on this request. For future requests an attempt to build the link will be made again.
You can substitute any attribute in a tag. Use %(attribute_name)s to do this. If the attribute contains a list value there will also be a string representation containing a comma separated list of values in %(comma_separated_attribute_name)s.
The following keys are provided:
- id: the node ID as set in the URL, for example nodeID=%(id)s
- kind: the node kind.
- uiModule: the UI module that normally handles display of the node kind.
- urlPrefix: the URL prefix of the appserver. This is usually ui.
In addition <link> with <attribute> entries contain:
- translated: the locale translated attribute name.
- otherNodeID: if the attribute represents a link then the node ID of the related node.

Link tags

The link tag specifies the type of link that is being created. These can be one of the following:

Normal Link — specified with a <link> tag.
Report Link — specified with a <node-report> tag.
A report that is run against a single node and the link should be visible when viewing a node of the correct node kind.
Chart Link — specified with a <node-chart> tag.
A chart that is run against a single node. The link should be visible when viewing a node of the correct node kind.
Set Report Link — specified with a <refine-report> tag.
A report that is run against a nodeset and the link should be visible when viewing a set of nodes of the correct node kind.
Set Chart Link — specified with a <refine-chart> tag.
A chart that is run against a nodeset and the link should be visible when viewing a set of nodes of the correct node kind.

Each tag must specify a name using the name attribute. Each link tag is in a distinct namespace.

Tags available

The following xml tags are available in all form of links:

Tag	Details
Title	Provides the main page title for the link. This tag is mandatory. <title>View trouble ticket for %(hostname)s</title>
Description	Populates the title attribute of the HTML link. Presented as a tool tip. Also shown as a subtitle in the following section the main page title. This tag is mandatory. <description>Shows the distribution of OS type on all hosts</description>
Kind	Link will be shown against this node kind. This tag is mandatory. <kind>Host</kind>
Image	Specifies an image to display. The image should already exist on the appliance as the specification is from the appliance image root ({{ http://appliance/styles/default/images/image_name}}). This tag is mandatory. <image>icon.gif</image>
Permissions	Specifies a list of permissions that the user must possess in order to display the link. <permissions> contains a list of <permission> entries, one per required permission. <permissions><permission>PERM_REPORTS_WRITE<permission><permissions>

The following xml tags are available in <link>:

Tag	Details
URL	The URL that the link points to. This tag is mandatory. <url>http://tickets.tideway.com</url>
Attribute	Displays a link in the UI next to the attribute if the attribute is not displayed, or not present on the node, then the link is not displayed. <attribute>hostname</attribute> Relationships can be specified by concatenating role, relationship, role and destination node kind with _. <attribute>Previous_EndpointIdentity_Next_Host</attribute>
Target	Populates the HTML anchor for the link. Points to the named window or frame that the results of this query will be displayed in. Frequently this will be _new so that the link will open in a new window. <target>_new</target>

The following xml tags are available in the remaining link types:

Tag	Details
Lookup	Supported in <node-chart> and <node-report>. Indicates if the query is relative to the node. Defaults to true which will generate a search of the form LOOKUP '%(id)s'. If you need a general search then use this tag to override the behaviour. <lookup>False</lookup>
Flags	Any flags to include in the search query. <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 in the search query. This tag takes an optional keyword attribute 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. <where>version = ''</where>
Order-by	Sort results of query by specified order. <order-by>name</order-by>
Show	List of attributes to display. For <node-chart> and <refine-chart> this represents the list of attributes shown when clicking through the chart. <show>SUMMARY</show>
Split	Supported in <node-chart> and <refine-chart>. 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 producting 2 columns, the time and the count. The title of the column is used as the axis title. A maximum of 2 <split> tags can be defined, the first for the x-axis, the second the y-axis. <split>os AS 'Detailed OS'</split>
Y-axis-title	Supported in <node-chart> and <refine-chart>. 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>

The default type of chart can be specified by adding the default attribute to <node-chart> or <refine-chart>. Supported charts depend upon the number of columns specified by <split>. For single columns the supported charts are:

pie (default)
bar
column

For two columns the supported charts are:

line (default)
column

Example 00additional_links.xml file

An example XML file is broken down and its constituent parts are described in the following section:
All files start with an XML declaration and an <reports> tag.

<?xml version="1.0"?>
<reports version="2.0">

The reports version must be 2.0.

External links

Each external link is defined under a <link> tag.

The following example shows a label populated with the text View trouble ticket for hostname, Where hostname is the name of the current host.
The URL in the example is to a trouble-ticketing system with a web interface. This assumes that there is a host attribute called ticketNum which contains the trouble ticket number.

Report links

Each report link is defined under a <node-report> tag.

The following examples retrieves a list of hosts with the same OS type as the currently viewed host.

      <node-report name="Node.Report.Host.SameOS">
        <title>Hosts with the same OS type</title>
        <description>List of hosts with the same OS type</description>
        <kind>Host</kind>
        <image>system/gif/report_16.gif</image>
        <lookup>False</lookup>
        <where>os_type = %(os_type)r</where>
      </node-report>

Chart links

Each chart link is defined under a <node-chart> tag.

A chart showing access methods for this host node.

      <node-chart name="Node.Chart.Host.AccessMethod" default="column">
        <title>Host Login Summary Chart</title>
        <description>Host Login Methods on a column chart</description>
        <kind>Host</kind>
        <image>system/gif/column_chart_16.gif</image>
        <where keyword="False">TRAVERSE :::DeviceInfo</where>
        <split>last_access_method as '_|Method|_' </split>
        <show>SUMMARY</show>
      </node-chart>

SetReport links

Each set report link is defined under a <refine-report> tag.

Show the number of hosts per software package on which the currently viewed set of packages are installed.

      <refine-report name="Refine.Report.Host.Density">
        <title>Package Host Density</title>
        <description>How many Hosts are these Packages installed on</description>
        <kind>Host</kind>
        <image>system/gif/report_16.gif</image>
        <show>
            name,
            version,
            NODECOUNT(TRAVERSE InstalledSoftware:HostedSoftware:Host:Host)
              AS '_|Number of Hosts|_'
        </show>
      </refine-report>

SetChart links

Each set chart link is defined under a <refine-chart> tag.

Summarise the currently viewed set of Software Instance nodes in a pie chart segmented by type.

      <refine-chart name="Refine.Chart.Host.SISummary" default="pie">
        <title>Software Instance Type Summary</title>
        <description>Show a Summary of the Software Instance Types</description>
        <kind>Host</kind>
        <image>system/gif/pie_chart_16.gif</image>
        <order-by>type</order-by>
        <split>type</split>
        <show>SUMMARY</show>
      </refine-chart>

Completion

Finally, the XML file is completed with the closing tag.

</reports>