导入第三方数据

CDB 允许从第三方系统导入数据，以便在 CDB Workbench 应用程序中进行清理和报告。这旨在用于导入存在于 Vault EDC 中受试者病例手册之外的受试者数据，例如，从 IRT 系统导入有关受试者的数据。

准备要导入的数据

可以将数据作为一系列 CSV 文件导入到 CDB Vault 的 FTP 服务器。要导入数据，首先需要创建列出临床数据的 CSV 文件，以及描述这些数据和 CDB 应该如何处理这些数据的清单文件（.json）。然后，创建一个包含所有这些文件的 ZIP 包（.zip），以便导入到 CDB 中。

数据 CSV 文件

为研究中的每个独立于 EDC 的数据收集表单创建一个 CSV 文件。对于每个 CSV 文件，必须提供四（4）个必需列，然后为每个执行数据条目提供一列。对于这四个必需列，可以任意命名，只要在每个 CSV 的清单文件中定义这些名称即可。请注意，这些列名称区分大小写，必须与清单文件中提供的值完全匹配。

除了“研究、研究中心、受试者、事件和序列”列之外，CDB 将每一列都视为一个数据条目，并会按此方式导入。每个列表对条目列的数量限制为 410 列。

以下是 CSV 文件示例：

在此示例中，有以下列映射：

• 研究：STUDY_ID
• 研究中心：SITE
• 受试者：SUBJECT_ID
• 事件：VISIT

INITIALS、DOB、GENDER 和 RACE 列都是数据条目。

清单文件

清单文件为 CDB 提供研究和源，列出 ZIP 中的文件，并为每个文件列出映射到所需数据点的列。

源是一个自定义值，允许标识数据包的内容。此值存储在 Workbench 的源（Source）字段中，因此可以通过 CQL 在 Workbench 中标识此数据包中的数据。源（Source）值在研究中必须是唯一的。

为研究提供研究名称（study__v）记录。为研究提供研究名称（study__v）记录。如果研究名称包含空格字符，则必须在清单文件中使用带有空格的值，但在数据文件中必须将空格替换为下划线（_）。

为源指定数据源。Vault 将此源应用于所有导入数据。然后，作为数组，列出每个 CSV 文件，包括其文件名（带扩展名）及其列映射，作为“数据”的值。

可以选择在导入文件中包含有关每个数据条目的配置元数据。请参见下面的详细信息。

示例清单：单表单

以下是 Deetoza 研究的示例清单文件，该文件从包含调查表单的 eCOA 导入一个数据包：

{ "study": "Deetoza", "source": "eCOA", "data": [ { "filename": "Survey.csv", "study": "protocol_id", "site": "site_id", "subject": "patient", "event": "visit_name" } ] } 

示例清单：多表单

以下是 Deetoza 研究的示例清单文件，该文件从实验室供应商处导入一个数据包，其中包含生化和血液学检查表单：

{ "study": "Deetoza", "source": "lab", "data": [ { "filename": "Chemistry.csv", "study": "STUDY_ID", "site": "SITE_ID", "subject": "SUBJECT_ID", "event": "VISIT", "formsequence": "LAB_SEQ" }, { "filename": "Hematology.csv", "study": "STUDY_ID", "site": "SITE_ID", "subject": "SUBJECT_ID", "event": "VISIT", "formsequence": "LAB_SEQ" } ] } 

还可以使用行 ID 映射，并使用单个 CSV 文件导入生化和血液学检查实验室数据。在该 CSV 文件中，可以使用"实验室检测集"列来指示该行的生化或血液学检查结果。

{ "study": "Deetoza", "source": "lab", "data": [ { "filename": "Labs.csv", "study": "STUDY_ID", "site": "SITE_ID", "subject": "SUBJECT_ID", "event": "VISIT", "rowid": ["LAB_TEST_SET", "LAB_TEST_SEQ"] } ] } 

可选：事件匹配

默认情况下，Workbench 将表单的 CSV 文件中的事件与 Vault EDC 中匹配的事件定义记录的名称进行匹配。还可以选择让 Workbench 根据事件定义的外部 ID 进行事件匹配。还可以在清单文件中定义一个默认事件，并将所有行自动分配给该事件。如果数据是在 EDC 计划事件之外收集的，则可以选择不映射到任何 EDC 事件，并让 Workbench 根据需要创建事件以匹配导入包中的事件。

如果事件位于重复事件组内，Workbench 会使用事件定义的外部 ID，并在其后附加序列号以进行匹配。文件中每个唯一事件的序列号会递增。如果一个事件在多个事件组中重复使用，则不会被视为重复。在这种情况下，Workbench 会将其匹配到 EDC 计划中的第一个匹配事件。

默认行为

如果在清单文件中未包含任何事件匹配配置，则适用以下默认值：

• Workbench 使用事件定义的名称进行匹配。
• Workbench 尝试与现有 EDC 事件匹配。如果 EDC 中没有匹配的事件，Workbench 会创建一个新事件。

这种默认行为相当于以下清单配置：

{ "study": "Deetoza", "source": "Labs", "edc_matching": { "event": { "target": ["name"], "generate": true } } } 

按名称匹配（默认）

如果在清单文件中未包含 edc_matching，Workbench 将自动使用事件定义的名称进行匹配。还可以在清单文件中指定基于名称的批处理。

{ "study": "Deetoza", "source": "Labs", "edc_matching": { "event": { "target": ["name"] } } } 

按外部 ID 匹配

要根据事件定义的外部 ID（以前称为 OID）进行匹配，必须包含 edc_matching，并将事件目标设置为 external_id。请参见以下示例摘录：

{ "study": "Deetoza", "source": "Labs", "edc_matching": { "event": { "target": ["external_id"] } } } 

设置默认事件

可以选择将事件设为清单文件中的默认事件，而不在 CSV 中列出事件。然后，Workbench 会自动将该 CSV 文件中的所有行分配给该事件。这由 default 键位控制。使用事件定义的名称作为 default.可以为特定数据文件设置默认值，或在数据包级别设置默认值。

示例：数据包级别默认事件

{ "study": "Deetoza", "source": "lab", "edc_matching": { "event": { "default": "treatment_visit" } }, "data": [ { "filename": "Labs.csv", "study": "STUDY_ID", "site": "SITE_ID", "subject": "SUBJECT_ID", "event": "VISIT", "rowid": ["LAB_TEST_SET", "LAB_TEST_SEQ"] } ] } 

示例：文件包级别默认事件

{ "study": "Deetoza", "source": "Labs", "edc_matching": { "event": { "default": "treatment_visit", } } } 

处理未匹配事件

默认情况下，如果 Workbench 无法按名称或外部 ID 将事件与 EDC 中的事件匹配，Workbench 会为特定于源的任何非 EDC 事件创建新事件。这些新事件将成为整个 Workbench 标题事件记录的一部分。（可通过 @HDR.Event 访问）。这由 generate 键位控制。默认行为的清单配置为 generate: true。如果数据是在 EDC 事件计划之外收集的，可以通过将 generate 设置为 false 来选择不与任何 EDC 事件匹配。如果将 generate 设置为 false，Workbench 将不会创建新的事件定义。相反，对于没有匹配 EDC 事件的任何行，导入都将失败。

示例：按外部 ID 匹配并忽略未匹配事件

{ "study": "Deetoza", "source": "Labs", "edc_matching": { "event": { "target": ["external_id"], "generate": false } } } 

如果数据完全在 EDC 计划之外收集，可以选择让 Workbench 为每个事件创建新事件，而无需尝试与 EDC 事件匹配。为此，请将 event 设置为 false，如以下示例所示：

{ "study": "Deetoza", "source": "Labs", "edc_matching": { "event": false } } 

可选：表单和条目组映射&

可以选择将 CSV 文件中的行映射到不同的表单和条目组，包括定义 Workbench 如何解释数据集中的重复表单和条目组。这使得 Workbench 能够将单个 CSV 转换为多个表单和条目组，而不是单个表单和单个条目组。

例如，实验室表单可以包含多个条目组 - 每个实验室检测类别一个条目组。可以使用 itemgroup 列来指示行中的数据条目所属条目组。Workbench 将行中所有未映射的列视为条目。Workbench 将这些条目导入到行指定的条目组内。可以在条目配置中为这些列指定额外的元数据。请参见下面的详细信息。

使用下表了解 Workbench 将如何通过不同表单和条目组配置场景来处理数据：

示例清单：多表单

在以下示例中，“Labs.csv”文件包含多个表单。这些表单在“Labs.csv”文件的表单列中被标识。

{ "study": "Deetoza", "source": "lab", "data": [ { "filename": "Labs.csv", "study": "protocol_id", "site": "site_id", "subject": "subject_id", "event": "visit", "form": "form" } ] } 

示例清单：多个条目组

在以下示例清单文件中，实验室表单具有多个条目组。这些表单在“Labs.csv”文件的lab_category列中被标识。

{ "study": "Deetoza", "source": "lab", "data": [ { "filename": "Labs.csv", "study": "protocol_id", "site": "site_id", "subject": "subject_id", "event": "visit", "item_group": "lab_category" } ] } 

可选：条目配置

在清单文件中，可以包含条目元数据，以告知 CDB Workbench 如何处理数据条目。可以为每个条目指定数据类型，并根据数据类型选择指定其他属性。

当省略条目配置时，CDB Workbench 会将所有条目视为文本。

简单配置与高级配置

条目“config”对象有两种配置格式，简单和高级。对于简单配置，只需指定条目的数据类型。条目的属性使用默认值。对于高级配置，需指定数据类型和属性。

"items" { "Weight": "float" }

"items" { "Weight": { "type": "float", "precision": 2 } }

按数据类型划分的可用属性

每种数据类型有不同的配置属性可用。

"items": { "Subject_Initials": { "type": "text", "length": 3 } }

"items": { "Actual_Dosage": { "type": "integer", "min": 1, "max": 1000 } }

"items": { "Weight": { "type": "float", "length": 4, "precision": 1, "min": 80, "max": 400 } }

"items": { "Start_Date": { "type": "date", "format": "yyyy-MM-dd" } }

"items": { "End_DateTime": { "type": "datetime", "format": "MM-dd-yyyy HH:mm" } }

"items": { "Time_Collected": { "type": "time", "format": "HH:mm:ss" } }

"items": { "Exam_Performed": "boolean" }

支持的日期和时间格式模式&

下面列出的格式模式可用于日期、日期时间和时间条目。日期时间条目合并日期和时间模式，例如“yy-MM-dd HH:mm””。如果对日期使用时间格式模式（反之亦然），导入将失败并显示错误（D-012）。

示例数据包：单个表单、条目元数据

以下是来自 Verteo Pharma 随机化供应商的示例导入包，其中包含带有条目元数据的随机化表单：

manifest.json：

{ "study": "Cholecap", "source": "IRT", "data": [{ "filename": "Randomization.csv", "study": "protocol_id", "site": "site_id", "subject": "patient", "event": "visit_name", "items": { "randomization_number": { "type": "integer", "length": "14" }, "date_of_randomization": { "type": "date", "format": "yyyy-MM-dd" } } }] } 

Randomization.csv：

严格导入

清单文件中的严格导入参数允许将数据摄取限制为仅清单中定义的条目，而不是数据 CSV 文件中的所有条目列。可以将此选项应用于整个数据包或单个文件。文件级设置会覆盖数据包级设置。

“strict_import” 参数可以设置为真（true）或假（false）。将此项设置为真（true）即启用严格导入。

可选：限制数据（盲态）

可以在条目、行、列表数据文件和源级别限制（设盲）数据，以隐藏无权访问受限数据的用户数据。例如，研究可能只为使用研究药物的受试者订购某些实验室检测。知道受试者已进行的实验室检测将揭示其身份。可以限制此信息，以防止盲态用户识别这些受试者。

"items": { "itemname": { "type": "text", "blinded": true } }

{ "study": "Deetoza", "source": "Labs" { ..."event": "visit", "row_blinded": "column_id" } }

{ "study": "Deetoza", "source": "Labs" { "filename": "chempanel.csv", "blinded": true, ...} }

{ "study": "Deetoza", "source": "Labs", "blinded": true ...}

对于有权访问受限数据的用户（通常是首席数据管理员），受限数据的行为方式与不受限数据相同。对于盲态用户（没有受限数据访问权限的用户），以下行为规则适用于任何导入的受限数据：

• 如果条目（列）受限：
  • CQL 投影不会返回受限条目的列。
  • CQL 投影不会返回引用受限条目的任何衍生列。
  • 如果盲态用户在 CQL 语句中引用了受限条目，CQL 仍然不会返回该列。
  • SHOW 和 DESCRIBE 不会返回受限条目。
• 如果行受限：
  • 结果集不会返回来自表单或条目组的任何行。
• 如果列表文件（csv）受限：
  • 列表中默认包含 @HDR 列，但不包含任何条目列。
• 如果源（数据包）受限：
  • CQL 不会在任何列表中返回来自受限源的任何条目或列结果。
  • CDB 将源中的所有条目定义、条目组定义和表单定义标记为受限。
  • 将所有数据行都标记为受限。
  • 默认的 @HDR 列仍将显示在核心列表中。

ZIP 包

创建清单文件和 CSV 文件之后，将这些文件压缩为 ZIP 文件。不要在压缩之前将这些文件放入文件夹中。可以随意命名这个 ZIP 文件夹。但建议使用唯一标识符对其进行命名，例如“研究名称_源_日期时间.zip”。不得在 ZIP 文件夹中包含任何文件夹。所有 CSV 文件和清单文件必须位于同一级别。

访问 Vault 的 FTP 服务器

域中的每个 Vault 有其自己的 FTP 暂存服务器。FTP 服务器是上传到 Vault 或从 Vault 提取的文件的临时存储区域。

服务器 URL

每个暂存服务器的 URL 与相应的 Vault 相同，例如，veepharm.veevavault.com。

如何访问 FTP 服务器

可以使用收藏的 FTP 客户端或通过命令行访问暂存服务器。

对 FTP 客户端使用以下设置：

• 方案：FTP（文件传输方案）
• 加密：需要显式 FTP over TLS（FTPS）。这是一项安全要求。网络基础设施必须支持 FTPS 流量。
• 端口：通常不需要添加，默认为端口 21。
• 主机：{DNS}.veevavault.com。例如：“veepharm”是 veepharm.veevavault.com 中的 DNS。
• 用户：{DNS}.veevavault.com+{用户名}。使用登录时的用户名。例如：veepharm.veevavault.com+tchung@veepharm.com。
• 密码：在此 Vault 中的登录密码。与标准登录使用的密码相同。
• 登录类型：正常
• 传输文件类型（Transfer File Type）：以二进制形式传输文件

FTP 目录结构

在用户目录中，有一个“workbench”目录。这是上传第三方数据的地方。CDB 会自动识别放置在此处的任何文件。

CDB 会将任何成功导入的文件移动到“workbench/_processed”中。请参见下面的详细信息。

导入数据

要导入数据，请使用选择的 FTP 客户端将 ZIP 文件上传到 FTP 存储服务器的“Workbench”目录。将 ZIP 上传到 FTP 存储服务器之后，CDB 会导入 ZIP 并转换数据。

导入完成后，Workbench 会向你及任何其他订阅该源的用户发送电子邮件通知。如果重新处理包的结果与之前的加载有所变化，Workbench 也将向你和订阅该源的用户发送通知。

成功导入

在成功导入之后：

• CDB 创建所有定义记录以及它们之间的关系。
• CDB 自动将所有导入记录的源字段设置为在清单中提供的值，以唯一标识数据源。（从 Vault EDC 导入的任何表单的该值默认设置为“EDC”。）
• CDB 为导入包中的每个唯一表单创建一个核心列表。请参见下面的详细信息。
• CDB 将导入的 ZIP 文件从“workbench”移动到“workbench/_processed/{study}/{source}”（如果导入失败，ZIP 文件将保留在“workbench”目录的根目录中。CDB 还会将导入的日期和时间附加到文件名中。

现在可以在 Workbench 中查看你的列表。在当前版本中，Workbench 不会立即显示你的新列表。首先，导航到研究的列表（Listings）页面，单击打开另一个核心列表，然后返回列表页面。此时，你的新数据列表将显示在列表中。现在可以单击其中一个列表的名称（Name）打开它。

导入失败

导入失败时：

• CDB 会将尝试导入的日期和时间附加到 ZIP 文件的文件名中，但 ZIP 文件仍保留在“workbench”目录的根目录中。
• CDB 会创建一个错误日志（“<导入日期时间>_<数据包名称>_错误.csv”）。

请参阅此可能的错误列表以及如何解决这些错误。

审查和批准更改的导入&

为了确保导入到 CDB 的数据不会改变已批准的格式和结构，CDB 会检测每个第三方源从一次加载到下一次加载的数据包配置中的任何更改。

如果系统检测到数据包、文件或盲态级别的配置更改，或者 CSV 文件结构发生更改，CDB 将暂停导入过程。数据包不会被处理，并进入已暂停（Paused）状态，直到具有批准权限的用户批准或拒绝数据包。如果用户批准了数据包，CDB 会记录批准原因并导入数据包。数据包获得批准后，CDB 会通过电子邮件通知订阅批准更改的用户。CDB 会在所有关联列表和视图上显示更改指示器。用户可以关闭此指示器，并下载任何列表或视图的表单更改日志。如果用户拒绝数据包，CDB 会记录拒绝原因，将数据包标记为被拒绝（Rejected），并将其分配为未导入（Not Imported）状态。CDB 然后会恢复到该源上最后成功导入的数据包。

当数据包处于已暂停状态时，相同源的所有其他已上传数据包将进入队列，等待暂停的数据包获得批准或被拒绝。暂停的数据包获得批准或被拒绝后，CDB 就会跳到最后一个排队的数据包进行处理。队列中最后一个已暂停的数据包和最后一个数据包之间的任何数据包将不会被处理。例如，如果“数据包 1”已上传并暂停，则上传数据包 2-5，而“数据包 1”仍处于暂停状态，在“数据包 1”获得批准或被拒绝后，CDB 将跳至“数据包 5”，而不处理数据包 2-4。

对于新源的第一个上传数据包，CDB 会自动应用已暂停状态，用户必须先批准或拒绝第一个数据包，然后系统中才会显示来自该源的任何数据。

对于需要批准的数据包，Workbench 现在有一个数据包详细信息（Package Detail）面板，其中包含差异（Differences）和关联对象（Associated Objects）选项卡。差异选项卡显示当前数据包和先前数据包之间清单的更改。用户可以查看他们批准的更改的先前和当前值。关联对象选项卡显示数据包中的更改可能影响的导出定义、列表和视图。

批准或拒绝导入数据包需要拥有批准导入权限，默认情况下，该权限分配给标准 CDMS 超级用户（CDMS Super User）和 CDMS 首席数据管理员（CDMS Lead Data Manager）研究角色。

批准导入

要批准导入，请执行以下操作：

1. 导航到研究的导出>数据包。
2. 按待批准项筛选导入数据列表。

3. 从数据包菜单（）中，选择查看数据包详细信息（View Package Details）。

4. 在数据包详细信息（Package Details）面板中，单击差异（Differences）显示更改。
5. 查看更改。
6. 单击批准数据包（Approve Package）。
7. 可选：输入原因（Reason）。
8. 单击批准。

数据包已获得批准，现在将进入队列进行处理。

拒绝导入

要拒绝导入，请执行以下操作：

1. 导航到研究的导出>数据包。
2. 按待批准项筛选导入数据列表。

3. 从数据包菜单（）中，选择查看数据包详细信息（View Package Details）。

4. 在数据包详细信息（Package Details）面板中，单击差异（Differences）显示更改。
5. 查看更改。
6. 单击拒绝数据包（Reject Package）。
7. 可选：输入原因（Reason）。
8. 单击拒绝。
9. 在拒绝数据包（Reject Package）确认对话框中，单击确认（Confirm）。

查看关联对象

可以从数据包详细信息（Package Details）面板的关联对象（Associated Objects）选项卡查看导入数据包的关联对象。该选项卡列出了数据包中的更改可能影响的导出定义、列表和视图。

要访问该选项卡，请打开数据包详细信息（Package Details）面板，然后单击以打开关联对象（Associated Objects）选项卡。

Workbench 在每个已更改表单的表单标签上显示一个更改图标（橙色圆圈）徽章。

对于在清单文件的“表单（form）”属性中映射的任何文件，关联对象选项卡不会显示该导入文件中可能受到影响的任何对象。

查看导入状态

可以从导入（Import）>数据包（Packages）中检查导入数据包的状态。此页面列出了从 Vault EDC 和第三方工具导入的每个数据包的状态。还可以从此页面下载导入数据包和问题日志（错误和警告）。

没有“受限数据访问权限”的用户可以下载导入包日志，但无法下载数据文件。具有受限数据访问权限的用户可以下载包含盲态数据的数据包。

每次将数据包导入 Workbench 时，Workbench 都会自动重新处理所有其他源的最新数据包。例如，当夜间 Workbench 导出 EDC 作业运行并导入到工作台中时，Workbench 也会重新处理最新的实验室数据和成像数据包。对于来自同一源的早期数据包，Workbench 会将其标记为已由最新数据包替换。

可以使用导入状态筛选器轻松筛选列表，仅显示已完成或失败的导入。单击错误（Error）仅显示失败的导入，或单击完成（Complete）以显示已完成的导入。

Workbench 导入状态

当导入数据包能够导入且仅带警告时，Workbench 会以橙色突出显示状态，以指示存在警告。导入完成后，可以下载问题日志以查看警告。

下载导出包

要下载导入包，请执行以下操作：

1. 导航到导入> 数据包。
2. 在列表中找到导入数据包。

3. 单击数据包链接。

4. 从 ZIP 文件夹中提取文件，并在选择的工具中进行查看。

下载日志

可以下载任何导入操作的导入日志（CSV）和失败导入操作的问题日志（CSV）。导入日志列出了有关导入作业和摄取到 Workbench 的数据的详细信息。

导入日志列出了以下信息：

• 转换开始时间
• 转换完成时间
• 转换持续时间
• 导入开始时间
• 导入完成时间
• 导入持续时间

要下载导入日志，请执行以下操作：

1. 导航到导入> 数据包。
2. 在列表中找到导入数据包。
3. 从数据包（）菜单中，选择查看数据包详细信息（View Package Details）。
4. 在数据包详细信息（Package Details）面板中，单击问题（Issues）。
5. 可选：在问题（Issues）选项卡中，单击下载（Download）（）以下载问题日志的 CSV。

问题日志

问题日志列出了 Workbench 在导入数据包时遇到的所有错误和警告。在此处查看可能的错误和警告列表。

要查看问题日志，请执行以下操作：

1. 导航到导入> 数据包。
2. 在列表中找到导入数据包。
3. 从数据包（）菜单中，选择查看数据包详细信息（View Package Details）。
4. 在数据包详细信息（Package Details）面板中，单击问题（Issues）。
5. 可选：在问题日志（Issue Log）面板中，单击下载（）以下载日志的 CSV。

要下载问题日志，而不先在应用程序中进行查看，请执行以下操作：

1. 导航到导入> 数据包。
2. 在列表中找到导入数据包。
3. 从数据包（）菜单中，选择下载问题日志（Download Issue Log）。

查看导入的数据

上传后，Workbench 会为导入包中的每个唯一文件创建一个表单。Workbench 会自动为研究中的每个唯一表单生成核心列表，无论该表单来自 Vault EDC 还是从第三方系统导入。

这些核心列表的默认 CQL 查询为：

SELECT @HDR, * from source.filename 

在上述实验室导入示例中，CDB 使用以下查询创建两个核心列表：生化和血液学（每个 CSV 文件一个）：

SELECT @HDR, * from labs.Chemistry 

SELECT @HDR, * from labs.Hematology 

定义

CDB 为每个 CSV 文件创建一个表单定义，以在 CDB Workbench 应用程序中将导入的数据定义为“表单”。这些记录使用 CSV 文件名（不带扩展名）作为名称，例如，“hematology”。CDB 还会创建一个条目组定义，以便在表单中将数据条目分组在一起。CDB 通过在 CSV 文件名（不带扩展名）前加上“ig_”来命名，例如“ig_hematology”。

这两个定义在列表中显示为一列（form_name 和 ig_name）。可以编辑列表的 CQL 查询以隐藏这些列。