Promoting Assets from API Gateway User Interface

Edit online

Before you begin

Pre-requisites:
  • You must define a stage to represent the asset's lifecycle such as development, test, and production. For details about how to add a stage, see Adding a Stage.
  • You must have the Manage promotions functional privilege assigned to perform this task.

About this task

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

  1. Authorization server promotion: Promote Authorization server in one of the following ways:
    • Export the authorization server from one environment and import it into another, if you want to use the same authorization server across multiple environments.
    • Create the authorization server with the same name as in the current environment, if you want to use a different authorization server instance.

    Proceed to the next step once the authorization server is ready.

  2. 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 tot he selected team(s).
    • Search using two keywords.You can provide more than one keyword by separating the keywords using a pipe symbol (|). For example, to search for assets whose names contain pet and test, you can provide pet|test in the search field.
    • Search using wild card characters. You can use wild card characters in your search keyword. For example, to list all assets that start with graph, you can provide graph*.
  3. 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.
    Note: As groups and users are part of the team, if you want to promote the Groups and Users (optional dependencies) of the team that the selected asset belongs to, you have to set the enableTeamWork extended setting to true. Only then the Groups and Users sections appear.
  4. 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.
  5. Configure the promotion details: During this step, you provide the promotion-specific information.
  6. With API Gateway version 10.15 Fix 19, you can promote assets from API Gateway versions 11.0 and 11.1 into version 10.15.

    However, the following restrictions apply:

    • You cannot promote Keystores and Truststores from API Gateway 11.0 and 11.1 to version 10.15.
    • You cannot promote Approved Configurations from API Gateway 11.0 and 11.1 to version 10.15.
    • You cannot promote the standard teams - Administrators, API-Gateway-Providers, and Default from API Gateway 11.0 and 11.1 to version 10.15.
Important: If you plan to perform bulk promotion of assets from a source stage to a target stage, Software AG recommends you to perform the following:
  • Increase the value of maxRegexLengthInSearchQuery setting on the Extended Settings page under Administration > General in both the source and target stages, considering that the generated RegEx search query length may become longer during bulk promotion of assets. The default value of this property is 37000. When you increase the value, it can lead to higher memory and CPU utilization, particularly when dealing with complex regular expressions. Therefore, Software AG recommends to closely monitor any spike in memory and CPU usage while promoting assets. For example, if your RegEx search query's length is more than 37000, asset promotion fails indicating that the length of RegEx used in RegEx Query request has exceeded the allowed maximum. In such case, you must increase the value of maxRegexLengthInSearchQuery setting to more than the value specified in the error message.
  • Increase the value of the pg.gateway.elasticsearch.http.socketTimeout property, located at ​SAG_Install_Directory/IntegrationServer/instances/IS_Instance_Name/​packages/WmAPIGateway/config/resources/elasticsearch/config.properties​​. The default value of this property is 3000. To bulk promote assets, for example, 50 numbers, you would set the value of this property to 60000. Depending on the number of assets you want to promote, increment the value as 70000, 80000, and so on. You must restart API Gateway for changes to this property to take effect.

To promote assets

Procedure

  1. Expand the menu options icon , in the title bar, and select Promotion management.
  2. Select Promotions.
    The Promotions 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.
    Note: You can search multiple times for the same type while retaining the previous search results.
    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.
    Important: Authorization server, External Authorization server, and Providers are listed under the Aliases category. To select any of these assets, select the Aliases check box and then choose the required asset.
    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.
    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 which you want to promote the assets, dependencies, and administrative configurations to.
  12. Click Next.
    The Promote page appears.
  13. Provide the following information:
    Field Description
    Name Name of the promotion.
    Description Description of the promotion.
    Overwrite Select an overwrite option:
    • None. If you do not want to overwrite matching assets that exist on the server. If a matching asset exists on the target stage, then the promotion of that asset fails.
    • All. If you want to overwrite any matching asset that exists on the target stage.
    • Custom. If you want to select specific types of assets to be overwritten on the target stage if a match is found. If a matching asset exists on the target stage for an asset type that is not selected in the Custom overwrite list, then the promotion of that asset fails.
    Note:
    • Some assets types have dependencies on other asset types. For example, APIs have a dependency on policies, aliases, and applications. Some of the dependencies are required, while others are optional. The required dependencies are always included. You should consider your requirements and select the assets that need to be overwritten in the Custom list.
    • Some asset types can have multiple overwrite options organized in the form of a tree. When you select such an asset, all its components are displayed and selected by default. You can select a parent component without selecting any of its child components. However, you cannot select a child component without selecting its parent component. For example, when you select Applications, it expands and displays its components, Strategies and API Keys. Strategies, in turn, has a component Credentials. You can overwrite Applications without overwriting the API Keys. However, you cannot overwrite the API Keys without overwriting the Applications. Similarly you can overwrite Strategies without overwriting the Strategy Credentials, but not the other way round.
    Fix missing version Select the check box to fix the API version history. The discrepancy between the asset versions in the source and target stages, if any, are fixed.

    For example, consider that you have created an API and have five versions of the API from 1 to 5, in the source. If you select versions 1,2,4, and, 5 for promotion to the target, and if this check box is not selected, versions 1 and 2 are linked separately and versions 4 and 5 are linked separately. However, if you select this check box, version 2 is linked to version 4 and hence all versions 1,2,4, and 5 are now linked in the target.

    Include application registrations Select the checkbox to include the application registrations when you promote an API.

    When you promote APIs from versions 11.0 or 11.1 to 10.15, they lose their registration to applications on the target API Gateway. To avoid this issue, select the Include application registrations option during deployment.
  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.