Getting started#

Django-organizations allows you to add multi-user accounts to your application and tie permissions, events, and other data to organization level accounts.

The core of the application consists of three models:

  • An organization model; the group object. This is what you would associate your own app’s functionality with, e.g. subscriptions, repositories, projects, etc.

  • An organization user; a through model relating your users to your organization. It provides a convenient link for organization ownership (below) and also a way of storing organization/user specific information.

  • An organization owner. This model links to an organization user who has rights over the life and death of the organization.

You can allow users to invite other users to their organizations and register with organizations as well. This functionality is provided through “backend” interfaces so that you can customize this code or use arbitrary user registration systems.

Installation#

First add the application to your Python path. The easiest way is to use pip:

pip install django-organizations

Quickstart Configuration#

Note

If however you want to use single-table customized organization models and/or custom organization user models, it may be best to treat Django organizations as a library and not install it in your Django project. See the Advanced customization using abstract models section.

Ensure that you have a user system in place to connect to your organizations.

To install the default models add organizations to INSTALLED_APPS in your settings file.:

INSTALLED_APPS = (
    'django.contrib.auth',
    'organizations',
)

This should work for the majority of cases, from either simple, out-of-the-box installations to custom organization models.

URLs#

If you plan on using the default URLs, hook the application URLs into your main application URL configuration in urls.py. If you plan on using the invitation/registration system, set your backend URLs, too:

from organizations.backends import invitation_backend

urlpatterns = [
    url(r'^accounts/', include('organizations.urls')),
    url(r'^invitations/', include(invitation_backend().get_urls())),
]

Registration & invitation#

You can specify a different invitation backend in your project settings, and the invitation_backend function will provide the URLs defined by that backend. You can do the same with the registration backend:

INVITATION_BACKEND = 'myapp.backends.MyInvitationBackend'
REGISTRATION_BACKEND = 'myapp.backends.MyRegistrationBackend'

Auto slug field#

Django-Organizations relies on django-extensions for the base AutoSlugField. While django-extensions is great, this does require that every project install django-extensions for this one small feature.

If you decide to use the default django-organization models by adding organizations to your INSTALLED_APPS, you can choose a different AutoSlugField. Just specify the full dotted path like so:

ORGS_SLUGFIELD = 'django_extensions.db.fields.AutoSlugField'

While you can specify the source of this class, its interfaces must be consistent, including keyword arguments. Otherwise you will end up generating extraneous and possibly conflicting migrations in your own app. The SlugField must accept the populate_from keyword argument.

Users and multi-account membership#

The key to these relationships is that while an OrganizationUser is associated with one and only one Organization, a User can be associated with multiple OrganizationUsers and hence multiple Organizations.

Note

This means that the OrganizationUser class cannot be used as a UserProfile as that requires a one-to-one relationship with the User class. User profile information is better provided by a profile specific model.

In your project you can associate accounts with things like subscriptions, documents, and other shared resources, all of which the account users can then access.

Views and Mixins#

Hooking the django-organizations URLs into your project provides a default set of views for accessing and updating organizations and organization membership.

The included class based views are based on a set of mixins that allow the views to limit access by a user’s relationship to an organization and that query the appropriate organization or user based on URL keywords.

Implementing in your own project#

While django-organizations has some basic usability ‘out-of-the-box’, it’s designed to be used as a foundation for project specific functionality. The view mixins should provide base functionality from which to work for most projects, and the Cooking with Django Organizations section provides detailed examples for various integration scenarios.