Functions for topology report expressions

You can use these functions when you create expressions for BIRT data sets. Press Ctrl+Space in the Expression field to see a list of functions and predefined XPath expressions.

Expressions in rows and columns

A BIRT data set includes several expressions that specify which data to retrieve. Each data set has a single row query, an expression that specifies the data for the rows of the data set. For example, if you wanted to show a table that lists each of the units in the topology, with information about the units in the columns, you can create a row query with the following expression:

DeployCoreRoot/topology/_schema-element_unit

After you have specified the expression for the row query, you specify one or more expressions for the column definitions. These expressions provide information about the topology elements that are identified by the row query. For example, if your row query returned units, you can specify column definitions to retrieve the units' attributes, such as @description to retrieve its description or @initInstallState to retrieve its initial install state.

With functions, you can go into more detail about the information that you want to retrieve, either in the row query or in the column definitions. Some functions are appropriate for row queries, and other functions are appropriate for column definitions.

Functions in row queries

With functions, you can specify complex data in the row query. For example, you can use the getHosted function in a row query to create a data set that includes only the units that a specified unit hosts. To use this function, import the topology model data source, as described in Creating custom report templates, create a new data set from this data source with a query parameter such as myUnit, and then use that parameter and the getHosted function in the query for the data set. You must also set the Type field for the row mapping to a compatible return type for the query; in the case of a query that returns units, you can specify core:Unit.

getHosted(resolveURI($myUnit))

Like most of the functions, the getHosted function accepts an XPath location as a parameter, in this case, the location of the host unit. Commonly used XPath expressions are listed in Predefined XPath expressions for topology reports.

However, most functions return the URI of the topology element rather than the XPath location. The URI includes the location of the topology file in your workspace and the ID of the unit within the topology, for example:

platform:/resource/MyProject/topologies/MyNamespace/MyTopology.topology#/Unit_1

URIs must be converted into XPath locations in order to be passed to the functions. You can use the resolveURI function to convert a URI into an XPath location, as in this example:

resolveURI('platform:/resource/MyProject/topologies/MyNamespace/MyTopology.topology#/Unit_1')

In most cases, you do not need to specify the XPath location or URI as a string literal; most of the data sources that are included with the report templates include a URI field that provides the XPath location of the unit or other topology element. You can pass this URI parameter to a function or to another data set in order to locate the unit or other topology element.

The functions that are intended for use in row queries are listed in Functions for rows in reports.

Functions in column definitions

Functions can return more complex information about each of the topology elements that are returned by the row query. Unlike row query functions, which return a set of data, column definition functions return a single piece of data, usually a primitive value, such as a string, integer, or Boolean.

For example, the getCaption function returns a string. If you create a data set that returns a series of units, using a data set query such as DeployCoreRoot/topology/_schema-element_unit, you can use the getCaption function to create a column in the data set that shows the caption for each unit.

Like row query functions, column definition functions also take XPath locations as parameters. However, the XPath locations are relative to the topology elements that are returned by the row query. For example, if the row query returns units, the XPath location of those units for use in column definitions is a period. As in the prior example, if the row query returns a series of units, you can create a column that contains the caption of each of those units with the expression getCaption(., 'true', 'true').

UML and EMF functions for use with topologies

The following functions are provided for use with the Eclipse Modeling Framework (EMF) and UML data sets, but they are also useful in topology data sets. These functions can be used in row queries and in column definitions.

resolveURI(inputURI)

Returns the XPath location of the specified topology element.

inputURI: The URI of a topology element.

Return type: string

getURI(inputElement)

Returns the URI of the specified topology element.

inputElement: The XPath location of a topology element.

Return type: string

getXMIType(inputElement)

Returns the type of the specified topology element.

inputElement: The XPath location of a topology element.

Return type: string

You can also use the other functions that are listed in Additional XPath functions for EMF and UML data sets.

Feedback