Composing XML output for an action in a flow

You can compose XML output within the node for an action by using data that's returned by a previous event or action in an IBM® App Connect flow. XML uses a universal format to store and transport structured data, and the "XML compose" function can be used 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.

Figure 1. Select XML as a target format
Select XML as a target format

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 string field's format is converted to XML after the file is imported, and the XML elements in the imported file are exposed 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.

Sections in this page:

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. Multiple XSD files in a ZIP archive are 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 in order 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.
  • Adding $xsiType as an attribute in your JSON will allow you to specify an override or an exact namespace and type for any complexType element that has been extended or restricted. For example: 
    
 
'Address': {
        '$attributes': {
          '$xsiType': {
            'type': 'overrideType',
            'xmlns': 'overrideNS'
          }
        },
        'HouseNumber': 23
      }

Defining the structure and content of your XML output

We'll use a simple scenario to describe how you can compose XML output from a field in your flow. Let's suppose you want to extract shipping details that are recorded for orders in a database so that you can save them to an XML file in Box for some further action. You have constructed a flow that includes an IBM Db2® Retrieve TABLE records action for the data to be retrieved.

  • Figure 2. Example of Db2 shipping records to be retrieved
    Example of Db2 shipping records to be retrieved
    Figure 3. Db2 retrieve records action example
    Db2 retrieve records action example

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

  1. 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
    Folder and file name selection in the Box node
  2. In the File content field, click abc and then select XML. (This is the field that you want to use to compose your XML content.)
    Figure 5. Select XML as the format for a string field
    Select XML as the format for a string field
  3. In the XML schema settings panel, either drag and drop the XSD file from its location in an open file browser into the boxed area, or click within the boxed area to open a file browser and locate the .xsd file. You'll see the file name in the boxed area.
    Figure 6. Example of an XSD file in the boxed area for import
    Example of an XSD file in the boxed area for import
    • 
<?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>
  4. If the XSD file contains global elements, select a global element name from the Global element drop-down list to identify which portion of the schema should be used to define the XML output structure. (XSD files with a single global element will show that element name by default.)
  5. 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
    Field-based representation of the XML elements and structure
  6. Define the XML data content by mapping to the Db2 fields.
    Figure 8. XML fields mapped to Db2 fields
    XML fields mapped to Db2 fields
  7. To change the structure, field labels, or data types defined for the exposed nested fields , click Regenerate schema. (Note that you will lose any mappings that are currently defined.) In the XML schema settings panel, clear any previous setting, and then add an XSD file with the required XML schema.
  8. If you are sending the XML output to a file, be sure to indicate that the file type should be text (rather than binary).

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

Figure 9. Generated XML file in Box
Generated XML file in Box

Example: Processing the generated XML output

The XML output that the XML compose function generates can be used in any number of ways to complete an action in the same or a different flow, or used externally. Let's suppose that you'd like to use the .xml file that was generated in the previous scenario to create shipping records for orders within some other application.

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

Figure 10. XML Parser node
XML Parser node(Click image to view full size.)
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
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.

For each node

Using a "create" action within the For each node, you can then map to the XML content from the XML Parser so that you can create the relevant records within the required application.