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

Configuring Additional Links

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

Searching TWF 7.3

Table of Contents

The external links feature provides links from objects modelled in Tideway Foundation, 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 Tideway Foundation UI, you may see a link to that host in a change management application such as Remedy. See Dynamic Toolbox.
Search queries are used to construct the links. See Search and Reporting Service for more information.

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 has changed in Tideway Foundation 7.3 to become 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 of Tideway Foundation 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.

Notes:
  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 may 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.

Link Tags

The link tag specifies the type of link that is being created. These may 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. Note that 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 below 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 within <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 within 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 within 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 may 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 below:
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.

      <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>
Report Links

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

The following examples retrieves a list of hosts with the same operating system 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>
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.