---
name: import-solution
description: Safe solution import with overwrite awareness. Reads solution contents before importing, flags high-risk component overwrites (sitemaps, security roles, forms), and verifies post-import state. Use when importing any solution into a Dataverse environment.
argument-hint: "[environment-name] [solution-file-or-name]"
---

# Import Solution Safely

Import Dataverse solutions with overwrite awareness. Read before importing, warn about risks, verify after importing.

## Arguments

- `$ARGUMENTS[0]` — Target Dataverse environment name
- `$ARGUMENTS[1]` — Solution file path or solution unique name (for cross-environment transfer)

## When to Use

- Importing a solution file (.zip) into any environment
- Transferring a solution from dev to test/production
- Any time `dataverse_import_solution` would be called

## Pre-Flight

1. Confirm the target environment with the user
2. Determine the solution source:
   - If importing from a file: verify the file exists and read its metadata
   - If exporting from another environment first: identify the source environment and solution name
3. Authenticate to the target environment if not already authenticated

## Phase 1: Understand What's Being Imported

If importing from another environment, export first:
```
dataverse_export_solution(solution_name, managed: true/false)
```

Examine the solution's components. If the solution is already exported, check:
```
dataverse_get_solution(solution_name) — in the SOURCE environment
```

Identify the component types in the solution:
- Tables and their customizations (forms, views, columns)
- Sitemap
- Security roles
- Web resources
- Plugins
- Flows
- Connection references

## Phase 2: Risk Assessment

Check the TARGET environment for existing versions of high-risk components:

### Sitemaps (HIGHEST RISK)
If the solution contains a sitemap, check if one already exists in the target:
```
dataverse_get_sitemap(app_id) — in the TARGET environment
```
**Warning:** Importing a solution with a sitemap will COMPLETELY REPLACE the existing sitemap. This is the most common source of "everything disappeared from the app navigation" incidents.

### Security Roles
If the solution contains security roles, check existing roles in the target:
```
dataverse_list_security_roles — in the TARGET environment
```
**Warning:** Importing will overwrite role privilege definitions for roles with matching names.

### Forms
If the solution contains form customizations, check existing forms:
```
dataverse_list_forms(table_name) — in the TARGET environment
```
**Warning:** Form customizations in the imported solution will replace existing form XML for matching forms.

## Phase 3: Present Risk Summary

Before importing, present a clear summary to the user:

```
**Solution Import Summary**

Source: [solution name, version, managed/unmanaged]
Target: [environment name]

**Components:**
- Tables: X
- Forms: X
- Views: X
- Flows: X
- Web Resources: X
- Security Roles: X
- Sitemap: [yes/no]

**High-Risk Overwrites:**
- [list any sitemaps, security roles, or forms that exist in target and will be overwritten]

**Recommendation:** [proceed / backup specific components first / review with user]

**Proceed with import?**
```

Wait for explicit user confirmation.

## Phase 4: Import

If high-risk overwrites were identified and the user wants safety:
- For sitemaps: save the current sitemap XML before importing (copy from `dataverse_get_sitemap` output)
- For security roles: note current privilege configuration

Then import:
```
dataverse_import_solution(solution_file, overwrite_customizations: true/false)
```

- `overwrite_customizations: true` — replaces all customizations in target with solution versions
- `overwrite_customizations: false` — preserves target customizations where they differ (may cause conflicts)

## Phase 5: Post-Import Verification

After import completes:

1. **Check import status** — verify the import succeeded without errors
2. **Spot-check key components:**
   - If sitemap was included: open the app and verify navigation is intact
   - If security roles were included: verify role assignments are still correct
   - If forms were included: open a form and verify it renders correctly
   - If flows were included: check flow states (active/draft)
3. **Publish all** — after import, run `dataverse_publish_all` to ensure all changes are visible

## Guardrails

- **NEVER import without reading the solution contents first.** Phase 1 and Phase 2 are mandatory.
- **NEVER delete existing components to resolve an import error.** Use `/troubleshoot` to diagnose import failures.
- **Managed solutions cannot be edited in the target.** If the solution is managed, users won't be able to customize imported components in the target environment. Confirm this is intended.
- **For production environments:** Always recommend exporting the current solution version as a backup before importing.
- **Connection references in the solution** may need to be wired to connections in the target environment after import. Check with `dataverse_list_connection_references`.

## Validation

After completing the import:
- Verify the solution appears in the target: `dataverse_list_solutions`
- Check solution version matches expected version
- Verify 2-3 key components exist and are functional
- If any high-risk components were flagged: verify they're intact
- Report: solution name, version, import status, component count, any warnings, post-import verification results