Design a Simple Sequential Blueprint

This guide walks you through creating the JSON structure for a basic, linear Blueprint. Sequential workflows are the most common type, where tasks must happen one after another in a specific order.

We'll design a Blueprint for a simple two-step document review:

An Initiator starts the workflow, providing initial data and potentially filling fields on a document defined in the Blueprint.
A Reviewer then reviews the document and adds their signature.

1. Define the Blueprint Manifest

First, you define the requirements for your Blueprint: the documents, roles, and data needed. This forms the top level of your Blueprint JSON object.

{
  "key": "simpleSequentialReview",
  "displayName": "Simple Document Review (Sequential)",
  "documents": [
    {
      "key": "reviewDoc", // Local key for this document instance
      "displayName": "Document for Review",
      "docTemplateKey": "standardReviewFormV1", // Assumes this template exists
      "roleMapping": { // Maps template roles to blueprint roles
        "submitter": "initiatorRole",
        "finalSigner": "reviewerRole"
      },
      "entityMapping": { // Maps template entity slots to blueprint slots
        "reviewData": "reviewDetailsEntity"
      }
    }
  ],
  "roles": [
    { "key": "initiatorRole", "displayName": "Initiator", "isMandatory": true },
    { "key": "reviewerRole", "displayName": "Reviewer", "isMandatory": true }
  ],
  "entitySlots": [
    { "key": "reviewDetailsEntity", "displayName": "Review Details", "schemaKey": "reviewDataSchemaV1", "compatibleSchemaVersion": "^1.0.0", "isMandatory": true }
  ],
  "rootEntitySlotKeys": ["reviewDetailsEntity"], // Must provide Review Details to start
  "steps": [
     // We'll define the steps next...
  ]
}

key, displayName: Basic identification. Use camelCase for keys.
documents: Lists document instances, links them to DocTemplates, and maps template roles/entities to this Blueprint's roles/entities.
roles: Defines the master list of participant roles for this Blueprint.
entitySlots: Defines the master data requirements.
rootEntitySlotKeys: Specifies data needed at the very start to initialize the Workflow.

2. Define the Steps (Sequential Logic)

Now, we define the workflow logic using the recursive Step model. For a sequence, the root Step is a CONTAINER with executionMode: "SEQUENTIAL". Its children array lists the keys of the steps to execute in order.

// Add this 'steps' array inside the main Blueprint object from above

"steps": [
  // --- The Root Container ---
  {
    "key": "root", // Must have one root step
    "stepType": "CONTAINER",
    "executionMode": "SEQUENTIAL", // Children run one after another
    "completionRule": "ALL",       // Container completes when all children are done
    "children": ["initiatorStep", "reviewerStep"] // Keys of the child steps, in order
  },

  // --- Step 1: Initiator Task ---
  {
    "key": "initiatorStep",
    "stepType": "PARTICIPANT_TASK",
    "name": "Submit Document and Data",
    "roleKey": "initiatorRole", // Assigns this step to the 'Initiator' role
    "taskInterface": "DOCUMENT_SIGNING", // Assumes interaction via fields on a doc
    "links": [ // Defines what the initiator interacts with
      {
        "documentKey": "reviewDoc",
        "fieldKey": "submitterNameField" // Specific field from the template
      },
      {
        "documentKey": "reviewDoc",
        "fieldKey": "submissionDateField"
      }
      // ... other fields for the initiator
    ],
    // Optional: Add mappers to save initiator input to entities
    "onCompleteMappers": [
       {
         "targetEntityKey": "reviewDetailsEntity",
         "mapperExpression": "$merge([entities.reviewDetailsEntity, { submittedBy: fields.submitterNameField.value.text }])" // Example
       }
    ]
  },

  // --- Step 2: Reviewer Task ---
  {
    "key": "reviewerStep",
    "stepType": "PARTICIPANT_TASK",
    "name": "Review and Sign",
    "roleKey": "reviewerRole", // Assigns this step to the 'Reviewer' role
    "taskInterface": "DOCUMENT_SIGNING",
    "links": [
      {
        "documentKey": "reviewDoc",
        "fieldKey": "reviewerSignatureField" // Specific signature field for the reviewer
      },
      {
         "documentKey": "reviewDoc",
         "fieldKey": "reviewerSignDateField"
      }
      // ... other fields for the reviewer
    ]
  }
]

The root Container step orchestrates the flow. Its children array (["initiatorStep", "reviewerStep"]) defines the sequence.
initiatorStep will run first. Only after it completes will reviewerStep begin.
Each PARTICIPANT_TASK uses roleKey to assign responsibility and links to specify which fields (identified by their key from the DocTemplate) the participant interacts with in this specific step.

3. Creating the Blueprint via API

Save this entire JSON structure into a file (e.g., simple_blueprint.json) and then create it using the POST /blueprints API:

curl -X POST \
  [https://api.signstack.com/v1/organizations/me/blueprints](https://api.signstack.com/v1/organizations/me/blueprints) \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  --data @simple_blueprint.json

You have now designed a simple, sequential Blueprint! You can build longer linear workflows by adding more step keys to the children array of the root container.

➡️ Next: Guides: Use Parallel Steps for Approvals