Permissions.md

@@ -4,8 +4,7 @@
 
 # Permissons
 
-To explain basic permissioning (ignoring workflows), we will use
-a helpdesk example. This is the basic table structure of our example:
+To explain basic permissioning (ignoring workflows), we will use a helpdesk example. This is the basic table structure of our example:
 
 ![permission_inheritance.png](https://bitbucket.org/repo/5qjnRde/images/2897491139-permission_inheritance.png)
 
@@ -15,26 +14,17 @@ There are three groups of users:
 * customers
 * accounting
 
-The setup designed to make sure customers only see their own tickets,
-empoyees to have private comments and the accountants to have a set of departments
-(which are a tree) they are able to do actions for.
+The setup designed to make sure customers only see their own tickets, empoyees to have private comments and the accountants to have a set of departments (which are a tree) they are able to do actions for.
 
-In the following text, we will distinguish between "list" and "join" rights. Both
-are basically "read" rights, but if a user does not have any transitions defined
-on an entity, a listing of that entity will always return an empty list.
+In the following text, we will distinguish between "list" and "join" rights. Both are basically "read" rights, but if a user does not have any transitions defined on an entity, a listing of that entity will always return an empty list.
 
-Nevertheless, it may be permitted to be joined to another table which references
-it, so that an instance can always be retrieved with all it's dependencies. Here,
-the permission on the main entry basically gets inherited by instances it 
-references.
+Nevertheless, it may be permitted to be joined to another table which references it, so that an instance can always be retrieved with all it's dependencies. Here, the permission on the main entry basically gets inherited by instances it references.
 
 See [Category] for an example.
 
 ## Tickets
 
-Apart from read, create, edit and delete actions, there is an additional "set_department" action which
-will set the value of the cost_bearing_department of a ticket. Here is a quick overview of who can do which
-action:
+Apart from read, create, edit and delete actions, there is an additional "set_department" action which will set the value of the cost_bearing_department of a ticket. Here is a quick overview of who can do which action:
 
 
 ```
@@ -46,23 +36,17 @@ accounting   all         -              -       -        -     only certain depa
 ----------------------------------------------------------------------------------------
 ```
 
-An employee can create a ticket on behalf of a different user. A customer can
-only create tickets for herself.
+An employee can create a ticket on behalf of a different user. A customer can only create tickets for herself.
 
-A delete will automatically cascade to referenced instances, regardless of
-permissions on the referenced instances.
+A delete will automatically cascade to referenced instances, regardless of permissions on the referenced instances.
 
-In our example, this means that a customer deletes a ticket including the
-private comments made by employees.
+In our example, this means that a customer deletes a ticket including the private comments made by employees.
 
-The set_department transition for accounting will only allow those departments
-to be set which are whthin the user's permissions. See [Departments].
+The set_department transition for accounting will only allow those departments to be set which are whthin the user's permissions. See [Departments].
 
 ## Category
 
-The category table has no explicit permission set at all. But, to enable
-the creating of a ticket, where it is a required field, full read
-access is granted to anyone who can create tickets:
+The category table has no explicit permission set at all. But, to enable the creating of a ticket, where it is a required field, full read access is granted to anyone who can create tickets:
 
 
 ```
@@ -74,15 +58,11 @@ accounting     -     [ticket]   -       -       -
 --------------------------------------------------
 ```
 
-Accounting has no direct read access but can still join any category which is being 
-referenced in the ticket table by tickets. This is restricted to those tickets
-the user has list rights on.
+Accounting has no direct read access but can still join any category which is being referenced in the ticket table by tickets. This is restricted to those tickets the user has list rights on.
 
 ## Public Comments
 
-Public comments can be written by customers and employees, only the ticket creator
-can edit or delete a ticket. This ensures that even an employee can not edit or delete
-anyone else's comments.
+Public comments can be written by customers and employees, only the ticket creator can edit or delete a ticket. This ensures that even an employee can not edit or delete anyone else's comments.
 
 ```
              list         join on    create       edit       delete  
@@ -93,17 +73,13 @@ accounting     -             -         -           -          -
 -------------------------------------------------------------------
 ```
 
-Because the binding of the actions on this table is the "creating_client", a listing
-of this entity will return only those comments owned by the user. 
+Because the binding of the actions on this table is the "creating_client", a listing of this entity will return only those comments owned by the user. 
 
-Nevertheless, joining this table on ticket will work and return any instances
-that reference a ticket a user has rights to.
+Nevertheless, joining this table on ticket will work and return any instances that reference a ticket a user has rights to.
 
-So, in our case, an employee has access to all tickets and will therefore be able to join
-all public comments.
+So, in our case, an employee has access to all tickets and will therefore be able to join all public comments.
 
-A customer will be able to join her own and any other user's comments onto
-her own tickets.
+A customer will be able to join her own and any other user's comments onto her own tickets.
 
 ## Private Comments
 
@@ -118,14 +94,22 @@ accounting     -        -           -           -          -
 -------
 ```
 
-Because customers and accounting have no actions defined on this entity and it's not referenced
-by any other entity (they have access to), they do not see it at all.
+Because customers and accounting have no actions defined on this entity and it's not referenced by any other entity (they have access to), they do not see it at all.
 
 ## Departments
 
-Departments have a "parent" attribute which may refer to an instance in the same entity.
-This means, that those instances can be represented as a tree and permission can be set on
-nodes of the tree and delegation of responsibilities is possible.
+Quick permission overview:
+
+```
+             list       join on    create   edit  delete  
+----------------------------------------------------------------            
+employee       -       [ticket]      -        -      -     
+customer       -       [ticket]      -        -      -
+accounting   see tree  [ticket]      -        -      -
+----------------------------------------------------------------
+```
+
+Departments have a "parent" attribute which may refer to an instance in the same entity. This means, that those instances can be represented as a tree and permission can be set on nodes of the tree and delegation of responsibilities is possible.
 
 This is the example we're going to look at:
 
@@ -137,11 +121,8 @@ The colored dots point out where new people are being assigned.
 
 ### global vs delegable vs local
 
-Global and delegable assignment both travel down the defined tree. Local puts the
-assignement on one node only.
+Global and delegable assignment both travel down the defined tree. Local puts the assignement on one node only.
 
-Global means that the permission is set independent of other people having an
-assignment set on a node.
+Global means that the permission is set independent of other people having an assignment set on a node.
 
-Deleigable means that the assignment only works where no one else has been assigned. Otherwise, 
-the rest of the tree is "cut off".
+Deleigable means that the assignment only works where no one else has been assigned. Otherwise, the rest of the tree is "cut off".
\ No newline at end of file
\ No newline at end of file