CIP execution

CIP (Composable Integration Pipelines) is how AI Fabrix runs governed Business Entity operations at runtime — list, get, create, update, delete — with the caller's identity, RBAC/ABAC, and audit context applied before any vendor API is contacted.

Why it matters

Role Assistants and digital workers do not call vendor APIs directly. They request compiled capability keys (customer:read, document:search). CIP is the execution layer that honors those keys: trust checks first, then pipeline steps, then normalized results for evidence and agent metadata.

Without a valid execution block on each exposed Business Entity, certification and live capability requests fail even when OpenAPI import succeeded.

Prerequisites

Business Entity JSON with root capabilities[] and exposed aligned to resourceType
Governed capabilities understood
Green aifabrix validate <systemKey> before integration or E2E tests

Where it lives

Layer	Location
CIP operations and steps	`<datasourceKey>.json` → `execution.cip.operations`
OpenAPI step bindings	Same file → `openapi.operations` (operation keys must match CIP operation names)
Test fixtures for E2E	Same file → `testPayload`
UI editing	Business Entity Data Flow tab (`?tab=cip`)

CIP is per Business Entity, not on the Connected System manifest. System OpenAPI is connectivity/bootstrap only; authoritative vendor contracts live on each entity via externalSpec / openapi.

How to set

Start from generated execution — OpenAPI import usually produces default CIP for standard operations. Extend only when you need transforms, filters, or multi-step calls.
Edit execution.cip.operations — each enabled capability needs steps that reference OpenAPI or datasource fetch sources:

{
  "key": "example-crm-customers",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"],
  "execution": {
    "engine": "cip",
    "cip": {
      "version": "1.0",
      "inputType": "void",
      "outputType": "records",
      "operations": {
        "list": {
          "enabled": true,
          "description": "List customers scoped by ABAC",
          "steps": [
            {
              "fetch": {
                "source": "openapi",
                "openapiRef": "list",
                "query": { "limit": "100" }
              }
            }
          ]
        }
      }
    }
  }
}

Add production-grade testPayload — E2E and integration tests merge CLI flags with manifest fixtures. Without testPayload, capacity/CRUD paths may fail at the config step:

{
  "testPayload": {
    "mode": "live",
    "primaryKey": { "externalId": "e2e-fixture-001" },
    "useCopyForMutations": true,
    "payloadTemplate": {
      "externalId": "e2e-fixture-001",
      "name": "E2E Customer",
      "country": "Finland"
    },
    "expectedResult": {
      "externalId": "e2e-fixture-001",
      "name": "E2E Customer",
      "country": "Finland"
    },
    "scenarios": [
      { "operation": "list", "enabled": true },
      { "operation": "get", "enabled": true },
      { "operation": "create", "enabled": true, "input": { "name": "E2E Customer" } },
      { "operation": "update", "enabled": true, "input": { "country": "Sweden" } },
      { "operation": "delete", "enabled": true }
    ]
  }
}

`testPayload` field	Production practice
`primaryKey`	Concrete values for list/get/mutations; use `primaryKey.search` when resolving a row via list
`payloadTemplate` / `expectedResult`	Shape field mappings and metadata schema before live vendor calls
`scenarios`	Ordered operation evidence for capacity E2E; disable destructive steps in shared tenants with `enabled: false`
`useCopyForMutations`	Default true when create runs — merges returned ids into later get/update/delete in the same run
`mode`	`live` for certification against real test tenants; `mock` for offline unit tests only

Re-validate after execution edits:

aifabrix validate <systemKey>
aifabrix test <systemKey>

Run integration then E2E (test credentials and isolated tenants):

aifabrix test-integration <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey> --test-crud

Use --primary-key-value @pk.json when reusing an existing vendor record. Use --no-run-scenarios to exercise the default capacity path only. Prefer --verify-audit when governance audit proof is required.

Certify operations — green E2E with --test-crud when capabilities mutate external data.

Defaults and examples

Guideline	Reason
Prefer generated CIP first	Matches OpenAPI operations; easier to validate
Keep pipelines entity-scoped	Clear ownership and certification boundaries
Operation keys match capability keys	`list`, `get`, `create`, `update`, `delete` or custom keys aligned with `openapi.operations`
Author `testPayload` before first E2E	Avoids config-step failures when CLI does not pass inline payloads
Re-upload after execution changes	Online drift breaks `verify-operations`

Root identity fields required before execution compiles:

Field	CIP impact
`key`	Pipeline ownership
`systemKey`	Auth and connection context
`entityType`	Sync/normalization path
`resourceType`	Capability and RBAC prefix
`primaryKey`	CRUD identity and `testPayload.primaryKey`

Validate

aifabrix validate <systemKey>
aifabrix test-integration <systemKey>
aifabrix verify-operations <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>

Bypassing capabilities to call vendor APIs directly from agents breaks Operational Trust — route through compiled capability keys and CIP.

Common mistakes

Mistake	Impact	Fix
Missing `testPayload` on exposed entity	E2E config step fails	Add `primaryKey`, template, and scenarios
Custom CIP without E2E	Operations cert fails on live API	`datasource test-e2e --test-crud`
Wrong execution shape (`pipeline` vs `cip.operations`)	Validate errors	Use `execution.engine: cip` and `execution.cip.operations`
OpenAPI ref mismatch	Runtime fetch errors	Align `openapiRef` with `openapi.operations` keys
Bypassing capabilities	Ungoverned AI access	Route through compiled capabilities
Editing CIP without re-upload	Online drift	`upload` + `show --online`

Limits

Advanced step types and orchestration patterns evolve with platform releases. This page covers the integrator path: generated CIP, deliberate extensions, and testPayload for certification — not every internal step catalog entry.

Complex multi-entity orchestration belongs in separate Business Entities linked by foreignKeys[] — do not embed cross-entity joins in one CIP file when governance boundaries differ per entity.

Keep custom steps idempotent when --test-crud runs — certification may create, update, and delete sandbox records in test tenants.

Documentation Index