Configure subscriptions

Connected System subscriptions[] declare platform tasks that run when a normalized event fires (most often after a Business Entity publishes). After upload, the dataplane syncs each entry into persisted subscription rows and optionally runs runOnCreate tasks once.

Use subscriptions to regenerate Enterprise MCP / COM / contract material when provider datasources publish — not as a free-form workflow engine, and not as an arbitrary Role Assistant task DSL.

Prerequisites

• Connected System JSON validates (aifabrix validate <systemKey>)
• Business Entities that the filter will match already declare the same root resourceType tokens
• Configure roles and permissions when filters use roleKeys
• Builder help topic subscriptionGuide for narrative context — trust the schema enums below if help prose conflicts

Where it lives

Manifest section: system.subscriptions. UI: Connected System Subscriptions tab when exposed.

What you can build (V1 schema)

Each entry must include:

Allowed task.type values

Only these platform task types validate on the external-system schema:

Invalid examples (will fail aifabrix validate): roleAssistantTask, runDigitalWorkerTask, or any custom string.

Common event values

Prefer these normalized names (runtime registry):

Do not invent vendor webhook names or wrong prefixes such as platform.record.updated — use record.update.

Filter shape (filter and datasource subscriptionFilter)

All keys optional; empty filter matches broadly (usually undesirable):

Builder MCP

How to set

1. Pick the platform outcome — which allowed task.type should run (usually generateEnterpriseDatasources or a contract regenerate task).
2. Pick the trigger event — for post-publish generation use platform.datasource.published.
3. Scope the filter — list only the resourceTypes (or keys) that should fire the task.
4. Add subscriptions[] on the system JSON — start from a known-good scaffold:

aifabrix create <systemKey> --type external
aifabrix repair <systemKey> --dry-run

5. Author the entry (platform lifecycle pattern):

{
  "subscriptions": [
    {
      "key": "enterprise-mcp-on-provider-publish",
      "displayName": "Enterprise MCP on provider publish",
      "description": "Regenerate enterprise MCP datasources when repository or template providers publish.",
      "event": "platform.datasource.published",
      "filter": {
        "resourceTypes": ["repository", "template"]
      },
      "task": {
        "type": "generateEnterpriseDatasources",
        "version": 1
      },
      "priority": "normal",
      "runOnCreate": true
    }
  ]
}

6. CRM / record Business Entity pattern — same task enum; filter on your catalog tokens:

{
  "subscriptions": [
    {
      "key": "mcp-contracts-on-customer-publish",
      "displayName": "MCP contracts when customers publish",
      "event": "platform.datasource.published",
      "filter": {
        "resourceTypes": ["customer"]
      },
      "task": {
        "type": "generateMcpContracts",
        "version": 1
      },
      "runOnCreate": true
    }
  ]
}

7. Optional: datasource subscriptionFilter — on a Business Entity JSON, mirror the same filter shape when generation inputs must be constrained per entity (role keys, include/exclude system kinds).
8. Validate, then upload:

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

On publish/sync, the dataplane upserts subscription rows from subscriptions[]. When runOnCreate: true, the task runs once after that upsert.

Defaults and examples

Minimal required shape (fails validate without task.type):

{
  "key": "compile-com-on-system-publish",
  "event": "platform.externalSystem.published",
  "task": {
    "type": "compileCom",
    "version": 1
  }
}

Validate

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

Confirm:

1. validate accepts task.type and key pattern.
2. After upload/publish, subscription rows exist for the system (Subscriptions UI or online show, when available).
3. Publishing a matching Business Entity (same resourceType) triggers the intended generator task when runOnCreate or the event path is live.

Common mistakes

Limits

Subscriptions bootstrap platform compile/generate tasks declared in the external-system schema. They do not replace Business Entity sync, protection, or Role Assistant channel install. Experimental fields such as runDigitalWorkerTask, per-entry conditions, triggerPolicy, and deduplicationKeyTemplate were removed from the validated schema — omit them so aifabrix validate stays green. Builder help topic subscriptionGuide may still mention older narrative; when in doubt, follow the task.type enum and event names on this page. Schedule events require platform schedule support in the environment — start with platform.datasource.published for integrator builds. Document each subscription key in operator notes so publish logs map to business intent.