Skip to main content

Contract Package Templates

Contract Package Templates provide a powerful abstraction mechanism for Blue documents by generating sets of related contracts from a single configuration block. They act as "macros" that expand into multiple interconnected contracts based on parameters you specify.

Why Use Templates?​

Templates solve several common challenges when building Blue documents:

  • Reduce repetition - Avoid writing the same contract patterns over and over
  • Standardize implementations - Ensure consistent behavior across documents
  • Simplify complex functionality - Express sophisticated behaviors concisely
  • Focus on parameters - Configure only what varies while inheriting best practices

Every compliant Blue processor must support the standard templates defined at Blue Contract Templates Repository.

How Templates Work​

When a processor encounters a template reference in a document, it:

  1. Evaluates the template parameters against the provided values
  2. Generates multiple concrete contracts based on those parameters
  3. Inserts the generated contracts directly into the document's contract collection
  4. Processes these contracts like any others defined in the document

The template itself isn't part of the final document structure—only the contracts it generates.

Logic Attached to Data​

Contract Package Templates represent a powerful pattern where reusable logic can be attached to specific data locations within a document. This creates a separation between:

  • Data structure - The document fields that store information
  • Logic - The operations and workflows that manipulate this data

By linking templates to specific document paths, we create a system where the document essentially serves as a database, while templates provide the interactive logic that operates on this data.

For example, the Field Setter template links an operation to a specific document path, allowing you to change that data through a standard interface. More complex templates like Online Lessons Operations connect sophisticated workflows to specific data sections (teacher profile, schedule, lesson types), creating a complete application from a data structure.

Standard Templates​

Field Setter​

The Field Setter template creates contracts that allow updating a specific field in your document:

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

See full specification at Field Setter Template.

Chat Messages​

The Chat Messages template creates a simple messaging system within your document:

generalChat:
  type: Chat Messages
  channel: userChannel

See full specification at Chat Messages Template.

Access Management​

The Access Management template creates a complete role-based access control system with operations for managing roles and participants:

accessManagement:
  type: Access Management
  roles:
    Admin:
      description: "Can manage the entire picnic and reset contributions"
      operations:
        - resetContributions
        - manageRoles
      participants:
        - ownerChannel
      channelName: adminChannel
    User:
      description: "Can choose what to bring to the picnic"
      operations:
        - chooseFood
        - chooseAlcohol
      participants:
        - aliceChannel
        - bobChannel
        - celineChannel
        - deanChannel
      channelName: userChannel

This template is particularly interesting because it doesn't need to connect to specific document paths - it's focused on generating contracts that manage access control.

Complex Application Templates​

More sophisticated templates combine multiple features into application-specific packages:

Online Lessons​

As demonstrated in the Assistant Agents section, this template creates a teaching platform by connecting logic to specific data locations:

teachingOperations:
  type: Online Lessons
  teacherProfilePath: /teacher
  schedulePath: /schedule
  lessonTypesPath: /offerings

This generates contracts implementing:

  • Teacher profile management
  • Lesson type configuration with pricing
  • Schedule availability settings
  • and more

The template takes existing data structures in the document and overlays operations and workflows that manipulate this data. This creates a complete teaching platform by connecting standardized logic to your document's specific data organization.

Best Practices​

When using Contract Package Templates:

  1. Choose the right abstraction level - Use templates for patterns that repeat across documents
  2. Keep parameters meaningful - Only parameterize values that need to vary
  3. Document clearly - Make it obvious what your template generates
  4. Test thoroughly - Verify that generated contracts behave as expected
  5. Consider composition - Combine multiple templates for complex functionality

By leveraging Contract Package Templates effectively, you can create sophisticated Blue documents with less code and greater consistency, treating your document as a data store with attachable logic bundles.