Commit 5a25fd63 authored by Sandro Eiler's avatar Sandro Eiler 🐌

Updated documentation.

parent b1926c71
......@@ -17,66 +17,81 @@ When not to use karmantra
- You need to have a very hierarchic role organization.
- You only have to define your user roles once and forever.
Definitions
------------
Modeling principles
-------------------
Role
* a role can have multiple rules
* a rule can be used by multiple roles
* one rule can have one trigger
* a trigger can be mapped to multiple rules
Rule
Trigger
One rule can have one trigger and one trigger can have multiple rules. So in case you wanted to have an additional trigger, you can simply add a rule before. This ensures better understandability and documentation of how your model works.
Usage of/interaction with karmantra
Usage of karmantra
------------------------------------
TODO Difference: Interface and module
To get your desired outcome, follow these three steps:
Whenever you use _karmantra_ for creating/modifying a role model, it will deploy the result into your stated location.
The deployment includes the file `config.yml` and a folder `karmantra`. The folder is an importable python-module.
The config-file is needed by karmantra to update your module.
The module includes not only the role model, but also the role evaluation mechanism.
**1. Module generation**
After you have imported the deployed module, your system can
_karmantra_ will provide you with an importable module.
* let your system fire triggers for users and their groups,
* receive a result object, including the users and their role status.
Therefore you have to specify:
- a path, where the outcoming module will be located
- names for your roles, rules and triggers
- a group wrapper, allowing you to use arbitrary group objects
You can use the result and make it persistent in a database, for example.
**2. Including module**
### Example for importing the deployed module
```python
import karmantra
# your users and group instances ...
results = karmantra.fired_trigger("updated_profile", [example_user], example_group)
for e in results:
if e.status_changed:
# Do something ...
```
**3. Using the module**
ToDos after deploying a role model
----------------------------------
TODO
The files of the following, which have to exist in karmantra's deployed python module, will be existing.
You will find all necessary steps to do as comments within these files!
**Modifying the module**
If you don't want to provide karmantra with the initial information or if you want to modify the module manually, you can get your hands dirty by yourself of course.
If you want to avoid thinking about how _karmantra_ works, our interface provides an easy walkthrough approach!
You can add, remove or alter e.g. your roles, rules and triggers from here.
### wrapper (mandatory)
The wrapper ensures that arbitrary group and user objects can be used by karmantras deployed python module.
You will have to specify how the role evaluation framework can extract the needed information in the required way.
The Command Line Interface
--------------------------
**File:** wrapper.py
**Where:** In the deployed import module
### rules (mandatory)
You will have to implement the rule functions which are needed to check if the rules apply for a user. A rule can be, for example, that the user has a specific attribute value or that a system event occurred.
**Files:** rule\_<rulename>.py
**Where:** In the deployed import module
TODO
### module globals (mandatory)
To check if a rule applies might require access to resources of your system.
Updating a project
------------------
**File:** module\_globals.py
**Where:** In the deployed import module
A project is updated whenever a developer wants to add/remove/modify roles, rules and triggers as well as she wants to alter the configuration for _kramnatra_'s roles.
### trigger firing (mandatory)
> :memo: **Behind the scenes...**
... _karmantra_ has to read the current state and write back the altered version of the project. Writing python code with all needed input from the developers is implemented through templates. Reading existing generated static python code for modification has to be done with a different approach since it's not trivial to reverse engineer paramters from ([stackoverflow](https://stackoverflow.com/questions/37813550/is-it-possible-to-use-a-jinja2-template-to-reverse-engineer-the-parameters-from)). Knowing this, the generated python code includes a behaviour of an interface returning the values that we might need to change ([stackoverflow](https://stackoverflow.com/questions/37303036/load-source-file-without-a-module)).
Wherever triggers have to be fired, the role evaluation tool has to be indicated as trigger receiver.
**Where:** In your system, where triggers are fired.
### Configuration file
### result format [optional]
By default, where _karmantra_s module is placed, you will find a configuration file as well.
In the configuration file, following information can be found:
If the default result format does not fit your needs, it can be replaced.
TODO
**File:** result.py
**Where:** In the deployed import module
......@@ -33,5 +33,3 @@ Its motivation comes from the fact that about one billion people have to hunger
Foodsaving groups intend to raise awareness for production and consumption of food through saving food.
Karrot provides the possibility for groups to organize via its platform.
Its idea is to use automated role assignment without interfering with group’s decisions on role assignment.
Check it out and
mkdocs-material==4.4.3
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment