The following examples demonstrate the composition of User (Person) data feeds while meeting a variety of use cases. These examples utilize the simplest possible data feed. There are cases where more information may be required by your institution - these are met by adding the required headers and data to the data feed. 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 lifecycle goals.
The examples are based on default Learn settings which visible in the integration configuration UI. Changing these configuration elements will result in change 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.
Users
User data is the primary information set which describes who has access to Learn, their role at your institution, and their role within the Learn system. In the context of SIS data USER objects are often referred to as "PERSON" and this is reflected in existing standards. Predating many of these standards, Learn uses "PERSON" and "USER" to refer to user-related records based on the context. The following examples will use "PERSON" to refer to the record and "USER" to refer to the person.
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 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.
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. For data 'ownership', Data Source, and keys, see SIS Framework 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. |
Complete Refresh By Data Source | Disable provided record. 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 PERSON operations are:
Person | Store, Complete Refresh, Delete, Complete Refresh By Data Source |
User Secondary Institution Role | Store, Complete Refresh, Delete, Complete Refresh By Data Source |
User Association | Store, Complete Refresh, Delete, Complete Refresh By Data Source |
User Association Examples may be found in the Hierarchy example section.
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 below 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.
To learn more, see Data Source Key Management.
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 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 User passwords. When applied to a User object field the associated script is run per user, altering or providing the data before it is stored in Learn. A full explanation of Field Mapping for Snapshot Flat File is provided in Snapshot Flat File Field Mapping.
A note on passwords
Passwords are required to log into Learn but are not a required field in PERSON data feeds. If a password is not provided in the data feed a random SHA512 password is generated and stored in the Learn database. This is not a problem if you are using external (such as LDAP) authentication, but what happens if you are using the Learn database to store user login passwords? You must provide the password on user creation as they will not be able to log in.
If you run a feed and set the password for a user who subsequently changes their password, their login will break. Yes and no - on an update operation you may select to not update the password field. This will allow Learn to retain the current password on update. If you do not select this option the password will be changed and the user will need to be notified of the change.
Person operation examples
At a high level, you can apply three SIS integration data feed patterns to all User data operations, and the selection of the pattern depends on the data you are able to provide and the integration goals.
- Using a single feed file you may create or update, or disable records (Store) - explicitly changing records via data present in the file.
- Using a single feed file you may refresh data - create or update, and disable (Complete Refresh) records - changing records via presence (create/update) or absence of data in the file.
- Using a combination of files you may Store with one, and set Availability or Disable with another.
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 such as data which is the result of testing operations.
Just the basics: Persons
All user accounts require a basic set of information to establish an account. This set of information is detailed in Snapshot Flat File Data Format and Snapshot Flat File Header.
If you are currently using the UI Batch Tools switching to using SIS Framework and using the minimal User data and the UI upload capabilities of the SIS Framework provides you with better logging and reporting of your data uploads without altering your data collection processes.
Data in brief
The minimal data set or headers required for creating a user account in Learn consists of:
- EXTERNAL_PERSON_KEY - a unique identifier for this user 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)
- USER_ID - The user's id - this is used for login as the username and should be associated with the user's LDAP CN, NET ID, or other external identifier, if you are using external authentication.
- FIRST_NAME - The user's first name
- LAST_NAME - The user's last name
- PASSWD - The password for this user
For an example of dynamically assigning a password if you cannot provide one in the data feed, see Snapshot Flat File Custom Field Mapping.
The SIS Framework, per an integration configuration, provides default values for, or ignores, non-required fields. Two useful fields which are not required for a PERSON feed are EMAIL and SYSTEM_ROLE. EMAIL is required for corresponding and providing email notifications with Learn users via Learn email, thus you should consider providing this data in your feed. SYSTEM_ROLE defaults to the configured setting of NONE.
Each of these headers is described completely in Snapshot Flat Files Data Format.
Adding person information
Two cases exist for adding PERSON information. The first is to additively STORE PERSON information resulting in the addition or updating of records as presented in the data feed. The Second is to REFRESH PERSON information already in Learn resulting in the addition of new or updating of existing records as presented in the data file while disabling existing records which are not present in the data file.
Store operation examples
Example #1: Create person accounts
You want to add users to Blackboard Learn without impacting existing accounts. You have your integration configured to use the same data source for all incoming data.
Prerequisite
None.
Minimum data feed requirements
EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
Solution
Create a PERSONS.txt data file containing the required headers and associated data per PERSON you wish to add to the system. For example:
EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME
testPerson1|aanderson_test|changeme|Alpha|Anderson
testPerson2|bbrown_test|changeme|Beta|Brown
testPerson3|gcarlin_test|changeme|Gamma|Carlin
Use the UI to upload this file via the PERSON Data Type using the STORE operation. The user account will be created and you can log in as the user.
Postcondition
PERSON records for aanderson_test, bbrown_test, and ccarlin_test are created.
Example #2: Update user accounts
You created user accounts and need to change them. For example, the previous example did not include any user's EMAIL addresses. You have the email address for aanderson_test.
Prerequisite
None - updates will occur on previously created records, data included where a record does not exist in Learn will result in the record being created.
Solution
Create a PERSONS.txt data file containing the required headers and associated data per PERSON you wish to add to the system. For example:
EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME|EMAIL
testPerson1|aanderson_test|changeme|Alpha|Anderson|[email protected]
Because STORE only operates on the data contained in the file the bbrown_test and ccarlin_test records previously submitted are not affected.
Use the UI to upload this file via the PERSON Data Type using the STORE operation. The user account will be updated.
Postcondition
The PERSON record for aanderson_test is updated to include the provided email address.
The PERSON records for bbrown_test and ccarlin_test is not affected.
Person: 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 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 COMPLETE REFRESH operations which should be handled appropriately per configuration (disable or purge).
Prerequisite
None.
Minimum data feed requirements
EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
Solution
Using the data from our last store operation and removing gcarlin_test from the data feed:
EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME
testPerson1|aanderson_test|changeme|Alpha|Anderson
testPerson2|bbrown_test|changeme|Beta|Brown
If other PERSON records are managed by this integration they will be disabled or purged because of their absence in the above data feed.
Postcondition
The PERSON record for aanderson_test retained and not affected.
The PERSON record for bbrown_test is retained and updated to include the email address
The PERSON record for ccarlin_test is marked as disabled or ready for purging per integration configuration.
Person: 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 only associated 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
None.
Minimum data feed requirements
EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
Solution
Using the data from our last store operation and removing gcarlin_test from the data feed:
EXTERNAL_PERSON_KEY|USER_ID|PASSWD|firstname|lastname
testPerson1|aanderson_test|changeme|Alpha|Anderson
testPerson2|bbrown_test|changeme|Beta|Brown
Postcondition
The PERSON record for aanderson_test retained and not affected.
The PERSON record for bbrown_test is retained and updated to include the email address
The previously created PERSON record for ccarlin_test is marked for as disabled or ready for purging per integration configuration.
If other PERSON records are managed by this 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.
Person account availability
PERSON account availability setting allows for an account in LEARN to log in (available) or not (unavailable). Note that this is not the same as disabling an account which not only makes the account unavailable but also means it is not available to additional operations such as membership management. 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 PERSON records.
The default integration settings when an AVAILABILITY setting is not provided is for the object to be made available on creation/update operations.
Example: Person account availability
Your SIS controls LEARN access availability for users, and your data feed indicates whether users individually have access to Learn. You want to make changes to individual user access using PERSON create/update.
Prerequisite
None.
Minimum data feed requirements
EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
AVAILABILITY_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_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME|AVAILABLE_IND
testPerson1|aanderson_test|changeme|Alpha|Anderson|Y
testPerson2|bbrown_test|changeme|Beta|Brown|Y
testPerson3|gcarlin_test|changeme|Gamma|Carlin|N
testPerson4|ddarling_test|changeme|Delta|Darling|Y
Postcondition
STORE
Only the PERSON records for aanderson_test, bbrown_test, and ccarlin_test are updated (they were previously created) and ddarling_test is created.
COMPLETE REFRESH
The PERSON records for aanderson_test, bbrown_test, and ccarlin_test are updated (they were previously created) and ddarling_test is created. All other records are will be disabled or marked for purging due to their absence in the above data feed.
COMPLETE REFRESH BY DATA SOURCE
The PERSON records for aanderson_test, bbrown_test, and ccarlin_test are updated (they were previously created) and ddarling_test is created.
If other PERSON records are managed by this 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 of the integration data source.
Disabling person records
Disabling a PERSON record in Learn makes it inaccessible for login purposes (disabled status overrides the availability setting) and also makes the record inaccessible for UI operations. For example, you cannot add a disabled PERSON to a course 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 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 above PERSON operations using REFRESH operations demonstrate Disabling thru exclusion, the following case and example demonstrate through the use of ROW_STATUS.
Example: Disabling person records
Students matriculate or are no longer required to have access to Learn. You are required to entirely remove their access to and presence in Learn (unlike making the record unavailable which only restricts login). If you are using STORE operations then to disable users you must explicitly disable the user by using the ROW_STATUS header. This is also useful in manual operations outside the scope of SIS feeds.
Prerequisite
Records targeted exist within the Learn system.
Minimum data feed requirements
EXTERNAL_PERSON_KEY
USER_ID
PASSWD
FIRSTNAME
LASTNAME
ROW_STATUS
Solution
Add the ROW_STATUS header to your data feed and provide an entry of ENABLED for enabled and DISABLED for disabled.
EXTERNAL_PERSON_KEY|USER_ID|PASSWD|FIRSTNAME|LASTNAME|ROW_STATUS
testPerson1|aanderson_test|changeme|Alpha|Anderson|enabled
testPerson2|bbrown_test|changeme|Beta|Brown|enabled
testPerson3|gcarlin_test|changeme|Gamma|Carlin|disabled
testPerson4|ddarling_test|changeme|Delta|Darling|enabled
Postcondition
STORE
Only the PERSON records for aanderson_test, bbrown_test, ccarlin_test, and ddarling_test are created or updated with the ROW_STATUS is explicitly updated.
COMPLETE REFRESH
The PERSON records for aanderson_test, bbrown_test, ccarlin_test, and ddarling_test are created or updated; All other records are will be disabled or marked for purging due to their absence in the above data feed.
COMPLETE REFRESH BY DATA SOURCE
The PERSON records for aanderson_test, bbrown_test, and ccarlin_test are updated (they were previously created) and ddarling_test is created.
If other PERSON records are managed by this 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 of the integration data source.
COMPLETE REFRESH BY DATA SOURCE
The PERSON records for aanderson_test, bbrown_test, ccarlin_test, and ddarling_test are created or updated, with the ROW_STATUS is explicitly updated.
If other PERSON records are managed by this 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 of the integration data source.
Managing user secondary institution roles
As a Community licensee, you have access to additional roles which you may assign to users, these are useful for managing access to materials and tabs in the Community Portal.
The management of Secondary Roles is a separate activity from creating or updating users and as such management of Secondary Roles is not part of PERSON create/update data feed.
Example: Adding user secondary institution roles
You need to provide Portal content specific to Students and Faculty of the School of Engineering.
Prerequisite
You have created a new institutional role using the System Administrator UI (see...) named "ENGINEERING_STUDENT"
Minimum data feed requirements
EXTERNAL_PERSON_KEY
ROLE_ID
Solution
Create an Institutional_Role feed containing the records to be created/updated.
EXTERNAL_PERSON_KEY|ROLE_ID
testPerson1|engineering_student
testPerson2|engineering_faculty
testPerson3|engineering_faculty
testPerson4|engineering_student
As with other data objects you may also provide the ROW_STATUS to enable or disable the PERSON access to the content associated with the Secondary Role. For example:
EXTERNAL_PERSON_KEY|ROLE_ID|ROW_STATUS
testPerson1|engineering_student|enabled
testPerson2|engineering_faculty|enabled
testPerson3|engineering_student|disabled
Postcondition
STORE
Only the Secondary Institution Role records for aanderson_test, bbrown_test, ccarlin_test, and dare created or updated with the Secondary Institution Role.
COMPLETE REFRESH
The Secondary Institution Role records for aanderson_test, bbrown_test, ccarlin_test, and dare created or updated; All other records are will be disabled or marked for purging due to their absence in the above data feed.
COMPLETE REFRESH BY DATA SOURCE
The Secondary Institution Role records for aanderson_test, bbrown_test, ccarlin_test, and dare created or updated.
If other PERSON records are managed by this 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 of the integration data source.
Observers
Observers are a special case User where the account is tied to another user account in an oversight or observation capacity. The Observer may login and see their associated User courses and activity.
An Observer account requires the same information as a User for account creation and has an additional layer of 'User Association Management' wherein the Observer is associated with a User account by linking the external_person_keys of the two accounts.
The Observer's account is created exactly as you would create any User account following your institution's data processing requirements.
Example #1: Create observer association
You wish to associate a Student with their parent's (or other suitable User) account so that activity may be observed.
Prerequisite
You have created a student identified by an external_person_key (test_student_100 in this example) and an observer identified by an external_person_key (test_student_100_observer and test_student_200_observer in this example).
Minimum data requirements
The Observer's external_person_key: EXTERNAL_OBSERVER_KEY
Observed Student's external_person_key: EXTERNAL_USER_KEY
Solution
Create a data file containing the observer's external_person_key and the student's external person key.
EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_200_observer|test_student_100
Use the UI to upload this file via the Observer Association Data Type using the Store operation. The association will be created and you can log in as the observer and view the student's course activity.
Example #2: Updating an observer association record
You need to change an association.
Prerequisite
You have created an association between test_student_200_observer and test_student_100, but the associated student account must be test_student_200.
Solution
Create a file containing the revision.
EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_200_observer|test_student_200
Use the UI to upload this file via the Observer Association Data Type using the Store operation.
Postcondition
The association will be updated and you can log in as the observer and view the correct student's course activity.
Example #3: Disable observer association records
An Observer Association is no longer needed and you wish to disable it.
Prerequisite
You have created associations between students and observers.
Solution
(Utilizing the data used in this example thread)
You previously created associations using the Store method and the following file:
EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_200_observer|test_student_200
Two feed-related patterns exist for satisfying the requirement to disable an observer association depending on your requirements:
- You want to disable a subset of Observer Associations associated with the current integration/data source.
- You want to disable a subset of Observer Associations while storing or updating additional records.
Disabling a subset of observer associations
To disable a subset of data you create an association feed and upload it to the Delete operation. For example:
To delete the association between test_student_100_observer|test_student_100 in the working data set you would create a feed file containing the following and upload it using the Delete operation:
EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_200_observer|test_student_200
Disabling a subset of observer associations while storing new/existing associations
To disable a subset of data that also allows the updating existing or storing new associations you would create an association file that contains existing and any new associations, remove those you wish to disable and upload using the Complete Refresh Operation. For example, using the working set of:
EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_200_observer|test_student_200
We want to disable the test_student_200_observer|test_student_200 association, so the file would contain only the test_student_100_observer|test_student_100 association. If we also wanted to add two new associations (meet the pre-requisite that the user accounts have been created) we would upload the following:
EXTERNAL_OBSERVER_KEY|EXTERNAL_USER_KEY
test_student_100_observer|test_student_100
test_student_300_observer|test_student_300
test_student_400_observer|test_student_400
Postcondition
The record for test_student_200_observer|test_student_200 is disabled.
Learn more
Snapshot Flat File Header Descriptions