Composing XML output for an action in a flow

You can compose XML output within the node for an action by using data that a previous event or action in an IBM® App Connect flow returns. XML uses a universal format to store and transport structured data. You can use the XML compose function to facilitate the distribution of this data between two integrating applications in a flow.

From your flows, you can select XML as the target format for any string field (identified by the abc notation) in an action node, and then define a structure and content for the XML output.

To define the XML output, you import an XML Schema Definition (XSD) file that defines an XML document structure to base your output on. The format of the string field is converted to XML after the file is imported. The XML elements in the imported file are shown as nested fields that conform to the structure and data types that are defined in the file. After you map these fields to data from previous modes, XML output is constructed "in memory" and gets written to the target application when you run the flow. Possible use cases for the XML compose function might be to create XML files in file management applications or in CRM applications that support the creation of attachments.

Guidelines and restrictions for the XSD import

Review these guidelines and restrictions to see which schema definitions are supported in XSD files that you want to import.

A single XSD file with a single namespace definition is supported. A .zip file that contains multiple XSD files is not currently supported.
The following elements are not supported:
- xsd:import (imports schema components from a different namespace into an XSD document)
- xsd:include (imports schema components that are in the same namespace)
- xsd:redefine (redefines simple and complex types, groups, and attribute groups obtained from external schema)
Schemas that include references must specify a target namespace to be rendered correctly.
targetclass is not supported.
xsd:choice child elements are merged, allowing access to all the child elements instead of providing a choice of only one.
References are followed and expanded until they become recursive structures.

To specify an override or an exact namespace and type for any extended or restricted complexType element, add $xsiType as an attribute in your JSON.


 
'Address': {
        '$attributes': {
          '$xsiType': {
            'type': 'overrideType',
            'xmlns': 'overrideNS'
          }
        },
        'HouseNumber': 23
      }

Defining the structure and content of your XML output

The following scenario describes how to compose XML output from a field in your flow. In this scenario, you want to extract shipping details that are recorded for orders in a database. You can then save the details to an XML file in Box for some further action. You constructed a flow that includes an IBM Db2® Retrieve TABLE records action for the data to be retrieved.

The following examples show the Db2 shipping records to be retrieved and the Db2 retrieve records action.

Figure 2. Example of Db2 shipping records to be retrieved

Figure 3. Db2 retrieve records action example

Next, you add a Box action to create a file with an .xml file extension, then generate an XML schema that defines the structure and content of your XML file. To generate this schema, you need an XSD file that describes the elements for the XML content.

From the Box node for the Create file action, specify the folder where you want to save the file, and then add a name of the XML file to be created.
Figure 4. Folder and file name selection in the Box node
In the File content field, click abc and then select XML. (You use this field to compose your XML content.)
Figure 5. Select XML as the format for a string field

In the XML schema settings panel, drag the XSD file from its location in an open file browser into the boxed area. Alternatively, you can click within the boxed area to open a file browser and locate the .xsd file. You can see the file name in the boxed area.

Figure 6. Example of an XSD file in the boxed area for import

The following example shows sample XSD contents (customized from https://www.w3.org/).


<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="fionasnamespace">

  <xs:element name="shiporders">
  <xs:complexType>
  <xs:sequence>
  <xs:element name="shiporder" maxOccurs="unbounded">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="orderperson" type="xs:string"/>
        <xs:element name="shipto">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="name" type="xs:string"/>
              <xs:element name="address" type="xs:string"/>
              <xs:element name="city" type="xs:string"/>
              <xs:element name="country" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="item">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="title" type="xs:string"/>
              <xs:element name="note" type="xs:string" minOccurs="0"/>
              <xs:element name="quantity" type="xs:positiveInteger"/>
              <xs:element name="price" type="xs:decimal"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute name="orderid" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>
  </xs:sequence>
  </xs:complexType>
  </xs:element>

</xs:schema>

If the XSD file contains global elements, select a global element name from the Global element list to identify which portion of the schema to use to define the XML output structure. (XSD files with a single global element show that element name by default.)
Click Import to display a field-based representation of the XML elements and structure.
Figure 7. Field-based representation of the XML elements and structure
Define the XML data content by mapping to the Db2 fields.
Figure 8. XML fields mapped to Db2 fields
To change the structure, field labels, or data types that are defined for the nested fields, click Regenerate schema. (This action deletes any mappings that are defined.) In the XML schema settings panel, clear any previous settings, then add an XSD file with the appropriate XML schema.
If you are sending the XML output to a file, be sure to indicate that the file type is text (rather than binary).

When you run the flow, you obtain an XML file with the specified structure and format. The following image shows an XML file that was generated for the previous scenario.

Example of processing the generated XML output

You can use the XML output that the XML compose function generates in any number of ways to complete an action in the same or a different flow, or used externally. In this example, you want to use the XML file that was generated in the previous scenario to create shipping records for orders within some other application.

You can add a Box Retrieve file action to a flow to retrieve the contents of the XML file. You can then add an XML Parser node to parse the file contents and generate an output schema that you can use to map the XML data in the subsequent create action.

XML Parser node(Click image to view full size.) — Figure 10. XML Parser node

Tip: You can provide the XML from the Box file as a sample for generating the schema. For more information about using the XML Parser node, see Using the XML parser to parse an XML string into an XML object.

Figure 11. Sample XML for generating your XML schema

Next, add a For each node and then specify the collection of items to be processed. In this case, the shiporder array of items from the XML Parser is chosen.

By using a create action within the For each node, you can map to the XML content from the XML Parser. You can then create the relevant records within the appropriate application.