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:

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

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:

1. Name and Organization Level

2. Coordinates: This is useful for map-based reports if using Organizations in  CommCare Supply project

3. Parent: Change or move the location to a different parent.  Currently only locations with no children can be moved.

4. 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.

1. 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.

1. 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). 

Assigning Mobile Workers to Location

To use the Organizations feature in your applications, you first need to assign mobile workers to the location.  

There are two ways to assign mobile workers to a location

1. You can choose the user from the mobile worker list, and then use the Locations tab to choose their location.  Each user can be assigned to more than one location.  Set the Primary Location to represent that user's main working location.  This primary location will then appear in the bulk mobile worker download / upload, and be displayed in the app when accessing the user's information.  

Orphan case alerts project setting

Depending on your usecase, 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.

2. Alternatively, you can use the Locations page to edit the location.  Choose Edit on the location from the Locations page, then chose the Users tab to assign mobile workers to that location.