.. _custom_post_processor:

.. role:: bash(code)
  :language: bash

.. role:: python(code)
  :language: python

.. role:: yaml(code)
  :language: yaml

Developing a custom postprocessor (nonpersistent backend)
=========================================================

Postprocessors in PyTerraBackTYL allow you to perform additional actions based on lock and state information from Terraform. An example of this is the SlackNotifyPostProcessor_ which pushes notications into a Slack chatroom.

.. _SlackNotifyPostProcessor: https://github.com/dev-dull/PyTerraBackTyl/blob/master/backends/slack_notify_post_processor.py

.. note::

  All exceptions generated by postprocessors are logged, but ignored as they cannot be allowed to interfere with the functionality of the persistent backend. For debugging purposes, the json data from :bash:`/state` endpoint includes a count of the number of errors logged for the postprocessor since startup, as well as the most recently logged error (useful for searching the logs later).

Import :python:`TYLNonpersistent` and define your subclass:

.. code:: python

  from abc_tylstore import TYLNonpersistent
  class MyNonpersistentBackend(TYLNonpersistent):
      def __init__(self, environment, constants, **kwargs):
      .
      .
      .

Implement the following functions in your class:

- :python:`__init__(self, environment, constants, **kwargs):`
    - :python:`environment` every environment will get a separate instance of your class and as a result, this value should be treated as a constant.
    - :python:`constants` a python class containing constant values. These values are partly populated by :bash:`config.yaml` as key:value pairs. For example, if you set :yaml:`MY_BACKEND_FOO: 'Hello, World!'` in :bash:`config.yaml`, you can access the string value with `constants.MY_BACKEND_FOO`. This allows you to configure your postprocessor module without the need of a separate configuration file.
    - :python:`**kwargs` It is recommended to add this to help ensure forward compatibility of your module with future versions of PyTerraBackTYL.
- :python:`def on_locked(self, state_obj, **kwargs):`
    - :python:`state_obj` Unpacked JSON (:python:`dict`) with the specifics on who is putting a lock on the environment.
    - :python:`**kwargs` includes :python:`raw` which contains the original JSON string (:python:`str`) value.
- :python:`def on_unlocked(self, state_obj, **kwargs):`
    - :python:`state_obj` Unpacked JSON (:python:`dict`) with the specifics on who is unlocking the environment.
    - :python:`**kwargs` includes :python:`raw` which contains the original JSON string (:python:`str`) value.
- :python:`def process_tfstate(self, tfstate_obj, **kwargs):`
    - :python:`tfstate_obj` Unpacked JSON (:python:`dict`) which specifies the current terraform state (:bash:`terraform.tfstate`)
    - :python:`**kwargs` includes :python:`raw` which contains the original JSON string (:python:`str`) value.
- :python:`def post_processor_status(self):` *OPTIONAL*
    - **RETURNS**: A JSON compatible object containing health and status information about the postprocessor.