Replacing a Product with another Product

You can replace a published Product in IBM® API Connect with another Product, and automatically migrate subscribers to the new Product, by using the API Manager.

Before you begin

The Product to be replaced must be in the Published state, and the replacement Product must be in the Staged, Published, or Deprecated state.

To complete the product management tasks that are described in this topic, you must either be the owner of the API provider organization, or be assigned Manage permission for products in the catalog that contains the product. If you have View permission for products, you have read-only access to the product management page. For information on configuring product management permissions for a catalog, see Creating and configuring catalogs.

The syndication feature in IBM API Connect means that products can be contained within a space in a catalog. In this case, to complete the product management tasks that are described in this topic, you must either be the owner of the API provider organization, or be assigned Manage permission for products in the space that contains the product. For information on configuring product management permissions for a space, see Managing user access in a space.

About this task

When you replace a Product with another Product, the following actions are taken:
  • The replacement Product is published.
  • If the visibility and subscribability settings in the replacement Product are such that access is the same as, or less restrictive than, the original Product, the settings in the replacement Product are used. If the settings in the replacement Product are more restrictive, meaning that fewer consumer organizations can see or subscribe to the Product, the replace operation fails. For more information on visibility and subscribability settings, see Changing the availability of a Product.
  • The subscribers to the original Product are migrated to the replacement Product.
  • The original Product is moved to the Retired state. Products in the Retired state are removed from the Developer Portal; they are no longer visible to the application developers, and any subscriptions to them are canceled. However, the Product can be staged again later if required.

Although you can publish to a development Catalog, the development Catalog should be used only for testing purposes. Similarly, a Developer Portal created from a development Catalog must be used for testing purposes only, and not for production use. For more information on Catalogs, see Working with Catalogs.

Note: All references in this topic to a Catalog, can also be applied to a Space in a Catalog, unless specified otherwise.

Procedure

To replace a Product, complete the following steps:

  1. In the navigation pane of the API Manager UI, click Manage icon in the API Manager UI navigation pane Manage catalogs, then select the catalog that you want to work with.
    The Products page of the catalog opens, and all of the products available in that catalog are displayed.
  2. If the product that you want to work with is contained within a space, select the required space by completing the following steps:
    1. Click the Spaces tab.
    2. Select the space that you want to work with.
    The Products page of the space opens, and all of the products available in that space are displayed.
  3. Alongside the Product version that you want to replace, click the options icon ACTION icon, then click Replace.
    The Replace window opens.
  4. Select the replacement Product, then click Next.
  5. From the drop-down list, select which Plans from your new Product correspond to Plans in your old Product.
  6. Click Replace.
    If approval is required to replace Products in this Catalog, an approval request is sent, and the Product moves to the Pending state; the Product is replaced when the request is approved. If approval is not required, the Product is replaced immediately. For information on configuring product lifecycle approvals for a catalog, see Creating and configuring catalogs. For information on approving requests, see Approving product lifecycle and subscription requests.
    Note:
    • Approval for product lifecycle state changes in a catalog is disabled by default. You must explicitly enable the product lifecycle state changes that you want to enforce.
    • Product lifecycle approvals can be configured only at the Catalog level. This feature is not available at the Space level.
    • To view the subscription tasks history, complete the following steps:
      • In the navigation pane of the API Manager UI, click Manage, then select the catalog that you want to work with.
      • Click Tasks tab.
      • Click Approvals history from the navigation pane.
    • You can view the history of Product lifecycle requests and approvals, by clicking the options icon options icon alongside the Product that you want to work with, and selecting View Approval History.

Results

Your new Product is in the Published state, and the original Product is in the Retired state.

Your new Product is published to your preferred organizations or communities. Application developers within the groups you selected can see and use the APIs within the Product.

Any application developer requests to use your Product are displayed on the Approvals tab in the containing Catalog, where you can decline or accept the request.