Developer journey

Developers do not only “build a connector.” You make systems, data, and capabilities usable by AI inside Operational Trust, Enterprise Knowledge, Role Assistants, and Evidence Fabrix.

Why it matters

Role Assistants need certified business context and governed capabilities — not raw API access. The developer path turns an external system into business metadata, relationships, protection, execution, and proof.

Prerequisites

Tenant ACTIVE and Builder CLI installed (Developer workstation setup)
Sandbox systemKey and reference fixtures available
Quickstart: new external system for the command ladder

Where it lives

Work happens under integration/<systemKey>/ — system JSON, datasource JSON, application.yaml, env.template, optional integration/.protection/, and generated deploy bundles.

How to set

Follow this CLI-first sequence (OpenAPI import is optional after scaffold):

Scaffold — aifabrix create <systemKey> --type external; copy fixture datasource JSON.
Authenticate — nested authentication.credential on system JSON; aifabrix repair --auth apikey when needed.
Model — root key, displayName, systemKey, entityType, resourceType, primaryKey, indexed externalId on each datasource.
Govern — dimensions, foreignKeys[], protection manifests under .protection/.
Expose — exposed capabilities; repair --rbac --expose.
Validate and test — validate → test-integration → test-e2e.
Publish — upload --probe, upload, show --online.
Certify — verify-operations → verify-trust → verify-governance → lifecycle.

Canonical process (CLI-first):

create + fixtures
  ↓
Authentication + repair
  ↓
External system + datasources (identity bands)
  ↓
Business metadata (fieldMappings, resourceType)
  ↓
Dimensions + foreign keys + protection
  ↓
Governed capabilities + CIP execution
  ↓
OpenAPI and MCP contracts (compiled online)
  ↓
Validation and repair
  ↓
Upload and deploy
  ↓
Certification (three pillars)
  ↓
Lifecycle maintenance

Optional OpenAPI/MCP import accelerates step 1 — see AI Wizard overview (Path B only).

Defaults and examples

Phase	Goal	Key articles
Scaffold	Folder + fixtures	Create integration, Quickstart
Model	Business meaning	Business Entities overview, Configure business vocabulary
Govern	ABAC + links	Configure business policies, Configure roles and permissions
Execute	Capabilities + CIP	Capabilities, CIP
Prove	Tests + cert	Test ladder, Certification
Operate	Drift control	Lifecycle

Example datasource identity band you repeat for every entity file:

{
  "key": "example-customers",
  "displayName": "Customers",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"],
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": { "type": "string", "index": true }
    }
  }
}

Validate

Use CLI workflow reference as the gate checklist. Never stop at verify-trust — operations and governance pillars are required for production AI use.

Common mistakes

Mistake	Fix
Treating import as finished integration	`repair --rbac --expose`, model metadata
Skipping indexed `externalId`	Add to `metadataSchema`
Protection after cert	Upload protection before `verify-governance`
Wizard-only mental model	Start at `create` + fixtures

Limits

This journey map is persona-scoped — it does not replace pillar narratives under Foundation or Operational Trust. Command flags and certification profiles evolve; confirm against CLI reference when debugging 403 or pillar failures.

Record and document storage build recipes live in dedicated model pages — pick entityType before copying fixtures so sync and exposed bands match your Enterprise Knowledge contract.

Each phase in this journey maps to explicit CLI gates — if a step lacks a validate or test command in CLI workflow, you are likely still in narrative-only territory rather than shippable integration work.

Minimum viable proof for a first integration is recordStorage + validate + upload + test-integration — add documentStorage, protection, and certification pillars incrementally rather than blocking first upload on full govern depth.

Use Minimum viable manifest checklist as a printable gate before declaring any systemKey ready for operator review.

Documentation Index