SIS Feed Files

The data that is fed into Blackboard Learn to create users, courses, update records and so on exists in a "feed file." Snapshot Feed Files can be character-delimited flat files or XML files that conform to IMS standards. Blackboard adheres to the Global Community XML encoding standards, which commonly uses UTF-8. This topic reviews in detail the format of Snapshot flat files and provides a link to information about IMS standards for XML files. For a complete list of feed file headers and object types, see SIS Feed File Headers and Object Types.

As of Blackboard Learn Release 9.1, SP9, any SIS Integration feed operation that creates or edits an object (any non-delete SIS feed operation) should "enable" the objects (courses, users, and so on) in the feed, unless the feed specifically says that the object should be "disabled".

To accept Multi-byte information, files must be in Unicode format. All Unicode formatted files must include the Byte Order Mark (BOM). If a BOM is not specified, the system reads it as ISO-8859-1. The supported formats are as follows:

UTF-8
UTF-16LE
UTF-16BE
ISO-8859-1

ASCII is also a supported format, since it is a subset of ISO-8859-1.

Delimiters and escape characters

The information in this topic applies only to command line feeds. Updating the Properties File does not affect anything in the SIS Integration user interface in Blackboard Learn.

For data to be parsed correctly from a Feed File, Snapshot needs to know where the data for each different field ends. A character that does not regularly appear in the data is usually selected as the delimiter - the character that separates one field from another in a row. The pipe ( | ) character is the default delimiter character in the Properties File.

Occasionally the delimiter character will appear in the data. Unless the system knows that this particular instance of the delimiter character is actually part of the data itself and not denoting the division of a field, the data feed will contain errors or fail all together. To tell the system that a particular delimiter character is part of the data set it must be "escaped".

To be able to escape a delimiter, an escape character is defined in the Properties File. The slash ( / ) character is the default escape character.

Change the delimiter

To change the default delimiter character, edit the Properties File. Any SQL character may be used as a delimiter. Find the line in the Properties File that reads:

# delimiter used for parsing snapshot files
data.delimiter=|

Change the character on the right side of the equals ( = ) sign to the desired character. If this character appears in a data field, it must be escaped in every field where it occurs. For this reason, selecting a character that doesn't commonly appear in the data fields.

Change the escape character

To change the default escape character, edit the Properties File. Find the line in the Properties File that reads:

# Determines character used to escape delimiter
escape.character=/

Change the character on the right side of the equals ( = ) sign to the desired character. This character would precede any delimiter character that appears in all data fields. For example, if the hyphen ( - ) has been set as the delimiter, every time a hyphen appeared in a data field it would be escaped by placing the slash ( \ ) character before it.

Example:

In the following example, the last name is Smith-Jones, so the hyphen in the last name must be escaped:

EXTERNAL_PERSON_KEY-USER_ID-SYSTEM_ROLE-FIRSTNAME-LASTNAME-EMAIL-INSTITUTION_ROLE
2000-jsmithjones100-none-John-Smith/...ng.com-Student

Snapshot flat feed file format

The Snapshot Feed File can be a "flat file," another term for a delimited text file. A Feed File may include information about any of the 10 entities that are transferred to Blackboard Learn. A Feed File consists of a header row that identifies each of the columns or fields of data followed by one or more rows of data records.

Header row

The Header Row in a Feed File contains Field Names, which are the exact names of the fields included in the file. These names are listed in the tables in the feed file topics, starting with Category Data Feed Elements. The header fields are delimited with the same character as the data records.

Fields can appear in the header row in any order, but fields not recognized by Blackboard Learn cannot be included or errors will occur or the operation will fail completely.

Snapshot feed files work in both Right to Left and Left to Right operating system environments. The order of the fields in the header row is not important, only that it matches the order of the data rows. The delimiter for Snapshot feed files used in a Right to Left environment must be a Tab. The commonly used pipe ( | ) can cause some fields to reverse order, misaligning the header row with the data rows.

Each Feed File type has a minimum number of required fields that need to be identified in the header row.

The minimum required fields for a user Feed File are:

EXTERNAL_PERSON_KEY
USER_ID
SYSTEM_ROLE
FIRSTNAME
LASTNAME
EMAIL
INSTITUTION_ROLE

The minimum required fields for a Course or Organization Feed File are:

COURSE_ID
EXTERNAL_COURSE_KEY
COURSE_NAME

The minimum required fields for an enrollment or staff Students Feed File are:

EXTERNAL_COURSE_KEY
EXTERNAL_PERSON_KEY
ROLE

Example: Header Row for a User Feed File

Data rows

After the header row, data records, one per line are added to the Feed File. Records are separated by a carriage return, a linefeed or the combination of the two. The record separator is not configurable.

Some data feed elements have sets of string constants for their possible values. For example, the attribute Institution_Role maps to coded characters in the database.

Information that is not given (left blank) for fields that are included in the header is not changed during the operation. Exceptions:

If the password field is null the User ID will be set as the password. To clear a field, enter a single space.
To clear the email field, enter a single @ symbol, as it is a requirement. If the email address field is left blank, the following error will be shown "(!)Invalid value provided: Email. Review documentation".

Any fields in the Feed File not found in the feed file topics, starting with Category Data Feed Elements, will be ignored.

Data contained in each record must conform to values that are acceptable to Blackboard Learn. For acceptable values for each field, see the feed file topics, starting with Category Data Feed Elements.

The delimiter for all Snapshot feed files to be used in a Right to Left environment must be a Tab. The commonly used pipe ( | ) delimiter can cause some fields to reverse order. The order of the data fields in the data rows must match the order of the fields in the header row. Additionally, any data that is entered as mixed orientation, some text formatted left to right and some formatted right to left in the same file will cause data errors or cause the operation to fail.

Example: Data Rows in a Delimited User Feed File

Delete records file

A "Delete Records" file will be the file format used to purge unwanted data from Blackboard Learn and may encompass information about any of the ten entities that are to be transferred to the Blackboard database. The file need only contain certain key fields to delete data records from Blackboard Learn. For a list of the required fields for each entity type, see the feed file topics, starting with Category Data Feed Elements. The file format for the Delete Records file is as follows:

Header: Field Names. The exact names of the fields included in the file.

Example: (Membership)

Invalid data

Incorrectly formatted data is handled as follows:

Strings that exceed the specified max length for that column will be truncated. Data Source Keys that exceed the specified max length for that column will cause the record to fail.
Data types that cannot be converted (such as dates) are ignored. (They are treated as a space or as missing.)
Invalid column headers are ignored.

Unsupported feed elements will not cause the feed to fail-they are ignored to preserve backward compatibility with older feed generators.

Snapshot XML feed file format

Compared to a flat file feed, an XML Snapshot file has increased flexibility in that the XML files can process one data type at a time, or combine multiple data types to be processed at once. While Blackboard Learn does not validate against the XML Data Dictionary defined in Data Format Tables for XML Files, the code must be well-formed, meaning each nested tag must be properly closed.

The Snapshot Tool will process IMS compliant XML files, version 1.01. Refer to the IMS website for information about IMS standards for XML files.

Since entities in the XML file are typed, there are no specific requirements to separate entities into separate Feed Files. However, the action and data source attributes specified in the IMS standard are ignored. In processing the IMS XML format, the Blackboard Learn Snapshot Tool still requires the same logic and workflow as used with a flat file.

XML template tags

The following refer to specific tags in the XML template:

Extension tags: These tags are not supported in the IMS specifications; they are only supported by Blackboard Learn. As they are adopted by the IMS project, Blackboard will phase them into proper XML definition.
Categories and Category Memberships: These are not IMS data types and are not supported by IMS; they are supported by Blackboard Learn.

The following tips are helpful for troubleshooting Snapshot XML files:

If a user fails to be created in an XML file then their membership will also fail. Many aspects of the XML file are related, therefore is one area fails, it may cause others to also fail.
Blackboard recommends using an XML viewer when viewing the .invalid file (error log). This file should be referenced if an error occurs.

XML feed file example

For an example of an XML Feed File, see Data Format Tables for XML Files.

Llengua