adjutant/doc/source/plugins.rst

##############################
Creating Plugins for Adjutant
##############################

As Adjutant is built on top of Django, we've used parts of Django's installed
apps system to allow us a plugin mechanism that allows additional actions and
views to be brought in via external sources. This allows company specific or
deployer specific changes to easily live outside of the core service and simply
extend the core service where and when need.

An example of such a plugin is here:
https://github.com/catalyst/adjutant-odoo

Building DelegateAPIs
=====================

New DelegateAPIs should inherit from adjutant.api.v1.base.BaseDelegateAPI
can be registered as such::

    from adjutant.api.v1.models import register_delegate_api_class,

    from myplugin import apis

    register_delegate_api_class(r'^my-plugin/some-action/?$', apis.MyAPIView)

A DelegateAPI must both be registered with a valid URL and specified in
ACTIVE_DELEGATE_APIS in the configuration to be accessible.

A new DelegateAPI from a plugin can effectively 'override' a default
DelegateAPI by registering with the same URL. However it must have
a different class name and the previous DelegateAPI must be removed from
ACTIVE_DELEGATE_APIS.

Examples of DelegateAPIs can be found in adjutant.api.v1.openstack

Minimally they can look like this::

    class NewCreateProject(BaseDelegateAPI):

        @utils.authenticated
        def post(self, request):
            self.task_manager.create_from_request('my_custom_task', request)

            return Response({'notes': ['task created']}, status=202)

Access can be restricted with the decorators mod_or_admin, project_admin and
admin decorators found in adjutant.api.utils. The request handlers are fairly
standard django view handlers and can execute any needed code. Additional
information for the task should be placed in request.data.


Building Tasks
==============

Tasks must be derived from adjutant.tasks.v1.base.BaseTask and can be
registered as such::

    from adjutant.tasks.v1.models import register_task_class

    register_task_class(MyPluginTask)

Examples of tasks can be found in `adjutant.tasks.v1`

Minimally task should define their required fields::

    class My(MyPluginTask):
        task_type = "my_custom_task"
        default_actions = [
            "MyCustomAction",
        ]
        duplicate_policy = "cancel" # default is cancel


Building Actions
================

Actions must be derived from adjutant.actions.v1.base.BaseAction and are
registered alongside their serializer::

  from adjutant.actions.v1.models import register_action_class

  register_action_class(MyCustomAction, MyCustomActionSerializer)

Serializers can inherit from either rest_framework.serializers.Serializer, or
the current serializers in adjutant.actions.v1.serializers.

Examples of actions can be found in `adjutant.actions.v1`

Minimally actions should define their required fields and implement 3
functions::

    class MyCustomAction(BaseAction):

        required = [
            'user_id',
            'value1',
        ]

        def _prepare(self):
            # Do some validation here
            pass

        def _approve(self):
            # Do some logic here
            self.action.task.cache['value'] = self.value1

        def _submit(self, data):
            # Do some logic here
            self.add_note("Submit action performed")

Information set in the action task cache is available in email templates under
task.cache.value, and the action data is available in action.ActionName.value.

If a token email is needed to be sent the action should also implement::

    def _get_email(self):
        return self.keystone_user.email

If an action does not require outside approval this function should be run at
the pre-approval stage::

    self.set_auto_approve(True)

If an action requires a token this should be set at the post approval stage::

    self.action.need_token = True
    self.set_token_fields(["confirm"])

All actions must be paired with a serializer to do basic data structure
checking, but should also check data validity during the action. Serializers
are django-rest-framework serializers, but there are also two base serializers
available in adjutant.actions.v1.serializers, BaseUserNameSerializer and
BaseUserIdSerializer.

All fields required for an action must be placed through the serializer
otherwise they will be inaccessible to the action.

Example::

    from adjutant.actions.v1.serializers import BaseUserIdSerializer
    from rest_framework import serializers

    class MyCustomActionSerializer(BaseUserIdSerializer):
        value_1 = serializers.CharField()

******************************
Building Notification Engines
******************************

Notification Engines can also be added through a plugin::

    from adjutant.notifcations.models import NotificationEngine
    from django.conf import settings

    class NewNotificationEngine(NotificationEngine):

        def _notify(self, task, notification):
            if self.conf.get('do_this_thing'):
              # do something with the task and notification


    settings.NOTIFICATION_ENGINES.update(
      {'NewNotificationEngine': NewNotificationEngine})

They should then be referred to in conf.yaml::

    TASK_SETTINGS:
        signup:
            notifications:
                NewNotificationEngine:
                    standard:
                        do_this_thing: True
                    error:
                        do_this_thing: False


*************************************************
Using the Identity Manager, and Openstack Clients
*************************************************

The Identity Manager is designed to replace access to the Keystone Client. It
can be imported from ``adjutant.actions.user_store.IdentityManager`` .
Functions for access to some of the other Openstack Clients are in
``adjutant.actions.openstack_clients``.

This will be expanded on in future, with the IdentityManager itself also
becoming pluggable.