Skip to main content
pdf?stylesheet=default
Blackboard Help

Snapshot Flat File Data Format

If you are familiar with Legacy Snapshot (the Command Line Snapshot Tools) the SIS Framework Flat File type brings no change to the format other than the addition of headers for the new data objects supported and the requirement for including a few previously optional fields.

The same rules of order apply for Snapshot Flat Files as for Legacy Snapshot – in short feeds will not succeed unless dependencies have been met. For example, a membership feed will not succeed until both the user feed and the course feed containing the membership related objects has been processed or a child course may not be tied to a parent course until the master course (parent) has been created. This logic applies to terms and nodes as well.

Also note that system behavior on processing data posted to the endpoints is configurable via the integration edit page.

For a complete description of URLs and their functions, see Snapshot Flat File.


ANGEL clients switching to Learn

There are differences between Learn and ANGEL data feed formats. These differences are called out in the ANGEL to LEARN data mapping knowledge path.

Acceptable character set for integration data

The inclusive safe character set on the core data fields is:

A-Z a-z 0-9 . ' , " : ! ? $ @ [ ] { } - _

The password and external keys may also contain:

% & # < > = \ + /

Characters not allowed in any field:

*


Samples using minimum data fields

Note these samples are the minimal required data for the feed – additional objects for each feed may be derived from the SIS Framework Snapshot Flat File Advanced Configuration Custom Headers UI. Also you may derive the required nature of a field from the Field Mapping UI. A full listing with descriptions, examples of default and acceptable values for each object is at the end of this document. Full URLs as used for your installation are discoverable via the SIS Framework Admin UI under HTTP Configuration. To learn more, see Snapshot Flat File.

The below samples use the pipe character - '|' - as the delimiter. You may select which delimiter is used when you configure your implementation.

For more complex data usage samples, see Snapshot Flat File Examples.


Users

Task: Creating/Updating Users (Persons)

URL: Person Store or Refresh

Sample:

external_person_key|user_id|passwd|firstname|lastname|system_role
testPerson1|aanderson_test|changeme|Alpha|Anderson|none
testPerson2|bbrown_test|changeme|Beta|Brown|none
testPerson3|ccharlie_test|changeme|Chi|Charlie|none
testPerson4|ddavis_test|changeme|Delta|Davis|none
testPerson5|eedwards_test|changeme|Epsilon|Edwards|none

While email is not a required field to create a User, not doing so will limit system capabilities such as emailing of course notifications, etc.

Task: Deleting/Disabling users (Persons)

URL: Person Delete

Sample:

external_person_key
testPerson1

Task: Person Secondary Institution Role Feed

URL: Role Store/Refresh /Delete

Sample:

external_person_key|role_id
testPerson1|ALUMNI
testPerson1|PROSPECTIVE_STUDENT
testPerson2|ALUMNI

Task: Person to Observer Association Feed

URL: Association Store/Refresh /Delete

Sample:

external_observer_key|external_user_key
testPerson6|testPerson1


Courses

Task: Creating/Updating new Courses

URL: Course Store or Refresh

Sample:

external_course_key|course_id|course_name
testCourse1|TEST_COURSE_1|Test Course 1
testCourse2|TEST_COURSE_2|Test Course 2
testCourse3|TEST_COURSE_3|Test Course 3

Task: Deleting/Disabling new Courses

URL: Course Delete

Sample:

external_course_key
testCourse1


Organizations

Task: Creating/Updating new Organizations

URL: Organizations Store or Refresh

Sample:

external_organization_key|organization_id|organization_name
testOrg1|TEST_ORG_1|Test Org 1
testOrg2|TEST_ORG_2|Test Org 2
testOrg3|TEST_ORG_3|Test Org 3

Task: Disabling new Organizations

URL: Organizations Delete

Sample:

external_organization_key
testOrg1


Memberships

Task: Creating/Updating Course Memberships

URL: Course Membership Store or Refresh

Sample:

external_person_key|external_course_key|role
testPerson1|testCourse1|instructor
testPerson1|testCourse2|student
testPerson2|testCourse1|student
testPerson3|testCourse1|student
testPerson4|testCourse2|instructor
testPerson5|testCourse3|student

Task: Disabling Course Memberships

URL: Course Membership Delete

Sample:

external_person_key|external_course_key
testPerson1|testCourse1

Task: Creating/Updating Organization Memberships

URL: Organization Membership Store or Refresh

Sample:

external_person_key|external_organization_key|role
testPerson1|testOrg1|instructor
testPerson1|testOrg2|student
testPerson2|testOrg1|student
testPerson3|testOrg1|student
testPerson4|testOrg2|instructor
testPerson5|testOrg3|student

Task: Disabling Organization Memberships

URL: Organization Membership Store or Refresh

Sample:

external_person_key|external_organization_key|role
testPerson1|testOrg1|instructor


Terms

Task: Create/Update Terms

URL: Term Store or Refresh

Sample:

external_term_key|name
testTerm1|Test Term 1

Task: Disable a Term

URL: Term Delete URL

Sample:

external_term_key
testTerm1


Nodes

Task: Create/Update Nodes

URL: Node Store or Refresh

Sample:

external_node_key|name
testNode1|Test Node 1
testNode2|Test Node 2

Task: Disable Terms

URL: Node Delete

Sample:

external_node_key
testNode1


Node association

Task: Create/Update /Disable Course to Node Association

URL: Course Association Store/Refresh /delete

Sample:

external_association_key|external_course_key|external_node_key
testCourseAssociation1|testCourse1|testNode1
testCourseAssociation2|testCourse2|testNode2

Task: Create/Update /Disable User to Node Association

URL: User Association Store/Refresh /Delete

Sample:

external_association_key|external_user_key|external_node_key
testUserAssociation1|testPerson1|testNode1
testUserAssociation2|testPerson2|testNode1
testUserAssociation3|testPerson1|testNode2

Task: Create/Update /Disable Organization to Node Association Feed

URL: Organization Association Store/Refresh /Delete

Sample:

external_association_key|external_organization_key|external_node_key
testOrgAssociation1|testOrg1|testNode1
testOrgAssociation2|testOrg2|testNode2


Category support

Task: Create/Update /Disable Course Category Feed

URL: Course Category Store/Refresh /Delete

Sample:

external_category_key|title
testCourseCategory1|Course Category 1
testCourseCategory2|Course Category 2

Task: Create/Update /Disable Organizations Category Feed

URL: Organizations Category Store/Refresh /Delete

Sample:

external_category_key|title
testOrgCategory1|Org Category 1
testOrgCategory2|Org Category 2

Task: Create/Update /Disable Course Category Membership Feed

URL: Course Category Membership Store/Refresh /Delete

Sample:

external_course_key|external_category_key|available_ind
testCourse1|testCourseCategory1|Y
testCourse2|testCourseCategory2|Y
testCourse3|testCourseCategory1|Y

Task: Create/Update /Disable Organization Category Membership Feed

URL: Organization Category Membership Store/Refresh /Delete

Sample:

external_organization_key|external_category_key|available_ind
testOrg1|testOrgCategory1|Y
testOrg2|testOrgCategory2|Y
testOrg3|testOrgCategory1|Y


Parent Child Support

Add the ‘master_course_key’ field to a course feed when there a parent:child relationship is desired.

You must create parent courses before assigning child relationships.

Task: Create a Parent Child relationship between courses

URL:Course Store/Refresh

Sample:

external_course_key|course_id|course_name|master_course_key
testCourse1|TEST_COURSE_1|Test Course 1|
testCourse2|TEST_COURSE_2|Test Course 2|testCourse1
testCourse3|TEST_COURSE_3|Test Course 3|testCourse1
testCourse4|TEST_COURSE_4|Test Course 4|
testCourse5|TEST_COURSE_5|Test Course 5|testCourse4

In this example, TEST_COURSE_2 and TEST_COURSE_3 are children of the parent course TEST_COURSE_1 while TEST_COURSE_4 is not. You may also run a child course feed separately from a course feed where all courses would contain an entry for the appropriate master_course_key - use Course Store for this operation to retain previously stored courses.


Course copy/template

Add the ‘template_course_key’ field to course feed populating when you wish for a new course to be populated with the contents of a 'Master' course. Eg: all new math courses should initially contain the materials from a master math course.

Sample:

external_course_key|course_id|course_name|master_course_key|template_course_key
testCourse1|TEST_COURSE_1|Test Course 1||test_course_template1
testCourse2|TEST_COURSE_2|Test Course 2|testCourse1|
testCourse3|TEST_COURSE_3|Test Course 3|testCourse1|
testCourse4|TEST_COURSE_4|Test Course 4||test_course_template1

For an understanding of course copy and course templates, refer to Create Courses by Copying Existing Courses.