AI Wizard overview

The AI Wizard is an optional accelerator for external integrations. It parses OpenAPI or MCP sources, detects system type, generates external system and datasource configs, and validates against schemas before writing files to integration/<systemKey>/.

Primary path: Quickstart CLI-first with aifabrix create and fixture copy. Use the Wizard when OpenAPI/MCP import saves time — not as a substitute for repair, govern, test, and certification work.

Why it matters

Manual JSON authoring is slow and error-prone. The Wizard creates a verified draft — system key, datasources, initial field mappings, and validation hooks — so you refine with repair / validate instead of empty files.

The Wizard does not replace business policy configuration or certification. Expect to repair auth method, RBAC, expose flags, and business metadata after first generation.

Prerequisites

aifabrix auth status green
OpenAPI file/URL or MCP server reachable from dataplane wizard API
Sandbox systemKey (lowercase, stable)

Where it lives

Output under integration/<systemKey>/:

Artifact	Purpose
`<systemKey>-system.json`	Auth, roles, OpenAPI/MCP hints
`<datasourceKey>.json`	`entityType`, initial mappings
`application.yaml`	Manifest and datasource list
`env.template`	`kv://` secret references
`wizard.yaml` / `error.log`	Resume diagnostics (when used)

How to set

Path B — after CLI scaffold exists (recommended order):

Ensure folder exists or run aifabrix create <systemKey> --type external first.
Run import (interactive or headless):

aifabrix auth status
aifabrix wizard
aifabrix wizard <systemKey>
# or headless:
aifabrix wizard --config path/to/wizard.yaml

Repair generated drafts (mandatory for most CRM OpenAPI specs):

aifabrix repair <systemKey> --auth apikey
aifabrix repair <systemKey> --rbac --expose
aifabrix validate <systemKey>

Complete identity bands on each datasource — root key, displayName, systemKey, entityType, resourceType, primaryKey, indexed externalId.
Continue the developer journey from model → govern → certify.

Example post-wizard system fragment (secrets as kv:// only):

{
  "key": "example-crm",
  "displayName": "Example CRM",
  "type": "openapi",
  "authentication": {
    "credential": {
      "method": "apikey",
      "apiKey": "kv://example-crm/apiKey"
    }
  }
}

Defaults and examples

Wizard session flow (dataplane API):

Create or resume wizard session
Parse OpenAPI URL/file or MCP server
Select credentials (optional)
Detect platform type and generate configs
Validate against application, system, and datasource schemas
Save files under integration/<systemKey>/

Situation	Action
CRM OpenAPI → OAuth detected	`repair --auth apikey` for private-app labs
Missing datasource in application.yaml	`repair --dry-run`
Validation fails on auth shape	Nested `authentication.credential` (schema 1.7+)
Empty `exposed` after import	`repair --expose`

Resume after failure uses integration/<systemKey>/wizard.yaml and error.log.

Validate

aifabrix validate <systemKey>
aifabrix test-integration <systemKey>

Wizard output proves schema shape — not live vendor auth, ABAC, or certification. Run integration and E2E before upload --probe.

Common mistakes

Mistake	Fix
Treating wizard as complete integration	Model + govern + cert ladder
OAuth template for API-key vendor	`repair --auth apikey`
Skipping `repair --expose`	Empty MCP/capability surface
Secrets pasted into JSON	`kv://` in env.template

Limits

Headless wizard --config requires YAML your org maintains — labs use interactive wizard or CLI-first fixtures instead. Wizard detection heuristics vary by OpenAPI vendor; always validate after import.

Datasource JSON still requires indexed externalId and top-level resourceType — wizard drafts may omit business metadata you must add before verify-trust.

After wizard import, compare generated datasource list with application.yaml using repair --dry-run — silent omissions are the top cause of validate failures on multi-entity CRM imports.

Headless configs should pin OpenAPI URLs and credential keys explicitly — non-deterministic wizard sessions make CI flaky when wizard.yaml drift is not version-controlled alongside integration JSON.

Documentation Index