Backwards compatibility standard

Last update: September 3, 2021

CREATED FOR:

  • Developer
NOTE
Adobe Experience Platform Launch has been rebranded as a suite of data collection technologies in Adobe Experience Platform. Several terminology changes have rolled out across the product documentation as a result. Please refer to the following document for a consolidated reference of the terminology changes.

Updates to a tag extension in Adobe Experience Platform must be backward compatible with previous versions of the extension. This means that:

  • Any modifications to the primary components of the extensions must be compatible with previous versions. This includes extension configuration, event types, condition types, action types, data element types, and shared modules.
  • Components that a user has created with the older extension version must be able to pass validation against the schemas provided by the newer version.
  • An Adobe Experience Platform user should be able to install an updated version of your extension and have everything they’ve done continue to function exactly as is until they make deliberate changes.

Allowed changes

The following types of changes to your extension are allowed:

  1. You may add new components (event types, condition types, etc).
  2. You may add new optional fields to your extension configuration settings.
  3. You may change required fields to optional fields.

Forbidden changes

The following types of changes to your extension are not allowed:

  1. You may not rename a component.
  2. You may not remove a component.
  3. You may not remove a field from a component.
  4. You may not change optional fields to required fields.
  5. You may not add new required fields.
  6. You may not change the API of existing shared modules.

If you make any of these changes, anyone who has installed your extension in their property will immediately begin to have problems such as:

  • Rules no longer render properly because one of the rule components is looking for a component that doesn’t exist
  • All builds fail because the Library includes an upstream resource that no longer exists on the Extension
  • All builds fail because the Library includes a resource with settings that fail validation against the new schema

Particularly in this second case, users can be left without a remedy and no way to fix their property so they can publish again.

Removing functionalities

There may be scenarios when you have a valid business reason and you think you really do need to make a forbidden change (listed above). You still can’t do it, but here’s what you can do instead:

  1. I want to remove a component => Make a new component and deprecate the old one
  2. I want to remove a field from a component => Make a new component with that field removed and deprecate the old one
  3. I want to change an optional field to be required => Make a new component requiring the desired field and deprecate the old one
  4. I want to change the API of a shared module => Make a new shared module and deprecate the old one

You may be picking up on a common thread. That’s good. When deprecating an old component, you’ll want to notify users of your extension that it has been deprecated and that they need to switch to a new one. A few suggestions on communicating with users:

  • Update the display name of the old component to include “(Deprecated)”.
  • Update the view for the old component to have big red warning text that this component has been deprecated and that the user should switch to the new component.
  • Update your module code to log deprecation notices in the console. Keep in mind that these will show to end-users, so keep it clean and somewhat generic.
  • Send nice friendly email messages from your CRM system.

In cases where the old functionality is not just undesired, but actually doesn’t exist in your solution anymore, there is one additional step you can take - but should only do after you’ve provided notice to your users and given them time to update.

  • Update the contents of your module so that it doesn’t do anything. This will remove the functionality from the user’s deployed library in the next build, but won’t break any of their rules or builds.