Understanding karmantra in detail

When to use karmantra

  • You want to allow your system to assign roles to users autamically (based on rules)
  • You are developing a system that allows groups to have users with different roles.
  • You want to adapt your system's roles over time.
  • You want your admins and users to be notified about changes.
  • Different user roles lead to different possibilities/status/... within your platform

When not to use karmantra

  • You need a role system without writing own code.
  • You need to have a very hierarchic role organization.
  • You only have to define your user roles once and forever.

Modeling principles

  • 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

Usage of karmantra

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.

After you have imported the deployed module, your system can

  • let your system fire triggers for users and their groups,
  • receive a result object, including the users and their role status.

You can use the result and make it persistent in a database, for example.

Example for importing the deployed module

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 ...

ToDos after deploying a role model

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!

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.

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_.py
Where: In the deployed import module

module globals (mandatory)

To check if a rule applies might require access to resources of your system.

File: module_globals.py
Where: In the deployed import module

trigger firing (mandatory)

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.

result format [optional]

If the default result format does not fit your needs, it can be replaced.

File: result.py
Where: In the deployed import module