The following examples demonstrate the composition of MEMBERSHIP data feeds while meeting a variety of use cases. These examples use the simplest possible data feed required to meet the use case. There are more MEMBERSHIP feed headers for use in creating membership records. Analysis of your institution's information system and registrar requirements and planning will help determine the depth of data necessary to properly populate Learn meeting your data and membership lifecycle goals.
The following examples are based on default Learn settings in the integration configuration UI. Changing these configuration elements will result in changes in 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.
Notes on Memberships in Merged Courses
When creating memberships on Merged Courses the following criteria ensure success:
- Follow the SIS lead. Memberships should maintain a 1:1 per the SIS. Do not force all memberships into the Parent course.
- A membership may not exist in more than one child course in merged courses. SP 12 introduces a new field mapping on Course Memberships to assist in managing enrollments on merged courses (Move Cross-listed Enrollment), which when applied, the membership and associated data/content is moved from the current course to new child course (See the following example usage).
- Without Move Cross-listed Enrollment, you must disable the membership in one child course before creating a membership in another. If your institution allows a broad course enrollment policy wherein students may enroll in more than one course instance you will experience integration errors on the additional membership requests. For example, Math100 has three child courses Math100.1, Math100.2, and Math100.3, and a student selects Math100.2 and Math100.3 as options during the enrollment period. One or the other will produce an error on processing in Learn depending on which child membership is processed first.
About membership data
Membership data is the primary information set which determines access to a course or organization by a user with a non-admin role.
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.
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 Files via the integration 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.
| Operation | Description |
|---|---|
| Store | 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. (See SIS Framework Overview for data 'ownership' and Data Source.) |
| Complete Refresh | 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 | This operation disables, per integration settings, the records contained in the data feed associated with the integration across all data sources. |
| Complete Refresh By Data Source | Introduced in SP 12 this operation performs a complete refresh of data associated ONLY with the integration configured data source. This operation emulates more closely the command-line snapshot process for refreshing data. |
The objects associated with membership operations are:
| Object | Operations |
|---|---|
| membership | Store, Complete Refresh, Delete, Complete Refresh by Data Source |
Organizations and Courses share the same patterns for membership management. They do require different headers, however, and these will be pointed out where appropriate, but the examples will maintain a focus on course membership management.
The provided examples are demonstrated using the Snapshot Framework UI Upload Feed File capability. To learn more about automating or using other command line/programmatic operations, see Snapshot Flat File Automation.
A reminder about 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.
This is not a required field in Framework based data feeds and unless noted the following examples assume the integration is configured to use a single data source. Introduced in SP 12 is the ability to specify the Data Source in the data feed separately from specifying a new data source. See Data Source Key Management and the section on changing a membership record's data source.
Notes on field mapping
Field mapping provides the ability to alter incoming data before it is stored in Learn. This allows you to have complete control over the data that is stored and enables you to meet Learn specific rules when the SIS data you are provided is insufficient, such as the creation of a suitable membership name entry. When applied to a membership object field the associated script is run per membership record, 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.
Membership operation examples
At a high level, you can identify three SIS integration data feed patterns which may be applied to all membership 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 (Complete 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: Memberships
All memberships require a basic set of information to establish. This information is detailed in Snapshot Flat File Data Format and Snapshot Flat File Header Descriptions.
If you are currently using the UI Batch Tools switching to using SIS Framework and using the minimal membership data and the UI upload capabilities of the SIS Framework provides you with better logging and reporting of your data uploads w/o altering your data collection processes.
Data in brief
The minimal data set or headers required for creating a membership account in Learn consists of:
- EXTERNAL_COURSE_KEY - a unique identifier for this membership record. For organizations this is EXTERNAL_ORGANIZATION_KEY.
- NEW_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. - EXTERNAL_PERSON_KEY - The user's id for whom the membership applies.
The SIS Framework per an integration configuration provides default values for, or ignores, non-required fields. Three useful fields which are not required for a membership feed are AVAILABLE_IND, ROW_STATUS, and ROLE. These will be covered in the following use case.
Each of these headers is described completely in Snapshot Flat File Header Descriptions.
Adding membership information
Two use cases exist for adding membership information. The first is to run STORE membership information resulting in the addition or updating of records as presented in the data feed. The Second is to REFRESH membership 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 membership data file.
Store operation examples
Example #1: Create memberships
You want to add memberships to Learn without impacting existing accounts. You have your integration configured to use the same data source for all incoming data.
Prerequisite
The course and user must exist before a membership operation will be successful.
Minimum data feed requirements
EXTERNAL_COURSE_KEY
EXTERNAL_PERSON_KEY
Solution
Create a memberships.txt data file containing the required headers and associated data per membership you wish to add to the system. For example:
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY
testcourse1|testPerson1
testcourse1|testPerson2
testcourse2|testPerson3
Use the UI to upload this file via the membership Data Type using the STORE operation. The membership accounts will be created and you can discover them via the System Administrator membership tools.
Postcondition
Memberships in testcourse1 were created for the persons with testPerson1, testPerson2 as their EXTERNAL_PERSON_KEY and a membership in testcourse2 was created for testperson3.
Example #2: Update memberships
You created membership accounts and need to change them. For example, the previous example added testPerson3 to testcourse2 when it should have been for testcourse1.
Note that while we can make the correct change to the data feed: testcourse1|testPerson3, the previous testcourse2 membership will remain in effect until it is disabled. This may be accomplished in a single feed by adding the ROW_STATUS header element.
Prerequisite
Course and Person records must exist in Learn.
The record for disabling must pre-exist in Learn.
Solution
Create a membership.txt data file containing the required headers and associated data per membership you wish to create/update or disable. For example:
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|ROW_STATUS
testcourse2|testPerson3|disabled
testcourse1|testPerson3|enabled
Because STORE operates only on the data contained in the file the membership records previously submitted data are not affected, the STORE operation requires explicit manipulation of data if you want records to be disabled.
Use the UI to upload this file via the membership Data Type using the STORE operation. The membership records in the file will be updated.
Postcondition
The membership records for testPerson3 are updated to explicitly disable the testcourse2 membership for testPerson3 while creating and enabling a membership in testcourse1.
Previously created membership records are not affected.
Membership: Complete refresh operation
COMPLETE REFRESH operates differently than STORE. COMPLETE REFRESH performs two operations that amount to a comparison of the data in the feed file and the records in Learn owned by the integration: storing new records, updating existing records, or disabling records in Learn that are not in the data file.
Example: Complete refresh
The data your SIS provides contains a full snapshot of the course memberships which should exist in Learn. This data contains membership records to add, membership records to update, and excludes records which have been removed since previous COMPLETE REFRESH operations which should be handled appropriately per configuration (disable or purge).
Prerequisite
Course and Person records must exist in Learn.
Minimum data feed requirements
EXTERNAL_COURSE_KEY
EXTERNAL_PERSON_KEY
Solution
Starting with the data from our first membership store operation and adding the correct membership for testPerson3 in testcourse1 and removing the incorrect membership for testPerson3 in testcourse2, provides similar results as the multiple STORE operations presented above, as COMPLETE REFRESH implicitly disables any records not in the file.
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY
testcourse1|testPerson1
testcourse1|testPerson2
testcourse1|testPerson3
Note that if other membership records are managed by this integration they will be disabled or purged because of their absence in the above data feed.
Postcondition
The membership record for testcourse1|testPerson1 and testcourse1|testPerson2 are retained and updated.
The membership record for testcourse1|testPerson3 is added to Learn.
The membership record for testcourse2|testPerson3, because it is not included in the data feed, is marked as disabled or ready for purging per integration configuration.
Membership: Complete refresh by data source operation
COMPLETE REFRESH BY DATA SOURCE performs a COMPLETE REFRESH operation but restricts the data affected to that which is associated only with the integration's data source.
Example: Complete refresh by data source
The data your SIS provides contains a full snapshot of the PERSONs who should have access to Learn. This data contains PERSON records to add, PERSON records to update, and records which have been removed since previous REFRESH operations which should be handled appropriately per configuration (disable or purge). Additionally, all data in this refresh is targeted using the same data source as defined in the integration and you wish for only data related to this data source key to be affected.
Prerequisite
Course and Person records must exist in Learn.
Minimum data feed requirements
EXTERNAL_COURSE_KEY
EXTERNAL_PERSON_KEY
Solution
Using the data from our last store operation add a new membership for testPerson3 in testcourse1 and removing testcourse2|testPerson3 from the data feed:
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY
testcourse1|testPerson1
testcourse1|testPerson2
testcourse1|testPerson3
Postcondition
The membership record for testcourse1|testPerson1 and testcourse1|testPerson2 are retained and updated.
The membership record for testcourse1|testPerson3 is updated/added to Learn
The membership record for testcourse2|testPerson3, because it is not included in the data feed, is marked as disabled or ready for purging per integration configuration.
If other membership records are managed by this integration they will not be disabled or purged because of their absence in the data feed unless they have the same data source as specified by the integration.
Membership availability
The membership availability setting allows for an account in Learn to be visible to Students (available) or not visible (unavailable). Note that this is not the same as disabling a membership, which not only makes the membership unavailable to everyone, but also means it is not available to additional operations such as membership management via the UI. The addition of this data feed header does not impact the above-demonstrated usage of STORE, COMPLETE REFRESH, COMPLETE REFRESH BY DATA SOURCE for creating membership records.
Note the default integration settings when an AVAILABILITY setting is not provided in the data feed is for the object to be made available on creation/update operations.
Example: Membership account availability
Your SIS controls Learn access availability and the data feed indicates the availability setting on users to control when they have access to Learn and you wish to control this access setting on PERSON create/update.
Prerequisite
Course and Person records must exist in Learn.
Minimum data feed requirements
EXTERNAL_COURSE_KEY
EXTERNAL_PERSON_KEY
AVAILABLE_IND
Solution
Add the AVAILABLE_IND header to your data feed and provide the single character of Y for available and N for unavailable.
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|AVAILABLE_IND
testcourse1|testPerson1|Y
testcourse1|testPerson2|Y
testcourse1|testPerson3|Y
testcourse2|testPerson3|N
Postcondition
STORE
Only the membership records for testcourse1 and testcourse2 are created or updated with current availability state.
Complete refresh operation
The membership records for testcourse1 and testcourse2 are created or updated with current availability state. All other records will be disabled or marked for purging due to their absence in the above data feed.
Complete refresh by data source
The membership records for testcourse1 and testcourse2 are created or updated with current availability state. If other membership records are managed by another integration they will not be disabled or purged because of their absence in the data feed unless they have the same data source as specified by the integration. COMPLETE REFRESH BY DATA SOURCE operates only on records of the integration data source.
Disabling membership records
Disabling a membership record in Learn makes it inaccessible to all users (disabled status overrides the availability setting) and also makes the record inaccessible for UI operations. For example, you cannot manage a disabled membership via the UI. Additionally, to purge a record from Learn, that record must first be disabled.
Disabling a record and subsequent purging removes all references to that record from Learn. Blackboard recommends that purging of disabled records take place only after a period of time as determined by your business and or legal practices which may otherwise require a record of activity.
Disabling of records may follow two models: Disabling through feed data exclusion on REFRESH operations, and Disabling through use of the feed header ROW_STATUS.
The previous membership operations using REFRESH operations demonstrate Disabling thru exclusion, the following case and example demonstrate through the use of ROW_STATUS.
Example: Disabling membership records
Policy dictates that you entirely remove memberships from Learn after a period of 5 years (unlike making the record unavailable which only restricts visibility). If you are using STORE operations then to purge a membership you must explicitly disable the membership by using the ROW_STATUS header. This is also useful in manual operations outside the scope of SIS feeds.
Prerequisite
Course and Person records must exist in Learn.
Minimum data feed requirements
EXTERNAL_COURSE_KEY
EXTERNAL_PERSON_KEY
ROW_STATUS
Solution
Add the ROW_STATUS header to your data feed and provide ENABLED for enabled and DISABLED for disabled.
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|ROW_STATUS
testcourse1|testPerson1|enabled
testcourse1|testPerson2|enabled
testcourse1|testPerson3|enabled
testcourse2|testPerson3|disabled
Postcondition
STORE
Only the membership records contained in the data feed are created or updated with the ROW_STATUS explicitly updated.
COMPLETE REFRESH
The membership records contained in the data feed are created or updated with the ROW_STATUS explicitly updated. All other records are will be disabled or marked for purging because of their absence from the data feed.
COMPLETE REFRESH BY DATA SOURCE
The membership records contained in the data feed are created or updated with the ROW_STATUS explicitly updated. If other membership records are managed another integration they will NOT be disabled or purged due to their absence in the above data feed unless they have the same data source as specified by the integration. COMPLETE REFRESH BY DATA SOURCE only operates on records matching the integration data source.
New In SP 12
Example: Move cross-listed enrollment
The use of merged courses present some constraints on membership (enrollment) processing. Specifically, a user may not simultaneously have an enabled membership in more than one of the merged courses.
In certain cross-listing scenarios, the SIS would normally be prevented from executing the enrollment of a user into course_child2 if the user is already enrolled in course_child1 in a cross-listed (merged) set. The Move Cross-Listed Enrollment field sets the control on the integration such that the SIS integration should assume any enrollment that is otherwise valid should not be prevented because of cross-listing restrictions. This means, following the above course_child2/course_child1 reference, that the enrollment for course_child1 would be moved from course_child1 to course_child2.
The field mapping for cross-listed enrollment management is available through the "Advance Configuration" of each Integration instance. It is a part of the "enrollment" object field mappings, and is called "Move Cross-listed Enrollment."
Move Cross-listed Enrollment uses an internal default script call which always returns "true." To change this behavior, you must supply a script that returns something other than true under some or all circumstances. For example, you could have a script that simply returns false or a script that only returned false if the Membership's course id conditionally meets some pattern and so on. To learn more, see Custom Field Mapping examples.
This mapping by default does not expect to be set "directly" as part of the feed for any integration type. I.e. there is no column for it in snapshot flat file, no XML node for it in IMS / Vista, etc. Thus, there is no "data" example for this field.
Complete example
Combining the above headers into a single file we can address most of the use cases at once.
Prerequisite
For the template copy operation to be successful, testmembership8 must not have been previously created.
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|AVAILABLE_IND|ROW_STATUS
testcourse1|testPerson1|Y|enabled
testcourse1|testPerson2|Y|enabled
testcourse1|testPerson3|Y|enabled
testcourse2|testPerson3|N|disabled
Postcondition
STORE
Only the membership records contained in the data feed are created or updated with the AVAILABILITY and ROW_STATUS explicitly updated with the following results:
All memberships have availability set to yes (Y), except for testcourse2|testPerson3, which is set to no (N).
Memberships for testcourse1 are set to enabled, while the membership for testcourse2|testPerson3 is disabled.
COMPLETE REFRESH
The same results as the store operation with the addition that all other records managed will be disabled or marked for purging because of their absence in the data feed.
COMPLETE REFRESH BY DATA SOURCE
The same results as the store operation with the addition that if other membership records are managed by another integration they will not be disabled or purged due to their absence in the above data feed unless they have the same data source as specified by the integration. COMPLETE REFRESH BY DATA SOURCE operates only on records of the integration data source.
Learn more
Snapshot Flat File Header Descriptions
