| Excerpt |
|---|
The sections below walk through how to use the Organizations Feature in CommCare. |
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
...
In order to use this feature, you must have Case Sharing enabled in your app. |
More information about case sharing can be found here: Case Sharing
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Setting up Organization Levels and Structure
Overview
Note: In 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.
...
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 support reporting and data exports (allowing you to download data or a view a report for users at and below a particular organization unit).
...
...
| minLevel | 2 |
|---|---|
| style | circle |
Set Your Organization Levels
...
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
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.
...
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
Orphan case alerts project settingDepending 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. |
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.
...
Case Sharing using Organizations
| multiexcerpt-include |
|---|
...
| Child pages (Children Display) | allChildren | true|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| -macro | ||||||||||
|
The Organization Structure lets you easily configure parent locations to view their child location's data (ex. A supervisor viewing their supervisee's data). In the example diagram below, users assigned to Fermathe Hospital can view the data for their health workers, and users assigned Grace Children's Hospital can view their health worker's data, but Fermathe Hospital can't view Grace Children's data, and each health worker cannot view each other's data.
...
This works by assigning cases to the child locations (ex. Andrea Fletcher). Users assigned to parent locations (that have View Child Data turned on) are then allowed to view data for any locations below them. A case sharing group is automatically created representing each location that can own cases - CommCare will then automatically assign mobile workers to the case sharing groups based on the organization hierarchy and data sharing settings.
Configuring Case Sharing for an Application
For mobile workers assigned to locations at an organization level that can only "Own Cases", but not "View Child Data", its relatively simple to configure the application. Turn on the Case Sharing option on the application settings page and newly created cases will automatically be assigned to the location.
...
For mobile workers assigned to locations at an organization level that can "View Child Data", they can sometimes be in more than one case sharing group. You'll be required to choose which location the case gets assigned to. To configure this, follow the instructions on the https://dimagi.atlassian.net/wiki/x/2CTKfw.
This works by assigning cases to the child locations (ex. Andrea Fletcher). Users assigned to parent locations (that have View Child Data turned on) are then allowed to view data for any locations below them. A case sharing group is automatically created representing each location that can own cases - mobile workers at that location and any parent locations that can view child location data are added to that case sharing group.
Location-Based Data Access and User Editing Restrictions
IMPORTANT: This feature dramatically limits what pages and reports are available. In particular, things like app-building, messaging, and admin configurations are disabled for restricted users. Be sure to log in as a restricted user to see what's available before committing to using this feature.
Organizations allow you to partition your project and restrict which data different users are allowed to view and edit. You can limit data exports so that a web user can only export data in their assigned location, or limit mobile worker and location editing. When you have organization-based restrictions turned on, users are only allowed to access the following:
Mobile Workers: The web user can view and edit mobile workers who are also assigned to their location, or assigned to any of their location's child locations.
Cases: The web user can view cases that are assigned to their location, their child locations or any mobile workers they also have access to
Forms: The web user can view forms submitted by mobile workers that they have access to
Some Reports: As of this writing, following reports are accessible:
Submit History (and associated child pages)
Case List (and associated child pages)
Aggregate User Status
Application Status
Submissions By Form
Daily Form Activity
Form Completion Time
Form Completion vs Submission Trends
Restricting Access for a Web User Role
Create or edit a web user role that defines what the web user will be allowed to access. When configuring the role, make sure you set "Full Organization Access" to false. For more information about configuring roles see https://dimagi.atlassian.net/wiki/x/BzXKfw.
...
Setting up a Web User
Once you've setting roles, you can assign a web user to that role and their accessible locations. This is done by clicking on the web user from the web user management page.
...
Restrictions to Routines and Pages on CommCareHQ
Once a user is location restricted, they will be able to access only pages on CommCareHQ that can have their information restricted by location. These pages include:
Data Exports: The user will be able to export form and case data, but they will only be able to filter the data to their assigned location or their child locations. If no filters are specified, all data from their assigned location (and that location's child locations) will be downloaded.
Mobile Workers: The mobile workers page will only list mobile workers that the user has access to. When creating a mobile worker, they will need to be assigned to one of the user's available locations
Organization Structure: Only locations that the web user has access to will be listed here and editable.
Adding Custom Location Fields
You may want to add and store additional data about each location. In order to do that, you can add custom location fields to your organization structure.
Step 1
To add a field, go to the Organization Structure page, and click on Edit Location Fields.
...
Step 2
Click on the green "Add a Field" button to add a custom field:
...
Step 3
Enter in the following information for the field:
Location Property: the unique ID you can use to reference this property in the app builder. This field should be concise, and cannot have any spaces.
Label: this is the text that users will see when adding or editing a location in CommCare HQ.
Required: tick this box if you want the field to be required for all locations.
Choices: if you want users to have to choose from a list of dropdowns, click on "add choice" and add as many answer options as you'd like to appear in the dropdown. If you want users to be able to enter in free text, do not add any choices.
See example below where we are adding a field called Facility Type, with three answer options in a dropdown (pharmacy, hospital, and clinic):
...
Step 4
Press the blue "Save Fields" button at the bottom of the page, and your location field will be saved.
...
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