--- title: Key concepts (early access) description: Understand the key concepts of native configuration promotion in PingOne. component: pingone page_id: pingone:early-access-features:ea-p1_promotion_key_concepts canonical_url: https://docs.pingidentity.com/pingone/early-access-features/ea-p1_promotion_key_concepts.html revdate: April 16, 2026 section_ids: source-and-target-environments: Source and target environments snapshots: Snapshots promotion-variables: Promotion variables p1-promote-sensitive-variables: Sensitive attributes and variables promotions-and-promotion-plans: Promotions and promotion plans rollback: Rollback mapping: Mapping dependencies: Dependencies missing-or-broken-references: Missing or broken references --- # Key concepts (early access) Familiarize yourself with the following key concepts to understand how configuration promotion works in PingOne and to ensure that you can use it effectively. ## Source and target environments In PingOne configuration promotion, the *source* environment is the environment that contains the configuration resources you want to promote. The *target* environment is the environment to which you want to promote those configuration resources. In a typical development workflow, you might promote configuration resources from a development environment (the source) to a test environment (the target), and then later promote those same resources from the test environment (the source) to a production environment (the target). Learn more in [Typical configuration management workflow (early access)](ea-p1_promote_typical_workflow.html). ## Snapshots A snapshot is a point-in-time representation of the configuration resources in a PingOne environment. When you create a promotion, PingOne automatically generates snapshots of both the source and target environments. These snapshots capture the current state of all configuration resources in each environment, allowing the promotion service to compare them and identify differences. ## Promotion variables Promotion variables are placeholders that you can define and use within configuration resources to represent values that might differ between environments. By using promotion variables, you can create a single configuration resource that can be adapted to different environments without needing to create separate versions of the resource for each environment. For example, you might have sign-on URLs that differ between your development, test, and production environments. Instead of hardcoding these URLs into your application configuration, you can define a promotion variable and use that variable in the application configuration. When you promote the application to a different environment, you can specify the appropriate value for the sign-on URL in that environment. Warnings display if the use of variables is recommended for a resource. For example, if you have an application with a sign-on URL that differs between environments, the promotion service might recommend that you use a promotion variable that URL attribute. You can run the promotion without variables, unless the variable is required. However, using promotion variables can help make your promotions more flexible and adaptable to different environments. ## Sensitive attributes and variables Some attributes in PingOne are marked as sensitive, such as passwords or client secrets. These attributes require the use of sensitive variables for promotion. Sensitive variables are promotion variables that are encrypted. After they're created, their values are hidden and can't be viewed or copied from the PingOne admin console or in API operations. If you try to promote a resource that contains sensitive attributes without creating variables for them, you'll be prompted to create the variables before continuing. Learn more in [Promotion variables (early access)](ea-p1_promotion_variables.html). ## Promotions and promotion plans A promotion is the process of moving configuration resources from a source environment to a target environment in PingOne. A promotion is done in two phases: * Phase 1 - Planning the promotion: Consider the configuration resources you want to promote. Create any promotion variables for these resources, then initiate a promotion. Select the resources you want to promote and map the resources and their dependencies as applicable to resources in the target environment. * Phase 2 - Running the promotion: When you run the promotion, configuration resources are created or updated in the target environment based on the selections you made during the planning phase. Learn more in [Configuring and running a promotion (early access)](ea-p1_configure_promotion.html). ## Rollback Rollback is the process of undoing a promotion or setting the target environment back to the state it was in immediately prior to the promotion. You should always use the rollback mechanism if you have an issue with a promotion and need to start over. In PingOne, you can roll back only the most recent promotion, and the promotion can be rolled back whether it failed or succeeded. When you roll back a promotion, everything that was promoted is rolled back. You can't roll back a subset of the resources that were promoted. Learn more in [Rolling back a promotion (early access)](ea-p1_promotion_rolling_back.html). ## Mapping Mapping is the critical process of linking a specific resource in a source environment to its corresponding resource in a target environment. This process ensures that the system knows whether to create a brand new resource in the target environment or update an existing resource when you run the promotion. The first time you promote a resource, the promotion service compares the source and target environments and attempts to identify matching resources based on attributes such as resource name or other comparison markers. Based on the comparison, the service makes suggestions as follows: * No match found: If the service doesn't find a match for the resource in the target environment, it defaults to **Promote as New Resource**. When you run the promotion, the configuration resource or dependent resource is created in the target environment. That new resource is automatically mapped to the resource in the source environment. * Potential match found: If the service finds a reasonable match for the resource in the target environment, it selects the match by default for mapping purposes. In either instance, the final decision is left to the administrator running the promotion. Mapping occurs only the first time you promote a resource to a specific target environment. For example, you know that different naming conventions are used in your source and target environments. You understand that the **Customer App** application in the target environment corresponds to the **My First App** application in the source environment. However, when you initiate the promotion of **My First App**, the promotion service doesn't recognize **Customer App** as a match and recommends creating **My First App** as new in the target environment. You can override that recommendation and instead map **My First App** to **Customer App** before you run the promotion. Similarly, you can reject a match recommended by the promotion service. For example, if the service recommends mapping **My First App** to **Test App** in the target environment, but you know that **Test App** is unrelated to **My First App**, you can change the mapping to **Promote as New Resource** or map it to a different resource before you run the promotion. In future promotions of the resource to the same target environment, the system remembers the mapping you selected. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In some cases, you might not be prompted to map a selected resource. For example, if there's never more than a single instance of a resource in an environment, you aren't prompted to map that resource during promotion because there's no possibility of confusion. Similarly, if the promotion service doesn't find any reasonable matches for a resource in the target environment, you aren't prompted to map it because the only option is to promote it as new. | ## Dependencies Many resources in an environment include dependencies as part of their configuration, and those dependencies can in turn have their own dependencies. If you tried to promote resources without including their dependencies, they wouldn't function as intended in the target environment. For example, a DaVinci flow might be configured to include a multi-factor authentication (MFA) connector. The MFA connector might be configured to use an MFA policy. The MFA connector is a direct dependency of the flow, while the MFA policy is an indirect dependency of the flow. These relationships are illustrated in the following diagram: ![A diagram showing the MFA Device Authentication Flow with a direct dependency on the MFA Connector, which has a direct dependency on the MFA Policy. The flow also has an indirect dependency on the MFA Policy through the MFA Connector.](_images/p1-promote-dependencies-diagram2.png) If the MFA policy isn't promoted to the target environment with the flow, the connector won't work properly, and the flow could fail. The PingOne promotion service automatically tracks these direct and indirect dependencies for you. When you select a resource for promotion, the service identifies all of its dependencies and includes them in the promotion plan, ensuring that you promote a complete and functional configuration. When you promote the flow, you're given the option to map these dependencies to corresponding resources in the target environment, or to create them as new, in the same manner as the main resource you're promoting. If the configuration service doesn't find a version of the dependency in the target environment, it's considered a required dependency and must be created as new in the target environment. You can't remove required dependencies. For example, a DaVinci flow might reference a subflow. If the subflow doesn't exist in the target environment and isn't brought over as a dependency of the main flow, the main flow itself won't run properly in the target environment. ## Missing or broken references In some cases, a configuration resource might include references to resources that no longer exist in the environment. If you try to promote a resource with missing references, the promotion might fail because the promotion service can't find the referenced resource. For example, you have an application that references an authentication flow that was deleted from the source environment. If you try to promote that application, the promotion service can't find the referenced authentication flow in the source environment snapshot and returns an error. The promotion interface displays warnings when you initiate a promotion that includes missing references. Review the warnings to determine if they apply to what you want to promote. You can still promote a resource that includes warnings for broken references, but the promotion could fail and the resource might not work properly in the target environment if the reference isn't resolved. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Resolve missing references before you promote a resource either by restoring the deleted resource or by removing the reference from the resource you want to promote. |