Using the AuthzGroup Service

Information

This explains basic usage of the Sakai AuthzGroup Service. This service is used to find out things about Authz (permission) groups and the users who have those permissions.

Trunk javadocs:
- AuthzGroupService : http://nightly2.sakaiproject.org/javadoc/org/sakaiproject/authz/api/AuthzGroupService.html
- AuthzGroup: http://nightly2.sakaiproject.org/javadoc/org/sakaiproject/authz/api/AuthzGroup.html
Trunk source location: https://source.sakaiproject.org/svn/authz/trunk/

Accessing the AuthzGroupService

You can use Spring Framework to inject the service or use the cover

Using Spring to get the service for your class (e.g. YourAppClass) (recommended)

Add the AuthzGroupService bean to the bean for YourAppClass

<bean id="org.sakaiproject.yourapp.logic.YourAppClass"
		class="org.sakaiproject.yourapp.logic.impl.YourAppClassImpl">
	<property name="authzGroupService"
		ref="org.sakaiproject.authz.api.AuthzGroupService" />
</bean>

Add a variable and setter to YourAppClass to use the service in like so:

private AuthzGroupService authzGroupService;
public void setAuthzGroupService(AuthzGroupService authzGroupService) {
	this.authzGroupService = authzGroupService;
}

Using the cover to get the service
- Note: This is not the recommended method, you should be using Spring to inject the service
1. Setup a variable to hold the instance from the cover
```
private AuthzGroupService authzGroupService;
```
2. Get access to the service using the cover
```
authzGroupService = org.sakaiproject.authz.cover.AuthzGroupService.getInstance();
```

Getting the users associated with a site which have a specific permission

Use this to tie data to a specific use of a tool in an area (probably a site or a section)

Use the ToolManager service to get the current context
```
String currentContext = toolManager.getCurrentPlacement().getContext();
```
- Note: You could also retrieve the context in other ways, this is just the common one
Use the SiteService to get the site reference from the context
```
String siteRef = siteService.siteReference(context);
```
- Note: This could also be a group reference instead of a site reference (in theory)
Create a Collection of the references and pass that to the AuthzGroupService to get the Set of userIds
```
java.util.List azGroups = new java.util.ArrayList();
azGroups.add(siteRef);
java.util.Set userIds = authzGroupService.getUsersIsAllowed("tool.permission", azGroups);
```
- Note: In this case, tool.permission is the permission you registered earlier with the FunctionManager

Setting the permissions for the !site.template (or any template)

Note: You have to be careful with this because it will overwrite the current permissions that the user has setup

Setup a constant for the site template string

private final static String SITE_TEMPLATE = "!site.template";

Use the AuthzGroupService to get the AuthzGroup for SITE_TEMPLATE

try {
	AuthzGroup ag = authzGroupService.getAuthzGroup(SITE_TEMPLATE);

Use the AuthzGroupService to check if ag can be updated
```
	if (authzGroupService.allowUpdate(ag.getId())) {
```

Use the AuthzGroup to set the maintain role to have the permission for the tool and the AuthzGroupService to save the group

		Role r = ag.getRole(ag.getMaintainRole());
		r.allowFunction("tool.permission");
		authzGroupService.save(ag);
		log.info("Added Permissions to group:" + SITE_TEMPLATE);

Log warnings and handle exceptions

	} else {
		log.warn("Cannot update authz group: " + SITE_TEMPLATE);
	}
} catch (GroupNotDefinedException e) {
	log.error("Could not find group: " + SITE_TEMPLATE + ", default perms will not be assigned");
} catch (AuthzPermissionException e) {
	log.error("Could not save group: " + SITE_TEMPLATE);
}