Learning Environment Connector Developer Guide - Snapshot XML - EduGarage (Blackboard Developers Network)

XML format

The LMS needs to generate an XML snapshot for use in Blackboard Learn. The document used must be well-formed although it does not require DTD validation.
The following elements are require for population of User, Course, and Enrollment information.

Document Header

element name	description
enterprise	Packaging element for the data components being provided.

Integration Details

element name	description
properties	Responsible for identifying the integration aligned with a 3rd party Learning System.
integrationId	GlcId associated with the LmsIntegration record.

Example:

<properties>
  <integrationId>foo</integrationId>
</properties>

Common Element

element name	description
sourcedid	Packaging element for identifying information for the associated entity.
source	Key representing "source" of the data from the 3rd party integration.
id	Unique key identifying entity.

User Details

element name	description
person	Packaging element for user information.
recstatus	(optional). 1=add, 2=update, 3=delete. If not specified, record will be treated as an add if the user doesn't exist yet, and an update if it does exist.
sourcedid	See Common element.
userid	User name for authentication attempt for user.
n	Packaging element for name information.
family	Last name for user.
given	First name for user.
x_bb_password	(optional) User's password. If specified, this value will be passed to MigrationProvider.convertPassword to have it converted into one of the password types that Bb9 supports.

Example:

<person recstatus="1">
  <sourcedid>
    <source>vendorA</source>
    <id>user_uid</id>
  </sourcedid>
  <userid>username</userid>
  <name>
    <n>
      <family>last name</family>
      <given>first name</given>
    </n>
  </name>
  <extension>
    <x_bb_password>Uw.xDeUgDOwgo</x_bb_password>
  </extension>
</person>

Course Details

element name	description
group	Packaging element for course information.
recstatus	(optional). 1=add, 2=update, 3=delete. If not specified, record will be treated as an add if the course doesn't exist yet, and an update if it does exist.
sourcedid	See common element.
description	Packaging element for listing information for the course.
short	Represents course id attribute.
long	Represents title of the associated course.
full	Represents the description of the associated course.

Example:

<group recstatus="1">
  <sourcedid>
    <source>vendorB</source>
    <id>course_uid</id>
  </sourcedid>
  <description>
    <short>course id</short>
    <long>course title</long>
    <full>course description</full>
  </description>
</group>

Enrollment Details

element name	description
membership	Packaging element for enrollment information.
sourcedid	Identifying information for the associated course record. See common element.
member	Packaging element for associated user information.
sourcedid	Identifying information for the associated user record. See common element.
role	Packaging element for students membership role within the course.
roletype	XML enumerated attribute identifying the membership role. See values below.
recstatus	(optional). 1=add, 2=update, 3=delete. If not specified, record will be treated as an add if the enrollment doesn't exist yet, and an update if it does exist.

role type values	description
0	None
1	Student
2	Instructor
3	Course Builder
6	Teaching Assistant
8	Grader
9	Guest

Example:

<membership>
  <sourcedid>
    <source>vendorB</source>
    <id>course_uid</id>
  </sourcedid>
  <member>
    <sourcedid>
      <source>vendorA</source>
      <id>user_uid</id>
    </sourcedid>
    <role roletype="01" recstatus="1"/>
  </member>
</membership>

Sample integration.xml

<?xml version="1.0" encoding="UTF-8" ?>
<enterprise>
  <properties>
    <integrationId>SampleIntegration</integrationId>
  </properties>
  <person>
    <sourcedid>
      <source>vendorA</source>
      <id>user_uid</id>
    </sourcedid>
    <userid>username</userid>
    <name>
      <n>
        <family>last name</family>
        <given>first name</given>
      </n>
    </name>
  </person>
  <group>
    <sourcedid>
      <source>vendorB</source>
      <id>course_uid</id>
    </sourcedid>
    <description>
      <short>courseid</short>
      <long>course title</long>
      <full>course description</full>
    </description>
  </group>
  <membership>
    <sourcedid>
      <source>vendorB</source>
      <id>course_uid</id>
    </sourcedid>
    <member>
      <sourcedid>
        <source>vendorA</source>
        <id>user_uid</id>
      </sourcedid>
      <role roletype="01"/>
    </member>
  </membership>
</enterprise>

Bulk data export

In addition to the runtime data feed, it is recommended that a mechanism be provided to perform a bulk export of all users, courses, and enrollments on the server. This can then be imported into Blackboard Learn using the snapshot tool. This is useful for LMS servers that already contain records when integration is configured. Existing records will be sent to Blackboard Learn using the bulk export, and any future record events will be sent using the Data Feed.

Windows

cd c:\blackboard\apps\snapshot\bin
snapshot.cmd -f XML_MANUAL_LMS_INT -t c:\data\bulk_snapshot.xml -C ..\data\snapshot.properties

Unix

cd /usr/local/blackboard/apps/snapshot/bin
./snapshot.sh -f XML_MANUAL_LMS_INT -t /usr/local/data/bulk_snapshot.xml -C ../data/snapshot.properties

Note: XML_SNPSHT_LMS_INT is also a valid function to use. XML_MANUAL_LMS_INT ignores any records that are not in the data file but are in the system, while XML_SNPSHT_LMS_INT disables records that are not in the data file but are in the system.

User Merging and Conflict Resolution

In certain cases, users specified in the incoming XML file conflict with users that already exist on the Blackboard Learn server. When this occurs, first determine whether the two users are the same person, using the following rules:

Look for existing integrated users using the IMS SourcedId.source and SourcedId.Id. If an existing record is found using this criteria, the records will be merged using these guidelines:
- The incoming integration will be added to their list of existing integrations.
- Authentication will be handled by the integration with the highest delegation priority.
If no integrated user could be found, conflict resolution will be applied and then a new account created:
- If the integration has been configured to always resolve conflicts, the incoming username will be changed using the rules specified for this integration by the System Administrator.
- If conflict resolution is only applied when conflicts actually occur, we will check to see whether the incoming IMS SourcedId.Id conflicts with an existing batch_uid, and whether the incoming username conflicts with an existing username.
- If (after applying conflict resolution) the user account still conflicts with existing records, an error will be thrown.