Build a static entity

Outcome

When you finish this guide, you have a minimal static external system and business entity — validated, uploaded, and ready to supply dimension or join data for ABAC and records search.

Static datasources hold reference rows your CRM or ERP does not provide — country mappings, department codes, or cross-system keys. They use the same recordStorage contract as vendor-backed datasources so dimensions, protection, and records search treat static rows like any other governed records.

Prerequisites

• Builder CLI login (aifabrix auth status)
• Static data for dimensions understood
• Dimension catalog keys planned (create catalog entries before cross-system ABAC if new keys are required)
• Integration folder writable under your workstation layout

Where it lives

Use type: custom on the external system for static reference data not backed by a vendor OpenAPI spec.

How to set

1. Create external integration scaffold:

aifabrix create <systemKey> --type external

2. Author system JSON — custom system for static mappings (api key or platform auth per your environment template).

3. Add datasource JSON — minimal valid shape:

{
  "key": "case-region-mapping",
  "displayName": "Case Region Mapping",
  "systemKey": "static-reference",
  "entityType": "recordStorage",
  "resourceType": "region-mapping",
  "primaryKey": ["externalId"],
  "labelKey": ["caseId"],
  "enabled": true,
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": { "type": "string", "index": true },
      "caseId": { "type": "string", "index": true, "filter": true },
      "country": { "type": "string", "index": true, "filter": true }
    }
  },
  "fieldMappings": {
    "attributes": {
      "externalId": { "expression": "{{raw.externalId}}", "description": "Stable row key" },
      "caseId": { "expression": "{{raw.caseId}}", "description": "CRM case identifier" },
      "country": { "expression": "{{raw.country}}", "description": "Country for ABAC dimension" }
    }
  },
  "dimensions": {
    "country": { "type": "local", "field": "country" }
  }
}

4. List business entity in application manifest — run repair if file lists drift:

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

5. Validate structure:

aifabrix validate <systemKey>

6. Upload when ready:

aifabrix upload <systemKey> --probe
aifabrix upload <systemKey>

7. Load rows with datasource load — after the business entity is published on the dataplane, import JSON or NDJSON fixtures through bulk record sync (aifabrix datasource load <datasourceKey> --app <systemKey>; use --dry-run first, --file to override the default path):

aifabrix datasource upload reference-countries --app <systemKey>
aifabrix datasource load reference-countries --app <systemKey> --dry-run
aifabrix datasource load reference-countries --app <systemKey> -v

By default, fixture files live under integration/.data/ as {systemKey}-data-{entitySuffix}.json (for example static-reference-data-countries.json for business entity key reference-countries). Override with --file ./path/to/rows.json.

8. Declare cross-system joins — set foreignKeys on CRM or ERP datasources so countryCode (or your normalized field) references the static country catalog. See Cross-system relationships.

9. Reference in ABAC on protected datasources — cross-system expressions join vendor records to static rows and filter on shared dimension keys. See Dimensions and access model.

10. Re-run governance certification when static mappings change visibility for subject-scoped test users — dimension outcomes shift immediately after row updates.

Defaults and examples

ISO country catalog (join key across CRM, ERP, and document systems)

SAP, Salesforce, HubSpot, and other vendors represent country differently — full names, numeric codes, picklist IDs, or optional fields. For ABAC and records search, normalize on a single static catalog keyed by ISO 3166-1 alpha-2 (two-letter codes such as FI, DE, US).

Country catalog datasource (minimal manifest excerpt):

{
  "key": "reference-countries",
  "displayName": "ISO country catalog",
  "systemKey": "static-reference",
  "entityType": "recordStorage",
  "resourceType": "country",
  "primaryKey": ["countryCode"],
  "labelKey": ["name"],
  "enabled": true,
  "metadataSchema": {
    "type": "object",
    "properties": {
      "countryCode": {
        "type": "string",
        "index": true,
        "filter": true,
        "description": "ISO 3166-1 alpha-2 code"
      },
      "name": { "type": "string", "index": true, "filter": true }
    }
  },
  "fieldMappings": {
    "attributes": {
      "countryCode": { "expression": "{{raw.countryCode}} | toUpper | trim" },
      "name": { "expression": "{{raw.name}} | trim" }
    }
  },
  "dimensions": {
    "country": { "type": "local", "field": "countryCode" }
  }
}

Fixture file (integration/.data/static-reference-data-countries.json):

[
  { "countryCode": "FI", "name": "Finland" },
  { "countryCode": "DE", "name": "Germany" },
  { "countryCode": "SE", "name": "Sweden" },
  { "countryCode": "US", "name": "United States" }
]

Load after publish:

aifabrix datasource load reference-countries --app static-reference --dry-run
aifabrix datasource load reference-countries --app static-reference -v

Then declare a foreign key on your CRM customer datasource so metadata.countryCode references reference-countries.countryCode. Records search and ABAC can join customers, documents, and the shared country dimension through the same code.

Export governed rows for diff or backup:

aifabrix datasource export reference-countries --app static-reference --limit 500 -v

Use export after load to confirm rows landed — see Validate loaded data in the dataplane.

Case-to-country mapping (when CRM has no country field)

Use the case-region JSON in step 3 when the vendor system lacks country entirely and you map business keys to countries in a separate static datasource.

When to repair

After adding or renaming business entity files:

aifabrix repair <systemKey> --expose --rbac
aifabrix json <systemKey>

Validate loaded data in the dataplane

After datasource load, confirm what the platform stores by exporting through governed records search — not a database admin dump:

aifabrix datasource export reference-countries --app <systemKey> --limit 500 -v
aifabrix datasource export reference-countries --app <systemKey> --format ndjson --filter '{"countryCode":{"eq":"FI"}}'

Compare export output to your fixture file (row counts, keys, dimension fields). For subject-scoped proof, run export with the same Bearer token you use for verify-governance or records-search checks — not only the integrator token used to load rows.

How access rights apply (load vs export)

Both commands run with your deployment token (Bearer/API key or application token from client credentials). Neither bypasses platform RBAC.

Validate

aifabrix validate <systemKey>
aifabrix datasource validate reference-countries --app <systemKey>
aifabrix datasource load reference-countries --app <systemKey> --dry-run
aifabrix datasource load reference-countries --app <systemKey> -v
aifabrix datasource export reference-countries --app <systemKey> --limit 500 -v
aifabrix datasource validate case-region-mapping --app <systemKey>

Run subject-scoped verify-governance when static rows participate in protection-backed datasources. Confirm records search returns expected scope for a test subject after mapping loads.

Common mistakes

Limits

Bulk load uses the external-data-source:sync permission (bulk sync API). Export uses record:search (governed records search with ABAC). Row limits and batch sizes vary by deployment — confirm with your operator before large loads.

Changing static mapping rows changes ABAC outcomes immediately after sync. Treat updates as production access changes — not informal spreadsheet edits. datasource export under a restricted principal may show zero rows while storage still holds data excluded by ABAC — use -v and subject-scoped tokens when validating protection.