Dynamically Constructing the XML Document with the XSD-Driven XML Writer

Introduction

This is the second Part in the series on using the XML Appender Parameters on the XSD-Driven XML Writer. In this part, we will examine some more advanced tools for constructing the final XML Document. Refer to Part 1 in the series for demonstration on basic usage of the XML Appender parameters. 
 

Step-by-Step Instructions

Dynamically constructing the XML Document with the _XML_DOCUMENT_ Feature Type 

Sometimes, manually entering the root document in the XML Document parameter may not be preferable. This can occur when the root document needs to be constructed from within the workspace itself. This problem can be solved by using the _XML_DOCUMENT_ Feature Type. Using this feature type, an XML document can be constructed from attributes or features from the workspace, for example using the XMLTemplater then fed into the XSD-Driven XML Writer through the _XML_DOCUMENT_ feature’s xml_document format attribute. This overrides any value set into the original XML Document parameter in the XSD Driven XML Writer.

1. You can add an additional Feature Type to the XSD-Driven XML Writer through the Writers tab. 


2. Make sure to name the new Feature Type as _XML_DOCUMENT_. This will ensure that the XML Document parameter will be overridden by a xml_document attribute. 


3. The xml_document is a format attribute of the XSD-Driven XML Writer that can be used to create an XML root document from the workspace. A method for constructing the XML document in the workspace is to use the XMLTemplater. A guide for doing this can be found here. Ensure that after constructing the root XML document, the final attribute should be named xml_document so that it can be consumed by the Writer. Once this is done, the XML document from the attribute will be used and any XML Features in the writer will be inserted into this document. 


4. In the above picture example, an XMLTemplater was used to construct an XML Document using attributes from various portions of the workspace. The resulting XML document attribute should be renamed xml_document so that it can be used in the Writer as a format attribute (Conversely, the attribute can be simply named xml_document in the XMLTemplater itself).

Append Path and Append As Format Attributes

By default, simply just using the xml_document format attribute with the _XML_DOCUMENT_ Feature Type will only override the XML Document parameter. If there are situations where the XML Document Append Path and Append As need to be dynamically controlled through the workspace, then there are additional format attributes for each of these parameters: xml_document_append_path and xml_document_append_as format attributes. 

For this example, we will use two different features: bed:mag and bed:depth. The former must be inserted as a child of bed:magnitude, while the latter must be inserted as a child of bed:origin. 

1. With the XSD-Driven XML Writer, define your XML Features. Here, we will be using two features where each will be inserted into different locations in the root XML document.

<bed:mag>
	<bed:value>5</bed:value>
	<bed:uncertainty>0</bed:uncertainty>
</bed:mag>

<bed:depth>
	<bed:value>7000</bed:value>
	<bed:uncertainty>1240</bed:uncertainty>
</bed:depth>

2. Add xml_document_append_path and xml_document_append_as attributes to the features. The method of adding these attributes to the features will depend on the workspace. Some methods include: AttributeCreator, Tester or Conditional Values with an AttributeTransformer. 

To place the bed:mag feature in bed:magnitude, it will need the path to be set as bed:eventParameters/bed:event/bed:magnitude. To place the bed:depth feature in bed:origin, it will need the path to be set as bed:eventParameters/bed:event/bed:origin. Placing the feature as a Succeeding Child will suffice in this example but this can also be changed with the format attribute depending on use case. 


3. These format attributes can be used together with the _XML_DOCUMENT_ Feature Type to have complete dynamic control over constructing the final XML Document. Using any of the format attributes instead of the parameter will override the corresponding parameter. 

<?xml version="1.0" encoding="UTF-8"?>
<bed:eventParameters xmlns:bed="http://quakeml.org/xmlns/bed/1.2" xmlns:catalog="http://anss.org/xmlns/catalog/0.1" publicID="quakeml:earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.quakeml">
    <bed:creationInfo>
        <bed:creationTime>2020-02-10T23:00:10.000Z</bed:creationTime>
    </bed:creationInfo>
    <bed:event publicID="quakeml:earthquake.usgs.gov/earthquakes/feed/v1.0/detail/pr2020035028.quakeml">
        <bed:magnitude>
            <bed:type>ml</bed:type>
            <bed:originID>quakeml:earthquake.usgs.gov/archive/product/origin/2020035028/pr/1581090391322/product.xml</bed:originID>
            <bed:stationCount>0</bed:stationCount>
            <bed:evaluationMode>manual</bed:evaluationMode>
            <bed:creationInfo>
                <bed:creationTime>2020-02-07T15:46:31.322Z</bed:creationTime>
            </bed:creationInfo>
            <bed:mag>
                <bed:value>5</bed:value>
                <bed:uncertainty>0</bed:uncertainty>
            </bed:mag>
        </bed:magnitude>
        <bed:origin>
            <bed:time>
                <bed:value>2020-02-04T14:45:55.720Z</bed:value>
            </bed:time>
            <bed:longitude>
                <bed:value>-66.8751</bed:value>
            </bed:longitude>
            <bed:latitude>
                <bed:value>17.8388</bed:value>
            </bed:latitude>
            <bed:originUncertainty>
                <bed:horizontalUncertainty>1050</bed:horizontalUncertainty>
                <bed:preferredDescription>horizontal uncertainty</bed:preferredDescription>
            </bed:originUncertainty>
            <bed:quality>
                <bed:usedPhaseCount>30</bed:usedPhaseCount>
                <bed:usedStationCount>17</bed:usedStationCount>
                <bed:standardError>0.19</bed:standardError>
                <bed:azimuthalGap>239</bed:azimuthalGap>
                <bed:minimumDistance>0.1364</bed:minimumDistance>
            </bed:quality>
            <bed:evaluationMode>manual</bed:evaluationMode>
            <bed:creationInfo>
                <bed:creationTime>
                          2020-02-07T15:46:31.322Z
                      </bed:creationTime>
            </bed:creationInfo>
            <bed:depth>
                <bed:value>7000</bed:value>
                <bed:uncertainty>1240</bed:uncertainty>
            </bed:depth>
        </bed:origin>
        <bed:preferredOriginID>quakeml:earthquake.usgs.gov/archive/product/origin/2020035028/pr/1581090391322/product.xml</bed:preferredOriginID>
        <bed:preferredMagnitudeID>
            quakeml:earthquake.usgs.gov/archive/product/origin/2020035028/pr/1581090391322/product.xml#magnitude
        </bed:preferredMagnitudeID>
        <bed:type>earthquake</bed:type>
        <bed:creationInfo>
            <bed:agencyID>pr</bed:agencyID>
            <bed:creationTime>
                      2020-02-08T17:09:13.140Z
                  </bed:creationTime>
        </bed:creationInfo>
    </bed:event>
</bed:eventParameters>

Inserting a Fragment into the XML Document

If a standalone XML Fragment needs to be inserted into the XML Document that is not a part of the XML Features, a user can use the special feature type _XML_FRAGMENT_. The fragment can be specified with the xml_fragment format attribute. Additionally, the xml_document_append_path and xml_document_append_as format attributes can be used to specify where and how the fragment is to be inserted into the XML Document.

We will expand on the above example and add a standalone bed:description fragment to the bed:event element. 

<bed:description>
	<bed:text>20km SSE of Guanica, Puerto Rico</bed:text>
	<bed:type>earthquake name</bed:type>
</bed:description>

1. Have an attribute with the value of the desired XML Fragment. This can be already located inside your data or can be assigned using an Attribute transformer. Name the attribute xml_fragment. 

2. Additionally, we need to direct where the fragment will be inserted into the XML Document. This can be done with the xml_document_append_path and xml_document_append_as format attributes. In order for them to apply to the XML Fragment, they must be routed into the _XML_FRAGMENT_ feature type. For this example, we will be inserting the fragment into bed:event as the Preceding Child. 


3. Add a _XML_FRAGMENT_ Feature Type. The xml_fragment attribute will then be fed into this feature type.

4. The output will now contain the inserted fragment at the beginning of the bed:event element. 

<bed:eventParameters xmlns:bed="http://quakeml.org/xmlns/bed/1.2" xmlns:catalog="http://anss.org/xmlns/catalog/0.1" publicID="quakeml:earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.quakeml">
	<bed:creationInfo>
		<bed:creationTime>2020-02-10T23:00:10.000Z</bed:creationTime>
	</bed:creationInfo>
	<bed:event publicID="quakeml:earthquake.usgs.gov/earthquakes/feed/v1.0/detail/pr2020035028.quakeml">
		<bed:description>
			<bed:text>20km SSE of Guanica, Puerto Rico</bed:text>
			<bed:type>earthquake name</bed:type>
		</bed:description>
		<bed:magnitude publicID="quakeml:earthquake.usgs.gov/archive/product/origin/2020035028/pr/1581090391322/product.xml#magnitude">
			<bed:type>ml</bed:type>
			<bed:originID>
quakeml:earthquake.usgs.gov/archive/product/origin/2020035028/pr/1581090391322/product.xml
                  </bed:originID>
			<bed:stationCount>0</bed:stationCount>
			<bed:evaluationMode>manual</bed:evaluationMode>

XML Wrapper Format Attribute

Similar to using the xml_document format attribute, the XML Wrapper also has its own format attributes that allow users to dynamically create the Wrapper from the workspace. This also allows each XML feature to have their own uniquely created Wrapper. 

In demonstrating this, we will look at two different bed:magnitude features. These features will be wrapped by a bed:event Wrapper fragment and each bed:event will have unique creation times. 

<bed:magnitude>
	<bed:mag>
		<bed:value>5</bed:value>
		<bed:uncertainty>0</bed:uncertainty>
	</bed:mag>
	<bed:type>ml</bed:type>
	<bed:stationCount>0</bed:stationCount>
      <bed:evaluationMode>manual</bed:evaluationMode>
</bed:magnitude>

<bed:magnitude>
	<bed:mag>
		<bed:value>5.3</bed:value>
		<bed:uncertainty>0.063</bed:uncertainty>
	</bed:mag>
	<bed:type>ml</bed:type>
	<bed:stationCount>24</bed:stationCount>
      <bed:evaluationMode>manual</bed:evaluationMode>
</bed:magnitude>

1. To use the XML Wrapper format attribute, first define a xml_wrapper attribute in the workspace. For this example, the attributes will be created with an AttributeCreator transformer. Additionally, format attributes xml_wrapper_append_path and xml_wrapper_append_as can be used to specify where the feature will be placed in the wrapper.  

In the xml_wrapper attribute. Some of the XML elements can be dynamically populated using another attribute. Here, the creationTime element of the Event wrapper is populated by the _timestamp attribute. 


2. Similar to the xml_document format attributes, the xml_wrapper format attributes will override any set parameters in the Writer. Set the Writer to write the bed:magnitude features. With these, the features will be wrapped with their corresponding xml_wrapper attributes.

<bed:event>
    <bed:magnitude>
        <bed:mag>
            <bed:value>5</bed:value>
            <bed:uncertainty>0</bed:uncertainty>
        </bed:mag>
        <bed:type>ml</bed:type>
        <bed:stationCount>0</bed:stationCount>
        <bed:evaluationMode>manual</bed:evaluationMode>
    </bed:magnitude>
    <bed:description>
        <bed:text>20km SSE of Guanica, Puerto Rico</bed:text>
        <bed:type>earthquake name</bed:type>
    </bed:description>
    <bed:creationInfo>
        <bed:creationTime>
            	2022-10-17T21:19:27.8266048
        	</bed:creationTime>
    </bed:creationInfo>
</bed:event>
<bed:event>
    <bed:magnitude>
        <bed:mag>
            <bed:value>5.3</bed:value>
            <bed:uncertainty>0.063</bed:uncertainty>
        </bed:mag>
        <bed:type>ml</bed:type>
        <bed:stationCount>24</bed:stationCount>
        <bed:evaluationMode>manual</bed:evaluationMode>
    </bed:magnitude>
    <bed:description>
        <bed:text>20km SSE of Guanica, Puerto Rico</bed:text>
        <bed:type>earthquake name</bed:type>
    </bed:description>
    <bed:creationInfo>
        <bed:creationTime>
            2022-10-17T21:22:41.4547742
        </bed:creationTime>
    </bed:creationInfo>
</bed:event>

3. However, this is not a valid XML document since it does not have a single root element. This can be alleviated by using the XML Document parameter (or conversely the _XML_DOCUMENT_ Feature Type). To fix this, we can add bed:eventParameters as the root in the XML document. 

<bed:eventParameters xmlns:bed="http://quakeml.org/xmlns/bed/1.2" xmlns:catalog="http://anss.org/xmlns/catalog/0.1" publicID="quakeml:earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.quakeml">
    <bed:event>
        <bed:magnitude>
            <bed:mag>
                <bed:value>5</bed:value>
                <bed:uncertainty>0</bed:uncertainty>
            </bed:mag>
            <bed:type>ml</bed:type>
            <bed:stationCount>0</bed:stationCount>
            <bed:evaluationMode>manual</bed:evaluationMode>
        </bed:magnitude>
        <bed:description>
            <bed:text>20km SSE of Guanica, Puerto Rico</bed:text>
            <bed:type>earthquake name</bed:type>
        </bed:description>
        <bed:creationInfo>
            <bed:creationTime>
            	2022-10-17T21:19:27.8266048
        	</bed:creationTime>
        </bed:creationInfo>
    </bed:event>
    <bed:event>
        <bed:magnitude>
            <bed:mag>
                <bed:value>5.3</bed:value>
                <bed:uncertainty>0.063</bed:uncertainty>
            </bed:mag>
            <bed:type>ml</bed:type>
            <bed:stationCount>24</bed:stationCount>
            <bed:evaluationMode>manual</bed:evaluationMode>
        </bed:magnitude>
        <bed:description>
            <bed:text>20km SSE of Guanica, Puerto Rico</bed:text>
            <bed:type>earthquake name</bed:type>
        </bed:description>
        <bed:creationInfo>
            <bed:creationTime>
                 2022-10-17T21:22:41.4547742
            </bed:creationTime>
        </bed:creationInfo>
    </bed:event>
</bed:eventParameters>