Post on 16-Dec-2014
description
transcript
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