Content Modifier in SAP CPI: Step-by-Step with Real-World Examples

Overview of SAP CPI's Content Modifier

Data virtually never comes in the precise format that the receiving system requires, as every integration developer soon discovers. An order may be delivered by a sender without the reference number that the recipient requests. A request may be rejected by the target API if one header is absent. A value that was only visible in the first message may be required in a step at the end of your flow. The Content Modifier is the step SAP Cloud Platform Integration (now part of SAP Integration Suite on SAP BTP) offers to address these little gaps between what one system offers and what another requires. These gaps are a daily reality of integration effort.

Although it is a simple, modest form in the palette, it may be found in almost all real-world integration flows. Without a mapping or a script, it is capable of adding, remembering, reshaping, and removing information. One of the most important things you can do early on for anyone learning SAP CPI is to fully comprehend this stage. It will make your flows far cleaner than they would otherwise be and save you hours of troubleshooting later in SAP Cloud Integration projects.

Comprehending Message Structure: Headers, Properties, and Body

You must first have a clear mental image of what a message looks like as it moves through an integration flow in order to use the Content Modifier effectively. Because SAP CPI is based on Apache Camel, each message that goes through the runtime is encapsulated in what Camel refers to as an exchange. The body, headers, and exchange attributes are the three components of that exchange that are important to you as a developer.

The message's core is its body. Whether it's an XML purchase order, a JSON customer record, a CSV file with thousands of rows, or a plain text notification, it's the real business content being sent between systems. The term "transforming data" typically refers to altering the body.

Headers are little labels that are affixed to a message. The content type, file name, language code, authorisation token, correlation identification, and other technical or contextual information are carried by them. It is crucial to keep in mind that headers accompany the message. The adapter frequently scans the headers and utilises them to determine how to act when your flow writes to a file server or contacts an HTTP service. As part of the outgoing request, some headers are even transmitted to the receiving system. Headers should therefore be seen as data intended to be viewed and utilised outside of your flow.

Exchange attributes are completely internal, yet they resemble headers in that they are labelled values associated to the exchange. They are never given to the recipient; they only exist while the message is passing through your integration flow. They can be compared to a personal journal that your flow maintains. A property is the ideal location if you need to remember something in between steps but don't want it to stray from the flow.

One of the most frequent causes of confusion for novices is the distinction between headers and properties, therefore it's important to clear this up as soon as possible. Use a header if the value should be visible to the outside world. Use a property if the value is just for your own flow.

Important Characteristics and Applications of the Content Modifier

Three tasks are completed by the Content Modifier in a single phase. It can add or remove headers, add or remove exchange properties, and add new content to the message body. In the step setup, each job has its own tab, and you can use any combination of them simultaneously.

The amount of sources from which the step can derive values is what gives it flexibility. When the value is constant, you can enter a fixed constant. An XPath expression can be used to select a value, like an order number or a customer identity, from an incoming XML payload. When creating a composite value, such as a file name, you can use an expression that mixes text with other headers and properties. You can read from variables saved by previous steps or from an already-existing header or property. Another option is to utilise an externalised parameter, which allows you to modify a value after deployment without changing the flow itself. When the same flow needs to behave differently in development, test, and production environments, that final option is particularly helpful.

These skills automatically lead to the use cases. The Content Modifier is used by developers to replace a large payload with a small request message, add authorisation or content type headers before calling an external API, store an order number early so it can be used in a confirmation message later in the flow, and set the file name before writing to an SFTP server. Additionally, it is used to prepare values that a subsequent router or filter step would rely on and to remove headers that shouldn't leak to the receiver. Many seasoned developers refer to the Content Modifier as the workhorse of SAP CPI since it can tackle a wide range of issues.

Step-by-Step Configuration of the Content Modifier

It's easy to incorporate the Content Modifier into your flow, but there are a few things to pay attention to. To begin, launch your integration flow (iFlow) in edit mode. Open the transformation category from the palette on the left, then choose the Content Modifier. The step will show up in the flow when you click on the process line at the desired execution point.

Position is more significant than it first seem. Only subsequent steps can access a value that you create in the Content Modifier. You will receive an empty result if you attempt to read a header or property before it has been generated. Similarly, if you alter the body too soon, the original payload could not be available when it's needed in a subsequent stage. Before implementing the step, pause to consider the order of your flow.

After the step has been positioned, select it and examine the properties panel located at the bottom of the screen. There are three tabs: the message body, the exchange property, and the message header. Rows are added in the header and property tabs. You select an action for each row, which is often to create but can also be to delete. Next, you enter the value, pick the data type, choose the source type, and give a name. For the most part, the default data type is a string, but you can alter it if you require anything different. Save the flow and launch it once the rows have been configured. The step then executes for each message that reaches that stage of the flow.

Using Exchange Properties

You may control the values that must travel with the message by using the message header tab. The action is the first choice made when a new row is added. When a header is created, its value is set, replacing any heading with the same name that already exists. When an incoming header could confuse the receiving system or reveal information you would prefer to keep private, it is useful to delete it entirely from the message.

You name the header after selecting the action. Be careful, as a lot of adapters search for headers with distinct, well-known names. Exact naming standards are followed by the file name used by an SFTP or file adapter, the content type sent by an HTTP adapter, and the authorisation header required by an API. A little spelling error results in absolutely no error notice. Simply put, the adaptor does something you did not expect and ignores the header.

For fixed values, such as a content type, a constant works well. When the value needs to be extracted from an XML payload, an XPath expression works well; however, you must keep in mind to define any namespaces that the expression depends on. You can create a file name from a prefix, a date, and an order number, for example, by combining text with other data using an expression. If the value has already been recorded, you can also copy it from another header or property. Lastly, administrators can change the value of an externalised parameter without affecting the flow.

One additional thing is worth mentioning. Headers should be brief and informative. Since many HTTP servers place restrictions on the total header size, large values in headers may cause issues with receiving systems and adapters. Store huge items in your body or on a property if you must carry them.

Making Use of Exchange Properties

The header tab and the exchange property tab are nearly identical in appearance and functionality. Anything saved here stays inside the flow, which is the essential distinction. It is never seen by the receiver and is never transmitted by the adaptor.

Because of this, properties are the best place to store internal information like an order number you want to refer to later, a counter used in a loop, a flag that instructs a router on which path to take, or an intermediate calculation result. Once generated, properties remain accessible throughout the entire main flow, even after the body has undergone a full transformation or replacement.

Capturing early and reusing late is the most beneficial habit you can develop with properties. A number of mappings, service calls, and transformations are frequently included in integration processes, and each of them can completely replace the body. You will frequently be let down if you depend on the original payload remaining accessible at the end of the flow. You may prevent them from being overwritten and retrieve them at any time by storing the crucial components in attributes from the beginning. When developers learn this technique, their flows become far less fragile, simpler, and easier to debug.

Changing the Body of the Message

You can replace the entire payload with content you specify using the message body tab. The final payload can be constructed dynamically at runtime by either typing a fixed message or writing text that contains data taken from headers and properties. Without having to create a complete mapping, this is an incredibly rapid method to create brief status updates, simple acknowledgements, or request messages.

The most crucial thing to keep in mind is that altering the body replaces the previous state. The prior payload has vanished and cannot be retrieved at a later stage. Before this stage is completed, save any parts that may be needed later in a property. The most frequent reason of confusing test results, where a flow appears to be missing data that was obviously present at the beginning, is forgetting this criterion.

Small, straightforward payloads work best with the body tab. A mapping step is a preferable option if you need to restructure massive documents in a complex way. Consider the mapping tool as the appropriate option for significant transformation and the content modifier as the appropriate tool for quick, light modifications.

Example 1 in the Real World: Dynamic File Naming

Consider a retail business that uses an SFTP server to communicate daily sales reports to a logistics partner. In order for their system to process files in the proper order, the partner has a rigorous rule: each file name must contain a date and a batch number. The adapter will use a fixed or default name if the file name is left unconfigured, and each day's file will replace the one before it. You will get an irate phone call and the partner will lose data.

This is easily resolved by the Content Modifier. You generate a header in the header tab using the target file name that the file adaptor recognises. You employ an expression for its value that combines the current date, a batch number derived from a property or the payload, and a fixed prefix like the term sales. The SFTP adaptor locates the header when it receives the message and saves the file with that exact name. A distinct file with a clear name is created every day, and the partner's system retrieves them sequentially. A seemingly difficult demand becomes a few-minute activity.

Example 2 in the Real World: Transferring Values Between Integration Steps

Think of a situation involving order processing. An order from a client enters the integration flow. In order to determine totals, the flow first contacts a price service. It then translates the pricing response into a different format, calls an inventory service, and lastly provides the consumer with a confirmation message. The body has been changed multiple times by the time the flow reaches the confirmation stage, and the original order number is nowhere to be found in the message.

Putting a Content Modifier at the start of the flow is the solution. An XPath expression that reads the number from the incoming order is used to fill a property named something like the order number that you create in the property tab. The order number is secure going forward. The consumer receives a confirmation that accurately cites the original order when the flow eventually constructs the confirmation message in the final step, when you make reference to the property in the body. The approach goes unnoticed, yet it makes the flow more dependable. One of the most crucial practices in SAP CPI development is the pattern of storing a value early and using it later.

Example 3 in the Real World: Customising the Payload for API Calls

Let's say that every time a customer's status changes, your business must inform an external CRM. The system offers a REST API that requires a brief, targeted request message with just a new status value and a customer identifier. But the message that enters your flow is a big document with a totally different format and dozens of fields that the external service doesn't care about.

To convert the enormous document into the little request, you could create a complete mapping, but that would be excessive for such a straightforward requirement. You utilise the Content Modifier instead. First, you use XPath expressions to extract the customer identifier and the status from the incoming message in the property tab. Next, you create the new request message in the body tab, placing the two property values in the appropriate places. Lastly, you add a header with the authorisation value and another that informs the recipient that the information is in the expected format in the header tab. The request is clear, accurate, and precisely what the external system requests when it reaches the HTTP adaptor. What may have been a lengthy mapping process is reduced to a brief, legible step that any colleague can quickly comprehend.

Best Practices and Typical Errors to Steer Clear of

Using the Content Modifier is lot simpler with a few good habits. To ensure that anyone who opens your flow months later knows what each header and property does, give them clear and consistent names. Make a conscious decision about whether a value belongs in a header or a property; if in doubt, go with a property to prevent your internal reasoning from coming through. To help your teammates understand your intentions, briefly describe each phase. Instead of hard coding values that vary between situations, use externalised parameters. Lastly, verify that headers, properties, and the body appear exactly as you anticipate at each stage by testing with actual sample messages and using the message processing trail in the monitoring area. You will learn more from seeing the real data at each level than from any documentation.

Once you are aware of the usual mistakes, you may easily prevent them. The first is to save the values you'll need later after overwriting the body. The second is reading a value back and spelling a name incorrectly, which results in an empty result with no error warning. The third is putting the step too late in the flow, which prevents the value from being accessible when you need it. Using the incorrect data type is the fourth, which might lead to subtle errors in subsequent steps. The fifth is overloading headers with big values, which can cause receiving systems and adapters to malfunction. The sixth is not realising that namespaces must be declared for XPath expressions on namespaced XML. Check these six causes first if a value returns empty and you are unable to determine why. The great bulk of issues are explained by them.

Conclusion

Although the Content Modifier might seem like a modest addition to the SAP CPI palette, it has a huge impact on effective integration design. Without writing a single line of code, it enables you to swiftly rebuild payloads, save values in between phases, and shape headers. You can confidently handle a surprisingly wide range of ordinary integration difficulties when you know the difference between headers, properties, and the body and when you adopt basic practices like naming everything clearly and capturing values early. Gaining proficiency with the Content Modifier will make your flows more dependable, readable, and much simpler to manage for years to come, regardless of how experienced you are with SAP CPI.

Join our Whatsapp Chenal for more SAP CPI tips and a must-read guide for SAP integration beginners and professionals.