研究文件格式 API
研究文件格式（Study File Format）（SFF）是一种从 Veeva EDC 和 CDB 系统导出临床数据的标准化方法。SFF 通过研究文件格式 API 访问，并以单独的压缩包提供，包括两个主要部分：研究数据（Study Data）和研究定义（Study Definition）。
SFF 可用于报告临床和操作数据以及与其他系统集成。压缩包包含一个清单文件以及提供临床、操作和参考数据的 CSV。清单文件详细说明了研究定义和研究数据之间的关系。
提取类型（Extraction Types）：SFF 提取有两种类型：完整提取和增量提取。完整 SFF 提取包含从数据收集开始到最近一次 SFF 完整提取运行的整个数据集。完整的 SFF 提取（数据包）每 24 小时提供一次，时间为 UTC 中午 12:00。可以通过增量的形式生成临床数据和操作数据，以反映自最近一次 SFF 提取以来的任何变化。您可以在使用 List Packages 端点时指定完整提取或增量提取。
许可：Veeva Clinical Data 许可证既包括完整 SFF 数据包，也包括增量 SFF 数据包。可以在“EDC 工具（EDC Tools）”中为每个研究 启用完整数据包。要启用增量数据包，请联系 Veeva 支持人员。
当前 SFF 版本不包括非 Veeva EDC（3PD）数据。
先决条件
默认情况下，具有标准 CDMS 超级用户（CDMS Super User）研究角色的用户可以执行下述操作。如果贵组织使用自定义角色，则你的角色必须授予以下权限：
| 类型 | 权限标签 | 控制 |
|---|---|---|
| 功能权限 | 研究文件格式 API 访问 | 能够访问和使用研究文件格式 API。 默认情况下，研究文件格式 API 访问能够提供 API 访问和受限数据访问。 |
| 功能权限 | 工作台（Workbench）选项卡* | 能够通过 Workbench 选项卡访问和使用 Data Workbench 应用程序。 *仅当在采用增量导出的 Workbench 研究中使用研究文件格式 API 时，才需要 Workbench 选项卡权限。 |
启用研究文件格式 API
SFF 只能在生产研究环境中启用。
要在 Vault 中启用研究文件格式功能：
-
导航到研究 的工具> EDC 工具> 研究设置。
- 单击编辑。
- 单击是以启用研究文件格式 API。
CDB 增量导入：CDB 增量导入是 CDB 研究的先决条件。如果你的 Vault 是在 24R2 版本之后创建的，则你的 Vault 中启用了增量导入（incremental import）功能。如果你的 Vault 是在 24R2 版本之前创建的，则可能尚未启用此功能。
如果您是首次启用 SFF，请等待首个完整 SFF 软件包发布并通过 API 获得。如果禁用该功能，然后为研究重新启用该功能，以上描述同样适用。
软件包结构
SFF 软件包以 ZIP 文件式提供。在 ZIP 文件中，有一个名为数据（data）的文件夹，其中包含所有 CSV 文件。在 ZIP 文件的根目录中，“manifest.json”文件包含软件包的自描述结构以及研究设计（Study Design）信息。
软件包文件名格式如下：
Study Name_SFF_Full/Incremental_YYYY_MM_DD_HH_MM_SS
例如，Natevba_SFF_Incremental_2024_08_16_00_30_00
名称中提供的时间戳表示软件包的发布时间。
完整提取
每 24 小时提供一次 ZIP 包的完整提取，旨在帮助您在以下情况下更新下游系统：
- 首次为研究启用 SFF
- 在新的研究设计更改或部署期间
- 使用完全“刷新”替换数据
- 出现需要重新启动的严重错误
研究设计数据
清单文件中的研究设计数据始终以完整数据集提取，而不是以增量形式提取。每次提取时都会捕获最新版本的研究设计数据。
标签和覆盖标签
标签和覆盖标签包括来自最新研究设计版本的数据。
增量提取
增量提取每 15 分钟提供一次。使用增量提取时，如果上一个数据提取和当前数据提取之间没有变化，则文件将生成为仅包含列标题的空白文件。
DELETES 文件
DELETES CSV 文件包含在增量提取的参考数据中。其中包括所有必要的已删除数据，以便确定应从您的集成系统中删除的行。
ROWID 列
在除 DELETES 文件之外的每个文件中均包含 ROWID 列，并且可用于标识已更新和已删除的行。它由 ROWID（行 ID）组成，这是用于创建唯一数据行的基础标识符。ROWID 结构因文件而异。
跟踪更改
对增量提取或压缩包的任何更改都应被视为 UPSERT（这意味着如果值已存在，则更新一行，如果值不存在，则插入一行）而不是 INSERT。唯一的例外是 DELETES 文件，它会跟踪已删除的行。
清单文件
JSON 是一种结构化格式，可用于将研究设计对象映射到研究数据。manifest.json 文件允许用户以程序化方式使用数据。其中定义了研究数据文件结构并包括了研究设计。
清单文件中的标题信息包括以下内容：
- 研究名称
- 文档 URL
- SFF 版本
- 提取名称
- 创建日期时间
- 软件包中的文件数
- 临床数据是否通过增量的形式生成
- 清单引用的研究设计版本
数据分为四个 JSON 代码块：
- 操作数据
- 参考数据
- 临床数据
- 研究设计
示例清单文件
下载示例清单文件。
操作数据和参考数据&
操作数据（operational_data）定义操作数据文件（包括系统文件），参考数据（reference_data）定义与研究关联的参考数据文件。
临床数据
临床数据（clinical_data）由文件名、源、表单和列标题组成：
| 字段 | 描述 |
|---|---|
| 文件名 | CSV 文件的名称（例如，“prescreening.csv”） |
| 源 | 临床数据文件的来源（例如，“EDC”） |
| 表单 | 表单定义的名称 |
| 列 | 文件列数组包括预定义的标题（header）列和临床项目列。每个项目列代表一个项目定义（Item Definition）。 项目定义元数据源自 EDC 工作室。 项目可能具有其他属性，详见下列其他项目属性（Additional Item Attributes）部分。 |
其他项目属性
以下是清单文件中临床数据的其他项目属性的示例：
- 名称：属性的名称。
- External_id：属性的外部 ID
- SDTM_name：SDTM 名称
- 数据类型：基于 EDC 数据类型（请参阅下面的部分）
- 长度：针对文本、数字、代码列表和单位项目类型的填充
- 精确率：针对数字和单位项目类型的填充
- 未知：可以填充允许未知部件的日期或日期时间项目定义
- 掩码：通常针对未知日期和日期时间的填充
- Item_type：例如，edc__v、derived__v、read_only__v
- Itemgroups：项目组定义（Item Group Definition）名称
- 如果项目定义在项目组定义中重复使用，则所有项目组定义将按照它们在表单定义（Form Definition）中列出的顺序显示在数组中
- 受限：受限数据，布尔值等于 true 或 false
- 代码列表：代码列表定义（Codelist Definition）名称
- 单位：单位定义名称
数据类型
数据类型项属性基于以下 EDC 数据类型：
- 文本
- 代码列表
- URL
- 标签
- 布尔值
- 数字
- 单位
- 日期
- 日期时间
- 时间
研究设计
研究设计（study_design）模块包括以下部分：
- 事件组：定义研究中配置的所有事件组定义（Event Group Definitions）
- 事件：定义研究中配置的所有事件定义（Event Definitions）
- 表单：定义研究中配置的所有表单定义（Form Definitions）
- 项目组：定义研究中配置的所有项目组定义（Item Group Definitions）
- 代码列表：定义临床数据文件（非实验室）中使用的所有代码列表定义（Codelist Definitions）
- 单位：定义临床数据文件（非实验室）中使用的所有单位定义（Unit Definitions）
- 受试者组：定义研究中配置的所有受试者组定义（Subject Group Definitions）
有关表单上每个临床项目的信息可在清单文件的临床数据 JSON 模块中找到。对于每个临床文件，都有事件组（Event Group）、事件（Event）和表单定义名称的引用键。可以用于映射临床文件和研究设计对象之间的关系。
清单文件中的列无法保证按顺序排列。但是，您可以通过程序化方式将每列映射到其相应的 CSV 列标题，该列标题将按顺序排列。
研究数据文件
SFF 的研究数据部分还包括临床、操作和参考数据。临床数据文件包括标题列，这些列指示与每个受试者关联的研究、研究中心国家/地区（Site Country）、研究中心（Site）、事件组、事件和表单。表单上的每个临床项目都有自己的列，位于主列标题之后。
研究数据文件包含受限数据。默认情况下，研究文件格式 API 访问权限会授予限制数据访问权限。
名称通常用于对象的标签，如事件组、事件、表单、项目组、项目定义和状态（Statuses）。标签可以在完整 SFF 压缩包的 LABELS CSV 文件中找到。ID 在 SFF 中不可见，但 ROWID 除外，ROWID 是一行数据的唯一标识符。
临床数据文件
临床数据文件由每个表单定义的一个 CSV 文件组成。文件的标题与表单定义名称相同。如果有多个具有相同名称的表单定义，则其他表单定义将在文件名后附加 _2、_3 等。顺序由源名称（Source Name）和表单定义名称的字母顺序确定。每个文件都包含代表特定表单实例的一行临床数据的记录。临床数据包括处于已提交（Submitted）和进行中提交后（In Edit）（in_progress_post_submit__v）状态的表单。
临床数据标题
临床数据标题是标准列，表示表单内临床数据的层次结构。所有临床数据文件中的标题都是通用的。
列的列表如下：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| EGROUPNAME | 文本 | 事件组名称 |
| EGSEQ | 数字 | 事件组序列 |
| EVENTNAME | 文本 | 事件名称 |
| FORMNAME | 文本 | 表单名称 |
| FSEQ | 数字 | 表单序列 |
| IGSEQ | 数字 | 条目组序列 |
| FORMSTATUS | 文本 | 表单状态 |
| CREATEDDT | 日期时间 | 表单创建日期时间 |
| FIRSTSUBMITDT | 日期时间 | 表单首次提交的日期时间 |
| LASTSUBMITDT | 日期时间 | 表单上次提交的日期时间 |
| FORMLASTMODDT | 日期时间 | 表单上次修改的日期时间 |
| 项目列 | 变量 | 项目列（扩展为表单上的项目数） |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
临床项目数据
临床项目显示在每个临床文件上方列出的标题列之后，每个项目定义名称（Item Definition Name）都位于其自身列中。必要时动态添加数据。例如，如果项目组是非重复的，则相应的项目组序列将不会在临床表单中显示。
数据类型 & 格式
| 数据类型 | 格式 | 描述 |
|---|---|---|
| 文本 | 字符串 | 对于临床数据项，文本可以表示为代码列表或 URL 数据类型。状态通过名称值表示。例如：submitted__v |
| 数字 | 数字 | 定义的精度和/或长度 |
| 日期 | 系统日期的格式为 YYYY-MM-DD。每个临床日期都有两列：输入的派生/ISO8601 日期和原始日期。 | 每个日期都有两列，即派生 ISO8601 格式和原始格式。例如：BIRTHDT：1990-01-25 和 BIRTHDT_RAW：25-Jan-1990 |
| 日期时间 | 系统日期时间采用 UTC 时区。每个临床日期时间都有两列：输入的派生/ISO8601 日期时间和原始日期时间。 | 每个日期时间都有两列，即派生 ISO8601 格式和原始格式。例如：LBDTC：2021-01-01T12:00:00 和 BIRTHDT_RAW 01-Jan-2021 12:00:00: |
| 时间 | HH:mm:ss | 标准格式、ISO8601 |
| 未知 | 对于日期未知的日期，派生日期格式为 2024-06-01，原始日期格式为 UN-Jun-2024。 对于日期未知的日期时间，派生日期时间格式为 2024-06-01T00:00:00，原始日期时间格式为 UN-Jun-2024 UN:UN:UN。 对于月 + 日未知的日期，派生日期格式为 2024-01-01，原始日期格式为 UN-UNK-2024。 对于月 + 日未知的日期时间，派生日期时间格式为 2024-01-01T00:00:00，原始日期时间格式为 UN-Jun-2024 UN-UNK-2024 UN:UN:UN。 对于未知时间，派生日期格式为 2024-06-02T00:00:00，原始日期格式为 02-Jun-2024 UN:UN:UN。 | 原始日期和日期时间输出表示未知日期和日期时间的方式。对于派生日期和日期时间，系统会将未知部分（月、日或时间）默认为 1 月 1 日 00:00:00 UTC。 |
| 布尔值 | True/False | |
| 单位 | (item)_UOM (item)_TRANSLATED (item)_UOM_TRANSLATED | 对于每个单位项目，有单位值、已转换的值和转换单位值。通过在临床项目名称后附加后缀来表示。度量单位（UOM）和已转换的度量单位显示单位标签。 |
| 代码列表 | （项目） (item)_DECODE | 代码值是项目值。DECODE 或标签是动态添加的辅助列，在项目名称后附加后缀。例如：民族_DECODE |
操作数据 & 系统数据集
除临床数据外，SFF 压缩包还包含多个包含操作数据的系统数据集。
系统数据集提供与特定 CDMS 对象相关的数据，并跟踪研究中所有受试者的进度。压缩包中会自动包含这些内容，并包含以下文件：
- SYS_EVENTS.csv
- SYS_FORMS.csv
- SYS_SUBJECTS.csv
- SYS_ILB.csv
- SYS_LINKS.csv
- SYS_SITES.csv
- QUERIES.csv
- QUERY_MSGS.csv
SYS_EVENTS
SYS_EVENTS 数据集描述与特定受试者相关的事件和事件组，以及它们的当前状态和更改原因。
其中包含以下事件状态（Event Statuses）：
- blank__v（空白）
- submitted__v（已提交）
- in_progress__v（进行中）
- planned__v（已计划）
- did_not_occur__v（没有发生）
SYS_EVENTS 列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| EGROUPNAME | 文本 | 事件组名称 |
| EGROUPORDER | 数字 | 事件组顺序 |
| EGSEQ | 数字 | 事件组序列 |
| EVENTNAME | 文本 | 事件名称 |
| EVENTORDER | 数字 | 事件顺序 |
| EVENTDT | 日期 | 事件日期 |
| VISMETHOD | 文本 | 访视方式 |
| PLANNEDDT | 日期 | 计划日期 |
| OVERDUEDT | 日期 | 事件逾期 |
| EVENTSTATUS | 文本 | 事件状态 |
| EVENTRESTRICTED | 布尔值 | 事件受限 |
| CHANGEREASON | 文本 | 事件更改原因 |
| EXPFORMS | 数字 | 预期的表单数量 |
| FROZEN | 布尔值 | 事件已冻结 |
| FROZENDT | 日期时间 | 事件冻结的日期时间 |
| LOCKED | 布尔值 | 事件已锁定 |
| LOCKEDDT | 日期时间 | 事件锁定的日期时间 |
| SIGNED | 布尔值 | 事件已签名 |
| SIGNEDDT | 日期时间 | 事件签名的日期时间 |
| EVENTDTLASTMODDT | 日期时间 | 事件日期上次修改的日期时间 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
SYS_FORMS
SYS_FORMS 数据集提供了包含受试者数据的所有表单概述，包括表单状态、SDV 和 DMR 的表单级审查状态以及表单级 ILB（特意留空）信息。
其中包含以下表单状态（Form Statuses）：
- blank__v（空白）
- submitted__v（已提交）
- in_progress__v（进行中）
- in_progress_post_submit__v（进行中提交后）
SYS_FORMS 列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| EGROUPNAME | 文本 | 事件组名称 |
| EGSEQ | 数字 | 事件组序列 |
| EVENTNAME | 文本 | 事件名称 |
| FORMNAME | 文本 | 表单名称 |
| FSEQ | 数字 | 表单序列 |
| FORMSTATUS | 文本 | 表单状态 |
| FORMRESTRICTED | 布尔值 | 表单受限 |
| CREATEDDT | 日期时间 | 表单创建日期 |
| FIRSTSUBMITDT | 日期时间 | 表单首次提交日期 |
| LASTSUBMITDT | 日期时间 | 表单上次提交日期 |
| NUMSUBMITS | 数字 | 表单提交数量 |
| OVERDUEDT | 日期 | 表单逾期 |
| CHANGEREASON | 文本 | 表单更改原因 |
| SDVOVRPLAN | 文本 | SDV 覆盖计划 |
| SDVREQ | 布尔值 | 需要 SDV |
| SDVCOMP | 布尔值 | SDV 已完成 |
| FIRSTSDVDT | 日期时间 | 首次 SDV 日期 |
| SDVCOMPDT | 日期时间 | SDV 完成日期时间 |
| SDVUSERMODDT | 日期时间 | SDV 用户修改日期 |
| DMROVRPLAN | 文本 | DMR 覆盖计划 |
| DMRREQ | 布尔值 | 需要 DMR |
| DMRCOMP | 布尔值 | DMR 已完成 |
| FIRSTDMRDT | 日期时间 | 首次 DMR 日期 |
| DMRCOMPDT | 日期时间 | DMR 完成日期时间 |
| DMRUSERMODDT | 日期时间 | DMR 用户修改日期 |
| FROZEN | 布尔值 | 表单已冻结 |
| FROZENDT | 日期时间 | 表单冻结的日期时间 |
| LOCKED | 布尔值 | 表单已锁定 |
| LOCKEDDT | 日期时间 | 表单锁定的日期时间 |
| SIGNED | 布尔值 | 表单已签名。 |
| SIGNEDDT | 日期时间 | 表单签名的日期时间 |
| ILB | 布尔值 | 表单特意留空 |
| ILBREASON | 文本 | 表单特意留空的原因 |
| FORMLASTMODBY | 文本 | 表单上次修改者 |
| FORMLASTMODDT | 日期时间 | 表单上次修改的日期时间 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
SYS_SUBJECTS
SYS_SUBJECTS 数据集包含与研究中的受试者相关的数据。
SYS_SUBJECTS 列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| EGROUPNAME | 文本 | 事件组名称 |
| EGSEQ | 数字 | 事件组序列 |
| EVENTNAME | 文本 | 事件名称 |
| FORMNAME | 文本 | 表单名称 |
| FSEQ | 数字 | 表单序列 |
| FORMSTATUS | 文本 | 表单状态 |
| FORMRESTRICTED | 布尔值 | 表单受限 |
| CREATEDDT | 日期时间 | 表单创建日期 |
| FIRSTSUBMITDT | 日期时间 | 表单首次提交日期 |
| LASTSUBMITDT | 日期时间 | 表单上次提交日期 |
| NUMSUBMITS | 数字 | 表单提交数量 |
| OVERDUEDT | 日期 | 表单逾期 |
| EVDTTOSUB | 数字 | 从事件日期到提交日期的天数 |
| CHANGEREASON | 文本 | 表单更改原因 |
| SDVOVRPLAN | 文本 | SDV 覆盖计划 |
| SDVREQ | 布尔值 | 需要 SDV |
| SDVCOMP | 布尔值 | SDV 已完成 |
| FIRSTSDVDT | 日期时间 | 首次 SDV 日期 |
| SDVCOMPDT | 日期时间 | SDV 完成日期时间 |
| SDVUSERMODDT | 日期时间 | SDV 用户修改日期 |
| SUBTOSDV | 数字 | 从提交到 SDV 的天数 |
| DMROVRPLAN | 文本 | DMR 覆盖计划 |
| DMRREQ | 布尔值 | 需要 DMR |
| DMRCOMP | 布尔值 | DMR 已完成 |
| FIRSTDMRDT | 日期时间 | 首次 DMR 日期 |
| DMRCOMPDT | 日期时间 | DMR 完成日期时间 |
| DMRUSERMODDT | 日期时间 | DMR 用户修改日期 |
| SUBTODMR | 数字 | 从提交到 DMR 的天数 |
| FROZEN | 布尔值 | 表单已冻结 |
| FROZENDT | 日期时间 | 表单冻结的日期时间 |
| SUBTOFROZEN | 数字 | 从提交到冻结的天数 |
| LOCKED | 布尔值 | 表单已锁定 |
| LOCKEDDT | 日期时间 | 表单锁定的日期时间 |
| SUBTOLOCKED | 数字 | 从提交到锁定的天数 |
| SIGNED | 布尔值 | 表单已签名。 |
| SIGNEDDT | 日期时间 | 表单签名的日期时间 |
| SUBTOSIGNED | 数字 | 从提交到签名的天数 |
| ILB | 布尔值 | 表单特意留空 |
| ILBREASON | 文本 | 表单特意留空的原因 |
| FORMLASTMODBY | 文本 | 表单上次修改者 |
| FORMLASTMODDT | 日期时间 | 表单上次修改的日期时间 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
SYS_ILB
SYS_ILB 数据集包含所有研究中心中每个受试者的特定表单上相关项目的特意留空数据。其中包括已提交状态的数据。
SYS_ILB 列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| EGROUPNAME | 文本 | 事件组名称 |
| EGSEQ | 数字 | 事件组序列 |
| EVENTNAME | 文本 | 事件名称 |
| FORMNAME | 文本 | 表单名称 |
| FSEQ | 数字 | 表单序列 |
| IGROUPNAME | 文本 | 项目组名称 |
| IGSEQ | 数字 | 条目组序列 |
| ITEMNAME | 文本 | 项名称 |
| ILBREASON | 文本 | 故意保留为空的原因 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
SYS_LINKS
SYS_LINKS 数据集包含有关添加到临床数据以进行表单至表单链接的任何链接的信息。
SYS_LINKS 列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| EGROUPNAME | 文本 | 事件组名称 |
| EGSEQ | 数字 | 事件组序列 |
| EVENTNAME | 文本 | 事件名称 |
| FORMNAME | 文本 | 表单名称 |
| FSEQ | 数字 | 表单序列 |
| LINKID | 文本 | 链接 Vault ID |
| LINKCREATEDBY | 文本 | 链接创建者 |
| LINKCREATEDDT | 日期时间 | 链接创建日期时间 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
SYS_SITES
此数据集包含有关研究中心的数据。
SYS_SITES 列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SITENAME | 文本 | Site Name（研究中心名称） |
| SITEPI | 文本 | 研究中心主要研究者 |
| SITESTATUS | 文本 | 研究中心状态（Site Status） |
| SITETIMEZONE | 文本 | 研究中心时区 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
查询文件
查询文件包含在研究中创建的每个查询的记录，以及操作指标，例如查询的打开时间、关闭时间和创建者。可以使用此数据来计算下游报告和分析的其他指标。
查询文件中的列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| EGROUPNAME | 文本 | 事件组名称 |
| EGSEQ | 数字 | 事件组序列 |
| EVENTNAME | 文本 | 事件名称 |
| EVENTDT | 日期 | 事件日期 |
| EVENTSTATUS | 文本 | 事件状态 |
| FORMNAME | 文本 | 表单名称 |
| FSEQ | 数字 | 表单序列 |
| IGROUPNAME | 文本 | 项目组名称 |
| IGSEQ | 数字 | 条目组序列 |
| ITEMNAME | 文本 | 项名称 |
| QUERYNAME | 文本 | 查询名称 |
| QUERYID | 文本 | 查询 ID |
| ORIGINSYS | 文本 | 原始系统 |
| ORIGINID | 文本 | 原始 ID |
| ORIGINNAME | 文本 | 原始名称 |
| QUERYSTATUS | 文本 | 查询状态 |
| QUERYTYPE | 文本 | 查询类型 |
| QUERYRESTRICTED | 布尔值 | 受限制的查询 |
| MANUALQUERY | 布尔值 | 手动或系统查询 |
| RULEDEF | 文本 | 规则定义名称 |
| TRIGID | 文本 | 触发器名称 |
| FIRSTQUERYMSG | 文本 | 第一条查询消息 |
| QUERYTEAM | 文本 | 查询团队 |
| QUERYROWEXTERNALID | 文本 | 查询行外部 ID（如果已设置，则为对非 Veeva EDC 数据的查询填充） |
| QUERYCREATEDBY | 文本 | 查询创建者 |
| QUERYCREATEDDT | 日期时间 | 查询创建日期时间 |
| QUERYLASTCLOSEDDT | 日期时间 | 查询上次关闭日期时间 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
查询消息
查询消息文件通过显示与特定查询关联的每条消息来补充查询文件。可以将查询 ID（Query ID）作为键，在查询文件和查询消息文件之间进行映射。
查询消息文件中的列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| STUDYNAME | 文本 | 研究名称 |
| SITECOUNTRY | 文本 | 研究中心三个字母的国家/地区代码 |
| SITENUM | 文本 | Site Number（研究中心编号） |
| SUBJID | 文本 | 受试者姓名 |
| QUERYNAME | 文本 | 查询名称 |
| QUERYID | 文本 | 查询 ID |
| QUERYMSGSTATUS | 文本 | 查询消息状态 |
| RESTRICTEDMSG | 布尔值 | 受限制的查询消息 |
| QUERYMSG | 文本 | 质疑消息 |
| QUERYMSGBY | 文本 | 消息创建者 |
| QUERYMSGDT | 日期时间 | 查询消息日期 |
| QUERYTEAM | 文本 | 创建消息的查询团队 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
参考数据文件
参考数据包括标签、显示覆盖标签、删除、本地实验室单位定义和本地实验室代码列表定义的文件。
有关 DELETES 文件的信息，请参阅增量提取。
标签
标签文件显示与研究定义对象相关的标签，例如：事件组、事件、表单、项目组和项目。文件包含来自最新研究设计版本的标签，并且仅适用于完整的 SFF 压缩包。标签以当前使用的 Vault 所设置的语言显示。
标签文件中的列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| NAME | 文本 | 对象名称 |
| LABEL | 文本 | 对象标签 |
| TYPE | 文本 | 对象类型（例如 eventgroup、event、form、itemgroup、item） |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
标签文件示例：
| NAME | LABEL | TYPE | ROWWRITEDT | ROWID |
|---|---|---|---|---|
| prescreening | 预筛选 | eventgroup | 2024-06-01T21:06:00Z | prescreening_eventgroup |
| visit1 | 访视 1 | event | 2024-06-01T21:06:00Z | visit1_event |
| physical_exam | 体检 | form | 2024-06-01T21:06:00Z | physical_exam_form |
| ig_prescreen | 预筛选 | itemgroup | 2024-06-01T21:06:00Z | ig_prescreen_itemgroup |
| dob | 出生日期（Date of Birth） | item | 2024-06-01T21:06:00Z | dob_item |
| in_progress__v | 进行中 | event_status | 2024-06-01T21:06:00Z | in_progress__v_event_status |
| submitted__v | 已提交 | event_status | 2024-06-01T21:06:00Z | submitted__v_event_status |
| blank__v | 空白 | event_status | 2024-06-01T21:06:00Z | blank__v_event_status |
| did_not_occur__v | 没有发生 | event_status | 2024-06-01T21:06:00Z | did_not_occur__v_event_status |
| planned__v | 已计划 | event_status | 2024-06-01T21:06:00Z | planned__v_event_status |
在上面的示例中，ROWID 可能是拼接字符串。
覆盖标签
覆盖标签文件中的列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| SRCDEFINITION | 文本 | 源（对象）定义名称 |
| SRCLABELTYPE | 文本 | 源（对象）标签类型：如 eventgroup |
| TARGETDEFINITION | 文本 | 目标（对象）定义名称 |
| TARGETLABELTYPE | 文本 | 目标（对象）标签类型：如 event |
| TARGETOVERRIDELABEL | 文本 | 目标（对象）覆盖标签 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
本地实验室单位
本地实验室单位文件显示与本地实验室模块相关的单位定义。
实验室单位文件中的列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| UNITNAME | 文本 | 单位定义名称 |
| UNITEXTID | 文本 | 单位定义外部 ID |
| UNITTYPE | 文本 | 单位定义类型 |
| UNITITEMCODE | 文本 | 单位项目定义代码 |
| UNITITEMDECODE | 文本 | 单位项目定义解码 |
| UNITITEMEXTID | 文本 | 单位项目定义外部 ID |
| UNITITEMABBR | 文本 | 单位项目定义缩写 |
| UNITITEMSTANDARD | 布尔值 | 单位项目定义标准 |
| UNITITEMCONV | 文本 | 单位项目定义转换公式 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
本地实验室代码列表
本地实验室代码列表文件显示与本地实验室模块相关的代码列表定义。
本地实验室代码列表文件中的列的列表：
| 列 | 数据类型 | 描述 |
|---|---|---|
| CODELISTNAME | 文本 | 代码列表定义名称 |
| CODELISTEXTID | 文本 | 代码列表定义外部 ID |
| CODELISTITEMCODE | 文本 | 代码列表条目定义代码 |
| CODELISTITEMDECODE | 文本 | 代码列表条目定义解码 |
| ROWWRITEDT | 日期时间 | 将行写入文件的日期时间 |
| ROWID | 文本 | 行 ID |
有关错误处理的信息，请参阅 CDMS 开发人员门户中的 CDB 特定错误（CDB-Specific Errors）部分。
了解研究设计更改
如果 EDC 中发生研究设计更改，则会发布新的病例手册版本。将设计更改提取到 CDB 中后，无论是对于完整提取数据包还是增量提取数据包，API 响应都会将 full_required 字段作为 true 返回。当 full_required 为 true 时，仍会生成数据包，但为空。发生这种情况的原因是数据包在 48 小时内仍然可以访问。例如，即使该功能已关闭，只要尚未达到 48 小时的时间限制，仍可能返回一个空的数据包。
API 响应可以有不同的解释，具体取决于是增量提取还是完整提取：
- 对于增量数据包，true 响应意味着增量更改已停止，必须等待下一个完整的 SFF 数据包来恢复更新。
- 对于完整数据包，true 响应意味着该数据包可用于使用最新的完整数据集来刷新数据。