How to Use Versioning in Prismatic

Integration development is never really complete. Third-party APIs change, and changes in your own product can sometimes necessitate changes to your integrations. As you scale, you often add deeper functionality and additional configuration options to your integrations so they can serve a broader, increasingly diverse customer base. After "finishing" and deploying an integration, you'll inevitably need to update and maintain it for years to come.

As your integrations change over time, it's important to be able to change them easily and track those changes in a way that you and your team can understand – both now and six months from now. It's also extremely important to have control over when and how you roll out those changes to customers – especially since you might have customers on different versions of third-party systems and therefore need to be able to support multiple versions of an integration simultaneously.

With all of that in mind, we created a versioning system within the Prismatic platform that lets your team:

1. Update your integrations cleanly
2. Quickly and easily deploy the exact versions of integrations that each customer needs

In this post, let's walk through two Prismatic resources that have versioning – integrations and components – and talk about how to use versioning effectively when developing and deploying your integrations.

Integration versioning and deployment

We'll start by looking at how integration versioning works in Prismatic and after that look at component versioning.

Integration versioning helps you account for the iterative changes you make to your integrations. When you've tested an integration and are happy with the results, you click "Save & Publish" to create a new version of your integration that can be deployed to customers. The first time you publish your integration, it gets version "1". When you make, test, and publish some changes, the subsequent publications receive versions "2", "3", etc.

Each time you publish a version, you can include a comment summarizing what you changed (basically a commit message) to provide visibility to your team members.

I should note here that publishing a new version of an integration does not automatically deploy that version to customers who run that integration. Deploying integration changes willy-nilly like that would be unwise – we don't want to inadvertently change customers' live integrations with an accidental mis-click.

Plus, not all customers need the newest version of your integration – some, for example, might be stuck using a legacy version of a third-party service and need to stay on an older version of your integration. This also allows you to deploy a new integration version to a small subset of customers to work out any kinks before deploying it broadly.

Your team can choose who gets the new version and when, and the update does not require dev or DevOps involvement. Instead, customer-facing teams can easily make the update in Prismatic's simple management environment with just a few clicks. All they need to do is select the desired version of the integration to upgrade to, enter any missing configuration information, and click "Save and Deploy". There's no downtime for the customer, and no dev or DevOps time is required.

If something goes wrong – say a customer needs to roll back a third-party service and your integration needs to be rolled back with it – reverting an instance to run a previous version of the integration is similarly straightforward. Your team can can click "Reconfigure", select a previous version of your integration, and click "Save and Deploy" again. Within a few seconds, your customer can be back to running a known working previous version of your integration.

For the sake of maintainability, you probably want to keep customers on newer versions of integrations. With that in mind, you can mark versions of your integrations as deprecated from the integration's Version History drawer. By toggling a version off, you prevent your team and your customers from deploying that version of the integration.

Component versioning

Now, let's look at component versioning.

As you know, integrations in Prismatic are built by stringing a series of components together. Obviously, Prismatic's built-in components – like the "copy files on an SFTP server" component – are usable in multiple integrations, but any custom components that you've built can also be used in multiple integrations.

The danger with shared code is that someone might add new functionality or otherwise modify the code to fix something they're working on, but in doing so may inadvertently break other things that rely on that same code. That's obviously not great. It's the reason package managers like NodeJS's npm and Python's poetry, etc. have version lock files – you don't want code you depend on to be swept out from under you.

Like Node or Python packages in your code base, components that your integration is built from are similarly versioned. Each time you run prism components:publish on one of your custom components, a new version of that component is published. (Like integrations, component versioning follows a similar scheme – version 1, 2, 3, etc.)

Integrations are not automatically upgraded to use the latest versions of your components. That prevents a colleague from updating a custom component and inadvertently breaking other integrations that rely on it. Instead, you can choose to update and test newer versions of components in your integrations when it's convenient for you.

When a newer version of one or more components is available, you'll see a notification in the integration designer:

Simply click that notification to see which components have newer versions available and update them if you desire.

Prismatic's built-in components work the same way. We're constantly making improvements to the built-in components we offer, such as adding additional actions, but you retain control over when to update your integrations to use newer component versions.

Additional resources

You can learn more about versioning in the following docs:

• Publishing integrations
• Deploying instances of integrations
• Setting component versions

Try it out for yourself by creating an account or contact us if you'd like to learn more about Prismatic.