# Cpi Iflow Development

> 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.

- Skill: `williamcorrea23/cpi-iflow-development` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add williamcorrea23/cpi-iflow-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/williamcorrea23/cpi-iflow-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: williamcorrea23 (https://skillmd.com/u/williamcorrea23)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/williamcorrea23/cpi-iflow-development

---


# 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`
- Groovy 2.4+ syntax knowledge (CPI uses Nashorn engine, ECMAScript 5.1 dialect)
- 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](references/cpi-mcp-tool-contracts.md) before invoking
tenant or local tooling operations. Consult [CPI tooling catalog](references/cpi-tooling-catalog.md)
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:

```bash
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:

```xml
<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:**

```groovy
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

```bash
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:

```bash
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):

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

Run the canonical read-only quality workflow:

```bash
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:

```text
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
- 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. **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