AVEVA™ Information Standards Manager

Report Configuration via XML

Save PDF

Report Configuration via XML

Save PDF

Last UpdatedFeb 03, 2025
9 minute read

For a broader range of configuration options, it is possible to configure the report using XML Configurations for a report are contained in an XML Class Library definition, expressed as AVEVA ISM extensions, using a designated extension namespace. This implies that configurations can be embedded within a Class Library definition, or they can be kept in dedicated Class Library instances (containing nothing but report configuration information), referred to as Configuration Instances.

The XML schema

There is an XML schema, Aveva.GEICL.Syntax.PermGrid.xsd available. If you are using a schema aware XML editor (for example Microsoft Visual Studio, XMLSpy, or similar), installing this schema definition will improve the editing experience significantly.

The Permissible Grid extension namespace

The extension namespace for Permissible Grid configurations is defined as:

URI	http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Reports/PermissibleGrid/2015/01
Prefix	ism-pg

The URI is case sensitive, and has to be expressed exactly as stated above. The Prefix can actually be a value of your choice, as long as it is not conflicting with other namespace prefixes in the context (that is, Class Library) that the configuration is targeting. The recommendation is to use the value described above though.

In XML syntax the namespace declaration will look like:

<ClassLibrary xmlns="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Model/Basic/2012/01"

xmlns:geicl="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Model/Extension/2013/12"

xmlns:ism-pg="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Reports/PermissibleGrid/2015/01">

...

<ExtensionNamespace prefix="ism-pg"

name="AVEVA ISM Permissible Grid"

uri="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Reports/PermissibleGrid/2015/01"/>

</ExtensionNamespaces>

</ClassLibrary>

The <ExtensionNamespace> declaration is not required, but by including it the AVEVA ISM user interface will display the "friendly" name as opposed to the less readable URI in the extensions dialogue:

The structure of a report configuration

A report configuration is split into different sections, each section describing dedicated aspects of the report result. In compressed XML syntax the below example shows the sections of an overall configuration:

<?xml version="1.0" encoding="utf-8" ?>

<ClassLibrary xmlns="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Model/Basic/2012/01" xmlns:geicl="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Model/Extension/2013/12" xmlns:ism-pg="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Reports/PermissibleGrid/2015/01"

id="permissible.grid.01" name="01. Permissible Grid Default" version="1.0.0.0" versionDate="2015.01.18">

…

</Variables>

<Setup>

…

</Variables>

…

</Variables>

</InputPanel>

…

</InputPanels>

…

</Variables>

</Condition>

…

</Conditions>

</Styles>

…

</Style>

</Styles>

<Page>

</Headers>

</Trailer>

</Trailers>

</Page>

</OrderBys>

</Headers>

</Columns>

</Attributes>

</OrderBys>

</Columns>

</ Classes >

</PermissibleGrid>

</PermissibleGrids>

</Extension>

</ClassLibrary>

There are certain behaviors in AVEVA ISM that you should be aware of when working with Permissible Grid configurations.

The best way of editing a Permissible Grid configuration is to use a text editor, preferably one that is XML aware. A typical workflow in developing a configuration is to edit the XML file and load it into a catalogue item in AVEVA ISM (preferably an autonomous catalogue item, but it can also be merged into an already existing Class Library definition).

When you test the configuration, and find discrepancies or need to apply enhancements, you go back to the original XML file and apply your changes and merge it back into the previously loaded catalogue item. The way AVEVA ISM behaves when you load a file into an existing instance is that new nodes are appended at the end of their containing collection, and properties deleted from the file are still preserved. You will experience that in certain scenarios this might give a surprising result.

To control order of nodes, where significant, AVEVA recommends that you use the @geicl:sortOrder property. For example, when you insert new Classes/Columns nodes, they will be appended to the existing collection, independent of where they appear in the XML file, which means new Columns will appear at the end of the collection and will render at the end of the columns list in the resulting report. If you apply the @geicl:sortOrder property though, you are in total control of the order of the columns in the resulting report.

If you amend the configuration file by removing a property on a node, let’s say you remove the Classes/Columns/Columns/@suppress property, when you reload the XML file by merging it into the existing instance, the property does not go away! When merging an XML file into an existing instance, AVEVA ISM will apply changes to existing definitions being loaded, add new definition being loaded, but will not delete definition not being loaded.

If you are merging into an autonomous instance (i.e. an instance containing the Permissible Configuration only), the recommendation is to clear out the content (an icon in the catalogue view toolbar) before merging the amended XML file. This way you are deleting all existing content, and only the loaded content will preserve.

If you are merging into a composite instance, open the Class Library details dialogue, go the the Extensions tab, and delete the target permissible grid configuration before merging the amended XML file.

ClassLibrary

In the current version AVEVA ISM supports two ways of organizing XML Permissible Grid configurations:

Embedded in the target Class Library definition

With this approach, the report configuration will be an extension to the Class Library, as any other extension.
As a separate "Class Library" instance (recommended)

Even though a "Class Library" instance containing only a Permissible Grid configuration do not contain actual Class Library content, such as classes, attributes, and so on, it will be a separately named and versioned AVEVA ISM Catalogue item.

Note: A future version of AVEVA ISM might support multiple item types in the Catalogue, which will make it easier to separate Configurations from Class Libraries.

For this approach, the Class Library details, such as name, version, and so on will be properties describing the Configuration instance. AVEVA recommends that you apply these properties like you apply them for a real Class Library, that is, a globally unique identifier, a descriptive name, a real version number, and so on.

<ClassLibrary xmlns="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Model/Basic/2012/01"

xmlns:geicl="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Model/Extension/2013/12"

xmlns:ism-pg="http://schemas.aveva.com/Generic/Engineering.Information/Class.Library/Reports/PermissibleGrid/2015/01"

id=" my.permissible.grid.mycompanydomainname "

name="My Permissible Grid with Page Break"

version="1.0.0.0"

versionDate="2015.02.16">

<Extension>

A report configuration organized as a separate instance can potentially be used for multiple Class Libraries.

PermissibleGrids

The PermissibleGrids element is the root of the Permissible Grid configurations. It can take one or more PermissibleGrid child elements.

<PermissibleGrid geicl:id="my.permissible.grid.mycompanydomain"

name="Default Permissible Grid "

style="Default" headerStyle="DefaultHeader">

Element	Property	Description
PermissibleGrids	xmlns	Declares that the element, and any descendant elements, belongs to the specified namespace. The namespace uri should be the one for AVEVA ISM Permissible Grid, as stated in the ClassLibrary element at the top of the file. Notice that you should not specify the namespace prefix (ism-pg) in this case. Specifying the namespace on this element is for convenience. Without it, every XML tag in the configuration will have to be prefixed by ism-pg, for example <ism-pg:PermissibleGrids>
PermissibleGrid	geicl:id	Assign an identifier to the item. All items inside a collection element, such as PermissibleGrids must have an identifier which is unique within the containing collection
	style	The ID of a <Style> element (see below) that should be applied as the default style for all non-header cells in the grid. The default style will be applied only for cells not having an explicit style assigned
	headerStyle	The ID of a <Style> element (see below) that should be applied as the default style for all header cells in the grid. The default style will be applied only for cells not having an explicit style assigned
	Language	A language code, composed as "{languageCode}-{countryCode}". E.g. British English is specified as "en-GB". The first argument is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639-1 The second argument is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by The language code specified here is considered the default language for the output. When ordering a permissible grid output from the ISM user interface, you will have the option of choosing another language. When selecting a language different from Default, all ./@name and ./@description expressions will resolve to the corresponding language values on target entities. For entities in the Class Library where no translation has been specified for selected language, the default values for ./@name and ./@description will be used.
	namingConvention	A naming convention identifier. When applied, the value of all @id and/or @name properties will be mapped according to how the the naming convention has been applied on the Class Library definition
	extends	The identifier of another Permissible Grid definition, accessible in target composition. When specified, the resulting definition will be a combination of target definition merged with any ancestor definitions, where any settings in the target definition takes precedence. An inheritance chain can consist of multiple ancestors
	abstract	A boolean true/false value. When true, the definition can not be used as a runnable report, rather it is intended to be derived into other non-abstract definitions
	includeDeletedContent	A Boolean value specifying whether deleted nodes should be included in the report. Default value is false During a change session in AVEVA ISM (i.e. from Lock to Unlock), deleted nodes are preserved with a state of deleted, and they show in the user interface with a red background colour. For some use cases it might make sense to include deleted content in a Permissible Grid output, for example to show what changes will be applied when unlocking the Class Library and committing the changes
	geicl:sortOrder	Assign a Sort Order to the item. When there are multiple Permissible Grid configurations in one composition, the drop-down list in the user interface. for selecting a configuration, will be listed according to Sort Order

Variables

This section is optional and is used to define a collection of named values, that is, Variables. The value of the variables can be referenced elsewhere in the configuration, to control how the report renders.

</Variables>

For explanation of the details of this section, see Variables.

Setup

This section is optional and is used to define input fields for the report export dialogue in the user interface. This section can also contain conditional Variable definitions, based on user input in the export dialogue.

<Setup>

…

</ValidValues>

</Variable>

</Variable>

</Variables>

<Variable geicl:id="Input_Concept" name="'Select Concept'" description="'Select the concept of classes to be rendered in the report'"

required="true" geicl:sortOrder="10" value="Functional" validValues="$List_Concepts[]" consolidate="true" />

<Variable geicl:id="Input_MaturityLevel" name="'Select Maturity Level'" geicl:sortOrder="30"

validValues="./MaturityLevels" disabled="./MaturityLevels.isNull()" />

<Variable geicl:id="Input_Class_Hierarchy" name="'Class Hierarchy'" description="'...'"

required="true" geicl:sortOrder="40" value="Flattened" validValues="$List_Class_Hierarchy[]"/>

<Variable geicl:id="Input_Theme" name="'Select Colour Theme'"

required="true" dataType="Color" geicl:sortOrder="60" value="$Theme_Blue_Header_Color">

…

</ValidValues>

</Variable>

</InputPanel>

</InputPanels>

</Variables>

</Condition>

</Condition>

</Conditions>

</Setup>

Styles

This section is optional and is used to define a collection of Named Styles. A named style can be referenced elsewhere in the configuration, to be applied to a given selection of cells in the grid.

</Borders>

</Style>

</Style>

The values specified for the different properties can be literal strings (for example Center, true, and so on.), or they can be expressions (see Context nodes and expression syntax). Any expression in the Styles section are resolved in the context of the Class Library root node (see Context nodes).

For explanation of the details of this section, see Named styles.

Page Header and Trailer

This section is optional, and contains two sub-sections, one describing header rows that will be rendered above the grid in each sheet of the workbook, and the other describing trailer rows that will be rendered below the grid in each sheet of the workbook.

<Page>

</Headers>

</Trailers>

</Page>

For explanation of the details of this section, see Page Header and Trailer.

Attributes

This section contains three sub-sections, one describing the ordering of the attribute headers (running horizontally across the top of the grid), one describing values and formatting characteristics of the attribute headers, and the third describing values and formatting characteristics of the cells in the intersection between classes and attributes.

</OrderBys>

<Style>

</Style>

</Header>

</Headers>

</Columns>

</Attributes>

For explanation of the details of this section, see Attributes.

Classes

This section contains two sub-sections, one describing the ordering of the class headers (running vertically down the left side of the grid), and the other describing values and formatting characteristics of the class headers.

<OrderBy geicl:id="Extends" condition="./@extendsId ?? ZZZ" direction="Ascending" break="Row"

value="concat(./@extendsId, ' - ', ./@extends)" header="' '">

<Style>

</Style>

</Borders>

</HeaderStyle>

</OrderBy>

</OrderBys>

</Columns>

</Classes>

For explanation of the details of this section, see Classes

AVEVA™ Information Standards Manager