Configure field observers

Mark first-level metadataSchema fields with observer: true so committed changes to those normalized scalars can wake Enterprise Runtime observation — without treating observer flags as a second sync engine, subscription designer, or webhook payload mapper.

Observers notice governed field changes after persist. They do not replace webhook change signals, sync, or sync bridge.

Prerequisites

Business Entity with entityType that stores records (not none)
Configure metadata and identity understood
Stable externalId and normalized fields via business vocabulary
CIP get (or equivalent refresh path) certified when Runtime must re-read vendor truth after a wake-up

Where it lives

Layer	Location
Schema	`<datasourceKey>.json` → `metadataSchema.properties.<field>.observer`
Materialization	Fields with `index`, `filter`, or `observer` become physical columns
UI	Business Entity metadata / identity surfaces

Manifest section: datasource.metadata.

Builder MCP


Manifest sections	`datasource.metadata`
Help topics	`section`, `goldenExample`, `dependencyGraph`
Repair hooks	`fieldMappings`

Observer does not auto-mark a field filterable or ABAC-eligible. Keep index / filter when search and protection need those behaviors.

How to set

Identify first-level scalar fields whose change should wake Runtime (owner, status, region, amount — not nested objects or arrays).
Set observer: true on those properties in metadataSchema:

{
  "key": "example-customers",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"],
  "labelKey": ["name"],
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": { "type": "string", "index": true },
      "name": { "type": "string", "index": true },
      "status": { "type": "string", "index": true, "filter": true, "observer": true },
      "ownerId": { "type": "string", "index": true, "observer": true }
    }
  },
  "fieldMappings": {
    "attributes": {
      "externalId": { "expression": "{{raw.id}}" },
      "name": { "expression": "{{raw.name}}" },
      "status": { "expression": "{{raw.status}}" },
      "ownerId": { "expression": "{{raw.ownerId}}" }
    }
  }
}

Keep association and write field names on foreignKeys / exposed — observer flags do not declare CIP argument keys. See Configure CIP argument keys.
Publish and validate:

aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>

Prove change signals separately when the Connected System pushes events — observers react to committed normalized metadata, not raw vendor webhook bodies. Pair with Configure webhook change signals when inbound events should refresh knowledge first.

Defaults and examples

Flag	Effect
`observer: true`	Eligible for Runtime observation wake-up after UPDATE persist when the field value changes
`index: true`	Search / storage index eligibility
`filter: true`	Filterability hint for query planning

Illustrative goals:

Watch status so Runtime can re-evaluate work when a record moves states
Watch ownerId when ownership changes should refresh role-scoped context
Do not mark every indexed field as observer — noise reduces signal quality

What observers are not

Not this	Use instead
Inbound vendor event routing	Root `webhook`
Cross-datasource propagation	Root `syncBridge`
Scheduled bulk import	`sync`
Platform task generation on publish	Connected System `subscriptions`
Business thresholds / workflow designer	Out of scope for the observer keyword

Validate

aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>

Expect schema rejection for observer: true on nested objects, arrays, or unsupported entity types. After upload, confirm UPDATEs that change observer fields are eligible for observation; unchanged hashes and cancelled noise windows must not invent Runtime work.

Common mistakes

Mistake	Fix
Treating observer as webhook config	Observer is metadata after persist; webhook is inbound change signal
Observer on nested JSON paths	First-level scalars only
Expecting INSERT to wake Runtime	Observation is for committed UPDATE diffs on observer fields
Skipping CIP get when re-read is required	Certify refresh capabilities before relying on wake-up behavior
Assuming observer implies ABAC filter	Add `index` / `filter` when protection and search need them

When business reality changes — business meaning of watching fields
Configure metadata and identity
Configure webhook change signals
Configure sync bridge
Configure CIP argument keys
Enterprise webhooks

Limits

Observer wake-up availability and debounce behavior vary by deployment. The keyword documents eligibility; it does not create Business Event designers, Observation Index UIs, or Role Assistant subscription editors. Do not document lab vendor field names — resolve association names from the published manifest only.

Documentation Index