Managing Case Sharing & Data Access in Organizations

You’ve already learned how to set up the Organization Structure and define levels in CommCare. Now, you’ll see how it helps enable Case Sharing and Data access.

How Case Sharing Works with Organizations

By assigning mobile workers to specific locations, you can control which cases and data they can access. This ensures that users only see the information relevant to their assigned locations, improving security and collaboration. In this guide, you'll learn how to configure case sharing and manage data access using your Organization Structure.

Let’s say we have the following organization structure:

At the top is the West District, which oversees two clinics: Hope Care Clinic and Sunrise Health Centre. Each clinic has three Community Health Workers (CHWs). The hierarchy is structured as follows:

Open

Sample Organization Structure

Now, based on the organization structure above, we will define the levels as shown below. The top two levels (District and Clinic) will be able to view child data, while the bottom two levels (CHW and Clinic) will own cases.

Open

Organization Level

After putting all of the above information in place, the organization structure in CommCare looks like this as give below -

Open

Organization Structure

The Organization Structure in CommCare allows parent locations to view data from their child locations (e.g., a supervisor viewing their CHWs' data). For example, in the diagram above, users assigned to Hope Care Clinic can view data for their CHWs, and users at Sunrise Health Centre can view data for their CHWs. However, Hope Care Clinic cannot access Sunrise Health Centre’s data, and CHWs cannot view each other’s data. This workflow is achieved by assigning cases to child locations (e.g., CHWs), and allowing parent locations to view that data.

Users assigned to parent locations (with "View Child Data" enabled) can then access data from any locations directly below them in the hierarchy, but not those in other branches of the hierarchy.

Steps to Enable Case Sharing Application

When setting up Case Sharing in a CommCare application, you need to configure how cases are assigned based on the organization structure.

For Mobile Workers At One Location, Who Only Own Cases

• If a mobile worker is assigned to only one location that only owns cases (but cannot view child data), the setup is straightforward:

  • Enable the "Case Sharing" option in the application settings.

  • Once enabled, newly created cases will automatically be assigned to the worker’s location, ensuring that only relevant users at that location can access them.

Open

For Mobile Workers at 2+ Locations OR Who Can View Child Data

• Enable the "Case Sharing" option in the application settings.

• If a mobile worker is assigned to a location that can view child data, or is assigned to multiple locations, you will need to make a change in the application itself to tell CommCare where to assign the case. This is because there is no way for the app to know automatically where they should assign the case: they need logic in a hidden value, or the user to select a location in order to know the correct assignment. In this situation, when creating a case, you will need to choose which location the case gets assigned to. To configure this, follow the instructions below under the topic - Assigning Cases to One of Multiple Locations.

• Cases are assigned to child locations (e.g., individual CHWs like Alex).

• Users assigned to parent locations with "View Child Data" enabled can access data from any locations below them.

• Case-sharing groups are automatically created for each location that can own cases. These groups include:

  • Mobile workers at that location.

  • Any parent locations that have access to child location data.

This setup ensures a clear and controlled data flow, allowing organizations to efficiently manage case access based on their structure.

Setting Case Ownership using Locations

In CommCare, case ownership is automatically linked to the location of the user creating the case, ensuring that each case is assigned to the relevant health facility or geographic area. This setup helps maintain proper data management and accountability.

1. Automatic Case Ownership

When a case is created—such as when a patient is registered—automatic case ownership ensures that the case is assigned to the location of the user who fills out the form. This means that the case will be tied to the appropriate location in the organization’s structure.

• How it works: The case is automatically assigned to the location of the user who created it (e.g., a Community Health Worker or clinic staff).

• Note: This set-up only works if all users are assigned to only one location, and every location can own cases.

• owner_id = instance('commcaresession')/session/user/data/commcare_location_ids

Open

Setting up Automatic Case Ownership

2. Location-Based Logic

You can further customize case ownership by using location-based logic in your forms. This allows the case to be automatically assigned to the correct location based on the user’s current location or other input provided during the registration process.

• How it works:

  • If the location is linked to the user’s role, the system will use the user’s current location to assign the case (role-based logic).

  • Alternatively, if the location is determined by a field in the registration form (e.g., a dropdown of available locations), the system can assign the case based on the selected location (user-selected location).

This combination of automatic case ownership and location-based logic helps ensure that cases are correctly assigned, improving data management and access control within the organization. Let’s take a look at two examples of why a project would use either of these methods, and what they entail.
Orphan case alerts project setting

Example: Role-Based Logic & User-Selected Locations

Scenario An application has both community health workers (CHWs) and supervisors as mobile users. CHWs live at a location where they are the only user (they do not case share at that location). Supervisors live at the Clinic level, and oversee several CHWs. Typically only CHWs register new mothers, but when a new mom comes to the Clinic first, they are registered by the Supervisor, but need to get assigned to a CHW location for long-term monitoring.

Desired functionality: When a new mom is registered, if a CHW registers them, have the new mother case assigned to that CHW’s location. When a new mom is registered by the Supervisor, show the supervisor a list of possible CHWs where she can assign the new mom. Once the Supervisor selects the CHW location, assign the mother case to that location.

Roles-Based and User-Selected: This scenario demonstrates both the roles-based and user-selected functionalities. We first ask the application to look at the user’s location-- here we assume that supervisors live at clinic locations, and CHWs live at CHW locations (roles-based). If the user lives at a CHW location, we can calculate the location for case ownership automatically by looking at the user’s location. If, however, the user’s role is of a supervisor, we then ask the app to take us to another question where the user sees a list of locations, and can manually select the location (user-selected).

Steps to Create This Workflow:

1. Create a multiple choice question that has CHW locations as the choices. Follow instructions below for Assigning Cases to One of Multiple Locations.

   1. On this question, put a display condition that says the user’s location should be a clinic location (we only want this question to show for the Supervisors)

      instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@type = 'clinic'

2. Create a hidden value called owner_id. In the calculate condition, write the following expression:
   
   

   if(instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@type = 'chw', instance('commcaresession')/session/user/data/commcare_location_id, if(instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@type = 'clinic', #form/supervisor_select_chw_location, ""))

   Let’s break this calculation down to see what it’s saying:

if(instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@type = ‘chw',

the above syntax means that if the location that the user is assigned to is the location type ‘chw’

instance('commcaresession')/session/user/data/commcare_location_id,
then assign this case to the user’s location

if(instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@type = ‘clinic',

if the location the user is assigned to is the location type ‘clinic’

#form/supervisor_select_chw_location, ""))

then assign that case to the chw selected in the question supervisor_select_chw_location (hint: that’s the question you created in step 1). Otherwise, if neither of those criteria are met, leave this blank.

3. Save the question owner_id as a case property in your case management page.

Assigning Cases to One of Multiple Locations

What is This Feature?

This feature allows you to create dropdown lists in forms where users can select locations based on the pre-defined hierarchy you made when you created your organizational structure. It works similarly to using lookup tables or cases for multiple-choice questions.

Why Use It?

• Ensures consistency in selecting locations.

• Allows users to select from predefined location levels (e.g., state, district, block).

• Supports tiered selection, meaning a selection at one level can filter options at the next level.

When to Use It?

In some scenarios, you may want your users to manually select the location that a case gets assigned to. This could be because:

• Users live in multiple locations, and need to select the relevant location for this case

• A user higher up in the hierarchy needs to select a lower-level location for the case to live at (e.g. a clinic-level worker needs to assign to a CHW, or a district coordinator needs to assign a child to a school)

• Cases can be assigned to users who aren’t registering them. In some rare scenarios, a mobile user may register someone outside of their catchment area, and you may want them to be able to assign that person to the correct location (e.g. not this worker’s area). By letting the user choose the location, you enable the user to select the correct assignment for this case.

To facilitate this, you can add a multiple-choice question to your application that allows users to select the location where the case should be assigned.

Step 1: Enable the Required Add-On

To display a list of case-sharing groups during registration, you need to enable the "Custom Single and Multiple Answer Questions" add-on. This feature allows you to create custom choice lists in forms, such as listing case-sharing groups, instead of relying solely on Lookup Tables.

How to Enable the Add-On:

1. Open your application and click the gear icon (⚙) next to the application's name at the top left of the screen.

2. Navigate to the Add-Ons tab.

3. Under the Calculations section, enable the "Custom Single and Multiple Answer Questions" add-on.

4. Click Save.

Step 2: Configure Your Application

Once the add-on is enabled, update your Registration form to display the list of case-sharing groups using a Lookup Table Multiple-Choice Question.

How to Configure the Registration Form:

1. Open the form used for case registration.

2. Add a Multiple Choice Lookup Table question from the Choice dropdown.

3. Set the Question ID to owner_id (or another relevant identifier).

4. Set the Label to something meaningful, such as "Which location should this case be assigned to? or “Choose the CHW to allot the case to", shown in the GIF below.

5. In the left panel, select ‘Lookup Table Data’, then click the "..." button to configure the choices.

6. Set the Query Expression to:

   instance('locations')/locations/location[@type = 'TYPE OF LOCATION']

   • (Replace "TYPE OF LOCATION" with the specific location type in your application who you want to allot the case to. The type of location can be picked up from ‘Advanced mode’ section of Organization Level, as shown in the GIF below.

   • This expression ensures that only relevant locations appear as options.

7. Set the Instance ID to locations and the Instance URI to jr://fixture/locations. Click Save.

8. On the Lookup Table Data page:

   • Set Value Field to @id (this assigns the selected location’s ID to the case).

   • Set Display Text Field to name (this shows the location name in the dropdown).

   • The filter option under Logic would have automatically changed to @type='TYPE OF LOCATION'.

9. Save the form.

Step 3: Assign the Location to the Case

To ensure the selected location is assigned to the case:

1. Go to the Case Management section of the form.

2. Save the Multiple Choice Lookup Table question to the case property owner_id.

   • owner_id is a special property used to define case ownership.

3. Save your changes.

Step 4: Test with a New Registration

1. Log in as a mobile worker assigned to locations with "View Child Data" access. In the GIF, you can see that I have logged in as a clinic mobile worker who can view child data.

2. Go to your Registration form, scroll down, and you will see a multiple-choice question displaying all the CHWs or the location you opted above in the question for case allocation.

3. Before submitting the data, you can check the Data Preview to verify if the Owner ID is capturing the correct location ID of the mobile worker.

From now on, whenever a mobile worker registers a new case, they will be prompted to select a location, ensuring the case is assigned correctly.

Open

Assigning Cases to One of Multiple Locations

Restricting Web User Data Access Based on Locations

In CommCare, access to data can be restricted based on user-assigned locations, ensuring that users only see the information relevant to their designated areas. This is particularly useful for large-scale projects with hierarchical structures, such as national or regional programs.

For mobile users, location assignments determine the cases and forms they can access. Similarly, Web Users can also be location-restricted—meaning that when they log into CommCare HQ and export case or form data, they will only see data from the locations they are assigned to. This helps maintain data security and ensures that users work within their relevant scope. For more information about configuring roles see https://dimagi.atlassian.net/wiki/x/BzXKfw.

By leveraging location-based restrictions, organizations can manage access efficiently while maintaining data privacy and integrity.

Setting Up Location-Restricted Web Users

Example:
A local partner has been assigned to a specific district. In this case, they should only be able to access the data associated with that district and not data from other districts. Similarly, program managers responsible for different regions or geographies should only have access to data related to their assigned region.

To achieve this, you can set up a location-restricted web user role for each partner or program manager. This ensures that they can only view and manage data for their respective locations, maintaining data security and ensuring that users access only what they are authorized to see.

Organizations in CommCare allow you to partition your project and restrict which data different users can view and edit. With location-based restrictions, you can limit data exports so that a web user can only export data for their assigned location, or restrict mobile worker and location editing. When organization-based restrictions are enabled, users are limited to accessing the following:

1. Mobile Workers

A web user can view and edit mobile workers who are assigned to their location or any of their location's child locations.

2. Cases

The web user can view cases that are assigned to their location, their child locations, or any mobile workers they have access to.

3. Forms

The web user can view forms submitted by mobile workers they have access to.

4. Some Reports

Currently, the 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

Once roles are configured, assign a web user to that role and specify their accessible locations by selecting the user from the web user management page.

Open

Steps showing how to set-up a Location-restricted Web User

Restrictions on CommCareHQ Pages and Routines

When a user is location-restricted, they will only be able to access pages on CommCareHQ that are tied to their location. These include:

• Data Exports: The user can export form and case data, but only for their assigned location or child locations. If no filters are set, the data from their assigned location (and child locations) will be exported.

• Mobile Workers: The mobile workers page will only display workers that the user has access to. When creating a new mobile worker, they must be assigned to one of the user's available locations.

• Organization Structure: Only locations that the web user has access to will appear here and be editable.

By implementing these restrictions, you ensure that users can only access the data they are authorized to see, improving data security and privacy within your organization.