No matter how hard you work to design your connected system, there comes a time when you'll need to release another version to fix bugs, handle new use cases, or add additional operations. This page explains how connected system plug-ins handle versioning so you can add capabilities while minimizing disruption for your users.
When you create the connected system plug-in manifest, you define one version for the entire plug-in (in plugin-info) and separate versions for each connected system. There's no direct dependency between the two version types.
The plug-in version must be incremented with each release (no matter how minor) in order for the newer version to be deployed over prior releases. During development you can deploy with the same version as long as the filename of the plug-in remains the same. We recommend including the plug-in version in the package filename to help distinguish between different files.
Each connected system template in your plug-in has it's own versions. There can be multiple versions of a connected system in the same plug-in, but you can only have one instance of each major version. The following sections will help you decide when and how to make different version changes to your connected system.
We work hard to ensure that customer applications keep working even when they upgrade Appian. We call this backward compatible. The same principle applies when you release new versions of your connected system plug-in.
Some things to keep in mind when you think about what compatibility looks like for your connected system:
The promise of backward compatibility is core to the Appian platform, and therefore, it is important for your connected system to use the different versioning options provided.
Use major versions when your connected system changes won't be compatible with prior versions. For example:
If you are going to make a major version change to any object (connected system template, integration template, client API Template), create a copy of your existing connected system, including all the related code, resources, and definitions in your plug-in manifest. For more details, see How to version.
Different major versions must be packaged in the same appian-plugin.xml, but packaging two connected system templates with the same name and same major version together will result in an error when the plug-in is loaded.
When you deploy a new major version of your connected system, Appian retains the behavior of the existing connected systems and integrations. Integrations will continue to use the prior version of your connected system and their behavior won't change. When designers create new connected systems, they'll only see your new connected system version in the connected system modal.
There's no limit to the number of major versions you can create for your connected system, integration, or client API templates. Keep in mind that with each major version, designers have to manually update existing integrations to use the new version. If your change doesn't impact backward compatibiliy it's better to make a less-disruptive minor update to your connected system.
Existing connected system objects cannot be upgraded to a new major version. Newly created connected system objects will use the latest version. Manually update the properties with values from the existing connected system object.
Open the integration in Appian Designer and point it to a connected system object built off the version you would like to migrate to. Existing properties should be auto-populated from the existing integration configuration.
Note: The migrated IntegrationTemplate may have added or removed properties. To revert the integration, use the integrations versions dialog (rollbacks are only possible if previous versions of the plug-in are installed).
Use minor versions when you add functionality that is compatible with prior versions of your plug-in. For example:
Connected system templates do not directly support minor versions. We recommend that you indicate the logical minor versions through the appian-plugin.xml instead. So, backwards-compatible feature additions to a connected systems should cause a minor version bump (for example, 1.1.3 –> 1.2.0). Don't create a copy of the connected system tag or contents. Make your (compatible) updates to the existing connected system. See versioning how to for more details.
When you deploy a new minor version of your connected system, Appian automatically starts using the new version in all connected system and integration objects. Designers don't need to take any action to update existing interfaces unless they want to take advantage of new functionality.
Use patch versions when you fix bugs or update non-functionality that is compatible with prior versions of your plug-in. For example:
Connected system templates do not directly support patch versions. We recommend that you indicate the logical patch versions through the appian-plugin.xml instead. So, backwards-compatible feature additions to a connected systems should cause a patch version bump (for example, 1.1.3 –> 1.1.4) for the plug-in bundle. Don't create a copy of the connected system tag or contents. Make your (compatible) updates to the existing connected system. See versioning how to for more details.
When you deploy a patch version of your connected system, Appian automatically starts using the new version in all connected system and integration objects. Designers don't need to take any action to update existing interfaces unless they want to take advantage of new functionality.
Connected systems act as a parent container for integration templates and client APIs. Any addition or modification of an integration template or client API should result in an update to the parent connected system and plug-in manifest.
Integration templates are considered part of connected system templates, and do not have or need their own version number. Any major change to an integration needs to be reflected in the parent connected system and plug-in manifest.
Adding an enhancement or bugfix to an integration template should result in a version bump to the parent package (appian-plugin.xml). See minor and patch versioning above.
Adding a new integration template to an existing connected system template should be considered a minor version change for the plug-in bundle. See minor and patch versioning above.
Adding a new required field to an integration is a major version change and must happen in lock stop with major version bumps of the parent connected system and plug-in manifest. See major versioning above.
Like integration templates, client APIs are considered part of connected system templates, and do not have or need their own version number. Client APIs should obey exactly the same versioning rules as integration templates.
Versioning
