Skip to main content

Version Your Components and Integrations

In a perfect world, you wouldn't need to version anything for integrations. Your team would get it right the first time it built a component or an integration and no one would ever change anything. Unfortunately, none of us live in a perfect world. Fortunately, we have a good solution for managing component and integration versions in Prismatic.

We have largely built best-practices for versioning into the platform, to ensure that it is easy for your to determine what versions of components and integrations are available but also to know which ones are currently deployed. In addition, there are some steps you can take to make best use of the versioning functionality and we call those out in the following sections.

How components are versioned in Prismatic#

Integrations in Prismatic are largely built by stringing components together. Built-in components (like SFTP) can be used in any number of integrations, but so can each of your custom components.

The drawback of using the same component in different integrations is that someone might add new functionality or otherwise modify component code to fix/do something they need for their integration, but in doing so may inadvertently break another integration. That's not good.

The good thing is that all the components (whether built-in or custom) are versioned. Each time you run prism components:publish on one of your custom components, Prismatic publishes a new version of the component as V2, V3, etc.

When a new version of a component is available, you'll see a notification in the integration designer.

Integration designer with component version notification

At this point, you may click the notification to see what components have newer versions available and update the components to use them, as needed.

Integration designer with component version selection

Built-in components work the same way. Prismatic regularly adds new actions and otherwise modifies components to improve functionality, but you determine if you want to stay with the component version you are currently using, or update a given integration to use a newer version.

What you can do with component versioning#

Use prism components:publish --comment "Whatever the comment is" to add a description to a given version of a component. This makes is simpler for someone else to know changes a specific version has.

It's important to note that integrations are not automatically updated to use the latest version of your component. This ensures that a member of your team won't update a custom component and break an integration that you (or someone else) is using. Instead, you can choose to update integrations to newer versions of components and test those versions when it is convenient for you.

How integrations are versioned in Prismatic#

Integrations, like components, may also be versioned. When you've created/modified and then tested an integration and you click "Save & Publish," the system increments the version by 1. An original integration will have V1, followed by V2, etc.

Integration designer with integration version

As with versioning a component, versioning an integration does not automatically deploy that version to customers. As noted, automatic deployment could be very bad, since a change to an integration for one customer might break something for another. Not all customers may be on the newest version of your integration; some may be using a legacy version of a third-party service which requires them to stay on their current integration version.

Instead, your customer-facing team decides who gets which version and when — with no need to rely on dev or DevOps to make the updates. Team members can simply select the desired integration version from the available list, enter any needed configuration data and click "Save and Deploy."

Integration designer with instance version

If something should go wrong when you switch a customer to a new version of the integration, you can easily revert to the prior version of the integration by following a similar process. Simply click "Reconfigure," select the correct version of the integration, and click "Save and Deploy" once again. In a few seconds, everything is back the way it used to be.

What you can do to with integration versioning#

Each time you publish a version, you can include a comment (basically a commit message) summarizing the changes.

Ideally (to make maintenance sane), you'll want to keep customers on newer versions of integrations. To support that, you can mark any version of an integration as deprecated (using the integrations Version History drawer). Once a version is deprecated, it will still show in the list, but will not be selectable by your team or customers for deployment/activation.

If you know for certain that you want all your customers to be updated to the current version, you can click "Update all Instances" in the version drawer.

Only one version of a given integration is can be made available in the marketplace, but that's not automatically updated (since nothing is automatically updated) when a new version is created. You can have your team deploy a new version of an integration internally for testing, but only allow your customers to update their instances via the marketplace when that QA is complete.