Promote Environment¶

Overview¶

The Promote Environment feature lets you review APIs mapped to gateway environments and promote an API into an additional gateway environment from a single view.

With this feature, you can:

See which gateway environments each API is mapped to.
View API publishing details and per-environment domain mappings.
Promote an API to a target environment that is not already attached.
Track Approval Status and, when a workflow is attached, submit promotions for approval.

Promotion in the API Manager means attaching the API to a new gateway environment — not changing backend service URLs from API onboarding.

Scope¶

API list with current gateway environment mappings.
Read-only view of API and environment details.
Promote action to attach an API to a new target environment.
Approval status visibility and Submit for Approval when an Environment workflow is attached.
Search and list navigation.

Outcome¶

APIs available on additional gateway environments.
Clear visibility into which environments an API already uses.
Auditable promotion workflow from a single Gateway Control page.

When to Use Promote Environment¶

Use this feature when:

An API is already mapped to at least one gateway environment and you need it on another.
You have created target environments in Environments and want to attach APIs to them.
You need to review published URLs and domain mappings before promotion.

When Not to Use Promote Environment¶

Do not use this feature when:

No gateway environments exist yet — create them in Environments first.
You only need to change backend service URLs — use Onboard APIs or Onboard SOAP APIs.
The API is already mapped to every available gateway environment — there is no remaining target to promote to.

Prerequisites¶

Required Access and Permissions¶

Users must have:

API Manager access.
Permission to promote APIs to gateway environments.

System / Technical Requirements¶

At least one gateway environment created in Environments.
At least one published API.
A target environment that is not already in the API's environment list.

What Promotion Means¶

When you promote an API:

You select a target gateway environment from environments not already attached to that API.
The platform attaches the API to that environment (immediately, or after approval if a workflow is attached).
The API becomes available through the target environment's domains.

Promotion does not:

Change backend URLs configured during onboarding.
Replace or remove existing environment mappings — it adds a new one.

Step-by-Step Implementation¶

Reviewing API Environment Mappings¶

Step 1: Navigate to Promote Environment¶

From the left navigation panel, open Gateway Control → Promote Environment.

Step 2: Locate an API¶

Use the search bar to filter by API name (Search by API Name).
Review columns on the promotions list: API Name, Environment Name, No.of.Domains, Promote, Approval Status, Last updated, View.

In the Environment Name column, the default environment is shown as Default. If an API is mapped to more than two environments, additional names are summarized (for example, Default, Staging, 2 more).

Approval Status shows the latest promotion approval state for the API (for example, Pending, Approved, Rejected, or Scheduled). If no status is returned, the UI treats it as Approved.

Step 3: Open the View Dialog¶

Click View (eye icon) on the API row.

Step 4: Review API and Environment Details¶

The View {API Name} dialog shows:

Section	Details
API summary	`API Name`, `URLs` (list of published URLs, or `—` if none)
Environment tabs	One tab per mapped environment; default environment is listed first
Per-environment details	`Domains` (count and comma-separated list), `Default` (Yes or No)

Click Close when finished.

Promoting an API to a Target Environment¶

Step 1: Open the Promote Dialog¶

In the promotions list, click Promote on the API row.

Step 2: Review the Summary¶

The Promote Environment dialog opens with the same API and environment summary as the view dialog:

API Name, URLs
Environment tabs with Domains and Default status

Step 3: Select a Target Environment¶

In Select Environment, search and choose a target environment.
Placeholder: Search and Select Environment.
Only environments not already attached to this API appear in the list.
Each option shows the environment name and a domain preview. Use the chevron on an option to open Environment Details (name, domains, dataplane) without leaving the dialog.

Step 4: Confirm Promotion¶

The primary action is disabled until a target environment is selected.
Click the primary button to run the promotion:
Promote — when no approval workflow is attached to the API for environment promotion.
Submit for Approval — when an Environment approval Workflow is attached. Approvers process the request in Pending Approvals.

Success

A confirmation message appears, then the promotions list refreshes and the dialog closes:

Promote — "Environment promoted successfully"
Submit for Approval — "Environment promotion request submitted for approval."

Best Practices¶

Practice	Reason
Create target environments before promoting	Promotion requires available environments not already attached
Review the view dialog first	Confirms current mappings, domains, and published URLs
Verify domain configuration on the target	Promotion uses the target environment's domains
Promote to one environment at a time	Each promotion attaches a single new environment
Re-check the list after promotion	Confirms the new environment appears in the API's mapping and that Approval Status updates as expected

Troubleshooting¶

Issue	Possible Cause	Resolution
No APIs in the list	No APIs are mapped to gateway environments yet	Ensure APIs are onboarded and associated with environments
No options in Select Environment	All environments are already attached to this API	Create a new environment in Environments or choose a different API
Promote / Submit for Approval disabled	No target environment selected	Select a target from `Select Environment`
Button shows Submit for Approval	An Environment approval workflow is attached	Confirm and submit; ask an approver to process it in Pending Approvals
Approval Status stays Pending	Approvers have not completed the request	Open Pending Approvals and approve or reject the Environment request
Promotion failed	Server or validation error	Retry after verifying the API and target environment still exist
Expected environment not in dropdown	Environment already attached to the API	Use `View` to confirm current mappings
Empty list message	No promotable API-environment data	Confirm APIs exist and gateway environments are configured

Frequently Asked Questions¶

What does promoting an API do?

It attaches the API to an additional gateway environment so the API is available through that environment's domains.

Can I promote to an environment the API already uses?

No. Environments already mapped to the API are excluded from the Select Environment dropdown.

Do I need to create environments first?

Yes. Create gateway environments in Environments before promoting APIs to them.

When does the button say Submit for Approval instead of Promote?

When an approval Workflow for the Environment module is attached to the API. The promotion then waits for approval in Pending Approvals.

Does promotion change backend URLs?

No. Backend URLs are configured during API onboarding. Promotion only affects gateway environment mappings.

Tip

Use View before Promote to confirm published URLs and existing domain mappings. This reduces mistakes when selecting a target environment.