Asset Promotions

API Gateway supports staging and promotion of assets. In a typical enterprise-level, solutions are separated according to the different stages of Software Development Lifecycle (SDLC) such as development, quality assurance (QA), and production stages. As each organization builds APIs for easy consumption and monetization, continuous integration (CI) and continuous delivery (CD) is an integral part of the solution. CI is a development practice that requires developers to integrate code into a shared repository several times a day, and CD is a software engineering approach in which teams produce software in short cycles, ensuring that the software can be reliably released at any time.

Manage Stages, Promotions, and Rollbacks

API Gateway provides the staging and promotion feature to automate the CI and CD practices. Modifications made to the APIs, policies, and other assets can be efficiently delivered to the application developers with speed and agility.

Staging and promotion allows you to:

Stages

The fundamental phases of assets starts with requirements or needs at the development stage and once the assets are developed, they are promoted to the QA stage for testing, after testing of the assets is complete, the assets are promoted to the production stage.

An asset’s overall lifecycle can be split across two or more API Gateway instances. For example, assets that are in the development and test phases of their lifecycle can be maintained in one instance and assets that are deployed (that is, in production) can be maintained in a separate instance.

When the asset’s lifecycle is split across multiple API Gateway instances, each participating instance is referred to as a stage. A stage definition in API Gateway describes an API Gateway instance by its name and configuration information.

Note: Software AG recommends you to have API Gateway instances across stages to be completely independent. For example, the API Gateway instances from the Development stage and the API Gateway instances from the QA stage must not share any resources in common such as databases.

Adding a Stage

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

API Gateway can contain one or more stages. You define a stage to represent the asset’s lifecycle such as development, test, and production.

To add a stage

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Click Add Stage.

  3. Provide the following information in the Basic information section:

    Field Description
    Name Mandatory. Name of the stage.
    Note: A stage name must be unique within API Gateway.
    Description Description of the stage.
  4. Provide the following information in the Technical information section:

    Field Description
    Stage URL Mandatory. The URL of the host machine where the stage is deployed on an API Gateway installation.
    The Stage URL value is specified in the format, <scheme>://<host>:<port>. The scheme is http or https. The host is the host name of the machine on which the target API Gateway instance is running. The port is the port number of the target API Gateway instance.
    Username Mandatory. The username of a registered API Gateway user who has the Manage promotions or Manage assets functional privilege in the target API Gateway instance.
    Password Mandatory. A valid password of the API Gateway user identified by the attribute Username.
    Keystore alias The alias of the keystore containing the private key that is used for performing asset promotion from one (source) stage to another (target) stage.
    The Keystore alias field contains a list of the available keystore aliases in API Gateway. If there are no configured keystore aliases, this field lists the default Integration Server keystore, DEFAULT\_IS\_KEYSTORE.
    Note: This field is required when the Stage URL scheme is set to https
    Key alias (signing) The alias of the private key that is stored in the keystore specified by the keystore alias.
    The Key alias field contains a list of the available aliases in the selected keystore. If there are no configured keystores, this field is empty.
    Note: This field is required when the Stage URL scheme is set to https
  5. Click Save.

Viewing Stage List and Stage Details

The Stages tab displays a list of the available stages in API Gateway.

In addition to viewing the list of stages, you can also examine the details of a stage and delete a stage in the Stages tab.

To view the stage list and stage details

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.
    The Stages tab displays a list of available stages. This tab provides the following information about each stage:

    Column Description
    Name Name of the stage.
    Description The description for the stage.
  2. Click the required stage whose details you want to examine.
    The Stage details page appears. The stage details are displayed in the following sections:

    • Basic information: This section contains the stage name and description.

    • Technical information: This section contains the stage specific URL, authentication credentials to access the stage, and the keystore configurations.

Modifying Stage Details

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

You can modify the basic or the technical information of a stage at any time.

To modify the stage details

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.
    The Stages tab displays a list of available stages.

  2. Click the required stage whose details you want to modify.
    The Stage details page appears.

  3. Click Edit.
    This opens the basic information of the stage.

  4. Modify the basic information as required.

  5. Click Technical information.
    This opens the technical information of the stage.

  6. Modify the technical information as required.

  7. Click Save.

Deleting a Stage

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

You delete a stage to remove it from API Gateway permanently. You can remove a stage at any time.

To delete a stage

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.
    The Stages tab displays a list of available stages.

  2. Click the Delete icon for the stage that you want to delete.

  3. Click Yes in the confirmation dialog.

Promotions

Promotion refers to moving API Gateway assets from the source stage to one or more target stages. For example, you might want to promote assets you have developed on servers in a Development stage (the source API Gateway instance) to servers in a QA or Production stage (the target API Gateway instance). When you promote an asset from one stage to another, the asset’s metadata is copied from the source instance to the target instance.

Note: For the list of assets and configuration settings that can be promoted, see Assets that can be exported and imported.

Assets that are dependencies for the asset are also promoted. The required dependencies of an asset are always promoted with the asset. However, you can choose which optional dependencies are promoted at the time of promoting the asset. For example, at the time of promoting an API, the policies and aliases used by the API are always promoted. However, you can choose which dependent applications are promoted as applications an optional dependency for APIs. You can choose to promote all or no application, or select specific applications that you want to included with the API in the promotion.

The following table lists the required and optional dependencies of assets that are supported by promotion management.

Asset Dependencies (Required) Dependencies (Optional)
APIs Policies, Aliases Applications
Applications APIs
Packages APIs, Plans, Policies, Subscriptions
Plans Policies
Subscriptions Packages, Plans Applications
Teams Group
Approval configurations Access profiles
Configuration > Keystore Keystore, Truststore
Email destination Trust store
Service Registry Keystore, Truststore
Custom destinations Keystore, Truststore, Aliases

Note: Till API Gateway version 10.3, promotion management supported only the simple and endpoint types of aliases. Starting from API Gateway version 10.4, all types of aliases are supported.

Promoting Assets

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

Promoting assets from one (source) stage to another (target) stage includes the following high-level steps:

  1. Select assets for promotion: During this step, you search for assets by using a keyword and by performing a type search that sorts and filters the results.

    • Search using a keyword: You can search for all assets whose string attributes (asset name, description, and so on) contain a certain keyword (character string).

    • Search using a Type: You can search for assets on the basis of types.
      You may use the Search by type filter to restrict the types on which the search is conducted. In the Search by type panel, API Gateway shows you a list of supported asset types.

    • Search by team: You can search for assets assigned to team(s). Click the team(s) to view the assets that are assigned to the selected team(s).

  2. Optionally select assets’ dependencies for promotion: During this step, you specify whether the dependencies (for example, a list of applications that are registered for an API, subscriptions for a package, and so on) of the selected assets will be included for the promotion.

  3. Select the stages to promote: During this step, you specify one or more target stages to which you want to promote the selected assets and their dependencies.

  4. Configure the promotion details: During this step, you provide the promotion-specific information.

To promote assets

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Promotions.
    The Search page appears.

  3. Click Promote.

  4. In the Search by keyword text box, type the keyword to search for assets. You can use one or more wildcards to specify the keywords.
    API Gateway returns the assets that match the specified keyword.

  5. In the Search by type drop-down list, select the required type(s). Select the All check box to search across all asset types.
    API Gateway returns the assets that match the selected type(s). The number of search results is displayed in the results area, for example, Showing 10 results. If no results are found, the results area is displays a blank page.

  6. Optional. Select the Include admin configurations check box if you want to include administrative configurations in the promotion.
    API Gateway displays the administrative configurations that are supported for promotion. For the list of assets and configuration settings that can be promoted, see Promotions.

    Important: Before you configure API Gateway to promote an administrative configuration, make sure that the corresponding administrative settings are already configured in API Gateway. For example, to include the Load balancer configuration in the asset promotion set, the required Load balancer URLs should be configured.

  7. Select the assets and the administrative configurations that you want to promote.

  8. Click Next.
    The Assets and dependencies page appears.

  9. Select the referenced assets that you want to promote.

  10. Click Next.
    The Stages page appears.

  11. Select the target stages to that you want to promote the assets, dependencies, and administrative configurations.

  12. Click Next.
    The Promote page appears.

  13. Provide the following information:

    Field Description
    Name Mandatory. Name of the promotion.
    Description Description of the promotion.

    Note: The Overwrite assets if exists on selected stages option allows you to overwrite assets that exist on the target stages. If you do not want to overwrite assets in the target stages, clear this check box.

  14. Click Promote.
    The selected assets, dependencies, and administrative configurations are promoted to the selected stages.

    The Stage-specific promotion status page displays the status of the asset promotion in each of the selected stages. The available values are:

    • Success

    • Failure

    The page also displays the reason if the promotion fails.

Viewing Promotion List and Promotion Details

The Promotions tab displays a list of the available asset promotions in API Gateway. The asset promotions are listed alphabetically by name.

In addition, you can examine the details of an asset promotion history, repromote assets to the configured stages, and delete the promotion history from API Gateway database in the Promotions tab.

To view the promotion list and promotion details

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Promotions.
    The Promotions tab displays a list of available asset promotions. This tab provides the following information about each promotion:

    Column Description
    Name Name of the stage.
    Promoted by Name of the user who initiated the asset promotion.
    Promotion time The time at which the asset promotion occurred.
    Status The status report on the asset promotion.
  3. Examine the Report link in the Status column and check for any errors that occurred during the asset promotion.
    The Promotion status report displays the following information:

    Column Description
    Asset type Name of the asset type that was promoted from the source instance.
    Name Name of the asset that was promoted from the source instance.
    Status The status of the asset promotion.
    Comments A descriptive comment on the asset promotion status.
  4. Click the required promotion whose details you want to examine.
    The Promote page appears.

Repromoting Assets

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

If you have made recent changes to an asset’s information, you can repromote the updated asset to the already promoted target stages.

If you need to update an asset, for example, you need to correct an attribute setting, modify the asset’s description, that has already been promoted to a target stage, you can simply make the change directly to the asset in the source target and then repromote the updated asset to the target stage just as you did with the previous version of the asset. In a multi-stage environment, you will need to repromote the updated assets in each of the participating API Gateway instances.

To repromote assets

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Promotions.
    The Promotions tab displays a list of available promotion histories in API Gateway.

  3. Click the Repromote icon for the required assets’ promotion history.
    The Stages page appears.

  4. Select the target stages to that you want to repromote the assets, dependencies, and administrative configurations.

  5. Click Next.
    The Promote page appears.

  6. Provide the following information:

    Field Description
    Name Mandatory. Name of the promotion.
    Description Description of the promotion.

    Note: The Overwrite assets if exists on selected stages option allows you to overwrite assets that exist on the target stages. If you do not want to overwrite assets in the target stages, clear this check box.

  7. Click Promote.
    The selected assets, dependencies, and administrative configurations are repromoted to the selected stages. The Stage-specific promotion status page displays the status of the asset repromotion in each of the selected stages. The available values are:

    • Success

    • Failure

    The page also displays the reason if the repromotion fails.

Rollbacks

Rollback is the process of restoring the asset’s metadata in the target API Gateway instance to a previous state.

You might need to rollback assets to revert any promotional data changes being made in the target API Gateway instance.

Rollback Asset Promotions

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

You can rollback an asset promotion that is already available in the target stage at any time.

To rollback asset promotion

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Rollbacks.
    The Rollbacks tab displays a list of available promotion histories.

  3. Click the Rollback icon for the promotion history that you want to rollback.

  4. Click Yes in the confirmation dialog.

Viewing Rollback List and Rollback Details

The Rollbacks tab displays a list of the available asset promotion rollbacks in API Gateway. The rollbacks are listed alphabetically by name.

In addition, you can also examine the details of a rollback, and delete the rollback history in the Rollbacks tab.

To view the rollback list and rollback details

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Rollbacks.
    The Rollbacks tab displays a list of available asset promotion rollbacks.

    This tab provides the following information about each rollback:

    Column Description
    Name Name of the rollback.
    Promotion time The time at which the asset promotion was rolled back.
    Status The status report on the rollback operation.
  3. Examine the Report link in the Status column and check for any errors that occurred during the rollback process.
    The Promotion status report displays the following information:

    Column Description
    Asset Type Name of the asset type that was promoted from the source instance.
    Asset Name Name of the asset that was promoted from the source instance.