Curriculum 'User Guide Viedoc 4'

Data mapping for import of data Download PDF

1 Introduction

  • Viedoc offers the possibility to import data, for example laboratory data, via the Viedoc 4 Data Import Application. The Viedoc 4 Data Import application does the following:
    • it converts the provided data into CDISC ODM clinical data format using a data mapping file, and
    • it pushes the data into Viedoc through the Viedoc 4 API.
  • You can download the latest version of the Viedoc Data Import Application from the Data mappings window in Global design settings in Viedoc Designer.
  • This lesson describes how to create a data mapping file in Viedoc Designer. More information on how to use the Viedoc 4 Data Import Application, see the Viedoc 4 Data Import Application document. The Viedoc 4 Data Import Application document is available on request, please contact PCG Solutions AB.
  • Instructions on how to create a data mapping file and how to import data using the Viedoc 4 Data Import Application can also be found in our video tutorial. Click here to watch the video.

2 About importing data into Viedoc 4

  • In order to import data into Viedoc, the following is needed:
    • the Viedoc Data Import application,
    • a data mapping file,
    • a configuration file,
    • a valid Viedoc username and password, and a study-specific Viedoc 4 API client key,
    • the data file containing the data to be imported. The data file should be a delimited file, such as a CSV (comma-separated value)-file.
  • The data mapping file defines how the external data will be mapped to form items in Viedoc. You can create a data mapping file in Global design settings in Viedoc Designer. Internally, the data mapping will be stored in CDISC Define-XML format.
  • The configuration file is an xml file that defines (mandatory):
    • where to find the data mapping file,
    • where to find the data that should be imported,
    • into which Viedoc study data should be imported,
    • into which API instance the data should be imported,
    • the login credentials that should be used when importing the data.

    In the configuration file, you can also define the following (optional):
    • whether you would like new subjects to be added by the data import,
    • whether you would like visits to be initiated by the data import,
    • which character encoding should be used, when the imported file is read, and
    • which file delimiter should be used, when the imported file is parsed.

    One configuration file can contain the import configurations for multiple studies.
  • You can create a Viedoc 4 API client key in the Study settings window on the API configuration tab in Viedoc Admin.

3 The data import procedure

  • The import of data into Viedoc using the Viedoc 4 Data Import Application involves the following steps:
    1. Creating a data mapping file in Viedoc Designer.
    2. Creating a Viedoc 4 API client key in Viedoc Admin.
    3. Creating a configuration file (not in Viedoc).
    4. Preparing the work folder.
    5. Installing the Viedoc 4 Data Import Application.
    6. Dropping data into the work folder.
    7. Running the Viedoc 4 Data Import Application.
  • Detailed instructions on how to use the Viedoc 4 Data Import Application are provided in the Viedoc 4 Data Import Application document.

4 Description of the data mapping file

  • The data mapping file describes each column of the data file containing the data to be imported, and defines where these data should be imported into Viedoc.
  • A separate data mapping file should be created for each study, and for each type of data file to be imported.
  • The data mapping window in the Global design settings in Viedoc Designer has the following main fields (see image):
    1. Data Mapping Name, a name (free text) for the data mapping.
    2. Domain Name, the SAS domain that will be stored in the Define-XML file according to the CDISC standard.
    3. Data mapping table, that has two main parts:
    • Imported file structure, describing each column of the data file to be imported.
    • Viedoc, describing the destination of the data in Viedoc.
  • The data mapping table has the following columns:

    Column name Description
    # Number of the column in the data file to be imported.
    Column name Name of the column in the data file to be imported.
    Description Description of the parameter in that specific column to be imported (free text).
    Link to Links the content to a parameter defined in another column in the data file. This is used when importing data in a tall-skinny format.
    IM Item mapping: inserts more rows into the table so that one data column can be mapped to multiple destinations in Viedoc.
    Destination Address in Viedoc into which the data should be imported. This directs the data to the correct subject, visit, form and field.
    CL Code list: a list of codes that build up a dictionary that can be used to map the imported data values into their corresponding items in Viedoc.

5 Creating the data mapping file

  • Follow the steps below to create a data mapping file.
    1. In Viedoc Designer, select the study for which you would like to create a data mapping file.
    2. In the Global design settings field, click Edit to open the global design settings.
    3. In the Data mappings field, click Edit to open the data mappings overview.
    4. Click Add new data mapping, or
    if a data mapping has already been created, select the data mapping that you would like to edit.
    5. Type a name for the data mapping in the Data Mapping Name field.
    6. Type a domain name in the Domain name field.
    7. Click Add new row to add a new row to the table, and fill out:
    • Column name of the first column of the data file.
    • Description of the first column of the data file.
    • Destination in Viedoc of the data in the first column of the data file.
    For more information on how to correctly map the subject ID, visit ID and laboratory data, refer to the sections below.
    8. Repeat step 7 with the next column in the data file, until all the columns in the data file are described in the data mapping table.
    If you would like to link the contents of the current row to the contents of another row, select the row to link to from the Link to dropdown menu. This is mainly used for data in tall-skinny format. Choosing Link to automatically creates rows with the same code list items as the row that is being linked to. Linked rows can be updated by clicking on the refresh button.
    9. Click Save changes, and click Close to close the data mapping table.
    10. Click Close to exit the data mappings overview.
    11. Click Publish settings in the Global design settings window to publish the changes.
    12. In the Data mappings field, click Edit to open the data mappings overview.
    13. Click the Download icon behind the data mapping that you just created.
    An xml file will be downloaded that contains the data mapping.
    14. Save the xml file in the work folder.
  • If you want to map one data column to more than one destination in Viedoc, you can add more mapping details by clicking the +-icon in the IM column.
  • You can enter code list items by clicking the +-icon in the CL column. Code list items define how values in the data file should be translated into values in Viedoc. Code lists are also used to specify the address for data in tall-skinny format.
  • Code lists can also be used to map data to a form item in which multiple checkboxes can be activated (thus: to import multiple data into one item). When importing multiple data into one item, the data should be mapped based on code list item number, not based on code list item label. The reason for this is that it is only possible to import multiple values, not multiple strings.

    Note that for importing multiple data into one field, all data for that specific item:
    • should be separated by a comma, and
    • should be surrounded by one set of double quotation marks. This is to determine that these data belong to the same column in the data file, and thus should be imported into the same item.

    For example, let's say that we would like to activate the checkboxes belonging to code list items 1 and 3 during the data import. The data in the data file should then look as follows:
    ..., ..., "1,3", ... , ...
  • Only the fields with a light blue background can be filled in.
  • You can remove a table row by clicking on the trash can icon.
  • You can import and edit an existing Define-XML file by clicking on Import data mappings in the Data mappings overview. Select the file you would like to import and click Open. Edit the data mapping table if necessary and click Save changes to save the data mapping.
  • You can remove existing data mappings in the Data mappings overview by clicking Delete. It is not possible to delete a data mapping that has already been published.

6 Overview of variables to be mapped

  • The following table gives an overview of the variables that can be mapped.

    Variable Mandatory to map?
    SiteCode Mandatory at all times.
    SubjectKey Mandatory for importing data into existing subjects, not mandatory when new subjects are to be added.
    SiteSubjectSeqNo Not mandatory if the SubjectKey is mapped. Can be mapped separately for matching existing subjects or creating new subjects.
    StudySubjectSeqNo Not mandatory if the SubjectKey is mapped. Can be mapped separately for matching existing subjects or creating new subjects.
    StudyEventDefId Mandatory for matching the event that the data should be imported into.
    EventDate When importing data into unscheduled events, either EventDate or StudyEventRepeatKey is mandatory. Optional for scheduled events.
    StudyEventRepeatKey When importing data into unscheduled events, either EventDate or StudyEventRepeatKey is mandatory. Optional for scheduled events.
    FormDefId Mandatory for matching the form that the data should be imported into.
    ItemDefId Mandatory for matching the item that the data should be imported into, can be combined with FormDefId to one string.
    FormRepeatKey Mandatory only when the same form occurs multiple times within the same event.

7 Mapping the subject ID

  • The subject ID should be mapped to {SubjectKey}, see image. Note that the mapping is case sensitive!
  • The site code should be mapped in one of the following ways:
    • by mapping it to {SiteCode} in a separate row in the data mapping table, or
    • by mapping the format of the subject key, as in the example: {CountryCode}-{SiteCode}-{SiteSubjectSeqNo}. Click the +-icon in the IM column to add these mapping details to the subject key mapping.

    The format of the subject key is defined in the Subject Id Generation Settings in the Study Settings in Viedoc Designer. Click here for more information.
  • Viedoc imports the data into existing subjects by matching the complete subject key as a string.
  • Instead of mapping to the subject key, it is also possible to map the subject ID to {SiteCode} and {SiteSubjectSeqNo}. If both the subject key and the site subject sequence number are provided during the import, the site subject sequence number will take precedence.
  • It is possible to add new subjects through the data import, see below for more information.

8 Mapping the visit ID and event date

  • The visit ID should be mapped to {StudyEventDefId}, see image. Note that the mapping is case sensitive!
  • For scheduled events, the date of the visit can be mapped in two different ways (optional):
    • Mapping to {EventDate}
    {EventDate} is used to initiate events if the event (visit) has not been initiated yet. If the event already has been initiated, the Viedoc Import Application imports the data but keeps the existing event date.
    • Mapping to {$THIS.$EVENT.EventDate}
    {$THIS.$EVENT.EventDate} is used to update the event date. If the event already has been initiated, the Viedoc Import Application updates the existing event date with the new event date. Note that for matching the events, it is necessary to map the original event date to {EventDate} as well, so that the system recognizes which event should be updated.

    Data will be imported into scheduled events even if the event date is not given or not matching the initiated event date.
  • For unscheduled and common events, the visit ID should also be mapped to either {EventDate} or {StudyEventRepeatKey}, along with {StudyEventDefId}. The event will then be matched on event date or on event sequence number.

    If the event has been initiated, the Viedoc Import Application checks whether the date in the data file matches with the existing date. If the dates are matching, the data will be imported. If the dates are not matching, the data will not be imported.

    If the event has not been initiated yet, the event date will be imported and/or an event sequence number will be created.
  • Recurring events should be mapped to {StudyEventRepeatKey}, along with {StudyEventDefId}.
  • You can also map data to a certain activity within a visit using the Activity ID. This is useful when the same form is used in two different activities within the same event, for example before and after administration of a drug. The Activity ID should be mapped to {FormRepeatKey}. For more information about mapping data to specific activities, see the example below under Using FormRepeatKey to map activities and repeating forms.

9 Mapping the data

  • The data, for example laboratory results, should be mapped to the correct form and field ID, see image. The mapping of these data is also case sensitive.
  • In the example in the image, the laboratory results of the alanine aminotransferase serum levels are mapped to {$THIS.CC.RES_ALAT}. This is build up as follows:

    $THIS maps the data to the visit as defined earlier in the mapping.

    CC is the ID of the form that the data should be imported into.

    RES_ALAT is the ID of the field in the form that the data should be imported into.
  • You can also specify a scheduled event explicitly in the data mapping. For example, it is possible to map the above data directly to Visit 1 using {V1.CC.RES_ALAT}. In that case, the visit ID does not have to be included in the data file, and, hence, the visit ID does not need to be mapped to {StudyEventDefId}, because the event is already specified in the destination of the data.

10 Using {FormRepeatKey} to map activities and repeating forms

  • The {FormRepeatKey} can be used to map the FormRepeatKey of a form, as well as to which activity the form belongs. This is done as follows:
    • if not mapped, then the data will be mapped to the first activity where the form appears and the FormRepeatKey will be "1".
    • if only the FormRepeatKey is specified (e.g. 2), then the data will be mapped to the specified form instance (e.g. FormRepeatKey = "2") in the first activity where the form appears.
    • if only the ActivityDefId is specified (e.g. V1ACT1), then the data will be mapped to the respective activity (e.g. V1ACT1) and FormRepeatKey will be "1".
    • if both FormRepeatKey and ActivityDefId are specified, in the format {FormRepeatKey}${ActivityDefId} (e.g. 3$V1ACT2) then the data will be mapped to the respective instance of the form (e.g. FormRepeatKey = "3") in the specified activity (e.g. V1ACT2).
      This format is used for repeating forms, i.e when the same form appears multiple times within the same activity.
  • In the example of the image, we map data into the vital signs form VS, that is used in two different activities within visit 1:Activity 1 and Activity 2. In Activity 2, the form is set as repeating.

    The activity column in the data file specifies both the form repeat key (1, 2, 3, 4) and the ActivityDefId (V1ACT1, V2ACT2), separated by $. The activity column is mapped to {FormRepeatKey}. The data highlighted in green will be imported in the third instance of the VS form in Activity 2.
  • The FormRepeatKey attribute in the ODM export contains both the ActivityDefId and the FormRepeatKey, separated with a $, as in the following format:

    {FormRepeatKey}${ActivityDefId}

11 Adding new subjects using data import

  • You can add new subjects through the import of data.
    Note that in the configuration file the tag AllowCreatingSubjects should be set to true, see the Viedoc 4 Data Import Application document for more information.
  • To enable Viedoc to add new subjects, one of the following should be mapped:
    • {SiteCode}, the next available site subject sequence number will then be assigned to the new subject.
    • {SiteCode} and {SiteSubjectSeqNo}, to assign a site subject sequence number to the new subject yourself.
    • {SubjectKey}.
  • If only the subject key is mapped, Viedoc needs to extract the country code, site code and site subject sequence number from the subject ID. It is necessary to map the format used for the subject ID, for example:

    {CountryCode}-{SiteCode}-{SiteSubjectSeqNo}
  • Viedoc can only correctly extract the country code, site code and site subject sequence number within a subject ID if one of the following two requirements are met:

    • The country code, site code and subject sequence number are separated with a separator (any symbol), for example:
    {CountryCode}-{SiteCode}-{SiteSubjectSeqNo}.

    • The exact number of digits in the country code, the site code and the site subject sequence number are specified in the subject ID generation settings in Viedoc Designer.
    For example, if the subject ID generation settings in the study design are set at {CountryCode:00}{SiteCode:00}{SiteSubjectSeqNo:000}, the country code should consist of two digits, the site code should consist of two digits, and the site subject sequence number should consist of three digits.

Was this information helpful?