Mapping a target element from database tables

To map a target element from a database table, set up the Mapping node to:
  • retrieve the relevant rows from the database
  • populate the message target elements with values from database
There are a number of ways to add a database as a source for a mapping, as described in Adding a database to the source. After you have added a database to the mapping, the Spreadsheet pane contains a $db:select entry in the Map Script column. By default, its value is fn:true(), which means that all rows are retrieved from the database table. In database SQL, you would restrict the number of rows by adding a WHERE clause to a database call. In the Mapping node the equivalent method of restricting the number of selected rows is to use a $db:select expression.

These steps show the equivalent method of restricting the number of rows selected in a Mapping node:

  1. In the Spreadsheet pane, click the $db:select row. This causes fn:true() to be put into the Edit pane.
  2. Edit the expression in the Edit pane to specify the correct condition for the database call. To help you achieve this, you can:
    1. Select any database columns that are relevant to the rows that are retrieved, and drag them from the Source pane to the Edit pane. These are the database column names that are used in an SQL WHERE clause.
    2. Select any source message elements with values that are relevant to the rows that are retrieved, and drag them from the Source pane into the Edit pane. These are values against which the selected database columns can be matched.
    3. Open Content Assist by clicking Edit > Content Assist.
    4. From Content Assist, select the functions to apply to message elements in the database call.
Here is an example of a $db:select entry where a database column is matched against a constant or a field from an input message:
$db:select_1.BROKER50.JDOE.RESOLVEASSESSOR.ASSESSORTYPE = 'WBI' or $db:select_1.BROKER50.JDOE.
RESOLVEASSESSOR.ASSESSORTYPE = $source/tns:msg_tagIA81CONF/AssessorType 

A $db:select entry retrieves all qualifying rows, so it is possible that more than one row is retrieved. By default, the selection is treated as repeating, which is indicated by the ‘for’ row below $db:select in the Spreadsheet pane.

After you have configured the $db:select, populate the target message from the database by dragging the database column from the Source Pane to the message element in the Target pane. The mapping is indicated by a line between the database column in the Source pane and the element in the Target pane. An entry for this map in Xpath format also appears in the Spreadsheet pane. Triangular icons appear in the Source and Target panes next to objects that have been mapped.

Start of changeUsing database selects

By default a $db:select entry is accompanied by a 'for' row that iterates over the select result set. Ensure that your 'for' row is in the correct position for your mapping. The behavior of the map is determined by the position of the 'for' row in the Spreadsheet pane. For example, if the results of the $db:select statement matched 5 rows in the database and the 'for' row is located above the $target entry in the Spreadsheet pane, then 5 complete messages are output by the mapping node. If the 'for' row is positioned within the message body, then one message is generated with 5 repeating elements in the message body.

A mapping can contain multiple 'for' rows associated with a $db:select entry that perform a single database select and iterate over the results multiple times. For example, multiple 'for' rows can be used in conditional mappings, where an individual 'for' row is used with a 'condition' or an 'else'.

A 'for' row is not always required and can be deleted in the following circumstances:
  • If the database select returns only one row
  • If you use an aggregate Xpath function on the select results

    For example: fn:sum or fn:count.

Any $db:select expression must be within the scope of the $db:select entry in the Spreadsheet pane, meaning that it must be a descendant of the select statement. If a $db:select expression is out of scope the Message Mapping editor moves the $db:select entry to a position where the $db:select expression is in scope. Ensure that the position of the $db:select entry is correct for your messsage mapping.

Database table join

Database table join is supported for tables within the same database. For example, consider the following two tables where PRODUCT_ID and PART_NUMBER match:
Table    Column        Row 1    Row 2    Row 3      Row 4
ORDER    PRODUCT_ID    456      456      345        123
         QUANTITY      100      200      300        400

PRODUCT  PART_NUMBER   123      456      789        012
         PART_NAME     pen      pencil   paperclip  glue
         PRICE         0.25     0.15     0.02       0.99
A $db:select expression with the following syntax joins the tables:
$db:select.MY_DB.SCHEMA1.ORDER.PRODUCT_ID=$db:select.MY_DB.SCHEMA2.PRODUCRT.PART_NUMBER
The $db:select expression in the example generates the following result set:
                Row 1    Row 2    Row 3
PRODUCT_ID      456      456      123
QUANTITY        100      200      400
PART_NUMBER     456      456      123
PART_NAME       pencil   pencil   pen
PRICE           0.15     0.15     0.25
You can then use the 'for' row to iterate through the results set in the same way as results from a single table.
End of change
Related concepts
Message Mapping editor
Creating message mappings
Related reference
Mapping node
Message Mapping editor Source pane
Message Mapping editor Target pane
Message Mapping editor Edit pane
Message Mapping editor Spreadsheet pane
Message mappings