Asset Promotion Best Practices
Asset promotion works best when the source and target environments are kept in sync over time, not just during a single export and import. The following practices help you avoid most import conflicts before they happen and make the remaining ones easier to resolve.
If you are new to asset promotion, start with Asset Promotion via Import and Export and the workflow described in Promote Assets.
Promote in one direction only
Pick a source environment and a target environment and keep the direction fixed:
-
Author and edit assets in the source environment.
-
Treat the target environment as read-only for promoted content.
If the same assets are edited in both environments, import matching cannot tell which version is the correct one. Every promotion then produces unnecessary conflicts that need to be resolved manually.
Follow a staged promotion path
Promote assets along your environment chain (DEV → TEST → PROD) and validate them at each stage before they reach production. This minimizes the risk of promoting broken or untested assets into production environments.
Synchronize the environments for the first time
Once the source and target environments are in sync, every subsequent promotion is straightforward: each import maps source asset IDs to their target counterparts, so matching assets line up automatically the next time. The initial synchronization takes the most effort, but it is a one-time task.
This applies especially if the two environments were built independently and contain similar business content with different internal IDs, for example, rules that are almost the same in both environments. Differing IDs are particularly common for child assets, such as the individual components of a rule. To reconcile the environments:
-
Clean up the target environment by discarding outstanding drafts and resolving existing system validation errors.
The cleaner the target environment, the fewer ambiguities the import needs to deal with.
-
Run the first import and work through every reported violation.
Each violation you resolve either creates a persistent ID mapping that is reused by all future imports or fixes the data in one of the environments. For details, see Resolve Import Conflicts.
-
After the reconciliation, make changes only in the source environment.
From then on, assets are matched by ID, and newly created assets share IDs across both environments.
Remove references to attributes missing in the target
Standard catalog items are not promoted: the target environment is expected to have its own catalog items, populated from its own data sources. This means the attribute structure of a catalog item can differ between the two environments.
If an attribute is missing in the target environment and the corresponding attribute in the source environment references a term or a data quality (DQ) rule, remove that reference in the source environment before promoting. Otherwise, the import cannot resolve the reference and reports a violation.
Promote small, focused exports
Export only the assets you need. A focused promotion, for example, one monitoring project at a time, is faster, easier to review, and produces fewer conflicts than promoting everything at once.
Smaller archives also simplify conflict resolution and make the Import Report easier to review.
Keep at most one unpublished import per monitoring project
While an import is in the Review needed state, its drafts hold unpublished changes on top of the published data in the target environment. Keeping multiple unpublished imports on the same monitoring project makes publishing unpredictable: drafts can interact in unexpected ways, and the Import Report becomes harder to interpret.
As a general guideline:
-
For each monitoring project, keep at most one import in the Review needed state at a time.
-
Pending imports for different monitoring projects can wait for review in parallel.
Review finished imports without delay
As the target environment keeps changing, the Import Report of an unpublished import becomes less reliable over time.
When an import finishes:
-
If the Import Report contains no errors, publish the import.
-
If the Import Report contains errors, investigate them as soon as possible. Fix the underlying data in the source or target environment (for example, profile a missing catalog item), or add an import mapping that resolves the mismatch. Then discard the pending import and run the promotion again.
For details about specific errors, see Resolve Import Conflicts.
Was this page useful?