User Examples

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 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.

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 can 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 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.

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:

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:

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

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:

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:

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.

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.

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.

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.

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.

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.

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:

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.

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

SIS Framework Overview

Snapshot Flat File Header Descriptions

Snapshot Flat File Data Format

Snapshot Flat File Automation

Users

Snapshot Flat File data management

A reminder on data source keys

A note on field mapping

A note on passwords

Person operation examples

Just the basics: Persons

Data in brief

Adding person information

Store operation examples

Example #1: Create person accounts

Prerequisite

Minimum data feed requirements

Solution

Postcondition

Example #2: Update user accounts

Prerequisite

Solution

Postcondition

Person: Complete refresh operation

Example: Complete refresh

Prerequisite

Minimum data feed requirements

Solution

Postcondition

Person: Complete refresh by data source operation

Example: Complete refresh by data source

Prerequisite

Minimum data feed requirements

Solution

Postcondition

Person account availability

Example: Person account availability

Prerequisite

Minimum data feed requirements

Solution

Postcondition

Disabling person records

Example: Disabling person records

Prerequisite

Minimum data feed requirements

Solution

Postcondition

Managing user secondary institution roles

Example: Adding user secondary institution roles

Prerequisite

Minimum data feed requirements

Solution

Postcondition

Observers

Example #1: Create observer association

Prerequisite

Minimum data requirements

Solution

Example #2: Updating an observer association record

Prerequisite

Solution

Postcondition

Example #3: Disable observer association records

Prerequisite

Solution

Disabling a subset of observer associations

Disabling a subset of observer associations while storing new/existing associations

Postcondition

Learn more

Learn - مسؤول