导入引用数据

CDB 允许通过参考对象导入非临床数据。参考对象是一种特定类型的数据集，可以与临床数据一起导入到 CDB 中，用于清理和导出目的。它们与表单类似，因为它们可以包含有限的条目集，但在与其他标题和表单数据的关系上有所不同。表单与研究、研究中心和事件有预定义的关系，但在导入过程中必须定义参考对象与标题和表单数据之间的关系。在将参考对象中的数据导入 CDB 之后，只要其相关数据包含在选择中，就可以像使用 CQL 中的任何其他表单一样使用它。

可用性：临床数据库（CDB）仅对 CDB 许可证持有者提供。请联系 Veeva 服务代表了解详细信息。

先决条件

配置

在将数据导入 CDB 之前，组织必须执行以下任务：

所需权限

默认情况下，具有 CDMS 首席数据管理员（CDMS Lead Data Manager）标准研究角色的用户可以执行下述操作。如果贵组织使用自定义角色，则你的角色必须授予以下权限：

类型 权限标签 控制
“标准”选项卡 工作台选项卡

能够通过工作台（Workbench）选项卡访问和使用 Data Workbench 应用程序
功能权限 查看导入

能够访问“导入（Import）”页面
功能权限 API 访问权限

能够访问和使用 Vault CDMS API。（使用 CDB 也需要此权限。）
功能权限 批准导入

能够批准或拒绝包含配置更改的导入包
功能权限 下载导入包

能够下载导入包

如果您的“研究”包含受限数据，您必须具有“受限数据访问（Restricted Data Access）”权限才能查看该数据。

了解有关“研究角色”的更多信息。

与临床数据相关

可以为参考对象定义键，以将其与临床数据相关联。这些键是参考对象中与其他表单或标题中的条目相关联的条目。只能将参考数据与单个表单或标题相关联。键的数据类型必须与相关条目的数据类型匹配。例如，如果参考对象中的键的数据类型是 INT（整数），则表单上的相关条目也必须使用 INT。

一个参考对象最多可以有四（4）个键。

键或键的组合在数据集中必须是唯一的。因此，参考对象不能重复。

参考对象没有像表单和标题那样的属性，例如名称或创建日期。因此，不能使用 @Form 或 @ItemGroup。

参考对象可以与标题数据（@HDR）连接。无需在 CQL 语句中指定此连接，因为 CQL 已经知晓。但是，如果在选择子句中将参考对象与表单一起使用，则参考对象必须至少与选择中的一个表单相关联。

参考对象始终作为左外连接与其源数据连接。

无法使用高级连接将参考数据与其他数据连接。

准备要导入的源数据

与临床数据不同，参考数据 CSV 文件没有任何列要求。每个数据条目包含一列。CDB 将列标题用作条目的名称。

与临床数据导入类似，CDB 使用 CSV 的文件名来命名参考对象。

创建参考清单文件

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

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

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

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

可以在 reference_data 中包含多个条目。每个条目表示不同的参考数据表。

要将参考对象与标题（@HDR）相关联，请对 related_form 使用 @HDR，对 related_item 使用标题属性。

参考清单文件名：将此文件另存为“reference_manifest.json”。请注意，Workbench 仅接受具有此确切文件名（区分大小写）和扩展名的参考清单文件。

"reference_data": [ { "filename": "MedDRA.csv", "reference_object_name": "MedDRA_Query_List", "related": [ { "related_form": "AE", "related_itemgroup": "ae_itemgroup", "related_item": "AETERM", "related_item_function": { "name": "CODEDCODE", "argument" : ["LLTCD"] } "related_key": "AELLTCD" }, ], "items": { "LIST_CODE": "text", "LIST_ID": "integer", "LIST_NAME": "text", "LLT_CODE": "integer", "LLT_NAME": "text", "LANG": "text", "AELLTCD": "integer" } } ]

在此示例中，MedDRA.csv（文件名）表示包含参考数据的 CSV 文件。属性 reference_object_name 是 CDB 中参考数据表的名称。属性 reference_object_name 是可选的。省略时，CDB 中参考数据表的名称默认为文件名的值。

参考数据具有以下字段：LIST_CODE、LIST_ID、LIST_NAME、LLT_CODE、LLT_NAME、LANG 和 AELLTCD。

参考数据中的条目 AELLTCD（related_key）是键。表单 AE 中的 related_item 是条目 AETERM 的已编码值。为了使用 AETERM 的 CODEDCODE 函数，定义了一个名为 related_item_function 的新属性。related_item_function 定义了要应用于 related_item 的函数名称和参数。

related_item_function 需要两（2）个属性：

  • name：CQL 函数的名称。
  • argument：传递给函数的参数数组（如 name 属性所定义）。

AELLTCD 的数据类型必须与将 CODEDCODE 应用于 AE 表单中的条目 AETERM 的输出数据类型相匹配。

在 reference_data 条目中使用以下键来定义参考对象、其条目及其与临床数据的关系。

父键 键名称 必填 依赖关系 描述
reference_data 文件名 是（Yes） 包含参考数据的 CSV 文件的名称
reference_data reference_object_name 否（No） CDB 中参考数据表的名称
reference_data related 是（Yes） 使用此属性定义一个键或键组合
related related_form_source 否（No） 与参考数据相关的 related_form 的源名称
related related_form 是（当参考数据与表单上的条目相关时） 与参考数据相关的表单的名称
related related_itemgroup 是（当参考数据与表单上的条目相关时） 与参考数据相关的条目组的名称
related related_item 是（Yes） 与参考数据相关的表单或标题中的条目的名称
related related_key 是（Yes） 参考数据中定义键的名称
reference_data 条目 是（Yes） 使用此属性定义每种数据类型及其属性
条目 {数据列名称} 是（Yes） 引用要定义数据类型的列名称
{数据列名称} 类型 是（Yes） 定义数据类型：文本、整数、日期和日期时间
{数据列名称} 长度 否（No） 类型必须为文本 定义文本类型的长度
{数据列名称} min 否（No） 类型必须为整数 定义整数的最小值
{数据列名称} max 否（No） 类型必须为整数 定义整数的最大值
{数据列名称} 格式 否（No） 类型必须为日期或日期时间 定义日期和日期时间数据类型的可接受格式。有关有效格式的列表，请参阅下表。

日期和日期时间格式&

类型 有效格式
日期
  • dd MM yy
  • dd MM yyyy
  • dd MMM yyyy
  • dd-MM-yy
  • dd-MM-yyyy
  • dd-MMM-yyyy
  • dd.MM.yy
  • dd.MM.yyyy
  • dd/MM/yy
  • dd/MM/yyyy
  • ddMMMyyyy
  • ddMMyy
  • ddMMyyyy
  • MM/dd/yy
  • MM/dd/yyyy
  • MMddyy
  • MMddyyyy
  • MMM dd yyyy
  • MMM/dd/yyyy
  • MMMddyyyy
  • yy-MM-dd
  • yy/MM/dd
  • yyyy MM dd
  • yyyy-MM-dd
  • yyyy.dd.MM
  • yyyy.MM.dd
  • yyyy/MM/dd
  • yyyyMMdd
  • dd/MMM/yy
  • dd-MMM-yy
  • ddMMMyy
  • dd MMM yy
日期时间
  • dd/MM/yyyy HH:mm
  • MM/dd/yyyy HH:mm
  • yyyy-MM-ddTHH:mm:ss+HH:mm
  • yyyy-MM-ddTHH:mm:ssZ
  • yyyyMMddTHH:mm:ssZ

导入包要求

导入包必须是一个 ZIP 文件，其中包含 reference_manifest.json 和所选源的任何参考数据 CSV 文件。不得在 ZIP 文件夹中包含任何文件夹。所有 CSV 文件和清单文件必须位于同一级别。

CSV 文件中的列标题：在当前版本中，列标题不能包含空格字符。

导入参考数据包

为了使 CDB 能够导入并验证参考数据，相关表单的临床数据必须已经存在于 CDB 中，或者必须与参考数据一起导入到同一个上传包中。要将参考数据与临床数据一起导入，请在与临床数据相同的清单文件中包含 reference_data 数组键。

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

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

成功导入

在成功导入之后：

  • CDB 从参考对象创建所有记录。
  • CDB 会自动将源字段设置为所有导入记录的参考清单中提供的值，以唯一标识数据源。
  • CDB 将导入的 ZIP 文件从“workbench”移动到“workbench/_processed/{study}/{source}”（如果导入失败，ZIP 文件将保留在“workbench”目录的根目录中。CDB 还会将导入的日期和时间附加到文件名中。

查看导入状态

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

完成状态：要使导入包进入移至完成导入状态，研究的 Workbench 用户必须打开一个列表。否则，导入将保持进行中状态。如果研究启用了自动交换功能，则不需要进行此操作。

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

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

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

Workbench 导入状态

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

状态 说明
进行中 此数据包的导入过程已经开始，Workbench 未发现任何错误或警告。
进行中（带警告） 导入过程正在进行中，但 Workbench 已发现警告。
错误 导入失败，因为导入包中存在一个或多个错误。下载问题日志并查看错误。
完成 Workbench 已成功导入数据包，没有错误或警告。
完成（带警告） Workbench 已成功导入数据包，但存在一个或多个警告。下载问题日志并查看警告。
正在进行重新处理 Workbench 已开始重新处理此数据包，因为导入了来自其他源的新数据包。
重新处理完成 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 中查看参考数据

可以使用 CQL 查询参考数据。

从参考对象中进行选择的方式与标题或表单相同。如果选择 *，CQL 将返回参考对象上的所有条目。

select * from Reference_Object_Name

要检索研究中的所有参考对象列表，请使用 SHOW 关键字：

SHOW Reference

然后，可以使用 DESCRIBE 关键字来检索给定参考对象上的条目列表：

DESCRIBE Reference <Reference_Object_Name>

使用 ReferenceRelations 关键字检索以下属性的键值对表：reference_object_name、related_form、related_item 和 related_key。

ReferenceRelations <Reference_Object_Name>

可以使用 KEYMATCH 函数检查 related_item 和 related_key 之间是否存在匹配。如果存在匹配，CQL 返回真（true）。否则，CQL 返回假（false）。

KEYMATCH(form_name, reference_object)

对于文本类型的参考对象条目，CQL 支持以下函数：

  • CONCAT
  • LENGTH
  • TRIM
  • LTRIM
  • RTRIM
  • UPPER
  • LOWER
  • LEFT
  • RIGHT

对于日期类型的参考对象条目，CQL 支持以下函数：

  • ADDDATE
  • SUBDATE
  • DATEDIFF
  • DATE_FORMAT
  • SITENORMALIZEDDATE
  • RAWDATE
  • SDTMDATEFORMAT
  • STR_TO_DATE
  • CURDATE
  • NOW
  • YEAR
  • MONTH
  • WEEK
  • DAY
  • HOUR
  • MINUTE
  • SECOND
  • LAST_DAY

CQL 限制

使用参考对象时，CQL 限制适用。

以下函数不能与参考数据一起使用：

  • FROZEN
  • ILB
  • LABEL
  • LASTCODED
  • LASTMODIFIEDDATE
  • LOCKED
  • SIGNED
  • STATUS

也无法使用高级连接将参考数据与其他数据连接。