Custom report expressions

To define a custom data set, you might need to write an expression that identifies the data to include in the report. The deployment planning tools include a group of functions that you can use to help specify the data.

You can use custom expressions in two places in a custom data set. Typically, custom expressions define the query for the data set, specifying the data that goes into the rows of the report. For example, the following figure shows the custom report expression DeployCoreRoot/topology/unit, which as is explained later in this topic, returns each unit in a topology:

A custom report expression on the Row Mapping page of the New EMF Data Set window

You can also use a custom expression in a column definition for the data set. In this way, you can specify the information that you want to retrieve about each row in the data set. Building on the following example, which retrieves each unit in a topology, you can use a custom expression to retrieve information about each unit. For example, the expression isPublicEditableUnit(.) returns true if the current unit, which is represented by a period, is public-editable.

A custom report expression on the Column Mapping page of the New EMF Data Set window

To see examples of expressions, you can view the expressions of the predefined data sets by right-clicking them in the Data Explorer view, clicking Edit, and then clicking Row Mapping.

Sample XPath expressions

XPath expressions identify the data that you want to use in a data set, in this case, one or more topologies or topology elements. For example, a topology is found as a child of the root DeployCoreRoot element, so an XPath expression that returns a topology looks like this:

DeployCoreRoot/topology

Similarly, units are found as children of the topology, so an XPath expression that returns each unit in the topology looks like this:

DeployCoreRoot/topology/unit

You can use the flexibility of XPath expressions and functions to retrieve more complex data. For example, the following expression returns every constraint in the topology, regardless of whether that constraint is on a unit, requirement, capability, link, or topology:

instanceOf(//*, "core:Constraint")

By contrast, the following expression retrieves only the constraints that are on a unit (excluding constraints on other topology elements, such as capabilities and requirements):

DeployCoreRoot/topology/unit/constraint

XPath expressions with functions

The deployment planning tools include functions that can help you retrieve the data you want. For example, the getRealizes(inputXPath) function returns only the units that have realization links to the unit that you pass to the function. If you pass every unit in the topology to this function, the function returns every unit that realizes another unit:

getRealizes(DeployCoreRoot/topology/unit)

If you pass a specific unit to the data set, either through a parameter or through a specific XPath expression, the function returns only the units that have realization links to that unit.

getRealizes(resolveURI($unitParam))

For a list of the available functions, see Functions for topology report expressions.

XPath expressions with parameters

You can insert parameters that you added on the Query Parameters page by prepending a dollar sign to the parameter name. For example, if you created a variable named currentUnit, you could set that variable to a particular unit in the report and then use that variable to retrieve only the capabilities on that unit. That expression might look like this:

resolveURI($currentUnit)/capability

This expression uses the resolveURI function to retrieve an element from the topology based on its specific location within the topology model.

Return types for report expressions

When creating report expressions, you must be aware of the type of topology element that the expression returns, such as units, capabilities, or constraints. For example, the expression DeployCoreRoot/topology/unit returns units. If you use this expression in the query for a data set, you must indicate that the query returns units in the Type field of the Row Mapping page of the New EMF Data Set window. To specify the return type of the expression, select the corresponding type in the Browse section and then click the right arrow button next to the Type field.

Selecting the expression return type on the Column Mapping page of the New EMF Data Set window

For example, the expression DeployCoreRoot/topology/unit calls for the return type of core:Unit. For expressions that return capabilities, set the return type to core:Capability, and for expressions that return constraints, set the return type to core:Constraint.

Most topology elements are defined in the core topology model; therefore, to select the return type for the expression, you first select the core topology model schema from the list in the Browse section. The URI of the core topology schema is as follows:

http://www.ibm.com/ccl/soa/deploy/core/1.0.0/

Selecting the URI in the New EMF Data Set window

However, some topology elements are reused from the definitions in the Graphical Modeling Framework (GMF), so these types are found in the GMF schema. For example, if you write an expression that returns topology diagrams, such as getTopologyDiagrams(DeployCoreRoot/topology, '*'), you must select the notation:Diagram type from the GMF schema. This schema uses the following URI:

http://www.eclipse.org/gmf/runtime/1.0.1/notation

When you write custom expressions for the columns of the report, your choices of data type are limited to the types that BIRT accepts for column data, including integers, strings, Boolean values, and binary large objects (BLOBs). Most pieces of data that you retrieve from a topology element are strings, such as names, labels, and other textual attributes. Some functions return integers or Booleans. BLOBs are the appropriate data type for the functions that return images, such as getTopologyDiagramImage.

Feedback