Skip to main content

Composite Timeline Channel

Composite Timeline Channels let you treat multiple timeline channels as one logical channel. They match if an incoming event would match any child channel (union). They are useful when a single workflow should respond to events from several sources while preserving each child's filtering and recency behavior.

Basic Structure​

contracts:
  aliceChannel:
    type: Timeline Channel
    account: alice@example.com

  bobChannel:
    type: Timeline Channel
    account: bob@example.com

  activityChannel:
    type: Composite Timeline Channel
    channels: [aliceChannel, bobChannel]

The channels field lists contract keys in the same scope. Each child channel is evaluated independently, and the composite delivers one event per matching child in the order listed.

Example: One Workflow, Two Sources​

contracts:
  teacherChannel:
    type: Timeline Channel
    account: teacher@example.com

  studentChannel:
    type: Timeline Channel
    account: student@example.com

  messagesChannel:
    type: Composite Timeline Channel
    channels: [teacherChannel, studentChannel]

  messageWorkflow:
    type: Sequential Workflow
    channel: messagesChannel
    steps:
      - name: RouteMessage
        type: JavaScript Code
        code: |
          const source = event.meta?.compositeSourceChannelKey;

          if (source === 'teacherChannel') {
            return { events: [{ type: 'Teacher Message' }] };
          }

          if (source === 'studentChannel') {
            return { events: [{ type: 'Student Message' }] };
          }

          return { events: [] };

Event Metadata​

When the composite delivers an event, it adds the child channel key to event.meta.compositeSourceChannelKey. Use this value to branch on the originating channel.

Validation Rules​

  • Every entry in channels must reference a channel declared in the same contracts map.
  • Composite channels may reference other composite channels, but cycles are not allowed.
  • If channels is empty or missing, the composite never matches.

Recency and Checkpoints​

Composite channels keep per-child recency by checkpointing each child independently. An older event on one child will not block newer events from another child, and each child channel's own recency rules still apply.