Backends

django-anysign‘s signature backend encapsulates signature workflow and integration with vendor specific implementation.

Note

The backend API is quite experimental. This document deals with both vision (concepts) and current implementation (which may improve).

Scope of a backend

A signature backend is typically known by models and views. They use the backend to perform vendor-specific operations. The backend contains vendor-specific implementation that has to be shared with several consumers such as models and views.

A signature backend also typically knowns the workflows. So it should be helpful for URL resolution.

django-anysign’s SignatureBackend

Here is the current implementation of base backend.

class django_anysign.backend.SignatureBackend(name, code, url_namespace='anysign', **kwargs)

Bases: object

Encapsulate signature workflow and integration with vendor backend.

Here is a typical workflow:

  • SignatureType instance is created. It encapsulates the backend type and its configuration.
  • A Signature instance is created. The signature instance has a signature type attribute, hence a backend.
  • Signers are notified, by email, text or whatever. They get an hyperlink to the “signer view”. The URL may vary depending on the signature backend.
  • A signer goes to the backend’s “signer view” entry point: typically a view that integrates backend specific form to sign a document.
  • Most backends have a “notification view”, for the third-party service to signal updates.
  • Most backends have a “signer return view”, where the signer is redirected when he ends the signature process (whatever signature status).
  • The backend’s specific workflow can be made of several views. At the beginning, there is a Signature instance which carries data (typically a document). At the end, Signature is done.
name = None

Human-readable name.

code = None

Machine-readable name. Should be lowercase alphanumeric only, i.e. PEP-8 compliant.

url_namespace = None

Namespace for URL resolution.

send_signature(signature)

Initiate the signature process.

At this state, the signature object has been configured.

Typical implementation consists in sending signer URL to first signer.

Raise NotImplementedError if the backend does not support such a feature.

get_signer_url(signer)

Return URL where signer signs document.

Raise NotImplementedError in case the backend does not support “signer view” feature.

Default implementation reverses get_signer_url_name() with signer.pk as argument.

get_signer_url_name()

Return URL name where signer signs document.

Raise NotImplementedError in case the backend does not support “signer view” feature.

Default implementation returns anysign:signer.

get_signer_return_url(signer)

Return absolute URL where signer is redirected after signing.

The URL must be absolute because it is typically used by external signature service: the signer uses external web UI to sign the document(s) and then the signature service redirects the signer to (this) Django website.

Raise NotImplementedError in case the backend does not support “signer return view” feature.

Default implementation reverses get_signer_return_url_name() with signer.pk as argument.

get_signer_return_url_name()

Return URL name where signer is redirected once document has been signed.

Raise NotImplementedError in case the backend does not support “signer return view” feature.

Default implementation returns anysign:signer_return.

get_signature_callback_url(signature)

Return URL where backend can post signature notifications.

Raise NotImplementedError in case the backend does not support “signature callback url” feature.

Default implementation reverses get_signature_callback_url_name() with signature.pk as argument.

get_signature_callback_url_name()

Return URL name where backend can post signature notifications.

Raise NotImplementedError in case the backend does not support “signer return view” feature.

Default implementation returns anysign:signature_callback.

create_signature(signature)

Register signature in backend, return updated object.

This method is typically called by views which create Signature instances.

If backend stores a signature object, then implementation should update signature_backend_id.

Base implementation does nothing: override this method in backends.

django-dummysign’s SignatureBackend

Here is the demo signature backend implementation provided by django-dummysign.

import logging

from django_anysign import api as django_anysign


logger = logging.getLogger(__name__)


class DummySignBackend(django_anysign.SignatureBackend):
    def __init__(self):
        super(DummySignBackend, self).__init__(
            name='DummySign',
            code='dummysign',
        )

    def create_signature(self, signature):
        """Register ``signature`` in backend, return updated object.

        As a dummy backend: just emit a log.

        """
        signature = super(DummySignBackend, self).create_signature(signature)
        logger.debug('[django_dummysign] Signature created in backend')
        return signature