Function Name	Filter
Category	Set
Icon
Description	Filter mapped nodes based on a condition
Inputs	Nodes Nodes to filter Bool Boolean value indicating whether the node meets a condition
Outputs	Result Filtered nodes representing only those returning true results after conditional test. The output takes its type from the input Nodes, see Dynamic Output Values.
Properties	None -

Usage

The Data Mapper Set Filter function allows you to restrict the nodes mapped using a conditional test. Filtering allows you to only map data items that meet a certain condition. By filtering, you can make sure you map only those input values you want mapped, for example those with a particular value, or range of values, within a child element or attribute. To apply the Set Filter function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd, an XML Schema Definition and the following XML data:

<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd

The data models sporting clubs and their members. Some of the elements can appear multiple times. Let's assume that we only want to map active members within each club. To achieve this, we will need to test the "active" value for each "member" element to determine whether it reads "Yes" or not. We will use an Equal function and Constant Value in conjunction with the Filter component. Here is the Data Mapper with Source and Target imported:

Drag the Set Filter function from the Component Palette into the mapping area:

The Set Filter function takes two inputs, representing the nodes to filter and the boolean value.

The Nodes input should be connected to the source item you want to filter, and the Bool input should be connected to the output of the conditional test or a boolean value, which will be either true or false. The output comprises the input nodes that meet the condition, and should be connected to the target item, whether an item in the XML Writer or another component in the Mapper.

Before we can connect our Filter function, we need to carry out the conditional test. Drag an Equal function from the Comparator section onto the Mapper. Connect the "active" output in the XML Reader to the Value 1 input in the Equal function.

Now we need to define the value we want the "active" item to match, so drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose String from the Data Type drop-down list and enter "Yes" as the value.

Connect the Constant output to the Value 2 input in the Equal function.

Connect the Result output of the Equal function to the Bool input of the Filter function.

Now connect the Nodes input of the Filter function to the "member" output in the XML Reader, since this is the item we want to filter.

Now the Filter output is only going to contain those "member" elements whose "active" value matched the "Yes" Constant. Connect the Filter output to the "player" input in the XML Writer.

Finally, connect the remaining inputs and outputs.

We can now execute the transform by pressing Shift-F5 or the Execute button (). The transform is applied and the file we selected as output opens in the editor:

<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Chris Black" is_active="Yes">
   <joined>2005</joined>
   <title>League 2009</title>
   <title>Cup 2007</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
 </team>
 <team t_name="City Netball Team">
  <player p_name="Joanne Smith" is_active="Yes">
   <joined>2005</joined>
   <title>Regional Championship 2007</title>
   <title>National championship 2007</title>
  </player>
  <player p_name="Mary Owens" is_active="Yes">
   <joined>2007</joined>
   <title>National Championship 2008</title>
  </player>
 </team>
</clubs>

The only "player" items in the output are those with "Yes" as their "is_active" value. It is common when mapping data to cut out redundant items, perhaps when upgrading systems and minimizing on storage resources.