Presentation given at the 2010 Blackboard Developer's conference in Orlando. Looks at how you can use the Blackboard APIs to diagnose and fix problems with user accounts and course enrolments

1. Diagnosing account, enrolment and snapshot problems using the APIs Dr Malcolm MurrayDurham University Photo by Terry Bain: http://www.flickr.com/photos/axis/2897335784/

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

3. 1 Modelling Users Looking at the APIs and peeking under the covers into the database

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

5. bb-platform.jar blackboard.data.user.User

6. bb-platform.jar blackboard.data.user.User

8. getDataSourceId() String

9. getIsAvailable()boolean

10. getUserName() String

12. getDataSourceId() String

13. getIsAvailable() boolean

14. getUserName() String

15. getId() IdTwo unique fields! UserName & BatchUid

17. getDataSourceId() String

18. getIsAvailable() boolean

19. getUserName() String

21. Snapshot Making sense of complicated data Users Portal Roles Courses Course Roles Quota

22. Snapshot Reality: multiple sources, frequently changing Courses: Timetabling Roles: LDAP Roles: Student Record System Users: Student Record System Courses: Student Record System Users: HR System Roles: HR System

23. Managing Snapshot Preparation, Preparation, Preparation Quota feed Course feed User feed Enrol feed Role feed

24. Snapshot Simplified scenarios – snapshotting Users Users are only ever blocked, not removed SNAPSHOT 2 SNAPSHOT 1

25. 3 Data Source Keys Mean nothing to you?Stay awake through this bit then

27. getDataSourceId() String

28. getIsAvailable() boolean

29. getUserName() String

30. getId() IdUsers created using the UI are given a Data Source Key of SYSTEM Snapshot runs with a different DSK and controls the ROW_STATUS field of all Users with this DSK

32. getId() Id

33. RowStatus not exposed

34. getBatchUid() String

36. 4 And then there were Two... Working with multiple JAR filesuntil these are finally merged in a future API release

38. blackboard.admin.data.role.PortalRoleMembership

39. blackboard.admin.data.course.CourseSite

40. blackboard.admin.data.course.Membership

41. blackboard.admin.data.course.Enrollment

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

44. Loaders & Persisters blackboard.admin.persist.user.PersonLoader PersonLoader loads any entry

45. Loading Persons by Template SELECT * FROM BB_BB60.USERS WHERE AVAILABLE_IND = ‘N' AND LASTNAME = 'Smith' AND ROW_STATUS = 2;

46. 5 Applying this knowledge Account Problems – “I can’t log in...”

47. ACCESS? Diagnosis requirements – User Account User Availability User.getIsAvailable() or Person.getIsAvailable() Row Status Person.getRowStatus() Data Source Key Two parts: Person.getDataSourceBatchUid() - may be enoughUser only exposes getDataSourceId() blackboard.admin.persist.datasource.DataSourceLoader. loadByBatchUid() no loadById() method blackboard.admin.data.datasource.DataSource.getDescription() OWNER?

48. Model of the Process Not Rocket Science... Entry Point: Module Username Known? NO Search Tool YES Identify User Display Information Fix Problem

49. Implementation

50. Display information

51. Fix Problem

52. Limits of the APIs blackboard.persist.user.UserSearch UserSearch can also be a bit picky about who it returns results too – you may need a SYSTEM_ROLE to see any!

53. Wrote my Own!

54. Populate an ArrayList with Person objects

55. Very Important Ensure you always hand back the Connection

56. 6 Applying this knowledge Enrolment Problems – “My Current Courses List is wrong...”

57. Diagnosis requirements - Enrolment User Course ACCESS? ACCESS? OWNER? OWNER? Portal Role Course Membership ACCESS? ACCESS? OWNER? OWNER?

59. DataSourceLoaderHow many database round-trips would this cost? Loader-tastic!

60. Displaying Information

61. Summary of User’s Account Status

62. Summary of Enrolment

63. Definitely a candidate for DIY

64. Definitely a candidate for DIY

65. All captured in a single custom class

66. 7 Straying off topic What you can do with this knowledge

67. Manage the Snapshot Rules in Bb

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

69. 8 Conclusion Almost there!

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

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