Working with Organizations and Locations

Note: Since Liferay v4.4 besides what is explained in this article, users can belong to several organizations and with a different 'organization' role for each if desired.

Introduction #

Organizations and Locations are the mechanism provided by Liferay to organize the users of the portal following a hierarchical structure. This article explains how to use them to map the structure of companies or institutions regardless of their complexity.

Organizations and Locations were introduced in Liferay 4.0, but it wasn't until Liferay 4.3.1 when thanks to a contribution they achieved the level of flexibility that they have now. Most of what is described in this article refers to the features available since that version.

First let's start with some definitions.

Organizations #

Represent the logical structure of the company or institution where the portal is being used. It has a hierarchical structure with as many levels as desired.

Each user can be assigned to at most one organization inheriting the permissions and associations of that organization. The user will also inherit all the permissions and associations of the parents of that organization that have been marked as recursable.

The name organization was chosen because it's agnostic and matches well with most real world uses. It can be used for departments, groups, divisions, partner companies, providers, etc.

Locations #

Represent physical locations where the company or institution users may work. Each location belongs to an organization.

Each user can be assigned to at most one location. That location must belong to the organization to which the user is assigned or to one of the recursable parents of that organization

Note, that for many situations organizations will be enough to match the desired structure. Only very complex structures will require the additional use of a location. Starting with version 4.3.2 (not yet released at the time of writing) it's possible to disable locations from the UI for those cases when they are not needed. That way you can benefit from a simpler UI if that's your case (see for details).

Websites for Organizations and Locations #

Starting with Liferay 4.3.1 every organization and every location of the system can have their own set of public and private pages, just as it happens to communities. The portal administrator can configure those pages by using the Enterprise Admin portlet.

Users that belong to an organization or location will be able to navigate to them through the 'My Places' dropdown menu. Note that if a user belongs to an organization that has parent organizations, she'll be able to navigate and view the pages of each of those parent organizations.

Managing organizations and locations #

Organizations and locations are managed from the Enterprise Admin portlet. The 'Organizations' tab allows browsing the Organization hierarchy, including finding which locations are assigned to each organization.

At the right side of each organization there is a set of icons that allows the administrator to:

  • Edit the details
  • Manage it's permissions. To determine who can manage this organization as well as its locations and users.
  • Configure pages
  • Add a user that belongs to that organization
  • View the users of that organization
  • View the suborganizations
  • Add an inner location
  • View the list of inner locations
  • Delete the organization. You will not be allowed if it contains users, locations or suborganizations

The 'Locations' tab shows a list of all the existing locations regardless of their position within the organization hierarchy.

At the right side of each organization there is a set of icons that allows the administrator to:

  • Edit the details
  • Manage it's permissions. To determine who can manage this organization as well as its locations and users.
  • Configure pages
  • Add a user that belongs to the location (and to the organization to which it belongs)
  • View the users of that location
  • Delete the location. You will not be allowed if it contains users.

Learning by example #

The purpose of this section is to show how to match real world structures of companies and other institutions with Liferay's organizations and locations. We'll start with a structure of medium complexity that can be matched using only organizations. Later we'll add even more complexity to show how locations can be used. Finally, a real world, very complex structure will be introduced.

A company structure: an example of hierarchical organizations #

Let's start with an example of an structure of a real company. Part of the actual structure has been removed for simplicity, but what is left reflects all the possible scenarios.

Hierarchy of organizations #

To match this structure within Liferay we create an organization hierarchy that maps directly to the previous diagram:

  • Company ABC
    • Board: Bob
      • Sales: Anna
      • Engineering
        • Frontend: John
        • Backend: Barbara
      • Support

Next to the Organization name are the names of the users that would be created within it.

Inheritance of permissions #

Now we can use Liferay's permission system to assign permissions to users based on the organization to which they belong. That is, the Liferay permission system allows the portal administrator to assign a certain permission or role to ALL the members of an organization at once by assigning that permission or role to the organization itself. But not only to the users that currently belong to the organization, any new user that is later assigned to that organization will also get that permission or role.

This inheritance of permissions from the user's organization works hierarchically. For example, looking at the diagram above, if we want all of the members of the Engineering department have the custom role 'Engineer' I just have to assign it to the Engineering organization. John and Barbara don't belong to that organization directly but to sub-organizations (Frontend and Backend), but those sub-organizations also inherit the permissions from the parent.

That recursability of permissions from one organization to its children organization is most often what is desired, but not always. Imagine we want the members of the Directors Board, such as Bob, to be able to access a page called 'Confidential' in the guest community. We can assign that permission to the organization called 'Board', but then, every user would inherit that permission, because 'Board' is a parent of all other permissions.

To support this situations, each organization has an attribute named 'Recursable permissions' that allows the administrator to decide if the permissions assigned to that organization will be inherited by suborganizations or not. In our example we would set that attribute to false in the 'Board' organization to achieve our purposes. So our hierarchy of organizations would be as shown next:

  • Company ABC (Recursable permissions: Yes)
    • Board (Recursable permissions: NO)
      • Sales (Recursable permissions: Yes)
      • Engineering (Recursable permissions: Yes)
        • Frontend (Recursable permissions: Yes)
        • Backend (Recursable permissions: Yes)
      • Support (Recursable permissions: Yes)

Adding distributed departments: an example of locations #

Let's imagine that time passes and Company ABC grows. While it previously had only one office in Paris, now opens two more in Dalian and New York. The company structure does not change, but now there are Sales people working in New York and Paris and Engineering people working in Dalian and Paris.

Furthermore, they want their employees to have special permissions based on the place where they work, additionally to those based in what organizations they belong to (as seen in the previous section).

Locations within the hierarchy of organizations #

Liferay's locations can be used to achieve the needs of this scenario. We'll create the following locations within the existing organizations:

  • Company ABC
    • Location: Paris
    • Board
      • Sales
        • Location: New York
      • Engineering
        • Location: Dalian
        • Frontend
        • Backend
      • Support

Some things to note in this hierarchy is that we've decided to put the Location Paris as a direct child of the 'Company ABC' organization, while the locations 'New York' and 'Dalian' are children of Sales and Engineering respectively. Once these locations have been created they can be assigned to the actual users. The pop-up to assign a location to a user will only show those locations that are children either directly from its organization or of one of its parent organizations. For each of the users in our example the possible organizations would be:

  • Anna (Sales): New York or Paris
  • John (Fronend, Engineering): Paris or Dalian
  • Barbara (Backend, Engineering): Paris or Dalian
  • Bob (Board): Paris

Once this hierarchy has been set up we can use the Enterprise Admin portlet to assign each user to their respective location. We can later assign permissions for portal resources to those locations to control what their users can do.

What is important to note here is that we've been able to separate those permissions that the users get due to the (logical) organization to which they belong, such as Sales or Engineering to those that they get due to the location in which they work. That way if a user moves for example from one Location to another, it's very easy to change the location to which she is assigned to have those permissions modified properly, but keeping the permissions from the organization to which she belongs.

An alternative hierarchy #

Another hierarchy that also would have met the above requirements would have been to associate all locations to the top level 'Company ABC' organization.

In some situations people may find that hierarchy easier to understand and work with. It's only potential drawback is that the pop-up shown to assign a user to a location will show all locations, even those that may make no sense in the real world.

A very complex scenario #

This section contains an example of a very complex scenario, extracted out from a real use of Liferay (In fact this is from the project for which hierarchical organizations was implemented).

We'll just show a picture describing the structure, and will leave as an example for the reader to find out how to match it using organizations and locations.

Note: The picture uses the term inheritable to refer to organizations with recursable permissions

Configuration options #

There are several configuration options available in the portal(-ext).properties file. Here is a description of them:

  • Set the following to true if users must belong to a parent organization.
  • Set the following to true if organizations must have an associated country.
  • Set the following to true if users must belong to a location. If location is required, then a parent organization is also required. (Since Liferay v4.3.2)
  • Set the following to false to disable location management from the portal. This setting simplifies the UI for cases in which locations are not necessary. (Since Liferay v4.3.2)

Frequent questions #

Deciding whether to use communities or organizations #

Both solutions are good for many situations and often there are little differences. Here are some benefits for each of the approaches.

Benefits of using Organizations

  • Organizations can be structured in a hierarchical manner
  • Organizations are managed by the portal administrator thus are better to match existing external structures that change less often

Benefits of using communities

  • It's possible to delegate the permission of creating new communities, so they are better to match dynamic structures and groups that change very frequently
  • Community roles allow easier delegation of tasks within a community
  • Users can belong to many communities

How to delegate the administration of an organization to a user #

Unfortunately, that's not possible right now. Only the portal administrator can administer the organizations

Is it possible to associate users to more than one organization #

No, it's not possible right now. Although it's something that is being considered for future versions

Why have locations at all when they're really just without children? #

There are some circumstances in which you may need the extra flexibility provided by locations.

For example, a user may belong to the organization "Engineering" and inherit permissions from it. But also belong to the Location "Paris" and also (and independently) inherit its permissions. If the user moves to location "Los Angeles", he would loose the permissions from "Paris" but would keep those from "Engineering".That would not be possible without locations.

Related information #

  • Project proposal that finished with the implementation of what was described in this article in Liferay 4.3.1: Hierarchical Organizations
0 Attachments
Average (4 Votes)
The average rating is 5.0 stars out of 5.