Advanced Organization Level Configuration

Enabling Advanced Options for Organization Levels

CommCare offers advanced settings for organization levels to better manage complex projects. These options, available by checking the Advanced checkbox on the Organization Levels page, help customize data access, user roles, and multi-location structures to fit your project’s needs.

Open

Enabling Advanced checkbox on Organizations Levels page

Advanced Organization Options

1. Type Code

A Type Code is a unique identifier assigned to a location type in CommCare. It helps reference specific location types in lookup tables or logic expressions when building forms and reports.

How Does It Work?

Let’s say your project includes different organization levels, like Country, State, and District Warehouses. Each of these levels can have a Type Code to make them easier to reference in formulas.

For example:

• If your location type is District Warehouse, the Type Code might be ‘district_warehouse’.

• In the example below, the location is a district, so its Type Code is ‘district’.

Using Type Codes helps streamline data organization and ensures that location-based logic works correctly in your CommCare application.

Open

2. Level to Expand From

By default, CommCare syncs a user’s assigned location, along with its ancestors (higher levels) and descendants (lower levels) in the organization hierarchy.

For example, if the hierarchy is:
District → Clinic → CHW (Community Health Worker)
And a user is assigned to a Clinic, they will receive data for:

• Their District (ancestor)

• Their Clinic (assigned location)

• All CHWs within that Clinic (descendants)

Why Adjust "Level to Expand From"?

Sometimes, a user needs access to locations outside their standard hierarchy.

For instance, if a user is assigned to ‘Clinic A’ but needs access to ‘all Clinics within their District’, you can set the Level to Expand From to ‘District’ instead of Clinic. This would be helpful if you had clinics workers who might register patients in one clinic today, but want the patient’s case to be owned by another clinic long-term (e.g. the clinic they will receive care from, the one closer to their house, etc).

Now that you have adjusted the Level to Expand From to ‘District,' the user will receive:

• Their clinic

• All Clinics locations in that District (including their own)

This setting allows greater flexibility in data access, ensuring users get the information they need without unnecessary restrictions.

Open

Level to Expand from

3. "Level to Expand To" (Performance Optimization)

The Level to Expand To setting helps control which location types are sent to a user. This is mainly used to optimize performance by reducing unnecessary data.

How It Works

By default, if a user is assigned to a District, CommCare sends them data for:

• Their District (assigned location)

• All Clinics in that District

• All CHWs within each Clinic

If there are too many CHWs, it can slow down the app by increasing the amount of data that needs to be processed.

Why Adjust "Level to Expand To"?

If CHW data isn’t needed, you can set Level to Expand To = Clinic. This means the user will now receive:

• Their District

• All Clinics in that District

• 🚫 CHWs will NOT be included, reducing data load

This setting improves app performance while ensuring the user still gets the necessary location data.

Open

Level to Expand to

4. Include without Expanding/Force Sync

The Force Sync option allows CommCare to send all locations of a specific type to a user without including their lower-level locations (descendants).

How It Works

In a standard hierarchy:
District → Clinic → CHW (Community Health Worker)
If a user is assigned to a Clinic, they normally receive:

• Their District

• Their Clinic (assigned location)

• All CHWs in that Clinic (descendants)

Why Use Force Sync?

Let’s say a user needs to see all Districts but not the Clinics or CHWs within them.

• Enabling Force Sync for Districts ensures the user receives:

  • All Districts

  • Their assigned Clinic

  • 🚫 No Clinics or CHWs from other Districts

This setting is useful when users need high-level location access without being overwhelmed by unnecessary data.

Open

5. Include Only

   The Include Only setting lets you control which location types or levels a user can see in CommCare. This ensures users only access the locations relevant to their work while keeping the interface clean and manageable.

How It Works

Every location type you select must also include its parent levels.

For example, in a District → Clinic → CHW hierarchy:

• If Include Only is applied at the Clinic level, the user will see:

  • Their assigned Clinic

  • 🚫 No Districts (parent level is removed)

  • 🚫 No CHWs (child level is removed)

Why Use "Include Only"?

This setting is useful when:

• You want to limit unnecessary information for users.

• Users should only focus on their assigned location without seeing higher or lower levels.

• It helps simplify workflows by displaying only the data they need.

By keeping the interface focused, ‘Include Only' makes it easier for users to navigate and complete their tasks efficiently.

Open

Include Only

Translating or Customizing Location Display

Location names in CommCare cannot be translated directly, but there is a way to customize how they appear in your app. This method lets you display locations in different languages and formats as needed.

Understanding the Approach

Normally, multiple-choice or checkbox questions using lookup tables pull location names directly from the system, giving you little control over customization. To work around this, we create a nodeset using a repeat group with a model iteration query. This allows us to define additional properties, like translated names, for use in lookup table questions.

Step 1: Storing Location Translations

To make this work, we first need to store translations for location names. We can do this by adding custom location fields for different languages. Go to ‘Edit Location Fields’ under Organization Structure and Click on ‘Add a Field’. Add new custom fields for each language:

• name-en (for English)

• name-hin (for Hindi)

• name-es (for Spanish)

After adding these fields, we edit each location (e.g., District, Block, CHW) to store the correct names in each language.

• Go back to Manage Locations.

• Select a location (e.g., a District, Block, or CHW).

• Enter the translated names under the new fields (name-en, name-hin, name-es).

• Repeat this for all locations.

• Save changes.

Step 2: Referencing the Current Language

To use the correct translation, we need to reference the current language selected in the app. This process is described at Lookup Tables | Using Lookup Tables with Multiple LanguagesBy setting up a lang-code question, we can use:

jr:itext('lang-code-label')

to dynamically fetch the right translation.

Step 3: Setting Up a Nodeset for Location Display

1. Create a Repeat Group:

   • Under "Advanced," set the Model Iteration ID Query to:

     instance('locations')/locations/location/@id

   • This ensures the repeat group runs for each location in the system (e.g., all Districts, Blocks, and CHWs).

   • Set Instance ID to "locations" and Instance URI to "jr://fixture/locations".

2. Store Location Translations in Hidden Values:

   • Inside the repeat group, create a hidden value to store the translated name:

     cond(jr:itext('lang-code-label') = 'es', instance('locations')/locations/location[@id = ../@id]/location_data/name-es, jr:itext('lang-code-label') = 'en', instance('locations')/locations/location[@id = ../@id]/location_data/name-en, jr:itext('lang-code-label') = 'hin', instance('locations')/locations/location[@id = ../@id]/location_data/name-hin, instance('locations')/locations/location[@id = ../@id]/name)

   • This ensures the correct language version of the location name is selected dynamically.

Step 4: Setting Up the Lookup Table Question

1. Create a Lookup Table Question.

2. Link it to the Nodeset:

   • Drag the repeat group into the Query Expression field. It should look like:

     /data/locations/item

   • (Ensure it starts with /data/, as using #form/ will cause an error.)

3. Set Display & Value Fields:

   • Value Field: @id

   • Display Text Field: name (or any custom field you want to show)

Final Outcome

Now, when users select a location (e.g., District → Block → CHW), they will see the name in their preferred language. This method ensures proper translations while keeping the lookup table flexible and customizable.

Referencing the Location Hierarchy in Applications

What is this feature?

Referencing the Location/Organization Hierarchy means using XPath expressions in CommCare to dynamically pull location-related data into your forms and workflows. This allows apps to automatically retrieve and display information based on a user’s assigned location. This can be incredibly helpful, because it allows the application to find and store information relevant to the case based on the user’s information without burdening the user.

For example, if I have a user who is assigned to District A, and I calculate that in a hidden value, I can then refer to the location hierarchy to get other information about District A, or other locations above or below it. If I wanted to save the name of the state or country that District A is a part of, I could do that easily using calculation conditions in hidden values (without having to make the user manually answer questions).

Why use this feature?

• Automate Data Entry – Users don’t have to manually enter their location details; the app can automatically retrieve them.

• Control User Access – Helps restrict data visibility based on the user’s assigned location. For example, a CHW can only see data for their assigned village, while a District Manager can access all villages in their district.

• Improve Reporting & Analysis – Ensures that reports and dashboards display location-specific data for better decision-making.

• Simplify Case Management – Helps link cases to the correct location automatically.

By using this feature, organizations can reduce errors, save time, and ensure accurate data collection in their CommCare applications.

How to use this feature?

Ensuring Access to the Location Hierarchy

To reference the location hierarchy in forms, you need to manually edit the XML source and construct XPath expressions.

Confirming Access to the Location Data Source

Before using location references, ensure the form has access to the Locations data source:

• If the form contains at least one select question with locations as choices, the data source will be available automatically.

• If not, create a dummy question following these steps:

  1. Add a select question with locations as choices.

  2. Set the Display Condition to false() to hide it.

This ensures that location data is accessible throughout the form. If you are already using a Locations-driven select question, the dummy question is not needed.

Enabling Access to Location Hierarchy

All new projects in CommCare automatically include the location hierarchy. However, older projects may be configured to use the Old Hierarchical Fixture. To transition to the new flat fixture format, follow these steps:

1. Navigate to Project Settings.

2. Select Pre-Release Features → Location Fixture. (This option will not be visible to new domains, so you can skip this step).

3. Enable the new flat fixture format.

Open

Enabling Location Fixture

Once enabled, new app versions will start using the new location format. After all users have transitioned to an updated version of the app, the Old Hierarchical Fixture can be turned off. This process is described in more detail in the documentation.

Retrieving the User’s Location ID

To access the currently logged-in user’s location ID, use the commcare_location_id session variable. This can be referenced in a form with the following expression used in a hidden value type question -

instance('commcaresession')/session/user/data/commcare_location_id

This ID is linked to the user’s assigned location within the organizational hierarchy and can be used for data filtering, case management, and reporting.

Open

Retrieving User's Location ID

Referencing the User’s Location or Ancestor Location in a Form

You can use the following XPath templates to reference the properties of a user’s location or their ancestor location. These examples assume a State → District → Block → Outlet hierarchy but should be customized based on your specific setup.

Finding the Organization Level Code

Each organization level has a unique code. To find the correct code:

1. Go to the Organization Level page.

2. Click on the Advanced checkbox to view the level-specific codes.

Example: Retrieving an Ancestor Location ID

If your hierarchy follows Village → City → County, and you need to retrieve the City ID for a Village-level user, modify the following XPath expression:

General Template:

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

Customized for City ID:

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

Replace @block_id with @city_id or any other relevant location level based on your hierarchy.

By implementing these expressions, you can dynamically pull location-based data for users and customize form logic accordingly.

Open

Referencing ancestor location in a form

Accessing the location additional information (Location Fields)

Once you have the location's ID you can access it to get other information.

These examples assume your ID is stored in a hidden value called location_id

Open

Access Location Fields in the form

Syncing a Broader Location Hierarchy to Users

By default, CommCare synchronizes only the locations that a user is directly assigned to, along with their ancestors (higher levels) and descendants (lower levels).

For example, if a user is assigned to a ‘block’, their synced location data will include:

• Their ‘block’ (assigned location).

• The ‘district' and 'state’ (ancestors of the block).

• All outlets within the ‘block’ (descendants).

Expanding Location Sync Beyond Default Settings

In some cases, users may need access to locations beyond their direct hierarchy. For instance:

• A user assigned to a block might also need to see all districts within the state, even if they are not direct ancestors or descendants.

This can be configured using the "Expand From" settings, which allow additional location levels to be synced based on project needs.

For more details on how to configure this, refer to the "Expand From" section in the documentation.

When to Use Lookup Tables Vs Locations

When working with hierarchical data in CommCare, users often choose between Lookup Tables and Locations to structure their information. Here’s a breakdown of their differences and best use cases.

Lookup Tables

What They Are:
Lookup Tables (or fixture data) store static reference data in a structured format, such as a list of districts, services, or product inventories.

Key Features:

• Used for dropdown menus in forms (e.g., selecting a village from a district).

• Can be updated via Excel or API.

• Data is not linked to user permissions—any user can access it.

• Supports parent-child relationships (e.g., Country → State → City).

When to Use:
✅ When the data doesn’t change frequently.
✅ When multiple users need access to the same dataset.
✅ When user access restrictions are not required.

Locations

What They Are:
Locations define a hierarchy of geographic or organizational units within a project (e.g., Country → State → District → Facility). They help manage case ownership and user assignments.

Key Features:

• Used to assign users and restrict data access.

• Integrated with mobile worker permissions.

• Users see only data relevant to their assigned location.

• Supports hierarchical relationships similar to lookup tables.

When to Use:
✅ When data needs to be linked to specific users or groups.
✅ When you need to restrict access to location-based data.
✅ When managing case ownership at different geographic or organizational levels.

Key Differences

Which One Should You Use?

• If you need simple reference data without user-based access, go with Lookup Tables.

• If you need to control access to data and assign users based on geography or organization, use Locations.