4.9.2 Structure of the ACL

The structure of the ACL is illustrated by the diagram below.

Thus, the ACL consists of number of "document selections", for each of which a number of access rules (the Access Control Entries) can be defined. In case of the read and write permissions, Access Details can contain finer-grained permissions to allow partial read access and partial write access to the document.

In the Daisy API, the "document selection" is called the ACL object. This is the general term for a protected resource. The subject is an entity wanting to perform an operation on the object. The objects in our case are documents, selected using an expression. The subjects are users (persons or programs acting on their behalf).

The Daisy ACL is evaluated entirely from top to bottom, later rules overwriting the result of earlier rules. The order of the entries is hence important. The evaluation of the ACL is described in detail below.

4.9.2.1 Document selection

A document selection is defined by a Boolean expression, an expression evaluating to either true or false. During ACL evaluation, the document being evaluated will be checked against each of the expressions to see if it matches.

The expression uses the same syntax as in the where clause of the Daisy Query Language. However, the number of identifiers that are available is severely limited. More specifically, you can test on the following things:

• the document type
• collection membership (using the InCollection function)
• document ID (to have rules specific to one document)
• document namespace
• fields for which the ACL-allowed flag of the field type is set to true
• the branch and language
• an ACL-specific identifier called conceptual (more on this in the section on saving new documents)

Some examples of expressions:

InCollection('mycollection')

documentType = 'Navigation' and InCollection('mycollection')

$myfield = 'x' or $myotherfield = 'y'

For the evaluation of these expressions, the data of the fields in the last version is used, not the data from the live version.

4.9.2.2 Access Control Entry

An access control entry specifies that for a certain subject (a specific user or role, or everyone), what permissions the subject has on the document variant. The available permissions are:

• read (+ detail permissions)
• write (+ detail permissions)
• publish
• delete

In the access control entry, for each of these permissions you can specify that the user:

• should be granted the permission
• should be denied the permission
• or that the permission should be left to its current state

4.9.2.2.1 read permission

The read permission obviously gives users the ability to read a document.

When the read permission is granted, it can be further refined with a number of detail permissions:

• can non- live versions be read (= all versions, including those that have never been  live). If not, this also implies the following limitations:
• the list of versions cannot be retrieved
• access to retired documents is denied (regardless of whether they have a live version)
• can historic live versions be read (= all versions that were once live).
• can all fields be read. If not, a list of accessible fields can be specified.
• can all parts be read. If not, a list of accessible parts can be specified.
• can the fulltext index be read. If not, this document will not be returned in queries containing a FullText condition.
• can fulltext index context fragments be retrieved. If one is allowed to perform fulltext searches (= if the fulltext index can be read), this option can be used to prohibit that the user can see context fragments. Context fragments are small parts of content around matching words.
• can the document summary be read.

The first two permissions are additive. If you have the first permission, it doesn't make a difference wether you have the second one or not.

4.9.2.2.2 write permission

The write permission gives users the ability to:

• create documents
• update (save) documents
• take a lock on the documents

When the write permission is granted, it can be further refined with a number of detail permissions:

• can all fields be changed. If not, a list of writable fields can be specified.
• can all parts be changed. If not, a list of writable parts can be specified.
• can the following properties be changed:
• document name
• custom fields
• links
• collection membership
• document type
• reference language
• private flag
• retired flag
• version metadata (change comment, change type, synced-with link)

4.9.2.2.3 publish permission

The publish permission gives users the ability to change the publish/draft state of versions of documents. There is one detail permision:

• change live history. With this permission, the user is allowed to make arbitrary changes in the timeline. Without it, only the 'current live version' can be changed.

4.9.2.2.4 delete permission

The delete permission gives users the ability to delete documents or document variants. This permission only applies to real deletes, not retirement (archival) of documents. In general, it is good practice to disable the delete permission, to avoid users deleting documents by accident.

4.9.2.3 Staging and Live ACL

In Daisy, there are two ACLs: a staging ACL and a live ACL. Only the staging ACL is directly editable. The only way to update the ACL is to first edit the staging ACL, and then put it live (= copy the staging ACL over the live ACL).

Before putting it live, it is possible to first test the staging ACL: you can give a document id, a role id and a user id and get the result of ACL evaluation in return, including an explanation of which ACL rules made the final decision.

In the Daisy Wiki front end, all these operations are available from the administration console. It is recommended that after editing the ACL, you first test it before putting it live, so that you are sure there are no syntax errors in the document selection expressions.