Quickstart: new external system

Get a new external system from scaffold to uploaded, validated, and test-ready using the Builder CLI — without relying on the wizard as the only path.

Why it matters

Integrators need a repeatable CLI ladder: scaffold folder → author or copy JSON → validate in tight loops → upload → test. The wizard can accelerate OpenAPI import, but production integrations are maintained through create, repair, and validate.

Prerequisites

Developer workstation setup complete
aifabrix auth status succeeds (run aifabrix login if needed)
Tenant ACTIVE and dataplane reachable for your environment
OpenAPI spec file or MCP endpoint URL (for system JSON)

How to set

Path A — CLI-first (primary)

Scaffold the integration folder

aifabrix create <systemKey> --type external

Creates integration/<systemKey>/ with application.yaml, env.template, and placeholders for system and datasource JSON. Copy a known-good fixture from your org’s integration library and trim keys — do not start from an empty {}.

Register resource types in the catalog

Every datasource requires a top-level resourceType catalog key:

aifabrix resource-type list
aifabrix resource-type create --key customer --display-name "Customer"
aifabrix resource-type create --key document --display-name "Document"

See Entity basics, types, and resource type. Catalog sync to the dataplane may lag — re-list after create before upload.

Author system and Business Entity JSON — one file per entity under integration/<systemKey>/. Required root bands: key, displayName, systemKey, entityType, resourceType, plus recordStorage companions (primaryKey, metadataSchema with externalId, fieldMappings, sync, exposed). Build recipes: record storage entity, document storage entity.
Align auth and manifest lists

aifabrix repair <systemKey> --dry-run
aifabrix repair <systemKey> --auth apikey
aifabrix repair <systemKey> --rbac --expose
aifabrix json <systemKey>

Many CRM OpenAPI specs default to OAuth — use --auth apikey when you use a private app key. See Configure authentication.

Validate locally

aifabrix validate <systemKey>
aifabrix datasource validate <datasourceKey>

Fix schema errors before upload. See Validation, schemas, and repair.

Upload and test

aifabrix upload <systemKey> --probe
aifabrix test-integration <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>

See Test ladder and protection.

Govern and certify (before production AI)

Add business policies (dimensions and protection), protection manifests and upload, then:

aifabrix verify-governance <systemKey> --subject-email <email>
aifabrix verify-operations <systemKey>
aifabrix verify-trust <systemKey>

Path B — Wizard accelerator (optional)

When OpenAPI or MCP import saves time:

aifabrix wizard
# or: aifabrix wizard --config path/to/wizard.yaml

Then run steps 2–7 above — wizard output still needs repair, resource types, field mappings, and governance. See AI Wizard overview.

Defaults and examples

Minimal system fragment (extend with your OpenAPI path or MCP URL):

{
  "key": "my-system",
  "displayName": "My System",
  "type": "openapi",
  "authentication": {
    "method": "apikey",
    "credential": "my-system/apiKey"
  },
  "openapi": {
    "specPath": "./openapi.yaml"
  }
}

Minimal recordStorage datasource fragment (add fieldMappings, sync, and exposed before upload):

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

Artifact	Typical path
System JSON	`integration/<systemKey>/<systemKey>-system.json`
Datasource JSON	`integration/<systemKey>/<datasourceKey>.json`
RBAC	`integration/<systemKey>/rbac.yaml`
Deploy manifest	`integration/<systemKey>/<systemKey>-deploy.json`

Files affected

integration/<systemKey>/
  application.yaml
  <systemKey>-system.json
  <datasourceKey>.json
  env.template
  rbac.yaml
  <systemKey>-deploy.json

Limits

This quickstart assumes one external system key and at least one datasource. Multi-datasource CRM + document library setups follow the same ladder per datasource file. Catalog and upload behavior depend on controller sync — confirm resource-type list before blaming validate errors on JSON shape alone. Wizard output is a draft — always run repair and datasource validate before upload. When integration fails after a green local validate, compare uploaded manifest with local JSON using aifabrix show <systemKey> --online before re-running E2E.

Documentation Index