Promoting an App to the Next Environment

Learn about promoting an app 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.

In some cases, depending on the structure of the underlying topology, promotion might be to two or more environments rather than to a single environment in the chain. For more information, see What is promotion fanout?

Lifecycle Coordinator is a standalone user interface that's installed separately. This feature also includes modifications to the Community Manager developer portal user interface (Hermosa theme) to allow an app developer to promote an app to the next environment.

Lifecycle Coordinator

Within 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 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 feature allows an app developer 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.

Note: The Promotion feature is not available in Simple Developer theme.

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.

How do I know if the promotion feature is available for my app?

If the promotion feature is available for your app, you'll see an extra section to the right of your app's Details page, as shown below.

Note: In the example below, the Promotion feature is enabled for app developers, so the Promote button is available. If you see the right pane, but you don't see the Promote button, the feature is available but disabled in the Community Manager developer portal settings. See How do I promote my app?

Promotion feature for an app; Details page

The extra section shows:

  • Current environment / status in current environment
  • Environment chain / status in each environment
  • Promote button

How do I promote my app?

When your app is ready to be promoted, just click the Promote button, as shown below.

Promotion feature with Promote button enabled

In some cases, you might see the promotion feature in the right pane, but there is no Promote button, as shown below:

App promotion feature with Promote button disabled

In this scenario, the promotion feature is available, but an app developer cannot control the promotion process. This is controlled by the Site Admin in the site settings; see General API Settings: App Promotion. If you need help or have questions about your app promotion, contact a Site Admin for assistance.

Notes:

  • If you promote the app, and then find you need to make further changes, you can just make the changes and then promote it again. You can promote your app, from one environment to the next as many times as you need to. See Iterations above.
  • What happens to the app, after you click the Promote button is determined by the workflow in place in the Promotion Coordinator. For example, if approval is required, the resource isn't actually promoted until approval is granted.
  • If your app has contracts with APIs that haven't yet been promoted to the new environment, promotion will fail. Make sure the APIs are promoted first. To check your app's contracts, go to App > APIs. See My app has contracts with APIs. What happens with the contracts when I promote my app? below.

What are the different promotion states?

The basic lifecycle of an app 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? (Site Admin help).

My app has contracts with APIs. What happens with the contracts when I promote my app?

If your app has contracts with APIs, and the APIs exist in the new environment that you're promoting the app to, the contracts are automatically promoted at the same time, and your app will have the same contracts, with the same APIs, in the new environment.

However, if your app has contracts with APIs that don't exist in the new environment, you won't be able to successfully promote your app. In this scenario you can do either of the following:

  • Get the API or APIs promoted, and then promote the app.
  • Cancel the contracts, and then promote the app.

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.

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 the multiple target environments based on custom properties of the app or API.

In the 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