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

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 delegate user access to specific sites or department levels.
  2. Provide a friendly interface for administrators to 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 has been granted access to sites, to access the site using the direct URL for the site.

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 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.

Shopping Period Tool:

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:

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

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:8082/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.

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.


Search By Access Page

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


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+.  As of Sakai 10.0, Delegated Access and Hierarchy are included as core tools.

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

Hierarchy Tool:
https://source.sakaiproject.org/svn/hierarchy/  (anything Sakai10x+)  SAK-33191 - Hierarchy Service Doesn't Account for Max In Clause for Oracle Resolved SAK-33169 - Hierarchy Table Indexes can get out of sync Resolved

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

  • HIERARCHY_NODE.directChildIds
  • HIERARCHY_NODE.childIds

 

(Mysql)


Special Cases:

 

back to index

Sakai.Properties:

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:

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 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

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:

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

5 Comments

  1. Should there be a step in here for building and deploying the hierarchy tool?

    1. Unknown User (francois_campbell)

      I would like to add my voice to Nicola Monat-Jacobs's , please include the step for building this tool.

       

      The standard mvn clean install sakai:deploy -Dmaven.tomcat.home="..."  , it builds and deploys it. I have also added the configurations listed above into the sakai.properties file, uncommented and modified these configs to make sense to my installation, but there are still no additional tools available in the realms.

  2. "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."

     

    The above does not seem to be working as there is no "Delegated Access" tool listed under the "Edit Tools" for "My Workspace".

    1. I noticed today that the DA tool was missing from the experimental builds server.  There has been some changes to that build, so maybe someone accidentally removed it.  I'll get it back up there.

    2. Looks like the experimental build is pointing to Sakai Trunk, so it's not really an experimental server right now.  You can easily just add "-Dsakai.demo=true" to your JAVA_OPTS in a local instance and demo sites will be created and a hierarchy will be built for you automatically.