integration-suite

name	integration-suite
description	Use when building integrations on SAP Integration Suite / Cloud Integration: integration flow (iFlow), adapters (HTTPS, SOAP, OData, SFTP, IDoc, JMS, AMQP, ProcessDirect), content modifier, message mapping, router, splitter, gather, content enricher, Groovy or JavaScript script, externalized parameters, security material (User Credentials, OAuth2 Credentials, keystore), exception subprocess, and Message Processing Log (MPL) monitoring.
metadata	{"category":"integration","version":"1.0.0","keywords":["SAP Integration Suite","Cloud Integration","CPI","integration flow","iFlow","adapter","content modifier","message mapping","Groovy script","ProcessDirect","security material","externalized parameters","exception subprocess","MPL","iPaaS"],"related":{"messaging":"SAP Event Mesh and event-driven integration from CAP","remote-services":"S/4HANA / external OData consumed from CAP","btp-destinations":"connectivity and Cloud Connector for on-premise systems","security-auth":"OAuth and principal propagation for inbound/outbound calls"}}

SAP Integration Suite — Cloud Integration Best Practices

Primary reference: https://help.sap.com/docs/integration-suite Cloud Integration: https://help.sap.com/docs/cloud-integration Creating integration flows: https://help.sap.com/docs/integration-suite/sap-integration-suite/creating-integration-flow Integration Flow Design Guidelines: https://help.sap.com/docs/cloud-integration (see "Integration Flow Design Guidelines")

SAP Integration Suite is SAP's open, modular iPaaS. The Cloud Integration capability designs and runs integration flows (iFlows) for application-to-application (A2A), business-to-business (B2B), and business-to-government (B2G) scenarios across cloud, on-premise, and hybrid landscapes.

Anatomy of an integration flow

Sender ──▶ [Start] ──▶ processing steps ──▶ [End] ──▶ Receiver
             (adapter)   Content Modifier          (adapter)
                         Message Mapping
                         Router / Splitter
                         Request-Reply / Script

• Sender / Receiver adapters connect the runtime to systems. Common adapters: HTTPS, SOAP, OData V2, OData V4, IDoc, SFTP, FTP, Mail, JMS, AMQP, AS2/AS4, Kafka, SuccessFactors, Ariba, and ProcessDirect (flow-to-flow reuse).
• Processing steps transform and route the message: Content Modifier, Message Mapping, Router, Splitter, Gather, Content Enricher, Filter, Request-Reply, Script.

Content Modifier — set headers, properties, and body

Use a Content Modifier to shape the message. Prefer exchange properties for values used later in the flow and headers for values sent to the receiver.

Message Header:   X-Correlation-ID   = ${header.SAP_MessageProcessingLogID}
Exchange Property: orderType          = constant: STANDARD
Body:             ${property.mappedPayload}

Groovy script — the message processing API

Scripts implement com.sap.gateway.ip.core.customdev.util.Message. Read/write the body, headers, and properties; return the Message.

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

def Message processData(Message message) {
    // Read the body as a String (streaming-safe types are also supported)
    def body = message.getBody(java.lang.String) as String

    // Read headers and exchange properties
    def headers = message.getHeaders()
    def props   = message.getProperties()

    // ... transform ...
    def transformed = body.trim()

    // Write back
    message.setBody(transformed)
    message.setHeader("X-Processed", "true")
    message.setProperty("status", "OK")
    return message
}

Externalize configuration — never hardcode endpoints

Externalize environment-specific values (URLs, addresses, credential names) so the same iFlow moves cleanly across DEV/TEST/PROD without editing steps.

Address: {{receiver_endpoint_url}}
Credential Name: {{receiver_credential_alias}}

Maintain the values under the iFlow's Externalized Parameters.

Security material — reference secrets, don't embed them

Store secrets centrally under Monitor → Manage Security Material and reference them by name from adapters. Never place passwords, tokens, or keys inside a script or a header.

• User Credentials — basic auth username/password
• OAuth2 Credentials / OAuth2 Authorization Code — token-based outbound auth
• Keystore — X.509 key pairs and certificates for TLS / client-certificate auth

Error handling — Exception Subprocess

Wrap the integration process with an Exception Subprocess so failures are caught, logged, and (optionally) rethrown, instead of failing silently.

[Integration Process]
   └── Exception Subprocess
         [Error Start] ──▶ Content Modifier (capture ${exception.message})
                       ──▶ Script (log / build fault) ──▶ [Error End]

Access the cause with the reserved property ${exception.message} (and the CamelExceptionCaught header for the exception object).

Monitoring

Every processed message produces a Message Processing Log (MPL) in Monitor → Monitor Message Processing. Set custom MPL headers/properties for traceable correlation IDs. Enable payload logging only in non-productive tenants.

Common mistakes to avoid

• ❌ Hardcoding credentials, tokens, or endpoint URLs inside a Groovy script or Content Modifier — ✅ use Security Material + Externalized Parameters
• ❌ Loading huge payloads fully into memory in a script — ✅ split large messages (Splitter) and stream where possible
• ❌ No Exception Subprocess — a failure aborts the flow with no diagnostic context; ✅ always add one and capture ${exception.message}
• ❌ Assuming exactly-once delivery — retries can redeliver; ✅ make receivers idempotent (e.g. key on a correlation ID)
• ❌ Logging full payloads with sensitive data in productive tenants — ✅ disable payload logging or mask fields
• ❌ Duplicating the same logic across iFlows — ✅ extract shared steps into a ProcessDirect-connected flow
• ❌ Setting values as headers when they are only needed internally — ✅ use exchange properties for in-flow state, headers only for what the receiver needs