The Split by Type function takes data from an input node and splits it into two or more output data nodes. The split is based on an input element's value. For example, an Addresses input node can be split into Shipping and Billing output nodes.

Split by Type functions are available as part of the Data Transformation Layer (DTL When used as part of a BPA Platform tool, the Data Transformation Layer (DTL) extend the tool's functionality by transforming SML from schema to another. In addition, several transformation functions are available for use with the input data before such data is mapped to the destination schema.) feature.

Adding a Split by Type Function

Split by Type functions are used in the Mapping tab of the following tools:

►

Microsoft SQL Server Connector

►

Run Microsoft Reporting Services The Run Microsoft Reporting Services tool automates the running of Microsoft Reporting Services (MSRS) reports.

►

Transform Data Transform Data is a Format tool that enables a new structure to be created from an existing XML or recordset data source. The output generated by this tool is ready for use in a destination system which consumes or requires XML.

►

Web Service Connector

1. Open the relevant task step and go to the Mapping tab.

2. Click Functions to expand the Functions pane.
3. Expand the Looping node and drag Split by Type to the Transformation Mappings pane.
4. Drag the Input Data node containing the records you want to split to the icon.
5. Drag the Input Data element containing the values you are basing the split on (for example, an Address_Type element if you want to split based on values Delivery or Billing) to the icon.
6. Do the same for the receiving Output Data node.
7. Double-click the icon.

The Transformation Mappings pane is replaced with the Split by Type's configuration pane:

8. Enter a meaningful Function Name.
9. Make sure the ObjectToSplit and SplitBasedOn mappings are correct (hover over each Mapped To parameter in turn).

   To change an existing mapping, either Inputs or Output, use the drop-down lists under Mapped To to select a new node or element.

10. The output (destination) link(s) created previously now appear in the Output tab. If you have more than one connected output, it is recommended you Edit each Parameter in turn and rename it.

Defining the Split

If you haven't renamed the Output parameters, it is recommended you do this now. This makes it easier to identify mappings.

1. Go to the Mapping tab.
2. In Split Based On Value, enter the value that indicates this record is outputted to this output node. In this example, where a 1 is received in the designated input element (SplitBasedOn), the record is outputted to the mapped Billing node:

Selecting Error Handling Options

Use the Options tab to define error handling behaviour for this function.

At task run-time, if a mapped input element is not included in the received input recordset or XML, you can choose to:

►

Output an empty String — An empty string is passed to the mapped output node at task run time, for example, <country></country>.

►

Output no Data — The element isn't included in the output XML.

►

Output Value — Enter a static value in the provided text box; this value is passed to the mapped output at task run-time.

►

Error — The function logs an error to the BPA Platform Event Log. Depending on the parent task step's own error handling options, the task can either continue or fail completely.

If a value is detected in the SplitBasedOn element (Inputs tab) that is not specified in the Mapping tab, you can choose to:

►

Create Output — Map the record to the output parameter specified here.

►

Create no output for this object instance and continue — The function ignores the unexpected value and continues looping or, if at the end of the loop, continues with the task step.

►

Error — The function logs an error to the BPA Platform Event Log. Depending on the parent task step's own error handling options, the task can either continue or fail completely.

Click OK to save the function and return to the parent task step's Mapping tab.

Example Usage

Let us say this is the XML we receive as the input:

<company>
  <id>1</id>
  <address>
    <line1>7 American Ash Court</line1>
    <line2>London</line2>
    <is_shipping>1</is_shipping>
  </address>
</company>
<company>
  <id>1</id>
  <address>
    <line1>98298 Kim Place</line1>
    <line2>Edingburgh</line2>
    <is_shipping>0</is_shipping>
  </address>
</company>
<company>
  <id>2</id>
  <address>
    <line1>67787 Thackeray Park</line1>
    <line2>Cardiff</line2>
    <is_shipping>1</is_shipping>
  </address>
</company>

And this is the expected outputted XML structure:

<company_address>
  <id>1</id>
  <shipping_address>
    <line1>7 American Ash Court</line1>
    <line2>Edinburgh</line2>
  </shipping_address>
  <billing_address>
    <line1>9 Green Ridge Street</line1>
    <line2>London</line2>
  </billing_address>
</company_address>

In the Transform Data tool, we have replicated the required output structure (Main tab):

A few things to note:

►

shipping_address and billing_address nodes both have minOccurs set to 0. This is because we cannot guarantee each customer record has both.

►

line1 and line2 for both address types have minOccurs and maxOccurs both set to 1. These cannot be repeated for a single address type.

The Mapping tab is structured as follows:

Click the image to view full size.

►

A Simple function connects the parent company input node to the company_address output node

This function loops through the XML and creates a company_address record for every company record it finds.

►

line1 and line2 from the input XML are mapped to both their corresponding elements in the shipping_address and billing_address nodes

Let's take a look at the configuration for the Split by Type function:

►

The inputs are as follows:

where for every record found in address, a corresponding record is made in the output schema based on the value found in is_shipping.

►

The outputs are as follows:

These are the nodes in the output schema where the address records are mapped to. Note how the default parameter names have been changed— changing the parameter names from "Output0" allows you to quickly understand which value should be mapped here.

►

Finally, the Mapping tab determines which records go to shipping_address and which to billing_address: