Configure entity configuration

Business Entity configuration[] holds runtime overrides for variables already declared on the Connected System. Each entry is name + value only — entity scope replaces the system default for that variable when CIP, sync, or capabilities run on this datasource.

Use this when one Connected System hosts multiple Business Entities that share connection/auth but need different vendor scope — for example one SharePoint integration with separate document libraries for deals, contracts, and general documents.

Why it matters

Connected System Configure system configuration defines what variables exist (name, location, required, portalInput). Business Entities declare which values differ per entity without duplicating auth, OpenAPI bindings, or CIP pipelines.

System configuration     →  declares SHAREPOINT_SITE_ID, SHAREPOINT_LIST_ID, …
Entity A configuration   →  overrides SHAREPOINT_LIST_ID → deals library GUID
Entity B configuration   →  overrides SHAREPOINT_LIST_ID → contracts library GUID
Entity C configuration   →  (no override) → uses system default list id

At runtime the platform merges system definitions with datasource overrides before resolving {{VARIABLE}} placeholders in CIP steps and OpenAPI paths.

Prerequisites

• Configure system configuration on <systemKey>-system.json with every variable you intend to override
• Entity identity bands complete (key, systemKey, entityType, resourceType, …)
• CIP/OpenAPI paths reference configuration variables with {{NAME}} syntax where appropriate

System vs entity configuration

Validation rejects entity overrides for unknown names, extra fields (location, required, …), or keyvault targets.

Where it lives

Manifest section: datasource.configuration.

Builder MCP

When reading help topic sections, distinguish system.configuration (definitions) from datasource.configuration (overrides).

How to set

1. Declare shared variables on the Connected System

Example — one SharePoint site, default list id, operator fills values at deploy:

{
  "configuration": [
    {
      "name": "SHAREPOINT_SITE_ID",
      "value": "{{SHAREPOINT_SITE_ID}}",
      "location": "variable",
      "required": true,
      "portalInput": {
        "field": "text",
        "label": "SharePoint Site ID"
      }
    },
    {
      "name": "SHAREPOINT_LIST_ID",
      "value": "{{SHAREPOINT_LIST_ID}}",
      "location": "variable",
      "required": true,
      "portalInput": {
        "field": "text",
        "label": "Default document library (list GUID)"
      }
    }
  ]
}

2. Override per Business Entity (name + value only)

Deals library — same site, different list:

{
  "key": "sharepoint-deals",
  "displayName": "Deal documents",
  "systemKey": "sharepoint-crm",
  "entityType": "documentStorage",
  "resourceType": "deal",
  "configuration": [
    {
      "name": "SHAREPOINT_LIST_ID",
      "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

Contracts library:

{
  "key": "sharepoint-contracts",
  "displayName": "Contract documents",
  "systemKey": "sharepoint-crm",
  "entityType": "documentStorage",
  "resourceType": "contract",
  "configuration": [
    {
      "name": "SHAREPOINT_LIST_ID",
      "value": "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
    }
  ]
}

General documents — omit configuration[] to inherit the system default SHAREPOINT_LIST_ID.

Each entity still has its own resourceType, metadata schema, sync band, and CIP operations — only the resolved configuration values change.

3. Reference variables in CIP and OpenAPI bindings

Use {{SHAREPOINT_SITE_ID}} and {{SHAREPOINT_LIST_ID}} in path templates, query parameters, and CIP fetch steps. When execution runs for sharepoint-deals, the platform resolves SHAREPOINT_LIST_ID from the entity override; for sharepoint-documents it uses the system value.

4. Validate and upload

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

After upload, operators can adjust entity-specific values on the Business Entity Configuration tab without changing system-wide defaults.

Runtime merge behavior

For each name in system.configuration:
  if datasource.configuration declares same name AND a stored datasource value exists
    → use datasource-scoped value
  else
    → use system-scoped (or global, when enabled) value

Overrides affect this entity only — sync jobs, webhooks, and capabilities on sibling entities keep their own resolved values.

Defaults and examples

Validate

aifabrix validate <systemKey>
aifabrix datasource validate <datasourceKey>

Validation errors to expect:

Re-run integration/E2E per entity after override changes — a green system validate does not prove each library path resolves correctly.

Common mistakes

Limits

• Override names must match system definitions exactly (uppercase NAME pattern).
• Keyvault-backed system variables cannot be overridden at entity level.
• Entity configuration does not replace documentStorage, sync, or CIP bands — it only changes resolved variable values at runtime.

Related reading

• Configure system configuration
• Build a document storage entity
• Configure data flow (CIP)