Process Versioning

The tSM Process Engine supports the deployment and management of multiple versions of a single process definition. Versioning ensures that you can continue to evolve and improve your processes over time, while still supporting currently running instances. It also enables controlled rollouts, hotfixes, and major or minor updates.

1. Core Concepts

1. Process Code

   • Each process definition is identified by a code.
   • This code cannot be changed once the process is deployed; it remains the permanent identifier for all versions of that process.

2. Version Label (SemVer)

   • A human-friendly label, typically following semantic versioning (SemVer) conventions (e.g., 1.0.0, 2.1.2).
   • Identifies the process version for business users

3. Internal Version

   • Internally, each new deployment creates a unique internal version (starting at 0 for each label).
   • This means you can have multiple deployed instances of the same version label—but each gets its own internal revision number.
   • While this is useful in development environments (e.g., multiple incremental builds under the same label), using multiple internal versions for the same label in production is discouraged.

2. Deployment and Version States

"Deploy" vs. "Deploy and Convert to Current"

• Deploy

  • Creates a new internal version of the process without changing the current version label used by new process instances.
  • Good for development scenarios where multiple internal versions of the same label may be tested before final release.

• Deploy and Convert to Current

  • Deploys a new internal version and makes it the “current” version.
  • The newly deployed version becomes read-only (locking the model). Any further modifications must be done by creating a new version label.
  • New process instances will automatically start with this current version unless otherwise specified.

Starting a Process with a Particular Version

• By default, a new process instance starts with the current version of the process definition.
• You can override this at the API or module level to explicitly start with a specific version if needed (advanced scenarios).

3. Running Processes and Migration

Version in Use for Running Instances

• An instance that started on version X of a process continues to run on version X.
• If a new version is deployed, existing instances remain on their original version unless a migration is performed.

Migration to a New Version

• You can migrate running instances to a newer version either individually or in bulk using the process instance list or automated scripts.
• During bulk migration, the system checks version compatibility to ensure all user tasks and flow nodes in progress have equivalents in the new version.

info

Auto-Migration: During deployment, you can choose to automatically convert all running instances to the new version. This is only recommended if the new version is fully compatible (e.g., no missing user tasks). Otherwise, you must define a migration path or handle manual updates.

4. Monitoring and Statistics

Statistics Tab in Process Designer

• The Statistics tab displays each deployed version of a process, including both:
  • Version Label (e.g., 7.0, 7.1)
  • Internal Version (e.g., 7.0-1, 7.0-2, etc.)
• Shows the number of running instances on each deployed version.
• From this screen, you can list the instances (orders, tickets, etc.) using that version, facilitating targeted migrations or updates.

Visual Comparison Tool

• The Process Designer includes a comparison tool that highlights differences between any two versions of the same process definition.
• Differences could be new or removed tasks, altered transitions, or changes to forms and DMN rules.
• Example of new user task in a process:

5. Recommended Versioning Strategy

1. Semantic Versioning

   • Major Version (e.g., 7.0 → 8.0): For significant or breaking changes.
   • Minor Version (e.g., 5.0 → 5.1): For smaller feature enhancements.
   • Patch Version (e.g., 5.1.0 → 5.1.2): For hotfixes or urgent minor fixes.

2. Development Environments

   • Incrementally deploy multiple internal versions under the same label.
   • Test thoroughly before designating the final release version.

3. Production Environments

   • Deploy once for each major/minor/patch label, then use “Deploy and Convert to Current.”
   • Lock the process version as read-only to enforce consistent behavior.
   • Avoid multiple internal versions under the same label to reduce confusion.

6. Example Lifecycle

1. v6.0 Development

   • Deploy multiple times to test environment:
     • v6.0 internal version 0, v6.0 internal version 1, etc.
   • Finalize changes, then “Deploy and Convert to Current” → becomes the production v6.0.

2. Bug Fix

   • Deploy a patch version v6.0.1 or v6.1 with a small fix.
   • Optionally auto-migrate all running instances if changes are minor and tasks map cleanly.

3. Major Redesign

   • Introduce v7.0 with significant BPMN changes.
   • Migrate active instances if feasible, or allow them to finish on v6.0.x.

7. Additional Notes (from Current Docs)

• Auto-Migration is recommended for long-running processes but only if the new version is fully compatible.
• If incompatible changes are introduced, you must either:
  • Provide a migration path.
  • Allow existing process instances to finish on their old version.
• Minimizing production hotfixes reduces complexity. It’s often better to test changes on a dedicated environment and release a new version as needed.

---

Summary

Process Versioning in tSM allows for safe, incremental evolution of business processes while preserving the integrity of ongoing work. By employing labels (SemVer) and internal versions, you can maintain clear version histories, support parallel development, and decide exactly when new instances or migrations should occur. Combined with the comparison and statistics tools, this approach offers full visibility and control over process lifecycles in a production-grade environment.