Create an integration

An external integration is a Builder-managed folder that registers one external system and one or more datasources — the unit of work for making a vendor system part of Enterprise Knowledge.

Why it matters

AI Fabrix organizes enterprise reality by systemKey and datasource key. Creating the integration folder correctly ensures validate, upload, test, and certification commands target the right artifacts. One integration folder equals one external system; multiple datasources model different business entities (customers, deals, documents) under that system.

For the full end-to-end walkthrough, start at Create an enterprise external system. This page focuses on scaffolding the folder and first validation.

Prerequisites

Builder CLI installed; aifabrix auth status green
Sandbox systemKey chosen (lowercase, stable)
Optional: clone reference fixtures from your org integration library

Where it lives

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

Local files are source of truth until upload. If cloud and folder drift, use aifabrix download <systemKey> then repair.

How to set

Create the folder:

aifabrix create <systemKey> --type external
cd integration/<systemKey>

Copy a known-good fixture — record or document datasource JSON from your library; set root key, displayName, systemKey, entityType, resourceType, primaryKey, indexed externalId.
Edit system JSON — nested authentication, roles, connectivity hints (Connected System basics and kind).
Align env.template — kv:// secret paths only.
Generate deploy bundle:

aifabrix json <systemKey>
aifabrix validate <systemKey>
aifabrix repair <systemKey> --dry-run
aifabrix repair <systemKey> --rbac --expose

Follow quickstart ladder — Quickstart: new external system through upload and test.

Optional OpenAPI/MCP import may accelerate step 2 — always repair auth, RBAC, and expose flags before publish (AI Wizard overview).

Defaults and examples

File	Role
application.yaml	App key, external integration manifest, datasource file list
`<systemKey>-system.json`	Authentication, roles, OpenAPI/MCP config
`<datasourceKey>.json`	`entityType`, field mappings, foreign keys, sync/CIP, exposure
env.template	Secret references — never commit raw secrets
`<systemKey>-deploy.json`	Generated deploy manifest

Example application manifest fragment:

externalIntegration:
  schemaBasePath: .
  systems:
    - example-crm-system.json
  dataSources:
    - example-customers.json

Example datasource identity band:

{
  "key": "example-customers",
  "displayName": "Customers",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"]
}

Validate

aifabrix validate <systemKey>
aifabrix repair <systemKey> --dry-run
aifabrix test-integration <systemKey>

Repair fixes common drift: missing datasource entries in application.yaml, wrong systemKey on datasources, auth-only vars in configuration, metadataSchema out of sync with attributes.

Common mistakes

Mistake	Fix
Skipping fixture copy	Start from known-good JSON
Multiple systems in one folder	One `systemKey` per folder
Secrets in committed JSON	`kv://` in env.template only
Validate once then edit many files	Re-run after each datasource change

Limits

This page scaffolds the folder — modeling business metadata, protection, and certification follow Developer journey and linked build articles.

Import tools produce drafts — they do not replace repair --rbac --expose, resource type registration, or governed exposed configuration before upload --probe.

Treat systemKey as permanent — renaming after upload requires coordinated lifecycle operations (Lifecycle).

Keep application.yaml datasource file lists synchronized with disk — orphan JSON files fail validate with confusing paths until repair reconciles lists. After adding a datasource file, run json <systemKey> before first upload so deploy bundles include new keys.

Document hand-edits in your team changelog when process requires audit — repair logs do not replace human change records for regulated industries.

First upload --probe should run only after validate and repair --expose on a fresh scaffold — skipping repair produces probe failures that look like platform permission errors.

Name datasource key values for stable certification history — renaming after protection upload requires coordinated manifest and scenario pack updates.

Documentation Index