Catching Unknown Headers and Properties in SAP CPI Before They Fail Silently

A header that is never set does not stop an SAP CPI iFlow. The expression that reads it returns an empty value, a Router condition turns false, a field in the payload stays blank, and the message carries on. The error, if there is one, appears several steps later or in the receiving system.

This article explains why missing headers and exchange properties fail silently, the causes that come up again and again, and the checks that catch them before a message does.

Why a missing name does not raise an error

Apache Camel treats a header or property that is not there as empty, not as a mistake. That is convenient for optional values, and it is the reason a typo can live in an iFlow for months. What you see depends on where the name is read:

• A Content Modifier value such as ${property.orderId} becomes an empty string.
• A Router or Filter condition such as ${header.orderType} = 'EXPRESS' evaluates to false, so the message takes another route, often the default one.
• A receiver address such as /orders/${property.orderId} calls /orders/, and the receiving system answers with an error that does not mention the missing property.
• In a Groovy script, message.getHeader("orderId", String) returns null, and the script fails later with a null pointer error, or writes the text null into the payload.

The usual causes

• A typo, or the wrong case in a property name: exchange property names are case-sensitive, so orderID and orderId are two different properties. Header names are not case-sensitive.
• A stray space, for example ${header.orderId }: the name with the space is a different name.
• A value set on only one route of a Router and read after the routes meet again.
• A header sent by the caller but not let in: an HTTPS sender only passes the custom headers listed in Allowed Header(s) under the iFlow's Runtime Configuration.
• A property expected from another iFlow: exchange properties do not cross a ProcessDirect call, only headers do (see the ProcessDirect and JMS article).
• A header row reading a property created in the same Content Modifier, which runs the header table before the property table.

Make a missing value fail loudly

For values the flow cannot work without, fail at the point where they are needed instead of three steps later. A short Groovy step at the start of the flow is enough:

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

def Message processData(Message message) {
    def orderId = message.getProperty("orderId")
    if (orderId == null || orderId.toString().trim().isEmpty()) {
        throw new IllegalStateException("Exchange property orderId is not set")
    }
    return message
}

The message then ends in an error with a sentence that names the missing property, visible in the message processing log. For Router conditions, give the default route a clear purpose: end it in an Error End event when no route should ever be missed, instead of letting the message continue on a path that was meant as a fallback.

While you test, set the iFlow's log level to Trace. The trace shows the headers and exchange properties at each step, so you can see exactly where a value disappears.

A checklist before you deploy

1. List every header and property the iFlow reads: in expressions, conditions, adapter fields and scripts.
2. For each one, find the step that sets it, on every path that reaches the reader.
3. Compare the spelling exactly, including the case for properties and any spaces.
4. For headers that come from the sender, check that they are in Allowed Header(s).
5. For values passed from another iFlow, check that they travel as headers, not properties.

Done by hand, this takes a while on a large iFlow, which is why it is the first check worth automating.

Naming habits that prevent the problem

• Pick one style, such as camelCase, and use it for every header and property in the package.
• Set the values the whole flow depends on in one Content Modifier near the start, so there is one place to look.
• Leave the SAP_ and Camel prefixes to SAP and Apache Camel; give your own names a different shape.
• Use properties for values only this iFlow needs, and headers only for values that must leave it.

The article on Camel Simple expressions explains the syntax behind every name in this list.

How Kitegra helps

The Kitegra browser extension runs this checklist in the SAP Integration Suite designer. Its lint panel flags headers and properties that nothing in the iFlow sets, an unclosed ${ and stray spaces in expressions, before you deploy.

When you type ${ or $, it suggests only names the iFlow defines, including names set in Groovy and JavaScript scripts, plus SAP and Camel standard headers, so a typo is less likely in the first place. A name set on only some paths is marked "set on some paths only". It never saves, deploys or edits an iFlow's content, and your tenant changes only when you click one of four named actions, which can be switched off.

When a value is empty at runtime, tracing the message step by step shows the headers and properties before each step, and the iFlow review checklist covers the design mistakes behind it.

Without an account it works on 5 iFlows per module. The Free plan covers 50, Starter 100 and Pro 300; Business has no limit. Compare the plans.

Try it in your next iFlow

Read what Kitegra does in the SAP Integration Suite designer, or see it next to its modules.

Frequently asked questions