cpi-iflow-development

name	cpi-iflow-development
description	SAP CPI iFlow development — integration flow design, Groovy scripting, XSLT/Message mappings, content modifier, router, ZIP packaging, deploy via MCP. Use when creating CPI iFlows, writing Groovy scripts for CPI, packaging iFlows as ZIP, deploying to SAP CPI tenant, or debugging CPI message processing failures.
trigger	["CPI iFlow development","Groovy script CPI","integration flow design","XSLT mapping","message mapping","content modifier","router pattern","iFlow ZIP packaging","deploy iFlow","CPI message processing","XmlSlurper","value mapping API","exception subprocess"]

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_TENANT_URL, CPI_TOKEN_URL, CPI_CLIENT_ID, CPI_CLIENT_SECRET
• Groovy 2.4+ syntax knowledge (CPI uses Nashorn engine, ECMAScript 5.1 dialect)
• Access to CPI Web UI for monitoring and trace

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">
      
      60000
    
    
      
      
    
  
  
    ${destination.S4HANA}/sap/opu/odata/sap/Z_ORDER_SRV
  

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

There is no automated Groovy linter in this repo — review the script by hand against these rules before packaging:

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

Step 6 — Deploy to CPI Tenant

# List packages: call MCP tool mcp__mcp-integration-suite__packages
# Deploy iFlow: call MCP tool mcp__mcp-integration-suite__deploy-iflow
# Check messages: call MCP tool mcp__mcp-integration-suite__get-messages
# Check runtime: call MCP tool mcp__sap-cpi-mcp__cpi_logs (message processing logs)

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
• Groovy execution timeout: 5 min
• External call timeout: 10 min
• Max parallel branches: 50

Pitfalls

• Groovy Sandbox blocks file I/O — Cause: CPI runs Groovy in Nashorn sandbox, new File() is blocked. Solution: Use Data Store or Header/Property for persistence.
• XmlSlurper vs XPath — Cause: javax XPath is restricted in sandbox. Solution: Use new XmlSlurper().parseText(body) for XML navigation.
• 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().
• Groovy timeout on large payloads — Cause: 5-min script timeout. Solution: Split long operations across multiple iFlow steps; use Splitter for batch processing.
• Hardcoded credentials — Cause: Passwords in Groovy scripts. Solution: Use Secure Parameters or OAuth2 credentials from Security Material.

Verification

1. Lint passes: Call MCP tool cpi_lint (Hermes MCP) on all scripts and flow.xml — zero errors
2. ZIP validates: Packager validate command exits 0
3. Deploy succeeds: Call Integration Suite MCP get-messages or Hermes MCP cpi_mcp — artifact 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