Group

You can use the Group transform to map a single list of elements into a nested list of elements based on an input element.

Overview

For example, you can use the Group transform to map a single list of company employee records into a nested list of employees by department.

The Group transform provides a nested transform for mapping each collated input array occurrence to the output nested array structure.

The nested transforms are performed sequentially for each collated group of input elements that have matching values in the element that you have selected to group by in the General tab.

Inputs and outputs

The input to a Group transform must be a repeating complex type, such as an array or a list, and contain a simple type element that will be used for collating groups.

The output to a Group transform must be a repeating complex type, that includes the following elements:

A none repeating simple type element in which to set the group identifier.
A repeating complex type into which to map the data from the matching inputs.

Group by

In the General tab of the properties page, you configure the Group by selection.

You can select one simple type element from the input data to the Group transform.

The value of the simple type element is used to collate occurrences of the repeating input.

Define when the transform is applied at run time

You can define multiple connections between input elements and the Group transform. You can then use these input elements in a conditional expression that defines the condition under which the transform is applied. If the condition evaluates to true, the transform is applied.

Alternatively, to define the conditional expression, you can call a static method on an imported Java™ class. You can also create a complex expression comprising XPath, Java and extension functions such as iib:getUserDefinedProperty("propertyname").

You configure the expression in the Condition tab that is available in the Properties page of the transform.

For more information, see Configuring the properties of a transform, Defining an XPath conditional expression for a transform and Defining a Java conditional expression for a transform.

You can use the input connected with a primary connection to the transform. To add more inputs, you can define supplement connections between input elements and the transform.

Example

You can use the Group transform to map a single list of company employee records into a nested list of employees by department.

The input to the Group transform is the repeating array EMPLOYEE.

The output to the Group transform is the repeating array Department.

The schema file that contains the schema for the repeating array EMPLOYEE is the following:


<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:employee="http://www.ibm.com" targetNamespace="http://www.ibm.com">
    <element name="SQLResult">
        <complexType>
            <sequence>
                <element ref="employee:EMPLOYEE" minOccurs="0" maxOccurs="unbounded"/>
            </sequence>
        </complexType>
    </element>

    <element name="EMPLOYEE">
        <complexType>
            <sequence minOccurs="1" maxOccurs="1">
                <element ref="employee:NAME" minOccurs="1" maxOccurs="1"/>
                <element ref="employee:SALARY" minOccurs="1" maxOccurs="1"/>
                <element ref="employee:BONUS" minOccurs="1" maxOccurs="1"/>
                <element ref="employee:COMM" minOccurs="1" maxOccurs="1"/>
                <element ref="employee:DEPARTMENT" minOccurs="1" maxOccurs="1"/>
            </sequence>
        </complexType>
    </element>

    <element name="NAME" type="string"/>
    <element name="SALARY" type="string"/>
    <element name="BONUS" type="string"/>
    <element name="COMM" type="string"/>
    <element name="DEPARTMENT" type="string"/>
</schema>

The schema file that contains the schema for th repeating array Department is the following:


<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:se="http://www.ibm.com" targetNamespace="http://www.ibm.com">
    <element name="Company">
        <complexType>
            <sequence>
                <element ref="se:Department" minOccurs="1" maxOccurs="unbounded"/>
            </sequence>
        </complexType>
    </element>

    <element name="Department">
        <complexType>
            <sequence minOccurs="1" maxOccurs="1">
                <element ref="se:Name" minOccurs="1" maxOccurs="1"/>
                <element ref="se:Employee" minOccurs="1" maxOccurs="unbounded"/>
            </sequence>
        </complexType>
    </element>

    <element name="Employee">
        <complexType>
            <sequence minOccurs="1" maxOccurs="1">
                <element ref="se:Name" minOccurs="1" maxOccurs="1"/>
                <element ref="se:Salary" minOccurs="1" maxOccurs="1"/>
                <element ref="se:Bonus" minOccurs="1" maxOccurs="1"/>
                <element ref="se:Comm" minOccurs="1" maxOccurs="1"/>
            </sequence>
        </complexType>
    </element>

    <element name="Name" type="string"/>
    <element name="Salary" type="string"/>
    <element name="Bonus" type="string"/>
    <element name="Comm" type="string"/>
</schema>

The following figure shows the map with a Group transform defined between EMPLOYEE and Department.

This figure shows the input and output to a Group transform.

In the General tab of the Properties view for the Group transform, you select DEPARTMENT:string. Then, click Add to include it in the Group by selection. The value of DEPARTMENT is used to collate occurrences of EMPLOYEE.

This figure shows the Properties tab of a Group transform.

Next, you open the nested map associated to the Group transform. You define the mappings to set the output elements of Department.

This figure shows the nested map of a Group transform.

When you run the following input message:


<?xml version="1.0"?>
<employee:SQLResult xmlns:employee="http://www.ibm.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com Employee.xsd ">
  <employee:EMPLOYEE>
    <employee:NAME>SAM HIGH</employee:NAME>
    <employee:SALARY>52750.00</employee:SALARY>
    <employee:BONUS>1000.00</employee:BONUS>
    <employee:COMM>4220.00</employee:COMM>
    <employee:DEPARTMENT>DEVELOPMENT</employee:DEPARTMENT>
  </employee:EMPLOYEE>
  <employee:EMPLOYEE>
    <employee:NAME>SALLY TANGO</employee:NAME>
    <employee:SALARY>38250.00</employee:SALARY>
    <employee:BONUS>800.00</employee:BONUS>
    <employee:COMM>3060.00</employee:COMM>
    <employee:DEPARTMENT>HUMAN RESOURCE</employee:DEPARTMENT>
  </employee:EMPLOYEE>
  <employee:EMPLOYEE>
    <employee:NAME>JOHN SMITH</employee:NAME>
    <employee:SALARY>40175.00</employee:SALARY>
    <employee:BONUS>800.00</employee:BONUS>
    <employee:COMM>3214.00</employee:COMM>
    <employee:DEPARTMENT>DEVELOPMENT</employee:DEPARTMENT>
  </employee:EMPLOYEE>
</employee:SQLResult>

You get the following output message:


<io:Company xmlns:io="http://www.ibm.com">
<io:Department>
  <io:Name>DEVELOPMENT</io:Name>
  <io:Employee><io:Name>SAM HIGH</io:Name><io:Salary>52750.00</io:Salary><io:Bonus>1000.00</io:Bonus><io:Comm>4220.00</io:Comm></io:Employee>
  <io:Employee><io:Name>JOHN SMITH</io:Name><io:Salary>40175.00</io:Salary><io:Bonus>800.00</io:Bonus><io:Comm>3214.00</io:Comm></io:Employee>
</io:Department>
<io:Department>
   <io:Name>HUMAN RESOURCE</io:Name>
   <io:Employee><io:Name>SALLY TANGO</io:Name><io:Salary>38250.00</io:Salary><io:Bonus>800.00</io:Bonus><io:Comm>3060.00</io:Comm></io:Employee>
</io:Department>
</io:Company>