Templates in SignStack are like the source code for your documents. 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. This ensures that updates to your Templates don't accidentally break Blueprints or Workflows that depend on them.

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

Why Version Templates?

Versioning is crucial for:

• Safe Evolution: Make changes (like adding or removing fields) without affecting workflows already using older versions.

• Rollback: Easily revert to a previous, stable version if a new one causes issues.

• Auditability: Maintain a clear history of how your documents have changed.

• Dependency Management: Allows Blueprints to specify compatible version ranges, preventing unexpected breaking changes.

Understanding Semantic Versioning (SemVer)

SignStack uses the standard MAJOR.MINOR.PATCH format:

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

• MINOR (x.Y.z): For non-breaking new features (e.g., adding a new optional field or role). Blueprints compatible with ^1.2.0 can safely use 1.3.0.

• PATCH (x.y.Z): For non-breaking bug fixes (e.g., fixing a typo in a displayName or valueExpression). These changes are generally always safe to adopt.

(Note: SignStack provides tools, like the "Smart Save" dialog in the UI or automatic detection via API, to help determine the correct version bump. See the Advanced Topics section for details on automatic versioning.)

API for Version Management

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

1. Creating a New Version (Creates a Draft)

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

• Endpoint: POST /v1/organizations/{organizationId}/templates/{templateKey}/versions

• Authentication: Requires a valid SignStack JWT Access Token.

• 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 Template (V1.3)",
      "revision": "Rev. 11/25",
      // ... include any other fields from TemplateDbo 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 Template 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 (either newly created or by editing an existing draft), you can modify it in place until you're ready to activate it.

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

• Authentication: Requires a valid SignStack JWT Access Token.

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

  {
     "id": "tpl_...", // The ID of the specific draft version being updated
     "key": "myTemplate",
     "version": "1.3.0", // Must match the version in the URL
     "status": "Draft", // Must remain Draft during updates
     "displayName": "My Template (V1.3 - Final Edits)",
     "fields": [ /* ... Updated fields array ... */ ]
     // ... All other properties MUST be included ...
  }

  json

• Response: 200 OK with the updated DRAFT object.

3. Activating a Version (Changing Status)

When a Draft is ready, you change its status to Active. This typically involves updating the template using the PUT endpoint.

• Endpoint: PUT /v1/organizations/{organizationId}/templates/{templateKey}/versions/{version}

• Request Body: The full Template object with the status changed to Active.

  {
     "id": "tpl_...",
     "key": "myTemplate",
     "version": "1.3.0",
     "status": "Active", // <-- Change the status
     // ... All other properties ...
  }

  json

• Backend Logic: Your backend might have rules, such as ensuring only one version per MAJOR line is Active at a time (e.g., activating 1.3.0 might automatically change 1.2.3 to Deprecated).

• Response: 200 OK with the updated Template object (now Active).

4. Listing All Versions of a Template Key

Retrieve the complete version history for a specific template key.

• Endpoint: GET /v1/organizations/{organizationId}/templates/{templateKey}/versions

• Authentication: Requires a valid SignStack JWT Access Token.

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

• Response: Paginated list containing the full Template objects for all versions associated with that key.

5. Getting a Specific Version

Fetch the full details of a specific historical or active version.

• Endpoint: GET /v1/organizations/{organizationId}/templates/{templateKey}/versions/{version}

• Authentication: Requires a valid SignStack JWT Access Token.

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

Properly managing Template versions using these APIs ensures your documents evolve safely and predictably, providing a robust foundation for your Blueprints and Workflows.

➡️ Next: Guides: Use valueExpression for Dynamic Fields