Versioning Workflows

With workflow versioning, it is possible to save multiple versions of a WEGnology workflow and run specific versions of that workflow based on the payload it receives. Doing so allows you to actively develop a workflow that is currently in production use, test it without disrupting current functionality, and then deploy those changes once the updates are complete.

Creating Versions

Every workflow has at least a “Develop” version. When creating a new workflow (or when using workflows created prior to the release of the versioning feature), Develop will be the only available version, and it will be set as the “Default” workflow.

To create a version, click the “Versions” tab within the workflow editor. Then, click the “Create New Version” button. This will present a form with the following fields:

• Version Name: This required field is the identifier you will use to invoke a specific version within your payloads. This can be any string except “develop” or “default”, though we recommend following semantic versioning. If you provide a name that matches another version within that workflow, you will be prompted to confirm that you wish to overwrite that version.
• Make this the default version: For application workflows, this is a shortcut to mark the new version as the workflow’s default. The default version can be changed at any time.
• Notes: Optionally, you may provide some more details on what this specific version entails.

Versioning Experience Workflows

Experience workflows cannot be versioned independently of your application experience as a whole; this is to help keep the back-end logic provided by a workflow in sync with the front-end presentation from experience views. To create and utilize experience workflow versions, you must create a whole experience version.

Working With Versions

By default, when first visiting a workflow, you will be presented with its default version. To view other versions, click the Versions tab in the right column. In there you will find a list of the workflow’s versions; click the version name to view it. (The currently viewed version is bolded and unlinked.)

Once you have selected a version, you will see that version name alongside the workflow’s name at the top of the page. The button and dropdown menu in the top right corner will also reflect actions available for that version.

A version’s nodes, connectors, global variables and target agent version (in the case of edge workflows) are specific to that version. Other than within the Develop version, these items are not editable (except as described below), but you can still view their configuration.

There are a few actions you may take relative to a version:

• For application workflows, any version can be set as the workflow’s default. It is this version that runs when a payload hits the workflow without a specific version specified.
• Versions can have their contents copied to Develop, where they can then be edited and saved as a new version.
• Versions can be exported either to a JSON file or, if you have edit permissions within the application, cloned as a new workflow.
• For application workflows, any version besides Develop can be individually disabled.
• Any version besides Develop, or the current default version, can be deleted. This action cannot be undone.

Debugging Versions

Any workflow version can be debugged the same as its parent Develop version; however, the process varies depending on the type of workflow being viewed. Visit our debugging workflows documentation for more information.

Editing Existing Versions

Once a workflow version has been created, its nodes, connectors and globals cannot directly be edited. Rather, if you need to make changes to an existing workflow:

1. Copy the version to Develop. (You may want to save your current Develop as a new version so you don’t lose any changes made since your last version creation.)
2. After copying, make any necessary edits to the workflow and save your changes.
3. Create a new workflow version, setting its name to the same as the version you need to overwrite.

Deleting Versions

To delete a workflow version, navigate to the “Versions” tab and click the “Other Actions” dropdown (indicated by a line of three vertical circles). Select “Delete” in the dropdown options, and then confirm with the “Delete My Version!” button in the modal that appears.

Edge workflow versions may not be deleted if they are in active deployment. You may delete all edge workflow versions that are not in active deployment by clicking “Delete Undeployed Versions” in the “Versions” tab. Prior to bulk-deleting undeployed workflows, you should export any versions you’d like to save for posterity as this action cannot be undone.

Workflow Properties That Are Not Version-Specific

Not every property of a workflow can be changed on a per-version basis:

• Workflow storage values span across all workflow versions. If your application requires using workflow storage on a per-version basis, we recommend prefixing your storage keys with the name of your workflow version.
• A workflow’s name and description, when modified, will change across all workflow versions. Any identifying or descriptive information about a workflow version can be stored in the version’s name and notes.
• If an application workflow is disabled, all versions of the workflow are also disabled, regardless of that version’s specific enabled / disabled state.

Triggering Specific Versions

When sending a payload to the platform, you may optionally include a version name to run for any workflows triggering off of that payload. If a version is not specified, the triggers will run the default workflow; if a version is specified but the version does not exist, the workflow will not fire.

Only the following trigger types can fire a specific workflow version:

• Endpoints and webhooks invoke specific versions by including an HTTP header with the name X-Flow-Version and a value matching one of your version names.
• Device State triggers fire workflow versions by including a flowVersion root-level property in the body of your request (either via HTTP or MQTT). The value of the property is the name of the workflow version you wish to invoke.
• Google Pub/Sub allows for the passing of attributes with your messages. Include an attribute with the key flowVersion and a workflow version name as the value in order to invoke that version.
• Virtual Buttons, when clicked, will simply fire the version that the button is a part of. To invoke a virtual button press through the API, include a flowVersion root-level property in the body of your request. The value of the property is the name of the workflow version you wish to invoke.

All other trigger types will only fire if they are part of the workflow’s default version. Triggers that will not fire for this reason are indicated as such within the workflow editor.