PingOne Platform APIs - Early Access

Promotions

A promotion includes, at a minimum, source and target environment references, automatically generated source and target snapshots, the resource or resources to promote to the target environment, and a promotion plan for the promotion operation. You need to have the Environment Admin role for both the source and target environments. You can optionally include a specific source environment snapshot to use, as well as a mapping of the source environment configuration resource or resources to the target environment configuration resource or resources.

Currently, you can promote configurations only to environments within the same PingOne tenant.

A PingOne admin having Environment Admin permissions can review the promotion plan, and update the promotion mapping and variable definitions or declarations as needed. The promotion plan is then regenerated based on the updates. Use the Read One Promotion or Read All Promotions to view the promotion plan.

If you do not set any promotion variables, the configuration resource or resources that you specify for the source or target environment will be used as is, and cannot be changed during the promotion operation. Refer to Promotion Variables for more information.

When you choose to start the promotion operation, the promotion plan supplies the promotion operation instructions to the Promotions service. The Promotions service then:

  • Filters out any configuration resources that haven’t changed, and calls the required target environment API using the new or altered resources.

  • Sets the promotion’s started_at and status values.

  • Collects any errors into a JSON array, and returns the errors.

  • Updates the promotion’s completedAt and status values when the promotion operation is complete.

Promotions data model

Property Type Required Mutable Description

createdAt

Date

N/A

Read-only

The date and time the promotion was created.

completedAt

Date

N/A

Read-only

The date and time the promotion operation completed.

description

String

Optional

Mutable

A description of the promotion to be performed.

errors

Object[]

N/A

Read-only

An array of JSON objects correlating the configuration resource identifier in the source environment to the error messages from the target environment.

excludedResources

Object[]*

Optional

Mutable

An array of JSON objects. *Optionally, this can be an array of strings. Contains the resource identifiers, and resource URLs for the configuration resources to be excluded from promotion.

resourceMapping

Map

Optional

Mutable

A mapping of the configuration resource identifiers in the source environment to the configuration resource identifiers in the target environment.

promotionPlan

Object[]

N/A

Read-only

An array of JSON objects containing the promotion plan generated. The promotion plan is generated by the POST operation, but is returned only by either of the Read Promotion operations. For a DELETE operation, the payload property in the response will be empty.

promotionPlan.steps

Object[]

N/A

Read-only

An array of JSON objects identifying the resource or resources, the configuration of the resource or resources, and the target environment or environments.

promotionPlan.totalDistance

Integer

N/A

Read-only

(Internal use only.) A comparison metric the Configuration Management service uses to determine whether there is a comparable resource in the target environment to replace.

selectedResources

Object[]*

Optional

Mutable

An array of JSON objects. *Optionally, this can be an array of strings. Contains the resource identifiers, and resource URLs for the configuration resources selected for promotion. If this is omitted, the entire current environment is used (the environment ID is injected.)

sourceEnvironment

Object

Optional

Mutable

Contains the identifier of the source environment.

sourceEnvironment.id

String

Required/Optional

Mutable

The identifier of the source environment.

sourceSnapshot

Object

Optional

Mutable

Contains the identifier of the snapshot to use as the promotion source.

sourceSnapshot.id

String

Required/Optional

Mutable

The identifier of the snapshot to use as the promotion source. If not specified, the Configuration Management service automatically generates a snapshot of the source environment at the time of the POST request, and uses that snapshot as the promotion source.

startedAt

Date

N/A

Read-only

The date and time the promotion operation started.

status

String

N/A

Read-only

An enumeration indicating the status of the promotion. This can be: NEW, PREPARING, ADDITIONAL_SNAPSHOTS_REQUESTED, READY, IN_PROGRESS, VALIDATION_FAILED, COMPLETED, ERROR, ROLLED_BACK, ROLLBACK_NEW, ROLLBACK_PREPARING.

targetEnvironment

Object

Required

Immutable

A JSON object containing the identifier of the target environment.

targetEnvironment.id

String

Required

Immutable

The identifier of the target environment.

targetSnapshot

Object

Required

Immutable

A JSON object containing the identifier of the target snapshot.

targetSnapshot.id

String

Required

Immutable

The identifier of the target snapshot.

Rolling back a promotion

You can roll back promotions as needed (whether they failed or were successful), restoring the environment to its prior state.

A rollback cannot be undone, so be sure to review the limitations and considerations before you use it.

Limitations and considerations

  • You can roll back only the most recent promotion to the target environment. You can’t select a subset of resources to roll back, nor can you roll back a completed rollback.

  • A promotion can sometimes affect resources that weren’t part of the promotion plan. For example, if you promote the deletion of a policy that was assigned to an application, the promotion also deletes the association between the application and the policy in the target environment. To restore the target environment to its previous state, a rollback must not only restore the deleted policy, but also restore the association between the policy and the application. In this case, the application is considered an indirectly affected resource, and is included in the rollback.

  • If you update promoted resources in the target environment after the initial promotion and before the rollback, those changes can be overwritten by the rollback.