Skip to main content
pdf?stylesheet=default
Blackboard Help

Term Examples

The following examples demonstrate the composition of TERM data feeds while meeting a variety of use cases. These examples utilize the simplest possible data feed required to meet the use case. There are more TERM feed headers for use in creating membership records - analysis of your institution's information system, registrar requirements, and planning will help determine the depth of data necessary to properly populate Learn meeting your data and TERM (and associated Course/Organization) lifecycle goals.

The examples are based on default Learn settings visible in the integration configuration UI. Changing these configuration elements will result in changes to example results. Explanations of these settings are available in SIS Framework Overview. Also, it is assumed unless otherwise noted that the integration is configured to use the same data source for all incoming data.

TERM

The TERM object provides another useful means for organizing and controlling access to Courses and Organizations. When using a TERM object to control course access the settings specified by the TERM override those otherwise provided on the course data - meaning if you specify start or end dates and duration at the course level these are superseded by those specified in the associated TERM.

This topic describes the use of Snapshot Flat File to create and manage TERM objects and presents a single example of the use of the TERM object in a course data feed.

Snapshot Flat File Data Management

The SIS Framework supports Snapshot Flat File data feed uploads via a UI Feed Upload and via a set of URLs provided by the Learn system. 

Access HTTP Information and Upload Feed File via the integration contextual menu in the System Admin Data Integration Student Information Systems Integration UI.

In both cases, the behavior of the data operation is driven by the configuration of the integration and the operation type selected. The data operation type selected controls how the data in the feed is 'interpreted' and each URL will provide different results to meet the desired goals of your integration.

The examples use the Snapshot Framework UI Upload Feed File capability. For automating or otherwise using command line/programmatic operations, see Snapshot Flat File Automation.

Operations

Data may be provided to Learn and then subsequently updated, removed, or amended - thus you may start with the simplest data set and augment as your institution's data requirements change. 

The following operations are available via the UI and HTTP:

Operation Description

Store

Store or Update a provided record per integration configuration.

When using this operation type data that is contained in the feed file is stored or updated (per configuration settings) across all data sources that are owned by the integration.

To learn more about data 'ownership', see SIS Framework Overview. To learn more about data source keys, see Data Source Key Overview.

Refresh

Store, Update, or Disable  a record provided presence in Feed and Learn.

This operation either stores or updates data that is contained in the data feed while disabling data that is not contained in the data feed which associated with the integration across all data sources.

Delete

Disable provided record.

This operation disables, per integration settings, the records contained in the data feed associated with the integration across all data sources.

The objects associated with TERM operations are:

TERM Store, Complete Refresh, Delete, Complete Refresh by Data Source

The provided examples are demonstrated using the Snapshot Framework UI Upload Feed File capability. For automating or otherwise utilizing command line/programmatic operations, see Snapshot Flat File Automation.

A Reminder on Data Source Keys

All data objects support the ability to alter the data source key for the grouping of that data set and may be used to alter the associated data source - Note: this is not a required field in Framework based data feeds and unless noted the provided examples assume the integration is configured to use a single data source. See Data Source Key Overview.

Introduced in SP 12 is the ability to specify the Data Source in the data feed separately from specifying a new data source.

A Note on Field Mapping

Field mapping provides the ability to alter incoming data before it is stored in Learn. This allows you to have control over the data that is stored and enables you to meet Learn specific rules when the SIS data you are provided is insufficient (for example, the creation of User passwords when a password is not provided in the data feed).

When applied to a Term object field the associated script is run per object, altering or providing the data before it is stored in Learn. A full explanation of Field Mapping is provided in Snapshot Flat File Custom Field Mapping.

Operations

Data may be provided to Learn and then subsequently updated, removed, or amended - thus you may start with the simplest data set and augment as your institution's data requirements change.

The provided examples are demonstrated using the Snapshot Framework UI Upload Feed File capability. For automating or otherwise utilizing command line/programmatic operations, see Snapshot Flat File Automation.

TERM Examples

At a high level, one can identify three SIS integration data feed patterns which may be applied to all TERM data operations and the selection of the pattern depends on the data you are able to provide.

  • Using a single feed file you may Store and Update records (Store) utilizing a separate process to disable (Delete) records
  • Using a single feed file you may Store, Update, and Disable (Refresh) records
  • Using a combination of files you may Store with one, Disable with a Second.

Finally, and this is not an SIS feed pattern, but worth mentioning, you may also disable and purge based on DSK alone utilizing the Data Source Management tool available in the UI. You should exercise great discretion when managing your SIS provided data in this manner. This is extremely useful when purging data which never was or is no longer provided via the SIS or the result of testing operations.

Just the Basics - TERM

All TERM objects require a basic set of information to establish. This set of information is detailed in Snapshot Flat File Data Format and Snapshot Flat File Header Descriptions.

Data In Brief

The minimal data set or headers required for creating a membership account in Learn consists of:

  • EXTERNAL_TERM_KEY - a unique identifier for this term record.
  • DATA_SOURCE_KEY - a unique identifier for the data set this record. Note: this is provided either in the feed or via the integration configuration
  • NAME - the name associated with the TERM. Note that as this is what is searched on when searching for TERM records it is helpful to use a naming convention which makes it easier to differentiate your TERMs over time. For example: use "Arts and Sciences Fall 2013" rather than "Fall"

The SIS Framework per an integration configuration provides default values for, or ignores, non-required fields. Three useful data points which are not required for a TERM feed are DESCRIPTIONAVAILABLE_INDROW_STATUS,  these operate in the same manner as with other Learn objects. Additionally, to use the TERM object to control course access, you will use the START_DATE and END_DATE data points. These will be covered in a use case below.

Each of these headers is described completely in Snapshot Flat File Header Descriptions.

Adding TERM Objects

To use the TERM object to control course availability you must first create the TERM object.

There are two cases for adding TERM information. The first is to additively STORE membership information resulting in the addition or updating of records as presented in the data feed. The Second is to REFRESH TERM information already present in Learn resulting in the addition of new or updating of existing records as presented in the data file while disabling existing Learn records which are not present in the TERM data file.

STORE Example

STORE Case #1 - create TERMs

You wish to add TERMs for your Academic Year 2013-2014 to LEARN without impacting existing records. You require different TERMs for your school of Medicine and school of Arts and Sciences.

You have your integration configured to use the same data source for all incoming data.

Prerequisite

None

Precondition

None

Minimum Data Feed Requirements

EXTERNAL_TERM_KEY
NAME

Solution

Create a terms.txt data file containing the required headers and associated data per TERM you wish to add to the system. For example:

EXTERNAL_TERM_KEY|NAME
AS_FA.2013|Arts and Sciences Fall 2013
AS_WI.2014|Arts and Sciences Winter 2014
AS_SP.2014|Arts and Sciences Spring 2014
AS_SU.2014|Arts and Sciences Summer 2014
MED_T1.2013|School of Medicine Term 1 2013
MED_T2.2014|School of Medicine Term 2 2013
MED_T3.2014|School of Medicine Term 3 2013

Use the UI to upload a file containing the above via the TERM Data Type using the STORE operation. The TERM records  will be created and you can discover them via the System Administrator Term tools.

Postcondition

Term objects are created for both schools: 4 for Arts and Sciences and three for the School of Medicine.

STORE Case #2 - update TERMs

You wish to add and update TERMs for your Academic Year 2013-2014 without impacting existing records. Additionally, you want to explicitly control the availability and the enabled status of the TERM records. The school of Arts and Sciences has different start and end dates per term so you want to set the start and end dates for each school's term to control the visibility of the associated courses.

You have your integration configured to use the same data source for all incoming data.

Prerequisite

None

Precondition

None

Minimum Data Feed Requirements

EXTERNAL_TERM_KEY
NAME
AVAILABILITY_IND
DURATION
END_DATE
ROW_STATUS
START_DATE

Solution

Create a terms.txt data file containing the required headers and associated data per TERM you wish to add to, or update in, the system.

To properly utilize START_DATE and END_DATE a DURATION must also be specified (RANGE) For example:

EXTERNAL_TERM_KEY|NAME|START_DATE|END_DATE|DURATION|AVAILABLE_IND|ROW_STATUS
AS_FA.2013|Arts and Sciences Fall 2013|20130915|20131205|RANGE|Y|ENABLED
AS_WI.2014|Arts and Sciences Winter 2014|20140103|20140418|RANGE|Y|ENABLED
AS_SP.2014|Arts and Sciences Spring 2014|20140420|20140520|RANGE|Y|ENABLED
AS_SU.2014|Arts and Sciences Summer 2014|20140608|20140820|RANGE|Y|ENABLED
MED_T1.2013|School of Medicine Term 1 2013|20130801|20131215|RANGE|Y|ENABLED
MED_T2.2014|School of Medicine Term 2 2014|20140110|20140602|RANGE|Y|ENABLED
MED_T3.2014|School of Medicine Term 3 2014|20140603|20140818|RANGE|Y|ENABLED
Postcondition

TERM objects are created or updated, explicitly setting the availability of the TERM record and the start and end of each term. When associated with a course the term associated will control the visibility of the course.

REFRESH Examples

REFRESH Case - create/disable TERMs

You want to add and update TERMs for your Academic Year 2013-2014 while disabling records no longer required. Additionally, you want to explicitly control availability and the enabled status of the TERM records. The school of Arts and Sciences has different term start and end dates per term so you want to set the start and end dates for each school's term to control the visibility of the associated courses.

You have your integration configured to use the same data source for all incoming data.

Prerequisite

None

Precondition

None

Minimum Data Feed Requirements

EXTERNAL_TERM_KEY
NAME
AVAILABILITY_IND
DURATION
END_DATE
ROW_STATUS
START_DATE

Solution

Create a terms.txt data file containing the required headers and associated data per TERM you wish to add to, or update in, the system.

To properly utilize START_DATE and END_DATE, a DURATION must also be specified (RANGE). For example:

EXTERNAL_TERM_KEY|NAME|START_DATE|END_DATE|DURATION|AVAILABLE_IND|ROW_STATUS
AS_FA.2013|Arts and Sciences Fall 2013|20130915|20131205|RANGE|Y|ENABLED
AS_WI.2014|Arts and Sciences Winter 2014|20140103|20140418|RANGE|Y|ENABLED
AS_SP.2014|Arts and Sciences Spring 2014|20140420|20140520|RANGE|Y|ENABLED
AS_SU.2014|Arts and Sciences Summer 2014|20140608|20140820|RANGE|Y|ENABLED
MED_T1.2013|School of Medicine Term 1 2013|20130801|20131215|RANGE|Y|ENABLED
MED_T2.2014|School of Medicine Term 2 2014|20140110|20140602|RANGE|Y|ENABLED
MED_T3.2014|School of Medicine Term 3 2014|20140603|20140818|RANGE|Y|ENABLED
Postcondition

Submitted using COMPLETE_REFRESH operation:
Term records contained in the data file are created or updated explicitly setting availability of the term record and providing the ranged availability that courses associated with those terms will become available (start_date) and when they will become unavailable (end_date). As with all COMPLETE_REFRESH operations, all records that are not contained in the submitted data set are disabled (data feed: ROW_STATUS=DISABLED, database: ROWSTATUS=0).

Submitted using COMPLETE_REFRESH_BY_DATA_SOURCE operation:
Term records contained in the data file are created or updated explicitly setting availability of the term record and providing the ranged availability that courses associated with those terms will become available (start_date) and when they will become unavailable (end_date). As with all COMPLETE_REFRESH_BY_DATA_SOURCE operations, all records that are not contained in the submitted data AND have a data source key that matches the integration configured data source are disabled (data feed: ROW_STATUS=DISABLED, database: ROWSTATUS=0).TERM records not associated with the integration configured data source are not affected.

Using TERM in Course Feeds

Organizations and Courses share the same patterns for TERM management. The provided examples will maintain a focus on course TERM object usage.

While possible to control the availability of courses using, duration, dates, availability, and row status using the TERM object allows for application of same settings to groups of courses as associated with a TERM object. TERM is an optional data element in course feeds.
Normal operational outcomes should be anticipated based on the operation chosen to send the data to Learn.

CASE

In the above example you created TERM objects for each of your 2014 terms for Arts and Sciences, and Medical Schools and now wish to manage availability of some of the courses from each school using those TERM objects.

Prerequisite

You have created the TERM objects to which you wish to associate your courses

Precondition

None - courses will either be created and associated with the TERM provided or will be updated with the TERM association as noted by the DURATION type of TERM.

Minimum Data Feed Requirements

EXTERNAL_COURSE_KEY
COURSE_ID
COURSE_NAME
DURATION
TERM_KEY

Solution

Create a termmanagedcourses.txt data file containing the required headers and associated data per course you wish to add to, or update in, the system.

To properly utilize START_DATE and END_DATE a DURATION must also be specified (RANGE). For example:

EXTERNAL_COURSE_KEY|COURSE_ID|COURSE_NAME|DURATION|TERM_KEY
AHIST.101-01.03.FA2013|AHIST.101-01.03.FA2013|Art History 101|TERM|AS_FA.2013
AHIST.101-01.03.WI2013|AHIST.101-01.03.WI2013|Art History 101|TERM|AS_WI.2014
AHIST.101-01.03.SP2013|AHIST.101-01.03.SP2013|Art History 101|TERM|AS_SP.2014
AHIST.101-01.03.SU2013|AHIST.101-01.03.SU2013|Art History 101|TERM|AS_SU.2014
ANAT.100-01.T1|ANAT.100-01.T1|Basic Anatomy|TERM|MED_T1.2013
ANAT.100-01.T2|ANAT.200-01.T2|Intermediate Anatomy|TERM|MED_T2.2014
ANAT.100-01.T3|ANAT.300-01.T3|Advanced Anatomy|TERM|MED_T3.2014
Postcondition

The courses in the data  feed are created or updated and will be visible to users as dictated by the parameters for the TERM associated with each course. Effect on other system data is dictated by the operation used to load the data into Learn:

Submitted using STORE Operation:
When using store no other data is impacted - only data contained in the data feed file is added or updated.

Submitted using COMPLETE REFRESH Operation:
When using complete refresh data contained in the file is added or updated - all other data managed by this data source is disabled due to an absence in the data file regardless of data source.

Submitted using COMPLETE REFRESH by DATA SOURCE Operation:
When using complete refresh by data source data contained in the file is added or updated - all other data managed by this data source and associated with this integration's configured data source is disabled. Data not contained in the feed file and not associated with the integration data source is not affected.