The mapping document

The XML mapping document specifies the mapping between CSV fields and output attributes. The operator validates the XML mapping document against the etc/xsd/CSVParseMapping.xsd XML schema definition (XSD) file in the toolkit directory. This XSD file contains reference documentation for the XML mapping document, which is located, by default, in the SPL application directory. The root element in the XML document is mappings. It can have an arbitrary number of mapping element children. The mappings element can have one attribute named useDefaults. This attribute can also be applied to the mapping element. If set on the mappings element, it is applied to all mapping elements. The attribute is described in the next section.

Mapping Element

A mapping specifies the assignment of CSV items from the input to SPL attributes in the output. A mapping should be defined for each CSV line format. Each mapping has a unique name and can define a filter that is matched against a CSV input line to determine if a mapping applies to that line. The content of the mapping can be an automatic or manual assignment specification. As shown in the example above, the mapping element can have 6 attributes:

  • name

    A unique name for the mapping. The name is also used for the record statistics custom output functions.

  • filterIndex

    The CSV field at this index that is used for comparison. If you do not specify a value for this attribute and the filterValue attribute is present, the index defaults to zero.

  • filterValue

    The string that is compared against the specified CSV field in the input line. If the value matches, this mapping is applied to the CSV line. If the filterIndex attribute is present, this attribute is mandatory.

  • itemCountMin

    If this attribute is specified and the mapping applies to a given CSV line, the number of fields in the CSV line is checked against this value. If the line has less than the specified number of items, this is treated as an error.

  • itemCountMax

    If this attribute is present and the mapping applies to a given CSV line, the number of fields in the CSV line is checked against this value. If the line has more than the specified number of items, an error occurs.

  • useDefaults

    If this attribute is set to true all empty CSV fields (strings of length zero) that shall be mapped to SPL numeric attributes (integers and floats), will be set to zero. If the attribute is set to false, the operator will instead produce an error record, because the conversion is treated as failed. This applies to all attributes in the current mapping. If this attribute is also set in the mappings element, the setting in the mapping element takes precedence. The default value for this attribute is false.

Manual Assignment

A manual assignment consists of a list of assignments. For each assignment, you can specify the index in the CSV item list and the target SPL attribute name. With a manual assignment, you can only use the assign element within a mapping element. The assign element has two optional attributes:

  • index

    The index of the CSV field in the input line (starts with zero). If this attribute is omitted, the index of the preceding assignment is incremented. So the next CSV field is picked up.

  • attribute

    The name of the SPL output attribute to which to assign the value. If this attribute is omitted, the next unassigned output attribute is used.

Consequently, the color mapping from Example 1 can also be written as: 


<mapping name="colors">
  <assign attribute="R" index="2"/>
  <assign/>
  <assign/>
</mapping>

In this case, the two assign elements that do not have attributes select the G and B SPL attributes because they are the next in the output port schema and are assigned CSV fields 3 and 4 because the first assign element starts with index 2.

Automatic Assignment

An automatic assignment can consist of a list of included or excluded SPL attribute names. Included attributes participate in the mapping, while excluded ones do not. Included and excluded attributes cannot be mixed. The automatic assignment can be empty, meaning that all attributes participate in the mapping. In the following example, the mapping tries to assign the following attributes from example 1: R with CSV field 0, G with CSV field 1 and B with CSV field 2: 


<mapping name="colors">
  <auto/>
</mapping>

The next two mappings try to assign the following attributes from example 1: R with CSV field 0 and B with CSV field 1: 


<mapping name="colors">
  <auto>
    <include>R</include>
    <include>B</include>
  <auto>
</mapping>

<mapping name="colors">
  <auto>
    <exclude>G</exclude>
  <auto>
</mapping>