Elements and Attributes for Project Configuration

ConfigurationSettings

This is the root element for all Project Configurations and contains following sub-elements. There would be only one ConfigurationSettings element allowed in the Project Configuration XML.

TemplateID

Each EIWM output file should have a template Id that must be unique to that file for the project. The "TemplateID" is typically based on the output file name. "TemplateID" is an optional element.

The "TemplateID" can be specified in a number of ways:

• Fixed "TemplateID" specified:

  All file(s) produced based on the configuration file will have the Template ID specified. This should not be used if multiple files are being produced.

  for example, <TemplateID>C:\Staging\Equipment_null.XML</TemplateID>

• Root "TemplateID" specified:

  The Template ID in the output file will be the full output file name with the string specified removed from its start.

  for example, <TemplateID Root="true">C:\</TemplateID>

  In this example, if the full output file name is "c:\Staging\Equipment_null.xml", then the output would be "Staging\Equipment_null.xml".

• No "TemplateID" specified.

  If no "TemplateID" is specified then the full file name (incl. path) of the output file will be used for the Template ID.

  "TemplateID" supports following Attribute:

Root

As mentioned in the example above, this attribute is used to remove the specified path from the start of the full output file path.

OutputFile

AVEVA Schematic Gateway will generate an XML output in EIWM format that can be imported into AVEVA Asset Information Management using AVEVA AIM Import Controller. Although the output for the entire DataSet can be generated into a single EIWM file, sometimes its desirable to split the output into multiple EIWM files to facilitate easy import of data into AVEVA AIM. This is because AVEVA AIM can handle small EIWM files more effectively as compared to large EIWM files. "OutputFile" is a mandatory element.

"OutputFile" element supports following attributes:

File

This attribute allows user to specify the name of the Output File. It's a mandatory attribute.

for example,. <OutputFile File="Equipment_null.XML"/>

DeleteExisting

"DeleteExisting" can have "true" and "false" as valid values. Setting "DeleteExisting" to "true" deletes all the contents of the staging area before proceeding with execution of the export functionality of the Gateway. This is an optional attribute and default value of this attribute would be "false".

"OutputFile" can have following sub-elements:

Directory

In order to break the output into multiple EIWM files, an element "Directory" can be used. This is an optional element, but if used, it can occur many times under "OutputFile" element.

for example, <Directory>AreaNo</Directory>

In above example, a sub-directory for each AreaNo will be created under Staging Area ("AreaNo" would be the exact column name in the DataSet) and each sub-directory would contain EIWM file/s corresponding to the specific AreaNo.

<Directory>AreaNo</Directory>

<Directory>TagNo</Directory>

Above example will result into sub-directory under Staging Area for each unique AreaNo and then further sub-directories under each "AreaNo" specific directory per "TagNo" (again "AreaNo" and "TagNo" should be the exact column names in the DataSet).

"Directory" element supports following attributes:

SearchExpression

This attribute allows user to provide an expression to generate the name of the directory. This is an optional attribute.

for example, <Directory SearchExpression="substring(TagNo, 1, 4)"/>

Above example will result into sub-directories with unique strings of first 4 characters of the available "TagNo"s. ("TagNo" should be the exact column name in the DataSet).

KeepUnmappedAttributes

This element defines how to handle attributes of the entity not defined in Attributes Mapping configuration. This element can have "true" and "false" as valid values. If it is set to "true", then all unmapped attributes of the entity will be exported as characteristics. This is an optional element and its default value will be "false" if not defined explicitly.

for example, <KeepUnmappedAttributes>true</KeepUnmappedAttributes>

Mapping

The mapping section is where configuration gets down to mapping rows/nodes from the DataSet to AVEVA AIM objects. Each configuration file can have one or more mapping sections but most of the cases, there would be need of at the most only one mapping section. In case of multiple mapping sections each mapping section will be applied to each entity (row or node) in the DataSet in turn.

Object mappings will create object instances for AVEVA AIM. The format of the mapping for the high level object data (identity, class…) will resemble:

<Mapping Type="Object" Condition="" UseIdForFileNames="false">

     <ID ApplyBehaviour="concat(ID, TagNo, ' Equipment')"/>

     <Context Value="PROJECTCONTEXT"/>

     <ClassID From="Description"/>

     <Name From="Description" Default="N/A" RegExPattern="[A-Z]{3}" RegExRemovePattern="\s"/>

</Mapping>

Various AVEVA AIM Properties that can be mapped here are:

• ID

• Context

• ClassID

• Name

All these properties can be specified under mapping section as separate elements. As mentioned above, these elements support following attributes:

Value

Hard coded string that will be used as the value of the property in the output.

ApplyBehaviour

Perform some processing on DataSet value(s) to determine the output. The setting for the ApplyBehaviour can be any XPath 1.0 functions.

From

DataSet column (or node) name from which value should be read.

Default

A default value that will be used if no value is found in the DataSet. If no value is found in the DataSet for a mapped property then that will not be included in the output file unless a default for it is defined - if no value to be written, specify default="".

RegExPattern

Specified regular expression pattern will be applied to the property value and the matched sub-string to the pattern will be the output value.

RegExRemovePattern

A regular expression pattern to identify part of the value to be removed. For example, this could be used to remove spaces or dashes from a value.

Note:
Out of "From", "Value" or "ApplyBehaviour" which define how the value for the property should be determined, one and only one of these three should be specified. In case user specifies more than one attributes out of these three, then preference will be given in following sequence > Value, ApplyBehaviour, From.

"Mapping" supports following attributes:

Type

The only supported type at the moment is "Object". Specifying Type="Object" will treat the element as an object in AVEVA AIM.

Condition

"Condition" helps to filter items in a DataSet or to treat items with some common property differently.

for example, . <Mapping Type="Object" Condition="Class='Junction Box' and Manufacturer!='ACME'">

In this case the mapping will only be applied (and therefore output data generated for) to those items where the 'Class' column does and 'Manufacturer' column does not match the values listed. Any number of and/or statements can be combined to provide the desired logic (use lower case for 'and' and 'or').

UseIdForFileNames

This element has "true" and "false" as valid values. If the user chooses to generate multiple output files - one per object, then setting this attribute to "true" will generate the names of these output files by appending the Id at the beginning of the file name specified in "OutputFile" element.

Association

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. This is an optional element.

Association supports following sub-elements:

TargetClassID: This element specifies the Class ID of the target object with which the object has the association.

TargetContext: This element specifies the namespace of the target object.

TargetClassID: This element specifies the Class ID of the target object with which the object has the association.

TargetContext: This element specifies the namespace of the target object.

TargetName: This element specifies the name assigned to the target object.

All these sub-elements support "From", "Value" and "ApplyBehaviour" attributes, but at a time one and only one out of these three should be specified. Usage of these attributes will be exactly same as mentioned above in "Mapping" section.

"Association" supports following attribute:

Type

This attribute specifies the type of relationship between the object and the target object. The relationship mentioned here should be supported by AVEVA AIM. For example:

<Association Type="is classified as">

    <TargetID From="TagNo"/>

    <TargetRevision Value="1.2"/>

    <TargetClassID From="Description"/>

    <TargetContext Value="NewNamespace"/>

    <TargetName Value="Equipment"/>

</Association>

InputFiles

This element gives information about how to process the input files of different types (e.g. xls, xlsx, pdf). "InputFiles" is not mandatory and can be ignored if there are no input files to be processed.

AVEVA Schematic Gateway accepts "input file location" as well as list of files to be processed as an input. When no input file names are provided to the Gateway, it will process all the files present in the Input location.

"InputFiles" support following attribute:

IncludeSubFolders: If IncludeSubFolder is set as "true", Gateway will search the subfolders of the Input location too. This attribute will carry no meaning if list of files to be processed is provided to the Gateway.

InputFiles support following sub-elements:

Files

This Element provides the gateway, information about the different types of file extensions that are processed by it, for example:

<Files>

    <Extension>xlsx</Extension>

    <ExcelAddHotspotting>true</ExcelAddHotspotting>

    <ExcelRanges>true</ExcelRanges>

    <TagsNamedRange>VNETTags,TagNo</TagsNamedRange>

</Files>

Files will support following sub-elements:

Extension

This specifies the extension of the files unique to the current "Files" element for which rest of the elements in the "Files" block are applicable to. Valid values are: xls, xlsx, pdf.

for example, <Extension>xls</Extension>

ExcelRanges

This element has "true" and "false" as valid values. If this is set to "true", the gateway will hotspot the output file with the specified ranges in the excel spreadsheet. This element works in conjunction with "TagsNamedRange" and only the ranges specified in "TagsNamedRange" will be hot-spotted.

If this element is "false", then the Gateway will hotspot the values which match the search patterns mentioned in RegularExpression.

This element will be ignored if "ExcelAddHotspotting" is set to "false". Moreover this element is applicable only if "Extension specified is either "xls" or "xlsx". For other extensions this element will be ignored. Default value of this element, if not set, will be "false".

ExcelAddHotspotting

If this is set to "true", then hot-spotting would be performed on the output MHTML file. This element is optional and is expected to be set only if "extension" is "xls" or "xlsx". Default value of this element, if not set, will be "false".

TagsNamedRange

If "ExcelRanges" is set to "true", then the gateway will hot-spot the Ranges mentioned in this element.

for example, <TagsNamedRange>VNETTags,TagNo</TagsNamedRange>

This element is optional and is expected to be set only if "extension" is "xls" or "xlsx". Default value of this element, if not set, will be "". Multiple ranges can be specified as a comma separated string.

RegularExpression

If "ExcelRanges" element is set to "false", the Gateway would choose the Regular expression search patterns for hot-spotting. This element is optional.

RegularExpression supports following sub-elements:

Search

The regular expressions specified in this element would be matched to the text in the input file and the cell containing the matching text would be hot-spotted.

for example, <Search>[A-Z]{3}</Search>

If the above search pattern is provided in the Project Configuration and if the datasheet has a cell with value "ABCD123", then that cell would be hot-spotted.

RegularExpression

Can have as many "Search" expressions as want but there has to be at least one "Search" element under it.