> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insight.nobly.dk/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration promotion
> Move configuration you have built and verified in one environment to the next: export it to a file, preview every difference in the target, and apply the changes you choose.
Configuration promotion takes configuration that already works in one environment, such as TEST, and applies it to another, such as PROD, so you do not rebuild it by hand in each environment. You export the source environment's configuration to a file. You then import that file in the target environment, review every difference it would make, and apply the changes you tick. Each promotion is recorded in the target environment's history.
Open **Admin settings → General → Configuration promotion**. The page has four tabs:
| Tab | What it is for |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| **Export** | Export this environment's configuration to a file |
| **Import** | Compare an exported file with this environment, review the differences, and apply the ones you choose |
| **Rules** | Map user group names from other environments to the groups here, and record what this environment keeps different |
| **History** | See the **Environment status** and every promotion applied to this environment |
## How a promotion works
Choose the configuration types to include and export them. The file downloads straight away.
Every difference between the file and the target environment is listed as a change to create, update or delete. Changes that cannot be applied yet are marked **Blocked** with the reason. Nothing is written until you apply.
Map user group names the target does not have to the groups it does have, and create anything that has to exist first, such as a secret value.
Tick the changes to apply, confirm, and add a comment such as a change request reference. The target environment's configuration is saved as a version first.
The result shows what was applied. **History** keeps the record, and **Environment status** shows anything changed directly in the environment since.
The file is the only thing that travels, and the environments are never connected directly. To promote DEV → TEST → PROD, export from DEV and import in TEST, then export from TEST and import in PROD.
Configuration is matched by **name**, not by internal ID, so a document type or keyword type is recognized in each environment even though its ID differs. The one exception is script code, which is copied as written. A script that uses an ID from the source environment is flagged for you to check; see [changes left out until you tick them](/configuration-promotion/promoting-configuration#changes-left-out-until-you-tick-them).
Configuration is fixed forward. No step restores an earlier version. To change what a promotion applied, change it in the source environment and promote again.
## What a promotion covers
The **Export** tab groups the configuration types as follows. A type appears only if that part of the product is available in the environment. For example, workflow types need workflows to be available.
| Group | Configuration |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Documents** | Document type groups; document types, with their keyword assignments and access rights; custom document actions; retention policies |
| **Security** | Security keyword rules; permission grants, meaning which user groups hold each application permission |
| **Keywords and data** | Keyword types, including their value lists; keyword type groups; external datasets; autofill keyword sets (their definition, not their values); cascading datasets |
| **Caseflow** | Applications; classes, with their attributes and access rights; sequences; Caseflow and form templates; datasets; bulk edit settings; attribute security rules |
| **Search and navigation** | Shared saved searches and their folders; folder trees; navigation links |
| **Client and appearance** | Client settings; feature controls; banners |
| **AI** | AI settings; the AI classification tree; AI extraction profiles |
| **Reporting** | Data sources; dashboard categories; dashboards; allowed reporting sources |
| **Workflows and scripts** | The latest published version of each workflow; workflow schedules; workflow environment variables; workflow secrets (names only); the published version of each script with its bindings; script secrets (names only) |
## What a promotion never moves
Some configuration stays in its environment by design:
* **User groups and their members.** A promotion never creates, renames, deletes or copies a user group. References to groups are matched by name, and a name the target does not have blocks the change until you [map it with a reference rule](/configuration-promotion/rules-and-differences#user-group-reference-rules). Rights that belong to promoted configuration do travel: document type access, Caseflow class access, template user groups and application permission grants. Privileges set on the group itself stay with the group.
* **Secret values.** Script secrets and workflow secrets travel as names only. Set the value in the target environment by hand.
* **Credentials in workflow environment variables.** A variable whose value looks like a credential is exported without its value. Examples are a value containing a password, key, secret, token or shared access signature, or a URL with a user name and password in it.
* **Data.** Documents, keyword values, autofill values, Caseflow objects and users are not configuration and are never promoted.
* **Storage and file prerequisites.** Disk groups, file types, note types and folder types must already exist in the target. A change that needs a missing one is blocked until you create it there.
* **Environment-specific AI settings.** AI model selection and AI rate limits are set in each environment.
* **Personal searches and unpublished work.** Only shared saved searches travel. For scripts and workflows, only published versions travel.
* **Settings maintained outside Nobly Insight.** Password rules and the rights to create form letters are neither compared nor copied.
Values that are often different on purpose, such as addresses and connection details in workflow environment variables, do travel. They are held back for you to check; see [changes left out until you tick them](/configuration-promotion/promoting-configuration#changes-left-out-until-you-tick-them).
## Permissions
To open **Configuration promotion**, you need **Keyword configuration administration** (`keyword-configuration.admin`). Without it, the menu entry is hidden. The same permission is required to export, preview and apply.
On top of that, promotion asks for the same permissions as the admin screen of each configuration type:
* **Seeing a type** decides what you can export and import. When you export all types, types you cannot view are left out of the file. When you pick a type you cannot view, the export is refused and names the permission you are missing. A file that holds a type you cannot view is refused on import.
* **Changing a type** decides what you can apply. A change you may view but not make arrives **Blocked** and names the permission it needs.
* **Adding or removing reference rules** also needs **Manage user groups**.
* **Adding or removing kept differences** also needs permission to change and delete the type concerned, or every type for an entry that applies to any type.
* **History and environment status** show every promotion, but list the individual changes only for types you can view.
| Configuration | To export and preview | To create or update | To delete |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Document types, document type groups | View document structure | Manage document structure | Document structure administration |
| Custom document actions | View document structure | Manage document structure; a workflow action also needs View workflows | As for create |
| Keyword types, keyword type groups, autofill keyword sets | View keyword configuration | Manage keyword configuration | Keyword configuration administration |
| External and cascading datasets | View keyword configuration | Manage keyword configuration | Manage keyword configuration |
| Security keyword rules | View keyword configuration and View user groups | Manage keyword configuration and Manage user groups | As for create |
| Caseflow applications, classes, sequences, datasets | View Caseflow configuration | Manage Caseflow configuration | Caseflow configuration administration; classes are never deleted by a promotion |
| Caseflow bulk edit settings | View Caseflow configuration | Manage Caseflow configuration | As for create |
| Caseflow attribute security rules | View Caseflow configuration and View user groups | Caseflow configuration administration and Manage user groups | As for create |
| Caseflow and form templates | View Caseflow configuration and View form templates | Manage Caseflow configuration for a Caseflow template; Manage form templates for a form template | As for create |
| Permission grants | View permissions | Manage permissions | As for create |
| Feature controls | View user groups | Manage user groups | As for create |
| Navigation links | View users | Manage users | As for create |
| Client settings | View users, View upload behaviour, View keyword behaviour and View Caseflow configuration | The Manage permission for the settings that change | As for create |
| Banners | Manage banners | Manage banners | Manage banners |
| Folder trees | View folder trees | Manage folder trees | As for create |
| Shared saved searches and folders | View system searches | Manage system searches | As for create |
| Retention policies | View retention policies | Manage retention policies | As for create |
| Reporting data sources | View reporting data sources | Manage reporting data sources | As for create |
| Dashboards, dashboard categories | Manage reporting dashboards | Manage reporting dashboards | As for create |
| Allowed reporting sources | Manage reporting allowed sources | Manage reporting allowed sources | Never deleted by a promotion |
| AI settings | View AI configuration, View AI chat settings and View AI search index | Manage AI search index for automatic indexing; Manage AI chat settings for chat settings; otherwise Manage AI configuration | As for create |
| AI classification tree | View AI configuration | Manage AI configuration | As for create |
| AI extraction profiles | View extraction profiles | Manage extraction profiles | As for create |
| Scripts | View scripts | Manage scripts | Script Engine administration |
| Script secrets | Script Engine administration | Script Engine administration | Script Engine administration |
| Workflows, workflow schedules | View workflows | Manage workflows | Never deleted by a promotion |
| Workflow environment variables and secrets | Workflow Engine administration | Workflow Engine administration | Workflow Engine administration |
See [Application permissions](/permissions/application-permissions) for what each permission grants on its own.
## Before you begin
* **Confirm the feature is available in both environments.** Configuration promotion is enabled per tenant. It is not available in environments whose database runs on Oracle. If the page is missing, contact your consultant team.
* **Run the same release in both environments.** The file records the release it was exported from, but the import does not check it. A configuration type the target does not recognize makes it refuse the file.
* **Prepare what the target must already have.** That includes its user groups, the disk groups and file types your document types use, and the secret values your scripts and workflows read. Also decide how group names in the source map to groups in the target.
* **Handle the export file as sensitive.** It holds script code, reporting queries and workflow environment variable values that do not look like credentials. Store and share it the way you store configuration.
Do not edit an export file. The import checks every entry against the file's own fingerprints and refuses a file that has been changed after export. Export again instead.
## Where to read next
Export from the source environment, review every difference in the target, and apply the changes you choose.
Map user group names between environments and record what an environment keeps different on purpose.