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

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

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.

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:

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.

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.

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.