Skip to main content
pdf?stylesheet=default
Blackboard Help

1. 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 following examples are based on default Learn settings visible in the integration configuration UI. Changing these configuration elements will result in change in example results. Explanation of theses settings are available in the SIS Framework Configuration knowledge path. 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 contextual menu in the System Admin Data Integration Student Information Systems Integration UI.

In both cases 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 provided examples are demonstrated using the Snapshot Framework UI Upload Feed File capability. For automating or otherwise utilizing command line/programmatic operations please see the Snapshot Flat File Automation Knowledge Path.

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. (see SIS Framework Overview for data 'ownership' and Data Source )

See SIS Framework Overview for data 'ownership' and Data Source for more information on data ownership and data source keys.

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 PERSON operations are:

Person Store, Complete Refresh, Delete
User Secondary Institution Role Store, Complete Refresh, Delete
User Association Store, Complete Refresh, Delete

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 please see the Snapshot Flat File Automation Knowledge Path.

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. See Data Source Key Management and the Data Source Key Example Knowledge Path.

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 the Snapshot Flat File Field Mapping Knowledge Path.

A Note on Passwords

Passwords are a required field in PERSON data feeds, 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? 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 Examples

At a high level one can identify three SIS integration data feed patterns which may be applied 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 the Snapshot Flat File Data Format and Snapshot Flat File Header Knowledge Paths.

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 w/o 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 - see Snapshot Flat File Custom Field Mapping Knowledge Path for an example of dynamically assigning a password if you cannot provide one in the data feed.

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 the Snapshot Flat Files Data knowledge path.

Adding PERSON Information

There are two cases 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 Example

STORE PERSON Case #1 - create PERSON accounts

You wish to add users to LEARN without impacting existing accounts. You have your integration configured to use the same data source for all incoming data.

Pre-requisite

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.

STORE PERSON Case #2 - update user accounts

You created user accounts and need to change them. For example, the above 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|...owhere.erehwon

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.

COMPLETE REFRESH PERSON

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.

COMPLETE REFRESH Case

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

Note that if other PERSON records are managed by this integration they will be disabled or purged due to 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 Account Availability

PERSON account availability setting allows for an account in LEARN to login (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.

PERSON Account Availability Case 1

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

 

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

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 - eg: you cannot add a disabled PERSON to a course via the UI. Additionally, in order to purge a record from Learn that record must first be disabled.

Note that disabling a record and subsequent purging removes all references to that record from Learn - it is recommended 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 above PERSON operations using REFRESH operations demonstrate Disabling thru exclusion, the following case and example demonstrate through the use of ROW_STATUS.

Disabling PERSON records case

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

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.

Adding User Secondary Institution Roles Case

You need to provide Portal content specific to prospective Students and Faculty of the School of Engineering.

Prerequisite

You have created a new institutional role using the System Administrator UI (see...) named "PROSPECTIVE_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_student
testPerson4|engineering_student

As with other data objects you may also provide the ROW_STATUS to enable or disable the PERSONs 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 ddarling_test are created or updated with the Secondary Institution Role

COMPLETE REFRESH

The Secondary Institution Role 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. 

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

OBSERVER Examples
Create Observer Association Case

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 students course activity.

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

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

There are two Feed related patterns for satisfying the requirement to disable an observer association depending on your requirements:

  1. You wish to disable a subset of Observer Associations associated with the current integration/data source
  2. You wish to disable a subset of Observer Associations while storing or updating additional records
1. 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

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