Child pages
  • Delegated Access Tool

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Provide a friendly interface for administrators to delegated delegate user access to specific sites or department levels.
  2. Provide a friendly interface for administrators to delegated delegate shopping period admin privileges for users at the site or departments level.
  3. Provide a friendly interface for delegated users to view, search and access their delegated sites.
  4. Provide a friendly interface for delegated shopping period admins to adjust shopping period data within their scope of privileges.
  5. Allow a user, who have has been granted access to sites, to use access the site using the direct URL for the site to access it.

The delegated access tool allows administrators to search for users and delegate site, role, and shopping period admin access.  It also allows you to select specific tools the user should not have access to.

The easiest way to think of how the tool works is liking relating it to the Role Swap feature in Sakai. Instead of just swapping the role, you can specify the realm and role the user will receive for that particular site or node in the hierarchy.  All child nodes will inherit the parent settings unless overridden.

...

The shopping period tool is just a special use case of the Delegated Access Tool from the perspective of a shopping consumer.  In another words, we treat the .anon or .auth role as a delegated user which we can determine what role they will inherit when they enter a site.  There are three user cases that the shopping period section handles:

...

The Delegated Access Tool was developed by the Longsight Group under contract with Columbia University. It is licensed under the Educational Community License, Version 2.0.

back to index

Local Demo

  • Add the following to your JAVA_OPTS: "-Dsakai.demo=true"
  • Startup Sakai
  • Log in as admin and add Delegated Access to your My Workspace
    • You can use the "Sites" tool and add the tool manually. Just go to "Sites" and select your site. Then "Add/Edit Pages"->"New Page". Enter any title you want and click "Tools"->"New Tool". The select Delegated Access and click "Save" at the bottom.
    • Note: Non admins can add the tool by going to "Worksite Setup" in your My Workspace site then find your My Workspace site in the list and click the checkbox next to it.  Then you click "Edit" on the top.  This will bring you to the "Site Info" page where you can click "Edit Tools".  In this page, you check "Delegated Access" and click save to add this tool to your My Workspace site.
  • Go to the tool and search for yourself and others and set their permissions.

Live Demo

  • log into http://nightly2.sakaiproject.org:80858082/portal
    • username: admin
    • pw: admin
  • Setup Delegated Access Demo:
    • If the Delegated Access tool isn't in the Administration Workspace, Add "Delegated Access" to your My Workspace.
      • Note: you have to do by going to "Worksite Setup" in your My Workspace site then find your My Workspace site in the list and click the checkbox next to it.  Then you click "Edit" on the top.  This will bring you to the "Site Info" page where you can click "Edit Tools".  In this page, you check "Delegated Access" and click save to add this tool to your My Workspace site.
    • Go to tool. 
      • To start you can see how it looks to have access delegated to you by clicking "Search Users" and searching for yourself ("admin"). This is where you can grant access to specific nodes in the hierarchy.  Checking the boxes will enable the permissions.  Doing this enables additional options in the tool which will show up when refreshed.
  • Setup Shopping Period Demo:
    • Add "Delegated Access" to your My Workspace.
      • Note: you have to do by going to "Worksite Setup" in your My Workspace site then find your My Workspace site in the list and click the checkbox next to it.  Then you click "Edit" on the top.  This will bring you to the "Site Info" page where you can click "Edit Tools".  In this page, you check "Delegated Access" and click save to add this tool to your My Workspace site.
    • Add "Shopping Period" tool to the Gateway page (!gateway).  This can be done in the Sites tool on the Administration Workspace.
    • Go to the Delegated Access tool. 
      • To start you can see how it looks to have access delegated to you by clicking "Search Users" and searching for yourself ("admin"). This is where you can grant access to specific nodes in the hierarchy.  Checking the boxes will enable the permissions.  Doing this enables additional options in the tool which will show up when refreshed.
      • Grant yourself "Shopping Admin" permission on the top node and save.
      • Refresh Browser
      • Click top nav link "Shopping Admin"
      • Choose what sites and what permissions you want to test and save.
    •  Log out (or log in as a normal user) and go to the Gateway page and use the Shopping Period tool.

back to index

Screen Shots

Delegated Access Landing Page
This page will show which sites you’ve been granted access to.  You can search your sites or click the title in the node tree.

Image RemovedImage Added

Site Search Page
This page allows you to search through the sites by site id, site title, site term, or instructors

Image RemovedImage Added

User Search Page
This page allows Sakai Administrators to search for user’s to grant privileges to.

Image Removed

Image Added

Search By Access Page

This page allows you to search for users who have access at specific points in your hierarchy.

Image Added

Edit User Privileges Page
This page is where you set a user’s access and shopping admin privileges.

Image RemovedImage Added

Shopping Period Settings Page
This is the page where a shopping period administrator can edit the shopping period information for their sites or departments.

Image RemovedImage Added

back to index

Shopping List Page

This page is where you can search for reports on the current status of active shopping sites as well as all shopping settings

Image RemovedImage Added

back to index

Shopping Period Page

This is the page where a use would access to shop for sites that are open to shopping.

Image Removed Image Added

 
back to index

Instructor Shopping Period Edit Page

...

Delegated access can run in Sakai 2.8.2+ and 2.9.0+.  As of Sakai 10.0, Delegated Access and Hierarchy are included as core tools.

Delegated Access Tool:
https://source.sakaiproject.org/contribsvn//delegatedaccess/

Hierarchy Tool:
https://source.sakaiproject.org/contribsvn/caret/hierarchy/  (*1.2.6+ recommended)anything Sakai10x+) 

Jira
serverSakai
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId66e9c5b5-d22c-30a2-a9d4-703f4354570c
keyDAC-2
Jira
serverSakai
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId66e9c5b5-d22c-30a2-a9d4-703f4354570c
keyDAC-52

You will also need to set the following Columns to "Clob" for Oracle or "mediumblob" for MySQL

  • HIERARCHY_NODE.directChildIds
  • HIERARCHY_NODE.childIds

 

(Mysql)

Code Block
alter table hierarchy_node modify childIds mediumblob;
alter table hierarchy_node modify directChildIds mediumblob;


Special Cases:

  • Running in an large institution:
    • Run trunk Hierarchy Tool (or a version that includes contrib r78264) (DAC-2)
    • You will also need to set the following Columns to "Clob" for Oracle or "mediumblob" for MySQL
      • HIERARCHY_NODE.directChildIds
      • HIERARCHY_NODE.childIds

Steps to build against Sakai Trunk:

...

  • Integration with Evaluations tool

...

...

 

back to index

Sakai.Properties:

Code Block
#delegatedaccess.hierarchy.site.properties
#This property allows you to overwrite the default site hierarchy properties expected in a Site.
#Example:
#delegatedaccess.hierarchy.site.properties.count=3
#delegatedaccess.hierarchy.site.properties.1=School
#delegatedaccess.hierarchy.site.properties.2=Department
#delegatedaccess.hierarchy.site.properties.3=Subject

#delegatedaccess.toolslist
#This property allows you to specify a list of tools you want to be able to select in the “Restrict Tools” list.  Each tool is specified individually.
#Example:
#delegatedaccess.toolslist.count=4
#delegatedaccess.toolslist.1=sakai.gradebook.tool
#delegatedaccess.toolslist.2=sakai.resources
#delegatedaccess.toolslist.3=sakai.samigo
#delegatedaccess.toolslist.4=sakai.announcements

#delegatedaccess.toolslist.sitetype
#This property allows you to choose a site type which the “Restrict Tools” list will be populated from.
#Example:
#delegatedaccess.toolslist.sitetype=course

#delegatedaccess.toolslistexclude
#This property allows you to exclude specific tools from the delegated access and shopping period tools list.
#Example:
#delegatedaccess.toolslistexclude.count=3
#delegatedaccess.toolslistexclude.1=sakai.assignment.grades
#delegatedaccess.toolslistexclude.2=sakai.schedule
#delegatedaccess.toolslistexclude.3=sakai.announcements
 
 
#Setting term field
#delegatedaccess.termfield
#This property allows you to choose what the term field property is for your sites.
#The default term field is "term_eid".  If you don't use that property name, you will need
#to set this to the name you do use.
#This field will be used for searching as well as displaying term options in the list of terms
#Example:
#delegatedaccess.termfield=term

#delegatedaccess.term.useCourseManagementApi
#If you don't use Course Management API for your terms, you will want to set this to false.
#Default is true
#When true:  The term list options are gathered from the Course Management API
#When false: A site property query will be used to find the distinct list of terms based on the term property set (delegatedaccess.termfield)
#Example:
#delegatedaccess.term.userCourseManagementApiuseCourseManagementApi=false

#delegatedaccess.hometools
#If you want to include the Home Tool in the list of restricted tools, then you will need to set this property to the
#list of all possible home tools
#Example:
#delegatedaccess.hometools.count=4
#delegatedaccess.hometools.1=sakai.iframe.site
#delegatedaccess.hometools.2=sakai.synoptic.announcement
#delegatedaccess.hometools.3=sakai.synoptic.chat
#delegatedaccess.hometools.4=sakai.synoptic.messagecenter


#delegatedaccess.realmoptions.shopping
#This field allows you to set the realm options in the edit shopping period page
#Default is !site.*
#Example:
#delegatedaccess.realmoptions.shopping.count=2
#delegatedaccess.realmoptions.shopping.1=!site.template.course
#delegatedaccess.realmoptions.shopping.2=!site.template.portfolio

#delegatedaccess.roleoptions.shopping
#This field alows you to set the role options in the edit shopping period page
#It will filter all roles except these for all realmoptions
#Example:
#delegatedaccess.roleoptions.shopping.count=2
#delegatedaccess.roleoptions.shopping.1=Instructor
#delegatedaccess.roleoptions.shopping.2=access

#Note, if there is only one option for realm and one option for role, then the "User Becomes" column will
#be hidden and all access will default to that realm/role.

#delegatedaccess.realmoptions.delegatedaccess
#This field allows you to set the realm options in the edit users page
#Default is !site.*
#Example
#delegatedaccess.realmoptions.delegatedaccess.count=1
#delegatedaccess.realmoptions.delegatedaccess.1=!site.template.course

#delegatedaccess.roleoptions.delegatedaccess
#This field allows you to set the role options in the edit users page.
#It will filter all roles except these for all realmoptions
#Example
#delegatedaccess.roleoptions.delegatedaccess.count=1
#delegatedaccess.roleoptions.delegatedaccess.1=Instructor

#delegatedaccess.root.title
#This property allows you to set the root title of your hierarchy
#Default is based on the ui.service property, if not set, then "Sakai"
#Example:
#delegatedaccess.root.title=My Root Title

#delegatedaccess.email.errors
#This property enables emails to be sent to the address specified when an
#error occurs in a high level situation (like a job process failure)
#Example:
#delegatedaccess.email.errors=noreply@sakai.com

#delegatedaccess.shopping.instructorEditable
#This property allows instructors to edit their shopping period dates and access information.  False by default.
#You will see the interface in Site Info -> Manage Access
#Example:
#delegatedaccess.shopping.instructorEditable=true

#delegatedaccess.disable.user.tree.view
#False by default.  If you set to true, the tree structure will be removed on a delegated access user's landing page.
#They will still be able to use the search fields to find their sites.
#delegatedaccess.disable.user.tree.view=true


#delegatedaccess.disable.shopping.tree.view
#False by default.  If you set to true, the tree structure will be removed on a shopping tool's landing page.
#Users will still be able to use the search fields to find their sites.
#delegatedaccess.disable.shopping.tree.view=true

#delegatedaccess.term.showLatestXTerms
#shows all terms by default.  If you want to limit the number of terms that show up in the terms field,
#you can set this property to show the latest X number of terms.  The order is set depending on the method
#you use to gather terms.  If you use CourseManagementAPI, then the order is by Start Date.  If you do not use
#CourseManagementAPI, then the order is set by portal.term.order and any non matching terms are put in last
#Example:
#delegatedaccess.term.showLatestXTerms=5

#delegatedaccess.sync.myworkspacetool
#true by default.  This setting will sync a user's MyWorkspace with the Delegated Access tool.  Another words,
#if the user is granted permissions in the tool, it will add the Delegated Access tool to their My Workspace.
#if all the permissions are removed for a user, it will remove the Delegated Access tool from their My Workspace
#Example:
#delegatedaccess.sync.myworkspacetool=true

#delegatedaccess.siteaccess.instructorViewable
#false by default.  This setting controls whether an instructor can see who has been granted access to their site.
#The list of users will show up in "Site Info"->"Manage Access".
#Example
#delegatedaccess.siteaccess.instructorViewable=true

#delegatedaccess.siteaccess.instructorViewable.hiddenRoles
#empty by default.  Use this setting to restrict certain roles in the Site Info -> Manage Access -> View DA Access table.
#Example:
#delegatedaccess.siteaccess.instructorViewable.hiddenRoles.count=1
#delegatedaccess.siteaccess.instructorViewable.hiddenRoles.1=Student

#delegatedaccess.subadmin.realmrole.order
#Create a list of "realm:role;realm:role;" from highest to lowest level of access.
#For instance, if you wanted to order the importance of roles
#of sakai's default permissions, it would look like:
#delegatedaccess.subadmin.realmrole.order.count=3
#delegatedaccess.subadmin.realmrole.order.1=!site.template.course:Instructor;!site.template:maintain;
#delegatedaccess.subadmin.realmrole.order.2=!site.template.course:Teaching Assistant
#delegatedaccess.subadmin.realmrole.order.3=!site.template.course:Student;!site.template:access;
#This will only allow subadmin to assign permissions at their level and below.  
#Any realm/role that isn't in that list will be considered the last level on the bottom.
#If this isn't set, then all options will be available to any sub admin.

#delegatedaccess.enable.active.site.flag
#false by default.  If you want to use this feature, you must apply the patch to jobscheduler attached in
#https://jira.sakaiproject.org/browse/DAC-40.  The job will populate a table which DA will lookup
#to determine whether a course is active or not and display a warning in the site search is its inactive
#ex.
#delegatedaccess.enable.active.site.flag=true

#delegatedaccess.allow.accessadmin.set.allowBecomeUser
#DAC-57Add new permission to allow user to become users within their delegated access
#This property controls whether an "Access Admin" will have the ability to set the 
#advanced option permission: allowBecomeUser
#Note, requires SAK-23829 and DAC-57
#default true
#ex.
#delegatedaccess.allow.accessadmin.set.allowBecomeUser=false
 
#delegatedaccess.enableProviderIdLookup
#false by default.  If you set this to true, the search results table in Delegated Access site search will have
#an extra column to "lookup roster".  This will show you the "provider id" for that site's realm.
#ex.
#delegatedaccess.enableProviderIdLookup=true
 
#delegatedaccess.search.hideTerm
#false by default.  If you set this to true, then the term dropdown option in the search fields will be removed.
#This is useful if you already have term in your hierarchy and you don't want term listed twice in the search
#fields
#ex.
#delegatedaccess.search.hideTerm=true
 
#delegatedaccess.search.hierarchyLabel.{hierarchyLevel}
#This allows you to set labels for your hierarchy search options.  By default it will use the hierarchy level, but you can
#override this by setting the label.  For example:
#Hierarchy = school->dept->subj
#delegatedaccess.search.hierarchyLabel.school=School
#delegatedaccess.search.hierarchyLabel.dept=Deptartment
#delegatedaccess.search.hierarchyLabel.subj=Subject
 
#Suggested Additional Properties:
#https://jira.sakaiproject.org/browse/SAK-13778
#siteinfo.prohibited_role.count=2
#siteinfo.prohibited_role.1=.anon
#siteinfo.prohibited_role.2=.auth

#portal.term.order.count=2
#portal.term.order.1=SPRING_2012
#portal.term.order.2=SUMMER_2012

#jobscheduler.invocation.interval controls the automatic update timing to shopping period settings
#when an instructor or shopping admin makes changes
#jobscheduler.invocation.interval=(default value in seconds is 600 aka 10 mins)   
 
 

back to index

Using the Tool

 

Overview

In order to use the Delegated Access tool in your Sakai instance, you'll need to configure both your instance and all appropriate sites, via property settings. The configuration workflow should be:

  1. Configure Sakai instance

  2. Configure sites

  3. Run hierarchy job via Job Scheduler


Configure instance

To configure your Sakai instance for site hierarchy, you must add a group of property settings to your local.properties file. These settings will determine the quantity, organization, and labels of nodes in the hierarchy.

Example:

delegatedaccess.hierarchy.site.properties.count=3

delegatedaccess.hierarchy.site.properties.1=School

delegatedaccess.hierarchy.site.properties.2=Department

delegatedaccess.hierarchy.site.properties.3=Subject

 

Keep in mind that the number in each node property setting will determine the order of nodes in the hierarchy. With the above example, users opening the hierarchy would:

  • Expand a "School" node to view all of its "Department" nodes

  • Expand a "Department" node to view all of its "Subject" nodes

  • Expand a “Subject” node to view all of its sites

 

Once you have added these property settings, you must restart your Tomcat server(s) for the changes to take effect.

 

Configure sites

To configure a site so it is included in site hierarchy, you must add the appropriate properties to the site.

These properties should align with the global settings for site hierarchy added to your local.properties file:

Global property node value = site property name

Using the previous example of global hierarchy settings, you might add the following property settings to a site:

school=Arts and Sciences

department=Education

subject=Educational Technology

 

You can add site properties to a specific site manually, via the Sites tool in the Admin Workspace. Select the Sites tool and follow these steps:

  1. Find and select appropriate site (search by site name or site ID as necessary).

  2. Click Add/Edit Properties button.

  3. Create first property setting by adding entry in Name and Value field.

  4. As necessary, click New Property button to create other property settings.

  5. Click Save.

Automating site configuration

You may want to automate site configuration as an alternative to adding site properties manually. Site properties can be added automatically via SIS integration, customized code during site creation, or through a daily script that can parse your sites’ id or title into the required site properties for each site (see example script below).

(Note: the following example is based on the hierarchy example above, with “school,” “department,” and “subject” nodes derived from the site titles)

<?php

require "../shared/functions.php";

$conn = mysql_connect(ip, dbuser, pwd);

mysql_select_db(dbname);

$soap = new SoapClient($script_wsdl, array('exceptions' => 0, 'connection_timeout' => 10));

 

$sql = "select SITE_ID, TITLE from SAKAI_SITE where type='course' and SITE_ID not in (select SITE_ID from SAKAI_SITE_PROPERTY where NAME = ‘School’)”;

$res  = mysql_query($sql);

 

while ($row = mysql_fetch_object($res)) {

 $site_id = $row->SITE_ID;

 $site_title = $row->TITLE;

 $pieces = explode(" ", $site_title);

 if(sizeof($pieces > 2)){

   $ss = $soap->setSiteProperty($session, $site_id, ‘School’, $pieces[0]);

   $ss = $soap->setSiteProperty($session, $site_id, 'Department', $pieces[1]);

   $ss = $soap->setSiteProperty($session, $site_id, ‘Subject’, $pieces[2]);

 }

}

?>

 

Run hierarchy job

Once you have configured your Sakai instance and all sites in your instance with the appropriate hierarchy property settings, you must run the Delegated Access Site Hierarchy job. This job populates the hierarchy in the Delegated Access tool, by searching for hierarchy property values in all sites in your instance.

In the Admin Workspace, select the Job Scheduler tool. Then follow these steps:

  1. Click the Jobs button.

  2. Click the New Jobs button.

  3. From the Type menu, select Delegated Access Site Hierarchy Job. In the Job Name field, enter this or another appropriate name.

  4. Click Post.

 

You'll see the job listed on the Jobs page, where you can click the Triggers link for it. You have two options for running the job:

  • Run the job immediately, by clicking Run Job Now.

  • Set up a trigger, such as for every time your SIS integration runs. Click Create Trigger. Enter a name in the Trigger Name field and an appropriate expression in the Cron Expression field. Then, click Post.

Once this job has run, all appropriate hierarchy nodes should display in the Delegated Access tool.

Adding the Tool

There are two tools for delegated access:

...

Once you have set up your hierarchy properties, you will need to add these properties to your sites. This should be done during your site integration job or can be done with a daily script.  The hierarchy job will then look for these properties in your sites and add them to the hierarchy based on their values.  For example, if a site has the following properties: School=Music; Department=Classical; Subject=Beethoven; then it will show up in the hierarchy like Music->Classical->Beethoven->Site

back to index

Site Hierarchy Quartz Job

...

WARNING:  Switching the hierarchy can remove settings.  For instance, if you have a 3 tier hierarchy and you add a new tier between 2 and 3 (e.g. 1->2->New->3->Site), all settings assigned to tier 3 and below will be deleted.

Site Quartz Job had an error and node titles or descriptions are null, causing the hierarchy tree to not properly open in the UI

If there are null values in either the title or description fields of the HIERARCHY_NODE_META table, you will see that the hierarchy in the UI will have trouble loading certain branches, as well as a NPE in the logs.  Run the following queries to remove these nodes from the hierarchy.

Update HIERARCHY_NODE hn

right join (select ID from HIERARCHY_NODE_META where TITLE is null or description is null) a on hn.childIds like concat('%:', concat(a.ID, ':%'))

set hn.childIds = replace(hn.childIds, concat(':', concat(a.ID, ':')), ":");

 

Update HIERARCHY_NODE hn

right join (select ID from HIERARCHY_NODE_META where TITLE is null or description is null) a on hn.directchildIds like concat('%:', concat(a.ID, ':%'))

set hn.directchildIds = replace(hn.directchildIds, concat(':', concat(a.ID, ':')), ":");

 

*Run both of the updates until you see "0 record(s) affected".  Once all updates are complete, then you can run the delete queries below 


Delete From HIERARCHY_PERMS where nodeId in (select ID from HIERARCHY_NODE_META where title is null or description is null);

Delete from HIERARCHY_NODE where id in (select ID from HIERARCHY_NODE_META where title is null or description is null);

Delete From HIERARCHY_NODE_META where title is null or description is null;

 

Getting an error about "Invalid node id, cannot find node with id"

This more than likely means that your sequences for HIERARCHY_NODE and HIERARCHY_NODE_META are out of sync. 

1) Run the script above to remove all null titles/descriptions

2) Update the job last ran flag to a time before you saw this error:
Select * FROM HIERARCHY_PERMS where permission like 'siteHierarchyJobLastRunDate%'
(update this record)

3)  Make sure the Indexes are in sync

There are 2 indexes: 

HIERARCHY_NODE

HIERARCHY_NODE_META

back to index