// This module is included in the following assemblies:
// as_mapping-data.adoc

[id='applying-conditions-to-mappings_{context}']
= Applying conditions to mappings

In some integrations, it is helpful to add conditional 
processing to a mapping. For example, suppose that you are 
mapping a source zip code field to a target zip code field. 
If the source zip code field is empty, you might want to fill 
the target field with `99999`. To do this, you would specify 
an expression that tests the zip code source
field to determine if it is empty, and if it is empty, 
inserts `99999` into the zip code target field. 

ifeval::["{location}" == "downstream"]
[IMPORTANT]
====
Applying conditions to mappings is a Technology Preview feature only. Technology Preview features are 
not supported with Red Hat production service level agreements (SLAs) and might not be 
functionally complete. Red Hat does not recommend using them in production. 
These features provide early access to upcoming product features, enabling 
customers to test functionality and provide feedback during the development process. 
For more information about the support scope of Red Hat Technology Preview features, 
see link:https://access.redhat.com/support/offerings/techpreview/[]. 
====
endif::[]

The data mapper supports expressions that are similar to a Microsoft 
Excel expressions, but does not support all Microsoft Excel expression 
syntax. A conditional expression can refer to an individual field or to a field that is in a collection.

You can define zero or one condition for each mapping. 

The following procedure gets you started with applying 
conditions to mappings. 

*Note:* After you add a condition to a mapping, the Source and Target transformation options are disabled. You must place any transformations within the conditional expression.

.Prerequisites

* You are mapping fields in a *Data Mapper* step. 
* You are familiar with Microsoft Excel expressions or 
you have the conditional expression that you want to apply 
to a mapping. 

.Procedure

. If data types are not already visible, display them by clicking image:images/integrating-applications/show-types-icon.png[Show/hide types icon].
+
While this is not a requirement for specifying a condition, it is
helpful to see the data types.

. Create the mapping that you want to apply a condition to, or
ensure that the currently selected mapping is the mapping that you 
want to apply a condition to. For example, consider this mapping: 
+
image:images/integrating-applications/first-conditional-mapping.png[lastName and firstName map to customerName]

. In the upper left, click
image:images/integrating-applications/add-condition-to-mapping.png[the Add expression icon] to 
display the conditional expression input field. 
+
In the expression field, the data mapper automatically displays 
the names of the source fields in the current mapping. For example: 
+
image:images/integrating-applications/first-conditional-mapping-expression.png[lastName + firstName]
+
In the expression input field, the order of the source fields is the 
order in which you selected them when you created the mapping. 
This is important because the default mapping behavior is that the 
data mapper concatenates the field values in this order to insert 
the result in the target field. In this example, to create this 
mapping, `lastName` was selected first and then `firstName` was selected. 

. Edit the expression input field to specify the conditional 
expression that you want the data mapper to apply to the 
mapping. Details about supported conditional expressions follow 
this procedure.
+
If you want to include a transformation in a conditional mapping, you must add the transformation to the conditional expression. 
+
As you specify the expression, you can type `@` and start to type the name of a field.
The data mapper displays a list of the fields that match 
what you entered. Select the field that you want to 
specify in the expression. 
+
When you add a field name to the expression, the data mapper adds 
that field to the mapping. For example, consider this conditional 
expression: 

+
image:images/integrating-applications/second-conditional-mapping-expression.png[if(ISEMPTY(lastName), firstName, orderId + phone)]

+
During execution, if the data mapper determines that the `lastName`
field is empty, it maps only the `firstName` field to the target
`customerName` field.  If the `lastName` field contains a value, that is, 
it is not empty, the data mapper concatenates the values in the 
source `orderId` and `phone` fields, and inserts the result in 
the `customerName` field.  
(This example shows how the logic works, but it is probably not a 
useful example because when there is a value in the `lastName` field, 
you most likely want the data mapper to simply perform the 
mapping and not map some other value into the target.)

+
For this example, after you complete entering the expression, 
the data mapping is: 

+
image:images/integrating-applications/second-conditional-mapping.png[lastName firstName orderId phone are mapped to customerName]

+
In the conditional expression, if you remove a field name that is in 
the mapping that the expression applies to, the data mapper removes that 
field from the mapping. In other words, every field name in the mapping
must be in the conditional expression. 

. If mapping preview fields are not already visible, display them 
by clicking image:images/integrating-applications/preview-mapping-icon.png[the Show/Hide Preview Mapping icon]. 

. Type sample data in the source preview input field(s) 
to ensure that the target field or target fields
get(s) the correct value. 

. Optionally, apply transformations to one or more source or target fields in the selected mapping by clicking image:images/integrating-applications/transformation-icon.png[the Transformation icon] next to each field to which you want to apply a transformation and then selecting the desired transformation from the pull-down menu.
+
For example, in the same mapping presented in this procedure, in the
*Mapping Details* panel, you could apply the `Uppercase`
 transformation to the `firstName` field. You can test this by entering
 data in the `firstName` field's preview input field. 

. Edit the conditional expression as needed to obtain the desired result.  

.Supported functions in conditional expressions

* `SELECT(FILTER(source-collection-name, source-field-name1 != 'v1' ), source-field-name2)`
+ 
For a collection with multiple fields, the data mapper filters the values in one source field based on the value of a different source field (in the same collection). For example, if a collection (`person`) contains multiple fields including `name` and `gender`, you can use the following conditional expression to filter the `name` by the value of the `gender` field so that only male names are mapped to the target field:
+
`SELECT(FILTER(person, gender = 'male' ), name)``

* `ISEMPTY(_source-field-name1_ [+ _source-field-name2_])`
+
The result of the `ISEMPTY()` function is a Boolean value. Specify at least
one argument, which is the name of a source field in the mapping that 
you want to apply the condition to. When the specified source field is empty, 
the `ISEMPTY()` function returns true. 
+
Optionally, add the + (concatenation) operator with an additional field, for
example:
+
`ISEMPTY(lastName + firstName)`
+
This expression evaluates to true if both source fields, 
`lastName` and `firstName`, are empty. 
+
Often, the `ISEMPTY()` function is the first argument in an `IF()` function. 

* `IF(_boolean-expression_, _then_, _else_)`
+
When `_boolean-expression_` evaluates to true, the data mapper returns `_then_`. 
When `_boolean-expression_` evaluates to false, the data mapper returns `_else_`. 
All three arguments are required. The last argument can be null, 
which means that nothing is mapped when 
`_boolean-expression_` evaluates to false. 
+
For example, consider the mapping that combines the `lastName` and `firstName` 
source fields in the target `customerName` field. You can specify this 
conditional expression: 
+
`IF (ISEMPTY(lastName), firstName, lastName + ‘,’ + firstName )`
+
During execution, the data mapper evaluates the `lastName` field. 
+
** If the `lastName` field is empty, that is, `ISEMPTY(lastName)` 
returns true, the data mapper inserts only the `firstName` value into the 
target `customerName` field.  

** If the `lastName` field contains a value, that is, `ISEMPTY(lastName)` 
returns false, the data mapper maps the `lastName` value, followed by a comma, 
followed by the `firstName` value into the target `customerName` field. 
+

Now consider the behavior if the third argument in this expression is null: 
+
`IF (ISEMPTY(lastName), firstName, null )`
+
During execution, the data mapper evaluates the `lastName` field. 
+
** As in the previous example, if the `lastName` field is empty, that is, 
`ISEMPTY(lastName)` returns true, the data mapper inserts only the 
`firstName` value into the target `customerName` field.  

** However, when the third argument is null, if the `lastName` field contains 
a value, that is, `ISEMPTY(lastName)` returns false, the data mapper does 
not map anything into the target `customerName` field. 

* `LT(x,y)` or `<(x,y)`
+
The data mapper evaluates `x` and `y` and returns the lower value. 
Both `x` and `y` must be numbers. 

* `TOLOWER(string)`
+
The data mapper converts the specified string to lowercase and returns it. 

.Supported operators in conditional expressions


[cols="1,2"]
|===
|*Operator*
|*Description*

|`+`
|Add numeric values or concatenate string values. 

|`-`
|Subtract a numeric value from another numeric value. 

|`*`
|Multiply numeric values. 

|`\`
|Divide numeric values. 

|`&&` +
And
|Return true if both the left and right operands are true. 
Each operand must return a Boolean value.

|`\|\|` +
Or
|Return true if the left operand is true, or if  the right operand is true, or if both operands are true. Each operand must return a Boolean value. 

|`!`
|Not

|`>` +
Greater than
|Return true if the left numeric operand is greater than the right numeric operand.

|< +
Less than
|Return true if the left numeric operand is less than the right numeric operand. 

|`==` +
Equal
|Return true if the left operand and the right operand are the same. 

|===
