Press CTRL+K to open search

Entity basics, types, and resource type

  • Updated on Sep 13, 2026
  • Published on Jun 29, 2026
  • 3 minute(s) read
  • MR
  • EB
 Prev Next

Set entityType and root resourceType on each Business Entity manifest so sync, storage, RBAC, and AI exposure follow the correct contract.

Prerequisites

  • Connected System type chosen (Basics and kind)
  • One JSON file per Business Entity under integration/<systemKey>/
  • Builder CLI authenticated — aifabrix auth status green

Where it lives

<datasourceKey>.json → top-level entityType, resourceType, key, displayName, systemKey.

Manifest keys: key, displayName, systemKey, entityType, resourceType — all top-level, root keys (not nested under any grouping key). Never nest resourceType under fieldMappings.

Builder MCP
Manifest keys key, displayName, systemKey, entityType, resourceType
UI tab Overview / Technical readiness
Help topics section, goldenExamples, goldenExample
Repair hooks fieldMappings, metadata schema alignment

Entity type recipes: Business Entities guides.

How to set

  1. Create or open the entity file — scaffold the Connected System folder first:
aifabrix create <systemKey> --type external
aifabrix repair <systemKey> --dry-run
  1. Classify each Business Entity — what it primarily stores or represents.
  2. Set entityType per schema enum:
entityType Use when Enterprise Knowledge role
recordStorage CRM-style entities (customers, deals, cases); also reference/lookup rows with infrequent change Structured records with metadata
documentStorage Files with metadata, no vector index Document catalog and search
vectorStore Embeddings and semantic search Vector-backed retrieval
messageService Notification channel adapter (Slack, Teams, email) Message service
serviceContract Normalized executable service adapter without persistence — requires metadataSchema, fieldMappings, exposed Governed operations, no record storage
none Orchestration or composition only, no direct storage Composition root

Static reference data (country codes, department lookups, cross-system join tables) is not a separate entityType — model it as recordStorage with a small, infrequently changing row set. See Build a static entity.

  1. Align fieldMappings and sync — record types use business entities; document types emphasize file metadata.
  2. List catalog keys — reuse standard tokens when possible:
aifabrix resource-type list
aifabrix resource-type get --key customer
  1. Create missing catalog keys before first upload:
aifabrix resource-type create --key customer --display-name "Customer" --category business
  1. Set resourceType at the datasource root and validate:
aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>
  1. Continue in entity guides — record storage, document storage, or other guides overview for schema bands beyond identity.

Defaults and examples

Element Purpose Example
entityType Storage and sync model recordStorage, documentStorage
resourceType Business catalog token customer, document, deal
key Entity identifier example-crm-customers
systemKey Parent Connected System Must match system JSON

Example identity fragment:

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

Illustrative classification goals:

  • CRM companies → recordStorage + customer
  • SharePoint library → documentStorage + document
  • reference lookup table → recordStorage (static usage pattern) + catalog key matching business vocabulary

Validate

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

Wrong entityType often surfaces as sync or CIP compile errors — not auth failures. Re-run validate after changing resourceType; protection and subscription filters reference catalog tokens at runtime.

Common mistakes

Mistake Fix
resourceType under fieldMappings Move to root next to entityType
Invented catalog token Create with resource-type create first
Document entity with recordStorage Switch entityType to match storage model
Skipping repair after identity edits repair syncs metadata schema hints
Two table entities with the same resourceType Keep one authority table; add a storageType: view contributor instead

Limits

entityType drives sync bands, CIP templates, and UI tabs — changing it after publish may require re-modeling field mappings and protection. resourceType must exist in the platform catalog before upload; this page shows shape, not every catalog category. Complex multi-entity vendors still use one Business Entity file per governed resource — do not merge unrelated resources into a single JSON file.

One Connected System may publish one authority table plus read-only view contributors of the same resourceType (table list / get; viewpoint named answers). Two table entities of the same catalog type stay forbidden. Public uniqueness is {resourceType, capability} — see Build a viewpoint entity.

Related articles