Not available in Community Designer

Mapping editor is core part of XMLWriter (and JSONWriter). It lets you visually map input data records onto an XML tree structure (see Figure 54.28, “Mapping Editor”). The XML tree structure can be effectively populated by dragging the input ports or fields onto XML elements and attributes.

The editor gives you direct access to the mapping source where you can virtually edit the output XML file as text. You use special directives to populate the XML with CloverETL data there (see Figure 54.36, Source tab in Mapping editor).

The XML structure can be provided as an XSD Schema (see the XML Schema attribute) or you can define the structure manually from scratch.

You can access the visual mapping editor clicking the "..." button of the Mapping attribute.

Figure 54.28. Mapping Editor

There are two main tabs in the upper left corner of the editor's window:

Changes made in the Mapping tab take immediate effect in the Source tab and vice versa. In other words, both editor tabs allow making equal changes.

Adds a Namespace as a new xmlns:prefix attribute of the selected element. Declaring a Namespace allows you to use your own XML tags. Each Namespace consists of a prefix and an URI. In case of XMLWriter mapping, the root element has to declare the clover namespace, whose URI is http://www.cloveretl.com/ns/xmlmapping. That grants you access to all special XML mapping tags. If you switch to the Source tab, you will easily recognize those tags as they are distinct by starting with clover:, e.g. clover:inport="2". Keep in mind that no XML tag beginning with the clover: prefix is actually written into the output XML.

Adds a special directive to populate the element with attributes based on Include / Exclude wildcard patterns instead of mapping these attributes explicitly. This feature is useful when you need to retain metadata independence.

Attribute names are generated from field names of the respective metadata. Syntax: use $portNumber.field or $portName.field to specify a field, use * in the field name for "any string". Use ; to specify multiple patterns.

There are two main properties in a Wildcard attribute. At least one of them has to be always set:

Figure 54.30. Wildcard attribute and its properties

Adds a single attribute to the selected element. Once done, the Attribute name can be changed either by double-clicking it or editing Attribute name at the bottom. The attribute Value can either be a fixed string or a field value that you map to it. You can even combine static text and multiple field mappings. See example below.

Figure 54.31. Attribute and its properties

Path and Description are common properties for most nodes. They both provide a better overview for the node. In Path, you can observe how deep in the XML tree a node is located.

Adds an element as a basic part of the output XML tree.

Figure 54.32. Element and its properties

Depending on an element's location in the tree and ports connected to it, the element can have these properties:

Adds a set of elements. The Include and Exclude properties influence which elements are added and which not. To learn how to make use of the $port.field syntax, please refer to Wildcard attribute. Rules and examples described there apply to Wildcard element as well. What is more, Wildcard element comes with two additional properties, whose meaning is closely related to the one of Write null attribute and Omit null attribute:

Adds content of the element. It is displayed at the very end of an uncollapsed element, i.e. always behind its potential Binding, Wildcard attributes or Attributes. Once again, its value can either be a fixed string, a port's field or their combination.

Adds CDATA section.

The CDATA Section may contain data that is not allowed as value of the ordinary element or attribute. The CDATA Section can contain for example the whole xml file. The CDATA Sections can not be nested: A CDATA Section can not be included into another CDATA Section.

Adds a comment. This way you can comment on every node in the XML tree to make your mapping clear and easy-to-read. Every comment you add is displayed in the Mapping editor only. What is more, you can have it written to the output XML file setting the comment's Write to the output to true. Examine the Source tab to see your comment there, for instance:

	<!-- clover:write This is my comment in the Source tab.
	It will be written to the output 
	XML because I set its 'Write to output' to true.
	There is no need to worry about the 
	"clover:write" directive at the beginning as no attribute/element starting with 
	the "clover" prefix is put to the output.
	-->
         

Having added the first element, you will notice that every element except for the root provides other options than just Add Child (and Add Property). Right-click an element to additionally choose from Add Sibling Before or Add Sibling After. Using these, you can have siblings added either before or after the currently selected element.

Besides the right-click context menu, you can use toolbar icons located above the XML tree view.

Figure 54.33. Mapping editor toolbar

The toolbar icons are active depending on the selected node in the tree. Actions you can do comprise:

When building the XML tree from scratch (see Creating the Mapping - Designing New XML Structure ) why not make use of these tips saving mouse clicks and speeding up your work:

Every node you add can later be moved in the tree by a simple drag and drop using the left mouse button. That way you can re-arrange your XML tree any way you want. Actions you can do comprise:

Removing nodes (such as elements or attributes) in the Mapping editor is also carried out by pressing Delete or right-clicking the node and choosing Remove. To select more nodes at once, use Ctrl+click or Shift+click .

Any time during your work with the mapping editor, press Ctrl+Z to Undo the last action performed or Ctrl+Y to Redo it.

As of Clover v. 3.3, XMLWriter supports multivalue fields in metadata. That includes mapping lists and maps to the output XML. For more information, see Multivalue Fields and Data Types in CTL2.

The only thing to mind in XMLWriter is how lists vs. maps look in the output file. A map is written to a single tag (in between the curly { } brackets) while a list is separated to n tags where n is the list's element count. Example:

        	
        	<canadianMap>{ot=Ontario, bc=British_Columbia, at=Alberta, nt=Northern_Territory}</canadianMap> <!--  map with four key-value pairs --> 
        	
        	<valueList>-65.25</valueList> <!-- a three-element list --> 
    		<valueList>71.49</valueList>
    		<valueList>-35.02</valueList>
        	
        	

A template is a piece of code that is used to insert another (larger) block of code. Templates can be inserted into other templates, thus creating recursive templates.

As mentioned above, the Source tab's Content Assist allows you to smoothly declare and use your own templates. The option is available when pressing Ctrl+Space in a free space in between two elements. Afterwards, choose either Declare template or Insert template.

The Declare template inserts the template header. First, you need to enter the template name. Second, you fill it with your own code. Example template could look like this:

<clover:template clover:name="templCustomer">
<customer>
	<name>$0.name</name>
	<city>$0.city</city>
	<state>$0.state</state>
</customer>  
</clover:template>
        

To insert this template under one of the elements, press Ctrl+Space and select Insert template. Finally, fill in your template name:

<clover:insertTemplate clover:name="templCustomer"/>
        

In recursive templates, the insertTemplate tag appears inside the template after its potential data. When creating recursive structures, it is crucial to define keys and parent keys. The recursion then continues as long as there are matching key and parentKey pairs. In other words, the recursion depth is dependent on your input data. Using filter can help to get rid of the records you do not need to be written.

This example shows writing an xml file that needs modification, e.g. to add a DTD.

Write records to an XML file. Insert a DTD into the file on line 2.

Solution

Write records with XMLWriter to output port. Use streaming mode.

Read records with FlatFileReader: one line per record. The metadata between XMLWriter and FlatFileWriter should have no delimiters and should use EOF as delimiter.

Partition the records into the streams: first record to the first edge, another records to the second edge.

Use DataGenerator to create a record to be inserted.

Use Concatenate to bundle together the records in correct order.

Write records to a file with FlatfileWriter.

Figure 54.39. Writing non-standard xml

Since CloverETL 4.4.0-M1, you can use Omit XML declaration attribute to insert or omit the XML declaration.