Specifying what data to retrieve from an XML data source
BIRT reports must use data that is structured as a table consisting of rows and columns. XML documents use elements and attributes to present data. The data set wizard enables you to map a top-level XML element as a data set row, and other XML elements or attributes as columns. The wizard uses XPath expressions to define the paths to elements and attributes. XPath is a query language used to access parts of an XML document.
When you select an element or attribute to map to a row or a column, the wizard generates the corresponding XPath expression. If you are familiar with XPath syntax and you want to do more than the basic mapping, you can write your own XPath expressions.
This section describes the most common ways to write an XPath expression to use an element or attribute as a row or column in an XML data set. This section is not a substitute for formal XPath user documentation. Examples in this section refer to the following sample XML document:
<?xml version="1.0"?>
<library>
<book category="COOKING">
<title lang="es">The Spanish Cook Book</title>
<author name="Miguel Ortiz" country="es"/>
<year>2005</year>
</book>
<book category="CHILDREN">
<title lang="en">Everyone is Super Special</title>
<author name="Sally Bush" country="us"/>
<year>2005</year>
</book>
<audio format="CD" category="MUSIC">
<title lang="en">We All Sing Perty</title>
<artist name="Mary Rogers" country="us"/>
<year>2005</year>
</audio>
<audio format="CD" category="MUSIC">
<title lang="en">The Bluest Blues</title>
<artist name="Barry Sadley" country="us"/>
<year>2005</year>
</audio>
</library>
The most important syntax rules to consider when writing XPath expressions to define rows and columns are as follows:
Any path that starts with a forward slash (/) is an absolute path to an element.
Any path that starts with two forward slashes (//) selects an element at any location.
The XPath expression that defines the row mapping can use either of the previous path syntaxes. The following XPath expression selects all book elements that are children of library:
/library/book
The following XPath expression selects all book elements at any location:
//book
For attribute paths, use a single forward slash or left and right brackets. For example, the following paths are equivalent:
title/@lang
title[@lang]
To define an element’s attribute as a column, use either of the following syntax forms:
author/@name
author[@name]
To define a table-level attribute as a column, use either of the following syntax forms:
/@category
[@category]
To filter data rows, use either of the following predicate expression syntaxes:
Single-position predicates in the abbreviated form. The following example selects the first author listed:
author[1]
Single-equality conditions based on an attribute value. For example, select an element by using the value of an attribute of the element. In the following example, only books that are in English are selected:
title[@lang='eng']
XPath functions are not supported.
How to create a data set to retrieve data from an XML document
This procedure assumes you have already created the XML data source that this data set uses.
1 In Data Explorer, right-click Data Sets, then choose New Data Set.
2 In New Data Set, specify the following information:
1 In Data Source Selection, select the XML data source to use. Data Set Type displays XML Data Set.
2 In Data Set Name, type a name for the data set.
3 Choose Next.
3 In New XML Data Set, specify the XML source in one of the following ways:
To use the file specified in the XML data source, select Use the XML file defined in data source.
To select a file that is not specified in the data source, select the second option. In the text box, type the path to the XML file, or choose Browse to navigate to and select an XML file.
Choose Next.
4 Define the row mapping, using the following steps:
1 In XML Structure, navigate to the XML element that represents a data set row, and select the element. Choose the right arrow.
The Select or edit the XPath expression dialog displays an XPath expression that corresponds to the element you selected, as shown in
Figure 7‑9.
Figure 7‑9 Creating an XML data set
2 Select one of the generated XPath expressions or type another expression. For example, you can type a filter expression to retrieve only rows that meet a certain condition, as shown in the following example:
/library/book/author[@country='us']
Choose OK, then choose Next.
5 Define the column mapping, using the following steps:
1 In XML structure, navigate to and select the XML element or attribute that represents a column, then choose the right arrow. Column Mapping displays the default column mapping properties for the element or attribute you selected.
Figure 7‑10 shows an example of the default column mapping for an attribute named category.
Figure 7‑10 Column mapping properties
2 Select one of the generated XPath expressions or type another expression. Choose OK.
6 Repeat the preceding steps for every column to add to the data set.
Figure 7‑11 shows an example of column mappings defined in a data set.
Figure 7‑11 Mapping columns for an XML data set
7 Choose Finish to save the XML data set. Edit Data Set displays the columns, and provides options for editing the data set.
