2.6 Import Data

OpenClinica allows you to import Event CRF data from a file as an alternative to performing data entry using the OpenClinica web interface. The import data feature is useful when the data you want for a Study in OpenClinica is captured using a system other than OpenClinica. When data is imported, the Audit Log records the userid of the person performing the import as the data entry person.

Before importing data into OpenClinica, the following tasks must be completed:

  • Create the Study in OpenClinica
    Tasks>Create Study and then Tasks>Build Study>Create Study
  • Create the CRFs for the data being imported
    Tasks>Build Study>Create CRF
  • Add the Event Definitions for the data being imported, and associate CRFs for the data being imported with the Event(s)
    Tasks>Build Study>Create Event Definitions
  • Enroll the Study Subjects for the data being imported
    Subject Matrix>Add New Subject

  • For each of the Subjects, schedule the Events for which data is being imported
    Subject Matrix>Click on an Event for a Subject, then click Schedule and schedule the Event.

In addition, the following data characteristics are enforced when data is imported:

  • Data cannot be imported into a CRF that has a status of DoubleDataEntryStarted or DoubleDataEntryComplete.
  • Dates must be imported in the format YYYY-MM-DD
  • Data types in the import file must match the item data type in OpenClinica (i.e., you cannot import a character string into an item that was defined as integer).
  • Data values must match the response values specified in the eCRF. For example you cannot import "3" if the only response options provided were Yes (1) and No (2).
  • Required fields cannot be empty.

The information in the import file can be for:

    • one or more Subjects
    • one or more Events for each Subject
    • one or more CRFs for each Event

The type or amount of information for each Subject does not have to be the same. For example, the file can include one Subject with two Events - each with one CRF, and another Subject with one Event that contains three CRFs.

Sample eCRF and Import File

This section presents a sample eCRF and the related XML file that would import data into that CRF. Prior to performing the import, all of the steps listed above were performed.

Sample eCRF:

Sample XML File:

The following XML file was used to import data into the above eCRF. In the sample below, all highlighted values are values that must be specified for each import as follows:

  • Values in red are where your various OIDs must be provided
  • Values in bold are where you specify the description and status conditions for the import
  • Values highlighed in blue should be replaced with the actual data values that you want to import into the associated Item OID.

Import Status and Form Status

Beginning with version 3.6 of OpenClinica, the UpsertOn tag in the XML code for importing data allows you to specify whether to perform the import or not based on the current CRF status. This provides the option to update data that has already been imported or entered. For example, the following specification would only import the data if the current status of the form is "not started":

<UpsertOn NotStarted="true" DataEntryStarted="false" DataEntryComplete="false"/>

If you want to use the import to update data that is already in the database, but has not yet been marked complete, then use the following settings:

<UpsertOn NotStarted="false" DataEntryStarted="true" DataEntryComplete="false"/>

If all three statuses were set to true, then the import would occur regardless of the CRF status. If all three statuses were set to false, data would not be imported.

If you choose to remove the UpsertOn option from the XML file, then OpenClinica performs the import as if all UpsertOn statuses were set to "true."


  • For any data that is being imported and does not match the criteria for the UpsertOn settings, a list of "skipped" records is displayed for your review. Based on the data that is displayed, you may need to modify the UpsertOn settings, or you may want to continue with the import if the data was skipped appropriately.
  • You cannot import data into a CRF that has a status of DoubleDataEntryStarted or DoubleDataEntryComplete. OpenClinica does not include that data in the import, but does provide information about the skipped data in the Summary Statistics and Import CRF Data details window. 

Assign a Status

By default, when an import is complete, OpenClinica sets the CRF status to "complete." OpenClinica version 3.6 provides the option to instead set the status of the CRF to "data entry started" after the import is complete. To do this, set the "OpenClinica:Status=" to "inital data entry" (case sensitive). The following tag includes the Form OID (in this example F_DEMOG_1) as well as the status setting for that Form once the import is complete:

<FormData FormOID="F_DEMOG_1" OpenClinica:Status="initial data entry">

In this example, once the data is imported, the form will have a status of initial data entry.

If you remove the OpenClinica:Status clause from the XML file, or provide any value other than "initial data entry", OpenClinica implements the default behavior and sets the status of the form to "complete". Although you may omit the OpenClinica:Status="initial data entry" clause, the rest of the FormData statement must remain in place in order for the import to function.

The data import file must be a properly-formatted XML file. For details, see Data File for Import.

Automatic Edit Checks

For Rules to run automatically upon import, the Run parameter ImportDataEntry must be set to "true". For more information, see Creating Rules. 

Edit checks are processed as follows:

  • If Rules are set to run during import, failed Rules automatically create Failed Validation Discrepancy Notes.
  • If there are errors with the import definition (for example you tried to import text into an item defined as a date), then an error message displays in the the Alerts and Messages section of the screen.
  • If there are no errors, the CRF is automatically marked with the status provided in the "OpenClinica:Status=" clause.
  • Any subsequent changes can be done by editing the data via the Subject Matrix or by re-importing using the appropriate UpsertOn value. If you had set the OpenClinica:Status to "complete" on the initial import, the data can only be edited using Administrative Editing.
  • If there are any calculated value fields in the CRF, you must either supply the correct data in the import file or open and save the CRFs manually to generate the calculations.

You can automate the importing of data, which is useful when you import the data files on a recurring basis: see Scheduled Import Jobs. Another alternative for getting data into OpenClincia is with SOAP Web Services: see the import Data Web Service API in the OpenClinica Technical Documentation.

Functional approval by Laura Keita (lkeita), Director of Training and Compliance. Signed on 2016-06-06 12:56PM

Approved for publication by Benjamin Baumann (bbaumann), Principal. Signed on 2016-06-07 12:14PM

Not valid unless obtained from the OpenClinica document management system on the day of use.