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.
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
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.
