Import a Solution into an Environment

Goal

Import a solution package into a target environment so the entities, forms, views, and rules built elsewhere are re-created in that environment.

Prerequisites

• You are signed in to the Admin Control Center as a platform administrator.
• You have a solution package file exported from another environment (see Export a solution).
• The target environment exists and is Active (see Create an environment).

Steps

1. Select the target environment at the top of the Admin Control Center — a solution is imported into an environment, so the import applies to whichever environment is currently selected.
2. Open the Solutions page from the top navigation.
3. Select Import.
4. Supply the solution package you exported.
5. If the package carries demonstration data, you are asked about it before anything is imported: tick Include demonstration data to bring those rows, then select Import. The box is unticked unless you tick it, and disabled for a Production environment. The package's configuration rows always come, and a package without demonstration rows skips the question.
6. The solution deploys immediately — just as in Power Apps, an import applies straight into the selected environment. The imported (managed) solution then appears in the Solutions list, and makers can use its components.

What happens behind the scenes

Before anything is applied, the package is validated and its dependencies are checked — every form, view, and rule must refer to an entity that is either in the same package or already present in the target environment. The entities and their tables are then created inside the target environment's own isolated data area, and the forms, views, and rules are registered there. Each environment keeps its own separate data, so the imported solution starts empty in the target environment.

Importing is repeatable: if a component already exists in the target — because it is a standard table's built-in form or view, or because you are importing the same solution again — it is updated in place rather than causing an error, so a solution that adds a field to a standard table imports cleanly even though that table (and its default forms and views) is already present.

That includes option sets. An option set already in the target is brought up to date with the imported one: labels and ordering are refreshed, new options are added, and options the imported set no longer has are removed. Options are matched by the value the platform assigned them, so a renamed option is updated rather than added twice, and no record ever has the meaning of its stored value changed underneath it. Two situations stop the import instead, because neither can be resolved without losing data: an option set that shares a name with one already there but belongs to a different publisher, and the removal of an option that records still hold.

Imports apply immediately. A per-environment approval gate for higher-tier environments (Test, Production) is planned as part of the future Flow-based deployment pipeline — it is not part of the direct import today.

A solution can say what it is built on. If its package names solutions it needs, the import checks the environment first, and refuses with "Import … first" — before anything is written — when one is missing or too old.

If an import fails part way, nothing is kept. When it is the first time this solution version is imported here, everything it had already created — tables, forms, roles, apps — is removed again, and the import is marked Failed with the reason. Fix the cause and import again. (A re-import of a version that is already installed is not undone, because that would remove the working copy too.)

Importing a newer version: an upgrade

When the environment already has an earlier version of the solution, importing a newer one replaces it. The earlier version leaves the Solutions list, and the environment ends up the way a fresh install of the new version would leave it:

• Everything the new version still carries stays, records included, and now belongs to the new version.
• What the new version no longer carries is removed, as an uninstall would remove it. A role it dropped is taken from the people who held it.

If the earlier version cannot be retired, the import still succeeds, the earlier version stays in the list, and the message after the import says so. Import the new version again to retry. Do not uninstall the earlier version: it still owns parts of the new one.

When a solution adds to a table you already have

Some solutions add fields to a table the environment was created with, such as a code and a status on Units. The import adds those fields and leaves everything else on the table as it was, so the table keeps its existing fields, records and org chart. The table still belongs to the environment, not to the solution.

Uninstalling that solution takes away only what it added. The table stays, with its own fields and records.

A solution may point an existing lookup at a different table. For example, a unit's Manager could point at a position instead of a person. Values that pointed at the old table are cleared, because they mean nothing to the new one. Uninstalling points the lookup back and clears the values it held.

A solution cannot change a field's data type, such as turning a text field into a lookup. The import stops with a message naming the field, and nothing is changed. The solution's author has to add a new field instead.

When a solution needs another one

A solution can be built on another publisher's solution: a Badge table, say, whose Visitor column looks up the table the Visitors solution brings. Both can be installed side by side in one environment, each under its own publisher, but the one the other builds on has to be there first.

So the import checks every lookup. A column that looks up a table the package doesn't carry and the environment doesn't have stops the import before anything is written, and the message names the column and the table. Import the solution that brings the table, then import this one again.

Exports don't yet record which solutions a package is built on, so this check, table by table, is what catches an import made in the wrong order.

Seed data: configuration always, demonstration only when asked

Seed data is records a package brings with it, and each table's rows are one of two kinds:

• Configuration, rows the solution needs to work, such as approval thresholds. They always come, Production included.
• Demonstration, rows that show the solution off, such as invented customers. They come only when you tick Include demonstration data, and never into a Production environment, where they would sit among your own records with nothing to tell them apart and would stay if the solution were uninstalled.

The message after the import says what landed, and how many demonstration rows were left out. See Ship Seed Data with a Solution.

Troubleshooting

• "The solution package is invalid." — the package does not match the expected format. Re-export it from the source environment.
• "field '…' references '…', which is neither in the package nor in this environment." — a column in the package looks up a table, or takes its values from an option set, that the package doesn't carry and this environment doesn't have. Nothing was imported. If another solution brings it, import that solution first. If it belongs to this solution, add it in the environment you exported from and export again.
• "Demonstration data cannot be imported into …, which is a Production environment." Import the solution without it. Its configuration rows still come.
• The solution arrived but its sample records are missing. It was imported without its demonstration data. Import it again, into an environment that is not Production, with Include demonstration data ticked.
• "Target environment … was not found" / "is not active." — select an existing, Active environment; wait for a newly-created environment to finish provisioning.

Related scenarios

• Export a solution.
• Create an environment.