❗Notes on Study Design Export and Import

Summary

This document describes the management of study design files (.studydesign) in ClinSpark.

A study design file contains more than just study configurations. It also includes instance configurations closely linked to study properties such as Roles, Sites, Lab Interfaces, and Devices. These configurations are not limited to the study that is being exported/imported, but would impact all studies in the ClinSpark instance upon each upload.

One of the main purposes of the study design import mechanism is to provide an automated way to ensure that relevant configurations of a TEST instance match the MAIN instance. Many of the configurations in TEST instances are not allowed to be changed via the ClinSpark user interface because they are intended to automatically configured to match MAIN instance using this feature.

Export/Import Functionality

Study design files can be exported using the Administration > Utilities component.

Starting in ClinSpark version 1.5, design files can be imported to an environment through one of two ways:

Using Administration > Utilities, users can import study design from a PROD instance into a TEST instance. Upon import, the selected target study in TEST will have all study data erased and study design updated to match that of the source design file from PROD.
Using Administration > Studies, users can select the ‘Upload’ action menu item. This upload feature safely copies a design from the same instance into a new study, instead of replacing an existing study. Users also have the ability to review and optionally remove certain study design elements during the importation process. This upload mechanism is currently designed to only accept study design files from the same ClinSpark instance. For example, it is expected that a study design from PROD MAIN be uploaded into the same PROD MAIN instance. This feature does not support the upload of design files across different ClinSpark instances (such as taking a design from PROD MAIN and uploading to PROD TEST) or different environments (such as taking a design from a VAL environment into a PROD environment).

Dynamic Configuration Logic

There is a configurable global system setting called ‘ImportExportService’. This system setting contains a majority of the logic supporting the import/export process, and allows for a wide range of dynamic updates of the import/export features without requiring the need for a core code change (similar to other dynamic system components).

Changes to the system setting logic may be necessary to support unique customer requirements or certain support scenarios where issues may be occurring. Modifications to this setting are protected by Foundry Health ‘superadmin’ users and accommodated via service desk tickets where applicable.

Preconditions of Import

Import will automatically merge a wide range of study and instance configurations from the source instance to the target instance. However, certain preconditions of import are expected in order for the operation to proceed.

Matching ClinSpark Versions

When using Administration > Studies > Upload, the version & build numbers between source and target environments must be an exact match. Additionally, the study design file must be sourced from the same environment (meaning a design file cannot be uploaded if it came from another environment).

When uploading via Administration > Utilities in an environment running in ‘Test Mode’, the version & build does not need to match between source and target environments. Additionally, the design file can be sourced from a different environment (meaning a design file sourced from PROD can be imported into TEST).

Medical Dictionaries

Customers that leverage WHODrug and MedDRA dictionaries as part of study configurations are expected to have matching dictionary files loaded between their PROD MAIN and PROD TEST instances. However sometimes there may not be an exact match in the dictionaries between source/target environments which may cause certain issues upon import.

The import logic will check what dictionaries are present as it executes, and will attempt to match dictionary configurations for a study if they’re found in the target environment. If there is not a matching dictionary found, the import will still succeed but will not associate a dictionary to the study configuration automatically. This is true of both WHO Drug and MedDRA dictionaries.

Site configurations

When importing a study design file, system logic will attempt to merge all site configurations from the source design file environment into the target. If sites are missing in the target environment, the import mechanism will attempt to create them and associate with the imported study, but this may not always succeed with desired results (as the sites may not be properly linked to the study). To prevent these sorts of issues, it’s always best to ensure that site configurations match between target and source environments before performing an upload.

Addressing Import Failures

On rare occasion the study design import process may not succeed. There may be a number of conditions that would cause this, but whenever errors do occur, users are typically notified via error messaging in the user interface. We continuously look at improving these messages in newer releases to provide more context as to why a given import may have failed.

Most commonly we see issues associated with imports into a ‘target’ study that may have been used previously. Existing data or configurations in these already established studies can sometimes causes a conflict with import entities that are being merged in from a newer import file. When this happens ClinSpark will stop the import attempt as the feature is designed to commit changes only when fully succeeding with all import logic.

When users receive an error that their study design import has failed, the recommended path is to review the error message and see if there is enough context to self-correct. Otherwise, users should try the process again, but using a brand new receiving (target) study. This will allow the import mechanism to establish the specific study design and related data entities for the first time again in that study, instead of merging with an existing data set.

If customers continue to experience challenges with imports even into new studies, they should reach out to the Foundry Health support team via service desk. It is ideal to provide a screenshot of the error message present in the user interface as well as the study design file that is being used.

Import Entities

The following table represents all of the import entities that ClinSpark attempts to merge from source (MAIN) into target (TEST) studies.

Imported Entity	Description and Notes
Sample Tasks
Specimen Containers
Application User Roles and Role Actions	Application User Role configurations are synchronized from source to target upon import. This overwrites user Roles & Role Actions at the system level within the target environment. Role Actions cannot be modified from within environments running in ‘Test Mode’; changes can only be made through the import mechanism.
Sites	This include LabInterfaces, LabTests, LabPanels, and the lab’s Specimen Containers.
Device Categories
Devices
EDC Devices	This includes all EDC Devices, EDC Device Parameters and EDC Device Settings
Volunteers Interfaces	These are bindings between a Volunteer record and a CRF form. They are used in automatic importation into a form from the volunteer record.
Sample Containers
Study Lab Panels	Any Lab Panels belonging to the imported study, along with all lab tests referenced by those panels, are merged in.
Sample Path Configuration	This includes the study’s Sample Paths, Sample Path Transfers, Sample Path Step Devices, and Sample Path Specimen Containers
ECG Study Configuration
OpenClinica Account	The configuration of OpenClinica for the exported study if applicable.
Rave Account	The configuration of Rave for the exported study if applicable.
All CRF Design for the exported study	Notes Methods, Study Events, Forms, Items, ItemGroups, Code Lists, etc. Everything found in the CRF Design Study Library is included in the export.
All Activity Plan design for the exported study	Notes Everything configurable from this tab is included in the export.
All Study configuration for the exported study	Notes Everything configurable from this tab is included in the export.