OneRoster CSV
描述
ManageBac+ 允许管理员使用定制版的OneRoster 1.2 标准ManageBac+和导出用户、班级、注册信息及相关数据。此功能位于“设置”>“数据交换”下，并包含验证报告，以确保导入前数据正确无误。
OneRoster 标准由IMS 全球学习联盟开发和维护，并为数据交换提供了一个框架。有关技术实现的描述，请参阅此处的资源：
ManageBac+ OneRoster 1.2 CSV 自定义规范
出口
ManageBac+中的导出是指将数据从系统传输到外部格式的过程，允许用户与其他系统共享、备份或集成信息。
要开始导出，请导航至数据交换管理器中的“导出”选项卡。
如果您看到“步骤 2 - 模式选项（批量和增量）”，则表示其他管理员已完成导出。请选择所需的导出方法，然后单击“继续导出”。
ManageBac+中的批量导出和增量导出在数据管理中各有不同的用途：
- 批量导出：此过程一次性导出所有相关记录。通常在需要完整数据集时使用，例如初始设置或迁移到新系统时。此方法可确保所有现有数据都被捕获并传输。
- 增量导出：此过程仅导出自上次导出以来发生更改的记录，例如新增、更新或删除的条目。它有助于在不传输整个数据集的情况下保持数据最新，从而提高持续同步的效率。增量导出只能在批量导出完成后执行。
点击“继续导出”后，导出作业将在后台启动，并将用户导航至Exchange 历史记录选项卡。
完成后，找到您最新的导出文件，然后单击“下载”按钮（向下箭头）以获取 ZIP 文件。
请查看下载的文件。文件内容将包含所有实体及其在ManageBac+自定义规范中的表示方式。
输入
要通过数据交换管理器启动导入过程，请在“导入”选项卡中选择您的 ZIP 文件。
从您的计算机中选择 OneRoster ZIP 文件，然后单击“保存”上传。
请填写必填项：
如果您的manifest.csv文件中缺少source.systemname和source.systemcode字段，则上传区域下方会出现两个需要您填写的字段。更多详情，请参阅“ 文件规范 > manifest.csv”部分。
如果这些值已存在于manifest.csv文件中，则字段将预先填充，您无法输入它们。
一切设置完毕后，点击底部的“继续验证”按钮。这将启动导入作业，该作业会在后台运行 OneRoster 和ManageBac+验证。
一次只能导入一个 OneRoster 数据。
通过顶部的“Exchange 历史记录”选项卡查看导入状态。导入完成后，找到您最近一次导入的记录，并查看验证结果。
将打开“交换报告”页面，显示摘要以及从您的 OneRoster ZIP 上传的所有 CSV 文件。
在每个 CSV 工作表中，存在问题的单元格中，错误和警告将以相应的颜色突出显示。
共有三个标签页，默认初始选中的是“无效”标签页：
有效——包含所有没有警告或验证失败的行
警告—包含至少有一个警告的所有行
无效行—包含至少包含一个无效行的所有行
要了解与警告或失效相关的消息，请点击展开行信息：
警告信息表示潜在问题，但不会阻止导入。管理员可以根据具体情况选择忽略或进行调整。
无效记录不符合功能要求，无法导入。
解决所有导致数据失效的问题后，使用更新后的 ZIP 文件执行新的导入操作。
数据实体
下表说明了不同的ManageBac+实体如何与OneRoster 1.2实体和 CSV 文件相对应，从而确保无缝数据交换，同时考虑到数据模型的差异。
| OneRoster 1.2 实体 | ManageBac+实体 | OneRoster CSV 文件 |
| 组织 -> 地区 | 不适用 | 组织 |
| 组织 -> 学校 | 学校 | 组织 |
| 组织 -> 项目扩展 | 程序 | 组织 |
| 学年 -> 学年 | 学年 | 学术会议 |
| 课程 | 学科组 | 课程 |
| 课程 -> 科目 | 主题 | 课程 |
| 课程 | 课程 | 课程 |
| 用户、角色 -> 学生、人口统计信息 | 学生 | 用户、角色、人口统计信息 |
| 用户、角色 -> 教师 | 教师 | 用户、角色 |
| 用户、角色 -> 父级 | 父母 | 用户、角色 |
| 用户、角色 -> 管理员 | 管理员 | 用户、角色 |
| 用户 -> 代理 | 亲子关系 | 用户 |
| 入学人数 | 类别成员资格 | 入学人数 |
例如， ManageBac+学生对应于OneRoster 中角色为“学生”的用户。在 OneRoster 中，用户和角色分别在users.csv和roles.csv中定义。
数据交换管理器仅更新上述记录，不修改任何其他数据。
增量进口与批量进口
数据交换过程中的一个关键区别在于增量导入和批量导入之间的差异。
- Delta 进口：
- 匹配并更新现有的ManageBac+记录。
- 如果记录尚不存在，则创建新记录。
- 保留源数据中未包含的记录不变。
-
批量导入：
- 执行与增量导入相同的操作（匹配、更新和创建记录）。
- 此外，还会归档ManageBac+中源数据中不存在的任何活动记录。
- 例如，如果像“IB 生物学”这样的课程在ManageBac+中处于活动状态，但在源数据中缺失，则在导入处理完成后，该课程将被存档。
总而言之，批量导入不仅可以创建和更新源数据中的记录，还可以归档源数据中缺失的任何记录。
如果在学年过渡期间执行批量导入，请注意OneRoster不包含年级组，因此必须单独管理年级组。
导入时的记录匹配
在增量导入和批量导入过程中， ManageBac+使用两种主要策略将源数据中的记录与系统中的记录进行匹配：
- 如果sourcedId之前已被使用过，则使用下一点中描述的匹配方法直接将其与相应的记录匹配。
- 如果无法按sourcedIds进行匹配，或者这是首次匹配，下表概述了每个实体的匹配策略：
| 实体 | 源列（或） | 匹配到（MB） |
| 学校 | orgs.types == "school" | 与当前学校匹配（仅 1 条记录） |
| 程序 | orgs.sourcedId ，匹配第一个下划线后的后缀 |
与程序代码匹配 （例如abc-dedf_diploma是IB 文凭） |
| 学术会议 | academicSessions.startDate ， academicSessions.endDate | 与学年/学期开始/结束日期相匹配 |
| 课程 | 课程标题 | 与主题组标题匹配 |
| 主题 | courses.subjects[] | 数组中的每个字符串都与主题标题进行匹配。 |
| 课程 | classes.classCode | 与类别 ID 匹配 |
| 用户 | 用户.用户名 | 已匹配学生/教师/家长邮箱 |
常见问题解答
问： OneRoster是什么？为什么ManageBac+要使用它的自定义规范？
OneRoster是由IMS全球学习联盟开发的一项被广泛采用的规范，旨在标准化不同系统之间教育数据的交换，例如学生信息、课程数据和注册信息。ManageBac ManageBac+对OneRoster 1.2的实现采用了一种自定义规范，称为“ ManageBac+ OneRoster方言”（简称MB或方言），因为OneRoster基础规范的数据模型与ManageBac+的功能需求有所不同。这种自定义使得ManageBac+能够以符合其内部数据结构和功能的方式导入和导出记录。
问题： ManageBac+ OneRoster 导入/导出中包含哪些文件，哪些是必需的？
ManageBac+ OneRoster 数据以包含 CSV 文件的 zip 压缩包形式交换。manifest.csv 文件为必填项。以下文件为可选文件，但如果包含其对应的实体，则必须包含在压缩包中：academicSessions.csv、orgs.csv、courses.csv、classes.csv、roles.csv、users.csv、enrollments.csv 和 demographics.csv。请注意，空的可选文件必须包含必需的列标题。
问题：每个文件需要哪些列，以及哪些值是合法的？
这些细节在描述技术实现的资源中有所提供，可在此处查阅：
ManageBac+ OneRoster 1.2 CSV 自定义规范
问题：将 OneRoster 数据导入ManageBac+验证规则是什么？
ManageBac+会对所有导入的 CSV 文件应用多项通用验证。这些验证结果会显示在“数据交换历史记录”选项卡中。每个实体都有一组验证规则，其详细信息请参阅描述技术实现的资源，该资源可在此处查阅：
ManageBac+ OneRoster 1.2 CSV 自定义规范
问： ManageBac+与其他符合 OneRoster 1.2 标准的系统之间交换数据时，存在哪些差异和潜在的不兼容性？
将ManageBac+中的数据导出到实现了标准 OneRoster 1.2 的第三方系统时，导出结果通常是兼容的。ManageBac ManageBac+会在导出文件中包含一些额外的元数据列，例如“用户”、“课程”和“班级”，这些列通常可以被接收系统忽略。
然而，由于ManageBac+的自定义规范，从第三方系统导入数据到ManageBac+时需要满足某些要求。例如，课程和班级必须与具有特定类型（例如 ext:program）的组织关联，并且用户、课程和班级文件中可能还需要额外的元数据列。导入时，学期也需要部分符合规范。
问： ManageBac+数据交换管理器中的“批量导出”和“增量导出”有什么区别？批量导出是对所选数据进行完整导出，提供ManageBac+中当前信息的完整快照。这通常作为初始导出操作执行。而增量导出则仅导出自上次成功执行批量导出以来发生的更改（添加、修改和删除）。要执行增量导出，您必须事先至少完成一次批量导出。
问题：将 OneRoster ZIP 文件导入ManageBac+时，我应该在哪里指定源系统名称和代码？
ManageBac+需要 source.systemname 和 source.systemcode 来识别 OneRoster 数据的来源，尤其是在从多个学生信息系统导入名册数据时。如果您的 manifest.csv 文件中尚未包含这些字段，则在数据交换管理器中上传 ZIP 文件后，系统会提示您手动输入这些字段。从同一源系统导入的数据，这些值应保持一致。
问：为什么我无法选择 Delta 方法进行导出？
答：要启用增量导出方式，您必须先完成首次批量导出。首次批量导出完成后，增量导出方式即可使用。增量导出方式会导出自上次完整批量导出以来的所有更改。
问：在ManageBac+的自定义OneRoster规范中，我应该在哪里指定年级组？
答：目前暂不支持年级分组功能，但我们正在与 OneRoster 合作，探索如何支持满足 ManagaBac 功能需求的必要扩展。建议您通过“设置”->“花名册”->“成员资格”来维护年级分组成员信息。
问：交易历史记录页面上的状态是什么意思？
答： ManageBac+有四种不同的状态，具体说明如下：
已安排- 这意味着系统已成功安排导入操作，并将其加入队列，稍后开始执行。启动后，操作状态将变为“正在处理”。
正在处理中- 这表示系统当前正在后台处理您的导出或导入任务。此状态为临时状态，稍后将变为以下状态之一。
失败- 如果出现此状态，则表示后台任务无法完成。对于导出错误，请联系ManageBac+支持团队（提交请求）。对于导入错误，请单击眼睛图标打开“报告视图”页面，检查验证错误，并在下次导入时进行修复。
成功——这意味着任务已顺利完成，没有任何错误。