Child pages
  • Delegated Access Tool
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 87 Next »

Delegated Access and Shopping Period Tools

Index

About

The delegated access tool controls both delegating access to users outside of the site membership realm as well as setting up and controlling site shopping period information.  To make it easier to describe, I will break the description into two tools: “Delegated Access Tool” and “Shopping Period Tool”.

Delegated Access Tool:

The delegated access tool has five primary functionalities:  

  1. Provide a friendly interface for administrators to delegated user access to specific sites or department levels.
  2. Provide a friendly interface for administrators to delegated 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 been granted access to sites, to use 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 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.

Shopping Period Tool:

The shopping period tool is just a special use case of the Delegated Access Tool from the perspective of 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:

User Case: Administrator:

When a user who has been granted shopping period administrative privileges goes into the delegated access tool, they will see a link for “Shopping Period Admin”.  Here they can modify what role a .anon or .auth (public/logged in) user will inherit when they enter.  They can also choose which tools are open as well as the open and close date for the shopping period for that site or department.

Use Case: Instructor:

If you enable the instructor to override shopping settings, then the instructor will have an interface in the "Site Info" tool under the link "Manage Access" where he/she can modify their course's shopping settings.  This allows an instructor to opt in or out of the shopping period.

User Case: Shopper:

When a user who wants to shop for a particular site goes to the Shopping Period tool, they will see a node structure and a search box to look for a particular site they want to test out.  This tool, for example, can be added to Sakai’s !Gateway site so unauthorized users can view it.  When the user finds the site they want, they just click the link and go to the site.

back to index

Authorship and Licensing

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

Live Demo

  • log into http://nightly2.sakaiproject.org:8085/portal
    • username: admin
    • pw: admin
  • Setup Delegated Access 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.
    • 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.

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

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

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

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

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

back to index

Shopping Period Page

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


back to index

Instructor Shopping Period Edit Page

This page allows an instructor to set their own shopping period status for their site.  This is controlled by a sakai.property. An instructor can access it by going to "Site Info -> Manage Access" in their site.


back to index

Building

Source Location and Patches

Delegated access can run in Sakai 2.8.2+ and 2.9.0+

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

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

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
  • Integration with Evaluations tool

Steps to build against Sakai Trunk:

  1. svn co https://source.sakaiproject.org/contrib/caret/hierarchy/tags/hierarchy-1.2.6/ hierarchy
  2. cd hierarchy
  3. mvn clean install sakai:deploy
  4. cd ..
  5. svn co https://source.sakaiproject.org/contrib/delegatedaccess/trunk delegatedaccess
  6. cd delegatedaccess
  7. mvn clean install sakai:deploy

back to index

Sakai.Properties:

#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

#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.useCourseManagementApi=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
#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

Adding the Tool

There are two tools for delegated access:

sakai.delegatedaccess              
sakai.delegatedaccess.shopping

The “sakai.delegatedaccess” tool is set so anyone can add it to their MyWorkspace.  This isn’t a security issue since only Sakai Administrators have the ability to delegate site access and shopping period administration privileges.  If a user doesn’t have any privileges, it will just say they have no access.  You will want to add this to the Administration Workspace site.

The “sakai.delegatedaccess.shopping” tool is just a read only view of the Shopping period sites that are actively ready to be accessed.  This should be added somewhere where .anon user’s can access it.  One suggestion would be the !Gateway page.

back to index

Create a Site Hierarchy

The default hierarchy is based on a site's property values (in order):
School
Department
Subject

You can overwrite the hierarchy structure in sakai.properties with:

delegatedaccess.hierarchy.site.properties
ex:
delegatedaccess.hierarchy.site.properties.count=4
delegatedaccess.hierarchy.site.properties.1=Top
delegatedaccess.hierarchy.site.properties.2=Middle
delegatedaccess.hierarchy.site.properties.3=Middle2
delegatedaccess.hierarchy.site.properties.4=Bottom

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.

back to index

Site Hierarchy Quartz Job

The name of the quartz job is: Delegated Access Site Hierarchy Job

This is the default quartz job to populate/update(add/remove) the Delegated Access site hierarchy. It searches through all sites in Sakai and looks for structure properties tied to the site. You can run it as many times as you want. The best bet would be to set up a quartz trigger to go off after every time your site integration runs.  This job will add/move/remove site’s within the hierarchy.

back to index

Shopping Period Quartz Job

The name of this quartz job is: Delegated Access Shopping period Job

This job goes through the shopping period settings and adds and removes roles and site properties that are used to open and close a site for shopping.  Every time the shopping period settings are modified, this job is automatically scheduled to run against the changed nodes.  You also need schedule this job to run nightly through the jobscheduler tool.  Doing this syncs all shopping sites instead of sites that just have been modified.  This is needed to open and close the shopping sites based on their settings.

back to index

Sakai Administrator User Use Case

Go to the tool and click "Search Users" and find a user you want to delegate access for. Click their name.

The edit user page allows you to assign delegated access as well as shopping period admin permissions for this user.

For the "Shopping Admin" column, you can select the checkbox next to the level/site you want this user to have control over setting shopping period settings for. The nodes and children of the nodes you select for "Shopping Admin" will show up for the user in the "Shopping Period" link.

For the "Site Access" column, you can select which level/site you want the user to have access to. When you choose "Site Access", you must fill out what role the user will become when they visit that site or a site that under that level. You also have the ability to choose which tools are restricted for this user by clicking the "Restrict Tools" link. All child nodes will inherit their parents settings unless you have specifically overridden them. The nodes and children of the nodes you select for "Site Access" will show up for the user in the "Delegated Access" link. When you are done, click save or click cancel to undo all changes.      

back to index

Delegated Access User Use Case

By default the tool can be added to a user's My Workspace. Since only administrators can delegate access, a regular user won't be able to modify anything.  If the user doesn't have any access delegated to them, they will see a message saying so. Otherwise, you will see a node structure in which you can navigate and click on the sites you've been granted access to. Since this tool populates the delegated access information during login, a user could also use direct links to a delegated site.

back to index

Delegated Shopping Admin User Use Case

For a user who has been granted shopping admin privileges, they will be able to click the “Shopping Period” link on the top.

This page allows you to set the shopping period settings for the sites you've been granted permission to update. To set the shopping period settings, you can select the checkbox next to the level/site that you want to set. Note, you will only see a checkbox next to a node you have permission to modify. First, when you select a node, you must set the "Authorization" setting. The two options are ".anon" and ".auth". ".anon" is for anonymous users who do not need to log in to shop in this site. ".auth" is for users who must log in first in order to shop in this site. Next, you need to choose the role the user will become when they are shopping. Finally, you need to set the dates during which the shopping period will be open. You also have the ability to choose which tools are restricted for shoppers by clicking the "Restrict Tools" link and selecting the tools you want to restrict. All child nodes will inherit their parents settings unless you have specifically overridden them. When you are done, click save or click cancel to undo all changes.      

back to index

Shopping Instructor Use Case

If the properties are set to allow instructors to modify shopping period settings, then the instructor just needs to go to "Site Info->Manage Access" and override the shopping period settings.  The instructor can modify any setting for their site: Visibility, Start Date, End Date, Role, and Show Tools.

Shopping User Use Case

The shopping user is a person who is interested in trying a site that has been set up for shopping.  This user will go to shopping period tool (more than likely in the !Gateway page).  Here they will be able to see all their options in a node architecture and they will be able to search for sites by ID or Title.  When they have found the site they want to shop for, they will click the link for that site and inherit the privileges for that shopping period.

back to index

RESTful Services

  • GET /direct/delegated_access/SITE_ID
    • returns the node's shopping period information
  • POST /direct/delegated_access/SITE_ID
    • updates the node's shopping period information.  Parameters include:
      • shoppingAuth (string)
      • shoppingStartDate (string)
      • shoppingEndDate (string)
      • shoppingRealm (string)
      • shoppingRole (string)
      • shoppingShowTools (string or string[])
      • directAccess (boolean)
  • GET /direct/delegated_access/shoppingOptions/authorization
    • returns a list of available shopping period authorization options (i.e. .anon, .auth)
  • GET /direct/delegated_access/shoppingOptions/roles
    • returns a list of available shopping period roles
  • GET /direct/delegated_access/shoppingOptions/tools
    • returns a list of available shopping period tools to display
  • GET /direct/delegated_access/access/site/SITE_ID
    • returns a list of users who have access to the site

back to index

Architecture

Basic Tree Structure

This is the tree structure for both the Shopping Period Tree and Delegated Access Tree.

back to index

Delegated Access Tree Node

This is the basic tree node structure for every node in the Delegated Access tree.  The shopping period tree node is just 3 properties: Node Id, Site Id, Site Reference.

back to index

Trouble Shooting

Changed hierarchy structure and need to reprocess sites

If you changed the hierarchy structure, you will need to re-process all sites with the Site Hierarchy Quartz Job.  For performance reasons, there is a "job last successfully ran" time stamp that will only process sites that have been added/removed/modified since that date.  In order to reprocess all sites, you will need to remove this flag like so:

DELETE FROM HIERARCHY_PERMS where permission like 'siteHierarchyJobLastRunDate%'

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

 

  • No labels