Some systems have a large master list of actions, and then for each role, there would be a tick against each of the actions that users with that role can do.
 
The problem with that kind of approach is that it is best employed when the system has a predefined set of actions that need to be controlled. However, Calpendo is designed to allow for precise control over the detail of what people are allowed to do. This means that it is much more flexible for a variety of situations. That flexibility also leads to a degree of complexity, but this section of the manual will try to make this topic as simple as possible.
 
Permissions are not implemented with an all-encompassing list of actions. The method that is used is to define a small set of simple actions, and then create customised and highly targeted individual Permissions to control what can be done. The overall picture is then obtained by aggregating those individual Permissions.
 
That aggregation is possible due to a mechanism that allows layering of Permissions, where some Permissions can override others. The crucial element in allowing this is the concept that Calpendo supports both authorising Permissions that permit something to be done, and non-authorising Permissions that deny the right to do something.

Breaking An Activity Into Its Parts

Let's start by looking at an example, viewing the content of a booking.

 
This breaks down into the following items:

1.Action
 
Start by looking at the underlying action. Everything is broken down into an action of some sort, and the most common actions are create, read, update and delete. In the example, it is view, or read.

2.Biskit Type
 
Next, look at the type of the data the action will affect. In the example in order to control viewing of the content of a booking, the Biskit Type is booking.

3.Property
 
When trying to read or update something, as in the example, then the action has an impact on individual properties. That means the user may have permission to read some of the properties on the booking, but not all of them.
 
So for some Permissions, it is necessary to define the property controlled by the Permission. For example, to grant or deny the ability to view a particular property on a booking, create a Permission that affects just that one property.
 
Permissions that apply to individual properties are only relevant to reading and updating things. For example, when deleting something, the whole thing is deleted and not just individual properties. So it makes no sense to specify a property on a Permission that controls who can delete data.

Layering Permissions

When defining Permissions, specify the action to be controlled and optionally the Biskit Type and property. Permissions that specify only the action are known as action Permissions. Permissions that specify the action and a Biskit Type are known as Biskit Type Permissions, and Permissions that specify action, Biskit Type and property are known as property Permissions.

 
In a typical system, everybody can read most things. So it is usually easier to start by giving read Permission to everybody to read everything. This can be done with an action Permission for the read action. Then, layered on top of that, create a non-authorising Permission that takes away permission for the things that are not allowed to be read.
 

The layering works by using action Permissions only if there isn't a relevant Biskit Type or property Permission. Similarly, Biskit Type Permissions are used if there isn't a relevant property Permission.

 
There is also a numerical priority that can be specified for each Permission, and that provides another way to layer Permissions because the highest priority Permissions within each of the three layers, action, Biskit Type and property, are considered first.

 

If a relevant Permission can not be found, then permission to perform the action is denied.

Precedence Of Permissions

When sorting through the Permissions to decide which one to apply, Calpendo will only consider those that match the action, Biskit Type, properties, conditions and that also target the user concerned. Also, note that those Permissions that do not specify a Biskit Type will also be considered.
 
Once that filtering has taken place, Calpendo will use property Permissions first, then Biskit Type Permissions, and finally action Permissions. Within each of those three, Permissions are further sorted by priority, and the Permission with the highest numerical value for its priority will be used. If there are multiple Permissions with the same priority, then it is undefined which one will be used. The reason this is required will become apparent after going through the way in which the conditions under which each Permission may be used can be specified.

 

                  Precedence of permission types.

 

When a BiskitDef has another BiskitDef as its parent it will have access to the Permissions created for the parent.

When checking Permissions all the child Permissions will be filtered and acted on. If there is not a relevant Permission then the parents Permissions will be filtered and acted on, for each type of Permission in order of precedence. For the action Update this will be done first using property Permissions, and then BiskitDef Permissions and finally the action Update Permissions. This means all property Permissions on the parent will be checked before any BiskitDef Permissions on the child will be checked.

Conditions

The conditions assigned to a Permission provide a means of very precise control over the situations in which a Permission will apply. For example, there may be different Permissions that apply depending on:

•the resource a booking is made for

•the status of a booking (for example, a booking may be editable while it is a request, but not once it has been approved)

or a particular Permission is to apply when:

•approving a booking

•cancelling a booking

All of these things are specified by the conditions. Here are some examples. Suppose there are two Permissions, both of which apply to updating bookings, and both of which are Biskit Type Permissions (which means they specify the action and Biskit Type but not a property). Permission A has the condition:

•status equals Requested

 
and Permission B has the condition:

•resource equals Wet Lab

In this case, assuming both Permissions apply to the current user, then Permission A will apply whenever the user tries to update a requested booking and Permission B will apply whenever the user tries to update a booking for the Wet Lab resource.
 
What happens when trying to update a requested booking for the Wet Lab. In that case, both Permissions could apply. This is where the Permission priority comes in. If one Permission has a higher priority than the other, then the highest priority Permission will be used. If they have the same priority, then either one could be used.

Authorising And Non-authorising Permissions

When thinking about giving permission for something, one normally thinks in positive terms. That is, authorising permission for something. However, the layering used in Calpendo requires that there is also the notion of non-authorising permissions as well as authorising ones. That means that a Permission can be written that will grant the right to do something at one layer, and then have another Permission at another layer that will explicitly deny the right to do something.
 
For example, there may be an authorising action Permission that allows everybody to read everything, and then a non-authorising property Permission to deny the ability to read the booking price for some people.

Targeting Users

For each Permission, choose which users it will affect.

 

However, it's sometimes easier to say who a Permission shouldn't affect, or to say that it's everybody meeting some criteria, apart from those that meet some other criteria.

 

So Exprodo applications allows the specification of the users a Permission applies to as well as those it does not apply to. The affected users will be everybody the Permission applies to that are not amongst those it does not apply to.

 

Within each of the applies to and does not apply to sections, identify users by employing one or more of the following methods:

•Name individual users or user groups.

•Specify users by the roles they have.

•Specify a property on the object being controlled that will identify a user or user group.

This last item, specifying a property that identifies a user or user group, needs more explanation. For example, a Calpendo booking has an owner that is the user that owns the booking, a booker that is the user that created the booking and a project. Each project also has an owner and users.

 

Consequently, when writing a Permission that affects a booking, users can be targeted by using any of the properties owner, booker, project.owner and project.users.

 

Showing the targeted and untargeted users, defined by the "Applies To" and "Does Not Apply To" users.

Available Actions

The following table shows the available actions, and indicates whether each action uses

action, Biskit Type or property Permissions:

 

 

Create

When a new object is created, action and Biskit Type Permissions for the Create action are checked. The property Permission is checked to see if the property should be rendered read or read/write only by comparing against the default value of the property.

Read, Exists and Email Readable

When a user tries to view an object, Exprodo applications check whether the user has:

•Exists permission on the object to check whether the user is allowed to know that the object exists

•Read permission on each property, which means that property checks are performed on every property on the object.

The value of any property on which the user does not have Read permission will be hidden from the user.

 

When displaying a list of objects, Exists permission will be checked so that only those objects that the user is allowed to know exist will be seen. This also means that when generating a report that counts the number of objects matching some criteria, then the count will not include objects for which the user does not have Exists permission.

 

When sending an email, each object property that is to be included in the text is checked for both Read permission and Email Readable permission. Also, for every property inserted into the email, the object the property comes from is checked for Exists permission.

 

Emails may be read by anybody, and so when Exprodo applications check permissions for what can be included in an email, it checks whether the special user nobody has the relevant permission as well as the user that performed the action that caused an email to be sent. Therefore it is necessary to create a Permission that gives Email Readable permissions to user nobody for any information that is required to go into an email. See Special Users for more details on user nobody.

Update

When a user tries to update an object, Exprodo applications will check for Update permission on the object and also on each property. If permission is denied for any property, then Update permission for the whole object is denied. This is different from viewing an object, where being denied permission to read one property does not stop the user from seeing the other properties.

 

When editing an object, if Exprodo applications can determine that Permissions prevent the user from changing a property, then that property will be rendered in an unmodifiable form. This will prevent the user from making changes that would only be rejected later.

Delete

When deleting an object, Delete action and Biskit Type Permissions are checked.

Run Report

Run Report action Permissions are checked whenever a report is run. This allows the administrator to prevent some types of report being run (for example, to stop some people from running summary or group reports), or the Biskit Type being reported on (for example, to restrict reports about system usage or other things).

 

To control which reports somebody can run, create a Run Report action Permission for the Biskit Type Report. Then place conditions on which reports can be run. If most users are set up not to be able to run a report then make sure the user nobody is in the Does Not Apply To section in order that scheduled reports will run.

 

Run Report Permissions for any Biskit Type other than Report will be ignored.

Execute

There is a workflow Biskit of type System Command which is used to specify which system commands can be run. The administrator must set up an Execute permission on this Biskit, Data Property to None, Authorisation to Grant Permission, and specify in the Conditions which commands are allowed.  eg. Value of command equals groff. They can then specify who it applies to etc.

 

Tthe Execute permissions can be applied to the Layout Biskit to define which Layout individuals can see, rather than using Exists which also causes problems when editing the Layout, as if it doesn't exist for Admin role they cannot see it to edit it.

 

This is also checked when trying to run the Booking Rule Validator so that only permitted users may test Booking Rules. This is important because an Advanced Booking Rule contains user-supplied Java code that will be executed on the server. To cover the potential security issue, users require Execute permission on the Booking Rule.

 

To allow a user to validate Booking Rules, there must be a Permission for the Rule Biskit Type that must have no conditions. A future version of Calpendo will allow the administrator to control which Booking Rules a user can validate. Currently, users can either validate all Booking Rules or no Booking Rules.

Checked Edit

This defines who can use the Checked Edit feature of List Views.

Manage Add-ons

This defines who can use the Add-ons feature

Dump Database

Dump Database action Permissions are checked when trying to using the Database Backup page to generate a copy of all the data in the database.

Update Database Schema

Checked when using the Bakery to modify the database schema.