Setting up Organization Levels and Structure
Overview
Note: In order to use this feature, you must have Case Sharing enabled in your app. For more information, please see https://dimagi.atlassian.net/wiki/x/ITLKfw.
Once you've defined a hierarchy, it can be used to simplify managing the project:
Case Sharing can be configured so that cases are assigned to a location. Then higher levels can see cases of lower levels (ex. Mobile workers at a clinic can see the CHWs' cases)
Lookup Tables can be assigned to a location allowing all mobile workers at that unit and below it to see that lookup table's data
Your organization structure can be displayed inside your forms (ex. Allowing users to choose the village for a given beneficiary from a list).
In the future, "Organizations" will also enable reporting and data exports (allowing you to download data or a view a report for users at and below a particular organization unit).
Set Your Organization Levels
To use Organizations, you first need to define your Organization Levels. These describe the behaviour of different levels of your hierarchy (i.e. whether Clinics, for example, can have cases assigned to them).
To setup Organization Levels, go to Users tab and choose Organization Levels from the menu.
You can use the page to define the levels in your organization hierarchy. 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 (ex. the parent level of 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 created and assigned to them. For example, you may have Health Workers that own cases, but districts do not. If there are multiple workers assigned to a single location at this level they will share cases if this box is checked. Depending on your use case, you might want to see https://dimagi.atlassian.net/wiki/x/XTPKfw for more information.
View Child Data: For an organization level that has child organization levels, this controls whether a location at that level can view cases assigned to child locations. For example, you may want to have Clinics view cases owned by each child Health Worker.
Here's a simple example of the organization levels for a project:
Set Your Organization Structure
Once you've configured your Organization Levels, you can create the the Organization Structure for your project. The Organization Structure is comprised of locations that can represent a geographical hierarchy (i.e .a state or a district), a real world location (i.e. a Clinic) or just a programmatic point in the hierarchy (i.e. a Supervisor and Health Workers).
Click on the Users tab and choose Organization Structure.
Click on the "New location at top level" to create your first location.
Once you've created a location, you can click New Child Location, or go back to the Locations page to create more locations.
When viewing the location tree, you can use the + button to expand a location and view its children. Once expanded, there will also be a button to create more child locations for that location.
You can also 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 CommCare Supply project
Parent: Change or move the location to a different parent. 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
Bulk Importing your Organization Structures
Once you've created your Organization Levels, you can also use Excel to create or update the organization structure. Using Excel might be easier when managing larger numbers of locations.
1. Go to the Organization Structure page (Users tab -> Organization Structure) and then choose Bulk Upload.
2. Download the Excel file - it will list 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 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. If the location doesn't have a parent, leave this column blank
Latitude and Longitude: Optional columns to set the coordinates of the location.
3. Once you've created or updated your Excel file, upload the Excel file using the same download page.
Note: You cannot move locations using the bulk upload (changing the parent site code for an existing location will result in an error).