# Migrate Configuration

Configuration Migration lets authorized administrators copy portal configuration — reports, forms, glossaries, and system data files — from one environment to another. It is the primary tool for promoting content built in a staging or development environment into a production environment without manual re-entry.

## Table of Contents

* [Overview](#overview)
* [Who Can Use This Feature](#who-can-use-this-feature)
* [What Can Be Migrated](#what-can-be-migrated)
* [Migrating Reports](#migrating-reports)
  * [Migrating All Reports](#migrating-all-reports)
  * [Migrating a Specific Report Page or Group](#migrating-a-specific-report-page-or-group)
* [Migrating Forms](#migrating-forms)
  * [Migrating All Forms](#migrating-all-forms)
  * [Migrating a Single Form](#migrating-a-single-form)
* [Migrating Glossaries](#migrating-glossaries)
  * [Migrating All Glossary Terms](#migrating-all-glossary-terms)
  * [Migrating a Single Term or Letter Group](#migrating-a-single-term-or-letter-group)
* [Syncing System Data Files](#syncing-system-data-files)
  * [Available Sync Files](#available-sync-files)
  * [Queuing a Sync Job](#queuing-a-sync-job)
  * [Monitoring a Sync Job](#monitoring-a-sync-job)
* [Understanding Migration Results](#understanding-migration-results)
* [Common Scenarios](#common-scenarios)
* [Troubleshooting](#troubleshooting)

***

## Overview

When you build or modify reports, forms, or glossary terms in one environment (for example, a staging site), those configuration changes live only in that environment's database. Configuration Migration transfers those settings to a second environment by reading the current configuration and writing it to the destination database. The migration runs as a transaction, meaning either all changes succeed or none are applied — there is no partial state left behind.

The feature has two main modes:

* **Content migration** — moves reports, forms, and glossary entries, with the option to migrate everything at once or target a specific item.
* **System sync jobs** — runs predefined data files (widgets, menus, security routes, role policies, reference items, and more) against the destination database as background jobs, with status tracking.

***

## Who Can Use This Feature

Only users who have been granted a specific migration permission can trigger migrations. There are three separate permissions:

* **Reports Migrate** — required to migrate reports, view and queue sync file jobs.
* **Forms Migrate** — required to migrate forms.
* **Glossaries Migrate** — required to migrate glossaries.

If you do not see the migration controls, contact your system administrator to request the appropriate permission.

In addition, the destination environment must have a valid migration connection string configured in the site settings before any migration can run. If that connection string is missing or invalid, the system will display an error immediately when you attempt a migration.

***

## What Can Be Migrated

| Content type      | What is included                                                                                            |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| Reports           | Report definitions, report pages, report groups, report lists, containers, and dashboard cards              |
| Forms             | Form definitions, questions, and answer choices                                                             |
| Glossaries        | Glossary term entries                                                                                       |
| System data files | Widgets, menus, security routes, reference items, organizations, role policies, and other system-level data |

***

## Migrating Reports

Report migration copies the entire reporting configuration — including the pages that organize reports, the groups they belong to, their list membership, and any dashboard containers and cards linked to them.

### Migrating All Reports

To migrate all report configuration at once:

1. Navigate to the Migrate Configuration area.
2. Locate the Reports section.
3. Click **Migrate All Reports**.
4. Wait for the confirmation message. The result shows how many reports, pages, groups, lists, containers, and cards were transferred.

### Migrating a Specific Report Page or Group

If you only need to promote changes to one report page or one report group:

1. Navigate to the Migrate Configuration area.
2. In the Reports section, select **Migrate by Filter**.
3. Choose the target **Report Page** or **Report Group** from the provided selector.
4. Click **Migrate**.
5. Review the result summary to confirm the expected items were transferred.

***

## Migrating Forms

Form migration copies form definitions along with all of their questions and the answer choices attached to each question. The migration respects the order of questions and choices as they exist in the source environment.

### Migrating All Forms

1. Navigate to the Migrate Configuration area.
2. Locate the Forms section.
3. Click **Migrate All Forms**.
4. Review the result, which shows the number of forms, questions, and choices transferred.

### Migrating a Single Form

If you updated only one form and do not want to overwrite other form changes that may exist in the destination:

1. Navigate to the Migrate Configuration area.
2. In the Forms section, select **Migrate by Filter**.
3. Choose the specific **Form** from the selector.
4. Click **Migrate**.
5. Confirm the result.

***

## Migrating Glossaries

Glossary migration copies term entries to the destination environment. You can migrate the full glossary or narrow the scope to a single term or a letter group (for example, all terms beginning with "A").

### Migrating All Glossary Terms

1. Navigate to the Migrate Configuration area.
2. Locate the Glossaries section.
3. Click **Migrate All Glossaries**.
4. Review the total item count in the result.

### Migrating a Single Term or Letter Group

1. Navigate to the Migrate Configuration area.
2. In the Glossaries section, select **Migrate by Filter**.
3. To target a single term, choose it from the **Glossary** selector.
4. To target a letter group, choose the letter (for example, "B", "C", or "#" for symbol-prefixed terms) from the **Group** selector.
5. Click **Migrate**.

***

## Syncing System Data Files

In addition to content migration, the portal includes a set of predefined system data files that synchronize lower-level configuration — menus, widgets, security routes, reference data, and similar items. These jobs run in the background and do not block the browser while they execute.

### Available Sync Files

The following sync files are available:

| File                  | Description                                |
| --------------------- | ------------------------------------------ |
| Widgets               | Portal widget definitions                  |
| Security Routes       | Permission-based navigation security rules |
| Reference Items Reset | Resets reference lookup data               |
| Reference Items       | Reference lookup data                      |
| Updates               | General system updates                     |
| Reports               | Report synchronization data                |
| Report Admin          | Report administration data                 |
| Menus                 | Navigation menu structure                  |
| Organizations         | Organization hierarchy data                |
| Glossaries            | Glossary synchronization data              |
| Role Policies         | Role-to-permission policy assignments      |

### Queuing a Sync Job

Each sync file job runs asynchronously in the background. To queue one or more jobs:

1. Navigate to the Migrate Configuration area.
2. Locate the **Sync Files** section.
3. Select one or more files from the list.
4. Click **Queue Job**.
5. The system confirms that the job has been queued and assigns it a tracking ID.

You can queue multiple files in a single job submission. Each selected file is processed in order within the same job.

### Monitoring a Sync Job

After queuing a job, you can check its progress at any time:

1. Navigate to the **Sync Job History** view in the Migrate Configuration area.
2. Jobs are listed in reverse chronological order, showing who queued each job and when.
3. Each job displays one of four statuses:
   * **Queued** — the job is waiting to start.
   * **In Progress** — the job is currently running.
   * **Completed** — all files finished successfully.
   * **Failed** — one or more files encountered an error.
4. Expand a job to see per-file results, including the time each file took to process.

***

## Understanding Migration Results

After any migration completes, the portal displays a result summary. The summary always includes:

* **Success or failure status** — a clear indication of whether the migration was applied.
* **Item counts** — the number of records transferred for each category (for example, 12 reports, 3 pages, 5 groups).
* **Message** — a plain-language confirmation or, in the case of failure, a description of what went wrong.

If the migration fails, no partial changes are written to the destination. The entire operation is rolled back, leaving the destination database in its prior state. You can safely re-attempt the migration after resolving the underlying issue.

***

## Common Scenarios

**Promoting a new report from staging to production.** Build and test the report in staging, then use Migrate by Filter to migrate only that report's page to production. This avoids inadvertently overwriting other reports that may have been updated directly in production.

**Syncing menus and widgets after a platform update.** After upgrading the portal, run the Widgets and Menus sync file jobs to apply any menu structure or widget definition changes that came with the update.

**Refreshing reference items.** When lookup tables (such as grade levels or subject codes) change, run Reference Items Reset followed by Reference Items to clear and repopulate the reference data in the destination.

**Migrating a full environment clone.** When setting up a new tenant environment from scratch, run all four migration types — Reports, Forms, Glossaries, and all sync files — in sequence to fully populate the new environment.

**Auditing who ran migrations.** Review the Sync Job History to see a timestamped log of each sync job, including the username of the person who queued it.

***

## Troubleshooting

**"No files were provided to sync."** You submitted a sync job without selecting any files. Return to the Sync Files section, select at least one file, and click Queue Job again.

**"The following files are not valid sync files."** The file name you specified is not in the list of supported sync files. Use the file selector in the UI to choose files rather than typing names manually.

**The migration connection string is not configured.** The destination database connection has not been set up for this environment. Contact your system administrator to configure the Migrate Connection String in site settings before running any migration.

**The migration fails with a database error.** A failed migration is always rolled back automatically — the destination is left unchanged. Check the error message in the result for details. Common causes include schema differences between environments (when the destination is on a different version than the source) or network timeouts on large datasets. Re-attempting the migration after the underlying cause is resolved is safe.

**A sync file reports "SQL file not found."** The system file associated with that sync option was not deployed to the server. Contact your system administrator to verify the deployment package includes all required script files.

**Migrated content does not appear in the destination immediately.** Sync file jobs run in the background. If you just queued a job, check the Sync Job History to confirm it has reached Completed status before checking the destination environment for the changes.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nimble.docs.otised.com/guides/migrate-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.