Creating Dashboard Specifications

The Create Dashboard Report action generates a graphical report based on the contents of one or more Table datasets. The layout of the report, and the type and format of each chart are determined by the XML code set in the action’s Dashboard Spec property. This XML code should have the following structure:

REPORT Section

Each specification has a top-level <REPORT> section as follows:

…

</REPORT>

The dashboard’s background color and title font color may be specified using attributes in the <REPORT> tag, for example:

If the Create Dashboard Report action’s ‘Embedded’ parameter is set to ‘false’, the NoHeader and NoFooter attributes may be used in the <REPORT> tag to hide the report’s header and footer.

Hiding the header only:

…

</REPORT>

Hiding the footer only:

…

</REPORT>

Hiding both the header and footer:

…

</REPORT>

ROW Section

The <REPORT> section contains one or more <ROW> sections. Although more than one <ROW> section may be specified, a single <ROW> section is sufficient for many types of report.

<ROW>

…

</ROW>

</REPORT>

The following optional attributes may be used in the <ROW> tag:

Title: Specifies the title to be used for the row.
TitleColor: Specifies the color to be used for the title’s text.
TitleBackgroundColor: Specifies the color to be used for the title’s background.

For example:

…

</ROW>

</REPORT>

CELL Sections

Each <ROW> section in the specification contains one or more <CELL> sections, which represent columns in the report. Each <CELL> section has a Span attribute which specifies the number of columns the CELL should occupy.

Span attributes have the value "span1" … "span12". It is recommended that the total of the Span values in each <ROW> section should not exceed 6.

<ROW>

…

</CELL>

…

</CELL>

…

</CELL>

</ROW>

</REPORT>

OBJECT Sections

Each <CELL> section contains one or more <OBJECT> sections, which describe the charts and text objects that will be displayed vertically in the cell. Each <OBJECT> section specifies the Source parameter, Data Store table or text object that will provide the data for the chart.

<ROW>

…

</OBJECT>

…

</OBJECT>

</CELL>

</ROW>

</REPORT>

The UrlLink value refers to an input String property which should be added to the Create Dashboard Report action using the Define Action Parameters Wizard. The property should be linked to a String parameter or dataset that contains a URL, for example, linking to an HTML Report or external web site.

URL links may be added to any <OBJECT> tag, including those that contain <TEXT>, <IMAGE> or <GRAPHIC> tags. Click a Dashboard report object to display its associated URL. In the case of Multi-Level Dashboard reports, click a chart’s title to open the associated URL. An example is shown here.

OBJECT_LINK Sections

Each <CELL> section may contain one or more OBJECT_LINK sections. These refer to the URLs of Dashboard reports that are to be included in the report being generated.

<ROW>

<OBJECT_LINK Param="Link1" LinkedParam="Source1"/>

</CELL>

<OBJECT_LINK Param="Link2" LinkedParam="Source2"/>

</CELL>

</ROW>

</REPORT>

The Param value refers to a String property linked to a Dashboard report URL. It may be a new String parameter created using the Define Action Parameters Wizard, or an existing String parameter, for example Subchart1. The LinkedParam value refers to a Source property in the associated Create Dashboard Report action that provides the data for the linked chart.

Multi-Level Dashboard Report Example

GRAPHIC Section

Each <OBJECT> section that specifies a Source parameter may contain a <GRAPHIC> section which describes the attributes of the chart. If you wish to use the default attributes that are set for a chart, the <GRAPHIC> section may be omitted.

<ROW>

…

</GRAPHIC>

</OBJECT>

</CELL>

</ROW>

</REPORT>

Note that each <GRAPHIC> object must specify a different Source parameter. However a <GRAPHIC>and <TABLE> object may share the same Source parameter.

<GRAPHIC> Tags

The following tags may be included within a <GRAPHIC> section. In most cases, these tags are only required in order to overwrite their default values.

<TYPE> (Default: Bar)

This attribute describes the type of the chart. The allowable values are: Bar, Bar-Cylinder, Column, Column-Cylinder, Doughnut, Line, Pie, StackedBar, StackedBar-Cylinder, StackedColumn, StackedColumn100, StackedColumn-Cylinder.

Note: StackedColumn100 charts display multiple series as percentage values, so that each column in the chart has a height of 100.

<WIDTH>

The width of the chart in pixels. If this value is not set, the width of the chart is determined by multiplying the number specified in the Span attribute by 240 pixels. In most cases, the <WIDTH> tag is not required.

The height of the chart in pixels. If this value is not set, the height of the chart is determined by multiplying the number specified in the Span attribute by 240 pixels. The <HEIGHT> tag may be required to limit the height of a wide chart.

<CHART_PROPERTIES>

A list of custom properties to be applied to the chart, specified as a list of comma-separated name/value pairs, for example:

<CHART_PROPERTIES>Name1=Value1, Name=Value2, ...</CHART_PROPERTIES>

A list of custom properties may be found at https://docs.microsoft.com/en-us/previous-versions/dd456764%28v%3dvs.140%29. Note that not all custom properties are applicable to all types of chart.

In this release of LiveCompare, Doughnut and Pie charts have been set to be rendered as flat by default, not using soft edges. The previous behavior may be restored by setting the following:

<CHART_PROPERTIES>PieDrawingStyle=SoftEdge</CHART_PROPERTIES>

<CHART_TITLE>

The title to be used for the chart. The default value is the name of the Table dataset that provided the data for the chart. A chart’s title may be set dynamically by carrying out the following steps:

Use the Define Action Parameters Wizard to add a new input property of type String to the Create Dashboard Report action. The String property should have an appropriate name, for example, ChartName.
Create a String parameter or dataset node for the ChartName property, and set its value to be the title to be used for the chart.
In the <CHART_TITLE> tag for the chart, refer to the ChartName property as follows:

<CHART_TITLE>%ChartName%</CHART_TITLE>

<BACKGROUND_COLOR> (Default: AliceBlue)

The color to be used for the text background, specified as either a symbolic name or a hexadecimal #RGB value.

<TITLE_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the chart title.

<TITLE_FONT_SIZE> (Default: 16)

The font size (in points) to be used for the chart title.

<TITLE_FONT_STYLE> (Default: Regular)

The font style to be used for the chart title. The allowable values are: Bold, Italic, Regular, Strikethrough, Underline.

<TITLE_FONT_COLOR> (Default: Black)

The color to be used for the chart title, specified as either a symbolic name or a hexadecimal #RGB value.

<LEGEND_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the chart legend.

<LEGEND_FONT_SIZE> (Default: 9)

The font size (in points) to be used for the chart legend.

<LEGEND_FONT_STYLE> (Default: Regular)

The font style to be used for the chart legend. The allowable values are: Bold, Italic, Regular, Strikethrough, Underline.

<LEGEND_FONT_COLOR> (Default: Black)

The color to be used for the legend text, specified as either a symbolic name or a hexadecimal #RGB value.

<SERIES_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the chart series.

<SERIES_FONT_SIZE> (Default: 9)

The font size (in points) to be used for the chart legend.

<SERIES_FONT_STYLE> (Default: Regular)

The font style to be used for the chart series. The allowable values are: Bold, Italic, Regular, Strikethrough, Underline.

<SERIES_FONT_COLOR> (Default: Black)

The color to be used for the series text, specified as either a symbolic name or a hexadecimal #RGB value.

<AXES_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the chart axes.

<AXES_FONT_SIZE> (Default: 9)

The font size (in points) to be used for the chart axes.

<AXES_FONT_STYLE> (Default: Regular)

The font style to be used for the chart axes. The allowable values are: Bold, Italic, Regular, Strikethrough, Underline.

<AXES_FONT_COLOR> (Default: Black)

The color to be used for the axes text, specified as either a symbolic name or a hexadecimal #RGB value.

<PALETTE> (Default: Pastel)

The palette of colors to use for a multiple series chart. The allowable values are: Berry, Bright, BrightPastel, Chocolate, EarthTones, Excel, Fire, Grayscale, IntelliCorp, IntelliCorp2, IntelliCorp3, Light, Pastel, SeaGreen, SemiTransparent. Custom palette names may also be used. See the ‘User-Defined Color Palettes’ section below.

<PALETTE_INDEX> (Default: 0)

This attribute specifies the index value of the palette color to use for a single series chart. If a graph has multiple series and a PALETTE_INDEX is specified, the same color is used for each of the series.

<IS3D> (Default: false)

Specifies whether a chart should be displayed in three dimensions.

<INCLINATION> (Default: 15)

The angle of inclination for a three dimensional chart.

<LINE_WIDTH> (Default: 1)

The line width to be used for line graphs.

<REVERSE_LEGEND> (Default: false)

Specifies whether the order of the items displayed in a chart’s legend should be reversed.

<ROTATION> (Default: 30)

The angle of rotation for a three dimensional chart.

The maximum value for the axis that displays a chart’s values. Does not apply to Doughnut or Pie charts. If this attribute is not specified, the maximum is set to accommodate the values in the table that is being reported upon.

<SHOW_LEGEND>

Specifies whether a legend should be displayed relating series colors to series names. The default value is ‘true’ for multiple series charts, or for charts of type Doughnut or Pie.

<SHOW_VALUE_LABELS> (Default: true)

Specifies whether numerical labels should be displayed on the chart.

<SHOW_X_MAJOR_GRID> (Default: true)

Specifies whether large interval X grid lines should be displayed on the chart.

<SHOW_X_MINOR_GRID> (Default: false)

Specifies whether small interval X grid lines should be displayed on the chart.

<SHOW_Y_MAJOR_GRID> (Default: true)

Specifies whether large interval Y grid lines should be displayed on the chart.

<SHOW_Y_MINOR_GRID> (Default: false)

Specifies whether small interval Y grid lines should be displayed on the chart.

<X_AXIS_INTERVAL> (Default: 1)

The interval used for labels on the chart’s X axis. Set this value to 0 to remove the X axis labels.

<Y_AXIS_INTERVAL> (Default: Interval selected automatically)

The interval used for labels on the chart’s Y axis. Set this value to 0 to remove the Y axis labels.

<X_AXIS_LABEL_ANGLE> (Default: -45)

The angle of the axis labels relative to the X axis in degrees.

<Y_AXIS_LABEL_ANGLE> (Default: 0)

The angle of the axis labels relative to the X axis in degrees.

TABLE Sections

If an <OBJECT> section defines a chart, the associated table data may be displayed underneath it in the Dashboard report. This is achieved using an additional <OBJECT> section that refers to the chart’s Source parameter, and has a <TABLE> section that defines the table’s height and width (in pixels), and its background color.

The following Dashboard specification displays two column charts and their associated tables.

<ROW>

<TYPE>Column</TYPE>

<SHOW_VALUE_LABELS>false</SHOW_VALUE_LABELS>

</GRAPHIC>

</OBJECT>

<TABLE>

<BACKGROUND_COLOR>Cornsilk</BACKGROUND_COLOR>

</TABLE>

</OBJECT>

</CELL>

<TYPE>Column</TYPE>

<SHOW_VALUE_LABELS>false</SHOW_VALUE_LABELS>

</GRAPHIC>

</OBJECT>

<TABLE>

<BACKGROUND_COLOR>Cornsilk</BACKGROUND_COLOR>

</TABLE>

</OBJECT>

</CELL>

</ROW>

</REPORT>

TABLE Tags

The following tags may be included within a <TABLE> section.

<WIDTH> (Default: 500)

The width of the table in pixels.

<HEIGHT> (Default: 500)

The height of the chart in pixels. If a table is taller than its height setting, the table is shown with a vertical scrollbar.

<TITLE>

The title to be used for the table. The default value is the name of the Table dataset that provided the data for the associated chart. A table’s title may be set dynamically by carrying out the following steps:

Use the Define Action Parameters Wizard to add a new input property of type String to the Create Dashboard Report action. The String property should have an appropriate name, for example, TableName.
Create a String parameter or dataset node for the TableName property, and set its value to be the title to be used for the table.
In the <TITLE> tag for the table, refer to the TableName property as follows:

<TITLE>%TableName%</TITLE>

<BACKGROUND_COLOR> (Default: AliceBlue)

The color to be used for the table’s background, specified as either a symbolic name or a hexadecimal #RGB value.

<TITLE_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the table title.

<TITLE_FONT_SIZE> (Default: 16)

The font size (in points) to be used for the table title.

<TITLE_FONT_STYLE> (Default: normal)

The font style to be used for the table title. The allowable values are: Bold, Italic.

<TITLE_FONT_COLOR> (Default: Black)

The color to be used for the table title, specified as either a symbolic name or a hexadecimal #RGB value.

<SHOW_HEADER> (Default: true)

Determines whether the table’s header is displayed. Set this tag to false to hide the table’s header row.

<HEADER_COLOR> (Default: White)

The color to be used for the table header’s text, specified as either a symbolic name or a hexadecimal #RGB value.

<HEADER_BLACKGROUND_COLOR>

The color to be used for the table header’s background, specified as either a symbolic name or a hexadecimal #RGB value.

Text Objects

Text objects allow a title, value and subtitle to be displayed in a Dashboard report. Static text objects may be specified within an <OBJECT> tag as follows:

<TITLE>LiveCompare</TITLE>

<SUBTITLE>Dashboard Report Text Example</SUBTITLE>

</TEXT>

</OBJECT>

If the Index value is 0 or not specified, the text object is assumed to be static. Dynamic text objects may be displayed by specifying a positive index value as follows:

</OBJECT>

The index value <n> refers to the nth item in the ‘Texts’ Table parameter supplied to the Create Dashboard Report action. The Texts table should have TITLE, VALUE and SUBTITLE columns which contain the text items to be displayed. The following tags may be used to specify the background color, font and border properties for a text object:

<BACKGROUND_COLOR> (Default: AliceBlue)

The color to be used for the text background, specified as either a symbolic name or a hexadecimal #RGB value.

<BORDER_COLOR>

The color of the text object’s border, as either a symbolic name or a hexadecimal #RGB value. This tag applies if BORDER_WIDTH is greater than 0.

<BORDER_WIDTH>

The width of the text object’s border in pixels.

<TITLE>

The title to be used for the text object. The default value is the title for the text object specified in the Texts table. A text object’s title may be set dynamically by carrying out the following steps:

Use the Define Action Parameters Wizard to add a new input property of type String to the Create Dashboard Report action. The String property should have an appropriate name, for example, TextName.
Create a String parameter or dataset node for the TextName property, and set its value to be the title to be used for the text object
In the <TITLE> tag for the text object, refer to the TextName property as follows:

<TITLE>%TextName%</TITLE>

<TITLE_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the title text.

<TITLE_FONT_SIZE> (Default: 30)

The font size (in points) to be used for the title text

<TITLE_FONT_STYLE> (Default: Regular)

The font style to be used for the title text. The allowable values are: Bold, Italic, Regular, Strikethrough, Underline.

<TITLE_FONT_COLOR> (Default: Black)

The font family to be used for the title text, specified as either a symbolic name or a hexadecimal #RGB value.

<VALUE_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the value text.

<VALUE_FONT_SIZE> (Default: 60)

The font size (in points) to be used for the value text.

<VALUE_FONT_STYLE> (Default: Regular)

The font style to be used for the value text. The allowable values are: Bold, Italic, Regular, Strikethrough, Underline.

<VALUE_FONT_COLOR> (Default: Black)

The font family to be used for the value text, specified as either a symbolic name or a hexadecimal #RGB value.

<SUBTITLE_FONT_FAMILY> (Default: Helvetica)

The font family to be used for the subtitle text.

<SUBTITLE_FONT_SIZE> (Default: 20)

The font size (in points) to be used for the title text

<SUBTITLE_FONT_STYLE> (Default: Regular)

The font style to be used for the subtitle text. The allowable values are: Bold, Italic, Regular, Strikethrough, Underline.

<SUBTITLE_FONT_COLOR> (Default: Black)

The font family to be used for the subtitle text, specified as either a symbolic name or a hexadecimal #RGB value.

Dashboard Reports Text Examples

SUBCHARTS Section

Each <OBJECT> section may contain a <SUBCHARTS> section which lists the Subchart properties that are set in the Dashboard report. Subcharts are used when creating multi-level Dashboard reports. The subcharts are assigned to chart areas in the order specified. Take particular care when specifying subcharts for multi-series charts.

…

</SUBCHARTS>

Additional Subchart input parameters of type String may be added to a Create Dashboard Report action using the Define Action Parameters Wizard.

User-Defined Color Palettes

User-defined custom color palettes may be defined using <PALETTE> tags within a Dashboard specification’s top-level <REPORT> tag. Colors may be specified as either a symbolic name or a hexadecimal #RGB value.

<COLOR>Brown</COLOR>

<COLOR>Crimson</COLOR>

<COLOR>DarkBlue</COLOR>

<COLOR>DarkGreen</COLOR>

<COLOR>DarkMagenta</COLOR>

<COLOR>DarkRed</COLOR>

<COLOR>DarkSlateBlue</COLOR>

<COLOR>FireBrick</COLOR>

</PALETTE>

<COLOR>#FFADD6</COLOR>

</PALETTE>

…

</REPORT>

Each palette may have any number of color tags; the colors are used in rotation if a chart has more data points than the number of colors in the specified palette. Custom palette names may be used in the <PALETTE> tags within a Dashboard specification’s <GRAPHIC> section.

Images

Images generated by the Execute R action may be included in Dashboard reports. To add an image to a Dashboard report, use the Define Action Parameters Wizard to add a new input property of type Image to the Create Dashboard Report action, and link the property to an Image dataset returned by the Execute R action.

Use the <IMAGE> tag as follows in a Dashboard specification’s XML to include the image in a Dashboard report. In each of these examples, Image1 refers to the name of the action property defined by the Define Action Parameters Wizard.

</OBJECT>

Alternatively, the Param setting may be placed on the <IMAGE> tag as follows:

</OBJECT>

The <WIDTH> and <HEIGHT> tags may also be used to specify the image’s width and height in pixels:

<IMAGE>

</IMAGE>

</OBJECT>

Any image that may be referenced by a URL stored in an Image parameter or dataset may be included in a Dashboard report. If an image’s URL contains ‘Workspaces’ as part of the path, it is assumed to have been generated by the Execute R action, and the image will be copied to the <LiveCompare user data dir>\public\Reports\<Workspace Name> directory when the Create Dashboard Report action is run. Otherwise, it will not be copied and the link in the Dashboard report will point to the image’s original location.

Treemaps

Treemaps provide a visual representation of a hierarchy of objects stored in a Table dataset In the Smart Impact App’s Dashboard report, a treemap is used to the represent not impacted, impacted and most at risk objects.

Nodes in a treemap are displayed as rectangles are represent individual; the area of each node represents a numerical attribute of an object, for example its usage count, relative to the area of other nodes.
Containers in a treemap are displayed as boxes with a header row. Each container is named after a parent object, and includes all parent’s child objects.

Treemaps occupy the space made available by the Dashboard report’s Span setting. The following shows the specification for a simple treemap.

<ROW>

<MAX_DEPTH>2</MAX_DEPTH>

</TREEMAP>

</OBJECT>

</CELL>

</ROW>

</REPORT>

Source Table

The Source table represents a hierarchy of objects where each node has one parent and zero or more children (the exception is the root node in the hierarchy, which has no parents. The names used for the source table columns do not matter, but their order is important.

The first column stores a unique identifier for the node.
The second column stores the identifier for the node’s parent (for the root node, this column should be set to null).
The third column stores the nodes relative size value.
The fourth column stores a key for the treemap’s filter and interactive legend.
The fifth column stores the node’s name, which is used as part of the node’s tooltip.

The following values are supported in the table’s fourth column.

Value	Description
-1	Not Impacted
0	Impacted
1	Most-at-Risk
2	A top-level item that should not be filtered

For example, the following source table lists objects in three functional app areas.

ID	PARENT	SIZE	FILTER_KEY	NAME
Functional App Area	null	0	2
Cost Accounting	Functional App Area	0	2
Cross-Application	Functional App Area	0	2
Financial Accounting	Functional App Area	0	2
ZLEASEDCAR - TCOD	Cost Accounting	50	-1	Program ZTRV_LEASEDCAR_REPORT
CATSSHOW - PROG	Cross-Application	20	0	Display Time Sheet Data
RFFOAVIS - PROG	Financial Accounting	10	1	Payment Medium International - Zero Balance Notice
RFFOUS_C - PROG	Financial Accounting	10	1	International Payment Medium - Check (with check management)

In this example:

The Functional App Area, Cost Accounting, Cross-Application and Financial Accounting folders have a size of 0 and are not filtered.
Objects in the Cross-Application Functional App Area are not impacted.
Objects in the Cost Accounting Functional App Area are impacted.
Objects in the Financial Accounting Functional App Area are most-at-risk.

Node tooltips are formed from values in the ID, NAME and SIZE column. If a header row is selected in the treemap (for example Financial Accounting), the tool tip displays the sum of its child components’ SIZE values.

Note that the SIZE values above 0 must be sorted in descending order to allow the treemap’s zoom function to work correctly.

The legend for a treemap may be modified as described here.

TREEMAP Tags

The following tags may be included within a <TREEMAP> section.

<FONT_COLOR> (Default: White)

The color to be used for the treemap text, specified as either a symbolic name or a hexadecimal #RGB value.

<HEADER_HEIGHT> Default 20

The height used for header elements in pixels. Set this tag to 0 to display the treemap without header elements.

The height of the treemap in pixels (optional). The default is to use all the available space.

<MAX_COLOR> Default #CC1C0D (Red)

The color to be used for most-at-risk objects in the treemap, specified as either a symbolic name or a hexadecimal #RGB value.

<MAX_DEPTH> Default 1

The maximum depth of nodes to be displayed in the treemap.

<MAX_POST_DEPTH> Default 1

The number of nodes levels beyond <MAX_DEPTH> to show in hinted fashion. Hinted nodes are shown as shaded rectangles within a node that is within the <MAX_DEPTH> limit.

<MID_COLOR> Default #FCB128 (Orange)

The color to be used for impacted objects in the treemap, specified as either a symbolic name or a hexadecimal #RGB value.

<MIN_COLOR> Default #8BC34A (Green)

The color to be used for not impacted objects in the treemap, specified as either a symbolic name or a hexadecimal #RGB value.

<WIDTH>

The width of the treemap in pixels (optional). The default is to use all the available space.

Modifying a Treemap’s Legend

The <LEGEND> section of a treemap definition allows the color and label for the default Impacted, Not Impacted and Most-at-Risk legends to be modified. Either two or three ITEM entries may be specified within a <LEGEND> section, for example:

</LEGEND>

</LEGEND>

The Color attribute may be either a symbolic name or a hexadecimal #RGB value.

If a <LEGEND> section has three ITEM tags:

The legend in the first tag is used for items in the Source table with a FILTER_KEY value of -1.
The legend in the second tag is used for items in the Source table with a FILTER_KEY value of 0.
The legend in the third tag is used for items in the Source table with a FILTER_KEY value of 1.

If a <LEGEND> section has two ITEM tags:

The legend in the first tag is used for items in the Source table with a FILTER_KEY value of -1.
The legend in the second tag is used for items in the Source table with a FILTER_KEY value of 0.

If a <LEGEND> section is specified, the label associated with each ITEM tag is used in the treemap’s tooltips.

Create Dashboard Report Actions