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. E.G.: 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.

A complete description of URLs and their function is presented in the Snapshot Flat File About knowledge path.

 

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. See the Snapshot Flat File Configuration Knowledge Path for more information.

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 follow the Examples Knowledge Path.

 

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

Note: 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.

Note: 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 the above 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 follow the admin knowledge path on course copy.