Identity Cloud

Manage self-service promotions using the UI

For background on self-service promotions, refer to Introduction to self-service promotions.

Lower and upper environments

Before you run a promotion using the UI, you must know which tenant environment is the lower environment and which is the upper environment. Refer to Lower and upper environments.

The UI uses a push model to promote configuration, so you need to run a promotion from the UI in the lower environment. However, you also need to have a tenant administrator account in the upper environment, as the UI in the lower environment needs to authenticate to the upper environment.

When a promotion is complete, you can view a report in the lower environment. You can also view the report in the upper environment.

Promotions UI functionality in the lower environment

In the lower environment, the promotions UI lets you:

  • View changes awaiting promotion to the upper environment

  • Promote changes to the upper environment

  • View history of promotions sent to the upper environment

This lower environment functionality exists in your development and staging environments only. It does not exist in your production environment, as that environment does not send promotions to another environment.

View changes awaiting promotion to the upper environment

  1. In the Identity Cloud admin UI of the lower environment, open the Tenant menu (upper right)

  2. Click Promote configuration.

  3. The Promotion tab shows a summary of the promotion status for the environment:

    1. Your development environment shows information about promoting from your development environment to your staging environment:

      idcloudui promotion summary development

    2. Your staging environment shows information about promoting from your staging environment to your production environment:

      idcloudui promotion summary staging

  4. Any changes made by you or other tenant administrators to static configuration are automatically detected and indicated in the Promotion tab.

    For example, in the screenshot below, the UI indicates that two configuration changes have been made—one to a journey and one to an email template:

    idcloudui promotion view changes development

Sign in to the upper environment

When you run a promotion or view promotion history, the UI in the lower environment shows a sign-in screen for the upper environment. This lets the UI in the lower environment authenticate to the upper environment using your upper environment tenant administrator account.

In your development environment, the sign-in screen title is Sign in to Staging:

idcloudui promotion screen title sign in development

In your staging environment, the sign-in screen title is Sign in to Production:

idcloudui promotion screen title sign in staging

To sign in:

  1. Enter the credentials of your tenant administrator account for the upper environment.

  2. Click Next.

  3. Complete the authentication journey to the upper environment:

    • If 2-step verification is already enabled for your tenant administrator account, follow the UI prompts to provide your second authentication factor.

    • If 2-step verification is not yet enabled for your tenant administrator account:

      1. Click Set up.

      2. Follow the UI prompts to set up a second authentication factor for your tenant administrator account.

      3. Follow the UI prompts to provide your second authentication factor.

    • Otherwise, if 2-step verification is not mandatory in the upper environment, you can click Skip for now to defer the setup of 2-step verification.

Promote changes to the upper environment

  1. In the Identity Cloud admin UI of the lower environment, open the Tenant menu (upper right)

  2. Click Promote configuration.

  3. Review the static configuration changes that are awaiting promotion. Refer to View changes awaiting promotion to the upper environment.

  4. Click Promote n Changes.

  5. If the UI shows a sign-in screen for the upper environment, follow the steps in Sign in to the upper environment.

  6. In the Lock Tenants? screen, click Lock and Continue to lock the lower and upper environments.

    idcloudui promotion lock tenants development

    Allow 1–2 minutes for the locking process to complete. When the environments are locked, the UI has restricted functionality.

  7. In the Review Promotion screen, check the static configuration changes that are awaiting promotion.

    • If you want to cancel the promotion:

      1. Click Cancel Promotion.

      This unlocks the lower and upper environments. Allow 1–2 minutes for the unlocking process to complete.

    • If you want to proceed with the promotion:

      1. Click Start Promotion

      2. In the Start Promotion? modal window click Start Promotion again.

      This promotes the static configuration changes from the lower environment to the upper environment. At the end of the promotion process, Identity Cloud services are restarted in the upper environment, and both environments are automatically unlocked. Allow 10–45 minutes for these combined processes to complete.

      If the UI shows an error message during the promotion process, refer to the following:

  8. When the promotion completes you have a choice of actions:

    • Click View report to view the promotion immediately in the promotion history.

    • Click Done to return to the Promotion tab.

      idcloudui promotion success

View history of promotions sent to the upper environment

  1. In the Identity Cloud admin UI of the lower environment, open the Tenant menu (upper right)

  2. Click Promote configuration.

  3. Click View promotion history.

  4. If the UI shows a sign-in screen for the upper environment, follow the steps in Sign in to the upper environment.

  5. In the Promotion History page, click a promotion date in the left menu to review a report:

idcloudui promotion history development

Promotions UI functionality in the upper environment

In the upper environment, the promotions UI lets you view a history of promotions received from the lower environment.

This upper environment functionality exists in your staging and production environments only. It does not exist in your development environment, as that environment does not receive promotions from another environment.

View history of promotions received from the lower environment

  1. In the Identity Cloud admin UI of the upper environment, open the Tenant menu (upper right)

  2. Click Tenant settings.

  3. Click the Details tab.

  4. Click View updates.

  5. In the Tenant Updates page, click a promotion date in the left menu to review a report.

Restricted functionality

When you run a promotion and lock the upper and lower environments, the UI restricts some functionality under Tenant Settings > Promotion until the environments are unlocked.

Restricted functionality in the lower environment

In the lower environment, the UI has the following restricted functionality:

  • The left menu is hidden.

  • The page header shows Tenant Locked on the left.

  • The page header shows a restricted dropdown menu on the right.

idcloudui promotion review development

If you sign out and immediately sign back in, you are redirected back to Tenant Settings > Promotion.

However, other tenant administrators that are already logged in and working in other parts of the UI do not have this restricted functionality. They and are not redirected to Tenant Settings > Promotion unless they sign out and immediately sign back in while the upper and lower environments are locked.

Restricted functionality in the upper environment

In the upper environment (staging environment only), the UI has the following restricted functionality:

  • The Promote n Changes button is disabled to prevent you from initiating a separate promotion.

idcloudui promotion summary tenant locked staging

Troubleshooting

Resolve failed integrity check for missing ESVs

When you run a promotion, the UI may show an error message that you have missing ESVs:

idcloudui promotion error esvs

This happens when the upper environment failed an integrity check for missing ESVs.

To resolve this:

  1. Click Download Report to download a CSV report of the affected configuration.

  2. Click Cancel and Unlock Tenants. This unlocks the lower and upper environments. Allow 1–2 minutes for the unlocking process to complete.

  3. For each ESV in the report, create an equivalent ESV in the upper environment.

  4. Start the promotion steps again.

Resolve failed integrity check for encrypted secrets

When you run a promotion, the UI may show an error message that you have encrypted secrets in your configuration:

idcloudui promotion error encrypted secrets

This happens when your lower environment configuration failed an integrity check for encrypted secrets.

To resolve this:

  1. Click Download Report to download a CSV summary of the affected configuration.

  2. Click Cancel and Unlock Tenants. This unlocks the lower and upper environments. Allow 1–2 minutes for the unlocking process to complete.

  3. For each encrypted secret in the report:

    1. Create an ESV secret containing the encrypted secret in each of the development, staging, and production environments.

    2. Update your configuration to reference the new ESV secret.

  4. Start the promotion steps again.

Resolve tenant locked errors

When you run a promotion, the UI may show an error message that your tenant is locked:

idcloudui promotion error tenant locked

This happens when a previous promotion failed and left the environments in an error state that cannot be automatically resolved.

To resolve environment errors that are preventing promotions, raise a support ticket:

  1. Go to the Backstage website, and click Support > Tickets.

  2. On the support tickets page, click New Ticket.

  3. On the New Ticket page, choose How Do I…​?.

  4. Provide values for the following fields:

    Section Field Value

    Product

    Product

    1. ForgeRock Identity Cloud

    2. REST API

    Details

    What are you trying to achieve?

    Resolve environment errors preventing self-service promotions

    Please provide a short description

    An error has occurred during a self-service promotion to the development/staging/production environment.

    Insert error code and message (API users only)

  5. Click Submit.

Revert a promotion

To revert a promotion, raise a support ticket:

  1. Go to the Backstage website, and click Support.

  2. On the ForgeRock Support page, click New Ticket.

  3. On the New Ticket page, choose Identity Cloud: Config Request.

  4. In the Request Type section, provide values for the following fields:

    Field Value

    Hostname

    Enter the FQDN of the upper environment from the promotion you need to revert.

    What would you like to do?

    Choose Restore from backup

  5. In the Restore from backup section, provide values for the following fields:

    Field Value

    What is the environment name?

    Choose the option that corresponds with the upper environment from the promotion you need to revert:

    • Dev

    • Staging

    • Prod

    What is the date of the backup you would like to restore from?

    Enter a date from before the promotion you need to revert, using the format YYYY-MM-DD.

  6. Click Submit.

Copyright © 2010-2022 ForgeRock, all rights reserved.