Events

Events are the foundation of Blue document interactions—they flow into documents through channels, trigger workflows, and can be emitted by documents during processing. This page explains how events function within the Blue ecosystem and how documents can both react to and generate events.

The Event Lifecycle

Every Blue document interaction follows this pattern:

1. An event enters a document through a channel
2. Workflows process the event, potentially updating the document state
3. During processing, the document may generate new events
4. Any generated events are included in the processing result
5. Events directed to internal channels are also processed immediately as part of the same cycle

Extending Our Online Lesson Example

Building on the embedded payment document from the previous page, let's configure our lesson document to react to events from the embedded payment:

name: Online Lesson with Payments and Events
type: Online Lesson with Payments

contracts:
  # Channel for payment events
  paymentChannel:
    type: Embedded Node Channel
    path: /payment
  
  # Handler for payment success
  paymentSuccessHandler:
    type: Sequential Workflow
    channel: paymentChannel
    event:
      type: Payment Successful
    steps:
      - name: UpdateLessonStatus
        type: Update Document
        changeset:
          - op: replace
            path: /status
            val: "paid"

In this example, we create a channel that listens for events from the embedded payment document. When the payment document processes a successful transaction, it emits a "Payment Successful" event. Our parent document receives this event through the paymentChannel and updates the lesson status to "paid."

This pattern creates a clean separation:

• The payment document handles transaction processing
• The lesson document manages the overall lesson state
• Events provide the communication bridge between them

Document Update Channels

Document Update events occur whenever a specific path in a document changes. You can listen for these changes using a Document Update Channel:

statusUpdateChannel:
  type: Document Update
  path: /status

This channel emits events whenever the /status field changes. These events include both the old and new values:

type: Document Update
path: /status
before: "pending"
after: "confirmed"

note

Document Update channels only trigger when the exact node at the specified path changes, not when children of that path change. For example, /payment/status changes won't trigger a channel watching /payment.

Notifications

Document Processing Notification is a useful event type that can be used to show messages to user about processing changes:

# Add to our Online Lesson contracts
statusUpdateChannel:
  type: Document Update
  path: /status

# Notification workflow for status changes
statusNotificationWorkflow:
  type: Sequential Workflow
  channel: statusUpdateChannel
  steps:
    - name: CreateNotification
      type: JavaScript Code
      code: |
        // Create appropriate notification based on new status
        const newStatus = event.after;
        const oldStatus = event.before;
        
        let message;
        switch(newStatus) {
          case "confirmed":
            message = "Your lesson has been confirmed! Please complete payment.";
            break;
          case "paid":
            message = "Payment received! Your lesson is fully booked.";
            break;
          default:
            message = `Lesson status changed from ${oldStatus} to ${newStatus}.`;
        }
        
        return {
          events: [
            {
              type: "Document Processing Notification",
              message: message
            }
          ]
        };

This workflow:

1. Listens for changes to the lesson status
2. Creates appropriate notification messages
3. Emits notification events

These notification events are included in the processing result and can be handled by external systems to send emails or other communications.

Event Triggers

The Event Action Trigger contract provides a declarative way to transform events without requiring JavaScript code:

lessonStatusTriggers:
  type: Event Action Trigger
  events:
    - on:
        type: Document Processing Initiated
      emit:
        type: Lesson Created
        createdAt: ${event.timestamp}
    - on:
        type: Document Update
        path: /status
        after: "paid"
      emit:
        type: Lesson Ready
        lessonId: ${document('/id')}
        scheduledTime: ${document('/lessonDate')}

This contract:

• Automatically generates a "Lesson Ready" event when status changes to "paid"
• Emits a "Lesson Created" event when the document is first processed

The Document Processing Initiated event is a system event that fires automatically when a document with no previous checkpoint is processed for the first time.

Trigger Event Step

Events can also be triggered from sequential workflows through Trigger Event step:

- name: SendConfirmation
  type: Trigger Event
  event:
    type: Lesson Confirmation
    message: "Your lesson has been confirmed for ${document('/lessonDate')}"

Error Events

Blue represents errors as events, allowing consistent handling of both normal and error conditions. Error events typically include:

• type: The error category (Validation Error, Processing Error, Fatal Error)
• message: A human-readable explanation
• context: Additional information like affected fields or error codes

Common error types include:

Error Type	Description	Processing Impact
Validation Error	Invalid input data	Processing continues
Fatal Error	Unrecoverable failure	Processing stops

Fatal errors (such as division by zero in JavaScript) stop all processing and prevent document updates, ensuring documents remain in a valid state.

Event Processing Mechanics

When a Blue processor receives an event, it follows this sequence:

1. The event enters through a channel
2. Workflows listening to that channel execute in a deterministic order
3. These workflows may update the document and generate new events
4. Generated events directed to internal channels are processed immediately
5. This cycle continues until all internal events are processed
6. The processor returns:
   • The final document state
   • All generated events