Configure Workhub API Data Structure

The View configuration of Dashboard relies on the Workhub API data structure configuration.

Data Groups

Data groups are logical groupings of data records that allow selection of any data in the AIM Workhub data model and turn it into a source agnostic structure. They allow the data to be independent of the modelling.

Data groups can be composed of either projections or other data groups. Then, a number of a data groups are allocated to a Class. Examples of data groups can be found in BootstrapSampleDataGroups.xml.

Data Groups can be utilized on the AIM Dashboard summary, content card and mobile views.

A Data Group can contain one of two things:

• A projection of what data to display.

• Other Data Groups.

The <ID> of the Data Group is used to link the Data Group with the classes and UI Components with which it will be used .

The examples in this section are taken from the BootstrapSampleDataGroups.xml file that can be found in [installation folder]\Import\Server\Bootstrap. See Alter the Bootstrap Files.

Example: Defining Data Groups

<DataGroup>

<ID>Details</ID>
<!-- Projection or DataGroup -->

</DataGroup>

Projection

Note: For details about Associative Object Model and XML Schema, see Associative Object Model and XML.

The projection of a data group defines the structure and content of the results set when the data group is executed for a given Object. The projection XML schema is based on the EIA Projection schema which is documented in the EIA documentation. Data group projections have extensions to this schema to provide sorting and structural capabilities that allow the structure of the data group result to be changed.

The Projection for a data group is defined within a Projection element and the projection itself is wrapped in a CDATA block as below:

<DataGroup>

<ID>Details</ID>

<Project>

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

<Projection xmlns="http://www.aveva.com/NET/EIA/Search/Projection">

<Object>

<ID />

</Object>

<Projection>

]]>

</Project>

</DataGroup>

Properties

The properties of an Object are the core concepts associated with an AIM Object as referred to in the EIWM Manual and are exposed via XML elements.

Any of these elements can have the following attributes:

Example:

<DataGroup>

<ID>Details</ID>

<Project>

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

<Projection xmlns="http://www.aveva.com/NET/EIA/Search/Projection">

<Object>

<ID label="My Id" />

<Context label="My Context" />

<Revision label="My Revision" />

<Name label="My Name" />

<ClassID label="My Class Id" />

<ClassName label="My Class Name" />

<Alias label="My Aliases" />

<IncidentalClassId label="My Incidental Class Id" />

<Alias label="My Incidental Class Name" />

<Alias label="My Class Scheme" />

</Object>

<Projection>

]]>

</Project>

</DataGroup>

Characteristics (Attributes)

An object has characteristics which can either belong to itself or a dataset associated to the object through the "has dataset" association. This allows us to display the characteristics of an Object. Characteristics of a tag could be displayed in two different ways:

• Individual characteristics

• All characteristics

  Display Method	Description	Attributes	Example
  Individual Characteristics	A single characteristic (attribute) of a given Object can be displayed by specifying the Name of the Characteristic.	label This is an optional attribute that allows the resulting data record to have a label different from the default. This is useful when you want to Name a property differently from its AIM Name in the UI. datasetclass The datasetclass is being used to get the primary value of the Characteristic. The primary value is the basis for comparisons for clashing values. allvalues Used when we intend to display all the values of the characteristic from all the datasets that it belongs to.	<Characteristic label="My Installed Power" allvalues="true" datasetclass="E-Power Dataset" > <Name>Installed Power</Name> </Characteristic>
  All Characteristics	All characteristics of a given object by using a wildcard setting. This is done by not declaring a Name element for the characteristic element.	excludeattributes (optional) Used to exclude a set of attributes by name. The value can be separated by a pipe symbol to specify more than one. allvalues This is a common attribute for both individual and all characteristics.	<Characteristic allvalues="true" excludeattributes="NPSH Available|NPSH Required" />

Associations

An Association is a link between two Objects that can be followed from one Object to another and there is no limit to the number of Associations an Object may have.

The mandatory aspect of an association is that we define a type for the association. The "type" of the association element would be used to get the data from the associated object.

This element can have the following attributes:

Example:

<Association type="is a part of" associationclass="SET" excludedclasses=
"CONSTRUCTION PACK" countonly="true">

<Object>

<ID />

</Object>

</Association>

In the above example, it excludes the associations from the Class "CONSTRUCTION PACK" and includes from the Class "SET" and gets the count of the number of associations

Association as Instance as Group

When selecting an association as part of a data group projection output modifiers can be specified as XML attributes that transform the data selected in the association to a different structure other than flat. One of these modifiers is instance as group. This formats each instance/object found at the other end of an association to be a group in its own right. A good use case for this is when you want to group attributes by their dataset

This element can have the following attributes:

Example:

<Association type="has dataset" instanceasgroup="true">

<Object>

<ID />

<Characteristic />

</Object>

</Association>

Association as Tabulation

Association as tabulation allows you to structure the retrieved data in a tabular format.

This element can have the following attributes:

Example:

<Association type="is a part of" tabulate="true">

<Object>

<ID/>

<ClassID/>

</Object>

</Association>

Associations as Group

Association as group allows you to group a number of objects under a user defined group name. Instead of a flat output for the association the output is a group containing all the objects following the association. With the objects structured in a tabulated format as with the tabulate behaviour described above. This is a useful function when you want to group documents together in a labelled group. For example all 2D documents go under a 2D group.

This element can have the following attributes:

Example:

<Association type="is referenced in" associationclass="3D MODEL" groupname="3D Models">

<Object>

<ID/>

<Name/>

</Object>

</Association>

In the above example, we get all the 3D model documents that are associated to the tag. The data displayed is a group containing all the objects at the end of the association with a label set by the value of group name "3D Models" for an association type – "is referenced in".

Associations – Classes

Associations - Classes allows you to get the objects/instances associated to the Class of the Object or any Class up or down the hierarchy from the objects class. An association tag is used within the class tag to define the data to retrieve. This helps in listing query forms, where query forms are associated with parent classes of the Object.

This element can have the following attributes:

Example:

<Class hierarchy="reverse">

<Association type="is associated with" tabulate="true" associationclass
="QUERY FORM DEFINITION">

<Object>

<ID/>

</Object>

</Association>

</Class>

Lifecycle State

LifecycleState allows the retrieval of data with respect to Lifecycle states by using below attributes:

Example:

<LifeCycleState label="Work Status" lifecyclegroupid="IPE|WORK STATUS">

<ID />

</LifeCycleState>

Nested Data Groups

As mentioned before, Data groups can either have a projection defined or they can contain other data groups

Example:

<DataGroup>

<ID>My Data Group</ID >

<DataGroup >

<ID>My Nested Data Group 1</ID>

</DataGroup >

<DataGroup>

<ID>My Nested Data Group 2</ID>

</DataGroup>

</DataGroup>

Assigning Data Groups to Classes

After defining a data group, you must define the classes for which that data group should be available.

Classes inherit all data groups from the closest parent that has data groups defined against it. Data group inheritance is all or nothing. The data groups defined for a child class are not additive to the data groups of their parent. You have to redefine all the groups that are required for the child class.

The ID of a data group is used to link a data group to a given class.

Example:

<Class>

<ClassID>EQUIPMENT</ClassID >

<DataGroups>

<DataGroup>

<ID>Details</ID >

</DataGroup>

<DataGroup>

<ID>Attributes</ID >

</DataGroup >

</DataGroups>

</Class>

Overriding Data Groups for a Given Class

A child class can override a data group defined for its parent. This is useful for specializing the data group used for a given class without changing the identifier that is used. This allows the same summaries to be used as the data group identifier for the class is the same but the data is specialized as the data group has been overridden by a new definition.

Example:

<Class>

<ClassID>EQUIPMENT</ClassID >

<DataGroups>

<DataGroup >

<ID >Details</ID >

</DataGroup >

<DataGroup >

<ID >Attributes</ID >

</DataGroup >

</DataGroups>

</Class>

In the above example, we can have a specialized Details section for Equipment rather than using the generic Details group.

The benefit of this is that you do not have to define additional views for the Equipment Class and can instead use the Tag views and just redefine the data displayed for objects of the Equipment Class.