Importing/Exporting Document Types¶
A Document Type incorporates the Document Fields, Document Field Detectors, and Categories assigned to it. Document Types - along with all of their Fields and Field Detectors - can be migrated to other instances of ContraxSuite to which an Admin has access. Admins can bring a new Document Type into the instance, or update an existing Document Type, using this import/export function.
The following instructions are for importing, or exporting, Document Types using the Document Explorer in ContraxSuite. For instructions on how to import or export Document Types in the ReactUI, click here.
Migrating Document Types¶
Note: Depending on the number of Fields and Field Detectors associated with the Document Type, the migration process may take between 1 and 3 hours to complete
1. Log in to the ContraxSuite instance that contains the version of the Document Type you wish to migrate. Go to Data Science in the Main Menu and select Document Explorer.
2. In the Document Explorer, click Administration from the left column and then select Admin Tasks from the submenu. From the “Admin Tasks” page, click on the “Run Task” button in the upper left, and select “Export and Import” from the dropdown. Finally, select “Export document type.”
3. Select the Document Type you want to export. Then, select an option in the “Target CS Version” drop-down. The ContraxSuite version that you select should match the version of the ContraxSuite instance you wish to export this Document Type into (This is set to “Current” by default). Finally, click “Go”.
4. Find the exported file in your Downloads folder, and save it somewhere you can find it easily again on your local drive. Then go to the ContraxSuite instance where you want to import the Document Type that you just exported. Repeat Step #2, but this time choose “Import document type” from the menu.
5. In the “Import Document Type” window, click “Choose File” inside the “Document Type JSON file:” drop-down to select the Document Type file you exported and saved in Steps 3 and 4.
6. Once you have selected the Document Type file you wish to import, make sure that the “Source CS Version (optional)” form has the ContraxSuite version that corresponds to the file you’ve chosen to upload. The option to “Cache document fields after import finished” should be checked by default (recommended).
Before selecting “Go”, you have one of four options to choose in the “Action” drop-down. This is an important decision, depending on what you need your Document Type import for.
Option 1: Validate Only. Recommended first step for already in-use Document Types. Choose this option if you want to first ascertain whether the data in a Document Type can validly be imported into your chosen environment. This option is useful if you first want to figure out what is different between the source ContraxSuite instance and the destination instance, but wish to address any problematic discrepancies manually.
Option 2: Validate and import if valid. Recommended approach for new Document Types. Choosing this option will allow the system to import the Document Type only if there are no conflicts. If there are conflicts, the import will be cancelled and the conflicts will be reported in the log.
Option 3: Import and force auto-fixes - Retain extra fields / field detectors. WARNING: May delete data. This should only be used for Document Types that are not in live usage and/or do not yet have live data. This will force resolution of conflicts between the Document Type in the destination instance and any changes made in the source instance, and potentially delete invalid Field configurations, though all extra Fields and Field Detectors will still be stored. If you choose this option, it’s a good idea to follow up by reviewing Fields and Field Detectors for any extra data that may have been created by the import.
Option 4: Import and force auto-fixes - Remove extra fields / field detectors. WARNING: May delete data. This should only be used for Document Types that are not in live usage and/or do not yet have live data. Choosing this option will force the configuration of the Document Type in the new instance to conform exactly to its configuration in the instance from which it was exported, deleting Fields, Field Detectors, Field Values, and/or Field Annotations in order to do so.
Recommended Approach For Preserving User-Entered Data¶
We recommend that the following procedure be completed during maintenance hours
1. Select “Validate Only” and uncheck “Cache document fields after import finished”. This will not change anything in your production data or configurations; instead, you will just have a report of issues to resolve. If the Document Type in question has many Fields, and you’ve been careful about only making changes on a development (“dev
”) instance, then you may skip to #5 below.
2. When this task completes, the system will display either “SUCCESS” or “FAILURE”. Click View Logs to scan the log. You may have to skim the entire length of the log to find the word ERROR
. If ERROR
does not appear in the log, then there were no issues found and you can skip to #5 below.
3. Potential conflicts will lead to the message “VALIDATION ERRORS OCCURRED DURING VALIDATION”. The validation errors will be numbered and will look similar to the following:
"VALIDATION ERROR 1. Unable to update field #[UUID HERE] field_code_name_here.
Field type has changed, old field type is "Amount", new field type
is "Floating Point Number." Existing document field values become
invalid and will be removed. User entered X values, automatically
detected Y values. You need to set auto-fixes option to continue.
4. It is recommended you manually resolve all of the errors, rather than choosing any of the options that force changes (“Option 3” and “Option 4” above). Manually resolving errors will better inform you of what data you may be deleting, and this is also the safest method for making sure you have not deleted any data inadvertently. This manual review may involve deleting empty Document Fields, deleting extra Field Detectors that were already deleted from the source instance, etc. You can see which Field is being referred to by copying the UUID from the error code and pasting it at the end of this URL https://www.YOURCONTRAXSUITEINSTANCENAME/advanced/admin/document/documentfield/[UUIDHERE]
.
5. Once you have resolved all of the errors documented in the log, run the “Import” task again, choose the .json
file, and then select “Validate and import only if valid” in the “Action:” drop-down. Leave “Cache document fields after import finished” checked.
6. If all errors are resolved, the “Import” task will succeed. If you have not resolved all remaining errors, the task will fail. Look through the logs, and if necessary repeat these steps, to discover any additional unresolved errors.
Potential Problem Scenarios in Export/Import¶
WARNING: There is a lot of potential for conflicts when a Document Type exists on 2 or more ContraxSuite instances and you wish to update one instance with the Document Type configurations from another. It is STRONGLY recommended that you only ever make changes to Document Types in one “development” instance, and then migrate all new configurations to your main project environment once they are ready. Failure to do so is likely to create extraneous Fields and Field Detectors that cannot be synchronized, which can lead to downstream problems like accidental deletion of data, malfunctioning Fields, or other errors.
Below are examples of potential problem scenarios that can occur as a result of improper Document Type migration.
Conflict in Field Types: Imagine you have a String Field that you later decide to convert to a Number Field. If you change the Field Type on the source instance, the data will be deleted when you import the Field to the destination instance, because the string value cannot be converted to a number. This issue could lead to downstream deletion of string data from the Field.
Duplicate Fields: Imagine you have a Field with the Field Code “rent_amount” on one instance. On another instance, you create a Field and re-use that same Field Code of “rent_amount”. There is no inherent conflict when using the same Field Code on two different instances, but if you try to migrate this Field to an instance that already has a Field with the same Field Code, the system will not be able to resolve the conflict and will attempt to create a duplicate Field or delete one of the Fields. Depending on which of the four “Action” options you choose during the import process, this could lead to the “Import” task failing. Document Fields and Document Field Detectors are migrated and tracked based on their Codes, and on their unique UUIDs. Be sure to monitor both Field Codes and Field UUIDs for duplication issues.
Extra Field Detector: The system will always try to synchronize Field Detectors during an “Import” task. Imagine that you did not choose an import option that forces auto-fixes, and you have 3 Field Detectors for one Field. You decide that only 1 Field Detector is worth keeping, so you delete the other 2 Field Detectors from the source instance. However, your destination instance still contains a version of the Field that has 3 Field Detectors. Importing this Field from the source instance to the destination instance may result in a validation error. We recommend that in situations like this, you manually review and delete any extra Field Detectors from both your source instance and your destination instance, so that you are positive of what has been deleted. Depending on which of the four “Action” options you choose during the import process, failure to perform this kind of manual review could lead to the “Import” task failing, or to accidental deletion of data.