Business Entities in this Connected System

Each Business Entity models one governed business resource from a Connected System — customers, contracts, documents, or executable capabilities — listed in the system workspace and configured in the Business Entities band.

Business Entity = datasource + resourceType

Do: treat each Business Entity as one datasource JSON under the Connected System. Its business kind is the root resourceType (catalog token such as customer or deal) — not a separate registry row. This page only covers listing and registering those files; set and validate resourceType on the entity itself — see Entity basics, types, and resource type.

Why it matters

Enterprise Knowledge is built per Business Entity. This page covers listing and high-level structure only; field mappings, sync, and policies are configured per entity in the Business Entities band.

Prerequisites

Connected System JSON with authentication configured
Entity basics, types, and resource type
Stable systemKey on the parent Connected System folder

Where it lives

integration/<systemKey>/
  <datasourceKey>.json    # one file per Business Entity
  application.yaml        # lists every datasource file

Manifest section: system.businessEntities (list in UI; files on disk). The dataplane Business Entities tab mirrors the file list from application.yaml — there is no separate registry outside the integration folder.

Builder MCP


Manifest section	`system.businessEntities`
UI tab	Business Entities (`?tab=datasources`)
Help topics	`connectedSystemUi`, `section`
Repair hooks	datasource file list in `application.yaml`

Per-entity modeling: open the Business Entity in dataplane or edit <datasourceKey>.json — see Business Entities band.

How to set

Scaffold or copy a fixture — start from a known-good pattern for your entityType:

aifabrix create <systemKey> --type external
aifabrix repair <systemKey> --dry-run

Add one JSON file per entity — name <systemKey>-datasource-<slug>.json or follow your fixture convention; set root key, displayName, systemKey, entityType, and resourceType.
Register each file in application.yaml — the dataSources list must include every Business Entity path on disk.
Configure vocabulary and policies in the Business Entities band — identity, sync, and exposure bands live on each entity file.
Repair manifest drift when files were added or renamed manually:

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

Validate the system and each entity:

aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>

Defaults and examples

Element	Purpose	Example
`key`	Entity identifier	`example-crm-customers`
`systemKey`	Parent Connected System	Must match system JSON root
`entityType`	Storage and sync model	`recordStorage`, `documentStorage`
`resourceType`	Business catalog token	`customer`, `document`, `deal`
`application.yaml` entry	File registration	`- example-crm-datasource-customers.json`

Example application.yaml fragment listing Business Entities:

externalIntegration:
  systems:
    - example-crm-system.json
  dataSources:
    - example-crm-datasource-customers.json
    - example-crm-datasource-deals.json

Example minimal Business Entity root:

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

Illustrative goals:

one file equals one governed business resource
systemKey on every entity matches the Connected System folder
repair syncs missing files into application.yaml before upload

Validate

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

Empty Business Entity lists in the UI usually trace to application.yaml drift — not authentication failures. Re-run repair after adding or renaming JSON files; validate <systemKey> before upload when multiple entities changed in the same commit.

Common mistakes

Mistake	Fix
Entity file on disk but missing from `application.yaml`	Run `aifabrix repair <systemKey>`
Mismatched `systemKey` on entity JSON	Align with parent system file
One mega-file for multiple resources	Split into one Business Entity per resource
Skipping entity validate	Run `datasource validate` per file

Limits

This page covers listing and registration only — not field mappings, CIP execution, or certification. Complex multi-library document patterns use per-entity configuration[] overrides; see Configure entity configuration. When entity count grows, keep displayName aligned with operator vocabulary and verify each resourceType exists in the catalog before first upload.

Documentation Index