Promotion Feature

Learn about the promotion feature, which allows promoting APIs and apps to the next environment.

Table of Contents

What is the promotion feature?

The platform includes an add-on feature, Lifecycle Coordinator, which allows the Administrator to define a one-way topology that includes a chain of environments reflecting the development lifecycle. For example, the topology chain could be from Development to Testing to Staging to Production. Each environment is a separate installation of the Community Manager developer portal.

Lifecycle Coordinator is a standalone user interface that's installed separately. This feature also includes modifications to the Community Manager developer portal user interface to allow the API Admin or app developer to promote the app or API to the next environment.

Lifecycle Coordinator

Within the Lifecycle Coordinator, the authorized user can:

  • Define and manage the environment topology (two or more environments in a unidirectional chain).
  • Set up processing rules that are executed when an app or API is promoted from one specific environment to the next. For example:
    • A rule might change the target URL host for the physical services when an app or API is promoted from Staging to Production.
    • A rule might deploy an app or API to different deployment zones in the Production environment depending on the PCI compatibility of the resource.
    • A rule might define an approval required for the resource to be promoted to the next environment. If approval is required, the resource will be in a Promotion Pending state until the promotion is approved.

This feature includes a user permission specifically for the user who manages the Lifecycle Coordinator.

For more detailed information about the Lifecycle Coordinator feature, refer to the Lifecycle Coordinator Promotion Guide.

Community Manager developer portal

Within the Community Manager developer portal user interface, the new feature allows the API Admin or Business Admin to promote an API from the current environment to the next step in the environment topology.

When the user in the Community Manager developer portal promotes the app or API, it is passed to the Lifecycle Coordinator. The next steps are governed by the process set up in the Lifecycle Coordinator. For example, if a manual approval is required, approval is requested. If processing rules are in place, the rules are applied to the data before it is promoted to the next environment. The status of the promotion request is reflected in the Community Manager developer portal user interface; for example, Promoted or Promotion Pending.

Iterations

A resource can be promoted to the next lifecycle stage multiple times, each time being an iteration of the resource, to accommodate a development scenario where multiple changes are made before it is fully mature and ready to move to the next stage.

For example, an app or API might be promoted from Development to Testing, and some errors found in Testing. It can then be updated in the Development environment and promoted to Testing again, possibly multiple times until it fully passes Testing and is ready to be promoted to the next lifecycle stage in the next environment.

In the Lifecycle Coordinator, each of these iterations is stored, for historical tracking and non-repudiation.

Deployment

In terms of deployment, the Lifecycle Coordinator can be co-located with any one of the tenants, or it can stand alone and communicate remotely with any of them.

What resources can the promotion feature be used with?

The promotion feature is available for the following resources:

How is the promotion feature enabled?

The promotion feature required some feature installation and configuration outside the Community Manager developer portal. This is all done by an Administrator.

When the feature is set up and configured, the Site Admin can enable it for the Community Manager developer portal in the configuration settings ( More > Admin >Settings):

How is the promotion feature set up and configured?

If you're a Site Admin and want more detailed information about installing the Lifecycle Coordinator feature and setting up the promotion hierarchy, refer to the Lifecycle Coordinator Promotion Guide.

What are the different promotion states?

The basic lifecycle of an API goes from Not Promoted to Promoted in each environment. In some cases, approval of a promotion request might be required.

For details of the promotion states and their sequence, see What are the valid statuses and lifecycle for a promotion request? (Lifecycle Coordinator help).

What is promotion fanout?

The basic structure of an environment topology is linear; for example, from development to testing to production. However, in some cases a topology might include two or more environments at the same level. Perhaps there are two testing environments, for testing under different criteria sets; or there might be three production environments, each at a different global location.

The diagram below shows a very simple example of a fanout, where one environment can be promoted to two production environments:

Promotion fanout diagram

When the topology includes more than one environment at the same level, this is called fanout. When an app or API is promoted from one environment to the next level, which includes two or more environments, the fanout behavior can be either of the following:

  • It is promoted simultaneously to all environments that are at the next level.
  • It is promoted to multiple target environments based on custom properties of the app or API. For example, asset-filters might be set up based on one or more custom properties

The fanout behavior is determined by the topology definition in Akana Lifecycle Manager.

In the Community Manager developer portal user interface, fanout is shown by indentation. In the example below, there is one development environment, and one staging environment and there are two production environments.

Promotion fanout

An example of promotion based on custom properties:

  1. In the topology definition, you could set up asset-filters based on a Boolean property called external, with external and internal filters defined based on that property.
  2. Different production environments for internal and external APIs.
  3. Assuming the environment prior to production is acceptance, you could define two promotion profiles on the acceptance environment: one that specifies the internal filter and points to the internal production environment, while the other specified the external filter and points to the external production environment.

With the above configuration, the APIs are effectively routed based on the value of the external property.

How can I define different paths through the promotion hierarchy ("join" feature)?

You might encounter a scenario where you want to be able to set conditions to determine which environment resources will be promoted to, depending on certain circumstances.

For example, let's take the very simple two-tier fanout hierarchy shown in What is promotion fanout? above. You might want to be able to conditionally determine which of the below will apply:

  • Promote to a test environment and then to an external production environment.
  • Promote to an internal production environment speedily, without going through the testing stage first.

You can implement this by using conditional properties on your resource, and setting up the promotion profile to filter based on the values of the conditional properties.

The diagram below shows a very simple example of this hierarchy.

Promotion fanout diagram

In the example shown below, a property was defined on APIs, with a filter in the relationship between the environments, which is a property defined in the Promotion Profile. This allows filtering on the property.

At runtime, the Internal property appears as a selection field on the API Details page, as shown below.

Promotion join: conditional field determining hierarchy

In this example, there are three choices:

Results if user selects True

If the user selects True in the Internal field, meaning that the production environment is internal, the resource can be promoted from the development environment to the production environmen, as shown below.

Promotion join: user selects Internal=True

Results if user selects False

If the user selects False in the Internal field, meaning that the production environment is not internal, the resource can be promoted from the development environment to the test environment, and then to the production environment, as shown below.

Promotion join: user selects Internal=True

Results if user doesn't make a selection

If the user doesn't make a selection the Internal field, and the field is not marked as required, the platform cannot determine which environment is next. In this case, no promotion environment is available. The Promote button is grayed out in the user interface, as shown below, until the user makes a selection.

Promotion join: user selects Internal=True

This approach enables you to set up a conditional promotion hierarchy.

The example above shows implementation for an API. It works in exactly the same way for an app.

Note: For details about how to set up the promotion profile, including details about setting up filters, refer to the Lifecycle Coordinator Promotion Guide.