Highlights Syntax Reference

The top element of the highlights bundle consists of a Bundle top element in which two elements are allowed:

Role defines the user roles allowed to use the predefined highlight categories for this model using a name (mandatory) and the default artefact type selected in the UI using a preSelectedType (mandatory).
Filters defines a list of highlight categories for certain types of artefact types, defined using the type attribute.

There are several types of predefined highlights categories:

TopArtefacts is used to retrieve artefacts with the biggest value for a given measure.
TopDeltaArtefacts is used to retrieve artefacts with the biggest variation in the value of a given measure since an earlier version.
TopBorderlineArtefacts is used to retrieve artefacts that are closest to the upper limit of a given scale level, and therefore most likely to be easy to improve with the smallest effort.
TopNewArtefacts is used retrieve artefacts that are new in the current version, sorted according to the value of a given measure.
TopModifiedArtefacts is used to retrieve the artefacts modified in the current version, sorted according to the value of a given measure.

TopArtefacts allows the following attributes:
- id (mandatory) is the id of the filter.
- name (deprecated) is unused.
- artefactTypes (optional) defines the types of artefacts to filter on.
- excludingTypes (optional, default: none) lists the artefact types for which the metric should not be displayed. This allows refining the types entered in the main filter above.
- measureId (optional, default: the measureId associated with the root indicator) is the name of the measure Id to filter on.
- order (optional, default: ASC) is the sort order for the list according to the reference measure ID. Valid values are ASC and DESC.
- altMeasureId (optional, default: empty) is the second measure ID to use for sorting.
- altOrder (optional, default: empty) is the sort order for the second measure ID. Valid values are ASC and DESC.
- resultSize (mandatory) is the number of results to include in the list. Use 10 to display 10 artefacts or * to display all artefacts.
altMeasureId and altOrder shall be both set or not set.
TopDeltaArtefacts allows the following attributes:
- id (mandatory) is the id of the filter.
- name (deprecated) is unused.
- artefactTypes (optional) lists the types of artefacts to filter on.
- measureId (optional, default: LEVEL) is the name of the measure Id to filter on.
- order (mandatory) is the sort order for the list according to the reference measure ID. Valid values are ASC and DESC.
- resultSize (mandatory) is the number of results to include in the list. Use 10 to display 10 artefacts or * to display all artefacts.
TopBorderlineArtefacts allows the following attributes:
- id (mandatory) is the id of the filter.
- name (deprecated) is unused.
- artefactTypes (optional) lists the types of artefacts to filter on.
- indicatorId (optional, default: LEVEL) is the name of the measure Id to filter on.
- minLevel (optional, default: empty) is The name of the rank to be used as the threshold for results. If you want to exclude artefacts above LEVELC, set minLevel to LEVELC.
- order (mandatory) is the sort order for the list according to the reference measure ID. Valid values are ASC and DESC.
- resultSize (mandatory) is the number of results to include in the list. Use 10 to display 10 artefacts or * to display all artefacts.
TopNewArtefacts allows the following attributes:
- id (mandatory) is the id of the filter.
- name (deprecated) is unused.
- artefactTypes (optional) lists the types of artefacts to filter on.
- measureId (optional, default: LEVEL) is the name of the measure Id to filter on.
- order (mandatory) is the sort order for the list according to the reference measure ID. Valid values are ASC and DESC.
- resultSize (mandatory) is the number of results to include in the list. Use 10 to display 10 artefacts or * to display all artefacts.
TopModifiedArtefacts allows the following attributes:
- id (mandatory) is the id of the filter.
- name (deprecated) is unused.
- artefactTypes (optional) is the types of artefacts to filter on.
- order (mandatory) is the sort order for the list according to the reference measure ID. Valid values are ASC and DESC.
- resultSize (mandatory) is the number of results to include in the list. Use 10 to display 10 artefacts or * to display all artefacts.

All highlights categories support the following nested elements, to customise output:

Column is used to add column with the value of a measure to the table.
Where is used to restrict returned artefacts, using condition on measures.
OrderBy is used to specify sort directives, in addition to the main one.

Column allows the following attributes:
- measureId (optional) is the ID of the measure
- indicatorId (optional) is the ID of the indicator
- infoId (optional) is the ID of the textual information.
- artefactTypes (optional, default: the parent value of artefactTypes ) lists the artefact types for which the metric should be displayed. This allows refining the types entered in the main filter above.
- excludingTypes (optional, default: the parent value of excludingTypes ) lists the artefact types for which the metric should not be displayed. This allows refining the types entered in the main filter above.
- headerDisplayType (optional, default: NAME) is the label to display in the header. The supported values are:
  - NAME is the measure's name
  - MNEMONIC is the measure's mnemonic
- displayType (optional, default: VALUE) sets the value display type. The supported values are:
  - VALUE for the measure's numeric value
  - RANK for the indicator's rank
  - ICON for the indicator's rank icon
  - DATE for the measure's value, displayed as a UTC date
  - DATETIME for the measure's value, displayed as a UTC date and time
  - TIME for the measure's value, displayed as a UTC time
  For DATE, DATETIME and TIME, you can specify the required format using the dateStyle, timeStyle and datePattern attributes described below.
- dateStyle (optional, default: DEFAULT): the date formatting style, used when the displayType is one of DATE or DATETIME.
  - SHORT is completely numeric, such as 12.13.52 or 3:30pm.
  - MEDIUM is longer, such as Jan 12, 1952.
  - DEFAULT is MEDIUM.
  - LONG is longer, such as January 12, 1952 or 3:30:32pm.
  - FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST.
- timeStyle (optional, default: DEFAULT): the time formatting style, used when the displayType is one of DATETIME or TIME. See above for available styles.
- datePattern (formerly dateFormat) (optional, default: empty): the date pattern, used when the displayType is one of DATE, DATETIME or TIME.
  - "yyyy.MM.dd G 'at' HH:mm:ss z" is "2001.07.04 AD at 12:08:56 PDT".
  - "EEE, d MMM yyyy HH:mm:ss Z" is "Wed, 4 Jul 2001 12:08:56 -0700".
  If this attribute is set, both dateStyle and timeStyle attributes are ignored. The date is formatted using the supplied pattern. Any format compatible with the Java Simple Date Format can be used. Refer to http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html for more information.
- decimals (optional, default: 2) sets the number of decimals, used when the displayType is VALUE.
- suffix (optional, default: empty) is the text to display after the measure.
Either measureId , infoId or indicatorId is required. Note that all display related tags, except headerDisplayType and displayType are ignored when infoId is used.
Where allows the following attributes:
- measureId (mandatory) is the ID of the measure
- infoId (optional) is the ID of the textual information
- value (optional, default: empty) is the value of the measure
- bounds (optional, default: empty) sets bounds values for the measure.
Either measureId or infoId is required.
Either value or bounds is required. Note that bounds is not supported if infoId .
OrderBy allows the following attributes:
- measureId (mandatory) is the ID of the measure
- order (mandatory) is the sort order for measure. Supported values are:
  - ASC for ascending
  - DESC for descending

Prev	Up	Next
Understanding Highlights	Home \| ToC	Chapter 12. Tutorials