Skip to main content

Versioning flows

Overview​

Flows are versioned to provide robustness by allowing them to be updated without breaking any integrations with code in your application.

Committing changes​

The default view of the flow builder is of the Uncommitted version. This is a sandbox version which allows you to edit the flow without breaking the deployed version of the flow. When you are done editing a flow you can press the Commit changes button to save the flow into a new version.

This prompts you for a commit message and asks you how to transition users when they experience the new flow version.

You can set the transition to one of:

  • Restart in progress users only which restarts users who have started but not completed the flow to the beginning of the new flow version
  • Restart all users which restarts all users (including those who have completed) to the beginning of the new flow version
  • Stop in progress users only which stops users who have started but not completed the flow so they will not see the new version
  • Carry over in progress users which carries over the state of in-progress users from the previous version to the new version when possible. If a user's state can't be brought over due to incompatible changes, those users will be restarted from the beginning of the flow
info

Carry over in progress users is under development. Picking this migration strategy will restart users if large discrepancies exist in flow state between versions. For example, if users in your flow are lingering on historic versions, they will likely be restarted when they reach a version with this migration strategy.

Setting a flow version for an environment​

The flow version and environment your users experience are set in code via SDK. The flow version configuration determines which version of the flow is requested by the SDK and the API key determines the environment.

A flow version configuration is an object consisting of flow identifiers and version tags which looks like this:

{
  'onboarding-tour': 2,
  'initial-setup': 4,
  'welcome-modal': 'uncommitted',
  'feature-hotspot': 'latest',
}

Each version tag can be one of: a number, "uncommitted", or "latest".

In the configuration above, both the onboarding-tour and initial-setup flows are requested at a fixed version (2 and 4 respectively).

The welcome-modal flow is requested at the "uncommitted" version, corresponding to the uncommitted version in Dopt which contains all the uncommitted versions on the canvas as well. This version can also be accessed by using 0. This can be useful while actively developing your flow so that you don’t have to commit to see the changes while developing.

The feature-hotspot flow is requested at the "latest" version, corresponding to the last (most recent) committed version in Dopt. If no versions have been committed yet, this flow will return an empty flow. In combination with the Restart all users migration strategy, the "latest" version allows you to ship the latest updates to your users including things like status and maintenance banners, feature announcements, product changelogs, and more.

caution

Be careful when using the "uncommitted" or "latest" tags or the 0 version to access flows in your code because changes made in Dopt will directly propagate to your users without changes in your code.

Viewing a flow version​

Any flow version can be viewed from the Version history tab. In this view, you can inspect the flow’s blocks and paths as well as update field values. You will not be able to make any changes to the flow itself.

Restoring a flow version​

With the restore feature, you can restore the uncommitted version to any prior version. Restoring modifies your uncommitted version to have the same blocks and paths as a prior version.

caution

Restoring a version will also wipe out any existing uncommitted changes.

Comparing committing new flow versions versus deploying to a specific version​

When working with fields or with specific blocks like component blocks, webhook blocks, flow trigger blocks and true/false branch blocks, you can directly make changes to the configuration of those blocks and deploy those changes against a fixed flow version.

You might want to do this when you’re iterating on content being shown to users and don’t want existing users encounter the content again. After deploying changes, existing users won’t undergo state migrations because the version hasn’t changed; instead, you’ve changed the content and configuration for that specific version.

On the other hand, when you need to reset (or stop) the state of existing users, you’ll want to commit new versions with the appropriate version transition. For example, when you’re building a feature announcement modal, everytime the modal’s content changes because you’ve created new features, you may want to display the modal again for all users.

In this case, only editing the content values for the modal and deploying the changes to an existing version will not reset state for users who have already experienced that modal. Instead, you will need to commit a new version with the new content values and choose the Restart all users migration strategy. Then, all users will encounter the announcement with the new content the next time they enter your app.