Search

Composing XML Documents using the XML Appender Parameters in the XSD-Driven XML Writer

Liz Sanderson
Liz Sanderson
  • Updated

FME Version

Introduction

The XSD Driven XML Writer is a powerful tool for writing out XML features using any XSD schema. However, this may not encompass the entire XML document. There may be other parts or elements that are preferred to not be mapped as features and these parts may need to be written out into the final XML document somehow. To handle this, the XML Appender parameters in the XSD-Driven XML Writer can provide tools to help construct all parts of the final XML document. 

There are two parameters in this group: the XML Document and the XML Wrapper parameters. The XML Document parameter can be used to create a root XML Document into which your XML element features can be inserted. Conversely, the XML Wrapper parameter can be used to wrap your XML features with a specified XML Fragment. 

This tutorial will show some examples of how to use each of these features to compose your own XML document. Please be aware that this tutorial only pertains to the XML Appender parameters in the XSD-Driven XML Writer, not the XMLAppender transformer. As of version 2022.0, the tools on the XSD-Driven XML Writer are more powerful than the transformer. This tutorial also assumes prior knowledge on how to read and write XML features using the XSD-Driven XML Writer, please see this guide. 

 

Step-by-step Instructions

Appending Features into an XML Document

The XML Document parameter can be an excellent tool in composing a final XML document. This tool can be used to define a root XML document. After defining the root document, XML features from the Writer can then be inserted into the document with paths defined by the user.

For this demonstration, we will insert a bed:event XML feature into a bed:eventParameters XML document defined using the XML Appender parameter in the XSD-Driven XML Writer. The following feature is an example of an earthquake event.

<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: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:depth>
            <bed:value>7000</bed:value>
            <bed:uncertainty>1240</bed:uncertainty>
        </bed:depth>
    </bed:origin>
</bed:event>

1. Define the root XML document in the XML Document parameter into which your XML features will be placed. This example of XML root document will be the root for Earthquake events which also includes all XML declarations.
1.png

2.png

<?xml version="1.0" encoding="UTF-8"?>
<bed:eventParameters xmlns:bed="http://quakeml.org/xmlns/bed/1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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:eventParameters>

2. By default, the XML feature will be inserted in the path Succeeding Children of the root document. This can be adjusted based on user preference. 

3. Given the parameters that we have selected, the bed:event feature will be inserted into the bed:eventParameters XML document succeeding the bed:creationInfo element. Here is an example of the output written XML file. 

<?xml version="1.0" encoding="UTF-8"?>
<bed:eventParameters xmlns:catalog="http://anss.org/xmlns/catalog/0.1" xmlns:bed="http://quakeml.org/xmlns/bed/1.2" 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: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:depth>
                <bed:value>7000</bed:value>
                <bed:uncertainty>1240</bed:uncertainty>
            </bed:depth>
        </bed:origin>
    </bed:event>
</bed:eventParameters>


Appending Features into an XML Document with a Path

Depending on the XML document, a user may be required to select a particular path to which the XML element features will be inserted. This can be done with the XML Document Append Path parameter. With this parameter, you can append the XML feature into the specific path of your needs. Consider a new XML feature of an Earthquake Magnitude. 

<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:creationInfo>
        <bed:creationTime>2020-02-07T15:46:31.322Z</bed:creationTime>
    </bed:creationInfo>
</bed:magnitude>

1. Similar to above, a XML Document can be defined, however, this time the example is more complex. The root contains a child element which will be the correct path to insert the features. In this example, the bed:magnitude feature element will be inserted into the bed:event child element.
3.png

<bed:eventParameters xmlns:catalog="http://anss.org/xmlns/catalog/0.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bed="http://quakeml.org/xmlns/bed/1.2" publicID="quakeml:earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.quakeml">
    <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: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:depth>
                <bed:value>7000</bed:value>
                <bed:uncertainty>1240</bed:uncertainty>
            </bed:depth>
            <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: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:creationInfo>
        <bed:creationTime>2020-02-10T23:00:10.000Z</bed:creationTime>
    </bed:creationInfo>
</bed:eventParameters>

2. To insert the bed:magnitude feature into bed:event of the XML document, we will want to use the path bed:eventParameters/bed:event. Additionally, since we want bed:magnitude to be the last child of bed:event, we will also set the parameter XML Document Append As to Succeeding Children (default). We can also set this to Preceding Children which will insert the bed:magnitude element as the first child of the bed:event element at the beginning of the fragment. 

4.png

3. With the selected XML Appender parameters, the bed:magnitude will be inserted into the bed:event element at the end. Here is an example of the written output XML. 
 

<?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: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: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:depth>
                <bed:value>7000</bed:value>
                <bed:uncertainty>1240</bed:uncertainty>
            </bed:depth>
            <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: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:magnitude>
            <bed:mag>
                <bed:value>5</bed:value>
                <bed:uncertainty>0</bed:uncertainty>
            </bed:mag>
            <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:magnitude>
    </bed:event>
    <bed:creationInfo>
        <bed:creationTime>2020-02-10T23:00:10.000Z</bed:creationTime>
    </bed:creationInfo>
</bed:eventParameters>

 

Wrapping XML Features with the XML Wrapper

Another useful tool in composing your final XML document is the XML Wrapper parameter. Using this tool, you can wrap your XML features with an XML Fragment. This can be helpful if your XML features require another level of XML elements before being inserted into an XML document. For this demonstration, let us reconsider the Earthquake Magnitude XML Feature.

<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:creationInfo>
        <bed:creationTime>2020-02-07T15:46:31.322Z</bed:creationTime>
    </bed:creationInfo>
</bed:magnitude>

Additionally, we will be inserting these features into the root document bed:eventParameters.

<bed:eventParameters xmlns:bed="http://quakeml.org/xmlns/bed/1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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:eventParameters>

However, we are missing one level of XML elements in between, bed:event. We can fix this by using the XML Wrapper to wrap bed:magnitude with bed:event which will then be ready for the final XML document. 

1. Define an XML Document in the XML Document parameter. We can use the bed:eventParameters root element from the above example. 
5.png


6.png

2. To wrap the XML feature with the bed:event element, we want to define the wrapper in the XML Wrapper parameter. For this example, we will wrap our XML feature with the following XML elements. Additionally, by default the XML Wrapper parameter will append the feature to the Wrapper’s Succeeding Children. This means that the XML Feature will be appended to the end of any children of the wrapper element. 

<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:event>

7.png

8.png

3. With the above parameters set, the bed:magnitude XML Feature will be wrapped with the bed:event wrapper before being inserted into the root XML Document. 

<?xml version="1.0" encoding="UTF-8"?>
<bed:eventParameters xmlns:catalog="http://anss.org/xmlns/catalog/0.1" xmlns:bed="http://quakeml.org/xmlns/bed/1.2" 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>
            <bed:mag>
                <bed:value>5</bed:value>
                <bed:uncertainty>0</bed:uncertainty>
            </bed:mag>
            <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:magnitude>
    </bed:event>
</bed:eventParameters>

 

Wrapping XML Features with the XML Wrapper using a Path

Similar to the example in the XML Document, sometimes it may be preferable to define a path to where in the XML Wrapper you want your XML features to be inserted. This can occur when there is a wrapper that may have multiple other elements that may make the wrapper more complex. For this example, let us consider the XML feature element bed:mag. This time, we will wrap the feature with the same bed:event wrapper but with an additional bed:magnitude child. Since the bed:mag feature must be a child of bed:magnitude, we will be using the XML Wrapper Append Path parameter to specify the exact location the feature is to be placed. 

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

This is the wrapper for the XML feature:

<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>
        <bed:type>ml</bed:type>
        <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:magnitude>
</bed:event>

1. Define an XML Document in the XML Document parameter. We will be using the same  bed:eventParameters root element from the previous section. 
5.png

6.png

2. Define the Wrapper through the XML Wrapper parameter. For this example, the Wrapper will be a little more complex and the XML feature will be placed inside one of the children of the XML Wrapper.
7.png

9.png

3. At this point, the XML Feature will not be inserted into the correct spot. To fix this we will define the specific path with the XML Wrapper Append Path parameter. In the parameter, the path bed:event/bed:magnitude will specify that the XML Feature be placed in the bed:magnitude element. Additionally, the Path parameter is used in tandem with the XML Wrapper Append As parameter to specify the location in the path it should be placed. In this example, we will set this parameter to Preceding Children to insert the XML Feature as the first child of the bed:magnitude element. 
10.png


4. With the above parameters set, the bed:mag XML Feature will be added to the bed:magnitude element of the XML Wrapper before finally being inserted into the bed:eventParameters XML document. 

<?xml version="1.0" encoding="UTF-8"?>
<bed:eventParameters xmlns:catalog="http://anss.org/xmlns/catalog/0.1" xmlns:bed="http://quakeml.org/xmlns/bed/1.2" 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>
            <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:creationInfo>
                <bed:creationTime>
                             2020-02-07T15:46:31.322Z
                        </bed:creationTime>
            </bed:creationInfo>
        </bed:magnitude>
    </bed:event>
</bed:eventParameters>
 

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.