Configuration Export and Import Tool

Overview

This guide is for business users who move Workbench configuration between environments, such as from a sandbox to production. Export Config and Import Config are available to system administrators.

What these tools do

Export Config and Import Config copy configuration from one Workbench environment to another.

Use Export Config in the source environment to choose the entities you want, then download a configuration file. Use Import Config in the target environment to apply that file.

Choose only the entities you changed. That keeps unrelated configuration in the target environment as it is.

Workflow Steps Summary:

1. Make the configuration changes in the source environment.

2. Export the entities you changed.

3. Import the file into the target environment.

4. Wait for the completion email, then review the job record before anyone relies on the target environment.

Important Note: 

Leave configuration unchanged from the time you start an export or import until you receive the completion email. Changes made while a job is running can be missed or overwritten.

Accessing and Using the Tools

1. Sign in to Workbench.

2. Open the profile menu in the top right corner and go to System Settings.

3. In the left menu, open Export Config or Import Config.

The Export Config list shows configuration exports, the automatic backup taken before an import, and other data exports. Configuration jobs use these names:

• Configuration Export, followed by the environment name and the date and time
• Configuration Backup before import, followed by the date and time

The Import Config list shows configuration imports. Those records are named Configuration Import, followed by the date and time.

What an export includes

The export window lists configuration entities and system entities. It excludes deprecated entities and ordinary business records such as applications, licenses, and payments.

Export Contents tells you what the file will contain for that entity:

Entity setup means the entity structure, such as its fields. 
Configuration records mean the records stored in that entity, such as fee products, templates, or lookup values.

File attachments are not included. After the import, add those files again to the matching records in the target environment.

Export configuration

Choose the entities

1. Open Export Config.
2. Select the Export Configuration button in the toolbar.
3. In Export Configuration, review the list. The window explains: select the configuration and system entities to include in the export.
   

While viewing the list of entities to include in the export, these columns are visible to view and sort by.

• Select All and a checkbox on each row
• Entity Name, sorted A to Z. Select a name to open that entity and review its records. Your selections stay in place when you return to System Settings.
• Entity Label
• Last Modified On and Last Modified By, for the last change to the entity setup. Dates use your time zone.
• Export Contents
  

Select a column heading to change the sort. Search by entity name or label to shorten the list. The footer shows how many entities are selected. Export stays unavailable until at least one entity is selected. Cancel closes the window without starting an export.

Start the export

1. Select Export.

2. Confirm the message: you will receive an email once the export is complete, and you should not change any configurations during this time.

3. A new row appears on Export Config with status Submitted, then In Progress, then Completed. A failed job shows Error.

4. When the job finishes, Workbench emails you with the subject Configuration export is ready. The email points you back to Export Config. The file is not attached to the email.

Download the file

1. Open the completed Configuration Export record.

2. Read the messages for a summary of what was exported, including any entity or record that was skipped.

3. Open the Files tab and download the JSON file. 

• Keep the file name as downloaded. The name includes the source environment, a check value, and the date and time, in this form:
• config_export-{environment}_{check-value}_{date-and-time}.json
• Import checks that name. A renamed or edited file is rejected.

Import configuration

Import applies to every entity in the file. You choose entities during export, and you do not choose them again during import.

Upload the file

1. Sign in to the target environment.

2. Open System Settings, then Import Config.

3. Select the Import Configuration button.

4. Read the message: a backup file will be generated; you will receive an email when the import is complete, and you should not change any configurations during this time.

5. Select the JSON file, or drag it into the upload area, and select Upload.

• Workbench first tries to save a full backup of the target environment. That backup is a separate job on Export Config, named Configuration Backup before import. It includes the environment’s configuration entities, including entities that are not in the file you are importing. This backup does not send its own email.
• Note: If that backup cannot be created, the import still continues. Before you treat the import as protected by a backup, confirm that the backup record exists and its status is Completed.

What the import changes

For each entity in the file:

• Metadata and Metadata + Data: the entity setup on the target is replaced with the setup from the file. An entity that does not exist yet is created.
• Data and Metadata + Data: a record with the same record ID is updated. A record that does not exist on the target is added. Records already on the target that are not in the file are left as they are.

Notes:
The import cannot remove a record. Deleting a configuration record in the source, then importing, leaves that record in place on the target. Remove it on the target yourself when it should no longer be there.

An entity whose setup is missing on the target, and whose setup is not in the file, is skipped. The message log names anything that was skipped.

After the import

1. Wait for the email with the subject Configuration import completed.

2. Open the import record on Import Config.

3. Confirm the status is Completed, and read the messages for skipped entities or records.

4. Add any file attachments again on the target records.

To put the previous configuration back, download the Configuration Backup before import file from Export Config and import that file. The backup restores the setup and records it contains. Records added on the target after the backup was taken remain in place.

Job status

Refresh the list if a new job does not appear right away. There is no limit on how many export and import records Workbench keeps.

Limitations

• Only a system administrator can see Export Config, Import Config, and their action buttons.
• The tools copy configuration and system-entity setup. They do not copy business records such as applications, licenses, invoices, or payments.
• Deprecated entities are excluded.
• File attachments are excluded. Add them again in the target environment.
• Import updates and adds records. It does not delete records that are missing from the file.
• Records are matched by record ID. The same configuration created separately in each environment can have different IDs, so the import adds a second record instead of updating the existing one.
• Export related entities together. A lookup or link only works on the target when the related record is already there or is included in the same file.
• Keep the downloaded file name. Renaming or editing the file causes the import to fail with status Error.
• The selection list loads up to 1,000 entities. If an entity you expect is missing, contact Thentia.
• A backup is attempted before every import, and a failed backup does not stop the import. Check Export Config for a completed Configuration Backup before import record.
• Leave configuration unchanged until the completion email arrives.

Recommended practice

1. Confirm the source environment matches the target before you make changes, so the export carries only the changes you intend.
Note: If this is the first time you want to use this tool and you have done a manual migration (recreating configuration records in the Production environment manually) 
Then contact Thentia Support so that we can refresh your Sandbox instance. 

2. Make the changes in the source environment.

3. Export only the entities you changed, including entities that those changes depend on.

4. Import the original downloaded file into the target environment.

•     A new backup job is created in the Export Config section

5. Wait for the email, then review the import messages and the backup record.

6. Reattach files and remove any configuration records on the target that the import left behind. (Example: Document/Letter template)