Message Mapping in SAP Integration Suite - Custom Scripts and Conditional Mapping

[jirifridrich]

I find it useful to look at two capabilities of message mapping, which may seem confusing and may be overlooked for the first-sight complexity - custom functions and graphical conditional mapping - both being configured in the bottom half of the message mapping screen.

Custom Groovy Functions

The standard function library in the Mapping Expression editor already covers a lot of use-cases. Under Standard you get arithmetic, boolean logic, date functions, string operations, conversions, and node functions. For many projects, this is sufficient.

Where the standard library starts to show its limits is when your logic involves multiple conditions chained together, or when you need to validate and reformat values in a way the graphical nodes simply cannot express cleanly.

Writing a Custom Script Function

You can extend the mapping with your own Groovy functions. The function is added directly in the Mapping Expression editor under Scripts.

I chose a simple example of a custom function - the script will transform a date from YYYY-MM-DD format into SAP-native date format YYYYMMDD. This is a trivial functionality and is actually coved by the standard functions (section 'Date'), but the point here is just to show the syntax.
Click 'Create', give the script a name and you will be taken to a Groovy editor.

Delete the placeholder code and the script will then look like this:

import com.sap.it.api.mapping.*
def String date_to_YYYYMMDD(String date) {
    if (date == null || date.trim().isEmpty()) {
        return ""
    }
    // Expected input format: YYYY-MM-DD
    if (!date.matches("\\d{4}-\\d{2}-\\d{2}")) {
        return ""
    }
    // Remove hyphens
    return date.replaceAll("-", "")
}

Import com.sap.it.api.mapping.* is the API package you need for mapping scripts.
Null and empty guard - the very first thing the function does is handle null and blank input.
Input validation before processing - the regex check ensures the function only processes values that actually look like a date. If the source field contains garbage, the function returns empty rather than silently producing a malformed output.
The transform itself - once the value passes validation, removing the hyphens is a one-liner. 

You can even have multiple input parameters or work with nodes, but we keep it simple in this article. You will get the code from any AI tool anyway, so no reason to get too technical. The important thing here to know what is the place for custom logic.

Note: Keep your script functions focused — one function, one responsibility. It makes testing much easier and keeps the mapping readable for the next person who opens it.

Graphical Conditional Mapping

Custom scripts are powerful, but for conditional logic that depends on comparing a source field against a known value, the graphical approach is often cleaner and more transparent. 
We look at a dummy scenario, where the business rule is simple: if PO_NUMBER equals 100500, the recipient should be 100500; for anything else, the default recipient is 100000.

Building the Condition

In the Mapping Expression canvas this is what the setup looks like:

Those blue boxes are standard functions from the left menu, the yellow boxes are fields from mapping - PO_NUMBER is a source field, RECIPNT_NO is a target field, values '100500' and '100000' are constants, which we have to summon from the left-hand-side function menu as well.

The first function is 'equals(string)', which compares two inputs. If the two input values are equal, the result is a boolean 'true'.

The second function is 'if', which receives a boolean condition - if true, returns the 'true value', if false, returns the 'false value'.

Reading the canvas left to right: a constant node with value 100500 and the source field PO_NUMBER both feed into an equals(string1, string2) comparison node. The result of that comparison, together with the constant 100000, feed into an if node — where the comparison result is wired to condition, 100500 goes to true value, and 100000 goes to false value. The output of the if node maps directly to RECIPNT_NO.

No code required. The logic is immediately readable to anyone who opens the mapping editor.

Testing with the Simulate Tool

Once the mapping is defined you want to verify it before deploying. This is where the Simulate feature saves a lot of time. Instead of deploying the iFlow and sending a real message through it, you can test right inside the Mapping editor.

Generating a Test Payload

Click the Generate button to automatically create a dummy input payload based on your source structure.

Every field gets a _sample suffix value so you can immediately identify which source field produced which output. The PO_NUMBER field has been manually changed to 100111 — a value that does not match the constant 100500. The Test Output on the right shows RECIPNT_NO resolved to 100000, confirming the false branch of the condition fired correctly (highlighted by the blue arrow).

The generated payload is fully editable. This is the key point: Generate gives you the structure, and then you adjust individual field values to test specific scenarios without having to author an entire XML document by hand.

Testing the True Branch

Now change PO_NUMBER to 100500 and run the simulation again:

With PO_NUMBER set to 100500, the Test Output immediately shows RECIPNT_NO as 100500. The blue arrow highlights exactly where to confirm the result in the output tree. The condition evaluated true, and the mapping used the matching constant value.

Tips for Using the Simulate Tool Effectively

• Always test both branches of every condition. It is easy to only verify the happy path — set up values that exercise the false branch too.
• Test null and empty inputs. Leave a field blank in the test payload and check that your mapping handles it gracefully, especially for fields that feed into script functions.

Summary

Message Mapping in SAP Integration Suite is more capable than it might appear at first glance. The graphical function library handles conditional logic elegantly without a single line of code. Custom Groovy scripts let you express validation, reformatting and derivation logic that the standard nodes cannot cover. And the Simulate tool with its Generate feature gives you a tight test cycle right inside the editor.

To sum up the best-practice: start graphically, reach for a script only when the graphical approach becomes unreadable, and always validate with Simulate before you deploy.