Contract Package Templates

Contract Package Templates are reusable components that generate multiple contracts based on a set of parameters. They help eliminate code duplication by providing standardized implementations for common patterns in Blue documents. By parameterizing the variable parts while maintaining consistent structure, templates make documents more maintainable, consistent, and easier to create.

Each template follows a standard structure:

1. Parameters - Define what can be customized
2. Generates - Specify what contracts will be created
3. Functions - Optional helper functions for parameter processing

When a processor encounters a contract package template, it expands it into multiple concrete contracts based on the parameter values, allowing complex functionality to be expressed concisely.

Below are package templates every processor must support.

Field Setter

name: Field Setter
type: Contract Package Template
description: Reusable template for setting any field in a document

params:
  fieldPath:
    type: Document Path
    description: Path to the field to set
    required: true
  
  operationName:
    type: String
    description: Name of the operation (e.g., setValue, setAddress)
    required: true
  
  channel:
    type: Channel
    description: Reference to channel contract
    required: true
  
  fieldType:
    type: Type
    description: Type of the field
    required: true
    
  validationExpression:
    type: JavaScript Expression
    description: Optional validation logic (should return true if valid)
    required: false
    
  validationErrorMessage:
    type: String
    description: Error message when validation fails
    default: "Invalid input value"
    required: false

generates:
  - contractName: "${operationName}"
    contract:
      type: Operation
      request:
        type: ${fieldType}
  
  - contractName: "${operationName}Impl"
    contract:
      type: Sequential Workflow Operation
      operation: "${operationName}"
      channel: "${channel}"
      steps:
        - name: ValidateInput
          type: JavaScript Code
          code: |
            // Run custom validation if provided
            const isValid = ${params.validationExpression};
            if (!isValid) {
              throw new Error("${validationErrorMessage}");
            }
            return { valid: true };
        
        - name: UpdateField
          type: Update Document
          changeset:
            - op: replace
              path: "${fieldPath}"
              val: ${event}
      
      response: ${event}

Usage Examples

Setting a Text Field

addressSetter:
  type: Field Setter
  fieldPath: /shippingAddress
  operationName: setShippingAddress
  channel: customerChannel
  fieldType: Text

Setting a Boolean Field with Validation

giftOptionSetter:
  type: Field Setter
  fieldPath: /includeGift
  operationName: setGiftOption
  channel: customerChannel
  fieldType: Boolean

Setting an Address with Country Validation

shippingAddressSetter:
  type: Field Setter
  fieldPath: /shippingAddress
  operationName: setShippingAddress
  channel: customerChannel
  fieldType: Address
  validationExpression: "event.country === 'Poland'"
  validationErrorMessage: "Sorry, we currently only ship to Poland"

Chat Messages

name: Chat Messages
type: Contract Package Template
description: Reusable template for sending and receiving chat messages

params:
  operationName:
    type: String
    description: Name of the chat operation (e.g., chat, sendMessage)
    default: "chat"
    required: false
  
  channel:
    type: Channel
    description: Reference to channel contract
    required: true

generates:
  - contractName: "${operationName}"
    contract:
      type: Operation
      request:
        type: Text
  
  - contractName: "${operationName}Impl"
    contract:
      type: Sequential Workflow Operation
      operation: "${operationName}"
      channel: "${channel}"
      steps:
        - name: CreateMessageEvent
          type: Trigger Event
          event:
            type: Chat Message
            message: ${event}
            sender: ${eventSender}

Usage Examples

Simple Chat Implementation

generalChat:
  type: Chat Messages
  channel: userChannel

Custom Chat with Different Operation Name

supportChat:
  type: Chat Messages
  operationName: contactSupport
  channel: customerChannel