django-docusign

django-docusign is a Django application for DocuSign‘s digital signature SAAS platform.

It uses pydocusign as Python client. It implements django-anysign API.

Project status

django-docusign is under active development. The project is not mature yet, but authors already use it! It means that, while API and implementation may change (improve!) a bit, authors do care of the changes.

Also, help is welcome! Feel free to report issues, request features or refactoring!

Contents

Install

django-docusign is open-source software, published under BSD license. See License for details.

If you want to install a development environment, you should go to Contributing documentation.

Prerequisites

  • Python [1] 2.7, 3.3 or 3.4. Other versions may work, but they are not part of the test suite at the moment.

As a library

In most cases, you will use django-docusign as a dependency of another project. In such a case, you should add django-docusign in your main project’s requirements. Typically in setup.py:

from setuptools import setup

setup(
    install_requires=[
        'django-docusign',
        #...
    ]
    # ...
)

Then when you install your main project with your favorite package manager (like pip [2]), django-docusign will automatically be installed.

Standalone

You can install django-docusign with your favorite Python package manager. As an example with pip [2]:

pip install django-docusign

Check

Check django-docusign has been installed:

python -c "import django_docusign;print(django_docusign.__version__)"

You should get django_docusign‘s version.

References

[1]https://www.python.org/
[2](1, 2) https://pypi.python.org/pypi/pip/

Configure

Here is the list of settings used by django-anysign.

INSTALLED_APPS

There is no need to register django-docusign application in your Django’s INSTALLED_APPS setting.

ANYSIGN

Since django-docusign depends on django-anysign [1], configure settings.ANYSIGN [2].

Example from the Demo project:

ANYSIGN = {
    'BACKENDS': {
        'docusign': 'django_docusign.backend.DocuSignBackend',
    },
    'SIGNATURE_TYPE_MODEL': 'django_docusign_demo.models.SignatureType',
    'SIGNATURE_MODEL': 'django_docusign_demo.models.Signature',
    'SIGNER_MODEL': 'django_docusign_demo.models.Signer',
}

DOCUSIGN_*

Settings prefixed with DOCUSIGN_ are used by DocuSignBackend as default values to setup pydocusign.DocuSignClient. Use them when you want to use some global configuration for your Django-powered project.

Note

If you need to use custom options depending on your requests (as an example if you use several DocuSign credentials depending on user accounts), then you can pass explicit arguments to DocuSignBackend.

Example from the Demo project:

DOCUSIGN_ROOT_URL = 'https://demo.docusign.net/restapi/v2'
DOCUSIGN_TIMEOUT = 10

Here are available settings:

  • settings.DOCUSIGN_ROOT_URL: root URL of DocuSign API.
  • settings.DOCUSIGN_USERNAME: API username.
  • settings.DOCUSIGN_PASSWORD: API password.
  • settings.DOCUSIGN_INTEGRATOR_KEY: API integrator key.
  • settings.DOCUSIGN_ACCOUNT_ID: API account ID.
  • settings.DOCUSIGN_APP_TOKEN: API AppToken.
  • settings.DOCUSIGN_TIMEOUT: Connection timeout.

Notes & references

[1]https://pypi.python.org/pypi/django-anysign
[2]https://django-anysign.readthedocs.org/en/latest/settings.html

Demo project

Demo folder in project’s repository [1] contains a Django project:

  • demo illustrates usage. Examples in documentation are imported from the demo.
  • demo contains tests.
  • demo can be used as a sandbox in order to try or develop the software.

Feel free to use the demo project as a sandbox. See Contributing for details about development environment setup.

Notes & references

[1]https://github.com/novafloss/django-docusign/tree/master/demo/

About django-docusign

This section is about the django-docusign project itself.

Vision

django-docusign helps you integrate and use Docusign [1] within a Django project.

References

[1]https://www.docusign.com/

License

Copyright (c) 2014, Benoît Bryon. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of django-docusign nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Authors & contributors

Maintainer: Benoît Bryon <benoit@marmelune.net>, as a member of the PeopleDoc [1] team: https://github.com/novafloss/

Developers: https://github.com/novafloss/django-docusign/graphs/contributors

Notes & references

[1]http://www.people-doc.com

Changelog

This document describes changes between each past release. For information about future releases, check milestones [1] and Vision.

0.12 (2015-09-10)
  • Support Django 1.7
  • Support Tox 2
0.11 (2015-03-16)

Refactoring related to pydocusign version 0.13.

  • Refactoring #37 - Project repository moved to novafloss organization (was novapost).
  • Refactoring #38 - Upgraded to pydocusign 0.13. Refactored handling of routingOrder and Envelope.post_recipient_view.
0.10 (2015-02-04)

Features around settings.

  • Feature #34 - DocuSignBackend uses settings.DOCUSIGN_* to instanciate DocuSign client. Available settings are DOCUSIGN_ROOT_URL, DOCUSIGN_USERNAME, DOCUSIGN_PASSWORD, DOCUSIGN_INTEGRATOR_KEY, DOCUSIGN_ACCOUNT_ID, DOCUSIGN_APP_TOKEN, DOCUSIGN_TIMEOUT.
  • Bug #30 - Handle DocuSign callbacks that have no “decline reason” attribute (was raising errors in such a situation).
0.8 (2014-11-28)

Introducing DocuSign templates.

  • Feature #28 - Introduced support for DocuSign templates to create envelopes. To run the tests, you’ll need a new PYDOCUSIGN_TEST_TEMPLATE_ID environment variable: DocuSign’s UUID of a template which has 2 roles.
0.7 (2014-10-22)

Bugfixes & refactoring, mostly around SignatureCallbackView.

  • Bug #20 - In SignatureCallbackView:
    • update_signature is not triggered if signature is not updated, when a signer, not the last, has just signed the envelope.
    • update_signer is triggered for every signer when signature and signers have “Sent” status (signature has just been created in embedded mode).
  • Features #16 and #20 - In demo application, SignatureCallbackView is tested using pydocusign‘s templates.
  • Bug #17 - In demo application, added tests around settings view... and fixed it, so that it works as expected.
  • Bug #18 - In demo application, replaced using iterator.next() instead of list(iterator)[0].
  • Refactoring #19 - Removed deprecaded SignatureCallbackView.clean_status. Use pydocusign.DocuSignCallbackParser.envelope_status instead.
0.6 (2014-10-10)

Custom email subject and blurb.

  • Feature #10 - DocuSignBackend.create_signature accepts subject and blurb arguments, in order to customize email subject and body for DocuSign messages and embedded signing page.
0.5 (2014-10-08)

Improvements around multiple signers.

  • Feature #13 - DocuSignCallbackView also handles recipient notifications.
  • Feature #11 - Improved ordering of signers, better management of DocuSign’s routingOrder.
  • Feature #12 - Demo project shows how to implement signature of multiple signers.
  • Bugfix #9 - Fixed default value of signer_return_url in DocuSignBackend.post_recipient_view(). Default value was not assigned if value was not passed as argument.
0.4 (2014-09-26)
  • Feature #7 - Introduced django_docusign.SignatureCallbackView, as a generic view to handle DocuSign’s notification callbacks. Simplified demo’s code.
0.3 (2014-09-18)

Updated demo to manage DocuSign API callbacks.

  • Feature #1 - Introduced support for DocuSign API callbacks (envelope updates). At the moment, the feature is mostly made of sample code in the demo project. It shows how django-docusign can be used to handle DocuSign’s API callbacks. The idea is to let users try the feature then, later, add most useful parts in django_docusign package.
0.2 (2014-09-16)

Introduced demo application (with tests).

  • Feature #4 - Introduced demo application: illustrate and test API usage.
  • Feature #3 - On signature creation, tabs can be computed by backend.
0.1 (2014-08-12)

Initial release.

  • Introduced django_docusign.backend.DocuSignBackend with “create signature” and “post recipient view” features.

Notes & references

[1]https://github.com/novafloss/django-docusign/milestones

Contributing

This document provides guidelines for people who want to contribute to the django-docusign project.

Create tickets

Please use django-docusign bugtracker [1] before starting some work:

  • check if the bug or feature request has already been filed. It may have been answered too!
  • else create a new ticket.
  • if you plan to contribute, tell us, so that we are given an opportunity to give feedback as soon as possible.
  • Then, in your commit messages, reference the ticket with some refs #TICKET-ID syntax.

Use topic branches

  • Work in branches.
  • Prefix your branch with the ticket ID corresponding to the issue. As an example, if you are working on ticket #23 which is about contribute documentation, name your branch like 23-contribute-doc.
  • If you work in a development branch and want to refresh it with changes from master, please rebase [2] or merge-based rebase [3], i.e. do not merge master.

Fork, clone

Clone django-docusign repository (adapt to use your own fork):

git clone git@github.com:novapost/django-docusign.git
cd django-docusign/

Usual actions

The Makefile is the reference card for usual actions in development environment:

  • Install development toolkit with pip [4]: make develop.
  • Run tests with tox [5]: make test.
  • Build documentation: make documentation. It builds Sphinx [6] documentation in var/docs/html/index.html.
  • Release django-docusign project with zest.releaser [7]: make release.
  • Cleanup local repository: make clean, make distclean and make maintainer-clean.

See also make help.

Use private credentials to run the tests

The test suite contains several integration tests, so it requires valid DocuSign account credentials. The test suite reads environment variables to get the setup. Here is an example to run the tests:

DOCUSIGN_ROOT_URL='https://demo.docusign.net/restapi/v2' \
DOCUSIGN_USERNAME='your-username' \
DOCUSIGN_PASSWORD='your-password' \
DOCUSIGN_INTEGRATOR_KEY='your-integrator-key' \
DOCUSIGN_TEST_TEMPLATE_ID='UUID-of-your-docusign-template' \
DOCUSIGN_TEST_SIGNER_RETURN_URL='http://example.com/signer-return/' \
DOCUSIGN_TEST_CALLBACK_URL='http://example.com/callback/' \
make test

Notes & references

[1]https://github.com/novafloss/django-docusign/issues
[2]http://git-scm.com/book/en/Git-Branching-Rebasing
[3]http://tech.novapost.fr/psycho-rebasing-en.html
[4]https://pypi.python.org/pypi/pip/
[5]https://pypi.python.org/pypi/tox/
[6]https://pypi.python.org/pypi/Sphinx/
[7]https://pypi.python.org/pypi/zest.releaser/

Indices and tables