WebCTDAO package

This package provides PowerLinks developers with access to data objects relating to users and learning contexts. The initial release is functionally equivalent to the com.webct.platform.sdkext.authmoduledata available from Blackboard. The last release (1.4) of the Blackboard package was in May 2006 and it has not been updated for either Application Pack 1 or Application Pack 2. The latest information from Blackboard is that this functionality will become part of the core product in a future release, but no timescales are available for this. Given the lack of maintenance and support for the Blackboard package and its usefulness for PowerLink developers, this open source version has been prepared to comply fully with the original JavaDocs so only requires a change to the import statements for any existing source code. The community-supported version will also enable enhancements to be added to make the package an even more useful tool for developers; release 2 includes a number of enhancements including access to term data and system version information.

The WebCTDAO package is written for WebCT Vista 4 (or later) and WebCT Campus Edition 6 (or later). The package is version dependent but any updates required for future releases of WebCT Vista and WebCT Campus Edition should be possible via the properties file pending the release of a new version of this utility.

This package is designed for use with PowerLinks and may be installed either by copying the jar file into the same directory as the PowerLink itself, or placed in the common directory so that it can be shared by more than one PowerLink.

An optional properties file may be placed in the same directory as the package file. This file should have the same file name as the package but be given an extension of .properties. For example, if the package is named WebCTDAO.jar it will look for a properties file named WebCTDAO.properties. The properties file may contain one or more of the following settings:

• dateformat - the format for use by the getFormattedName() methods when converting dates
• timeformat - the format for use by the getFormattedName() methods when converting times
• datasource.name - the name of the JDBC data source for the WebCT database
• SQL_GET_VERSION - SQL to retrieve the version numbers of the installed application
• SQL_GET_INSTANCE_NAME - SQL to retrieve the name of a proxy tool instance
• SQL_GET_LC - SQL to retrieve details for a specified learning context; the select clause should return the fields in the same order as the LearningContextVO constructor
• SQL_GET_LC_CHILDREN - SQL to retrieve the IDs of the children of the specified learning context
• SQL_GET_LC_TERM - SQL to retrieve the term for a specified learning context
• SQL_GET_LC_CROSSLISTED - SQL to retrieve the cross-listed sections
• SQL_GET_USER - SQL to retrieve details for a specified user in a specified learning context; the select clause should return the fields in the same order as the UserVO constructor
• SQL_GET_MEMBERS - SQL to retrieve the IDs of the users who are members of the specified learning context
• SQL_GET_MEMBERS_ROLE - SQL to retrieve the IDs of the users who are members of the specified learning context with a specified role
• SQL_GET_CHILD_MEMBERS - SQL to retrieve the IDs of the users who are members of the specified learning context and the ID of the base learning context in which they are enrolled (which may be a child of a cross-listed parent section)
• SQL_GET_CHILD_MEMBERS_ROLE - SQL to retrieve the IDs of the users who are members of the specified learning context with a specified role and the ID of the base learning context in which they are enrolled (which may be a child of a cross-listed parent section)
• SQL_GET_USER_LC - SQL to retrieve the details of the learning contexts of which the specified user is a member; the select clause should return the fields in the same order as the LearningContextVO constructor
• SQL_GET_USER_LC_TYPE - SQL to retrieve the details of the learning contexts of the specified type of which the specified user is a member; the select clause should return the fields in the same order as the LearningContextVO constructor
• SQL_GET_PERSON_LC - SQL to retrieve the details of the learning contexts of which the specified person is a member; the select clause should return the fields in the same order as the LearningContextVO constructor
• SQL_GET_PERSON_LC_TYPE - SQL to retrieve the details of the learning contexts of the specified type of which the specified user is a member; the select clause should return the fields in the same order as the LearningContextVO constructor
• SQL_GET_USER_ROLES - SQL to retrieve the roles for a specified user in a specified learning context and its parents
• SQL_GET_USER_PRIMARY_INSTRUCTOR - SQL to retrieve the primary status of a section instructor
• SQL_GET_USER_ADDRESSES - SQL to retrieve address details for a user
• SQL_GET_USER_PHONES - SQL to retrieve phone numbers for a user
• SQL_GET_USER_CUSTOM_COLUMNS - SQL to retrieve the custom column values for a user
• SQL_GET_USER_ROLE_DEFINITIONS - SQL to retrieve the ID of user role definitions
• SQL_GET_USER_WHERE_ADDRESS - SQL to retrieve an address field for a user
• SQL_GET_USER_WHERE_PHONE - SQL to retrieve a phone number field for a user
• SQL_GET_USER_WHERE_CUSTOM - SQL to retrieve a custom column value for a user

The property names for SQL queries may be given a suffix of either _ORACLE or _SQLSERVER in order to specify a database-specific version. For example, this is needed when returning the path of a learning context which uses a built-in function which is referenced differently in Oracle and SQL Server. (Note: avoiding this issue by referencing RPT_LEARNING_CONTEXT is not used as this view is only updated at most every 24 hours and hence may not reflect the current state of the database.)

The default values of the properties are as follows:

• dateformat - d-MMM-yyyy
• timeformat - HH:mm
• datasource.name - WebCTDataSource
• SQL_GET_VERSION (only the first record returned is used):
  SELECT major, minor, patch, build
  FROM database_release
  WHERE application = 'WebCT'
  ORDER BY date_installed DESC
• SQL_GET_INSTANCE_NAME:
  SELECT name
  FROM PROXY_TOOL_INSTANCE
  WHERE id = ?
• SQL_GET_LC:
  SELECT LC.adminperiod, LC.enddate_time, LC.end_restrict, LC.fulldescription,
     LC.glcid, LC.source_id, LC.source_name, LC.id, LC.description, LC.name,
     LC.orgname, LC.orgtype, LC.orgunit, LC.parent_id,
     dbo.reporting_interface_pkg$GetLcPath(LC.id), LC.startdate_time, LC.start_restrict,
     T.template_id, LC.type_code, LCT.ims_typelevel
  FROM learning_context LC INNER JOIN lc_type LCT ON LC.type_code = LCT.type_code
     LEFT OUTER JOIN co_lc_assignment T ON LC.id = T.learning_context_id
  WHERE LC.id = ?
• SQL_GET_LC_CHILDREN:
  SELECT id
  FROM learning_context
  WHERE (deleted_flag IS NULL) AND (parent_id = ?)
• SQL_GET_LC_TERM:
  SELECT T.id, T.name, T.source_id, T.source_name, T.datasource, T.inst_lcid,
     T.startdate_time, T.enddate_time, T.description, T.fulldescription,
     T.restrict_learner, T.restrict_sdes, T.restrict_sins, T.restrict_stea
  FROM lc_term T INNER JOIN lc_term_mapping TM ON T.id = TM.lc_term_id
  WHERE TM.assigned_lcid = ?
• SQL_GET_LC_CROSSLISTED:
  SELECT master_lcid, child_lcid
  FROM xlist_lc_mapping
• SQL_GET_USER:
  SELECT P.demo_user, P.given_name, P.login_learning_context_id, P.person_id,
     P.family_name, P.name_prefix, P.name_suffix, P.other_name,
     P.source_id, P.source_name, P.access_status, P.user_id, P.email, P.auth_source,
     P.name_fn, P.name_nickname, P.name_sort, P.demographics_bday, P.demographics_gender
  FROM rpt_person P INNER JOIN learning_context LC ON P.login_learning_context_id = LC.inst_lcid
  WHERE (LC.type_code = 'Domain' OR LC.id = ?) AND P.user_id = ?
• SQL_GET_MEMBERS:
  SELECT DISTINCT P.user_id, P.person_id, P.family_name, P.given_name
  FROM rpt_member M INNER JOIN rpt_person P ON P.person_id = M.person_id
  WHERE M.active = 1 AND M.denied_access = 0 AND M.learning_context_id = ?
• SQL_GET_MEMBERS_ROLE:
  SELECT DISTINCT P.user_id, P.person_id, P.family_name, P.given_name
  FROM rpt_member M INNER JOIN rpt_person P ON P.person_id = M.person_id
  WHERE M.active = 1 AND M.denied_access = 0 AND M.learning_context_id = ? AND M.role IN (?)
• SQL_GET_CHILD_MEMBERS:
  SELECT DISTINCT P.user_id, ISNULL(C.learning_context_id, M.learning_context_id)
  FROM rpt_member M INNER JOIN rpt_person P ON P.person_id = M.person_id
     LEFT OUTER JOIN member T ON T.learning_context_id = M.learning_context_id AND T.person_id = M.person_id
     LEFT OUTER JOIN member C ON T.child_member_id = C.id
  WHERE M.active = 1 AND M.denied_access = 0 AND M.learning_context_id = ?
• SQL_GET_CHILD_MEMBERS_ROLE:
  SELECT DISTINCT P.user_id, ISNULL(C.learning_context_id, M.learning_context_id)
  FROM rpt_member M INNER JOIN rpt_person P ON P.person_id = M.person_id
     LEFT OUTER JOIN member T ON T.learning_context_id = M.learning_context_id AND T.person_id = M.person_id
     LEFT OUTER JOIN member C ON T.child_member_id = C.id
  WHERE M.active = 1 AND M.denied_access = 0 AND M.learning_context_id = ? AND M.role = ?
• SQL_GET_USER_LC:
  SELECT LC.adminperiod, LC.enddate_time, LC.end_restrict, LC.fulldescription,
     LC.glcid, LC.source_id, LC.source_name, LC.id, LC.description, LC.name,
     LC.orgname, LC.orgtype, LC.orgunit, LC.parent_id,
     dbo.reporting_interface_pkg$GetLcPath(LC.id), LC.startdate_time, LC.start_restrict,
     T.template_id, LC.type_code, LCT.ims_typelevel
  FROM learning_context LC INNER JOIN lc_type LCT ON LC.type_code = LCT.type_code
     LEFT OUTER JOIN co_lc_assignment T ON LC.id = T.learning_context_id
  WHERE LC.id IN
     (
      SELECT M.learning_context_id
      FROM rpt_person P INNER JOIN rpt_member M ON P.person_id = M.person_id
      WHERE M.active = 1 AND M.denied_access = 0 AND P.user_id = ?
     )
• SQL_GET_USER_LC_TYPE:
  SELECT LC.adminperiod, LC.enddate_time, LC.end_restrict, LC.fulldescription,
     LC.glcid, LC.source_id, LC.source_name, LC.id, LC.description, LC.name,
     LC.orgname, LC.orgtype, LC.orgunit, LC.parent_id,
     dbo.reporting_interface_pkg$GetLcPath(LC.id), LC.startdate_time, LC.start_restrict,
     T.template_id, LC.type_code, LCT.ims_typelevel
  FROM learning_context LC INNER JOIN lc_type LCT ON LC.type_code = LCT.type_code
     LEFT OUTER JOIN co_lc_assignment T ON LC.id = T.learning_context_id
  WHERE LC.id IN
     (
      SELECT M.learning_context_id
      FROM rpt_person P INNER JOIN rpt_member M ON P.person_id = M.person_id
      WHERE M.active = 1 AND M.denied_access = 0 AND P.user_id = ?
     ) AND LCT.ims_typelevel = ?
• SQL_GET_PERSON_LC:
  SELECT LC.adminperiod, LC.enddate_time, LC.end_restrict, LC.fulldescription,
     LC.glcid, LC.source_id, LC.source_name, LC.id, LC.description, LC.name,
     LC.orgname, LC.orgtype, LC.orgunit, LC.parent_id,
     dbo.reporting_interface_pkg$GetLcPath(LC.id), LC.startdate_time, LC.start_restrict,
     T.template_id, LC.type_code, LCT.ims_typelevel,
     LC.inst_lcid, LC.datasource, LC.email, LC.url, LC.lastarchived
  FROM learning_context LC INNER JOIN lc_type LCT ON LC.type_code = LCT.type_code
  LEFT OUTER JOIN co_lc_assignment T ON LC.id = T.learning_context_id
  WHERE LC.id IN
     (
      SELECT M.learning_context_id
      FROM rpt_member M
      WHERE M.active = 1 AND M.denied_access = 0 AND M.person_id = ?
     )
• SQL_GET_PERSON_LC_TYPE:
  SELECT LC.adminperiod, LC.enddate_time, LC.end_restrict, LC.fulldescription,
     LC.glcid, LC.source_id, LC.source_name, LC.id, LC.description, LC.name,
     LC.orgname, LC.orgtype, LC.orgunit, LC.parent_id,
     dbo.reporting_interface_pkg$GetLcPath(LC.id), LC.startdate_time, LC.start_restrict,
     T.template_id, LC.type_code, LCT.ims_typelevel,
     LC.inst_lcid, LC.datasource, LC.email, LC.url, LC.lastarchived
  FROM learning_context LC INNER JOIN lc_type LCT ON LC.type_code = LCT.type_code
  LEFT OUTER JOIN co_lc_assignment T ON LC.id = T.learning_context_id
  WHERE LC.id IN
     (
      SELECT M.learning_context_id
      FROM rpt_member M
      WHERE M.active = 1 AND M.denied_access = 0 AND M.person_id = ?
     ) AND LCT.ims_typelevel = ?
• SQL_GET_USER_ROLES:
  • SQL Server
    WITH Hierarchy (id, parent_id)
    AS
    (
      SELECT lc.id, lc.parent_id
      FROM learning_context AS lc
      WHERE id = ?
      UNION ALL
      SELECT lc.id, lc.parent_id
      FROM learning_context AS lc
      INNER JOIN Hierarchy AS h ON lc.id = h.parent_id
    )
    SELECT M.role, M.learning_context_id
    FROM rpt_member M INNER JOIN rpt_person P ON M.person_id = P.person_id
    WHERE M.active = 1 and M.denied_access = 0 AND P.user_id = ? AND
       M.learning_context_id IN (SELECT id FROM Hierarchy)
  • Oracle
    SELECT M.role, M.learning_context_id
    FROM rpt_member M INNER JOIN rpt_person P ON M.person_id = P.person_id
    WHERE M.active = 1 and M.denied_access = 0 AND M.learning_context_id IN
       (
        SELECT id
        FROM learning_context
        START WITH id = ?
        CONNECT BY PRIOR parent_id = id
       )
       AND P.user_id = ?
• SQL_GET_USER_PRIMARY_INSTRUCTOR:
  SELECT R.primary_flag
  FROM member M INNER JOIN role R ON M.id = R.member_id
     INNER JOIN role_definition RD ON R.role_definition_id = RD.id
  WHERE RD.name = 'SINS' AND M.person_id = ? AND M.learning_context_id = ?
• SQL_GET_USER_ADDRESSES:
  SELECT AT.address_type, A.adr_pobox, A.adr_street, A.adr_extadd, A.adr_locality, A.adr_region, A.adr_pcode, A.adr_country
  FROM ADDRESS_TYPE AT LEFT OUTER JOIN
        (SELECT * FROM ADDRESS WHERE person_id = ?) A
     ON AT.id = A.address_type_id
• SQL_GET_USER_PHONES:
  SELECT T.Phone_Type, P.Phone_Number
  FROM PHONE_TYPE T LEFT OUTER JOIN (
        SELECT *
        FROM PHONE
        WHERE (ISNULL(DeleteStatus, 0) = 0) AND (Person_ID = ?)
     ) P ON T.ID = P.PHONE_TYPE_ID
• SQL_GET_USER_CUSTOM_COLUMNS:
  SELECT M.Name, CASE WHEN M.DataType = 10 THEN V.Short_String_Value ELSE CAST(V.Number_Value AS varchar(31)) END AS Value
  FROM COL_META M LEFT OUTER JOIN (
        SELECT * FROM COL_VALUE WHERE (ISNULL(DeleteStatus, 0) = 0) AND (Person_ID = ?)
     ) V ON M.ID = V.COL_META_ID
  WHERE (ISNULL(M.DeleteStatus, 0) = 0) AND (M.Owner_Learning_Context_ID = ?)
• SQL_GET_USER_ROLE_DEFINITIONS:
  SELECT id, name, lc_type_code
  FROM role_definition
  WHERE delete_status = 0
• SQL_GET_USER_WHERE_ADDRESS:
  SELECT A.person_id
  FROM ADDRESS A INNER JOIN ADDRESS_TYPE AT ON AT.id = A.address_type_id
  WHERE (ISNULL(A.DeleteStatus, 0) = 0) AND (AT.address_type = ?)
• SQL_GET_USER_WHERE_PHONE:
  SELECT PH.person_id, PH.Phone_Number
  FROM PHONE_TYPE PT INNER JOIN PHONE PH ON PT.ID = PH.PHONE_TYPE_ID
  WHERE (ISNULL(PH.DeleteStatus, 0) = 0) AND (PT.Phone_Type = ?)
• SQL_GET_USER_WHERE_CUSTOM:
  SELECT CV.person_id, CASE WHEN CM.DataType = 10 THEN CV.Short_String_Value ELSE CAST(CV.Number_Value AS varchar(31)) END Setting
  FROM COL_META CM INNER JOIN COL_VALUE CV ON CM.ID = CV.COL_META_ID
  WHERE (ISNULL(CM.DeleteStatus, 0) = 0) AND (ISNULL(CV.DeleteStatus, 0) = 0) AND (CM.Name = ?)

The above default values are appropriate for versions from Application Pack 2 onwards; modified forms for some of these queries are used when installed with an earlier release of WebCT. The following transformations are applied to the specified SQL to convert between the syntax required for SQL Server and Oracle according to the database being used:

This package is comprised of eight published classes (including one deprecated class) which are described in the JavaDocs documentation. The documentation for com.webct.platform.sdkext.authmoduledata is also available. For any pre-existing PowerLinks just replace any references to com.webct.platform.sdkext.authmoduledata with org.oscelot.webct.dao; all classes, methods and properties of the original package are supported by this new one.

LearningContextService

This class provides the following methods:

• getInstance - returns an instance of this service
• getLCAncestor - retrieves the learning context data for an ancestor learning context of a given type.
• getLCChildren - retrieve a list of learning context IDs (children) for a given learning context ID
• getLCIdAncestor - retrieves the learning context Id for an ancestor learning context of a given type
• getLCInfo - retrieves the learning context data given a learning context ID
• getLCPathAncestor - retrieves the path from the server level to an ancestor learning context of a given type
• getCrossListedChildren - retrieves a list of learning context Ids of the children for a given parent learning context ID
• getCrossListedParent - retrieve the learning context of the parent for a given parent learning context ID
• getCrossListedParentInfo - retrieve the learning context of the parent for a given parent learning context ID
• getCrossListedSections - retrieve a map of cross-listed sections

The following example code extract from the login or commit methods of an authentication module illustrates how to retrieve details for the current learning context and a list of its child learning contexts:

...

  WebCTSSOContext ssoContext = getWebCTSSOContext();
  Long lcId = ssoContext.getCurrentLearningContextId();

  LearningContextService lcService = null;
  LearningContextVO sectionLC = null;
  LearningContextVO institutionLC = null;
  List childLCs = null;

// Get the learning context service instance
  try {
    lcService = LearningContextService.getInstance();
  } catch (VistaDataException e) {
    lcService = null;
  }

// Get the current learning context details
  if (lcService != null) {
    try {
      sectionLC = lcService.getLCInfo(lcId);
    } catch (VistaDataException e) {
      sectionLC = null;
    }
  }

// Get a list of child learning contexts
  if (lcService != null) {
    try {
      childLCs = lcService.getLCChildren(lcId.longValue());
      for (Iterator iter = childLCs.iterator(); iter.hasNext();) {
        Long childLC = (Long)iter.next();
        // insert code to execute for each child learning context
      }
    } catch (VistaDataException e) {
      childLCs = null;
    }
  }

// Get the institution learning context details
  if ((lcService != null) && (sectionLC != null)) {
    try {
      institutionLC = lcService.getLCAncestor(sectionLC.getLCId(), LearningContextVO.TYPELEVEL_INSTITUTION);
    } catch (VistaDataException e) {
      institutionLC = null;
    }
  }

...

LearningContextVO

This class provides the following methods for accessing details of a learning context:

• getAdministrativePeriod - get the administrative period
• getChildMembers - get a map of members and the learning context in which their enrolment exists (optionally having a specified role)
• getCrossListedChildren - retrieve a list of learning context Ids of the children for this learning context
• getCrossListedParent - retrieve the learning context Id of the parent for this learning context
• getCrossListedParentInfo - retrieve the LearningContextVO of the parent for this learning context
• getDataSource - get the data source
• getEmail - get the email
• getEndDateTime - get the end date
• getFormattedName - get learning context details based on variable substitution
• getFullDescription - get the full description
• getGlcId - get the global learning context Id
• getImsId - get the IMS Id
• getImsSource - get the IMS source
• getInstitutionLCId - get the parent learning context Id
• getLastArchivedDateTime - get the last archived date
• getLCId - get the learning context Id
• getLongDescription - get the long description
• getMembers - get a list of members (optionally having a specified role/roles and only a specified page)
• getMemberIDsWhere - get a list of member IDs satisfying a specified condition
• getMemberSettingsWhere - get a map of member setting values satisfying a specified condition
• getMembersWhere - get a list of members satisfying a specified condition
• getName - get the learning context name
• getNumMembersWhere - get a count of members satisfying a specified condition
• getOrganizationName - get the organization name
• getOrganizationType - get the organization type
• getOrganizationUnit - get the organization unit
• getParentLCId - get the parent learning context Id
• getPath - get the learning context path
• getStartDateTime - get the start date
• getTemplateId - get the template Id
• getTerm - get the term
• getTitle - get the learning context title
• getTypeLabel - get the learning context type label
• getTypeLevel - get the learning context type level
• getWebLink - get the web link
• isCourse - is this learning context a course?
• isCrossListedChild - is the learning context a cross-listed child section?
• isCrossListedParent - is the learning context a cross-listed parent section?
• isDivision - is this learning context a division?
• isDomain - is this learning context a domain?
• isEndDateRestricted - is the end date restricted?
• isGroup - is this learning context a group?
• isInstitution - is this learning context an institution?
• isSection - is this learning context a section?
• isServer - is this learning context a server?
• isStartDateRestricted - is the start date restricted?
• toString - get details of the learning context as a string

The following example code extract from the login or commit methods of an authentication module illustrates how to obtain the title of the parent course for the current section:

...

  String courseTitle = null;

// Get the parent learning context title
  try {
    Long lcId = getWebCTSSOContext().getCurrentLearningContextId();
    LearningContextVO lc = LearningContextService.getInstance().getLCInfo(lcId);
    lcId = new Long(lc.getParentLcId());
    lc = LearningContextService.getInstance().getLCInfo(lcId);
    courseTitle = lc.getName();
  } catch (VistaDataException e) {
    courseTitle = null;
  }

...

The title of the section could be obtained in a similar way. Alternatively, the getFormmattedName() method could be used to generate a string containing the course and section titles separated by a hyphen:

...

  String title = null;

// Get the course and section titles
  try {
    Long lcId = getWebCTSSOContext().getCurrentLearningContextId();
    LearningContextVO lc = LearningContextService.getInstance().getLCInfo(lcId);
    title = lc.getFormattedName("%1 - %C");
  } catch (VistaDataException e) {
    title = null;
  }

...

See the JavaDocs documentation for details of all the variable substitutions supported by this methood.

The following example code extracts members 26-50 having an email address:

...

  int pageSize = 25;
  int pageNum = 2;
  Long lcId = getWebCTSSOContext().getCurrentLearningContextId();
  try {
    List users = lcId.getMembersWhere(UserVO.SQL_WHERE_USER, 'Email', null, null, pageNum, pageSize);
  }

...

This class also defines a constant value for each type of learning context.

TermVO

This class provides the following methods:

• getAvailabilityToLearners() - get the section availablility for students and auditors
• getAvailabilityToSectionDesigners() - get the section availablility for section designers
• getAvailabilityToSectionInstructors() - get the section availablility for section instructors
• getAvailabilityToTeachingAssistants() - get the section availablility for teaching assistants
• getDataSource() - get the data source
• getEndDateTime() - get the end date (unix epoch time in milliseconds)
• getFullDescription() - get the full description
• getImsId() - get the IMS ID
• getImsSource() - get the IMS source
• getInstitutionLCId() - get the learning context ID of the institution to which the term belongs
• getLongDescription() - get the long description
• getName() - get the term name
• getStartDateTime() - get the start date time (unix epoch time in milliseconds)
• getTermId() - get the term ID
• toString() - get details of the term as a string

This class also defines a constant value for each form of section availablility.

UserService

This class provides the following methods:

• getChildMembers - get all members of the given learning context ID
• getInstance - returns an instance of this service
• getMembers - get members of the given learning context ID (optionally with a specified role and/or a specified page)
• getUser - retrieve a user definition for a user in a given learning context
• getUserRoleId - get a the Id of a user role

The following example code extract from the login or commit methods of an authentication module illustrates how to retrieve details for the current user:

...

  WebCTSSOContext ssoContext = getWebCTSSOContext();
  Long lcId = ssoContext.getCurrentLearningContextId();
  String userId = ssoContext.getUserId();

  UserService userService = null;
  UserVO currentUser = null;

// Get the user service instance
  try {
    userService = UserService.getInstance();
  } catch (VistaDataException e) {
    userService = null;
  }

// Get the current user details
  if (userService != null) {
    try {
      currentUser = userService.getUser(userId, lcId);
    } catch (VistaDataException e) {
      currentUser = null;
    }
  }

...

UserRole

This class has been deprecated; as of version 2 user roles are represented by string constants.

UserVO

This class provides the following methods for accessing details of a user. :

• getAddresses() - get the address details of the user
• getBirthday() - get the birthday of the user
• getCustomColumns() - get the list of custom column values associated with the user
• getDataSource() - get the data source
• getEmail() - get the email address of the user
• getFirstname() - get the first name of the user
• getFormattedName() - get user details based on variable substitution
• getFullname() - get the fullname of the user
• getInstitutionLCId() - get the institution learning context Id for the user
• getLastname() - get the last name of the user
• getLearningContexts() - get the learning contexts in which the user is a member
• getNamePrefix() - get the name prefix of the user
• getNameSuffix() - get the name suffix of the user
• getNickname() - get the nickname of the user
• getOtherName() - get the other name of the user
• getPersonId() - get the person Id for the user
• getPhones() - get the phone number details of the user
• getRoles() - get the list of roles associated with the user
• getSortName() - get the sort name of the user
• getSourceId() - get the source Id for the user
• getSourceName() - get the source name for the user
• getStatus() - get the status of the user
• getUserId() - get the user Id
• getUserRoles() - get the list of roles associated with the user
• hasGender() - has this user got a gender specified?
• isAuditor() - is this user an auditor?
• isCourseDesigner() - is this user a course designer?
• isCourseInstructor() - is this user a course instructor?
• isDemoUser() - is this user a demo student?
• isDivisionAdmin() - is this user a division administrator?
• isDivisionDesigner() - is this user a division designer?
• isDomainAdmin() - is this user a domain admin?
• isDomainDesigner() - is this user a domain designer?
• isGroupAdmin() - is this user a group admin?
• isGroupDesigner() - is this user a group designer?
• isInstitutionalAdmin() - is this user an institutional admin?
• isInstitutionalDesigner() - is this user an institutional designer?
• isPrimarySectionInstructor() - is this user a primary section instructor?
• isSectionDesigner() - is this user a section designer?
• isSectionInstructor() - is this user a section instructor?
• isServerAdmin() - is this user a server administrator?
• isStudent() - is this user a student?
• isTA() - is this user a TA?
• isUserInRole() - is this user in the given role?
• isMale() - is this user a male?
• isFemale() - is this user a female?
• toString() - get details of the user as a string

The following example code extract from the login or commit methods of an authentication module illustrates how to obtain the name of the current user (first name followed by last name):

...

  String userName = null;

// Get the name of the current user
  try {
    Long lcId = getWebCTSSOContext().getCurrentLearningContextId();
    String userId = getWebCTSSOContext().getUserId();
    UserVO user = UserService.getInstance().getUser(userId, lcId);
    userName = (user.getFirstame() != null) ? user.getFirstame() + " " : "";
    userName += (user.getLastame() != null) ? user.getLastame() : "";
  } catch (VistaDataException e) {
    userName = null;
  }

...

An alternative is to use the getFormmattedName() method to generate a string containing the first and last names of a user:

...

  String userName = null;

// Get the name of the current user
  try {
    Long lcId = getWebCTSSOContext().getCurrentLearningContextId();
    String userId = getWebCTSSOContext().getUserId();
    UserVO user = UserService.getInstance().getUser(userId, lcId);
    userName = user.getFormattedName("%a %b");
  } catch (VistaDataException e) {
    userName = null;
  }

...

See the JavaDocs documentation for details of all the variable substitutions supported by this methood.

This class also defines a constant value for each type of user role and each type of address element.

User profile data

Values from a users profile can be accessed using the following methods:

• getAddresses
• getPhones
• getCustomColumns

Each of these methods will return a map containing an entry for each element type even if it has not value for the corresponding user. Thus, at the time of writing, the map returned by getAddresses would contain entries with the following names:

• POBox 1
• Street 1
• ExtAdd 1
• Locality 1
• Region 1
• PCode 1
• Country 1
• POBox 2
• Street 2
• ExtAdd 2
• Locality 2
• Region 2
• PCode 2
• Country 2

Similarly, at the time of writing, the map returned by getPhones would contain entries with the following names:

• Voice 1
• Fax
• Mobile
• Pager
• Voice 2

The getCustomColumns method will return a map containing an entry for each custom column defined for the institution, even if there is no value for the user.

The names of entries in the maps returned by the getAddresses, getPhones and getCustomColumns methods may all be used as variable substitutions in calls to the getFormattedName method. For example, if a user with a surname of Smith has set the first telephone number in their profile to 12 3456 and has a value of Student in custom column named TYPE, then the following code will set the variable userDetails to a value of Student: Smith (12 3456).

...

  String userDetails = null;

// Get the details of the current user
  try {
    Long lcId = getWebCTSSOContext().getCurrentLearningContextId();
    String userId = getWebCTSSOContext().getUserId();
    UserVO user = UserService.getInstance().getUser(userId, lcId);
    userDetails = user.getFormattedName("%{Type}: %b (%{Voice 1})");
  } catch (VistaDataException e) {
    userDetails = null;
  }

...

Further details on the available variable substitutions can be found in the JavaDocs documentation.

VistaDataException

This class defines an exception type which is raised when errors occur in the methods of the LearningContextService, UserService and WebCTApplication classes.

WebCTApplication

This class provides the following methods:

• getApplicationBuildVersion() - get the current build version of WebCT
• getApplicationMajorVersion() - get the current major version of WebCT
• getApplicationMinorVersion() - get the current minor version of WebCT
• getApplicationPatchVersion() - get the current patch version of WebCT
• getApplicationVersion() - get the current version of WebCT
• getApplicationRelease() - get the current release of WebCT
• isDatabaseOracle() - is this WebCT installation using an Oracle database?
• isDatabaseSQLServer() - is this WebCT installation using a Microsoft SQL Server database?
• getInstanceName() - get the name of the proxy tool instance

The following example code extract from the login or commit methods of an authentication module illustrates how to retrieve details for the current learning context and a list of its child learning contexts:

...

  import org.oscelot.webct.dao.WebCTApplication;
  import org.oscelot.webct.dao.VistaDataException;

...

  String appVersion = null;
  int majorVersion = 0;
  Boolean isOracleSystem = null;
  try {
    appVersion = WebCTApplication.getApplicationVersion();
    majorVersion = WebCTApplication.getApplicationMajorVersion();
    isOracleSystem = new Boolean(WebCTApplication.isDatabaseOracle());
  } catch (VistaDataException e) {
  }

...

The following constants are also defined:

• MAJOR_VERSION_AP1: 13 (Application Pack 1)
• MAJOR_VERSION_AP2: 14 (Application Pack 2)
• MAJOR_VERSION_V8: 18 (Release 8)

These constants may be used to test which release of WebCT is being used; for example:

...

  import org.oscelot.webct.dao.WebCTApplication;
  import org.oscelot.webct.dao.VistaDataException;

...

  try {
// check if terms are supported
    if (WebCTApplication.getApplicationMajorVersion() >= WebCTApplication.MAJOR_VERSION_AP2)
// enter term-dependent code here
  } catch (VistaDataException e) {
  }

...

This package is designed to be functionally equivalent to version 1.4 of com.webct.platform.sdkext.authmoduledata available from Blackboard. Its behaviour differs only in respect of bug fixes, some changes to make the methods provided simpler or more consistent and some feature enhancements.

Bugs fixed

LearningContextService class

• The getLCChildren() method returns an up-to-date list of learning contexts (see known issue)

LearningContextVO class

• The getAdministrativePeriod() method returns the value of this property rather than a null (see known issue)
• The getOrganizationUnit() method returns the value of this property rather than the administrative period (see known issue)
• The getFullDesription() and getLongDesription() methods returns the value of these properties rather than a null

UserRole class

• A role has been added for the server administrator which was not previously defined

UserService class

• The list returned by the getMembers() method includes users who have had their roles deleted from the learning context (see known issue)
• The getUser() method may return the details of a user with the same WebCT ID from a different institution (see known issue)
• The list returned by the getUserRoles() method includes roles which have been deleted from the learning context (see also known issue); this also means that the isAuditor(), isCourseDesigner(), isCourseInstructor(), isDesignerInstructor(), isDomainAdmin(), isDomainDesigner(), isGroupAdmin(), isGroupDesigner(), isInstitutionalAdmin(), isInstitutionalDesigner(), isSectionDesigner(), isSectionInstructor(), isStudent() and isTA() methods are also unreliable.
• When a user has no roles in a learning context the getUserRoles() method returns an empty list rather than a list containing a single null object

Changes

The following issues have been identified with the com.webct.platform.sdkext.authmoduledata package which may be resolved by implementing enhancements to this package.

LearningContextService class

• Learning Context IDs are inconsistently defined using both long and java.lang.Long data types in different places. This package will standardise on using java.lang.Long at all times. Thus, getLCChildren(long lcId) will be deprecated and replaced with getLCChildren(java.lang.Long lcId).

LearningContextVO class

• There is no need for the constructor methods to be publicly declared as there are no occasions when an object of this type needs to be instantiated outside this package. This is particularly evidenced by the fact that no methods are provided for setting the property values; it is merely designed as a read-only object. These methods are, therefore, deprecated and a future release of this package will change them to have package scope only.
• As well as inconsistencies with the data type used for Learning Context IDs (see above), the original package is also inconsistent with the abbreviation used. This package will standardise on using LCId to refer to a Learning Context ID. Hence, the getLcId() and getParentLcId() methods will be deprecated and replaced with getLCId() and getParentLCId() which will both return java.lang.Long values.
• The getStartDate() and getEndDate() methods both return the Unix epoch time in milliseconds so these methods will be deprecated and replaced with getStartDateTime() and getEndDateTime() which return a java.util.Long value (rather than java.lang.String).
• The getStartDateRestricted() and getEndDateRestricted() methods are duplicated by isStartDateRestricted() and isEndDateRestricted(); the former pair of methods will be deprecated.

UserRole class

This class does not appear to server any useful purpose. The class represents a role as a combination of a string and an integer value. Since the former value is unique and the latter value appears to have no meaning, the class adds unnecessary complexity. It is, therefore, proposed to deprecate this class and replace the role constants with a set of string constants in the UserVO class.

UserService class

• The getUserRoles() method is duplicated by the UserVO.getUserRoles() method so, given the deprecation of the UserRole class (see above), this method is also deprecated and replaced by UserVO.getRoles().
• The getLearningContexts() method is fundamentally flawed as it tries to identify a user solely by their WebCT ID. Since this ID is only unique within a single institution, an additional parameter is required to allow the institution within which the user is defined to be specified. Thus, the method, as it stands, cannot be relied upon to return the details of the correct user. This method will be deprecated and replaced with UserVO.getLearningContexts(int typeLevel) method.

UserVO class

• There is no need for the constructor methods to be publicly declared as there are no occasions when an object of this type needs to be instantiated outside this package. This is particularly evidenced by the fact that no methods are provided for setting the property values; it is merely designed as a read-only object. These methods are, therefore, deprecated and a future release of this package will change them to have package scope only.
• Since both the getSourceId() and getUserPrimaryKey() methods are equivalent, the latter is deprecated as its name is the most misleading; the value is only unique in combination with the value returned by getSourceName().
• The getDemoUser() method is duplicated by isDemoUser(); the former method will be deprecated.
• The isDesignerInstructor() and isMentor() methods will be deprecated as there are no role of these types.
• As part of the standardisation on using java.lang.Long values for learning contecxt IDs, the getInstitutionLCId() method will be deprecated and replaced with a method of the same name which returns java.lang.Long value instead.
• A set of string constants will be defined for each user role using the same names as those defined in the UserRole class (except that no constant for MENTOR_ROLE or DESIGNER_INSTRUCTOR_ROLE will be created as these roles do not exist).
• Since the UserRole class is deprecated, the userInRole(UserRole role) method is also deprecated; the userInRole(java.lang.String roleName) method remains available for use in its place. The getUserRoles() is also deprecated and a new method (getRoles()) added which returns roles as a list of String elements (rather than UserRole elements).
• A isServerAdministrator() method will be added to test for a user having a role of server administrator similar to the methods provided for other roles. Only Help Desk roles are excluded from having a specific method, but the isUserInRole() can be always used, if required.

Enhancements

The following additional features have been added to update the package for more recent releases of WebCT and provide other useful functionality.

LearningContextService class

• getLCIdAncestor(java.lang.Long lcId, int typeLevel) - get the ID for a particular type of ancestor learning context
• getLCAncestor(java.lang.Long lcId, int typeLevel) - get the information for a particular type of ancestor learning context
• getLCPathAncestor(java.lang.Long lcId, int typeLevel) - get the path to a particular type of ancestor learning context
• getCrossListedChildren(java.lang.Long lcId) - get a list of learning context IDs of the children for a given parent learning context ID.
• getCrossListedParent(java.lang.Long lcId) - get the LearningContextVO object of the parent for a given child learning context ID.
• getCrossListedParentInfo(java.lang.Long lcId) - get the learning context of the parent for a given parent learning context ID.
• getCrossListedSections() - get a map of cross-listed sections.

LearningContextVO class

• getDataSource() - get the data source
• getEmail() - get the email
• getInstitutionLCId() method to return the learning context ID of the institution to which the learning context belongs. A null is returned for learning contexts at the domain or server levels. This method is similar to the one of the same name already implemented in the UserVO class except that the value returned is of type java.lang.Long.
• getLastArchivedDateTime() - get the last archived date
• getWebLink() - get the web link
• getMembers(java.lang.String roleType) will return a list of UserVO objects for each user having the specified role within the learning context; omitting the parameter or specifying a roleType of null will cause users with any role within the learning context to be included in the list.
• getTerm() - method to return the TermVO (see below) for the term to which a section has been assigned (returns null if the learning context is not a section or if it has not been assigned to a term)
• getFormattedName() - get learning context details using a format string with variable substitutions
• getChildMembers() - get a map of members and the learning context in which their enrolment exists.
• getChildMembers(java.lang.String role) - get a map of members with a specified role and the learning context in which their enrolment exists
• getCrossListedChildren() - get a list of learning context Ids of the children for this learning context.
• getCrossListedParent() - get the learning context Id of the parent for this learning context.
• getCrossListedParentInfo() - get the LearningContextVO of the parent for this learning context.
• isCrossListedChild() - is the learning context a cross-listed child section?
• isCrossListedParent() - is the learning context a cross-listed parent section?
• getMembers(java.lang.String role) - get a list of members with a specified role
• getMembers(java.lang.String role, int pageNum, int pageSize) - get a page of members with a specified role
• getMembers(java.util.List roles, int pageNum, int pageSize) - get a page of members with at least one of the specified roles
• getMembersWhere(int fieldType, java.lang.String fieldName, java.lang.String fieldValue, java.util.List roles, int pageNum, int pageSize) - get a list of members satisfying a specified condition
• getMemberSettingsWhere(int fieldType, java.lang.String fieldName, java.lang.String fieldValue, java.util.List roles) - get a map of member setting values satisfying a specified condition
• getNumMembersWhere(int fieldType, java.lang.String fieldName, java.lang.String fieldValue, java.util.List roles) - get a count of members satisfying a specified condition

UserService class

• getChildMembers(java.lang.Long lcId) - get child learning context for all members of the given parent learning context Id
• getUserRoleId(java.lang.String role) - get the ID of a user role

UserVO class

• getDataSource() - get the data source
• isPrimarySectionInstructor() method to determine whether the user is a primary section instructor
• getFullname() - get the fullname
• getNickname() - get the nickname
• getSortName() - get the sort name
• getBirthday() - get the birthday
• getAddresses() - get the address details
• getPhones() - get the phone number details
• isMale() - is the user male?
• isFemale() - is the user female?
• hasGender() - does the user have a gender specified?
• getFormattedName() - get user details using a format string with variable substitutions

The following constants are defined to represent the possible user property type settings:

• int SQL_WHERE_ADDRESS
• int SQL_WHERE_CUSTOM
• int SQL_WHERE_NONE
• int SQL_WHERE_PHONE
• int SQL_WHERE_USER

TermVO class

A new class representing data about terms. It would provide the following methods:

• java.util.Long getInstitutionLCId() - method to return the learning context ID of the institution to which the term belongs.
• java.util.Long getTermId() - get the term ID
• java.lang.String getName() - get the term name
• java.lang.String getImsId() - get the IMS Id
• java.lang.String getImsSource() - get the IMS source
• java.lang.String getDataSource() - get the data source
• java.util.Long getStartDateTime() - get the start date
• java.util.Long getEndDateTime() - get the end date
• java.lang.String getLongDescription() - get the long description
• java.lang.String getFullDescription() - get the full description
• int getAvailabilityToLearners() - get the section availablility for students and auditors (see below)
• int getAvailabilityToSectionDesigners() - get the section availablility for section designers (see below)
• int getAvailabilityToSectionInstructors() - get the section availablility for section instructors (see below)
• int getAvailabilityToTeachingAssistants() - get the section availablility for teaching assistants (see below)

The following constants are defined to represent the possible section availability settings:

• int SECTION_AVAILABLE
• int SECTION_NOT_AVAILABLE
• int SECTION_AVAILABLE_AFTER_TERM_STARTS
• int SECTION_AVAILABLE_BEFORE_TERM_ENDS
• int SECTION_AVAILABLE_BETWEEN_TERM_DATES

WebCTApplication class

A new class is proposed for system-level functionality:

• java.lang.String getApplicationVersion() - method to return the current version of WebCT as a string comprising the major, minor, patch and build version numbers separated by periods.
• int getApplicationMajorVersion() - method to return the major release version number of WebCT.
• int getApplicationMinorVersion() - method to return the minor release version number of WebCT.
• int getApplicationPatchVersion() - method to return the patch release version number of WebCT.
• int getApplicationBuildVersion() - method to return the build release version number of WebCT.
• java.lang.String getApplicationRelease() - method to return the current release of WebCT as a string comprising the major, minor, service pack release numbers separated by periods.
• boolean isDatabaseOracle() - method to determine whether WebCT is using an Oracle database.
• boolean isDatabaseSQLServer() - method to determine whether WebCT is using a Microsoft SQL Server database.

If you experience any problems using this utility try the following to trace the cause:

• inspect the webct.log file for any reported errors
• increase the logging level to DEBUG for org.oscelot either via the GUI as serveradmin or by editing the log4j.properties file in the serverconfs directory

This work is written by Stephen Vickers and is released under a Creative Commons GNU General Public Licence. The WebCTDAO package can be downloaded from OSCELOT where it is also possible to report bugs and submit feature requests.