------------------------- Sakai Section Info Tool This document consists the following sections: I. Building and deploying the application and its shared services II. Available service implementations III. Authorization and Section Awareness rules ------------------------- I. Building and deploying the application and its shared services The section info tool can be built as either a standalone web application, or as a tool to be embedded in a sakai portal. The tool depends on several sakai artifacts, even when building standalone. You must therefore build the entire sakai project prior to building the Section Info tool either in embedded or standalone mode. Sakai Embedded Just run 'maven sakai', or build a default (as of Sakai 2.1) sakai installation, which includes the sections tool. Standalone 1. Create a database for the application to use. All tables and sequences will be automatically generated when the app starts up. 2. Configure the database connection by specifying the 'hibernate.properties.dir' property either on the command line or in $HOME/build.properties. This property defines the directory containing the custom hibernate.properties file you'd like to use (copy the one in /sections-app/src/hibernate to your custom location and edit it there). Be sure to include a trailing slash when defining this property. 3. Specify the location of your tomcat 5.5.9 webapps directory (not your sakai tomcat -- you must use a different tomcat installation!) with the 'standalone.deploy.dir' property, either from the command line, in $HOME/build.properties, or in /sections-app/project.properties. Make sure you nclude the trailing slash. 4. Run "maven -Dmode=standalone cln bld" to clean and build the app. This will also copy the war file into your tomcat webapps directory. If you are using -Dmem=false (see below), make sure you include that when running your build: "maven -Dmode=standalone -Dmem=false cln bld", and make sure that your database is empty so the tests don't attempt to insert duplicate records. Due to these constraints, using -Dmem=false is not recommended. Other Settings Each time the sections tool is built, it runs a suite of tests to ensure that the business and database logic is operating correctly. These tests use an in-memory hsql database by default, but can also be configured to use your chosen database (as defined above in Standalone item #2). This is useful for developers wishing to test the application on different database platforms, but shouldn't be needed by someone simply deploying the app. To use your own database settings, issue a build with the additional property '-Dmem=false'. All of the tests roll back any database modification performed, so your data should be in the same state before and after the test suite is run. That being said, it is highly recommended that you run the tests on a clean (empty of records) database to avoid possible data integrity violations (a test may attempt to insert a value that already exists in another record, which may not be allowed due to uniqueness constraints). Data loading The sections tool expects the framework to provide the "course context". Since the sections tool is not intended to manage courses, it can not create new course contexts. Therefore, we need to bootstrap course information so when the app starts, it can find its course context. To load the initial course contexts for standalone mode, run one of the following commands from the 'sections-app' subdirectory. Standalone dataload maven -Dmode=standalone -Dmem=false loadData Standalone gradebook dataload (for running the standalone gradebook on top of section awareness) maven -Dmode=standalone -Dmem=false loadGradebookData Sakai 2.1 dataload (not available) II. Available service implementations The following service implementations are available to support the Section Info tool and its shared services. 1) Standalone: This is appropriate for supporting the standalone webapp, it is not capable of functioning inside the sakai framework. 2) Sakai 2.1: This is the default mode when building the application. This implementation decorates Sakai's native group capabilities with section-specific metadata. III. Authorization and Section Awareness rules The Section Info tool applies the following authorization rules for checking whether a user can perform a particular operation: Add/Edit/Remove Sections -- requires the 'site.upd' authorization function. Modify Section Options -- requires the 'site.upd' authorization function. Modify TA Section Memberships -- requires the 'site.upd' authorization function. Modify Student Section Memberships -- requires either the 'site.upd' or 'site.upd.grp.mbrshp' authorization function. View All Sections -- requires either 'site.upd', 'site.upd.grp.mbrshp' or 'section.role.ta'. View Own Section Enrollments -- requires the 'section.role.student' marker function at the site level. The Section Info tool will display in one of four modes: 1) Full control / Sakai control: Users with site.upd have full control of sections and their memberships as long as the site is not flagged as externally managed. 2) Full control / Enterprise control: Users with site.upd have control of TA memberships in sections, but can not change student enrollments or section metadata, and can not add or remove sections. 3) Enrollment control / Sakai control: Users without site.upd but with site.upd.grp.mbrshp can modify section enrollments, but not TA memberships. They can not add/edit/remove sections or modify section options. 4) Own enrollment control / Sakai control: Users enrolled in a non-enterprise-managed site can join or switch their section enrollments if those options have been enabled in the site. The SectionAwareness API uses the following rules when determining the membership lists of sites and sections: Sites use a "marker" authorization function to determine whether a user is a student, a TA, or an instructor. There could be more than one role with the "marker" authorization function (e.g both 'TA' and 'Head TA' could have the TA marker set, and members of both roles would be returned as Site TAs by SectionAwareness. Students: Find the users who have been granted the 'section.role.student' authorization function. The members in the site with this authorization function are considered students in the site. TAs: Find the users who have been granted the 'section.role.ta' authorization function. The members in the site with this authorization function are considered TAs in the site. Instructors: Find the users who have been granted the 'section.role.instructor' authorization function. The members in the site with this authorization function are considered instructors in the site. Sections use a "marker" authorization function to determine which sakai role contains the list of members. Only one role per section can contain the marker function. If more than one role contains the marker function, SectionAwareness will fail quickly. Since there is no UI exposed to the user for editing section authzGroups, this kind of misconfiguration shouldn't occur. Students: Find the role that contains the 'section.role.student' authorization function. The members in this section's role are considered students in the section. TAs: Find the role that contains the 'section.role.ta' authorization function. The members in this section's role are considered TAs. Instructors: Find the role that contains the 'section.role.instructor' authorization function. The members in this section's role are considered instructors. We must insist that only one section role have any particular marker in a site because, when adding a user to a section, we need to find the one (and only one) role to use when adding the user. If two roles with the same marker function existed in the section's authzGroup, it would be impossible to know which roles to use when determining the section's membership.