研究形式 API に関するヒントとベストプラクティス

このページでは、スタディファイル形式 (SFF) API を使用するためのヒントとベストプラクティスを紹介します。

プログラム上の消費を使用

SFF API は、手動でファイルを読み込むのではなく、プログラムでアクセスするように設計されています。SFF パッケージにあるマニフェストファイルは、各列の CSV ファイルとメタデータを整理し、各研究データセクションは独自のブロックを持ちます。

スタディデザインセクションは、マニフェストファイル内で個別に構成されています。各アイテムは CSV ファイルの列であるため、アイテム定義データは臨床データセクションに含まれます。マニフェストは、SFF のメタデータおよびスキーマの信頼できるソースとして扱う必要があります。

列の見出し

また、SFF の列の見出しは機械が読みとれるように設計されています。JSON 形式の属性は、特定の順序であることが保証されていないため、プログラムで列のパースを行うことが重要です。臨床データセクションの itemgroups 配列は唯一の例外です。 この配列によって、アイテムグループ内に各アイテム定義が表示される順序が維持されます。これにより、複数のアイテムグループ定義間で同じアイテム定義が使用されるのを防ぐことができます。

効率的に変更を追跡

SFF の各ファイルには 列 ID があり、これは各行の一意識別子として機能します。この列を使用して、あらゆる行レベルの変更を追跡します。

• 各変更を UPSERT として扱う: インクリメンタル SFF ファイルに行が表示された場合、その行に追加または変更が加えられたことを示します。
• DELETES CSV ファイルは、最新の変更で削除された行をリストアップします。

参照データのマッピング

SFF の完全なパッケージには以下の 2 つの CSV ファイルが含まれています: LABEL および OVERRIDE LABELS。 この 2 種類のファイルは、Veeva EDC で設定されたLABEL、DISPLAY OVERRIDE LABELS に追加データを提供します。

LABELS ファイル

LABELS CSV ファイルで、TYPE 列を使用してラベルのカテゴリーを識別し、オブジェクトの元の NAME にマッピングします。

例えば、TYPE が 「EVENT」の場合、これはイベント定義ラベル を参照します。 イベント定義名 は、SFF ファイル内のEVENT NAME 列です。 したがって、LABELS ファイルは、イベント定義名とイベント定義ラベルのマッピングに使用することができます。

LABELS ファイルの上書き

EDC Studio で特定のオブジェクト関係に対して設定されている場合、OVERRIDE LABELS ファイルを使用して DISPLAY OVERRIDE LABELS を特定します。

[OVERRIDE LABELS] には 5 つのタイプがあり、それぞれが研究定義オブジェクトにリンクされています:

• 事象グループ
• 事象
• フォーム
• 項目グループ
• 項目

SOURCE DEFINITION 列は、ソース定義名を TARGET DEFINITION 列の対応するターゲット定義名にマッピングします。

例:

SOURCE DEFINITION の値は「form_A」で、SOURCE LABEL TYPE は「form」です。 TARGET DEFINITION 名は 「ig_A」で、TARGET LABEL TYPE は「itemgroup」です。

これは、「ig_A」というアイテムグループ定義は、「form_A」というフォーム定義に属し、その値がTARGET OVERRIDE LABEL 列に存在する DISPLAY OVERRIDE LABEL が設定されていることを意味します。

作成済み日付の活用

ファイル名には、インクリメント抽出の場合は 15 分ごと、完全抽出の場合は 24 時間ごとで、定義された各インクリメントの公開時間が含まれます。SFF の ZIP パッケージは、API が返す created_date の順番で利用するのがベストプラクティスです。created_date を使用すると、特にインクリメンタル SFF 消費の場合、下流のシステムに変更を適用する順序を理解し、同期を保つのに役立ちます。例えば、created_date は UTC の 00:30 でも、公開時間は 00:45 を示す場合があります。これは、システムが 00:30 から 00:45 までの時間間隔を取り込んでいるためです。ファイル名の詳細についての詳細を確認してください。

セットアップとリフレッシュのための SFF フルパッケージを取得

初めて有効化する時、SFF フルパッケージを取得する必要があります。増分 SFF も有効化されている場合、サードパーティーのデータが必要でない限り、最初はフルパッケージを取得するだけです。サードパーティのデータはフルパッケージの場合にのみ利用可能です。 データの同期が取れなくなり、完全なリフレッシュが必要になった場合は、再度フルパッケージを取得することができます。

推奨されるファイル取り込み方法

これらのシナリオにおける SFF パッケージの取り込みには、以下の方法が推奨されます: 初回の有効化、研究デザインの変更、システムのリセット、およびサードパーティデータの消費。

初回の有効化

初回に SFF 有効化するには、午後 12 時 (UTC) にフルパッケージを取得します。 これには UTC 午前 6 時現在のデータが含まれています。 増分更新を使用している場合は、SFF の初回有効化後、午後 12 時 15 分 (UTC) に公開された増分パッケージをダウンロードしてください。 増分パッケージは、継続的なデータ更新のために、午後 12 時 15 分 (UTC) 以降に生成され、利用可能になります。

設計変更とフル抽出が必須

EDC スタディデザインを変更して CDB に取り込むと、API はfull_required をフル抽出と増分抽出の両方のレスポンスで「True」に設定し、フル抽出が必要であることを示します。 これにより、すべてのデータが最新のスタディデザインを反映するようになります。

full_required が「True」に設定されている次の完全抽出を実行すると、そのフル抽出の created_date 以降のすべての変更が次の増分抽出に含まれるようになります。 この created_date はUTC 午前 6 時頃で、パッケージは UTC 午後 12 時頃に公開されます。

SFF とスタディデザインの変更についての詳細を確認してください。

システムリセット

ターゲットシステムに問題が発生し、リセットする必要がある場合は、created_date に基づいて、最新公開のフル抽出を摂取してください。 その後、created_date に基づいて生成された増分抽出を使用します。

サードパーティデータの消費

サードパーティまたは Veeva 以外の EDC データはフルパッケージでのみ利用可能なため、システムで必要な再処理の数量を減らすことが推奨されます。

以下を参照してシステムの再処理を削減します:

• フルパッケージを消費しますが、臨床フォームデータを消費する際は EDC ソースデータを無視してください。EDC ソースは、マニフェストファイルの臨床データセクションまたはブロックで特定できます。
• EDC データを含むオペレーショナルデータファイルまたは参照データファイルは、フル抽出の作成から公開までの間に変更されている可能性があります。 したがって、フル抽出の created_date からフル抽出が公開されるまでの間に適用されたすべての増分更新を再適用する必要があります。これには、以下のすべてのシステムファイルが含まれます: クエリ、クエリメッセージ、ローカルラボコードリスト、ローカルラボユニット、および削除。