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
| Data Object | Snapshot Flat File Support | Snapshot XML Support |
|---|---|---|
| Users | Yes | Yes |
| Courses | Yes | Yes |
| Memberships
(Enrollments and Staff Assignments) |
Yes | Yes |
| Catalog Categories | Yes | Yes |
| Organizations | Yes | Yes |
| Observers | Yes | Yes |
| Institution Roles | Yes | Yes |
| Nodes | Yes | |
| Cross Listed Courses | Yes | |
| Terms | Yes | |
| Standards (as a Course Attribute) | Yes |
Requirements
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).
- Select Create Integration
- Select Snapshot XML or Snapshot Flat File
- 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
- Integration Name: enter Snapshot XML or Snapshot Flat File
- Description (optional): enter whatever you want to describe the integration For example: Test Snapshot XML or Test Snapshot Flat File
- Shared Username is used for data post operations as is Shared Password
- Set the Integration Status:
- Inactive - Integration performs no processing
- Active - Integration performs processing and updates Learn data
- Testing - Integration performs processing and does not update Learn
- 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.
- 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.
- Only Snapshot Flat File supports the management of parent nodes. Select appropriately to meet client goals.
- Finally select the objects handled via this integration and how to handle parity. Generally the defaults are fine.
- Note you may have multiple integration types each handling a unique subset of available integration objects.
- 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
Replacing:
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 > 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.
To learn more about processing data files, see Snapshot Flat File Automation.
Snapshot integrations
Snapshot integrations are based on sets of data that meet specific purposes. For example, 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 (For example: 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 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. For example: posting a Course data file to a Person endpoint will fail.
Disabling a course will disable memberships in that course. This is new behavior.
You can find an operation's endpoint URL in the Blackboard Learn user interface as well. Navigate to Administrator Panel > Data Integration > Student Information Systems Integrations. Locate the integration, open its menu, and select HTTP Information. The integration's endpoint URLs are listed.
| Operation | Endpoint URL |
|---|---|
| Course - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/store |
| Course - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/refresh |
| Course - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/refreshlegacy |
| Course - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/course/delete |
| Course Association - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/store |
| Course Association - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/refresh |
| Course Association - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/refreshlegacy |
| Course Association - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/courseassociation/delete |
| Course Category - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/store |
| Course Category - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/refresh |
| Course Category - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/refreshlegacy |
| Course Category - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategory/delete |
| Course Category Membership - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/store |
| Course Category Membership - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/refresh |
| Course Category Membership - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/refreshlegacy |
| Course Category Membership - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/coursecategorymembership/delete |
| Course Membership - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/store |
| Course Membership - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/refresh |
| Course Membership - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/refreshlegacy |
| Course Membership - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/membership/delete |
| Course Standard Association - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/store |
| Course Standard Association - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/refresh |
| Course Standard Association - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/refreshlegacy |
| Course Standard Association - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/standardsassociation/delete |
| Hierarchy Node - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/store |
| Hierarchy Node - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/refresh |
| Hierarchy Node - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/refreshlegacy |
| Hierarchy Node - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/node/delete |
| Observer Association - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/store |
| Observer Association - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/refresh |
| Observer Association - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/refreshlegacy |
| Observer Association - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/associateobserver/delete |
| Organization - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/store |
| Organization - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/refresh |
| Organization - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/refreshlegacy |
| Organization - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organization/delete |
| Organization Association - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/store |
| Organization Association - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/refresh |
| Organization Association - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/refreshlegacy |
| Organization Association - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationassociation/delete |
| Organization Category - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/store |
| Organization Category - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/refresh |
| Organization Category - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/refreshlegacy |
| Organization Category - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategory/delete |
| Organization Category Membership - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/store |
| Organization Category Membership - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/refresh |
| Organization Category Membership - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/refreshlegacy |
| Organization Category Membership - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationcategorymembership/delete |
| Organization Membership - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/store |
| Organization Membership - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/refresh |
| Organization Membership - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/refreshlegacy |
| Organization Membership - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/organizationmembership/delete |
| Person - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/store |
| Person - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/refresh |
| Person - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/refreshlegacy |
| Person - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/person/delete |
| Term - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/store |
| Term - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/refresh |
| Term - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/refreshlegacy |
| Term - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/term/delete |
| User Association - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/store |
| User Association - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/refresh |
| User Association - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/refreshlegacy |
| User Association - Delete | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/userassociation/delete |
| User Secondary Institution Role - Store | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/secondaryinstrole/store |
| User Secondary Institution Role - Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/secondaryinstrole/refresh |
| User Secondary Institution Role - Complete Refresh by DSK | https://<servername.domain.edu>/webapps/bb-data-integration-flatfile-BBLEARN/endpoint/secondaryinstrole/refreshlegacy |
| User Secondary Institution Role - Delete | https://<servername.domain.edu>/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. To learn more, see Snapshot Flat File Data Format and Snapshot Flat File Examples.
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://<servername.domain.edu>/webapps/bb-data-integration-ss-xml-BBLEARN/endpoint |
| Complete Refresh | https://<servername.domain.edu>/webapps/bb-data-integration-ss-xml-BBLEARN/endpoint/refresh |
| Delete Only | https://<servername.domain.edu>/webapps/bb-data-integration-ss-xml-BBLEARN/endpoint/delete |
