Skip to main content

快照平面文件用户示例

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

注意

这些示例基于集成配置 UI 中可见的默认 Blackboard 设置。更改这些配置元素将导致示例结果发生更改。有关这些设置的说明,请参阅学生信息系统框架概述快照平面文件集成配置。此外,除非另有说明,否则假定集成已配置为对所有传入数据使用相同的数据源。

用户

用户数据是主要信息集,用于描述谁有权访问 Blackboard、他们在贵机构中的角色以及他们在 Blackboard 系统中的角色。在 SIS 数据用户对象的上下文中,通常称为“PERSON”,这会反映在现有标准中。在许多这些标准之前,Blackboard 使用“PERSON”和“USER”来根据上下文来引用与用户相关的记录。以下示例将使用“PERSON”来指代记录,使用“USER”来指代人员。

快照平面文件数据管理

SIS 框架支持通过 UI Feed 上传和 Blackboard 系统提供的一组 URL 上传快照平面文件数据源。

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

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

注意

这些示例使用了快照框架 UI 上传馈送文件功能。有关自动化或以其他方式使用命令行/编程作,请参阅快照平面文件自动化

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

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

警告

请注意,使用“完全刷新”或“按数据源完全刷新”作上传简短的更正文件可能会无意中导致数据被删除或批量禁用。为防止这种情况发生,我们不鼓励手动使用作类型“完全刷新”或“按数据源完全刷新”。默认情况下,这些选项在上传源文件页面上不可用。但是,如果同时启用这两个选项,请选中“作类型”下的“启用高级选项”复选框。

操作

描述

存储

按集成配置存储或更新提供的记录。使用此操作类型时,馈送文件中包含的数据会在该集成所拥有的所有数据源中存储或更新(按配置设置)。有关数据“所有权”、数据源和密钥,请参阅学生信息系统框架概述

完全刷新

存储、更新或禁用在 Feed 和 Blackboard 中提供的记录状态。此操作会存储或更新在数据馈送中包含的数据,同时禁用未包含在数据馈送(与跨所有数据源的集成相关联)中的数据。您必须选择启用高级选项才能在手动上传文件时使用此选项。

删除

禁用提供的记录。此操作将根据每个集成设置禁用包含在数据馈送中的记录,这些数据馈送与跨所有数据源的集成相关联。

按数据源进行完全刷新

禁用提供的记录。在 SP 12 中引入此操作仅执行与集成配置数据源关联的数据的完全刷新。此操作会更紧密地模拟命令行快照过程,以进行数据刷新。您必须选择启用高级选项才能在手动上传文件时使用此选项可用

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

警告

请注意,使用完全刷新按数据源完全刷新作上传简短的更正文件可能会无意中导致数据被删除或批量禁用。为防止这种情况,我们不鼓励手动使用作类型完全刷新按数据源完成刷新。默认情况下,这些选项在上传源文件页面上不可用。但是,如果同时启用这两个选项,请选中作类型下的复选框启用高级选项

人员

存储、完全刷新、删除、按数据源进行完全刷新

用户次要机构角色

存储、完全刷新、删除、按数据源进行完全刷新

用户关联

存储、完全刷新、删除、按数据源进行完全刷新

注意

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

提供的示例是使用快照框架 UI 上传馈送文件功能进行演示的。有关自动化或以其他方式利用命令行/编程作,请参阅快照平面文件自动化

关于数据源密钥的提醒

所有数据对象都支持更改该数据集分组的<em>数据源密钥</em>,并可用于更改关联的数据源 - 注意:这不是基于框架的数据馈送中的必填字段,除非另有说明,否则以下示例假定集成配置为使用单个数据源。

若要了解详细信息,请参阅数据源密钥管理

关于字段映射的说明

字段映射提供了在将传入数据存储在 Blackboard 中之前更改传入数据的功能。这使您可以完全控制存储的数据,并使您能够在向您提供的 学生信息系统 数据不足时满足 Blackboard 特定规则,例如创建用户密码。当应用于用户对象字段时,关联的脚本将按用户运行,在数据存储在 Blackboard 中之前更改或提供数据。快照平面文件的字段映射的完整说明在快照平面文件字段映射中提供了。

有关密码的说明

登录 Blackboard 需要密码,但不是 PERSON 数据源中的必填字段。如果数据馈送中未提供密码,则会生成随机的 SHA512 密码并将其存储在 Blackboard 数据库中。如果您使用外部(如 LDAP)身份验证,则这不是问题,但如果您使用 Blackboard 数据库存储用户登录密码,会发生什么情况?您必须提供用户创建时的密码,因为他们将无法登录。

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

人员操作示例

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

  • 使用单个馈送文件,您可以创建或更新记录,或者禁用记录(存储)- 通过文件中提供的数据显式更改记录。

  • 使用单个馈送文件,您可以刷新数据 - 创建或更新并禁用(完全刷新)记录 - 通过文件中存在(创建/更新)数据或在文件中缺少数据来更改记录。

  • 利用文件组合,您可以用一种文件进行存储,用另一种文件设置可用性或禁用。

最后,这不是学生信息系统提要模式,但值得一提的是,您还可以使用 UI 中可用的<数据源管理>工具仅基于 DSK 禁用和删除。当以此方式管理 SIS 提供的数据时,应格外谨慎。这在删除从未或不再通过学生信息系统提供的数据(例如测试作的结果数据)时非常有用。

只是基础知识:人

所有用户帐户都需要一组基本信息来建立帐户。快照平面文件数据格式快照平面文件头中详细介绍了这组信息。

注意

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

数据简介

在 Blackboard 中创建用户帐户所需的最小数据集或标头包括:

  • EXTERNAL_PERSON_KEY - 此用户记录的唯一标识符。

  • DATA_SOURCE_KEY- 记录中数据集的唯一标识符。注意:这是在源中或通过集成配置提供的)

  • USER_ID - 用户的 ID - 用于以用户名形式登录,并且应与用户的 LDAP CN、NET ID 或其他外部标识符关联(如果您使用的是外部验证)。

  • FIRST_NAME - 用户的名字

  • LAST_NAME - 用户的姓氏

  • PASSWD - 此用户的密码

    有关在数据馈送中提供密码时动态分配密码的示例,请参阅快照平面文件自定义字段映射

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

注意

这些标头中的每一个都在快照平面文件数据格式中进行了完整描述。

添加人员信息

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

存储操作示例
示例 #1:创建个人帐户

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

先决条件

无。

最低数据馈送要求
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_testbbrown_testgcarlin_test的人员记录。

示例 #2:更新用户帐户

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

先决条件

无 - 更新将对以前创建的记录进行更新,如果记录在 Blackboard 中不存在,则包含的数据将导致创建记录。

解决方案

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

EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME|EMAIL testPerson1|aanderson_test|changeme|Alpha|Anderson|aanderson@test.com

注意

由于 STORE 仅对文件中包含的数据进行作,因此之前提交的Bbrown_testgcarlin_test记录不受影响。

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

后置条件

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

bbrown_testgcarlin_test的人员记录不受影响。

人员:完成刷新作

警告

请注意,使用完全刷新按数据源完全刷新作上传简短的更正文件可能会无意中导致数据被删除或批量禁用。为防止这种情况,我们不鼓励手动使用作类型完全刷新按数据源完成刷新。默认情况下,这些选项在上传源文件页面上不可用。但是,如果同时启用这两个选项,请选中作类型下的复选框启用高级选项

COMPLETE REFRESH操作方式不同于 STORE。COMPLETE REFRESH 执行两项作,相当于比较源文件中的数据与集成拥有的 Blackboard 中的记录 - 存储新记录、更新现有记录或禁用 Blackboard 中不在数据文件中的记录。

示例:完全刷新

您的 学生信息系统 提供的数据包含应有权访问 Blackboard 的人员的完整快照。此数据包含要添加的人员记录、要更新的人员记录以及自以前的 COMPLETE 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的人员记录以包含电子邮件地址。

每个集成配置,gcarlin_test的人员记录被标记为已禁用或准备删除。

人员:按数据源作完成刷新

警告

请注意,使用完全刷新按数据源完全刷新作上传简短的更正文件可能会无意中导致数据被删除或批量禁用。为防止这种情况,我们不鼓励手动使用作类型完全刷新按数据源完成刷新。默认情况下,这些选项在上传源文件页面上不可用。但是,如果同时启用这两个选项,请选中作类型下的复选框启用高级选项

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

示例:按数据源完成刷新

您的 学生信息系统 提供的数据包含应有权访问 Blackboard 的人员的完整快照。此数据包含要添加的人员记录、要更新的人员记录以及自以前的 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的人员记录以包含电子邮件地址。

根据每个集成配置,先前为 gcarlin_test 创建的 人员记录 被标记为已禁用或准备删除。

如果其他人员记录由此集成管理,则它们不会因上述数据馈送中缺失而被禁用或删除,除非它们具有与集成指定的相同数据源。

人员帐户可用性

警告

请注意,使用完全刷新按数据源完全刷新作上传简短的更正文件可能会无意中导致数据被删除或批量禁用。为防止这种情况,我们不鼓励手动使用作类型完全刷新按数据源完成刷新。默认情况下,这些选项在上传源文件页面上不可用。但是,如果同时启用这两个选项,请选中作类型下的复选框启用高级选项

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

注意

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

示例:个人帐户可用性

您的 学生信息系统 控制用户的 Blackboard 访问可用性,并且您的数据馈送指示用户是否单独有权访问 Blackboard。您希望使用 PERSON 创建/更新对单个用户的访问权限进行更改。

先决条件

无。

最低数据馈送要求
EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
AVAILABILE_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_testbbrown_testgcarlin_test 的人员记录(它们之前已创建)并创建ddarling_test

完全刷新

将更新 aanderson_testbbrown_testgcarlin_test 的人员记录(它们是以前创建的)并创建ddarling_test。所有其他记录将被禁用或标记为删除,因为它们在上述数据馈送中不存在。

按数据源进行完全刷新

将更新 aanderson_testbbrown_testgcarlin_test 的人员记录(它们是以前创建的)并创建ddarling_test

如果其他人员记录由此集成管理,则它们不会因上述数据馈送中缺失而被禁用或删除,除非它们具有与集成指定的相同数据源。按数据源进行完全刷新仅对集成数据源的记录进行操作。

禁用人员记录

在 Blackboard 中禁用人员记录会使其无法登录(禁用状态将覆盖可用性设置),并且还会使 UI作无法访问该记录。例如,您不能通过 UI 向课程添加管理禁用的人员。此外,要从 Blackboard 中删除记录,必须首先禁用该记录。

注意

禁用记录并随后删除记录会从 Blackboard 中删除对该记录的所有引用。Blackboard 建议仅在您的业务和/或法律惯例确定一段时间后删除残疾记录,否则可能需要活动记录。

禁用记录可能遵循两种模型:通过 REFRESH作上的源数据排除来禁用,以及通过使用源头ROW_STATUS禁用。

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

示例:禁用人员记录

学生入学或不再需要访问 Blackboard。您需要完全删除他们对 Blackboard 的访问权限和状态(与使记录不可用不同,后者仅限制登录)。如果您使用的是存储操作,要禁用用户,您必须使用 ROW_STATUS 标题明确禁用该课程。这也适用于 SIS 馈送范围以外的手动操作。

先决条件

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

最低数据馈送要求
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_testbbrown_testgcarlin_testddarling_test 的人员记录,并显式更新ROW_STATUS。

完全刷新

创建或更新 aanderson_testbbrown_testgcarlin_testddarling_test 的人员记录;所有其他记录将被禁用或标记为删除,因为它们在上述数据馈送中不存在。

按数据源进行完全刷新

创建或更新 aanderson_testbbrown_testgcarlin_testddarling_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_testbbrown_testgcarlin_testd 的辅助机构角色记录才会使用辅助机构角色创建或更新。

完全刷新

创建或更新aanderson_testbbrown_testgcarlin_testd 的辅助机构角色记录;所有其他记录将被禁用或标记为删除,因为它们在上述数据馈送中不存在。

按数据源进行完全刷新

创建或更新aanderson_testbbrown_testgcarlin_testd 的辅助机构角色记录。

如果其他人员记录由此集成管理,则它们不会因上述数据馈送中缺失而被禁用或删除,除非它们具有与集成指定的相同数据源。按数据源进行完全刷新仅对集成数据源的记录进行操作。

观察员

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

观察者帐户需要与用户相同的信息来创建帐户,并具有额外的“用户关联管理”层,其中观察者通过链接两个帐户的external_person_keys与用户帐户相关联。

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

示例 #1:创建观察者关联

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

先决条件

您创建了由external_person_key标识的学生(本例中为 test_student_100)和由external_person_key标识的观察者(本例中为 test_student_100_observertest_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_observertest_student_100之间创建了关联,但关联的学生帐户必须test_student_200

解决方案

创建包含修订版的文件。

EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY test_student_200_observer|test_student_200

使用UI通过观察者关联数据类型(Observer Association Data Type)上传此文件,并使用存储作

后置条件

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

示例 #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 的记录被禁用。

了解更多信息