| Table of Contents |
|---|
Summary
This document describes provides details on workflows and features supporting 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 configuration entities such as Roles, Sites, Lab Interfaces, Devices, Volunteer Connectivity Parameters, and so on. These configurations are not always limited to the specific study that is being exported/imported, but would could impact all studies in a ClinSpark instance upon each upload.
For this reason, the purpose of study design import mechanism is it to provide an automated way to ensure relevant configurations of a TEST instance match the MAIN instance. Many of the configurations in TEST instances are purposely not allowed to be changed via the ClinSpark user interface because they are intended to automatically be configured to match MAIN instance using this feature. More information about the management and use of TEST & MAIN instances can be reviewed here: https://foundryhealth.atlassian.net/wiki/spaces/DOCS/pages/3700260899/Technical+Overview#Environments
Export/Import Functionality
...
Using Administration > Studies, users can select the ‘Upload’ action menu item. This workflow accepts a .studydesign design file from the same ClinSpark instance.
This upload feature safely copies a design into a brand-new study, instead of replacing an existing study. This feature It is intended to be a quick way to copy an existing study design into the same environment. Users also have the ability to review, modify and optionally remove certain study design elements during the importation upload process.
...
This upload mechanism is 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.
...
There is a configurable global system setting called ‘ImportExportService’ which defines a portion most of the logic supporting the import/export features. As a dynamic system setting, it allows for certain updates of the import/export features feature logic to be done without requiring the need for a core code change (similar to other system components likes reports and dashboards).
...
| Info |
|---|
We do not encourage customers import study designs from different types of environments, for example, taking a design file from a Sandbox or VAL environment and importing into PROD. Clinspark was not designed with design files to be important wit used with this intent. These types imports often do not succeed due to differences in system settings, configurations and feature differences between versions. |
Medical Dictionaries
Customers that leverage WHODrug WHO Drug 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.
...
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.
...
...
Import
...
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 IQVIA 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 details represent all of the import entities that ClinSpark attempts to merge from source (MAIN) into target (TEST) studies. An entity can represent a set of configurations or settings that influence the behavior of an environment or a study design.
...
MedDRA Dictionary
Data Reviewers
Informed Consent
Recruitment Questionnaires
User Access
Cohort Assignments or Subjects that existed in ‘source’ studies
Addressing Import Failures
Sometimes the study design import process may not succeed. There may be a number of conditions that would cause this. This article provides guidance to customers to mitigate possible import failures.
Optimizing Study Design Import Workflows
Some issues are associated with use of the Administration > Utilities | Import feature, where imports are done into a ‘target’ study that may have been used previously for a long period. Existing data or configurations associated to these already established studies can sometimes causes a conflict with import entities that are being merged in from a newer import file.
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 IQVIA 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.