Using XML data

Dashboard Builder enables you to augment your dashboard by using XML data files as a data source in addition to Apama DataView. The properties of dashboard objects can be attached to data elements in XML files. To be used as a data source, an XML file must follow the formatting guidelines presented in this chapter.

XML files can be used to make a dashboard more generic by isolating label values, colors, and similar attributes in a file which can be shared by multiple dashboards. XML files can also be used as an intermediary for bringing data from other sources into a dashboard.

XML data format

XML files used as data sources with Dashboard Builder must adhere to the formatting guidelines detailed in this section.

XML data files must contain the dataset element. This element identifies the XML data as a dashboard XML data file. The standard template for an XML data file is as follows:

<?xml version="1.0"?>
<dataset xmlns="www.sl.com" version="1.0">Data elements</dataset>

All XML data files must adhere to this template.

XML data files can contain both scalar and tabular data elements as discussed in the topics below. XML data files can contain multiple scalar and tabular data elements.

Scalar data elements

Scalar data elements are single values such as a string or number. Scalar data elements are useful for isolating common labels, colors, and similar items in XML resource files that can be shared by multiple dashboard files.

A scalar element is defined in an XML data file with the data tag as follows:

<data key="element_name" value="element_value" />

The key attribute specifies the name of the data element. This name will be used when attaching object properties to the data element. The value specifies the value for the element; both string and number values can be specified for the value.

Following is an example of an XML data file containing scalar data elements:

<?xml version="1.0"?>
<dataset xmlns="www.sl.com" version="1.0">
  <data key="status_label" value="Current Status:" />
  <data key="status_complete" value="Completed" />
  <data key="status_failed" value="Failed" />
  <data key="load_factor" value="1.5" />
  <data key="max_occurence" value="10000" />
</dataset>

Here, five different scalar data elements are defined. The first three, status_label, status_complete, and status_failed, have string values. The last two, load_factor and max_occurence, have number values.

Tabular data elements

Tabular data elements contain multiple columns and rows of data. The value for each field can be a string, integer, double, or boolean. Tabular data elements are useful for data sets containing multiple item instances. Tabular data can be used to populate Table, Trend Chart, and other dashboard objects.

Tabular elements are defined in a table tag that includes a set of tags that describe the data in the table and tags for each row of data values. A tabular element is defined as follows:

  <table key="production_table">
    <tc name="column1"
      type="string | double | int | boolean"
      index="true | false"/>
    <tc name="column2"
      type="string | double | int | boolean"
      index="true | false"/>
    <tr name="ID0”>
      <td>column1_value</td>
      <td>column2_value</td>
    </tr>
    <tr name="ID1">
      <td>column1_value</td>
      <td>column2_value</td>
    </tr>
  </table>

The key attribute on the table tag specifies the name of the data table. This name will be used when attaching object properties to the data element.

The tc tag defines a column in the table. For each column, you must specify a name, type, and whether or not the column is to be used as index. Subsequent row definitions must contain values for each column where the type of the value matches the type defined for the column. The index field is reserved for future use.

The tr tag defines a single row of data. Each row must contain a td tag for each column in the table. The td tags define the value for a column for a single row.

Following is an example XML data file containing a tabular data element named production_table:

<?xml version="1.0"?>
<dataset xmlns="www.sl.com" version="1.0">
<table key="production_table">
  <tc name="Plant"
     type="string"
     index="true"/>
  <tc name="Units in Production"
     type="int"
     index="false"/>
  <tc name="Units Completed"
     type="int"
     index="false"/>
  <tc name="Status"
     type="string"
     index="false"/>
  <tc name="On Schedule"
     type="boolean"
     index="false"/>
  <tr name="PID 0">
    <td>San Francisco</td>
    <td>87</td>
    <td>70</td>
    <td>online</td>
    <td>true</td>
  </tr>
  <tr name="PID 1">
    <td>San Jose</td>
    <td>75</td>
    <td>63</td>
    <td>online</td>
    <td>false</td>
  </tr>
</table>
</dataset>

Here, the table is defined as containing four columns; Plant, Units in Production, Units Completed, and On Schedule. There are two rows in the table; one each for San Francisco and San Jose.

Defining an XML data source

To attach object properties to data elements in an XML data file, you need to first make the XML data file known by adding it as a data source

  1. Select Options… from the Tools menu. This will display the Application Optionsdialog.

  2. In the Application Options dialog select XML in the left pane.

    On this tab you can define the XML files to be used as data sources. The XML Source Prefix field allows you to define a file path prefix that can be used to locate XML data files.

  3. Set the XML Source Prefix field to the directory of the tutorial sample in your Apama installation. By default this is:

    %APAMA_HOME%\samples\dashboard_studio\tutorial\

    Be sure to include the final backslash in the XML Source Prefix.

  4. Click the Add button to define a new XML data source.

    This will display the Edit XML Source dialog.

  5. Define a new data source as follows and click the OK button.

    Illustration showing how to define a new data source

You have defined the XML data source named xml data. The data for this data source is in the file tutorial-xml-data.xml located in the tutorial directory.

When defining an XML data source you specify:

  • XML Source Name — The name you will use to refer to the data source when defining data attachments.
  • XML Source Path — The full path to the XML data file. If an XML source prefix is used, a partial path only need be specified.
  • Use XML Source Prefix — If enabled, the XML source prefix will be affixed to the XML source path.
  • Static — If enabled Apama will read the file only once. If disabled, Apama will read the file each time it is modified. Each time the file is read any attached objects will update to show the latest data elements in the file.
  • Contains Substitutions — Enable this option if the XML source path contains substitution variables. If enabled, Apama will not read the file until the substitutions have been defined.

To edit an existing XML data source, double-click it in the list of XML sources. You can also specify an XML data source to use as the default when defining XML data attachments.

XML data source definitions are saved in OPTIONS.ini. To persist an XML data source definition you must click Save in the Application Optionsdialog.

Attaching objects to XML data

After having defined an XML data source you can attach object properties to the data elements within the XML data file. The steps for doing this are similar to defining attachments to the instance data.

To attached object properties to the data elements within the XML data file

  1. If you have not yet done so, define the XML data source xml data as detailed in the previous section.

  2. Open the file tutorial-xml-data.rtv by selecting XML Data on the tutorial main page.

    Illustration showing a table object

    The table object in this dashboard is attached to the production_table data element in the file tutorial-xml-data.xml.

  3. Open the file tutorial-xml-data.xml in a text editor and examine it to see that there is a column in the table for each column defined for production_table and that there is a row in the table for each row defined.

  4. Select the table object and double-click the valueTable property in the Object Properties panel.

    Illustration showing how the valueTable property is defined

    Here the property is attached to the production_table data element for the XML data source named xml data. The Columns and Filter fields can be used to select a subset of columns or rows as is done for the instance data attachments.

  5. With the table object still selected, right-click the label property and select XML from the Attach to Data menu.

    Illustration showing the menu

  6. If label is a scalar property, it must be attached to a scalar data element. Attach it to the data element string_element as shown in the following:

    Illustration showing how the label property is defined

    Do not use the Data server field of the Attach to XML Data dialog.

The label of the table will change.

Illustration showing the table