以下示例演示了用户（人员）数据馈送的构成，可满足多种使用案例所需。这些示例使用了尽可能简单的数据馈送。在某些情况下，您的机构可能需要更多信息 - 通过向数据馈送添加所需的标题和数据可满足这些要求。分析您机构的信息系统以及注册要求和规划，可帮助确定正确填充 Learn 以满足数据和生命周期目的所需的数据深度。

这些示例基于集成配置 UI 中可见的默认 Learn 设置。更改这些配置元素将导致示例结果发生更改。有关这些设置的说明，请访问 SIS 框架概述。此外，除非另有说明，否则假定集成已配置为对所有传入数据使用相同的数据源。

用户

用户数据是主要信息集，用于描述谁有权访问 Learn、他们在您机构中的角色以及他们在 Learn 系统中的角色。在 SIS 数据用户对象的上下文中，通常称为“PERSON”，这会反映在现有标准中。在早于这些标准的时间里，Learn 使用“PERSON”和“USER”来指代基于上下文的课程相关记录。以下示例将使用“PERSON”来指代记录，使用“USER”来指代人员。

快照平面文件数据管理

SIS 框架支持通过 UI 馈送上传以及由 Learn 系统提供的一组 URL 来进行快照平面文件数据馈送上传。

通过系统管理员数据集成学生信息系统集成 UI 中的集成菜单，访问 HTTP 信息并上传馈送文件。

在这两种情况下，数据操作的行为是由集成配置和选定操作类型驱动的。  选择的数据操作类型将控制如何“解释”馈送中的数据，每个 URL 将提供不同的结果来满足您的集成的预期目标。

这些示例使用了快照框架 UI 上传馈送文件功能。要了解自动化或使用命令行/编程操作，请参阅快照平面文件自动化。

可以向 Learn 提供数据，然后随后进行更新、删除或修改。因此，您可以从最简单的数据集开始，随着机构的数据需求发生变化而扩充。

通过 UI 和 HTTP 可以访问以下操作。

操作 说明
存储 按集成配置存储或更新提供的记录。使用此操作类型时，馈送文件中包含的数据会在该集成所拥有的所有数据源中存储或更新（按配置设置）。有关数据“所有权”、数据源和密钥，请参阅 SIS 框架概述。
刷新 存储、更新或禁用在馈送和 Learn 中的记录。此操作会存储或更新在数据馈送中包含的数据，同时禁用未包含在数据馈送（与跨所有数据源的集成相关联）中的数据。
删除 禁用提供的记录。此操作将根据每个集成设置禁用包含在数据馈送中的记录，这些数据馈送与跨所有数据源的集成相关联。
按数据源进行完全刷新 禁用提供的记录。在 SP 12 中引入此操作仅执行与集成配置数据源关联的数据的完全刷新。此操作会更紧密地模拟命令行快照过程，以进行数据刷新。

与人员操作关联的对象包括：

人员 存储、完全刷新、删除、按数据源进行完全刷新
用户次要机构角色 存储、完全刷新、删除、按数据源进行完全刷新
用户关联 存储、完全刷新、删除、按数据源进行完全刷新

可在层次结构示例部分找到用户关联示例。

提供的示例是使用快照框架 UI 上传馈送文件功能进行演示的。要了解自动化或使用命令行/编程操作，请参阅快照平面文件自动化。

关于数据源密钥的提醒

所有数据对象都支持更改数据源密钥的功能（以便对该数据集进行分组），并可用于更改关联的数据源 - 注：这不是基于框架的数据馈送中的必填字段，除非特别指出，以下示例会假定集成已配置为使用单个数据源。

在 SP 12 中引入的功能使您可以独立于指定新数据源，来单独指定数据馈送中的数据源。

要了解详情，请参阅数据源密钥管理。

有关字段映射的说明

字段映射使您可以在传入数据存储到 Learn 之前对其进行更改。这样，您就可以完全控制所存储的数据，并且在提供的 SIS 数据不足的情况下，允许您符合 Learn 特定规则（例如：创建用户密码）。应用于用户对象字段时，关联的脚本将按用户来运行，并且在数据存储在 Learn 之前对其进行更改或提供。有关快照平面文件的字段映射的完整说明，请查看快照平面文件自定义字段映射。

有关密码的说明

必须输入密码才能登录 Learn，但不是人员数据馈送中的必填字段。如果数据馈送中未提供密码，则系统会生成随机 SHA512 密码，并将其存储在 Learn 数据库中。如果您使用的是外部（如 LDAP）验证，则这不是问题，但是如果您使用 Learn 数据库来存储用户登录密码，会发生什么情况？您必须提供用户创建时的密码，因为他们将无法登录。

如果您运行馈送并为随后更改其密码的用户设置密码，则其登录将会断开。是和否，在更新操作时，您可以选择该选项，以不更新密码字段。这将允许 Learn 在更新时保留当前密码。如果您未选择此选项，则密码将会更改，并且系统将需要通知用户发生更改。

人员操作示例

在较高层次上，您可以向所有用户数据操作应用三种 SIS 集成数据馈送模式，而选择的模式取决于您可以提供的数据和集成目标。  

  • 使用单个馈送文件，您可以创建或更新记录，或者禁用记录（存储）- 通过文件中提供的数据显式更改记录。
  • 使用单个馈送文件，您可以刷新数据 - 创建或更新并禁用（完全刷新）记录 - 通过文件中存在（创建/更新）数据或在文件中缺少数据来更改记录。
  • 利用文件组合，您可以用一种文件进行存储，用另一种文件设置可用性或禁用。

最后，这不是 SIS 馈送模式，但值得一提的是，您也可以利用 UI 中提供的数据源管理工具，单独基于 DSK 进行禁用和清除。当以此方式管理 SIS 提供的数据时，应格外谨慎。当清除那些过去从未或将来不再通过 SIS 提供的数据（例如，那些测试操作的结果数据）时，此功能非常有用。

基础要点：人员

所有用户帐户都需要一组基本信息来建立帐户。请参阅快照平面文件数据格式和快照平面文件标题了解此详细信息。

如果您当前使用的是 UI 批处理工具，现在切换到使用 SIS 框架并使用最小用户数据，则 SIS 框架的 UI 上传功能可让您更好地记录和报告数据上传，而无需更改您的数据收集过程。

简要数据

在 Learn 中创建用户帐户所需的最小数据集或标题包括：

  • EXTERNAL_PERSON_KEY - 此用户记录的唯一标识符。
  • DATA_SOURCE_KEY - 此记录中数据集的唯一标识符。注意：这可以在馈送中提供，也可以通过集成配置提供）
  • USER_ID- 用户的 ID - 用于以用户名形式登录，并且应与用户的 LDAP CN、NET ID 或其他外部标识符关联（如果您使用的是外部验证）。
  • FIRST_NAME - 用户的名字
  • LAST_NAME - 用户的姓氏
  • PASSWD- 此用户的密码
    有关动态指定密码（如果无法在数据馈送中提供）的示例，请参阅快照平面文件自定义字段映射。

每个集成配置的 SIS 框架提供非必填字段的默认值或忽略非必填字段。人员馈送非必填的两个有用字段为 EMAIL 和 SYSTEM_ROLE。对于通信，EMAIL 是必填的，通过 Learn 电子邮件为 Learn 用户提供电子邮件通知，因此，您应该考虑在馈送中提供此数据。SYSTEM_ROLE 默认为 NONE 配置设置。

快照平面文件数据格式对上述每个标题进行了全面介绍。

添加人员信息

存在两个案例用于添加人员信息。第一种情况是额外存储人员信息，从而导致添加或更新记录，这会在数据馈送中相应显示。第二种情况是刷新 Learn 中已存在的人员信息，从而导致新增或更新现有记录，这会在数据文件中相应显示，同时会禁用在数据文件中不存在的现有记录。

存储操作示例

示例 1：创建人员帐户

您希望在不影响现有帐户的情况下向 Blackboard Learn 添加用户。您已将集成配置为对所有传入数据使用相同的数据源。

先决条件

无。

最低数据馈送要求

EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME

解决方案

创建一个 PERSONS.txt 数据文件，其中包含您希望添加到系统中的每位人员的必填标题和关联数据。例如：

EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME
testPerson1|aanderson_test|changeme|Alpha|Anderson
testPerson2|bbrown_test|changeme|Beta|Brown
testPerson3|gcarlin_test|changeme|Gamma|Carlin

使用该 UI，利用存储操作，通过人员数据类型上传此文件。系统将创建用户帐户，您可以以用户身份登录。

后置条件

已创建 aanderson_test, bbrown_test, and ccarlin_test 的人员记录。

示例 2：更新用户帐户

您创建了用户帐户，并且需要对其进行更改。例如，前面的示例不包含任何用户的电子邮件地址。您有电子邮件地址 aanderson_test 。

先决条件

无 - 更新将发生在之前创建的记录中，Learn 中不存在记录的数据将导致创建记录。

解决方案

创建一个 PERSONS.txt 数据文件，其中包含您希望添加到系统中的每位人员的必填标题和关联数据。例如：

EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME|EMAIL
testPerson1|aanderson_test|changeme|...owhere.erehwon

由于存储仅对文件中包含的数据进行操作，因此先前提交的 bbrown_test 和 ccarlin_test 记录不受影响。

使用该 UI，利用存储操作，通过人员数据类型上传此文件。用户帐户将会更新。

后置条件

aanderson_test 的人员记录已更新为包括提供的电子邮件地址。

bbrown_test 和 ccarlin_test 的人员记录不受影响。

人员：完全刷新操作

COMPLETE REFRESH操作方式不同于 STORE。完全刷新执行两项操作，相当于对馈送文件中的数据以及集成拥有 LEARN 中的记录进行比较 - 存储新记录、更新现有记录或禁用 LEARN 中不在数据文件中的记录。

示例：完全刷新

SIS 提供的数据包含应有权访问 LEARN 的人员的完整快照。此数据包含要添加的人员记录、要更新的人员记录以及自上次完全刷新操作后已删除的记录，这些记录应根据配置进行相应的处理（禁用或清除）。

先决条件

无。

最低数据馈送要求

EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME

解决方案

使用上次存储操作中的数据并从数据馈送删除 gcarlin_test：

EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME
testPerson1|aanderson_test|changeme|Alpha|Anderson
testPerson2|bbrown_test|changeme|Beta|Brown

如果此集成管理了其他人员记录，则这些记录将被禁用或清除，因为在上面的数据馈送中没有这些记录。

后置条件

aanderson_test 的人员记录会保留，并且不受影响。

bbrown_test 的人员记录会保留，并已更新为包括提供的电子邮件地址

ccarlin_test 的人员记录已标记为已禁用或已准备好按集成配置进行清除。

人员：按数据源进行完全刷新操作

按数据源进行完全刷新会执行完全刷新操作，但会将受影响的数据限定为仅与集成的数据源相关联的数据。 

示例：按数据源进行完全刷新

SIS 提供的数据包含应有权访问 LEARN 的人员的完整快照。此数据包含要添加的 PERSON记录、要更新的 PERSON 记录，以及自上次 REFRESH 操作以来删除记录（应根据配置进行正确处理：禁用或清除）。此外，使用集成中定义的同一数据源，以此刷新中的所有数据作为目标，并且您希望仅影响与此数据源密钥相关的数据。

先决条件

无。

最低数据馈送要求

EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME

解决方案

使用上次存储操作中的数据并从数据馈送删除 gcarlin_test：

EXTERNAL_PERSON_KEY|USER_ID|PASSWD|firstname|lastname
testPerson1|aanderson_test|changeme|Alpha|Anderson
testPerson2|bbrown_test|changeme|Beta|Brown

后置条件

aanderson_test 的人员记录会保留，并且不受影响。

bbrown_test 的人员记录会保留，并已更新为包括提供的电子邮件地址

之前为 ccarlin_test 创建的人员记录已标记为已禁用或已准备好按集成配置进行清除。

如果还有其他人员记录由此集成管理，则这些记录不会被禁用或清除，因为这些记录在上述数据馈送中不存在，除非其具有与集成指定的相同数据源。

人员帐户可用性

人员帐户可用性设置允许将 LEARN 中的帐户设置为可以登录（可用）或不可登录（不可用）。请注意，这与禁用帐户不同，后者不仅会使帐户不可用，同时还意味着它对其他操作（如成员管理）也不可用。添加此数据馈送标题不会影响上面演示的存储、完全刷新、按数据源进行完全刷新用于创建人员记录的用法。

未提供可用性设置时，默认集成设置会应用于在创建/更新操作中可用的对象。

示例：人员帐户可用性

您的 SIS 控制用户对 LEARN 的访问可用性，而您的数据馈送则会指示用户是否可以单独访问 Learn。您希望使用 PERSON 创建/更新对单个用户的访问权限进行更改。

先决条件

无。

最低数据馈送要求

EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
AVAILABILITY_IND

解决方案

向您的数据馈送添加 AVAILABLE_IND 标题，如果可用，则提供单个字符 Y，如果不可用，则提供单个字符 N。

EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME|AVAILABLE_IND
testPerson1|aanderson_test|changeme|Alpha|Anderson|Y
testPerson2|bbrown_test|changeme|Beta|Brown|Y
testPerson3|gcarlin_test|changeme|Gamma|Carlin|N
testPerson4|ddarling_test|changeme|Delta|Darling|Y

后置条件

存储

仅为 aanderson_test、bbrown_test 和 ccarlin_test 更新人员记录（这些记录是以前创建的），并且创建了 ddarling_test。

完全刷新

已为 aanderson_test、bbrown_test 和 ccarlin_test 更新人员记录（这些记录是以前创建的），并且创建了 ddarling_test。将禁用所有其他记录或将其标记为清除，因为其在上述数据馈送中不存在。

按数据源进行完全刷新

已为 aanderson_test、bbrown_test 和 ccarlin_test 更新人员记录（这些记录是以前创建的），并且创建了 ddarling_test。

如果还有其他人员记录由此集成管理，则这些记录不会被禁用或清除，因为这些记录在上述数据馈送中不存在，除非其具有与集成指定的相同数据源。按数据源进行完全刷新仅对集成数据源的记录进行操作。

禁用人员记录

在 Learn 中禁用人员记录将使得登录时无法访问该记录（已禁用状态会覆盖可用性设置），并且还使该记录对 UI 操作不可访问。例如，您不能通过 UI 向课程添加管理禁用的人员。此外，要从 Learn 中清除记录，必须先禁用该记录。

禁用记录和后续清除将从 Learn 中删除对该记录的所有引用。Blackboard 建议仅在一段时间之后清除已禁用的记录，具体的时间段由您的企业自行决定，因为法律惯例可能会要求提供活动记录。

禁用记录有两种方式：通过刷新操作的馈送数据排除来禁用，通过使用馈送标题 ROW_STATUS 来禁用。

使用刷新操作的上述人员操作会演示通过排除来禁用，以下情况和示例会演示通过使用 ROW_STATUS 来禁用。

示例：禁用人员记录

学生入学或不再需要有权访问 Learn。您需要完全删除其对 Learn 的访问权限以及在 Learn 中的存在（将记录设为不可用会仅限制登录）。如果您使用的是存储操作，要禁用用户，您必须使用 ROW_STATUS 标题明确禁用该课程。这也适用于 SIS 馈送范围以外的手动操作。

先决条件

目标记录存在于 Learn 系统中。

最低数据馈送要求

EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
ROW_STATUS

解决方案

向您的数据馈送添加 ROW_STATUS 标题，如果已启用，则提供 ENABLED 条目，如果已禁用，则提供 DISABLED 条目。

EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME|ROW_STATUS
testPerson1|aanderson_test|changeme|Alpha|Anderson|enabled
testPerson2|bbrown_test|changeme|Beta|Brown|enabled
testPerson3|gcarlin_test|changeme|Gamma|Carlin|disabled
testPerson4|ddarling_test|changeme|Delta|Darling|enabled

后置条件

存储

仅为 aanderson_test、bbrown_test、ccarlin_test 和 ddarling_test 创建或更新人员记录，并且 ROW_STATUS 已明确更新。

完全刷新

将为aanderson_test、bbrown_test、ccarlin_test, 和 ddarling_test 创建或更新人员记录；将禁用所有其他记录或将其标记为清除，因为其在上述数据馈送中不存在。

按数据源进行完全刷新

已为 aanderson_test、bbrown_test 和 ccarlin_test 更新人员记录（这些记录是以前创建的），并且创建了 ddarling_test。

如果还有其他人员记录由此集成管理，则这些记录不会被禁用或清除，因为这些记录在上述数据馈送中不存在，除非其具有与集成指定的相同数据源。按数据源进行完全刷新仅对集成数据源的记录进行操作。

按数据源进行完全刷新

为 aanderson_test、bbrown_test、ccarlin_test 和 ddarling_test 创建或更新人员记录，并且 ROW_STATUS 已明确更新。

如果还有其他人员记录由此集成管理，则这些记录不会被禁用或清除，因为这些记录在上述数据馈送中不存在，除非其具有与集成指定的相同数据源。按数据源进行完全刷新仅对集成数据源的记录进行操作。

管理用户次要机构角色

作为社区许可证持有者，您可以访问您可以指定给用户的其他角色，这些角色对于管理对社区门户中的资料和标签的访问非常有用。

管理次要角色是独立于创建或更新用户的单独活动，因此对次要角色的管理不是人员创建/更新数据馈送的一部分。

示例：添加用户次要机构角色

您需要提供特定于工程学院学生和教工的门户内容。

先决条件

您已使用系统管理员 UI （请参阅 ...）创建了名为“ENGINEERING_STUDENT”的新机构角色

最低数据馈送要求

EXTERNAL_PERSON_KEY
ROLE_ID

解决方案

创建包含要创建/更新的记录的 Institutional_Role 馈送。

EXTERNAL_PERSON_KEY|ROLE_ID
testPerson1|engineering_student
testPerson2|engineering_faculty
testPerson3|engineering_faculty
testPerson4|engineering_student

与其他数据对象一样，您还可以提供 ROW_STATUS 来启用或禁用人员访问与次要角色相关联的内容。例如：

EXTERNAL_PERSON_KEY|ROLE_ID|ROW_STATUS
testPerson1|engineering_student|enabled
testPerson2|engineering_faculty|enabled
testPerson3|engineering_student|disabled

后置条件

存储

使用次要机构角色，仅为 aanderson_test、bbrown_test、ccarlin_test 和 d 创建或更新了次要机构角色记录。

完全刷新

将为 aanderson_test、bbrown_test、ccarlin_test 和 d 创建或更新次要机构角色记录；将禁用所有其他记录或将其标记为清除，因为其在上述数据馈送中不存在。

按数据源进行完全刷新

为 aanderson_test、bbrown_test、ccarlin_test 和 d 创建或更新了次要机构角色记录。

如果还有其他人员记录由此集成管理，则这些记录不会被禁用或清除，因为这些记录在上述数据馈送中不存在，除非其具有与集成指定的相同数据源。按数据源进行完全刷新仅对集成数据源的记录进行操作。

观察员

旁听者是一种特殊用户，该用户帐户可以对另一个用户帐户进行监督或观察。旁听者可以登录并查看与其相关联的用户课程和活动。

旁听者帐户需要与创建帐户的用户相同的信息，并且具有附加的“用户关联管理”层（即通过链接两个帐户的 external_person_keys，旁听者与一个用户帐户相关联）。

旁听者帐户的创建方式与您遵照机构的数据处理要求创建任何用户帐户完全一样。

示例 1：创建旁听者关联

您希望将学生与其父（或其他合适用户）帐户关联，以便可以观察活动。

先决条件

您已创建了由 external_person_key（本示例中的 test_student_100）标识的学生和由 external_person_key （本示例中的 test_student_100_observer 和 test_student_200_observer）标识的旁听者。

最低数据要求

旁听者的 external_person_key： EXTERNAL_OBSERVER_KEY

被旁听学生的 external_person_key： EXTERNAL_USER_KEY

解决方案

创建一个数据文件，其中包含旁听者的 external_person_key 和学生的外部人员密钥。

EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_200_observer|test_student_100

使用该 UI，利用存储操作，通过旁听者关联数据类型上传此文件。将创建关联，您可以以旁听者身份登录并查看学生的课程活动。

示例 2：更新旁听者关联记录

您需要更改关联。

先决条件

您已在 test_student_200_observer 和 test_student_100 之间创建了关联，但是关联的学生帐户必须为 test_student_200。

解决方案

创建包含修订版的文件。

EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_200_observer|test_student_200

使用该 UI，利用存储操作，通过旁听者关联数据类型上传此文件。

后置条件

将更新关联，您可以以旁听者身份登录并查看正确学生的课程活动。

示例 3：禁用旁听者关联记录

当不需要再使用一个旁听者关联，您希望禁用它。

先决条件

您已在学生和旁听者之间创建关联。

解决方案

（利用此示例话题中使用的数据）

您以前使用存储方法和以下文件创建了关联：

EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_200_observer|test_student_200

存在两种与馈送相关的模式，以满足根据您的需求禁用旁听者关联的要求：

  1. 您想要禁用与当前集成/数据源相关联的旁听者关联的子集。
  2. 您希望在存储或更新其他记录时禁用旁听者关联的子集。
禁用旁听者关联的子集

要禁用数据子集，您可以创建关联馈送并将其上传到删除操作。例如：

要删除工作数据集中 test_student_100_observer|test_student_100 之间的关联，您需要创建包含以下内容的馈送文件，然后使用删除操作将其上传：

EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_200_observer|test_student_200

在存储新的/现有关联时禁用旁听者关联的子集

要禁用也允许更新现有或存储新关联的数据子集，您可以创建包含现有和任何新关联的关联文件，然后删除要禁用的关联文件并使用完全刷新操作上传。例如，使用工作集：

EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_200_observer|test_student_200

我们希望禁用 test_student_200_observer|test_student_200 关联，因此该文件将仅包含 test_student_100_observer|test_student_100 关联。如果我们还想添加两个新关联（满足用户帐户已创建的先决条件），我们会上传以下内容：

EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_300_observer|test_student_300
test_student_400_observer|test_student_400

后置条件

test_student_200_observer|test_student_200 的记录已禁用。

了解详细信息

SIS 框架概述

快照平面文件标题描述

快照平面文件数据格式

快照平面文件自动化