Mapping Operators

A property of an object in the CIM may be a function of many attributes of many related objects the GIS model. The transformation of the GIS model to the CIM employs operators to compute these functions and may combine results of these operators in functional expressions. This section describes mapping operators provided with Network Adapter.

Note that a mapping operator can be implemented with attributes to the CIMProperty operator to reduce the number of lines in the mapping XML. In this case, the mapping operator is defined with the “rule” attribute. In the following example, the Scale operator is applied to the value of RatedKva with a scale value of 1000.

<cimProperty name="cim:TransformerWinding.ratedS" rule="Scale" scale="1000">
    <sourceField name="RatedKva" useDomain="false" />
</cimProperty>

More information about the Scale operator is provided below.

Common Mapping Attributes

The following are common attributes shared by multiple mapping operators.

useDomain: In an ArcGIS data source, the value of a field may have a related value through a coded value domain. If a field has a coded value domain, the value of the field corresponds to a description recorded elsewhere. By default, the sourceField operator returns this description rather than the value itself; however, the configuration can specify using the value of the field itself with the useDomain attribute.

In the following example, the configuration exports the numeric value for RatedKva to TransformerWinding.ratedS, rather than using the description of the domain value.

 <cimProperty name="cim:TransformerWinding.ratedS">
  <sourceField name="RatedKva" useDomain="false" />
 </cimProperty>

Boolean Operators

Boolean operators yield a Boolean value (either true or false). These operators often appear in expressions governing optional transformations in the mapping configuration (see Optional Mapping). Boolean operators can also yield CIM property values where a property has a Boolean valued.

SourceIs: SourceIs returns true if the source of a mapping operation belongs to a specified class in the data source.
In this example, The first operator under an <option> tag is a SourceIs, yielding a boolean value. If this operator returns true, the constant operator generates the property value. Otherwise, the constant operator within the <default> tag generates the property value.
```
  <cimProperty name="tdms:Equipment.isUnderground">
   <option>
    <SourceIs class="PriUGElectricLineSegment" />
    <constant value="true" />
   </option>
   <default>
    <constant value="false" />
   </default>
  </cimProperty>
```
HasRelatedObjects: HasRelatedObjects returns true if the source of a mapping operation has related objects in a specified class in the data source.
The following example illustrates the mapping of an optional property of a Breaker object in the CIM. The export generates an isFeederHead property on a Breaker object only if the corresponding DynamicProtectiveDevice feature in the GIS has a related CircuitSource object in the GIS. If the export generates this property, the value of the property is always true.
```
  <cimProperty name="tdms:Breaker.isFeederHead">
   <option>
    <HasRelatedObjects relatedClass="CIRCUITSOURCE" atLeast="1" />
    <constant value="true" />
   </option>
  </cimProperty>
```
And: The And operator returns true if all of its arguments in a mapping operator expression return true; otherwise, it returns false.
In the following example, the transformation sets the Fuse.cutout property to true only if the source object in the GIS is a Fuse and the subtype of the fuse in the GIS is Fused Cutout.
```
  <cimProperty name="cim:Fuse.cutout">
   <option>
    <And>
     <SourceIs class="Fuse" />
     <Equals value="Fused Cutout">
      <sourceField name="SUBTYPECD" />
     </Equals>
    </And>
    <constant value="true" />
   </option>
```

Or: The Or operator returns false if all of its arguments in a mapping operator expression return false; otherwise, it returns true.
In the following example, the transformation generates a Fuse object in the CIM only if the source object in the GIS is a Fuse or the source is a DynamicProtectiveDevice with the Station Fuse subtype.

 <cimClass name="cim:Fuse" primarySource="Fuse,DynamicProtectiveDevice">
 
  <optional>
   <Or>
    <SourceIs class="Fuse" />
    <And>
     <SourceIs class="DynamicProtectiveDevice" />
     <Equals value="Station Fuse">
      <sourceField name="SUBTYPECD" />
     </Equals>
    </And>
   </Or>
  </optional>

Not: The Not operator returns true if its arguments in a mapping operator expression return false; otherwise, it returns false.
In the following example, the transformation populates IdentifiedObject.name in the CIM with FacilityID only if the source object in the GIS is not a BusBar.
```
  <cimProperty name="tdms:IdentifiedObject.name">
   <option>
    <Not>
     <SourceIs class="BusBar" />
    </Not>
    <sourceField name="FacilityID" default="FacilityID is Null" />
   </option>
  </cimProperty>
```
Equals: Equals returns true if the value of its argument equals the value specified in the xml attribute value; otherwise, the operator returns false. See examples in the sections above.
Equals may also take two arguments in a mapping operator expression. In this case, the operator must not contain the value attribute, and the operator returns true if the values of the two arguments are equal.
NotEquals: NotEquals returns true if the value of its argument does not equal the value specified in the xml attribute value; otherwise, the operator returns false. In the following example, the transformation populates Switch.BreakingCurrent in the CIM with MaxInterruptingCurrent only if the source object is subtype is not a Circuit Breaker.
```
  <cimProperty name="tdms:Switch.breakingCurrent">
   <option>
    <NotEquals value="Circuit Breaker">
     <sourceField name="SUBTYPECD" />
    </NotEquals>
    <sourceField name="MaxInterruptingCurrent" default="200" /> 
</option>
  </cimProperty>
```
NotEquals may also take two arguments in a mapping operator expression. In this case, the operator must not contain the value attribute, and the operator returns true if the values of the two arguments are not equal.

GreaterThan: GreaterThan returns true if the value of its argument is greater than the value specified in the xml attribute value; otherwise, the operator returns false.
In the following example, the transformation generates a CompositeSwitch object in the CIM only if the source Fuse or Switch in the GIS has a PhaseDesignation value with length greater than 1 (that is, it is multi-phase)

 <cimClass name="cim:CompositeSwitch" primarySource="Fuse,OpenPoint">
 
  <optional>
   <GreaterThan value="1">
    <StringLength>
     <sourceField name="PhaseDesignation" />
    </StringLength>
   </GreaterThan>
  </optional>

GreaterThan may also take two arguments in a mapping operator expression. In this case, the operator must not contain the value attribute, and the operator returns true if the first value is greater than the second.

In either case, the operator converts its arguments to string values and performs a string comparison. This conversion can have unexpected results if arguments are numeric. For example, ’9’ > ’1’ is true, but ’9’ > ’10’ is also true.

Artihmetic Operators

Arithmetic operators permit the CIM transformation to derive a CIM property from many properties of many related objects in the data source using simple arithmetic expressions.

Multiply: The Multiply operator returns the product of its arguments in a mapping operator expression. The operator requires two or more arguments.
The following example computes the peakCurrent property of a Switch object in the CIM by multiplying the value for the MaxContinuousCurrent in the GIS by 2.56.
```
  <cimProperty name="cim:Switch.peakCurrent">
   <Multiply>
    <sourceField name="MaxContinuousCurrent" default="200" />
    <constant value="2.56" />
   </Multiply>
  </cimProperty>
```
Divide: The Divide operator returns the result of dividing its first argument in a mapping operator expression by its second argument. The operator requires two or more arguments.
In the following example, the transformation calculates the rated current of a generator by dividing its rated power (in watts) by its nominal voltage in volts.
```
  <cimProperty name="cim:AsynchronousMachine.ratedCurrent">
   <Divide>
    <Scale scale="1000">
     <sourceField name="KW" />
    </Scale>
    <ToVolts>
     <sourceField name="NominalVoltage" />
    </ToVolts>
   </Divide>
  </cimProperty>
```
Scale: The Scale operator multiplies its argument in a mapping operator expression by the value specified in an xml scale argument. The operator may also add the value of a xml offset argument to the result.
The previous section presents an example of the Scale operator.

String Operators

String operators permit the CIM transformation to derive a CIM property from many properties of many related objects in the data source using simple string expressions.

Concatenate: The Concatenate operator concatenates two or more strings. It separates the concatenated strings with the value of an xml separator attribute. If no separator attribute is present, a colon (’:’) separates the strings. If an argument in the mapping expression is not string-valued, Concatenate converts it to a string.
The following example concatenates the value of the LinkRating and MaxContinuousCurrent fields of a Fuse in the GIS feature to generate the ratingCurrent property in the CIM.
```
  <cimProperty name="cim:Fuse.ratingCurrent">
   <Concatenate>
    <sourceField name="LinkRating" />
    <sourceField name="MaxContinuousCurrent"/>
   </Concatenate>
```
Concatenate is the default operator in cimProperty tags. That is, if multiple arguments are listed for a cimProperty tag, but no operator is included, the transformation will concatenate the arguments.
Characters: Most of the operators described in this document return a single value; however, a mapping operator may return many values (a vector of values). Vector-valued operators are useful when mapping the data source model to the CIM requires refactoring. See the Refactoring section for more information about this advanced mapping option.
The Characters operator accepts a single string and returns a vector of characters in the string.
In the following example, the Characters operator returns a vector of the separate phases in the PhaseDesignation value. The transformation creates multiple Fuse objects in the CIM, one for each single-character phase value.
```
 <cimClass name="cim:Fuse" primarySource="Fuse">
  <cimProperty name="cim:ConductingEquipment.phases">
   <Characters>
    <sourceField name="PhaseDesignation" />
   </Characters>
  </cimProperty>
```
String Length: StringLength returns the length of its single, string-valued argument.
The following example calculates the number of phases carried by conducting equipment by counting the characters in the phase designation.
```
  <cimProperty name="tdms:ConductingEquipment.numberOfPhases">
   <StringLength>
    <sourceField name="Switch.PhaseDesignation" />
   </StringLength>
  </cimProperty>
```
PadString: The PadString operator extends the length of its string-valued argument by appending characters to the beginning or the end of the string.
In the following example, the transformation appends ’0’ characters to the beginning of the value of the FacilityID field in a data source feature. It appends characters until the length of the resulting string reaches five.
PadString may specify either a prefix or a postfix argument but not both.
```
  <cimProperty name="cim:IdentifiedObject.description" separator="">
   <sourceField name="OperatingCentreShortName" default="OperatingCentreShortName is Missing" />
   <PadString prefix="0" length="5">
    <sourceField name="FACILITYID" default="FacilityID is Null" />
   </PadString>
  </cimProperty>
```
Note here that Concatenate is the default operator for cimProperty tags. The separator attribute overrides the operator’s default separator (’:’), so the value of this property is the short form of an operating centre name followed by a facility id padded with preceding zeros to five characters in length.

Other Operators

The following operators support common mapping requirements.

Constant: Constant enables the mapping to include a literal string. For example, the following statement will result in a CIM mRID value made up of the text "Node" plus the unique identifier for the object in GIS.
```
   <cimProperty name="cim:IdentifiedObject.mRID">
    <constant value="Node" />
    <sourceField name="NAUNIQUEID" />
   </cimProperty>
```
NumberOfRelatedObjects: NumberOfRelatedObjects returns the number of related objects to the source of a mapping operation in the data source, for a specified related class.
The following example populates the EnergyConsumer.customerCount property with the number of related service points below a transformer that have a unique value for the ConsumptionType field (such as residential).
```
 <cimProperty name="cim:EnergyConsumer.customerCount">
  <NumberOfRelatedObjects relatedClass="SecondaryConnected*.ServicePoint" uniqueValuesOf="ConsumptionType" />
</cimProperty>
```
The text "SecondaryConnected*" instructs the transformation to trace secondary conductors below the transformer to find the service points.
SumRelatedValues: SumRelatedObjects returns the sum of values for a field within related objects to the source of a mapping operation in the data source.
The following example populates the EnergyConsumer.pfixed property with the sum of KW values for related CustomerInfo objects, for unique values of ServicePoint.ConsumptionType field (such as residential).
```
 <cimProperty name="cim:EnergyConsumer.pfixed">
  <SumRelatedValues relatedField="ServiceAddress.CustomerInfo.KW" uniqueValuesOf="SecondaryConnected*.ServicePoint.ConsumptionType"/>
 </cimProperty>
```

Lookup: The Lookup operator retrieves values from a catalog table based upon the value of fields in a data source object and related objects. Lookup does not require a data source relationship between the source object classes and the catalog table.
The following example finds a row of the MMENG_CONDUCTOR_ELEC table where the four key field match the argument list. The operator returns the value of the R_PER1000_UNITS_LENGTH field from the row.

<cimProperty name="cim:ACLineSegment.r">
 <Lookup tableName="MMENG_CONDUCTOR_ELEC" keyField="UNDERGROUND,MATERIAL,CONDSIZE,INSULATION" valueField="R_PER1000_UNITS_LENGTH" optional="true">
  <constant value="0" />
  <sourceField name="ConductorInfo.CONDUCTORMATERIAL" useDomain="false" useAny="true" />
  <FixCondSize>
   <sourceField name="ConductorInfo.CONDUCTORSIZE" useDomain="false" useAny="true" />
  </FixCondSize>
  <constant value="" />
 </Lookup>
</cimProperty>

Map: The Map operator returns the value from a property value map defined in the mapping configuration file corresponding to the value of its argument.
The following example converts a LowSideVoltage value in the GIS to a format expected by the ratedVoltage property.
```
  <cimProperty name="tdms:ConductingEquipment.ratedVoltage">
   <Map mapRef="Voltage">
    <sourceField name="LowSideVoltage" useDomain="false"/>
   </Map>
  </cimProperty>
```

ArcFM Operators

The following specialized operators aid transformation to the CIM from an ArcFM source.

ToVolts: The ToVolts operator accepts a string of the form

###[/###] Volts|kV

and returns a numeric value. ### represents a number. [/###] represents an optional second number preceded by ’/’. Either ’Volts’ or ’kV’ follows the numeric part of the string.
If the second number exists, the operator returns this value; otherwise, it returns the single value. In either case, if ’kV’ follows the numeric part, the operator returns the value multipled by 1000.
```
  <cimProperty name="tdms:ConductingEquipment.ratedVoltage">
   <ToVolts>
    <sourceField name="OperatingVoltage" />
   </ToVolts>
  </cimProperty>
```
NormalOpens: Most of the operators described in this document return a single value; however, a mapping operator may return many values (a vector of values). Vector-valued operators are useful when mapping the data source model to the CIM requires refactoring. See the Refactoring section for more information about this advanced mapping option.
The NormalOpens operator returns the value of one or more NORMALPOSITION fields in a network feature depending upon the value of the PHASEDESIGNATION field. The first argument must be an integer value between 0 and 7, and three other arguments must follow.
The operator returns boolean values corresponding to one or more of the three NORMALPOSITION arguments based upon the value of the first. If the value of the first argument is 1 (A phase), the operator returns only the value of NORMALPOSITION_B. If the value of the first argument is 7 (ABC phase), the operator returns all three NORMALPOSITION values.
```
  <cimProperty name="cim:Switch.normalOpen" tagReference="OptionalNormalOpens">
   <NormalOpens>
    <sourceField name="PHASEDESIGNATION" useDomain="false" />
    <sourceField name="NORMALPOSITION_A" />
    <sourceField name="NORMALPOSITION_B" />
    <sourceField name="NORMALPOSITION_C" />
   </NormalOpens>
  </cimProperty>
```

Value Mapping

The Map operator returns the value from a property value map defined in the mapping configuration file corresponding to the value of its argument. This section describes the configuration of value maps.

The Maps section of the configuration file lists all value maps available to the Map operator during the transformation to CIM. For example, the NumberOfPhases identifies the number of phases associated with each value for phase designation.

  <Map tagReference="NumberOfPhases">
   <map domain="1" range="1"/>
   <map domain="2" range="1"/>
   <map domain="3" range="2"/>
   <map domain="4" range="1"/>
   <map domain="5" range="2"/>
   <map domain="6" range="2"/>
   <map domain="7" range="3"/>
   <default range="3" />
  </Map>

If the Map operator finds no value in the domain of a map corresponding to the value of its argument, the operator returns the default value. If no default value exists, the Map operator returns the value of its argument and reports an error.