Available in Community Designer

Mapping is defined in the Mapping URL or Mapping attribute.

Every Mapping definition consists of a pair of the start and the end <Mappings> tags. The <Mappings> tag has no attributes. This pair of <Mappings> tags surrounds all of the nested <Mapping> and <TypeOverride> tags.

Each of <Mapping> tags contains some XMLExtract Mapping Tag Attributes. See also XMLExtract Type Override Tags or XMLExtract Mapping Tags for more information.

XMLExtract Field Mapping Tags

Field Mapping tags allows to map fields from an input record to an output record of parent Mapping element.

Example:

<FieldMapping inputField="sessionID" outputField="sessionID" />

• inputField

  Required

  Specifies a field from an input record, that should be mapped to an output record.

  inputField="fieldName"

• outputField

  Required

  Specifies a field to which a value from the input field should be stored.

  outputField="fieldName"

Nested structure of <Mapping> tags copies the nested structure of XML elements in input XML files. See example below.

Example 48.7. From XML Structure to Mapping Structure

• If XML Structure Looks Like This:

  <[prefix:]nameOfElement>
      <[prefix1:]nameOfElement1>ValueOfTheElement11</[prefix1:]nameOfElement1>
      ...                
      <[prefixK:]nameOfElementM>ValueOfTheElementKM</[prefixK:]nameOfElementM>
      <[prefixL:]nameOfElementN>
          <[prefixA:]nameOfElementE>ValueOfTheElementAE</[prefixA:]nameOfElementE>
          ...                
          <[prefixR:]nameOfElementG>ValueOfTheElementRG</[prefixR:]nameOfElementG>
      </[prefixK:]nameOfElementN>
  </[prefix:]nameOfElement>

• Mapping Can Look Like This:

  <Mappings>
      <Mapping element="[prefix:]nameOfElement" attributes>
          <Mapping element="[prefix1:]nameOfElement1" attributes11/>
          ...                
          <Mapping element="[prefixK:]nameOfElementM" attributesKM/>
          <Mapping element="[prefixL:]nameOfElementN" attributesLN>
              <Mapping element="[prefixA:]nameOfElementE" attributesAE/>
              ...                
              <Mapping element="[prefixR:]nameOfElementG" attributesRG/>
          </Mapping>
      </Mapping>
  </Mappings>

However, Mapping does not need to copy all of the XML structure, it can start at the specified level inside the XML file. In addition, if the default setting of the Use nested nodes attribute is used (true), it also allows mapping of deeper nodes without needing to create separate child <Mapping> tags for them).

	Important
	Remember that mapping of nested nodes is possible only if their names are unique within their parent and confusion is not possible.

XMLExtract Mapping Editor lets you define mapping by drag and drop.

To be able to specify mapping you need XSD schema. The path to schema is set in the XML Schema attribute. If you do not have the schema, the component can generate it from the source file. If you have neither the schema nor a source file, you can still specify the mapping using source tab.

When using an XSD, the mapping can be performed visually in the Mapping dialog. The dialog consists of two tabs: the Mapping tab and the Source tab. The Mapping attribute can be defined in the Source tab, while in the Mapping tab you can work with your XML Schema.

	Note
	If you do not possess a valid XSD schema for your source XML, you can switch to the Mapping tab and click Generate XML Schema which attempts to "guess" the XSD structure from the XML.

Mapping Tab

Figure 48.20. The Mapping Dialog for XMLExtract

In the pane on the left hand side of the Mapping tab, you can see a tree structure of the XML. Every element shows how many occurrences it has in the source file (e.g. [0:n]). In this pane, you need to check the elements that should be mapped to the output ports.

At the top, you specify Output for each selected element by choosing from a drop-down list. Possible values are:

• Not mapped - the mapping will not produce a record. By using such mapping elements, you can enforce that any child mapping will be processed only if the parser encounters this element first.

• Parent record - the mapping will not produce a record, but it will fill the mapped values to a parent record.

• portNumber(metadata) - the mapping will generate a record and write it to a selected output port.

You can then choose from the list of metadata labeled portNumber(metadata), e.g. "3(customer)".

On the right hand side, you can see mapping Input and Output fields. You either map them to each other according to their names (by checking the Map XML by name checkbox) or you map them yourself - explicitly. Please note that in Input - XML fields, not only elements but also their parent elements are visible (as long as parents have some fields) and can be mapped. In the picture above, the "pref:records" element is selected but we are allowed to leap over its parent element "pref:result" whose field "size" is actually mapped. Consequently, that enables you to create the whole mapping in a much easier way than if you used the Parent key and Generated key properties.

You can also map the input fields (Input fields section), fields from record produced by parent mapping (Parent fields section) or generate a unique id for record by mapping a sequence from Sequences section to one of the output fields.

	Note
	sequenceId and sequenceField is set if some sequence is mapped to output metadata field. However it's possible to set just sequenceField. In this case new sequence is created and mapped to the metadata field. The mapping is valid but Mapping Dialog shows warning that metadata field is mapped to non existing sequence.

Source Tab

Once you define all elements, specify output ports, mapping and other properties, you can switch to the Source tab. The mapping code is displayed there. Its structure is the same as described in the preceding sections.

	Note
	If you do not possess a valid XSD schema for your source XML, you will not be able to map elements visually and you have to do it here in Source.

	Note
	It's possible to map attribute or element missing at the schema. No validation warning is raised and mapping is visualized at Mapping tab. Italic font is used when displaying mapped elements and attributes missing at the schema.

If you want to map an element to XML fields of its parents, use the "../" string (like in the file system) before the field name. Every "../" stands for "this element's parent", so "../../" would mean the element's parent's parent and so on. Examine the example below. The "../../empID" is a field of "employee" as made available to the currently selected element "customer".

Figure 48.21. Parent Elements

<Mapping element="employee">
 	<Mapping element="project">
 	 	<Mapping element="customer" outPort="0"
 	 	 	xmlFields="name;../../empID"
 	 	 	cloverFields="name;empId"/>
 	</Mapping>
</Mapping>
        

There's one thing that one should keep in mind when referencing parent elements particularly if you rely on the Use nested nodes property set to true: To reference one parent level using "../" actually means to reference that ancestor element (over more parents) in the XML which is defined in the direct parent <Mapping> of <Mapping> with the "../" parent reference.

An example is always a good thing so here it goes. Let us recall the mapping from last example. We will omit one of its <Mapping> elements and notice how also the parent field reference had to be changed accordingly.

<Mapping element="employee">
 	<Mapping element="customer" outPort="0"
 	 	xmlFields="name;../empID"
 	 	cloverFields="name;empId"/>
</Mapping>
        

It is possible to map the value of an element using the '.' dot syntax. The dot means 'the element itself' (its name). Every other occurrence of the element's name in mapping (as text, e.g. "customer") represents the element's subelement or attribute. (Note: Available since Clover v. 3.1.0)

The dot can be used in the xmlFields attribute just like any other XML element/attribute name. In the visual mapping editor, the dot is represented in the XML Fields tree as the element's contents.

The following chunk of code maps the value of element customer on metadata field customerValue. Next, project (i.e. customer's parent element, that is why ../.) is mapped on the projectValue field.

<Mapping element="project">
 	<Mapping element="customer" outPort="0"
 	 	xmlFields=".;../."
 	 	cloverFields="customerValue;projectValue"/>
</Mapping>
        

The element value consists of the text enclosed between the element's start and end tag only if it has no child elements. If the element has child element(s), then the element's value consists of the text between the element's start tag and the start tag of its first child element.

Important

Remember that element values are mapped to Clover fields by their names. Thus, the <customer> element mentioned above would be mapped to Clover field named customer automatically (implicit mapping). However, if you want to rename the <customer> element to a Clover field with another name (explicit mapping), the following construct is necessary: <Mapping ... xmlFields="customer" cloverFields="newFieldName" /> Moreover, when you have an XML file containing an element and an attribute of the same name: <customer customer="JohnSmithComp"> ... </customer> you can map both the element and the attribute value to two different fields: <Mapping element="customer" outPort="2" xmlFields=".;customer" cloverFields="customerElement;customerAttribute"/> </Mapping> Remember the explicit mapping (renaming fields) shown in the examples has a higher priority than the implicit mapping. The implicit mapping can be turned off by setting implicit attribute of the corresponding Mapping element to false.

You could even come across a more complex situation stemming from the example above - the element has an attribute and a subelement all of the same name. The only thing to do is add another mapping at the end of the construct. Notice you can optionally send the subelement to a different output port than its parent. The other option is to leave the mapping blank, but you have to handle the subelement somehow:

    
<Mapping element="customer" outPort="2"
 	xmlFields=".;customer"
 	cloverFields="customerElement;customerAttribute"/>
 	<Mapping element="customer" outPort="4" /> // customer's subelement called 'customer' as well
</Mapping>
    

It is possible to map content of element to field. Whole subtree of element is sent to output port in that case. To map element content, use '+' or '-' character. The difference between '+' (plus) and '-' (minus) mapping is, that '+' maps element's content and its enclosing element and '-' maps element's content, but not element itself.

If you have xml

    
 	<customers>
 	 	<customer>
 	 	 	<firstname>John</firstname>
 	 	 	<lastname>Smith</lastname>
 	 	 	<city>Smith</city>
 	 	</customer>
    </customers>
    

and you will use '+' mapping on element 'customer', you will get

    
 	<customer>
 	 	<firstname>John</firstname>
 	 	<lastname>Smith</lastname>
 	 	<city>Smith</city>
 	</customer>
    

on output.

If you will use '-' mapping on 'customer' element, you will get

    
 	 	<firstname>John</firstname>
 	 	<lastname>Smith</lastname>
 	 	<city>Smith</city>
    

on output.

	Important
	Mapping of element content can produce very large amount of data. It can have high impact on processing speed.

If you want to map a value from nested element, but you do not want to create a separate record for the parent and nested elements, you may consider using the useParentRecord attribute of the Mapping element. By setting the attribute to true, the values mapped by the Mapping element will not be assigned to a new record, but will be set to a parent record. (Note: Available since Clover v.3.3.0-M3)

The following chunk of code maps the value of element project on metadata field projectValue and value of customer element on metadata field customerValue. The customerValue field is set in the same record as the projectValue.

<Mapping element="project" outPort="0" xmlFields="." cloverFields="projectValue">
 	<Mapping element="customer" useParentRecord="true" xmlFields="." cloverFields="customerValue" />
</Mapping>
        

Source tab is the only place where templates can be used. Templates are useful when reading a lot of nested elements or recursive data in general.

A template consists of a declaration and a body. The body stretches from the declaration on (up to a potential template reference, see below) and can contain arbitrary mapping. The declaration is an element containing the templateId attribute. See example template declaration:

<Mapping element="category"  templateId="myTemplate">
 	<Mapping element="subCategory" 
 	 	xmlFields="name"
 	 	cloverFields="subCategoryName"/>
</Mapping> 		
		

To use a template, fill in the templateRef attribute with an existing templateId. Obviously, you have to declare a template first before referencing it. The effect of using a template is that the whole mapping starting with the declaration is copied to the place where the template reference appears. The advantage is obvious: every time you need to change a code that often repeats, you make the change on one place only - in the template. See a basic example of how to reference a template in your mapping:

<Mapping templateRef="myTemplate" />
		

Furthermore, a template reference can appear inside a template declaration. The reference should be placed as the last element of the declaration. If you reference the same template that is being declared, you will create a recursive template.

You should always keep in mind how the source XML looks like. Remember that if you have n levels of nested data you should set the nestedDepth attribute to n. Look at the example:

		
<Mapping element="myElement"  templateId="nestedTempl">

 	 	<!-- ... some mapping ... -->
		
 	<Mapping templateRef="nestedTempl" nestedDepth="3"/>
	
</Mapping> <!-- template declaration ends here --> 	
		

Note

The following chunk of code: <Mapping templateRef="unnestedTempl" nestedDepth="3" /> can be imagined as <Mapping templateRef="unnestedTempl"> <Mapping templateRef="unnestedTempl"> <Mapping templateRef="unnestedTempl"> </Mapping> </Mapping> </Mapping> and you can use both ways of nesting references. The latter one with three nested references can produce unexpected results when inside a template declaration, though. As we step deeper and deeper, each templateRef copies its template code. BUT when e.g. the 3rd reference is active, it has to copy the code of the two references above it first, then it copies its own code. That way the depth in the tree increases very quickly (exponentially). Luckily, to avoid confusion, you can always wrap the declaration with an element and use nested references outside the declaration. See the example below, where the "wrap" element is effectively used to separate the template from references. In that case, 3 references do refer to 3 levels of nested data. <Mapping element="wrap"> <Mapping element="realElement" templateId="unnestedTempl" <!-- ... some mapping ... --> </Mapping> <!-- template declaration ends here --> </Mapping> <!-- end of wrap --> <Mapping templateRef="unnestedTempl"> <Mapping templateRef="unnestedTempl"> <Mapping templateRef="unnestedTempl"> </Mapping> </Mapping> </Mapping>

In summary, working with nestedDepth instead of nested template references always grants transparent results. Its use is recommended.

If you supply an XML Schema which has a namespace, the namespace is automatically extracted to Namespace Bindings and given a Name. The Name does not have to exactly match the namespace prefix in the input schema, though, as it is only a denotation. You can edit it anytime in the Namespace Bindings attribute as shown below:

Figure 48.22. Editing Namespace Bindings in XMLExtract

After you open Mapping, namespace prefixes will appear before element and attribute names. If Name was left blank, you would see the namespace URI instead.

Note

If your XSD contains two or more namespaces, mapping elements to the output in the visual editor is not supported. You have to switch to the Source tab and handle namespaces yourself. Use the 'Add' button in Namespace Bindings to pre-prepare a namespace. You will then use it in the source code like this: Name = myNs Value = http://www.w3c.org/foo lets you write myNs:element1 instead of {http://www.w3c.org/foo}element1

Sometimes the schema defines an element to be of some generic type, but you know, what the actual specific type of the element will be in the processed XML. If the subtypes of the generic type are also defined in the schema, you may use the Select subtype action. This will open a dialog as shown below. When you choose a subtype, the element in the schema tree will be treated as if it was of the selected type. This way, you will be able to define the mapping of this element by using Mapping editor. The information will also be stored in the Mapping source - see Type Override Tags.

Figure 48.23. Selecting subtype in XMLExtract

Consider following XML file

	
<customer name="attribute_value">
 	<name>element_value</name>
</customer>

	

In this case element customer has attribute name and child element of same name. If both attribute name and element name shall be mapped to output metadata, following mapping is incorrect.

<Mappings>
 	<Mapping element="customer" outPort="0"
 	 	xmlFields="{}name"
 	 	cloverFields="field1">
 	 	<Mapping element="name" useParentRecord="true">
 	 	</Mapping>
 	</Mapping>
</Mappings>

	

Result of this mapping is that both field1 and field2 contains value of element name. Following mapping shall be used if we need to read value of attribute name to some output metadata field.

<Mappings>
 	<Mapping element="customer" outPort="0"
 	 	xmlFields="{}name"
 	 	cloverFields="field2">
 	 	<Mapping element="name" useParentRecord="true"
 	 	 	xmlFields="../{}name"
 	 	 	cloverFields="field1">
 	 	</Mapping>
 	</Mapping>
</Mappings>