Manage dependencies between configurations

Published Mar 14, 2025

Sometimes configurations reference each other, which affects their deployment order and requirements. Using edit mode, you can change references between configurations.

To fully understand what this means, let's take a closer look at how dependencies work.

Dependency and referencing

If Config A contains a reference property mentioning Config B, then Config A depends on Config B, and Config B is a dependency for Config A.

If you want to deploy Config A, then Config B will be automatically included. You can't deploy Config A without Config B.

If we look at the same situation from Config B's perspective, Config A is a referencing configuration of Config B. Config B can be deployed without Config A, as it doesn't depend on it.

If you include both Config A and Config B in the deployment, Config B will be deployed first, and it must be successfully placed in the target environment for Config A to be deployed. In other words, if Config B fails, deployment of Config A will be skipped completely.

Direct and indirect

Let's have a look at a more complicated example.

This time, Config B additionally contains two reference properties mentioning Configs C and D. From Config A's perspective, its dependency on Config B is a direct dependency. Since Config B now further depends on Configs C and D, then Configs C and D become Config A's indirect dependencies.

If you want to deploy Config A now, Configs B, C, and D will all be automatically included. If any of those fail to deploy, Config A will be skipped.

Similar logic can be applied to the referencing configurations. If we look at this situation from Config B's perspective, Config A is Config B's direct referencing configuration, and some Config Z that depends on Config A will be Config B's indirect referencing configuration.

Just as before, referencing configurations don't affect the deployment of Config B. When deploying Config B, only Configs C and D will be automatically included. However, if Config B fails to deploy, both Config A and Z will be skipped.

If we expand this example further and add dependencies to Config C or D, they will also become Config A's indirect dependencies and will have to be deployed together with it.

Breaking a dependency

Following the previous example, what if we want to deploy only Config A to the target environment? In the current situation, selecting Config A for deployment will automatically add many other configurations. However, in reality, Config A only has one direct dependency. Perhaps this dependency is unnecessary for the configuration to function correctly in the new environment. In that case, you can break the dependency between Config A and Config B.

Breaking a dependency can be done simply by removing a corresponding reference property from Config A using edit mode. Config B and its dependencies, like Config C and D, are no longer the dependencies of Config A. Config A can now be deployed alone.

Breaking cyclic dependencies

Cyclic dependencies can occur when configurations are mutually dependent, becoming both a dependency and a referencing configuration from each other's perspective.

Cyclic dependency can be a simple situation with two configurations that are directly dependent on each other, or it can be more complicated, with a cycle spanning multiple different configurations.

Diagram note: Referencing labels were removed for clarity.

We can see that Config A has become its own dependency. However, all dependencies must be deployed before Config A can be deployed. This creates an impossible situation where Config A needs to be deployed before Config A.

When a dependency cycle is present, the order of deploying configurations can't be established. This means configurations taking part in the dependency cycle can't be deployed to the target environment.

How SaaS Upgrade Assistant helps with breaking cycles

Environments with cyclic dependencies are marked with a warning icon.

In the Select deployment type step, the option to deploy all configurations is blocked, as the existence of cyclic dependencies guarantees that the full deployment will fail. Selective deployment is the only option in that case.

The next step, Choose configurations to include in the deployment, contains guidance on how to deal with cyclic dependencies. If you want to deploy as many configurations as possible, there are two options:

Exclude the cycles.

In the Upgrade details: configuration tab, select Include all, then go back and select the Force exclude included cyclic configurations. This option will exclude all problematic configurations (and their referencing configurations).

This option is not ideal if you want to deploy affected configurations to the target environment, or if the problematic configurations are often referenced.
Break the dependencies manually.

Select Show dependency cycles to see all detected cycles. You can select Learn more to see the in-app guide. To start breaking the cycles, hover over a desired table row and select Jump to marked config.

An alternative way to search for configurations with cyclic dependencies is to select the Show only configurations with cyclic dependencies on the landing page of the Upgrade details: configuration tab. This button sets the Other problems filter to Has cyclic dependencies, which allows you to browse the problematic configurations.

Break the cycle

After drilling down to a configuration included in the dependency cycle, you'll again see the Show dependency cycles. This time, selecting this will automatically complete the Filter field, allowing you to see only the cycles related to this particular configuration. You can use this information to decide which reference properties need to be removed or changed.

After deciding on the reference property, you can enter edit mode and make the desired modifications.

To perform the full deployment, repeat this for all detected cycles.