Groovy Loops and Collections in SAP CPI: A Practical Guide for Integration Developers

If you have spent any time writing Groovy scripts inside SAP Cloud Platform Integration, you already know that sooner or later every script comes down to two things: looping through data and organizing that data into a structure you can actually work with. Whether you are transforming an incoming XML payload, enriching a JSON message with employee records, or building a dynamic routing condition, loops and collections are the backbone of almost every non-trivial Groovy script you write in an iFlow.

This guide walks through Groovy's loop constructs and its three core collection types — lists, maps, and ranges — the way you would actually use them inside a SAP CPI Script step. Rather than treating this as abstract programming theory, every concept here is tied back to the kind of message processing you will encounter in a real integration project: iterating over employee records, building dynamic payloads, filtering data, and transforming values before they move to the next step in the flow.

If you are completely new to scripting inside CPI, it helps to first get comfortable with the message object and the processData method — our beginner's guide to Groovy scripting in SAP CPI covers that foundation in detail. Once you understand how a script reads and writes the message body, headers, and properties, loops and collections are the next logical step, because that is how you actually manipulate the data sitting inside that message.

Why Loops Matter in SAP CPI Integration Flows

An integration flow rarely deals with a single record. A SuccessFactors extract might contain a thousand employee records. An order confirmation from an e-commerce platform might carry fifty line items. A batch IDoc might bundle hundreds of materials. Standard mapping steps and the Content Modifier are excellent for simple, one-to-one field assignments, but the moment you need to repeat the same logic across every item in a payload, you need a loop.

Without loops, you would have to write separate code for every single record — process employee one, then employee two, then employee three, and so on. That approach breaks down completely once the record count becomes dynamic, which it almost always is in production. A loop lets you write the processing logic once and apply it to however many records happen to be in the payload at runtime, whether that is five or five thousand.

This is exactly why Groovy, not the graphical Message Mapping tool, becomes the right choice whenever conditional repetition is involved. If you want a clearer picture of when to reach for Message Mapping versus Groovy, our graphical mapping tutorial explains that decision in more depth. As a rule of thumb: simple field-to-field mapping belongs in the mapping tool, and anything involving loops, conditions, or dynamic values belongs in a Groovy script.

Groovy Loop Types Used in SAP CPI Scripts

Groovy supports the same fundamental loop structures you would find in Java, C#, or Python, but it simplifies the syntax considerably. Understanding when to use each type will save you from writing overly complex or inefficient scripts.

The Classic for Loop

The traditional for loop is the right tool when you know exactly how many iterations you need to run. It follows the familiar pattern of an initial value, a condition, and an increment step.

for (int i = 1; i <= 5; i++) {
    println(i)
}

This loop starts with i equal to 1. As long as the condition i <= 5 evaluates to true, the block runs, printing the current value of i, and then increments i by one. Once i reaches 6, the condition becomes false and the loop exits. The output here is 1, 2, 3, 4, 5.

You will reach for this pattern in CPI scripts when the number of iterations is fixed and known ahead of time — for example, generating a sequence of dummy records for testing, or repeating a fixed set of validation checks a set number of times.

The for-in Loop for Iterating Over Lists

Far more common in real integration scenarios is the for-in loop, which is used to walk through every item in a list without needing to know the size in advance.

def employees = ["Sai", "Ravi", "Priya"]

for (emp in employees) {
    println(emp)
}

Here, employees is a list of names. The loop takes each element from the list — Sai, then Ravi, then Priya — and executes the block for each one. This is the pattern you will use constantly when processing repeating nodes extracted from an XML payload or entries pulled out of a JSON array, since incoming messages almost never have a fixed, predictable size.

Range-Based Loops

A range loop is a compact way of iterating between two numeric boundaries. In Groovy, a range like 1..10 represents every integer from 1 through 10 inclusive.

for (i in 1..10) {
    println(i)
}

The variable i takes on every value between 1 and 10, and the loop body runs once for each value. If you needed to process the first thousand records in a batch, you could define the range as 1..1000 and let the loop handle the iteration count for you, rather than hardcoding it. This is particularly useful in CPI when you need to generate sequence numbers, batch identifiers, or simply cap how many records a script processes in a single run.

The while Loop

Unlike for and range loops, a while loop does not rely on a known number of iterations. Instead, it keeps running as long as a condition remains true, and stops the moment that condition becomes false.

def i = 1
while (i < 5) {
    println(i)
    i++
}

In this example, the loop checks whether i is less than 5 before every iteration. It prints the current value and increments i, repeating until the condition fails. The output is 1, 2, 3, 4. while loops are useful in CPI scripts when you are polling for a condition to change — for example, retrying a transformation until a payload passes validation, or processing records until a specific flag or sentinel value appears in the data.

The each Closure

Groovy's each method is arguably the most idiomatic and most frequently used looping construct you will see in production CPI scripts. It is a closure-based approach that guarantees every single item in a collection is processed, with no skipping.

def employees = ["Sai", "Ravi", "Priya"]

employees.each {
    println(it)
}

Inside the closure, the implicit variable it represents the current element being processed. The each method loops through the entire list from start to finish — first Sai, then Ravi, then Priya — with no gaps. Because it reads cleanly and requires very little boilerplate, each tends to be the default choice for looping over lists and maps inside SAP CPI scripts, especially when you are simply transforming or logging every item rather than applying complex conditional logic.

each with Index

Sometimes you need not just the value but also its position within the list. Groovy provides eachWithIndex for exactly this case.

employees.eachWithIndex { employee, index ->
    println("${index}: ${employee}")
}

This prints each employee's name alongside its zero-based position in the list — index 0 for the first element, index 1 for the second, and so on. In practice, this construct is used less often than plain each, since most CPI transformation logic cares about the value itself rather than its position. It becomes useful, though, when you need to generate sequential identifiers or reference the position of an element for logging and troubleshooting purposes.

Controlling Loop Execution: break and continue

Not every loop needs to run to completion, and not every iteration needs to execute fully. Groovy provides two keywords that give you finer control over how a loop behaves mid-execution.

break: Exiting a Loop Early

The break statement immediately stops the loop and exits, without processing any remaining iterations.

for (i in 1..10) {
    if (i == 10) {
        break
    }
    println(i)
}

Here, the loop prints values 1 through 9. The moment i equals 10, the break statement fires and the loop exits before printing that value. In an integration scenario, you might use break to stop processing a payload the instant you detect a critical error, rather than continuing to loop through records that no longer matter once the error condition is hit.

continue: Skipping the Current Iteration

Where break exits the loop entirely, continue skips only the current iteration and moves on to the next one, leaving the rest of the loop intact.

for (i in 1..10) {
    if (i == 3) {
        continue
    }
    println(i)
}

This prints every number from 1 to 10 except 3. When i equals 3, continue skips the print statement for that iteration and jumps straight to the next value. This pattern is genuinely useful in CPI scripts when a specific record in a payload is invalid or incomplete — rather than halting the entire message, you can skip that one record and continue processing the rest, which is often exactly the kind of resilient behavior production integrations need.

Collections in Groovy: List, Map, and Range

Loops become far more powerful once you pair them with Groovy's collection types. A collection, unlike a single variable, can hold multiple values under one reference. Groovy gives you three primary collection types, each suited to a different kind of data.

Lists: Ordered Collections of Values

A list stores data in a fixed order, indexed starting from zero. It is the most common structure you will encounter when working with repeating elements in an SAP CPI payload, such as a list of line items or employee records.

def employees = ["Sai", "Ravi", "Priya"]

Accessing elements by index is straightforward:

println(employees[0])   // prints Sai

Adding values to a list uses the add method:

employees.add("Nithin")

Removing values works similarly:

employees.remove("Nithin")

Checking size tells you how many elements the list currently holds:

println(employees.size())   // prints 3

Checking membership with contains returns a boolean, which is especially useful for validation logic:

println(employees.contains("Ravi"))   // prints true

Sorting and reversing are built in as well:

println(employees.sort())     // alphabetical order
println(employees.reverse())  // reversed order

Beyond basic manipulation, Groovy lists come with two methods that are genuinely useful in transformation scripts: find and findAll. The find method returns only the first element matching a condition, while findAll returns every matching element.

def numbers = [10, 20, 30, 40]

println(numbers.find { it > 20 })     // returns 30, the first match
println(numbers.findAll { it > 20 })  // returns [30, 40], every match

Understanding this difference matters in real scripts — using find when you actually need every matching record is a common source of bugs, since you will silently lose data after the first match.

Finally, the collect method transforms every element in a list according to a given expression, returning a brand-new list without modifying the original:

def salary = [10000, 20000, 30000]
println(salary.collect { it * 2 })   // [20000, 40000, 60000]

This pattern is extremely common in CPI scripts when you need to apply a calculation — currency conversion, tax adjustment, or unit conversion — across every value extracted from a payload.

Maps: Key-Value Collections

While a list is ordered by position, a map stores data as key-value pairs, which is a natural fit for structured data like employee or customer records.

def employee = [id: "001", name: "Sai", country: "India"]

Accessing values can be done with either dot notation or bracket notation:

println(employee.name)      // prints Sai
println(employee["name"])   // also prints Sai

Adding a new key-value pair:

employee.department = "IT"

Updating an existing value:

employee.country = "USA"

Removing a key:

employee.remove("department")

Maps are especially relevant in CPI when you are working with the message object itself, since headers and exchange properties in SAP CPI are essentially map-like structures — you set and retrieve them using a key, much like you would with a Groovy map. If you have not yet worked through how the message object, headers, and properties fit together, our Groovy scripting fundamentals guide is a good companion resource before diving deeper into map manipulation.

Ranges: Sequential Values

A range represents a sequence of values from a starting point to an ending point, and it is what powers range-based for loops discussed earlier.

def numberRange = 1..10
def letterRange = 'a'..'f'

println(numberRange)   // 1 to 10
println(letterRange)   // a to f

Ranges are not limited to numbers — Groovy also supports character ranges, which can be handy for generating sequential codes or labels. In an integration context, ranges are most often used to control how many records a loop should process, or to generate a sequence of identifiers when the target system expects sequential numbering.

Putting It Together: A Realistic SAP CPI Scenario

Consider a common integration requirement: an incoming payload contains a list of employee records, and you need to process only those employees whose salary crosses a certain threshold, adding a calculated field to each qualifying record before the message moves to the next step.

def employees = [
    [name: "Sai", salary: 45000],
    [name: "Ravi", salary: 38000],
    [name: "Priya", salary: 52000]
]

def result = []

employees.each { emp ->
    if (emp.salary > 40000) {
        emp.grade = "A"
        result.add(emp)
    }
}

println(result)

This script combines a map (each employee record), a list (the overall collection of employees), and the each closure (to loop through every record) with a conditional check inside the loop. This is precisely the pattern you will encounter in real Script steps — looping through a collection extracted from XML or JSON, applying business logic conditionally, and building a new structure to pass downstream. It is also a good illustration of why Groovy earns its place over graphical mapping the moment conditional, repeated logic enters the picture.

Common Mistakes to Avoid

A few mistakes show up repeatedly in Groovy scripts written by developers who are newer to the language:

Confusing find and findAll. Using find when the requirement actually calls for every matching record silently drops data, since find only ever returns the first match.

Using for loops when each would be cleaner. A classic indexed for loop works, but for straightforward iteration over a list, each is more readable and less prone to off-by-one errors, since you never have to manage the index manually.

Forgetting that ranges are inclusive on both ends. A range like 1..10 includes both 1 and 10, which sometimes catches developers off guard if they are expecting the upper bound to be exclusive, as it is in some other languages.

Overusing break and continue for logic that should be a condition. These keywords are useful, but leaning on them too heavily inside deeply nested loops can make a script harder to follow. Where possible, a clean conditional check is easier to maintain than multiple exit points scattered through a loop.

Modifying a list while iterating over it. Adding or removing elements from a list inside an active each or for-in loop can produce unpredictable results. It is safer to build a new list, as shown in the employee example above, rather than mutating the original collection mid-loop.

Best Practices and Performance Considerations

When you are processing large payloads inside a CPI Script step, a few habits will keep your scripts both correct and performant:

• Prefer each and findAll over manually indexed loops for readability and fewer bugs, unless you specifically need the classic for loop's counter behavior.
• Avoid nested loops over large collections where possible, since the cost multiplies quickly with payload size. If you find yourself looping inside a loop over thousands of records, consider whether the transformation can be restructured or handled earlier in the flow.
• Use contains and find for validation checks rather than writing manual loops to search for a value, since Groovy's built-in methods are both cleaner and less error-prone.
• Keep loop bodies focused. A loop that does too much — validation, transformation, and logging all at once — becomes harder to debug when something goes wrong with a specific record.
• Log meaningfully but sparingly inside loops. Logging every single iteration in a payload with thousands of records can slow down message processing and clutter the monitoring logs in the Integration Suite cockpit.

For the official language reference on these constructs, the Apache Groovy documentation is the most reliable source, and SAP's own guidance on scripting inside Cloud Integration is available on the SAP Help Portal. The SAP Community is also a good place to see how other integration developers have solved similar looping and collection challenges in production iFlows.

Conclusion

Loops and collections are not an advanced side topic in SAP CPI Groovy scripting — they are the everyday tools you reach for the moment a payload contains more than one record, which is to say, almost always. Knowing when to use a for loop versus each, how lists differ from maps, and how break and continue change loop behavior gives you the vocabulary to write scripts that are both correct and easy for the next developer to read. Once these fundamentals feel natural, the next step is usually working with XML structures directly inside Groovy scripts, since most real CPI payloads arrive as XML before any transformation happens.

Frequently Asked Questions

1. What is the difference between a for loop and a for-in loop in Groovy?
A for loop uses a counter with a defined start, condition, and increment, and is best when you know the exact number of iterations. A for-in loop iterates directly over the elements of a collection, such as a list, without needing to track a counter manually.

2. When should I use each instead of a for loop in SAP CPI scripts?
Use each when you simply need to process every item in a list or map without skipping any elements. It is more concise and readable than a manually indexed loop and is the more common pattern in production CPI scripts.

3. Is a Groovy range inclusive of both endpoints?
Yes. A range written as 1..10 includes both 1 and 10. If you need to exclude the upper bound, you would need to adjust the range accordingly, since Groovy does not provide a separate exclusive-range operator by default.

4. What is the difference between find and findAll in Groovy?
find returns only the first element that matches a given condition, while findAll returns every element that matches. Using the wrong one is a common source of missing data in transformation scripts.

5. How is a Groovy map different from a list?
A list stores values in a specific order and is accessed by numeric index. A map stores data as key-value pairs and is accessed by key, which makes it a natural fit for structured records like employee or customer data.

6. What does the break statement do inside a loop?
break immediately terminates the loop, skipping any remaining iterations entirely. It is typically used when a condition is met that makes further looping unnecessary, such as detecting a critical error in a payload.

7. What does continue do differently from break?
continue skips only the current iteration and moves on to the next one, while break exits the loop completely. continue is useful when a single record should be skipped without stopping the processing of the rest of the collection.

8. Can I loop through an XML payload directly using these Groovy constructs?
Yes. Once an XML payload is parsed into a Groovy object, its repeating nodes typically behave like a list, which means you can use each or for-in to iterate over them just as you would with any other list.

9. Why does Groovy use each instead of traditional loops so often in CPI scripts?
each reads more naturally, requires less boilerplate, and reduces the risk of common indexing mistakes. Since most CPI transformation logic simply needs to process every item in a collection, each fits that requirement cleanly.

10. What happens if I modify a list while looping over it with each?
Modifying a list's contents while actively iterating over it can lead to unpredictable behavior, including skipped or duplicated elements. The safer approach is to build a separate result list, as shown in the employee grading example, rather than changing the original list mid-loop.

11. Are Groovy collections case-sensitive when checking values with contains?
Yes. Groovy's contains method performs an exact match, which means it is case-sensitive by default. If you need a case-insensitive check, you would need to normalize the case of both the collection and the value before comparing.

12. Is eachWithIndex commonly used in real SAP CPI projects?
Not as often as plain each. Most transformation logic cares only about the value of each element rather than its position, so eachWithIndex tends to be reserved for specific cases like generating sequential identifiers or detailed logging.