Diagnosing account, enrolment and snapshot problems using the APIs

Dr Malcolm MurrayDurham University

Photo by Terry Bain: http://www.flickr.com/photos/axis/2897335784/

Conference Blurb…

I've designed custom user and course tools to help diagnose and repair problems with user feeds and snapshotted enrolments. I'll demonstrate how you can use APIs to access fields not exposed in the UI. I'll also discuss times when directly querying the database is still the best thing to do (i.e. when there aren't comprehensive enough classes to use). I'll conclude with a discussion of managing access by portal role.

Modelling UsersLooking at the APIs

and peeking under the covers into the database1

bb-platform.jar

Models common objects seen in the UI

• blackboard.data.user.User

• blackboard.data.role.PortalRole

• blackboard.data.course.Course

• blackboard.data.course.CourseMembership

• blackboard.data.course.CourseMembership$Role

• etcetera

bb-platform.jar

blackboard.data.user.User

bb-platform.jar

blackboard.data.user.User

bb-platform.jar

blackboard.data.user.User

• getBatchUid() String

• getDataSourceId() String

• getIsAvailable() boolean

• getUserName() String

• getId() Id

bb-platform.jar

blackboard.data.user.User

• getBatchUid() String

• getDataSourceId() String

• getIsAvailable() boolean

• getUserName() String

• getId() Id

Two unique fields!

UserName & BatchUid

bb-platform.jar

blackboard.data.user.User

• getBatchUid() String

• getDataSourceId() String

• getIsAvailable() boolean

• getUserName() String

• getId() Id

SnapshotNothing more than a quick overview

RTFM for more information 2

Snapshot

Making sense of complicated data

Course Roles

Courses

UsersPortal Roles

Quota

Snapshot

Reality: multiple sources, frequently changing

Users: Student Record System

Users: HR System

Roles: HR System

Roles: Student Record SystemRole

s: LD

AP

Courses: Student Record System

Courses: Timetabling

Managing Snapshot

Preparation, Preparation, Preparation

Enrol feed

Course feedUser feed

Role feed

Quota feed

Day 1 Day 2 Day 3

New user

Continuing User

Change to User

Removing User

Snapshot

Simplified scenarios – snapshotting Users

SNAP

SHO

T 1

SNAP

SHO

T 2

Users are only ever

blocked, not removed

Data Source KeysMean nothing to you?

Stay awake through this bit then3

Data Source Keys

Ownership: Makes Snapshot work

User Details

Data Source Key

Portal Role

Data Source Key

Course Membership

Data Source Key

Course

Data Source Key

• getBatchUid() String

• getDataSourceId() String

• getIsAvailable() boolean

• getUserName() String

• getId() Id

blackboard.data.user.User

Snapshot runs with a different DSK and controls the ROW_STATUS field of all Users with this DSK

Users created using the UI are given a Data Source Key of SYSTEM

Content System Quota

Data Source Key

Data Source Keys

blackboard.data.datasource.DataSource• getModifiedDate() Calendar

• getId() Id

• RowStatus not exposed

• getBatchUid() String

• getDescription() String

Row Status

Controlling access

ROW_STATUS = 0 normal access

ROW_STATUS = 2 no access (blocked)

So where can you see this?

And then there were Two...Working with multiple JAR files

until these are finally merged in a future API release4

Enter bb-cms-admin.jar

Many of the classes seen in bb-platform.jar

• blackboard.data.user.User

• blackboard.data.role.PortalRole

• blackboard.data.course.Course

• blackboard.data.course.CourseMembership

• blackboard.data.course.CourseMembership$Role

are extended by classes in bb-cms-admin.jar

• blackboard.admin.data.user.Person

• blackboard.admin.data.role.PortalRoleMembership

• blackboard.admin.data.course.CourseSite

• blackboard.admin.data.course.Membership

• blackboard.admin.data.course.Enrollment

• blackboard.admin.data.course.StaffAssignment

bb-cms-admin.jar

blackboard.admin.data.user.Person

getRowStatus() would be here

Loaders & Persisters

blackboard.persist.user.UserDbLoader – many options

But...UserDbLoader will only

load User objects where the underlying USERS database table

entry has ROW_STATUS = 0

Loaders & Persisters

blackboard.admin.persist.user.PersonLoader

PersonLoader loads any

entry

Loading Persons by Template

SELECT * FROM BB_BB60.USERS WHERE AVAILABLE_IND = ‘N' AND LASTNAME = 'Smith' AND ROW_STATUS = 2;

Applying this knowledge

Account Problems – “I can’t log in...”5

ACCESS?

Diagnosis requirements – User Account

User

• AvailabilityUser.getIsAvailable() or Person.getIsAvailable()

• Row StatusPerson.getRowStatus()

• Data Source KeyTwo parts:1. Person. getDataSourceBatchUid() - may be enough

User only exposes getDataSourceId()2. blackboard.admin.persist.datasource.DataSourceLoader.

loadByBatchUid() no loadById() method3. blackboard.admin.data.datasource.DataSource.getDescription()

OWNER?

Model of the Process

Not Rocket Science... Entry Point:Module

Identify User

Search Tool

Display InformationFix Problem

Username Known? NOYES

Implementation

Display information

Fix Problem

Limits of the APIs

blackboard.persist.user.UserSearchUserSearch can also be a bit picky about

who it returns results too – you may need a SYSTEM_ROLE to see

any!

Wrote my Own!

Populate an ArrayList with Person objects

Very Important

Ensure you always hand back the Connection

Applying this knowledgeEnrolment Problems – “My Current Courses List is wrong...”6

Diagnosis requirements - Enrolment

User

ACCESS?

OWNER?

ACCESS?

OWNER?

ACCESS?

OWNER?

Course

Course Membership Portal Role

ACCESS?

OWNER?

User Account data

• PersonLoader

• DataSourceLoader

Course Data

• CourseSiteLoader

Enrolment Data

• EnrollmentLoader

• StaffAssignmentLoader

• DataSourceLoader

How many database

round-trips would this cost?

Loader-tastic!

Portal Role data

• PortalRoleMembershipLoader

• DataSourceLoader

Displaying Information

Summary of User’s Account Status

Summary of Enrolment

Definitely a candidate for DIY

Definitely a candidate for DIY

All captured in a single custom class

Straying off topic

What you can do with this knowledge7

Manage the Snapshot Rules in Bb

Rules, Roles and Tabs

We are about to completely rewrite the way we grant access to portal tabs (tab_groups)

This should make diagnosing “Who can see what problems” much easier!

Conclusion

Almost there!8

Snapshot

• Secret to success = pre-process your data

• Data Source Keys control what can be changed

• Snapshot alters ROW_STATUS values

• Available and Blocked (RowStatus) are not the same

APIs

• ROW_STATUS values are not accessible using classes in bb-platform.jar

• Classes in bb-cms-admin.jar expose this fields

Applications

• APIs well suited to simple tasks e.g. User Account Issues

• Normalisation of the database and thus the APIs means that some more complicated tasks, e.g. Enrolment Issues, may currently be more efficient using careful SQL queries

Please provide feedback for this session by emailing DevConFeedback@blackboard.com. 

The catchy title of this session is:

Diagnosing account, enrolment and snapshot problems using the APIs

You contact the author at

malcolm.murray@durham.ac.uk