Configure subscriptions

Declare system subscriptions on the Connected System manifest so normalized record events can bootstrap platform tasks for Role Assistants and digital workers after publish or sync.

Prerequisites

Business Entities published with stable resourceType tokens
Configure roles and permissions aligned with subscription filters
Builder help topic subscriptionGuide when editing through Builder API

Where it lives

Layer	Location
Subscription entries	`<systemKey>-system.json` → `subscriptions[]`
Datasource scoping	Optional `subscriptionFilter` on Business Entity manifests
Runtime	Persisted subscription rows after upload/sync

Manifest section: system.subscriptions. UI tab: Subscriptions on Connected System detail.

Builder MCP


Manifest section	`system.subscriptions`
Help topics	`subscriptionGuide`, `section`, `dependencyGraph`
Repair hooks	—

Read help topic subscriptionGuide before Builder API edits to subscription filters and normalized events.

How to set

Choose normalized events — platform record insert/update/delete or platform.datasource.published; avoid vendor-specific event names in manifest conditions.
Add a subscription entry with unique key, event, optional filter, and task:

{
  "subscriptions": [
    {
      "key": "deal-status-changed",
      "displayName": "Deal status changed",
      "description": "Spawn review task when deal stage updates",
      "event": "platform.record.updated",
      "filter": {
        "resourceTypes": ["deal"]
      },
      "task": {
        "type": "roleAssistantTask",
        "version": 1
      }
    }
  ]
}

Scope resourceTypes to catalog tokens declared on Business Entity roots (deal, customer) — not generic placeholders.
Align foreign keys when subscriptions span linked entities (document library → CRM deal).
Validate and upload:

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

Defaults and examples

Practice	Reason
One key per business trigger	Easier audit and repair
Filter by `resourceTypes`	Prevents cross-entity task storms
Match Role Assistant scope	Same tokens as RBAC and protection
`runOnCreate` sparingly	Platform bootstrap tasks only

Builder API: read system.subscriptions with help topic section before patch; patch with intent describing the business trigger.

Validate

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

Confirm subscription rows appear online after upload when your deployment exposes them.

Common mistakes

Mistake	Fix
Generic `document` filter on CRM library	Use business `resourceType` on the library entity
Vendor webhook names in `event`	Use normalized platform events
Subscriptions before entities publish	Upload datasources first
Missing role mapping	Align `system.rolesPermissions`

Documentation Index