Blueprints in SignStack are like the source code for your business processes. Just like code, they need to evolve safely over time. SignStack uses Semantic Versioning (SemVer) (e.g., 1.0.0, 1.1.0, 2.0.0) to manage these changes, ensuring that updates to your Blueprints don't accidentally break your running workflows or integrations.

This guide explains how to use the SignStack API to create and manage different versions of your Blueprints.

Why Version Blueprints?

Versioning is crucial for:

• Safe Evolution: Make changes to a process (like adding a step or changing a condition) without affecting workflows already using the older version.

• Rollback: If a new version introduces an issue, you can easily revert to a previous, stable version.

• Auditability: Maintain a clear history of how your business processes have changed over time.

• Dependency Management: Allows workflows and potentially other systems to depend on specific, stable versions of a Blueprint.

Understanding Semantic Versioning (SemVer)

SignStack uses the standard MAJOR.MINOR.PATCH format:

• MAJOR (X.y.z): Incremented for breaking changes (e.g., removing a required role or entitySlot, changing a step key). Existing workflows using older major versions will not automatically use this new version.

• MINOR (x.Y.z): Incremented for non-breaking new features (e.g., adding a new optional step or entitySlot, adding an onCompleteMapper). Existing workflows compatible with the previous minor version can often safely use this new version.

• PATCH (x.y.Z): Incremented for non-breaking bug fixes (e.g., correcting a typo in a displayName, fixing a flawed inclusionCondition). These changes are generally always safe to adopt.

API for Version Management

You manage versions using specific endpoints related to a Blueprint key.

1. Creating a New Version

This is the primary way to evolve a Blueprint. It creates a new Draft version based on an existing one.

• Endpoint: POST /v1/organizations/{organizationId}/blueprints/{blueprintKey}/versions

• Request Body:

  {
    "sourceVersion": "1.2.3", // Optional: Defaults to latest 'Active' version
    "changeType": "MINOR",    // Required: 'PATCH', 'MINOR', or 'MAJOR'
    "notes": "Optional description of changes.",
    "initialData": { // Optional: Initial updates for the new draft
      "displayName": "My Blueprint (V1.3)",
      // ... include any other fields from BlueprintDbo you want to set initially
    }
  }

  json

• Backend Logic: Finds the sourceVersion, calculates the new version number based on changeType (e.g., 1.2.3 + MINOR -> 1.3.0), creates a copy of the source Blueprint with the new version and status: "Draft", applies initialData overrides, and saves it.

• Response: 201 Created with the full object of the newly created DRAFT version.

2. Updating a Draft Version

Once you have a Draft version, you can modify it in place until you're ready to activate it.

• Endpoint: PUT /v1/organizations/{organizationId}/blueprints/{blueprintKey}/versions/{version}(Note: The {version} must correspond to a version with status: "Draft")

• Request Body: The full, updated Blueprint object for the draft version.

  {
     "key": "myBlueprint",
     "version": "1.3.0", // Must match the version in the URL
     "status": "Draft", // Must remain Draft during updates
     "displayName": "My Blueprint (V1.3 - Revised)",
     "steps": [ /* ... Updated steps array ... */ ]
     // ... All other properties ...
  }

  json

• Response: 200 OK with the updated DRAFT object.

3. Activating a Version

When a Draft is ready, you change its status to Active. (This might be done via the PUT endpoint above by changing the status field, or potentially a dedicated POST .../status endpoint).

• Logic: Typically, there should only be one Active version per MAJOR version line at any given time. Activating 1.3.0 might automatically deprecate 1.2.3. Your specific business rules for activation need to be defined (e.g., automatically deprecate previous minor/patch within the same major?).

4. Listing All Versions

Retrieve the history for a specific Blueprint key.

• Endpoint: GET /v1/organizations/{organizationId}/blueprints/{blueprintKey}/versions

• Query Params: limit, offset (sorted descending by version by default).

• Response: Paginated list of full Blueprint objects for all versions of that key.

5. Getting a Specific Version

Fetch the details of a specific historical or active version.

• Endpoint: GET /v1/organizations/{organizationId}/blueprints/{blueprintKey}/versions/{version}

• Response: The full Blueprint object for the requested version.

Properly managing Blueprint versions using these APIs ensures your workflows evolve safely and predictably, providing a robust foundation for your automation.

➡️ Next: Guides: Create a Basic Template via API