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

String

Optional

Immutable

A JSON object containing the ID of the source environment. If not specified, the current source environment for the actor is used.

sourceSnapshotId

String

Optional

Mutable

The identifier of the snapshot to use 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, READY, IN_PROGRESS, COMPLETED, VALIDATION_FAILED, or ERROR.

targetEnvironment

Object

Required

Immutable

A JSON object containing the identifier of the target environment.

targetSnapshotId

String

Optional

Mutable

The identifier of the snapshot to use as the promotion target.