This question comes up on the lists often enough it warrants an article:
“How do I add a new role to all sites in Sakai?”
A role is assigned to a participant in a site. There are a few defaults, like access and maintain for project sites, and various others for course and portfolio sites.
These roles have a set of permissions attached to them which various tools use to allow/hide access to certain features of tools.
For example the annc.newpermission controls what users can create announcements. If you are a participant of a site and are assigned the role that has this permission enabled, you can create announcements.
How sites get their roles
Sites in Sakai get their list of roles at creation time, copied from the appropriate !site.template.xxx realm, where xxx is the type of site.
For example, if I was to create a site of type project, then that site will get a copy of the roles defined in the !site.template.project realm.
You can see what roles are defined for the appropriate site types in the Admin Realms tool:
Caveat: In the Admin realms tool, note the !site.template realm (ie no .xxx after it). If you create a site with no type, or of a type that doesn’t match any of the other !site.template.xxx’s, then it will use this template instead.
You’ll also note that out-of-the-box there is no !site.template.project realm. Hence, project sites, by default, get their roles from the !site.template realm.
You can either create a !site.template.project realm, or just use the !site.template realm.
So, now we know that sites take a copy of the roles from their template and they are not inherited, i.e you cannot make a change in the template realm and expect it to propagate to the appropriate sites automatically.
Creating a new role
Suppose you want to create a new role called readonly. You want this role in project sites so that you can assign users this role and they can only read things not add, edit or delete.
In the Admin Realms tools, navigate to !site.template or !site.template.project (see paragraph above), and choose ‘Add Role’. You can also select an existing role and choose ‘Copy Role’ to create a new role based on the permissions in the existing role. Give the role an id, ‘readonly’ might be a good choice, perhaps a description, choose the relevant permissions then click ‘Done’.
You’ll see the new role in your realm. Click ‘Save’ to save your changes to that realm.
Now, any site that you create with the matching type (in this case ‘project’) will have this new role available to assign users to.
Existing sites however, will be unchanged.
Modifying an existing role
To modify an existing role, follow the same process as for creating, but this time select the role, adjust the permissions and save.
The !site.helper realm
This is a special realm whereby you can make temporary changes to all roles in all sites. For example, suppose I need to quickly give every maintain user the ‘content.new’ permission. I could adjust the permissions in the !site.helper realm for that role, and then every site with that role will have the new permission.
Caveat: the roles that you want to adjust must first exist in both the !site.helper realm AND the target site, i.e. you can’t create a new role in the !site.helper realm and have it available in all sites.
Populating new/updated roles to existing sites
So if the !site.helper realm doesn’t cascade new roles and creating new roles in the template doesn’t cascade them either, how do we get new or updated roles into every site? The answer is you need to adjust the realm for every site. And let me tell you, you do not want to do this if you have hundreds or thousands of sites.
So fear not! For I have already challenged and defeated this horrific beast.
The solution might come as a surprise to some who didn’t know this beautiful gem was in the Sakai distribution, the web services!
See my earlier post about how to enable the web services in Sakai and secure them, then read on.
Once you have them enabled, you need to install a web service of mine called copyRole .
This is as simple as editing:
SAKAI-SRC/webservices/axis/src/webapp/SakaiScript.jws, putting the copyRole method in, saving and rebuilding the webservices project.
You can even edit the deployed SakaiScript.jws (TOMCAT/webapps/sakai-axis/SakaiScript.jws) but you’ll lose your changes if you redeploy.
Then, get the Perl script sync-roles-in-sites.pl . This is a simple script I wrote to take care of iterating over many sites and adding/updating a role or many roles from a template realm, e.g. !site.template to the given sites. Note that the realm for a site is /site/siteid. You’ll see that in the script.
So, open up the script and take a look. You need to set the username and password, urls to your web services (there are two), the template realm, the list of roles and the target sites. It’s all documented.
You’ll also need the Perl module SOAP::Lite which you can get automatically by running:
perl -MCPAN -e 'install SOAP::Lite
You might want to take a look at test-connection.pl  before running the sync script, as it will check if your web services are working ok.
Then it’s simply a matter of running the script and watching as your roles and permissions are synchronised!