Case Sharing

Owned by Amelia Sagoff (Unlicensed)
Last updated: yesterday at 9:35 pm by Krinda Wernicke
11 min read

Case Sharing allows your field team to share responsibilities of a case load.

Overview

In the default CommCare model, each CommCare user has their own list of cases, comprised of the cases he/she has created. When a mobile worker registers a pregnant mother on CommCare Mobile, let's call her 'Monica' in this example, the 'Monica' case will only appear in this specific mobile worker's case list (What's a case list is? See https://dimagi.atlassian.net/wiki/x/8xrKfw). The 'Monica' case will not be show in anyone else's case list, meaning no other mobile worker can perform a follow-up visit with Monica.

Case Sharing changes this model by allowing mobile workers to share cases with other CommCare users.

To do so, you'll create a case sharing group, then add mobile users to that group. All mobile users within a single case sharing group have access to the cases other members of the group have created. These Case Sharing Groups allow multiple mobile workers to share responsibility for a group of cases, by making it seamless for different workers to conduct different pieces of overall project services for a single case. 

Some common use cases:

  1. David works with another community health worker, Maria, who has the same CommCare application on her phone.  David and Maria visit the same community members. Sometimes David will register a new pregnancy, and Maria will follow up with her later.

  2. David refers sick clients to a local clinic.  A nurse at the clinic has a phone with a different CommCare application for sick community members.  The nurse will want to see why David referred the patient, as well as all the data that David has collected about the patient in the past.  David will want to know the outcome of the visit.

How to enable case sharing

  1. Make sure any CommCare applications that you want to have share cases with one another are located in the same project space.

  2. Turn on case sharing for your application(s), by doing the following for each app:

    1. Go to app settings (by clicking the gear icon next to the app name).

    2. Select the "Advanced Settings" tab.

    3. Check the "Case Sharing" checkbox.

  3. Add your mobile users to case sharing groups, by doing the following:

    1. Go to the "Users" page.

    2. Click on "Groups".

    3. Enter a name for the group and then click on the "+ Create Group" button.

    4. On the new page that loads, click "Edit Settings" and then turn on Case Sharing.

    5. Under the "Group Membership" tab, add all users who you wish to have share cases with each other in this group, by entering each username one at a time and then clicking "Update".

  4. If you're sharing cases between two or more different CommCare applications, make sure that the case type matches between all the menus you want to have share case lists.

It is important to note that by default case sharing assumes all users are in exactly one case sharing group (or location). If a user is not in a group, or is in more than one group, apps will throw an error for any form that creates a new case unless additional configuration is provided to clarify the owner of the case.

To configure case sharing for users in multiple groups, you can read the following guides depending on what features you are using.

You can find steps to address issues with those configurations on this page: https://dimagi.atlassian.net/wiki/x/EzLKfw.

Advanced

You can structure your case sharing groups such that a "supervisor" user is in multiple case sharing groups. If you are on the Advanced plan or higher, this is easy to set up through Organizations.

Errors

Often if you have an error in case management (i.e. you did not follow one of the steps above), you will see a message indicating that your user is not in a case sharing group or is in more than one case sharing group. If you see this, go back and check your case sharing settings or visit to know more about the error. It is likely that 1 of your users is not in exactly one case sharing group.

Assigning cases to one of multiple groups

Let's suppose that you have nurses who see patients at health centres, and each health centre draws patients from several surrounding villages. Each village then has a worker who performs checkups in the village at the patients' houses. 

Alternative Option

This page describes manually configuring case sharing groups. You can also use the Organizations feature to more easily configure this setup.

What needs to exist for the above to happen (without having all the workers see all the other workers' cases) is one case-sharing group per village containing the worker and each nurse that could potentially assign a case to that worker. If the worker registers a new case, the case will be shared in the village's case-sharing group which includes the nurse. When the nurse registers a case, they will have to select which village's case sharing group will own the new case. This means that the nurses will be in several different case sharing groups.

 

Step 1: Setup the Case Sharing Groups

You need to setup one Case Sharing group for each set of cases you want shared.  In the example above, the project needs one group for Village 1 Worker, one group for Village 2 worker, one group for Village 3 worker.  You would then assign the nurse to all three groups, and the worker to their own groups.

To setup the Case Sharing groups, go to Users -> Groups.  Then create the case sharing groups required, and make sure you turn on "Case Sharing" for each group. To do so, select the group you want to enable case sharing for to proceed to the edit groups page. On this page, select Edit Settings to open a pop out window where you can turn case sharing on. 

Step 2: Turn on the Feature Preview

When a nurse is registering a patient, you want to display a list of the case sharing groups so that they can assign the case to the appropriate village worker.  To do this, you need to turn on a Feature Preview called "Custom Single and Multiple Answer Questions".  This allows you to display custom choice lists in forms (i.e. a list of case sharing groups) instead of just items from a Lookup Table.

  1. Proceed to the Application Settings by selecting the Gear in the top left hand corner. Then select the 'Add-ons' tab:

  1. Select the button with three lines on on the right hand side of the screen. Select 'Calculations' from this drop-down.

  1. Turn on the "Custom Single and Multiple Answer Questions" feature preview and then click 'Save'.

Step 3: Configure Your Application

In the application, you need to setup your Registration form so that it displays the list of case sharing groups in a single or multiple select question.  

  1. Go to your form that is used to register a new case.  Add a new Checkbox Lookup table question to the form:

  1. Set the question ID to 

village (or whatever makes sense) and the display text to "What village do you come from?"

  1. Choose the "Lookup Table Data" item in the left tree, and then choose the "..." button to configure the list of choices.

  1. Set the Query Expression to

instance('group')/groups/group . This will display the list of case sharing groups.   Set the Instance ID to group and the Instance URI to jr://fixture/user-groups .  Then click on the Save button. 

  1. Back on the Lookup Table Data page, set the Value field to 

@id and the Label field to name.  Note that the Lookup Table dropdown should say "Lookup table not found in project"

  1. Save your form, and then go to the Case Management section of the form and save the question to the case property called 

owner_id.

Separate worker and nurse apps

If the workers and the nurses use the same app, the workers will see the question 'what village do you come from?' with only one possible answer corresponding to the one village which they work in. To avoid this, you can have the workers use a separate app to register cases. Make sure the worker app has case sharing Enabled so that the nurses can see the cases they register. Remember that only forms with the above code can be accessed by users in more than one group.

Multiple workers in the same village

If each village has more than one worker, make sure that they are all the workers are in the village's group, that the group has case sharing enabled, and that the workers' app also has case sharing enabled (see above).

Case Sharing FAQs

If a case was created before case sharing was turned on and the case sharing group was created, does that case get reassigned automatically to that group's owner id, or does the case retain its original owner id?

The case should retain the original case owner ID

What is the difference between user id and owner id?

The owner ID is the id of the user or group who owns the case (the case will appear on their application's case list). User id is the id of the user who last submitted a form to the case.

What happens if two mobile users are sharing a case, are both working offline, and both make changes to the case?

Once the forms are submitted they will update the case in the order in which they are received (according to the server received time). If one of the forms closed a case and a subsequent form attempts to update that case, the case will not be reopened but the (now closed) case will be updated.

Is there a way to specify case sharing for different groups by menu or a specific case type?

Unfortunately this use case is not currently supported in the app builder. However, you can configure this manually by specifying the "owner_id" property for new cases which you don't want to share to be set to the id of the current user (defined in the form as a hidden value) in the normal case property configuration screen. That will result in those cases not being shared.

Debugging Case Sharing errors

If you are here, then you probably came across the error message "The case sharing settings for your user are incorrect. This user must be in exactly one case sharing group. Please contact your supervisor" in a CommCare app on a mobile device:

Or via Web Apps:

Before we can debug this error it's important to understand a few relevant concepts:

  • Case sharing - if an app has Case Sharing enabled, cases are supposed to be shared between users. For more on this, see .

  • Case Ownership - every case in CommCare has an owner that can be a user (web or mobile), a user group or a location, which means that before a case can be created its ownership needs to be decided. The decision of who (or what) should be the owner is normally done by CommCare but can also be done manually, as we will explain later. However, when Case Sharing is enable this process becomes complex for CommCare as the User, the default option, is no longer acceptable.

Let's now interpret the error. Mainly, Case Sharing is enabled and CommCare is responsible for determining the owner of cases. However, the user is either configured incorrectly or they are associated with too many locations and/or case sharing groups, so CommCare gets "confused" and throws this error. Often, this can be solved by setting the ownership manually. An important note here is that, in most of the scenarios this error is directly related to some design decision made for the app, so before implementing a solution, it's good practice to revisit documentation to ensure that whichever solution is applied won't break any workflow.

The following is a list of example scenarios that could lead to this error coming up:

  1. User is not assigned to a Location or Case sharing group - without a Location or Case Sharing Group associated to the mobile user, CommCare is forced to set the ownership to the user. However, setting the ownership to the user will automatically prevent the case from being shared, so CommCare prevents this behavior from happening automatically.

    1. Solution: assign the user to a Location or a Case Sharing Group

  2. User is assigned to more than one case sharing group and/or location - considering that there are many options available, CommCare is unable to decide on who should be the rightful owner, resulting in that same error being thrown. This also applies if the user is assigned to one Case Sharing Group and one Location when the Organizational Level is set to Own Cases (see more in ).

    1. Solution: There are two potential approaches here. You can change the configuration of the user so that they are only assigned to a single Case Sharing Group (see more in ) or Location (see more in ). Alternatively, you set the ownership manually within the form (see below).

  3. User is assigned to a Location that can't Own cases - in this scenario, CommCare sees that the user is assigned to a Location that, according to the configuration of the Organization Level, can't own Cases.

    1. Solution: There are two potential approaches here. You can change the configuration of the location to allow it to own cases (see more in ), or you can set the ownership manually (see below). You will need to ensure that all cases created within the form settings have an owner_id property set, including any child cases.

  4. User is assigned to a Location with child Locations and View Child Data is Enabled - this is a more complex problem to solve. In this case, it typically appears that the users are correctly configured, and that each one is assigned to a single location. However, since the user has access to data in the child locations as well, the child locations are also considered valid candidates for case sharing, similarly to if the user was actually assigned to multiple locations as outlined above.

In this example, we can conclude that Nurse should be able to see cases from their CHWs and also to have their own cases. The error would occur when Nurse tries to create a new case, however, the app should work fine for CHW 1 and 2.

a. Solution: In this case, usually the only viable option is to set the ownership manually (setting a hidden value in the form called owner_id, manually setting it to be the location you need the case to live at, and saving it as a case property). Of course, you could turn the View Child Data option off but this would most likely go against the workflow of the app.  

Setting case ownership manually

So, at this point it's safe to assume that you have exhausted all other options and decided to set the ownership of the case manually. First, you need the ID of the owner, this can be achieved either by having the user selecting a Location or a Case Sharing group from a Multiple Choice Lookup Table question or some calculation that returns a single ID. Next, you need to instruct CommCare to assign the ownership based on that ID, for that you have to set the case property owner_id in the Case Management section of your form. Find more information about this process in  .