SAP CPI iFlow Development

Full development lifecycle for SAP Cloud Integration (CPI) iFlows — from source code to deployed integration.

Prerequisites

• SAP BTP subaccount with Integration Suite enabled
• Service Key for Process Integration Runtime (OAuth2 client_credentials)
• Environment vars set: CPI_BASE_URL, CPI_OAUTH_TOKEN_URL, CPI_OAUTH_CLIENT_ID, CPI_OAUTH_CLIENT_SECRET
• Identify the target Script step version before writing code. Groovy uses its JVM runtime; JavaScript uses a separate engine. Match imports and syntax to the selected step version; see SAP's Script step documentation.
• Access to CPI Web UI for monitoring and trace

Canonical routing

Route CPI API operations to the reviewed local sap-cpi-mcp first. Use integration-suite-ui-mcp only when API/background access is blocked and a logged-in browser session is available. Never route to disabled community candidates.

Read CPI MCP tool contracts before invoking tenant or local tooling operations. Consult CPI tooling catalog when selecting an optional external adapter.

iFlow ZIP Structure

my-iflow.zip/
├── META-INF/MANIFEST.MF
└── src/main/resources/
    ├── flow.xml                  ← Main integration flow definition
    ├── script/*.groovy           ← Groovy scripts
    ├── mapping/*.xslt            ← XSLT transformations
    ├── mapping/*.mmap            ← Message mappings
    ├── resources/*.xsd           ← EDI/XML schemas
    └── parameters.prop           ← Externalized parameters

Step 1 — Create iFlow Source Files

Create the project directory and core files:

mkdir -p iflows/my-integration-flow/{src/main/resources/script,src/main/resources/mapping}

Write the MANIFEST.MF:

Manifest-Version: 1.0
Bundle-SymbolicName: my_integration_flow
Bundle-Version: 1.0.0
Bundle-Name: My Integration Flow

Step 2 — Write flow.xml

Define sender channel, integration process steps, and receiver channel:

<IntegrationFlow id="my_integration_flow" version="1.0">
  <Sender id="sender_1" type="HTTPS" direction="Inbound">
    <Address>/process/order</Address>
    <Authentication>Basic</Authentication>
  </Sender>
  <IntegrationProcess id="process_1" name="Process Order">
    <ContentModifier id="cm_1" name="Set Headers">
      <Property name="OrderId" source="body" sourceField="orderId"/>
    </ContentModifier>
    <GroovyScript id="script_1" name="Transform Payload"
                  scriptPath="script/process-data.groovy"/>
    <RequestReply id="rr_1" name="Call S/4HANA">
      <Receiver ref="receiver_1"/>
      <Timeout>60000</Timeout>
    </RequestReply>
    <Router id="router_1" name="Route by Status">
      <Condition expression="${property.Status} = 'OK'" targetStep="end_ok"/>
      <Condition expression="${property.Status} = 'ERROR'" targetStep="end_error"/>
    </Router>
  </IntegrationProcess>
  <Receiver id="receiver_1" type="ODataV2" direction="Outbound">
    <Address>${destination.S4HANA}/sap/opu/odata/sap/Z_ORDER_SRV</Address>
  </Receiver>
</IntegrationFlow>

Step 3 — Write Groovy Scripts

XML-to-JSON transform with error handling:

import com.sap.gateway.ip.core.customdev.util.Message
import com.sap.it.api.ITApiFactory
import com.sap.it.api.msglog.MessageLog

def Message processData(Message message) {
    def log = message.getMessageLog()
    try {
        def body = message.getBody(java.lang.String)
        if (!body?.trim()) throw new IllegalArgumentException("Empty body")
        def xml = new XmlSlurper().parseText(body)
        message.setBody("""{"orderId":"${xml.orderId.text()}","customer":"${xml.customer.text()}"}""")
        message.setHeader("Content-Type", "application/json")
        log.setStringProperty("Status", "COMPLETED")
    } catch (Exception e) {
        log.setStringProperty("Status", "FAILED")
        log.addAttachmentAsString("error.txt", e.getMessage(), "text/plain")
        throw e
    }
    return message
}

Value mapping lookup: ITApiFactory.getApi(ValueMappingApi).getMappedValue('COUNTRY_CODES', 'SAP_Internal', 'ISO', countryCode)

Step 4 — Package as ZIP

python scripts/cpi_iflow_packager.py create \
  --name my-integration-flow \
  --flow iflows/my-integration-flow/src/main/resources/flow.xml \
  --scripts iflows/my-integration-flow/src/main/resources/script/process-data.groovy \
  --output iflows/my-iflow.zip

Validate the ZIP structure:

python scripts/cpi_iflow_packager.py validate --input iflows/my-iflow.zip

Step 5 — Lint Before Deploy

Validate the packaged iFlow ZIP (structure, MANIFEST.MF, required files):

npm run cpi:validate -- --input <iflow>.zip

Run the canonical read-only quality workflow:

python scripts/cpi_client.py quality --input <iflow>.zip --engine auto
# MCP equivalent: cpi_quality_check

The built-in structural validator always runs. cpilint runs only when CPILINT_CMD resolves to an installed executable; no download is attempted. Also review Groovy against these rules:

• hardcoded passwords → error
• no exception subprocess → warning
• new File() in Groovy → error
• println() → info (use MessageLog instead)

Step 6 — Deploy to CPI Tenant

Use canonical MCP tools:

cpi_packages -> cpi_artifacts -> cpi_runtime_artifacts
cpi_logs -> cpi_message_details
cpi_deploy_plan -> independent human approval -> cpi_deploy_commit

Treat cpi_deploy_plan as read-only planning. Execute cpi_deploy_commit only with the approved action_id, plan_hash, argument_hash, and precondition_hash. Apply the same sequence to undeploy, iFlow generation, plotting, and Git sync.

Integration Patterns

• Sync Request-Reply: HTTPS → Groovy (transform) → RequestReply (OData) → Groovy (response) → HTTPS response
• Async with Retry: SFTP → ContentModifier (correlation ID) → Router → Groovy → RequestReply (IDoc) → Retry (3x/5min) → SFTP archive
• Splitter-Gather: HTTPS (batch) → Splitter → RequestReply (BAPI per record) → Gather → Groovy (aggregate) → HTTPS response

CPI Constraints

• iFlow design-time size: ~10 MB
• Message size: 100 MB max
• Verify script and adapter timeouts against the target tenant's current limits.
• External call timeout: 10 min
• Max parallel branches: 50

Pitfalls

• Unsupported file I/O or libraries — Groovy runs on the JVM. Follow SAP's scripting guidelines, use supported Cloud Integration APIs, and use Data Store for persistence.
• XML parsing imports — Match the parser import to the Groovy Script step version. For Groovy 4, use groovy.xml.XmlSlurper; see SAP's runtime compatibility guidelines.
• Content Modifier expression syntax — Cause: Wrong variable syntax causes silent failures. Solution: Use ${in.body} not ${message.body}; use ${property.X} for properties.
• Body type mismatch — Cause: Body can be String, InputStream, or byte[]. Solution: Always cast explicitly: message.getBody(java.lang.String).
• Content-Type header lost after transform — Cause: Setting body overrides headers. Solution: Set Content-Type header AFTER calling message.setBody().
• Script timeout on large payloads — Confirm the observed tenant timeout, then split long operations across multiple iFlow steps or use Splitter for batch processing.
• Hardcoded credentials — Cause: Passwords in Groovy scripts. Solution: Use Secure Parameters or OAuth2 credentials from Security Material.

Verification

1. Quality passes: Call cpi_quality_check; structural validation passes and configured cpilint reports no errors
2. ZIP validates: Packager validate command exits 0
3. Deploy succeeds: Use cpi_deploy_plan, obtain independent approval, then call cpi_deploy_commit; cpi_runtime_artifacts shows "Started"
4. Test message flows: Send test payload via HTTPS endpoint, check CPI Web UI → Monitor → Messages for successful processing
5. Trace enabled: CPI Web UI → Monitor → Trace shows input/output payloads at each step
6. Error subprocess works: Inject invalid payload, verify exception subprocess triggers and MessageLog shows "FAILED" status