Implement Conditional Logic

Use includeIf expressions to dynamically include or skip steps, envelopes, and documents based on entity data.

Where Conditions Apply

Element	Effect
Envelope `includeIf`	Skip the entire envelope and its documents
Document `includeIf`	Skip a single document within an envelope
Step `includeIf`	Skip a step (and all its children if a group)

All conditions are JSONata expressions evaluated against the blueprint's input data. They must return true to include the element. If includeIf is omitted, the element is always included.

Conditional Envelopes

Include an envelope only when relevant:

envelopes:
  - key: offer_envelope
    documents:
      - key: offer_letter
        template: offer_letter@1.0.0

  - key: benefits_envelope
    includeIf: '$.position.includesBenefits'
    documents:
      - key: benefits_form
        template: benefits_enrollment@1.0.0

When includesBenefits is false, the entire benefits envelope is omitted.

Conditional Documents

Include specific documents within an envelope:

envelopes:
  - key: compliance_envelope
    documents:
      - key: nda
        template: nda@1.0.0

      - key: ip_agreement
        template: ip_agreement@1.0.0
        includeIf: '$.position.department = "Engineering"'

The NDA is always included; the IP agreement only appears for Engineering hires.

Conditional Steps

Skip a step when a condition isn't met. Here, the manager approval step only runs for senior positions:

orchestration:
  key: root
  type: group
  execution: sequential
  children:
    - key: hr_sends_offer
      type: participant
      participant: hr_manager
      action:
        type: sign
        envelope: offer_envelope
        assignments:
          - document: offer_letter
            role: hr_representative

    - key: manager_approves
      type: participant
      participant: hiring_manager
      includeIf: '$.position.level > 3'
      action:
        type: sign
        envelope: offer_envelope
        assignments:
          - document: offer_letter
            role: manager

    - key: new_hire_accepts
      type: participant
      participant: new_hire
      action:
        type: sign
        envelope: offer_envelope
        assignments:
          - document: offer_letter
            role: employee

When $.position.level is 3 or below, the manager_approves step is skipped entirely.

Expression Examples

A few patterns that show up often. See JSONata Expressions for the full language reference.

# Simple property check
includeIf: '$.deal.value > 100000'

# Combining conditions
includeIf: '$.client.tier = "Enterprise" and $.deal.value > 50000'

# Checking existence
includeIf: '$exists($.employee.manager)'

# Array length
includeIf: '$count($.supplements) > 0'

Tips

For complex conditions, factor the logic into a Custom Function and call it from includeIf.
Use $exists() before accessing optional properties to avoid evaluation errors.
Cover each branch with a Scenario so you can preview both the include-this-step and skip-this-step paths.

The Workflow Engine — Where steps fit in the orchestration tree
The Data-First Principle — Workflow shape adapts to entity data

Generating Contracts with AI

Add SignStack to Your CI/CD Pipeline