Overview

This guide is for laying out what you need to do in order to add the Permissions Helper to a standard MVC/JSP- based Sakai tool (for this example, we are looking at the Kaltura media player which was done using Spring MVC). The Permissions Helper allows you to add a screen which gives the appropriate users access to quickly setting the tool specific permissions. For example, after adding this to the Kaltura Media Tool, we can see this:

It is essentially a shortcut for having to go into the Realms section of Sakai to configure the site permissions.

Step 1 - Server Side Controller Code

We start with the controller code. This should essentially work the same for most standard JSP frameworks. The breakdown of what is being done is show below this code sample. For the most part, a few specific details must be set into the ToolSession attributes and then you simply call the HelperTool's help method.

    protected ModelAndView handleRequestInternal(HttpServletRequest request, HttpServletResponse response) throws Exception {
        ToolSession toolSession = sessionManager.getCurrentToolSession();
        toolSession.setAttribute(PermissionsHelper.TARGET_REF, external.getCurrentLocationId());
        toolSession.setAttribute(PermissionsHelper.PREFIX, "kaltura.");

        ResourceLoader permissionsResourceBundle = new ResourceLoader("permissions");
        HashMap<String, String> permissionsResourceBundleValues = new HashMap<String, String>();
        for (Object key : permissionsResourceBundle.keySet()) {
            permissionsResourceBundleValues.put((String) key, (String) permissionsResourceBundle.get(key));
        }
        toolSession.setAttribute("permissionDescriptions", permissionsResourceBundleValues);
        toolSession.setAttribute(PermissionsHelper.DESCRIPTION, getPermissionsMessage(permissionsResourceBundle));

        ActiveTool helperTool = ActiveToolManager.getActiveTool("sakai.permissions.helper");
        toolSession.setAttribute(helperTool.getId() + Tool.HELPER_DONE_URL, request.getContextPath() + "/listCollections.htm");

        try {
            helperTool.help(request, response, "", "");
        } catch (ToolException e) {
            log.error("Exception trying to use permissions helper", e);
            throw new RuntimeException(e);
        }
        return null;
    }

• Line 3: Sets the location that the helper tool is going to render the grid.
• Line 4: Sets the prefix of the permissions associated with the tool. For this tool all the permissions start with"kaltura."(**IMPORTANT - the period is part of the prefix)
• Lines 6-12: Here we load the resource bundle that describes each of the permissions (described further below).
• Line 14: Get the Helper tool
• Line 15: Set the return location (from either Save or Cancel).
• Line 18: Call the helper's help method, which will build the page for us.
• Line 23: Do nothing - the helper tool will cause the user's request to be redirected so that the helper tool can write to the output stream. Since this will have already occurred, we don't want the framework (Spring MVC in this case) to do anything else.

Step 2 - Properties File

Next, rather than showing the permission keys (as they are displayed in the realms displays), we can show descriptive text. To do this, we create a properties file with descriptions of each key. For the properties file, the matching property description key values must be prefixed with *desc\-* and the remaining portion of the key will match the permission key. Other key-value pairs can also be added to this file.

desc-kaltura.admin=Allow user to edit collections and items in them (as collection permissions allow)
desc-kaltura.admin.perms=Allow user to grant/revoke the user permissions for a location
desc-kaltura.manager=Allow the user to edit the permissions on any items (as collection permissions allow)
desc-kaltura.editor=Allow user to edit the meta data for any items
desc-kaltura.write=Allow user to upload content and update the meta data on it (owned items only)
desc-kaltura.read=Allow the user to view any content in a location which is not hidden
desc-kaltura.uploadSpecial=Allow the user to access custom special uploader (instead of the default one)
desc-kaltura.showSiteLibrary=Allow the user to see the Site library, only if Kaltura is configured to require this permission. 
desc-kaltura.showMyMedia=Allows a user to access/see the My Media tab, which shows all the uploaded media for the user across sites.
permissions.description=Set permissions for {0} in worksite ''{1}''

The descriptions are loaded into a map and set into the ToolSession attributes with the key permissionDescriptions.

Beyond that, there isn't much left to do.You need to add a link to your controller (making sure that only those that have the correct access can see it) somewhere within your JSP pages. Users must have the realm.upd permission to see the page.