Migrating application subscribers to new Product versions

Edit online

When new versions of Products are created in IBM® API Connect, there are a number of ways that subscribers can be moved to the Plans of the new Product.

About this task

You can move users to the new Plans in different ways, depending on your Product strategy, by using the options icon options icon alongside the Product in the associated Catalog in the API Manager UI.

Procedure

To automatically migrate all existing subscribers to a new Product, for example, when you are applying fixes to a Product:
  • You should Replace the original version of the Product with a new version of the Product.
    • The replacement Product is Published.
    • The original Product is Retired.
    • The subscribers to the original Product are automatically migrated to the replacement Product.
    For more information about replacing Products, see Replacing a Product with another Product.
To encourage subscribers to move to a new Product, and stop new users from subscribing to the original Product, for example, if an enhancement or new feature is added:
  • You should Supersede the original version of the Product with a new version of the Product.
    • The superseding Product is Published.
    • The original Product is Deprecated.
    • The application developers that are already subscribed to the now deprecated Product can continue to use it, but no new developers can subscribe to the Product. In the Consumer Catalog the subscribers will see a Migrate this subscription message, which they can click to upgrade their subscription to the migration target.
    For more information about superseding Products, see Superseding a Product with another Product.
To prepare a Product to be removed from production, but leave the existing subscriptions as they are:
  • You should Deprecate the original Product.
    • The Product is Deprecated.
    • The application developers that are already subscribed to the now deprecated Product can continue to use it, but no new developers can subscribe to the Product.
    • You can define a replacement Product by using the Set Migration Target option in the Catalog. Application developers will then see a Migrate this subscription message in the Consumer Catalog that they can click to upgrade their subscription to the migration target.
    • Use Set Migration Target option to perform the same function as the Supersede option. It prepares subscriptions for migration to the destination product but does not deprecate the source product. The destination product must already be published.
      Note:

      Both Supersede Product and Set Migration Target assume that the source product will no longer be used after all subscriptions are migrated and that it will not be used as a migration target in the future.

      These options are typically used when a new version of product A supersedes an older version of the same product. The source and destination products are labeled with the attributes superseded_by and supersedes, respectively.

    • Use Execute Migration Target to force the migration of all subscriptions from a superseded product before retiring it.
      Note:

      Supersede Product and Set Migration Target prevent setting the migration target to an older product version to avoid circular dependencies, where two products point to each other as migration targets.

      To reset the migration target to an older version, first clear the superseded_by and supersedes settings created by Supersede Product or Set Migration Target. Then, run Execute Migration Target to migrate all subscriptions to the destination product.

      After all subscriptions are migrated, retire the source product. To reuse it, restage and republish it before using Set Migration Target with the older version.

    For more information about deprecating Products, see Deprecating a Product.