Organizations & Teams

Overview

Organizations are a core piece of functionality for many applications these days and Jumpstart Pro comes preconfigured with them so you don't have to do any of the heavy lifting. The name Organization is a generic term but can be thought of as a vehicle for creating teams or organizations as well as personal organizations.

The Organization model is the mechanism that allows resources to be scoped to an organization of one user or a varying number of users based on the type of organization. This way the resource(s) will be scoped to each customer of your SaaS/application.

By default when a new user signs up they will have an organization created for them that does not allow them to invite anyone else to it. This is known as a personal (solo) organization in Jumpstart Pro. After this initial organization is created the user can create other organizations which will by default allow them to invite other users to the organization. This is what many consider to be a team organization. If you always want the organizations that are created when a new user signs up to be team organizations, then you can disable the personal organization creation option via the configuration wizard.

GitHub is an example of a similar flow that has both personal (solo) and team organizations. Many users of GitHub start off with a personal (solo) organization and then later add new team organization (GitHub calls these organization organizations) so they can add users and collaborate within that team organization.

Continuing with the GitHub example when you first create your personal organization, all of your repositories are only available to you. If you create a team organization, you can then invite others to the team and share access to repositories to all members of that team. This type of team organization is the organization type that will be created every time an existing user creates a new organization after the initial personal organization in your Jumpstart Pro application out-of-the-box.

If you decide to disable the creation of personal (solo) organizations, then the default behavior is to create a team organization for users upon sign up for your Jumpstart Pro application. If the initial team organization has only one user it is similar to a personal organization, but they can invite users later if desired or necessary. If so, this should be conveyed to the end user in the UI.

Personal organizations can be re-enabled later if you change your mind, however, any previously existing users will not have personal organizations and you will need to create them for each existing user manually. Additionally, if you don't want to use the organizations functionality, you can simply remove links to the organizations, however, we encourage you to keep the organizations functionality around as it allows you flexibility in the future should you choose to implement organizations later in the development of your application.

There is a configuration option (shown in the screenshot below) that can be found at /jumpstart if you have the server running. In the first section labeled Organizations, there is a set of radio buttons for "Personal and Team Organizations" or "Just Team Organizations". If the "Personal and Team Organizations" option is selected, then every new user that signs up for your application will be given a personal organization by default.

NOTE: The default personal organization is created via an after_create callback that comes from the UserOrganizations concern which is included in the User class.

Working with Personal (Solo) and Team Organizations

When creating new resources that should be scoped to either type of organization, make sure to add organization:references when generating your models to set up the foreign keys. For example:

rails generate Post title:string body:text organization:references

You can then scope the queries in your controllers to the current_organization so the resources are shared between users in the associated organization.

class PostsController < ApplicationController
  def index
    @posts = current_organization.posts
  end
end

Using current_organization in this way allows the code in Jumpstart Pro to be simplified by functioning the same regardless of whether the organization in question is a personal or team organization. This is why Jumpstart Pro uses current_organization for a personal organization with a single user instead of current_user. You do still have access to current_user in other cases if needed.

Organization Association

Users in Jumpstart Pro can have many organizations, some of which they may be the owner of and others of which they may be members. You can query for all of a given users organizations via:

user.organizations
#=> [#<Organization:0x0000000108f31728>, #<Organization:0x00000001098735c0>]

Personal organizations on the other hand, have the relationship setup as a has_one association and can be accessed via:

user.personal_organization
#=> #<Organization:0x000000010935fca0>

Creating Organizations

If you ever need to create an organization outside of the default Jumpstart Pro UI (for example in your Rails console for development or production), you can do so with the following lines of code (adjust argument values as needed):

user = User.first
organization = user.organizations.new(owner: user, name: user.name)
organization.organization_users.new(user: user, admin: true)
organization.save

Checking The Type Of Organization

Building off of the previous code sample, if you need to check an organization type to find out if it is a personal (solo) organization or not, you can do so the following way:

organization.personal?
#=> false

To check if an organization is a team organization, you can do so the following way:

organization.team?
#=> true

Additional Organizations

After the initial organization is created, all additional organizations created will be team organizations. These new team organizations allow the user to invite other users to join them.

Organization Switching

Once created, users can switch which organization they're viewing from the dropdown in the navbar where their avatar is displayed as seen here:

Any new organizations that are created by the user will be displayed in the dropdown as well by default.