$URL: $ $Id: $ I. Introduction From its inception, Sakai has maintained a strong separation between the concept of a generic "site" and an academic "course". This allows the framework to maintain flexibility and to offer non-course-related worksites. The Course Management project provides course-oriented tools and services the ability to utilize course-specific data that can not be modeled in generic site -> member relationships while maintaining Sakai's generic site-orientation. II. Related Projects and Components The /course-management module contains the Course Management API, a hibernate implementation, and a federating implementation that allows for federating course data from multiple sources. See the section on federating CM implementations below. The /providers module contains Sakai's default GroupProvider, which makes use of the CourseManagementService to resolve users memberships. The /roster module contains the Roster tool, which is a client of the CourseManagementService. The /site-manage module contains the Worksite Setup and Site Info tools. Like the Roster tool, these tools are also clients of the CourseManagementService. Additionally, these tools also play an important role in associating sites with "Sections". CM is the source-of-authority for official Sections, and Site Info / WS Setup provides the "glue" that allows us to map between Sakai's Site & Group "providerIds" and CourseManagement's Section "enterpriseIds". III. Supplying CM with data There are several options for supplying Sakai with CM data via the CourseManagement APIs. A. Loading sample data To load sample data into the default hibernate implementation, simply start tomcat with -Dsakai.demo=true. You may customize the sample dataloading procedure here: /cm-impl/hibernate-impl/impl/src/java/org/sakaiproject/coursemanagement/impl/SampleDataLoader.java Note that the presence of existing CM data will cause the SampleDataLoader to fail. If you have existing sample data but would like to update the database with a new data set, empty the CM_* tables before running Sakai with -Dsakai.demo=true. Using -Dsakai.demo=true also loads the sample UserDirectoryProvider. Keep in mind that the CM data and the user data must be kept in sync. If CM returns a member of a section where the member's EID is 'foo', the UserDirectoryProvider should be able to resolve user 'foo'. B.Reconciliation In order to use the hibernate implementation, you need some way to populate the hibernate tables with your enterprise data. This can be accomplished by using the CourseManagementAdministration APIs. Preiodically running a quartz job to add, update, or remove CM objects via this API is a common practice. A sample job is distributed with Sakai: /cm-impl/hibernate-impl/impl/src/java/org/sakaiproject/coursemanagement/impl/job/ClassPathCMSyncJob.java This job reads in simulated enterprise data from an xml file and reconciles the data with entries in the hibernate-managed tables. Consider this job as just a sample to use in constructing your own reconciliation jobs. C. Re-implementation If you prefer to access your enterprise data directly and avoid reconciliation, you should write your own implementation of org.sakaiproject.coursemanagement.api.CourseManagementService. Not all CourseManagementService methods are called in Sakai. As of the 2.5 release, there are three CM clients: the GroupProvider, the Roster tool, and WS Setup / Site Info. Depending on the specific tools and/or group provider you have deployed, you may choose to implement a subset of the CourseManagementService's methods. If some kind of remoting (e.g. webservices) is used in your CM implementation, you should consider adding a caching mechanism to avoid excessive latency in CM service calls. D. Federating multiple data sources Some institutions may use a custom CM Service implementation to connect to an external data source which is 'read only' from the perspective of the Sakai administrators. Using the federated implementation allows an admin to append to or override some of the data provided by the custom implementation. Sakai's default configuration for CM uses the org.sakaiproject.coursemanagement.impl.CourseManagementServiceFederatedImpl implementation to demonstrate how to configure a federated service. See the javadocs on this class and on org.sakaiproject.coursemanagement.impl.CourseManagementServiceSampleChainImpl for more details on writing an implementation that can participate in a federated configuration. IV. Configuring Sakai to use CM A. SectionFieldProvider The CourseManagementService delivers course information the Site Info and Worksite Setup tools. These tools provide multiple UI widgets for specifying courses, one of which is a free-text entry. Some institutions want to provide a single text box for users to specify an section's enterprise ID, while others want multiple text boxes. Editing or re-implementing the OOTB SectionFieldProvider implementation allows an institution to change the default section selection behavior of WS Setup and Site Info. B. GroupProvider The CourseManagementGroupProvider uses memberships, enrollments, and official instructing status to determine what role, if any, a user has in a site. It uses an ordered list of resolvers to check for roles at different levels of the CM hierarchy. As of 2.4, this is Sakai's default group provider. To configure the CM-based group provider, edit /providers/component/src/webapp/WEB-INF/components.xml In the following example, only the SectionRoleResolver will be used to find users and their memberships in Sections. Any memberships defined above this level in the CM hierarchy will not be resolved, and hence will not be added to sites linked to a Section. You may add as many RoleResolvers as you like. Sakai's default configuration includes a SectionRoleResolver, a CourseOfferingRoleResolver, and a CourseSetRoleResolver. 3) Configure the roleMap for each role resolver. In the example above, if a Section member in CM has a role of 'I', this will be translated to the 'Instructor' Sakai role for this site. The ordering of the RoleResolvers is important. Earlier entries override later ones. 4) The SectionRoleResolver has two extra configurations: officialInstructorRole and enrollmentStatusRoleMap. OfficialInstructors in EnrollmentSets attached to a section will be resolved to have a Sakai role as defined by the officialInstructorRole property. Enrollments in EnrollmentSets will be resolved using the enrollmentStatusRoleMap. If an Enrollment is found to be enrolled in a relevant EnrollmentSet, the Enrollment's getStatus() will be compared to keys in this map, and the map's entries define the Sakai role to grant to this user. If the Enrollment status is not found in the map, the user will not be 'provided' to Sakai. C. User Directory Provider Ensure that the active UDP implementation can resolve all user EIDs provided by the active CourseManagementService implementation.