Elements and Attributes

ConfigurationSettings

This is the root element for all Project Configurations and contains the following sub-elements.

There is 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 element 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 files produced based on the configuration file will have the Template ID specified. This should not be used if multiple files are being produced.
  e.g <TemplateID>C:\Staging\Instruments_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.
  e.g. <TemplateID Root="true">C:\</TemplateID>
  In this example, if the full output file name is "C:\Staging\Instruments_null.xml", then the output would be "Staging\Instruments_null.xml".

• No TemplateID specified:
  If no TemplateID is specified, then the full file name (including the path) of the output file will be used for the Template ID.

The TemplateID element supports the following attributes:

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 AIM, using AVEVA AIM Import Controller. Although the output for the entire DataSet can be generated into a single EIWM file, sometimes it is 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.

The OutputFile element supports following attributes:

File: This attribute allows you to specify the name of the output file. It is a mandatory attribute.
e.g. <OutputFile File="Instruments_null.XML"/>

DeleteExisting: This element 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, a Directory element can be used. This is an optional element, but if used, it can occur many times under the OutputFile element.

e.g. <Directory>AreaNo</Directory>

In the 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 files corresponding to the specific AreaNo.

e.g. <Directory>AreaNo</Directory>

<Directory>TagNo</Directory>

The above example will result in a sub-directory under Staging Area for each unique AreaNo, and then further sub-directories under each AreaNo, specific directory per TagNo.

Note: AreaNo and TagNo should be the exact column names in the DataSet.

The Directory element supports the following attributes:

SearchExpression: This attribute allows you to provide an expression to generate the name of the directory. This is an optional attribute.
e.g. <Directory SearchExpression="substring(TagNo, 1, 4)"/>

The above example will result in sub-directories with unique strings of the first four characters of the available TagNo.

Note: 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.

e.g. <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, ' Instrument')"/>

     <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 of these properties can be specified under the mapping section as separate sub-elements. As mentioned above, these elements support the following attributes:

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

ApplyBehaviour: Performs some processing on DataSet values to determine the output. The setting for the ApplyBehaviour can be any XPath 1.0 functions.

From: DataSet column (or node) name from which the 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.
E.g. This could be used to remove spaces or dashes from a value.

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

Mapping supports the 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: Helps to filter items in a DataSet or to treat items with some common property differently.
e.g. <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 the '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 you choose 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 the 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 Association an object may have.

Association is an optional element.

Association supports the 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 of these sub-elements support From, Value and ApplyBehaviour attributes, but only one of these three should be specified. Usage of these attributes will be exactly the same as mentioned above in the Mapping section.

Association supports following attributes:

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="Instrument"/>

</Association>

InputFiles

This element gives us 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 attributes:

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

InputFiles supports 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 supports the following sub-elements:

Extension: This specifies the extension of the files unique to the current Files element for which the rest of the elements in the Files block are applicable to. Valid values are: xls, xlsx, pdf.
e.g. <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 hotspotted.
If this element is false, then the Gateway will hotspot the values which match the search patterns mentioned in the section about the RegularExpression element.
This element will be ignored if ExcelAddHotspotting is set to false.
Moreover, this element is applicable only if the Extension specified is either xls or xlsx. For other extensions, this element will be ignored. The default value of this element (if not set) will be false.

ExcelAddHotspotting: If this is set to true, then hotspotting would be performed on the output MHTML file. This element is optional and is expected to be set only if the Extension is xls or xlsx.
The default value of this element (if not set) will be false.

TagsNamedRange: If the ExcelRanges element is set to true, then the Gateway will hotspot the Ranges mentioned in this element.
e.g., <TagsNamedRange>VNETTags,TagNo</TagsNamedRange>
This element is optional and is expected to be set only if the Extension is xls or xlsx.
The default value of this element (if not set), will be "". Multiple ranges can be specified as a comma separated string.

RegularExpression

If the ExcelRanges element is set to false, the Gateway would choose the regular expression search patterns for hotspotting. This element is optional.

RegularExpression supports the following sub-elements:

Search: The regular expressions specified in this element will be matched to the text in the input file, and the cell containing the matching text will be hotspotted.
e.g., <Search>[A-Z]{3}</Search>
If the above search pattern is provided in the Project Configuration, and if the datasheet has a cell with the value "ABCD123", then that cell will be hotspotted.

RegularExpression can have as many Search expressions as necessary, but there has to be at least one Search element under it.