Operations

Operations are named, structured interfaces that documents expose to the outside world. They define specific actions that can be performed on a document, complete with formal request definitions.

The Role of Operations in Blue

Blue documents interact with the world through channels, processing events that arrive through these pathways. Operations build on this foundation by creating well-defined action endpoints within a document.

When to use operations:

• To create clearly named actions that express intent (e.g., approvePayment, scheduleLesson)
• To enforce specific input structures and validation rules
• To organize document capabilities into logical functional units
• To enable discoverability of available actions

Operations provide an organizational layer that helps structure interactions with a document. They create a clear API for document manipulation while working through the same underlying channel mechanisms that power all Blue document interactions.

Defining Operations

Operations are defined using the Operation contract:

increment:
  type: Operation
  request:
    description: Represents a value by which counter will be incremented
    type: Integer

This definition specifies:

1. The operation name (increment)
2. The expected input structure (request)
3. A description for the request

Implementing Operations

Once defined, operations need an implementation. The most common approach is using a Sequential Workflow Operation:

incrementImpl:
  type: Sequential Workflow Operation
  operation: increment
  steps:
    - type: Update Document
      changeset:
        - op: replace
          path: /counter
          val: ${event.value + document('/counter')}

This implementation:

1. Links to the increment operation definition
2. Defines processing steps that execute when the operation is called

The operation's implementation can access:

• The request data via event
• The current document state via document()
• Any other contextual information needed

Invoking Operations

Operations are invoked by sending an Operation Request event to the document's channel:

type: Operation Request
operation: increment  # Name of the operation to call
request: 5           # The increment value
document:
  blueId: 7UEBwTmRMfQ92rGt4vHkzPa8Ypd5KJsLNcA3FV6xDqbn  # Target document ID
allowNewerVersion: true  # Accept if document has changed

Request Formats

The request field can contain:

1. Simple values for primitive types:

   request: 5  # Integer

2. Structured objects for complex types:

   request:
     a: 12
     b: xyz

The request structure must match what's defined in the operation contract. If it doesn't match, the operation won't execute and will return an error.

The allowNewerVersion Flag

The allowNewerVersion flag addresses an important concern: what happens if the document changes between when you retrieve it and when you send your operation?

• true: Process the operation on the latest version, even if it changed
• false: Only process if the document still has the same BlueId as specified

This gives callers control over concurrent modifications:

• Use true when the operation should work regardless of other changes
• Use false when the operation depends on the document being in a specific state

Complete Counter Example

Let's bring everything together with our simple counter example:

name: Simple Counter
counter: 0
contracts:
  ownerChannel:
    type: Timeline Channel
  
  # Defines the increment operation interface
  increment:
    type: Operation
    request:
      description: Represents a value by which counter will be incremented
      type: Integer

  # Implements the increment operation
  incrementImpl:
    type: Sequential Workflow Operation
    operation: increment
    steps:
      - type: Update Document
        changeset:
          - op: replace
            path: /counter
            val: ${event.value + document('/counter')}

When a client wants to increment the counter:

1. It sends an Operation Request to the document's timeline:

   type: Operation Request
   operation: increment
   request: 5
   document:
     blueId: 7UEBwTmRMfQ92rGt4vHkzPa8Ypd5KJsLNcA3FV6xDqbn
   allowNewerVersion: true

2. Any compliant document processor:

   • Receives the request through the ownerChannel
   • Identifies the increment operation and its implementation
   • Executes the Update Document step, adding 5 to the counter

3. The counter is now incremented by 5

Operations in MyOS

You can see the example above in action in the Warm-Up Example from the Quick Start guide: