Embedded iPaaSUnified API

Versioning System

Learn how Alloy's Versioning System makes it easy to make changes to your workflows in real time.

Suggest Edits

Overview

Alloy Embedded makes it quick and easy to handle workflow changes thanks to our Versioning System. In this article, we'll take a look at how it works.

How it Works

In the previous tutorial, we learned how to build an integration from scratch using the Alloy Workflow Builder. Before you can go live, you need to publish a workflow. The Versioning System makes it easy to make changes to a workflow without breaking any of the end user's installations.

To illustrate how the Versioning System works, let's consider the following example:

ACMECo uses Alloy Embedded to build an integration that posts a Slack message to an end user's Slack channel each time an order is shipped in ACMECo's platform. As it currently stands, ACMECo has built their Slack integration to post the order number and status.

ACMECo rolled out this integration in June. Three months later, over 1,000 users installed it. Later that year, ACMECo introduces a new feature that allows users to check their order status via a tracking URL. ACMECo decides it wants to update its Slack integration to support this new tracking URL feature. But they quickly realize that making any sort of sudden change could impact the 1,000 users currently using the Slack integration.

This is where Alloy's Versioning System comes in. The Versioning System lets AcmeCo create multiple iterations of a workflow while not breaking any existing installations used by current users. When existing users log in to ACMECo's platform, they can be prompted to upgrade to the latest version.

🚧

Editing Workflows

Note that you cannot edit a previous version. Once a new version is released, old versions enter a read-only state.

Releasing a new version

If you've published a wofkflow, you've probably already used the Versioning System and didn't know it. To make a change to an existing workflow, navigate to the Alloy Workflow Builder and hit Create new version as seen below.

You'll be taken into the workflow editor experience to make any modifications you see fit. After you've made your changes, click the Release this version button to publish your changes. This will create a new version. Existing users will continue to use the previous version until they upgrade to the latest version.

To view previous versions or to restore to a previous version, click the clock icon as seen below. Selecting this will open a drawer listing all the workflows you've created.

Updating a Workflow

When a new workflow version is released that is newer than the currently installed version, you'll often want to prompt users to upgrade to the latest version.

📘

Updating Workflows

You can tell when a workflow needs to be updated by comparing the payload returned from the List Integrations or List Workflows endpoints. When the value of version is greater than the installedVersion value, you should prompt the user to update their workflow.

To update a workflow, invoke the update method. This method allows you to edit a workflow and accepts the same params as install. The edit method does not accept an integrationId and only works with workflowIds.

Alloy.update({
  workflowIds: ["YOUR_WORKFLOW_ID", "YOUR_WORKFLOW_ID"],
  callback: () => { console.log(); },
  alwaysShowAuthentication: true,
  hide: false,
  title: "Slack Integration" 
});

Note that the update method does not allow you to specify a version to update to. Instead, it defaults to whatever the most recently released version (as specified by the version key in the List Workflows endpoint).

Wrapping Up

In this article, we took a look at how to use the versioning system in Alloy Embedded. The versioning system allows ISVs to create multiple iterations of a workflow while maintaining workflow stability and continuity for existing users even when a change is made.

Updated 4 months ago