Manage self-service promotions using the API
For background on self-service promotions, refer to Introduction to self-service promotions.
Lower and upper environments
Before you run any promotions API requests, you must know which tenant environment is the lower environment and which is the upper environment. Refer to Lower and upper environments.
The API uses a pull model to promote configuration, so most API commands need to be run against the upper environment.
Dry-run promotions
When you are ready to run a promotion, you can optionally perform a dry run first. This lets you identify any problems with missing ESVs or encrypted secrets, before you run a full promotion.
Reports
Promotions API endpoints
To use the promotions API, refer to the following Identity Cloud API endpoints:
To authenticate to promotions API endpoints, use an
access token created with the
fr:idc:promotion:*
scope.
The following diagram summarizes how promotions API commands are used to run a promotion. Refer to Steps to run a promotion.
Check the lock state and the promotion status
You need to check the lock state and the promotion status several times during a promotion, and analyze the responses in order to decide how to proceed.
Check the lock state
To check the lock state, use the /environment/promotion/lock/state
endpoint:
curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/lock/state' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
1 | Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment. |
2 | Replace <access-token> with an access token for the upper environment (refer to
Get an access token). |
Refer to Steps to run a promotion to understand how to analyze the response from this endpoint.
Check the promotion status
To check the promotion status, use the /environment/promotion/promote
endpoint:
curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/promote' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
1 | Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment. |
2 | Replace <access-token> with an access token for the upper environment (refer to
Get an access token). |
Refer to Steps to run a promotion to understand how to analyze the response from this endpoint.
Steps to run a promotion
Step1: Check that the environments are unlocked
-
Check the lock state to confirm that both environments are unlocked. This is indicated in the response when
result
has a value ofunlocked
:{ "description": "Environment unlocked", "lowerEnv": { "state": "unlocked" }, "result": "unlocked", "upperEnv": { "state": "unlocked" } }
Step 2: Lock the environments
Locking an environment prevents configuration changes that could disrupt a promotion; however, all authentication flows continue to work as normal. |
-
To lock the environments, use the
/environment/promotion/lock
endpoint to create a lock request:curl \ --request POST 'https://<tenant-env-upper-fqdn>/environment/promotion/lock' \(1) --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Authorization: Bearer <access-token>'(2)
1 Replace <tenant-env-upper-fqdn>
with the FQDN of the upper environment.2 Replace <access-token>
with an access token for the upper environment (refer to Get an access token).-
If the lock request is successful, the response
result
has a value oflocking
:{ "description": "Environment lock in progress", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "result": "locking" }
-
If the lock request is rejected, the response
code
has a value of409
.-
In the example below the lock request was rejected because a lock already exists:
{ "code": 409, "message": "Environment is already locked for promotion 791eb03a-7ec1-42ae-ae84-ed142cf52688" }
To resolve this:
-
If another member of your team is already running a promotion:
-
Wait until the team member has completed their promotion and has released the lock.
-
Start the promotion steps again.
-
-
If the lock has accidentally been left in place, and no one else is running a promotion:
-
Unlock the environments using the promotion ID stated in the error message.
-
Start the promotion steps again.
-
-
-
In the example below the lock request was rejected because ForgeRock locked the environment:
{ "code": 409, "message": "Environment is locked by ForgeRock for maintenance. Retry later." }
ForgeRock typically locks an environment so that ForgeRock Support engineers can investigate an issue or perform maintenance. To resolve this, wait until ForgeRock releases the lock.
-
-
If the lock request causes an unexpected error, the response
code
has a value of500
.{ "code": 500, "message": "<internal-error-message>" }
To resolve this, submit a ForgeRock Support ticket. See Resolve environment errors that are preventing promotions.
-
-
Check the lock state to confirm that the lock is in progress. This is indicated in the response when
result
has a value oflocking
:{ "description": "Environment lock in progress", "lowerEnv": { "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "state": "locking" }, "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "result": "locking", "upperEnv": { "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "state": "locking" } }
-
Check the lock state as many times as you need until both environments are locked. This is indicated in the response when
result
has a value oflocked
:{ "description": "Environment locked", "lowerEnv": { "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "state": "locked" }, "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "result": "locked", "upperEnv": { "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "state": "locked" } }
Step 3: Check that a promotion is not already running
-
Check the promotion status to confirm that a promotion is not already running. This is indicated in the response when
status
has a value ofREADY
:{ "status": "READY", "message": "Environment ready for promotion", "blockingError": false, "globalLock": "LOCKED", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:12:32Z" }
Step 4: Run a dry-run promotion
To run a dry-run promotion, follow the steps in Step 5: Run the promotion; however, in
step 5.1, set the dryRun
flag to true
:
--data-raw '{
"dryRun": true
}'
If there are any scripts awaiting promotion, ensure that they do not emit any personally identifiable information (PII) of your end users into Identity Cloud logs. ForgeRock recommends that you establish a review and testing process for all scripts to prevent PII leaking out of your Identity Cloud tenant environments. |
Step 5: Run the promotion
-
To run a promotion, use the
/environment/promotion/promote
endpoint:curl \ --request POST 'https://<tenant-env-upper-fqdn>/environment/promotion/promote' \(1) --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Authorization: Bearer <access-token>' \(2) --data-raw '{ "dryRun": false (3) }'
1 Replace <tenant-env-upper-fqdn>
with the FQDN of the upper environment.2 Replace <access-token>
with an access token for the upper environment (refer to Get an access token).3 The dryRun
flag is set tofalse
in the request body.{ "result": "Promotion process initiated successfully" }
-
Check the promotion status to confirm that the promotion is in progress. This is indicated in the response when
status
has a value ofRUNNING
:{ "status": "RUNNING", "message": "Prepare config", "blockingError": false, "globalLock": "LOCKED", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:14:13Z" }
-
Check the promotion status as many times as you need until the promotion is complete.
-
If the promotion is still running, the response
status
has a value ofRUNNING
:{ "status": "RUNNING", "message": "Promote configuration", "blockingError": false, "globalLock": "LOCKED", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:15:51Z" }
-
If the promotion failed but is recoverable, the response
status
has a value ofERROR
, and the responseblockingError
has a value offalse
.-
In the example below, the promotion failed an integrity check for missing ESVs.
{ "status": "ERROR", "message": "Missing ESVs", "blockingError": false, "missingESVs": [ "email.from" ], "globalLock": "LOCKED", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:19:31Z" }
To resolve this:
-
Add the missing ESV into the upper environment.
-
Start the promotion steps again.
-
In the example below, the promotion failed an integrity check for encrypted secrets.
{ "status": "ERROR", "message": "Found encrypted values in the AM/IDM configuration", "blockingError": false, "globalLock": "LOCKED", "encryptedSecrets": [ "* am/services/realm/root-alpha/persistentcookiedecisionnode/1.0/organizationconfig/default/dd35c42f-177e-4633-9107-373214858fa7.json:10" ], "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:19:31Z" }
To resolve this:
-
If the encrypted secret is in your configuration by accident:
-
Create an ESV secret containing the encrypted secret in each of the development, staging, and production environments.
-
Update your configuration to reference the new ESV secret.
-
Start the promotion steps again.
-
If the encrypted secret is in your configuration deliberately, you can bypass this check:
-
Follow the steps in Step 5: Run the promotion; however, in step 5.1, set the
ignoreEncryptedSecrets
flag totrue
:--data-raw '{ "dryRun": false, "ignoreEncryptedSecrets": true }'
-
-
-
-
If the promotion failed and is not recoverable, the response
status
has a value ofERROR
, and the responseblockingError
has a value oftrue
:{ "status": "ERROR", "message": "Failed to promote config", "blockingError": true, "globalLock": "LOCKED", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:19:31Z" }
If you run the promotion again after a blocking error, the following response displays:
{ "code": 409, "message": "Environment is blocked from a previous failed promotion" }
To resolve this, submit a ForgeRock Support ticket. See Resolve environment errors that are preventing promotions.
-
If Identity Cloud services are restarting, the response
status
has a value ofRUNNING
, and the responsemessage
has a value ofWaiting for workloads to restart
:{ "status": "RUNNING", "message": "Waiting for workloads to restart", "blockingError": false, "globalLock": "LOCKED", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:32:06Z" }
This part of the promotion can take several minutes. It does not apply to dry-run promotions, where Identity Cloud services do not need to be restarted.
-
If the promotion is complete, the response
status
has a value ofREADY
, and the responsemessage
has a value ofPromotion completed
:{ "status": "READY", "message": "Promotion completed", "blockingError": false, "globalLock": "LOCKED", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "timeStamp": "2022-04-19T17:40:29Z" }
If no changes have been promoted, the
message
has a value ofPromotion completed (no change)
.
-
Step 6: View the promotion report
-
To view a report for the most recent promotion, use the
/environment/promotion/report
endpoint.curl \ --request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/report' \(1) --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Authorization: Bearer <access-token>' \(2)
1 Replace <tenant-env-upper-fqdn>
with the FQDN of the upper environment.2 Replace <access-token>
with an access token for the upper environment (refer to Get an access token).{ "createdDate": "2022-04-19T17:32:05Z", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "report": { "IDMConfig": [ { "configChange": { "added": [ "Forgotten Username" ] }, "configItem": "Email > Templates", "fileDestinationPattern": "idm/conf/emailTemplate-*.json", "fileName": "displayName", "type": "single" } ] }, "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c", "reportName": "Report_2022-04-19T17-32+00Z_dryrun=false_8acd3a87-2272-450f-a3b3-1eb222108740" }
In the example above, the promotion report shows that email template configuration was promoted.
-
To view a report from before the most recent promotion, see View previous promotion reports.
Step 7: Unlock the environments
-
To unlock the environments, use the
/environment/promotion/lock
endpoint:curl \ --request DELETE 'https://<tenant-env-upper-fqdn>/environment/promotion/lock/<promotion-id>' \(1) (2) --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Authorization: Bearer <access-token>'(3)
1 Replace <tenant-env-upper-fqdn>
with the FQDN of the upper environment.2 Replace <promotion-id>
with thepromotionId
created when you initially locked the environments.3 Replace <access-token>
with an access token for the upper environment (refer to Get an access token).{ "description": "Environment unlock in progress", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "result": "unlocking" }
-
Check the lock state as many times as you need until both environments are unlocked. This is indicated in the response when
result
has a value ofunlocked
:{ "description": "Environment locked", "lowerEnv": { "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "state": "locked" }, "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "result": "locked", "upperEnv": { "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "state": "locked" } }
View previous promotion reports
-
To view a list of previous promotion reports, use the
/environment/promotion/reports
endpoint:curl \ --request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/reports' \(1) --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Authorization: Bearer <access-token>'(2)
1 Replace <tenant-env-upper-fqdn>
with the FQDN of the upper environment.2 Replace <access-token>
with an access token for the upper environment (refer to Get an access token).[ { "createdDate": "2022-04-19T12:00:29Z", "dryRun": true, "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "reportId": "57aabe7d-4e8c-4fbb-8a13-2fc7d1cb4d52" }, { "createdDate": "2022-04-19T17:32:05Z", "dryRun": false, "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c" }, { "createdDate": "2022-04-19T13:56:10Z", "dryRun": true, "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "reportId": "df893dee-e952-489c-b94d-8c9ebf36e9a5" } ]
-
To view individual reports, use the
/environment/promotion/report
endpoint and supply areportId
from the response in the previous step:curl \ --request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/report/<report-id>' \(1) (2) --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Authorization: Bearer <access-token>'(3)
1 Replace <tenant-env-upper-fqdn>
with the FQDN of the upper environment.2 Replace <report-id>
with areportId
.3 Replace <access-token>
with an access token for the upper environment (refer to Get an access token).{ "createdDate": "2022-04-19T17:32:05Z", "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740", "report": { "IDMConfig": [ { "configChange": { "added": [ "Forgotten Username" ] }, "configItem": "Email > Templates", "fileDestinationPattern": "idm/conf/emailTemplate-*.json", "fileName": "displayName", "type": "single" } ] }, "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c", "reportName": "Report_2022-04-19T17-32+00Z_dryrun=false_8acd3a87-2272-450f-a3b3-1eb222108740" }
Revert a promotion
To revert a promotion, submit a support ticket:
-
Open an Identity Cloud: Config request with ForgeRock Support.
-
On the Identity Cloud: Config Request page, 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?
Select Restore from backup
-
In the Restore from backup section, provide values for the following fields:
Field Value What is the environment name?
Select the option that corresponds with the upper environment from the promotion you need to revert:
-
Dev
-
UAT[1]
-
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.
-
-
Click Submit.
Resolve environment errors that are preventing promotions
To resolve environment errors that are preventing promotions, submit a support ticket:
-
Open a How-To ticket with ForgeRock Support.
-
On the How Do I...? page, provide values for the following fields:
Field Value Product
Select the following from the lists:
-
ForgeRock Identity Cloud
-
Tenant Settings
-
Self-Service Promotion
What are you trying to achieve?
Enter
Resolve environment errors preventing self-service promotions
.Please provide a short description
Enter
An error has occurred during a self-service promotion to the development/staging/production environment
.Enter the error code and message (API users only).
-
-
Click Submit.