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

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

Upgrades from previous versions remove /usr/tideway/data/default/additional_links.xml and add the following new file:
/usr/tideway/data/installed/reports/00additional_links.xml

If you are upgrading, you must copy /usr/tideway/data/customer/additional_links.xml to /usr/tideway/data/custom/reports/00additional_links.xml and manually convert the file to the new format which is described on this page.

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.

  1. 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 <).
  2. The XML files are read when the Application server starts. Usually you would restart the whole tideway service.
  3. Parse errors in the XML do not prevent the Application server starting but might cause one or all external link definitions to be ignored.
  4. 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.
  5. 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.
  6. 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.
  7. 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.

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.

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

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.

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.

      <link name="Link.Host.Ticket">
        <title>View trouble ticket for %(hostname)s</title>
        <description>Browse trouble ticket system for this host.</description>
        <kind>Host</kind>
        <image>kind/gif/Location_16.gif</image>
        <url>http://tickets.tideway.com/tickets/%(ticketNum)s.cgi</url>
      </link>

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>

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>

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>

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>

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

  </reports>
Was this page helpful? Yes No Submitting... Thank you

Comments