Mapping file basics

Mapping files are XML documents that define how Infor Public Sector Data Management is to be import and export data. Data is imported and exported as XML, so there are two XML documents involved in each import or export: the data file and the mapping file.

In XML, a single record is represented by an element with one or more children and attributes. In Infor Public Sector, a single record is represented by a business object with one or more properties. The purpose of the mapping file is to identify which business object or property corresponds to each element or attribute in the XML so that data can be imported or exported.

The sample below shows how a vehicle record might be represented as a <VEHICLE> element in a simple data import file. There are three pieces of data associated with the vehicle: the vehicle ID, represented by the ID attribute; the description, represented by the <Description> element; and the vehicle type code, represented by the <VehicleType> element.

<VEHICLE ID="MyCar">
   <Description>The Description of my car</Description>
   <VehicleType>CAR</VehicleType>
</VEHICLE>

In Infor Public Sector, vehicles are represented by the Hansen.AssetManagement.Fleet.Vehicle business object. The vehicle ID property is called ID, the description property is called UnitDesc, and the vehicle type property is called UnitType. The Vehicle object in turn corresponds to the COMPVEH table in the database, and the three properties correspond to the UNITID, UNITDESC, and UNITTYPE columns.

To import the vehicle record, the mapping file must first identify a specific element in the XML. This is not necessarily the root element of the XML document itself, although it often will be.

In the import mapping file, the RootQuery attribute of the <Steps> element uses an XPath query to identify an XML element, as shown in this example:

<Steps RootQuery="/VEHICLE">
</Steps>

Next, the <VEHICLE> element is mapped to the Vehicle business object. The <Steps> element has one or more <Step> elements as children. The business object is identified by the TargetBusinessObject attribute of the <Step>, as shown below.

<Steps RootQuery="/VEHICLE">
   <Step Id="1" 
    TargetBusinessObject="Hansen.AssetManagement.Fleet.Vehicle" 
    Action="Create">
   </Step>
</Steps>

Finally, the ID attribute and the <Description> and <VehicleType> elements are mapped to their respective properties. Each piece of data is represented by a <Map> element. The Source attribute identifies the data source in the XML document, which can be an element, an attribute, or an element’s inner text. To specify an attribute as the source, use an @ symbol.

The Target attribute identifies the corresponding property of the target business object.

<Steps RootQuery="/VEHICLE">
   <Step Id="1" 
    TargetBusinessObject="Hansen.AssetManagement.Fleet.Vehicle" 
    Action="Create">
      <Mappings>
         <Map Source="@ID" Target="ID"/>
         <Map Source="Description" Target="UnitDesc"/>
         <Map Source="VehicleType" Target="UnitType"/>
      </Mappings>
   </Step>
</Steps>

The full mapping file is shown below. The <Steps> element is a child of the root <DataImport> element. The <Information> element stores tracking information about the mapping file.

<?xml version="1.0" encoding="utf-8" ?>
<DataImport Name="DataImportVehicle">
   <Information>
      <Version>1.0.0</Version>
      <ChangeBy>Test User</ChangeBy>
      <ChangeDate>2017-10-30</ChangeDate>
   </Information>
   <Steps RootQuery="/VEHICLE">
      <Step Id="1" 
       TargetBusinessObject="Hansen.AssetManagement.Fleet.Vehicle" 
       Action="Create">
         <Mappings>
            <Map Source="@ID" Target="ID"/>
            <Map Source="Description" Target="UnitDesc"/>
            <Map Source="VehicleType" Target="UnitType"/>
         </Mappings>
      </Step>
   </Steps>
</DataImport>

An export mapping file follows the same basic process in reverse. The business object to be exported is identified by the TargetBusinessObject attribute of the root <DataExport> element. The RootElement attribute defines the root element for the XML output.

<DataExport Name="Vehicle" 
 TargetBusinessObject="Hansen.AssetManagement.Fleet.Vehicle" 
 RootElement="VEHICLE">
</DataExport>

The <DataMap> elements are similar to the <Map> elements in the import mapping file, but in this case the Source attribute identifies the business object property to be exported, and the Target attribute identifies the XML element or attribute that will hold that value.

<DataExport Name="Vehicle" 
 TargetBusinessObject="Hansen.AssetManagement.Fleet.Vehicle" 
 RootElement="VEHICLE">
   <Steps>
      <Step Id="1">
         <DataMappings>
            <DataMap Source="ID" Target="@ID" />
            <DataMap Source="UnitDesc" Target="Description" />
            <DataMap Source="UnitType" Target="VehicleType" />
         </DataMappings>
      </Step>
   </Steps>
</DataExport>

So the example above instructs the export processor to create a VEHICLE element in the XML output, and to add an ID attribute and two child elements: <Description> and <VehicleType>. The output would thus be the same as the sample input that was shown previously.

<VEHICLE ID="MyCar">
   <Description>The Description of my car</Description>
   <VehicleType>CAR</VehicleType>
</VEHICLE>