Custom Permission Access Module For Multi-Level Organization

2017-09-22 07:03
Written by

When implementing the constituent relationship management solution for one of the biggest political organizations, we had to find a way to tailor the CiviCRM security model to the needs of a country-wide hierarchically structured organization.

Any multi-unit public organization with geographically distributed branches is set up with several levels of management, hierarchically structured units and roles. In our case there were four levels of hierarchy - the central office located in the capital, which manages the entire organization in 25 regions further divided into 12 to 30 districts each and finally the lowest level branches in every village or small town, as shown in pict 1. Such structure presupposes allocation of responsibilities and access hierarchically within a district, region or entire country.

Pict. 1

CiviCRM allows building the multi-level organization structure using Relationships. Also CiviCRM by default provides very flexible role based access control which could be implemented through ACLs while permission control for multi-level orgstructure is hardly supported. An access level to CRM data differs by roles not by units. Yet NGOs with geographically distributed branches allocate functions and responsibilities by units. Branch, district and regional offices exercise different level of control over an organization and require either extended or restricted access to data.

Agiliway team buckled down to work, determined to implement orgstructure based access control.

Before long we’ve built Custom Security Module to add necessary functionality. Based on the Related Permission Extension that had been heavily modified to work seamlessly across multi-level hierarchy, our Custom Security Module ensures multi-level permission control for our client. Each staff member is now given as much access to CRM data as their functions within a certain unit require.

The central office of the political organization coordinates activities of all units and requires an unrestricted access for managerial positions, while an extended access for workplace officers (pict. 2).

Pict. 2

The district or regional office manager will have access to the information for their branch as well as for all subordinate branches that report to them. So the access narrows down for branch offices and further down for every hierarchically lower unit. See pict 3.

Pict. 3

And regular office staff will now see CRM data only within their organization whatever level it is. See pict 4 below.

Pict. 4

As illustrated above, members of the district-level organization view each other's general information but do not have permissions to access the information of other members of the central office (above) or of the subordinate towns/villages (below).

The head of the regional-level organization can manage the information of all members of his regional organization and below including all subordinate districts and towns, but he does not see the information of the members of the central office (above) or other regions.

The solution also supports cases when a user is a member of two organizations - e.g. manager in one organization and a regular member in another one. Then, permissions are combined.

When implemented, our Custom Security Module enables CiviCRM users to:

  • setup Roles (admin, manager, regular member) for each user which define access permissions to different areas of information
  • allow access only to a specified organization(branch/unit) the user belongs to. It’s defined through CiviCRM Relationship between a user and corresponding organization
  • extend access to all subordinate organizations for selected Roles (e.g. Administrator or Manager). The relationship between organizations is defined through CiviCRM Relationship
  • grant/recall access only to a specific organisation. E.g. when a branch is reassigned from one District to another (this could be done updating CiviCRM Relationship record) then a manager of the first district loses access to the branch data while the second district manager is granted it automatically

In our project we had 4-level organization and 3 main roles as shown in the pictures above. Yet the security solution is built to support any number of levels in the organization structure.

Filed under


Sounds like a great feature set.  Is this implemented as a CiviCRM extension, or as a Drupal module, or?  Are the bits available as of yet?

This is CiviCRM extension.

Yes, we plan to make it publicly available. Still need to clean-up code and remove some client specific info. Hope we will do this in 1-1.5 month after we complete the project and have spare resources. 

BTW, we are going participating UK CiviCon this week. If you are there then we can meet and I will be glad to present how this works. Please feel free to write me directly


We would be very much interested in a similar way to organizer access levels. Are there any technical details available online? 

Hi Birgit,


We plan to make this CiviCRM extension public but we still need to make some code cleanup. I think it will take 1-1.5 month due to the current load. 

Also, I will be talking about this feature at CiviCon UK on Friday. We can meet there if you are attending. Otherwise, I can give you a call next week to present details. Please write me at to schedule time.

We haven’t published this functionality just because that the first “custom-permission-access module” we developed for Ukrainian political party (according to their structure/roles/permissions), and later customize a lot other “custom-permission-access modules”  for clients according to their requirements. As the base, we used " Relationship Permissions AS ACLS" extension 
So, from our experience, every client has different requirements/structure, and the best of all will be customize it according to Organization needs/structure/roles e.t.c.