Skip to main content
Blackboard Help

Snapshot Flat File

It is important to note that for the purposes of this document the use of the term ‘snapshot’ pertains to the general process of taking point-in-time data from the SIS that is stored in a flat file that is then consumed by Learn – not the snapshot controller.

Snapshot provides the ability to integrate using point-in-time data as provisioned by the SIS with two supported integration types (read: data formats) within the SIS Framework for Snapshot – Snapshot XML and Snapshot Flat File (or delimited data).  The latter, Snapshot Flat File, is the ‘go-forward’ supported format and will receive updating to support new data objects. Snapshot XML will only receive maintenance updates.

Processing for both snapshot integration types is via an HTTP post of the data file to the appropriate end-point.

Data Supported

Supported Data
Data Object Supported

Description: Description: Description: check

Courses Description: Description: Description: check

(Enrollments and Staff Assignments)

Description: Description: Description: check

Catalog Categories

Description: Description: Description: check


Description: Description: Description: check


Description: Description: Description: check

Institution Roles

Description: Description: Description: check


Description: Description: Description: check

Cross Listed Courses

Description: Description: Description: check


Description: Description: Description: check

Standards (as a Course Attribute)

Description: Description: Description: check

Table 1: Objects supported by Snapshot Flat File. Bold objects are not supported by Snapshot XML.


Ability of the SIS to generate data formatted for the chosen integration type – Snapshot XML or Snapshot Flat File with appropriate delimiter.

A point worth reiterating – the Snapshot Controller and the Snapshot XML data format should not be the integration option of first choice as they are only receiving maintenance updates not new object support or feature development. It should be expected that at some time in the future an announcement for support removal will be made with the provision of ample time for client adjustment.

See the Enterprise 1.1 examples section for data samples, noting that the data format is slightly different between the two supported flavors of Enterprise 1.1 (standard and vista).

Setup: Snapshot Integration Types

In addition to an understanding of the data involved in any SIS integration, setup of the Snapshot Integration integration types requires knowledge of the SIS capabilities and endpoints with an eye on whether the data objects supported in the selected Snapshot type meet the client’s integration goals. Additionally an understanding of the specific file format is necessary. You may create an Snapshot integration via the following steps in the Learn System Administrator SIS Integration UI: Data Integration > Student Information System Integrations

The following steps are the same for both Snapshot Integration types – the key difference in selection of the integration type is whether the data is XML (choose Snapshot XML) or delimited (Snapshot Flat File).

  1. Select Create Integration
  2. Select Snapshot XML or Snapshot Flat File
  3. On the next screen you are presented with the editable options for the configuration:

    To perform advanced configuration (Data mapping for example), an integration must be set to Testing or Active status

    1. Integration Name: enter Snapshot XML or Snapshot Flat File
    2. Description (optional): enter whatever you want to describe the integration e.g.: Test Snapshot XML or Test Snapshot Flat File
    3. Shared Username is used for data post operations as is Shared Password
    4. Set the Integration Status:
      1. Inactive – Integration performs no processing
      2. Active – Integration performs processing and updates Learn data
      3. Testing – Integration performs processing and does not update Learn
    5. Set the log verbosity levels – for Testing it is recommended that All Diagnostic and Debug Messages be selected. For Active it is recommended that a lower setting be used such as Errors Only or Errors and Warnings.
    6. Next select the Data Source Key (DSK) to be used for this integration. You may select to use a specific existing DSK, create a new key, or to use the data source provided in the feed. Note that in all cases a DSK must be created before the data feeds may be processed.
    7. Only Snapshot Flat File supports the management of parent nodes. Select appropriately to meet client goals.
    8. Finally select the objects handled via this integration and how to handle parity. Generally the defaults are fine.
    9. Note you may have multiple integration types each handling a unique subset of available integration objects.
    10. Submit and your new Snapshot integration will appear in the list of integrations.

One more step must be completed to support Snapshot integration and that is either configuring the SIS system to post data to Learn or to configure an app server side cron or batch job to post the data to Learn. Note that Snapshot endpoints are specific to the required task to be performed.

Application server side posting to learn is accomplished by using CURL or similar application triggered by a cron or batch job:

curl -k -w %{http_code} -H "Content-Type:text/plain" -u SHARED_USERNAME:SHARED_PASSWORD --data-binary @PATH_TO_TEST_FILE ENDPOINT_URL


SHARED_USERNAME with the shared username

SHARED_PASSWORD with the shared password

PATH_TO_TEXT_FILE with the path the the xml data file

Replace ENDPOINT_URL with the endpoint url.

You can see a list of the endpoints on the server by going to the Http Information page off of the context menu of your flat file integration:

System Admin (Building Blocks) > Data Integration > Student Information System Integrations > (Your integration's context menu) > Http Information)

If it is supported by a middle tier application or by the SIS, data may be posted directly to the endpoint following the above protocol.

Once the above has been completed and the SIS has been enabled to generate data and post or save to file for posting to Learn you should begin to see logs on the integration.

Assess the data and determine if you need to make adjustments using the Advanced Configuration/Field Mapping on the available data objects. See section on Field Mapping at end of examples section for description of this functionality.

For more detail on processing data files follow the Snapshot Automation knowledge path.

Snapshot Integrations

Snapshot integrations are based on sets of data which meet specific purposes e.g.: to manage Users or Courses in the system. Of the two supported types – snapshot XML and Snapshot Flat File – only Snapshot Flat File should be considered most current with supported Learn data objects.

As with all the “file based” integration types (Snapshot and Enterprise 1.1 types) there are two processes for consuming data in those files – the use of the GUI Upload Feed File or the use of an http data transfer (e.g.: cURL). In the case of http data transfer a cron or batch job may be used to trigger the operation. Additionally provided it is supported by the SIS or middle-tier a data stream may be posted directly.

To provide functionality similar to the legacy snapshot command-line tools each operation is achieved via a specific end point. These end points for the application server are available via the integrations HTTP Information link from the contextual menu.

Snapshot Endpoints

Snapshot Operation Endpoints for Flat File

Use this information to set up your SIS to POST Snapshot Flat File feed files to your integration. Stored objects will continue to exist, and retain their data. Deleted objects are removed. Complete Refresh will remove any existing objects that are not in the feed file. Posting a file of a specific object type to a non-matching endpoint will fail. e.g.: posting a Course data file to a Person endpoint will fail.

Operation Endpoint URL
Course - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/store
Course - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/refresh
Course - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/refreshlegacy
Course - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/delete
Course Association - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/store
Course Association - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/refresh
Course Association - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/refreshlegacy
Course Association - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/delete
Course Category - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/store
Course Category - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/refresh
Course Category - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/refreshlegacy
Course Category - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/delete
Course Category Membership - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/store
Course Category Membership - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/refresh
Course Category Membership - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/refreshlegacy
Course Category Membership - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/delete
Course Membership - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/store
Course Membership - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/refresh
Course Membership - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/refreshlegacy
Course Membership - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/delete
Course Standard Association - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/store
Course Standard Association - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/refresh
Course Standard Association - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/refreshlegacy
Course Standard Association - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/delete
Hierarchy Node - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/store
Hierarchy Node - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/refresh
Hierarchy Node - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/refreshlegacy
Hierarchy Node - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/delete
Observer Association - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/store
Observer Association - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/refresh
Observer Association - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/refreshlegacy
Observer Association - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/delete
Organization - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/store
Organization - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/refresh
Organization - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/refreshlegacy
Organization - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/delete
Organization Association - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/store
Organization Association - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/refresh
Organization Association - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/refreshlegacy
Organization Association - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/delete
Organization Category - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/store
Organization Category - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/refresh
Organization Category - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/refreshlegacy
Organization Category - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/delete
Organization Category Membership - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/store
Organization Category Membership  - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/refresh
Organization Category Membership  - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/refreshlegacy
Organization Category Membership  - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/delete
Organization Membership - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/store
Organization Membership  - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/refresh
Organization Membership  - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/refreshlegacy
Organization Membership - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/delete
Person - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/store
Person - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/refresh
Person - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/refreshlegacy
Person - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/delete
Term - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/store
Term - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/refresh
Term - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/refreshlegacy
Term - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/delete
User Association - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/store
User Association  - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/refresh
User Association  - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/refreshlegacy
User Association - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/delete
User Secondary Institution Role - Store https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/secondaryinstrole/store
User Secondary Institution Role  - Complete Refresh https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/secondaryinstrole/refresh
User Secondary Institution Role  - Complete Refresh by DSK https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/secondaryinstrole/refreshlegacy
User Secondary Institution Role - Delete https://<>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/secondaryinstrole/delete

If you are familiar with legacy Snapshot the SIS Framework Flat File type brings no change to the format other than the addition of headers for the new data objects supported. For more details follow the Snapshot Flat File Data Format and Examples knowledge paths.

Snapshot Operation Endpoints for XML

Use this information to set up your SIS to POST XML feed files to this integration. Stored objects will continue to exist, and retain their data. Deleted objects are removed. Complete Refresh will remove any existing objects that are not in the feed file. Posting an object containing an incorrect object type will fail.

Operation Endpoint
Use Record Status https://<>/webapps/bb-data-integration-ss-xml-BBLEARN/endpoint
Complete Refresh https://<>/webapps/bb-data-integration-ss-xml-BBLEARN/endpoint/refresh
Delete Only https://<>/webapps/bb-data-integration-ss-xml-BBLEARN/endpoint/delete