Groovy Scripting in SAP Integration Suite: Complete Developer Guide

Groovy scripting is the primary way to add custom logic to integration flows in SAP Integration Suite (formerly SAP CPI). When standard components — Content Modifier, Message Mapping, Router — can’t express the business logic you need, a Groovy script steps in. With it you can transform payloads, read and write headers and exchange properties, handle exceptions, call external APIs, log custom trace data, and control iFlow execution at runtime.

This guide covers Groovy fundamentals for SAP Integration Suite developers: what Groovy is, how to add it to an iFlow, the most common use cases with code examples, and practical tips from our integration consultants.

Table of Contents

What Is Groovy? Key Features for SAP Integration Suite

Groovy is a dynamic, JVM-based scripting language that combines the power of Java with a concise, readable syntax. In SAP Integration Suite, Groovy scripts run inside the Script step of an integration flow and receive the SAP Message object — giving full programmatic access to the payload, headers, and exchange properties of the message being processed.

Key features that make Groovy ideal for SAP CPI scripting:

Java compatibility: Any Java library available in the Integration Suite runtime can be imported and used in Groovy scripts.
Dynamic typing: Variables are declared with def; type resolution happens at runtime, reducing boilerplate code.
Native XML and JSON support: Groovy provides built-in XML slurper and JSON parser classes that simplify message parsing without external libraries.
SAP Message API: Access to the com.sap.gateway.ip.core.customdev.util.Message class for reading and modifying payload, headers, and properties.
Compact syntax: Significantly less code than equivalent Java, which matters for maintainability in large integration landscapes.

How to Add a Groovy Script to an SAP Integration Suite iFlow

Open your integration flow in the Integration Suite Design editor.
From the palette, drag a Script step into the flow sequence where custom logic is needed.
In the Script step properties, choose Groovy Script as the script type.
Click the script editor icon to open the inline editor, or upload an external .groovy file.
Write or paste your Groovy code. The mandatory entry point is the processData(Message message) method.
Save and deploy the iFlow to test the script in the monitoring.

Tip: Use groovyide.com/cpi to test and validate Groovy scripts against a CPI-compatible sandbox before deploying to your tenant. This eliminates the slow deploy-run-check cycle during development.

Groovy Script Structure: The processData Method

Every Groovy script in SAP Integration Suite must implement the processData method. This is the entry point called by the integration runtime when the Script step executes:

import com.sap.gateway.ip.core.customdev.util.Message
import java.util.HashMap

def Message processData(Message message) {
    // Your custom logic here
    return message
}

The method receives the current Message object and must return it (modified or unchanged) after processing. The integration flow proceeds with the returned message.

Most Common Groovy Scripting Use Cases in SAP Integration Suite

1. Read and Modify the Message Payload

def Message processData(Message message) {
    def body = message.getBody(java.lang.String) as String
    // Modify the body string as needed
    def modifiedBody = body.replace('OldValue', 'NewValue')
    message.setBody(modifiedBody)
    return message
}

2. Read and Set Headers

def Message processData(Message message) {
    def headers = message.getHeaders()
    def contentType = headers.get('Content-Type')
    // Set a new header
    message.setHeader('X-Custom-Header', 'MyValue')
    return message
}

3. Read and Set Exchange Properties

def Message processData(Message message) {
    def properties = message.getProperties()
    def orderNumber = properties.get('OrderNumber')
    // Write a new property for use in downstream steps
    message.setProperty('ProcessedOrderNumber', orderNumber + '-PROCESSED')
    return message
}

4. Custom Logging — Capture Payload in Trace

By default, message payloads are only visible in trace mode. Use the message log API to capture custom data at any log level:

import com.sap.gateway.ip.core.customdev.util.Message
import java.util.HashMap

def Message processData(Message message) {
    def body = message.getBody(java.lang.String) as String
    def messageLog = messageLogFactory.getMessageLog(message)
    if (messageLog != null) {
        messageLog.addAttachmentAsString('Payload Snapshot', body, 'text/plain')
    }
    return message
}

This is especially useful for debugging production issues without enabling full trace mode on the iFlow.

5. Parse and Transform XML Payload

import com.sap.gateway.ip.core.customdev.util.Message

def Message processData(Message message) {
    def xmlPayload = new XmlSlurper().parseText(message.getBody(java.lang.String) as String)
    def orderID = xmlPayload.OrderID.text()
    message.setProperty('OrderID', orderID)
    return message
}

6. Parse JSON Payload

import com.sap.gateway.ip.core.customdev.util.Message
import groovy.json.JsonSlurper

def Message processData(Message message) {
    def json = new JsonSlurper().parseText(message.getBody(java.lang.String) as String)
    def customerId = json.customer.id
    message.setProperty('CustomerID', customerId.toString())
    return message
}

7. Throw a Custom Exception for Error Handling

import com.sap.gateway.ip.core.customdev.util.Message

def Message processData(Message message) {
    def status = message.getProperty('ResponseStatus')
    if (status != '200') {
        throw new Exception("Upstream system returned error status: ${status}")
    }
    return message
}

The thrown exception triggers any Exception Subprocess configured in the iFlow, allowing structured error handling and alerting.

8. Stop an iFlow Execution Conditionally

import com.sap.gateway.ip.core.customdev.util.Message
import com.sap.it.api.exception.IgnoreMessageException

def Message processData(Message message) {
    def flag = message.getProperty('SkipProcessing')
    if (flag == 'true') {
        throw new IgnoreMessageException()
    }
    return message
}

The IgnoreMessageException terminates the iFlow cleanly with a Completed status and no error, useful for conditional processing logic.

Groovy vs JavaScript in SAP Integration Suite

SAP Integration Suite supports both Groovy and JavaScript as scripting languages. For most integration developers, Groovy is the preferred choice because:

Groovy is built on Java and has full access to Java libraries available on the runtime — JavaScript has more limited library access.
Groovy has native, first-class XML and JSON support through XmlSlurper and JsonSlurper — common tasks in integration.
Developers with an SAP PI/PO background will find Groovy syntax familiar; UDF (User-Defined Function) logic from PI/PO message mapping translates well to Groovy scripts in CPI.
The SAP community and most learning resources focus primarily on Groovy examples.

JavaScript remains useful if your team has strong JS expertise or if you’re doing light string manipulation that doesn’t require Java library access.

Advanced Tips and Best Practices

Reuse scripts with Script Collections: SAP Integration Suite supports Script Collections — packages of shared Groovy scripts that can be referenced across multiple iFlows in the same package. This avoids duplicating common utility functions.
Performance: Avoid heavy processing inside scripts when a standard component (Value Mapping, Message Mapping) can do the job more efficiently. Script steps that process large payloads in a loop are common performance bottlenecks.
Security: Never hardcode credentials or API keys inside Groovy scripts. Use User Credentials or Secure Parameter stores and access them via the ITApiFactory API.
Error visibility: Always catch exceptions in Groovy scripts that call external services or parse untrusted input. Uncaught exceptions surface as generic PROCESSING_FAILED errors that are hard to diagnose.
Version control: Store Groovy scripts as external .groovy files in a Git repository alongside your iFlow transport exports for full change history.

Frequently Asked Questions

What is the entry point method in a Groovy script for SAP Integration Suite?

The required entry point is def Message processData(Message message). The SAP integration runtime calls this method when the Script step executes. The method must return the Message object after any modifications. Additional helper methods can be defined in the same script but are called from processData.

How do I access message properties in a Groovy script?

Use message.getProperties() to retrieve a map of all exchange properties, then access individual values with .get('PropertyName'). To set a property: message.setProperty('PropertyName', value). Headers are accessed with message.getHeaders() and set with message.setHeader('HeaderName', value).

Can I use Java libraries in Groovy scripts in SAP CPI?

Yes. Standard Java libraries available on the Integration Suite runtime (Java SE classes, SAP-provided APIs) can be imported with standard import statements. You cannot add arbitrary third-party JAR files; only libraries bundled with the Integration Suite runtime are available.

What is the difference between Groovy scripting in message mapping vs in a Script step?

In message mapping (Graphical Mapping), Groovy is used to write custom User-Defined Functions (UDFs) that transform individual field values during mapping. In a Script step, Groovy operates on the entire message object — payload, headers, and properties — outside of mapping. Script steps are more powerful but also more complex; use them for logic that cannot be expressed in standard mapping functions.

How do I debug Groovy scripts in SAP Integration Suite?

Three approaches: (1) Enable Trace level logging on the iFlow during development and inspect message processing steps in the Monitor. (2) Use the messageLogFactory API to attach custom snapshots to the message log at any log level without requiring trace mode. (3) Use an external Groovy IDE (groovyide.com/cpi or IntelliJ IDEA with the CPI stubs) to test script logic locally before deploying.

References

Enes Varinli

SAP PI/PO & SAP Integration Suite (CPI) Consultant
Enes Varinli is an integration consultant who works on the analysis, design, and implementation of end-to-end ERP integrations between SAP and non-SAP systems and third-party applications. He focuses on developing sustainable and scalable integration architectures that are centered on business processes.