Setting Up Organization Levels & Structure
The sections below walk through how to configure and use the Organizations Feature in CommCare. In order to use this feature, you must have Case Sharing enabled in your app, which you can enable one the Advanced Settings page of your application settings.
More information about case sharing can be found here: Case Sharing
Step 1: Set Your Organization Levels
To use Organizations, you must first define your Organization Levels. These levels represent the different hierarchical levels within a project, such as State → District → Clinic → CHW (Health Worker). They establish a structured hierarchy that determines how cases and users are organized. Oftentimes programs want users sitting in higher in the organizational hierarchy to be able to see all the cases in their catchment area: this can easily be configured within the organizational structure, by giving upper level organizations access to view all data at locations below them.
To set up Organization Levels, you need to follow the steps given below or as shown in the gif.
Go to the Users tab and choose Organization Levels from the menu.
Specify the following information for each organization level:
Organization Level: The name of the organization level (ex. District or Clinic).
Parent Level: The parent level for the organization level, in other words, the level above this level (ex. the parent level of the Clinic is District). For the top level of your organization hierarchy, set the Parent Type to -top level-.
Owns Cases: This controls whether locations of this type are able to have cases assigned to them. When a location owns cases, that means that any users assigned to the location see all of those cases. If there are multiple workers assigned to a single location at this level they will share cases if this box is checked.
Oftentimes it is only the lower levels of an organizational structure that own cases, since mobile workers are typically only assigned to the bottom few levels of a structure. That means that you will often see hierarchies where some levels have the “owns cases” boxes ticked, and For example, you may have Health Workers (as the lowest level in your hierarchy) who own cases, but districts (an upper level in the hierarchy) do not. Depending on your use case, you might want to see https://dimagi.atlassian.net/wiki/x/XTPKfw for more information.View Child Data: This setting controls whether a location at that level can view cases assigned to child (lower in the hierarchy than them) locations. For example, you may want to have users at Clinics locations view cases owned by each child Health Worker locations. Tip: the vast majority of organizational structures have “view child data” turned on for their locations in the upper portions of their hierarchy.
Step 2: Create Your Organizations
Once you have defined the levels of your hierarchy, it is time to go in and create the specific locations. For example, in the above section we created a hierarchy with district, clinic, and CHW (health worker) levels. Now it is time to actually set up the specific districts, clinics, and CHWs that are involved in the project. For example, imagine that our project is taking place in 3 districts covering 20 clinics and 100 health workers. That means we need to create 3 district locations, 20 clinics underneath that, and 100 health workers underneath those. Each need to be nested within the correct part of the hierarchy.
To begin creating locations:
Navigate to the Organization Structure: Click on the Users tab and choose Organization Structure.
Create First Location: Click “New Location at Top Level.” This will prompt you to add your first location, for the highest level in your hierarchy. The only field you have to fill is the “Name” and then press “create.” CommCare will take you to that location’s page, where you’ll see that it has automatically filled in other fields, like the site code and organization type.
Create More Locations: Once you've created your first location, you can click the purple “New Child Location” button to make a location that is nested underneath this location, OR go back to the Locations page to create more locations.
Use the Location Tree to Find and Create Locations: When viewing the location tree, you can use the + button to expand a location and view its child locations. Once expanded, there will also be a button to create more child locations for that location, as shown in the gif below.
Note: you can also create your locations in bulk, by uploading them in an Excel spreadsheet. See section below for instructions on how to do this.
Step 3: Manage your Organization Structure
Once you have set up the Organization Structure, you can view the location tree and use the + button to expand a location and see its child locations. Once expanded, you will also find an option to create additional child locations. Additionally, you can edit a location using the Edit button next to it in the tree.
When editing a location, you can set the following information:
Name and Organization Level
Coordinates: This is useful for map-based reports if using Organizations in any location based project
Parent: Change or move the location to a different parent location. Currently, only locations with no children can be moved.
Site Code: A unique identifier for the location that can be used when assigning cases to the location via Excel or assigning lookup table rows to the location. Note: CommCare creates this automatically this when a new location is created.
Bulk Upload your Organization Structure
If your Organization Structure is large, adding locations one by one can be time-consuming. To simplify this process, CommCare allows you to bulk upload/import locations using an Excel file. This method helps you efficiently create, update, and manage multiple locations at once. In this guide, you'll learn how to prepare your import file, upload it to CommCare HQ, and troubleshoot common issues for a smooth import experience.
Select Bulk Upload Option: Go to the Organization Structure page (Users tab → Organization Structure) and select Bulk Upload. (Note that Bulk Upload will only work if you have already created organization levels)
Download the Excel file: Download the Bulk Upload Excel file. When you open it, you will see a tab for each organization level. You can add (or edit rows) in this Excel document to create new locations. For each location you're required to provide the following information:
Name: The readable name of the location.
Site Code: This is a unique identifier for the location and cannot contain any spaces or special characters.
Parent Site Code: This is the site code of the parent of this location. It is important that this parent site code is correct so that the location get nested in the right branch of the organizational hierarchy. If the location doesn't have a parent, leave this column blank.
Latitude and Longitude: (Optional) columns to set the coordinates of the location.
Once you've created or updated your Excel file, upload the Excel file using the same Bulk Upload page.
Note: You cannot move locations using the bulk upload (changing the parent site code for an existing location will result in an error).
Examples of Organization Structures
Example 1: Agricultural Extension Agents
Background
In this project, the primary users are Agricultural Extension Agents who were using an application to monitor farms.
Here is the government/administrative hierarchy where they were working:
Province
District
Administrative Post
The people involved in the project were in the following hierarchy:
Worker Type | Notes | Coverage |
|---|---|---|
Provincial Managers (PM) | Use a separate PM application in which they should be able to see cases created by any user in the entire province | Each PM is responsible for all cases/data collected by all of the district supervisors and extension agents in their province. |
District Supervisors (DS) | Also work as Extension Agents, but should be able to see and update cases of other Extension Agents in their district | Each supervisor is responsible for exactly one District, which includes 3-5 Administrative Posts |
Extension Agents (EA) | Collects data using the Extension Agent app | Each extension agent is responsible for one or more Administrative Posts |
Location Design
Notes on each level:
Administrative Post - Cases are actually owned by the Administrative Post, so when a mobile worker creates a case it is assigned to a Post. (NOTE: This means if you had multiple workers assigned to one location at this level that they would see each other cases).
Extension Agent - a level was created for the Extension Agents; this is the level to which Mobile Workers who are Extension Agents are assigned. This may seem a bit strange because you have to create both a mobile worker account as well as a location, but there advantages to this, as described below.
District - this is the level to which District Supervisors are assigned; this allows them to view cases created by any Extension Agents in their district and to create cases for any administrative post in their district.
Province - the provincial manager can see all cases below. Mobile workers at the PM level are assigned to locations at this level.
Other notes:
This app used the location hierarchy as a Lookup Table as described in Assigning Cases to one of Multiple Groups . Imagine you are an Extension Agent assigned to the Extension Agent level, which has three Administrative Posts under it. When create a case you would see a lookup table question which shows a list of the three Administrative Posts assigned to you. When you choose one and then submit the form that new case is assigned to the post you selected. It is also not necessary to maintain a separate lookup table
The application also captures the names of the locations above it in the hierarchy.
It is very easy to reassign administrative posts; you can just move the location to a different district in the hierarchy, and once the users sync their data the transfer will be complete
One drawback of this approach is that one person can only be assigned to one district; so if there were workers that covered a subset of districts that would need to be another level in the hierarchy
Step 4: Assign Mobile Workers to Locations
Once you have created your organizational levels, and added all of the locations to your organizational structure, the last step is to assign individual mobile workers to each of your locations. This ensures that users have the correct access and permissions based on their assigned locations. Note: users can live in more than one location if needed, though most times users are assigned to only one location.
There are two ways to assign mobile workers to a location:
From the Mobile Worker List
Go to the Mobile Workers section and select a user.
Navigate to the Locations tab and assign one or more locations to the user.
Set a Primary Location to indicate the user’s main working location.
The Primary Location will appear in bulk mobile worker downloads/uploads and be displayed in the app when accessing the user’s information.
From the Locations Page
Go to the Locations page and find the location you want to edit.
Click Edit, then go to the Users tab.
Assign mobile workers to that location.
Using either method, you can efficiently manage mobile worker assignments and ensure proper location-based access in your CommCare project.
Orphan case alerts project setting
Depending on your use case, you might want to consider enabling the Show Orphan Case Alerts on Mobile Worker Page project setting. This will notify the user before accidentally unassigning the last mobile worker from a location that owns cases, thereby orphaning those cases.
Optional - Customizing the Display Format in Location Dropdowns
CommCare allows you to customize how location names appear in dropdown menus. You can choose between two display formats:
Location Path (Default Format) – Displays the full hierarchy of a location.
Example: East/Clinic A/Supervisor ABC
When hovering over the location path, the location name and type are displayed.
Location Name Only – Displays just the location name and type.
When hovering over the name, the full location path is shown.
By default, CommCare uses the Location Path format. To switch between the two formats:
Click the gear icon in the top-right corner and select Project Settings.
Under Project Administration, go to Feature Previews.
Check or uncheck the Use Location Name box.
Click Update Previews to save the change.
Once updated, the selected display format will apply across CommCare, including on Web User Invite/Edit pages and Create/Edit Mobile Worker pages.
Adding Custom Locations Fields
In some cases, you may need to store additional data about each location in your organization structure. With CommCare, you can add custom location fields to capture this extra information.
Steps to Add Custom Location Fields:
Navigate to the Organization Structure Page
Go to the Organization Structure page, and click on Edit Location Fields to begin adding custom fields.Add a Field
Click the green "Add a Field" button to create a new custom location field.Configure the Field
Fill in the following details for the field:Location Property: A unique identifier for the field, used in the app builder. Keep it concise and without spaces.
Label: The name displayed to users when adding or editing a location in CommCare HQ.
Required: Check this box if you want this field to be mandatory for all locations.
Choices: If you want users to select from a list of options, click "Add Choice" and enter the available choices. If free text input is needed, leave this blank.
Save the Field
Once you've filled in the necessary details, press the blue "Save Fields" button at the bottom of the page to save the custom field.
Example: Real-Life Application
For example, a healthcare organization might want to categorize each facility as a pharmacy, hospital, or clinic. By adding a custom field called "Facility Type" with a dropdown of these options, the organization can easily track and filter locations based on facility type. This allows program managers and mobile workers to access relevant data specific to each type of facility.