データインポートのためのデータマッピングを作成する

はじめに

Viedocは、Viedocデータインポートアプリケーションを使用して、Viedocにラボデータなどをインポートするためのサポートをしています。 Viedocデータインポートアプリケーションは、

データマッピングファイルを使用して、データをCDISC ODM形式に変換します。
Viedoc APIを介してデータをViedocに取り込みます。(API)

Viedocデータインポートアプリケーションは、Viedoc Designerのグローバルデザイン設定のデータマッピングからダウンロードできます。

このレッスンでは、Viedocデータインポートアプリケーションを使用してViedocにデータをインポートするためのデータマッピングファイルを作成する方法について説明します。 Viedocデータインポートアプリケーションをダウンロードする方法、およびアプリケーションを実行してデータをインポートする方法の詳細については、Viedocデータインポートアプリケーションをご覧ください。

データマッピングファイルを作成する方法、およびViedocデータインポートアプリケーションを使用してデータをインポートする方法についての説明は、ビデオチュートリアルにもあります。ビデオチュートリアルに移動するには、ここをクリックしてください。

Viedocへのデータのインポートについて

データをインポートするには何が必要か？

Viedocにデータをインポートするには以下が必要です。

Viedocデータインポートアプリケーション
データマッピングファイル
インポートコンフィグファイル
有効なViedocユーザーネームとパスワード、当該試験用のViedoc APIクライアントキー
取り込みデータファイル (CSV形式)

データマッピングファイル

データマッピングファイルは、外部データをViedocのフォーム項目にどのようにマッピングするかを定義するものです。データマッピングファイルは、Viedoc Designerのグローバルデザイン設定で作成することができます。Viedoc内ではデータマッピングはCDISC Defin-XML形式で保存されます。

コンフィグレーションファイル

インポートコンフィグファイルは以下を定義する(必須)xmlファイルで、

データマッピングファイルの場所
インポートしたいデータの場所
Viedoc上どの試験にデータをインポートするか
どのAPIインスタンスにデータをインポートするか
データのインポート時に使用されるログイン資格情報

インポートコンフィグファイルでは以下の定義もオプショナルで可能です。

データインポートによって新規患者を追加するかどうか
データインポートによってイベントを開始させるかどうか
ファイル読み込み時に使用する文字エンコーディング
ファイル解析に使用する区切り文字(デリミタ)ファイル

1つの設定ファイルに、複数試験のインポート設定を含めることができます。

Viedoc API クライアントキー

ViedocAdminで、試験設定下にあるAPI設定にてViedoc APIクライアントキーを作成できます。詳細はViedocデータインポートアプリケーションをご覧ください。

データインポートの手順

Viedocデータインポートアプリケーションを使用したViedocへのデータのインポートは、次の手順になります。

Viedoc Designerでデータマッピングファイルを作成します。
Viedoc AdminでViedoc APIクライアントキーを作成します。
コンフィグレーションファイルを作成します。 (Viedoc上ではありません)
作業フォルダを準備します。
Viedocデータインポートアプリケーションをダウンロードします。
データを作業フォルダにドロップします。
Viedocデータインポートアプリケーションを起動します。

データマッピングファイルについて

データマッピングファイルとは？

データマッピングファイルは、インポートするデータを含むデータファイルの各列を記述し、これらのデータをViedocにインポートする場所を定義します。各試験ごとに、またインポートするデータファイルの種類ごとにデータマッピングファイルを作成する必要があります。

データマッピングファイルの構造

Viedoc Designerのグローバルデザイン設定のデータマッピングウィンドウには、メインフィールドが3つあります。（下の画像参照）

1. データマッピング名: データマッピングの名前（フリーテキスト）

2. ドメイン名: Define-XMLファイルに格納されるドメイン名を指定します。このドメイン名はデータをインポートする際には使用されません。しかし、このドメイン名は、インポートを Viedoc のフォームにリンクするための参照として使用することができます。

3. データマッピングテーブル:　以下2つに分かれています

インポートされたファイル構造: インポートするデータファイルの各列を説明します
Viedoc: Viedocのデータの保存先を記述します

データマッピングファイルの列

データマッピングファイルの列には以下が含まれています。

Column name	Description
#	インポートするデータファイルの列の番号
列名	インポートするデータファイルの列の名称
説明	インポートする特定の列のパラメータの説明（フリーテキスト）
リンク先	データファイル内の別の列で定義されたパラメータにコンテンツをリンクします。これは、 tall-skinny形式のデータをインポートする際に使用します。
IM	Item mapping: テーブルに行を追加して、1つのデータ列をViedocの複数の宛先にマッピングできるようにします。
説明	(Viedoc表現) データをインポートするViedocのアドレス。これにより、データが正しい患者、ビジット、フォーム、フィールドに送られます。
CL	Code list:インポートされたデータ値をViedocの対応するアイテムにマッピングするために使用する辞書を構築するコードのリスト。

マッピングされる変数の概要

以下の表は、マッピング可能な変数の概要を示しています。

変数	マッピングが必要か、不要か？
施設コード	常に必要
サブジェクトキー	既存の患者にデータをインポートするために必須、新しい患者を追加する場合は不要です。
SiteSubjectSeqNo患者の通し番号(施設単位）	患者キーがマッピングされている場合は必須ではありません。既存の患者を一致させるため、または新しい患者を作成するために個別にマッピングできます。
StudySubjectSeqNo患者の通し番号（試験単位）	患者キーがマッピングされている場合は必須ではありません。既存の患者を一致させるため、または新しい患者を作成するために個別にマッピングできます。
StudyEventDefId	データのインポート先のイベントを照合するために必須です。
EventDate	予定外イベントにデータをインポートする場合、EventDateまたはStudyEventRepeatKeyのいずれかが必須、規定イベントはオプショナルです。
StudyEventRepeatKey	予定外イベントにデータをインポートする場合、EventDateまたはStudyEventRepeatKeyのいずれかが必須、規定イベントはオプショナルです。
FormDefId	データのインポート先のフォームを照合するために必須です。
ItemDefId	データのインポート先のアイテムを一致させるために必須です。FormDefIdと組み合わせて1つの文字列にすることができます。
FormRepeatKey	同じフォームが同じイベント内で複数回発生する場合にのみ必須です。

ステップバイステップガイド

データマッピングファイルを作成する

データマッピングファイルを作成するには以下の手順に従ってください。.

1	Viedoc Designerで、データマッピングファイルを作成する試験を選択します。
2	変更をクリックしてグローバルデザイン設定を開きます。
3	データマッピングフィールドの変更アイコンをクリックします。
4	データマッピングを追加をクリックするか、既にマッピングされている場合は変更したいデータマッピングを選択します。
5	データマッピング名とドメイン名を記入します。
6	行を追加をクリックして表に新しい行を追加し、次の情報を記入します。データファイルの最初の列名データファイルの最初の列の説明データファイルの最初の列にあるデータのViedoc内のマッピング先 1つのデータ列をViedocの複数個所に紐づける場合は、IM列の+アイコンをクリックしてレコードを追加します。コードリストを作成する場合は、CL列の+アイコンをクリックしてリストを追加します*。コードリストは、他システムのデータファイルの値をViedocの値に変換する方法を定義します。コードリストは、トールスキニー形式でデータのアドレスを指定するためにも使用されます。
7	データファイルのすべての列がデータマッピングテーブルに記述されるまで、データファイルの次の列で手順6を繰り返します。現在の行のコンテンツを別の行のコンテンツにリンクする場合は、リンク先ドロップダウンメニューからリンク先の行を選択します。これは主にトールスキニー形式のデータに使用されます。リンク先のドロップダウンリストから項目の1つを選択すると、リンクされている項目（行）と同じコードリスト項目を持つ行が自動的に作成されます。リンクされた行は、更新ボタンをクリックして更新できます。
8	保存をクリックして保存をして閉じるでドメインを編集ページを閉じます。
9	閉じるをクリックしてデータマッピングページを閉じます。
10	グローバルデザイン設定ページでデザインを確定するをクリックして変更を確定します。
11	データマッピングフィールドの変更をクリックして概要を開きます。
12	作成したデータマッピングのダウンロードアイコンをクリックします。データマッピングが含まれたxmlファイルがダウンロードされます。
13	xmlファイルをワークフォルダーに保存します。

*コードリストを使用したデータを、1つのフィールドで複数のチェックボックスを有効化できるフォームにマッピングする場合、選択肢ラベルに基づいてではなく、選択肢番号に基づいてのみマッピングすることができます。このため、文字列ではなく値のみをインポートすることができます。コードリストの《列名》には全角文字は使用できません。

患者IDのマッピング

既存の症例は{SubjectKey}を使用して特定します。データマッピングはcase-sensitiveですので大文字/小文字にご注意ください。

以下のいずれかの方法で施設コードが紐づけられている必要があります。

データマッピングテーブル内のどこかで{SiteCode}を設定する、または
[患者ID形式設定]で定義されている形式をデータマッピングテーブル内に設定する（例：{CountryCode}-{SiteCode}-{SiteSubjectSeqNo}）IM列の + アイコンをクリックして、これらのマッピングの詳細をサブジェクトキーマッピングに追加します。

{SubjectKey}の形式はViedoc Designerで、試験設定 > 患者ID形式設定で定義します。詳細は患者ID形式設定をご覧ください。

Viedocは、完全なサブジェクトキーを文字列としてマッチングすることで、既存の患者にデータをインポートします。サブジェクトキーにマッピングする代わりに、患者IDを{SiteCode} または{SiteSubjectSeqNo}にマッピングすることも可能です。インポート時にサブジェクトキーとSiteSubjectSeqNoの両方が提供された場合、SiteSubjectSeqNoが優先されます。

データのインポートを通じて新規患者を追加することが可能です。詳細は以下をご覧ください。

イベントIDおよびイベント日付のマッピング

規定イベントのマッピング

ビジットIDは {StudyEventDefId}にマッピングさせます。以下の画像をご覧ください。データマッピングはcase-sensitiveですので大文字/小文字にご注意ください。

イベント日付は以下二つの方法でマッピングできます。(オプショナル）

{EventDate}に紐づけるイベントが未開始の場合{EventDate}を使用してイベントを開始することができます。開始済イベントの場合は、データインポート時、既存のイベント日付を保持します。
{$THIS.$EVENT.EventDate}に紐づける
イベント日付を更新するのに{$THIS.$EVENT.EventDate}を使用できます。データインポート時、開始済のイベントについてイベント日付を更新します。対象のイベントを特定するために、更新前のイベント日付を{EventDate}と紐づける必要があります。

イベント日付がファイル内で提供されていない場合や、Viedoc 4内に入力された日付と合致しなかった場合でも
データはインポートされます。

予定外および随時観察イベントのマッピング

ビジットIDは以下に紐づけする必要があります。

{StudyEventDefId}と、
{EventDate} または {StudyEventRepeatKey}のいずれか。 その後、イベントはイベント日付またはEvent sequence numberに照合されます。

データマッピングはcase-sensitiveですので大文字/小文字にご注意ください。

データインポート時、開始済のイベントについてはCSVファイル内に記入された日付と既存のイベント日付が合致するかをチェックします。日付が合致する場合はデータがインポートされ、合致しない場合はインポートされません。未開始のイベントについてはイベント日付がインポートされ、Event sequence numberが作成されます。

繰り返しイベントにマッピング

繰り返しイベントの場合は{StudyEventDefId}と共に{StudyEventRepeatKey}を設定する必要があります。

イベント内の特定のアクティビティにマッピング

アクティビティIDを使用することで、イベント内の特定のアクティビティにデータを紐づけることができます。同一フォームが、同一イベント内の異なるアクティビティの中で使用されている場合などに使用されます（例：服薬前後の情報を一イベント内で取得する場合等）。アクティビティIDは{FormRepeatKey}と紐づけられます。詳細は以下、 FormRepeatKeyを使用してアクティビティと繰り返しフォームにマッピングをご参照ください。

データをマッピング

検査結果などのラボデータは、正しいフォームとフィールドIDにマッピングされている必要があります。データマッピングはcase-sensitiveですので大文字/小文字にご注意ください。

上の画像では、アラニンアミノトランスフェラーゼの血清レベルの検査結果が{$THIS.CC.RES_ALAT}にマッピングされています。

$THIS - マッピング時に定義されたビジットにデータをマッピング
CC - データをインポートするフォームのID
RES_ALAT - データをインポートするフォームのフィールドのID

データマッピングで規定イベントを指定することもできます。たとえば、{V1.CC.RES_ALAT}を使用して上記のデータを直接Visit 1にマッピングすることが可能です。その場合、データファイルにビジットIDを含める必要はなく、また、ビジットIDは
データの紐づけ先に既にイベントが指定されているため、{StudyEventDefId}にマッピングする必要はありません。

データをマッピングの編集と削除

ごみ箱のアイコンをクリックすると、テーブルの行を削除できます。

既存のDefine-XMLファイルをインポートまたは編集するには、データマッピングページ右上にあるImport data mappingsをクリックします。インポートするファイルを選択し、開くをクリックします。必要に応じてデータマッピングテーブルを編集し、保存をクリックしてデータマッピングを保存します。

データマッピングページで削除をクリックすると、既存のデータマッピングを削除できます。すでに確定されているデータマッピングを削除することはできません。

Good to know!

FormRepeatKey を使用してアクティビティと繰り返しフォームをマッピング

FormRepeatKeyを使用して以下を指定できます。

同じイベント内の異なるアクティビティで同じフォームが使用されている場合に、どのアクティビティにデータをインポートするか
フォームが繰り返し使用されている場合、データをどのフォームにインポートするか

Form repeat key は{FormRepeatKey}にマッピングされている必要があります。

ODMのForm repeat key属性には ActivityDefID と FormRepeatKey が含まれており、次の形式のように、$で区切ります。{FormRepeatKey}${ActivityDefID}

以下の画像の例では、 visit 1での2つの異なるアクティビティ、Activity 1 とActivity 2 で使用されるバイタルサインフォーム (VS) にデータをマップしています。Activity 2 では、繰り返しフォームが設定されています。

データファイルの activity 列は、フォームの繰り返しキー（1、2、3、4）とActivityDefId（V1ACT1、V2ACT2）の両方を$で区切って指定します。アクティビティ列は{FormRepeatKey}にマップされます。緑マーカーで強調されたデータは、Activity 2のVSフォームの3番目のインスタンスにインポートされます。

データのインポート中にFormRepeatKeyのみが指定され、ActivityDefIdが指定されていない場合、データは、それぞれのフォームが使用される最初のアクティビティにインポートされます。

データインポートで新規患者を追加する

データのインポートによって新しい患者を追加することができます。その場合、設定ファイルのタグAllowCreatingSubjectsをtrueに設定する必要があります。詳細はViedocデータインポートアプリケーションをご覧ください。

新しい患者を追加できるようにするには、次のいずれかがマッピングされている必要があります。

{SiteCode}, 次に利用可能なサイトサブジェクトシーケンス番号が新しい患者に割り当てられます。
{SiteCode} と {SiteSubjectSeqNo}, 自分で新しい患者にサイトサブジェクトシーケンス番号を割り当てます。
{SubjectKey}

サブジェクトキーのみがマッピングされている場合、Viedoc はサブジェクト ID から国コード、サイトコード、サイトサブジェクトシーケンス番号を抽出する必要があります。サブジェクト ID に使用されるフォーマットをマッピングする必要があります。例として、{CountryCode}-{SiteCode}-{SiteSubjectSeqNo}

Viedocは、次の2つの要件のいずれかが満たされた場合にのみ、サブジェクトID内の国コード、サイトコード、およびサイトサブジェクトシーケンス番号を正しく抽出できます。

国コード、サイトコード、サブジェクトシーケンス番号は区切り記号（任意の記号）で区切られます。例として、{CountryCode}-{SiteCode}-{SiteSubjectSeqNo}
国コード、サイトコード、サイト被験者シーケンス番号の正確な桁数は、Viedoc Designer のサブジェクト ID 作成設定で指定します。例えば、試験デザインのサブジェクトID作成設定が{CountryCode}{SiteCode}{SiteSubjectSeqNo:000と（セパレータなし、例 : SE02001)と設定されている場合、国コードとサイトコードに正しい数字がマッピングされるよう、マッピングも{CountryCode:00}{SiteCode:00}{SiteSubjectSeqNo:000}　と設定する必要があります。

特殊なケース

範囲項目

範囲項目にインポートする際二つのケースが考えられます。

範囲が= / < / <= / > / >=の場合、ファイル内の値は例えば >=10 であるべきです。
範囲がInclusive In Between (両端値を含む）の場合は、[ Lower,Upper ] のように、例えば [ 10.2,20.1 ] のように記述します。下限と上限はカンマで区切り、小数点以下はピリオドで指定することに注意してください。

注意! Inclusive In Between 値 (両端値を含む）をインポートする際ファイル内の区切り文字がコンマの場合、範囲値を引用符で囲む必要があります。

チェックボックス

チェックボックスにインポートする場合は、「1,3,5」のようにカンマで区切ってコード値を指定する必要があります。

注意! 　ファイル内の区切り文字がコンマの場合は、値を引用符で囲む必要があります。

部分的な日付

日付の一部を日付フィールドにインポートする場合、既知の日付の部分のみを追加する必要があります。たとえば、日がわからない場合は、年と月、2020-01を追加します。または、月がわからない場合は、2020 を追加してください。