> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/other/commcare/best-practices.md).

# CommCare Best Practices

Get clean, reliable CommCare exports — tips for date filtering, combining forms and cases, and avoiding data gaps in field program reporting.

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Always set a start date</strong></td><td>CommCare projects can accumulate years of submissions. Use the date picker to limit your export to a relevant window — this keeps runs fast and destinations manageable.</td></tr><tr><td><strong>Use separate entities for forms and cases</strong></td><td>Add both Forms and Cases as separate sources in the same data flow, then use a Join transformation to connect them via case_id. This gives you richer context than either entity alone.</td></tr><tr><td><strong>Create a dedicated API user</strong></td><td>Avoid using a personal CommCare account for API access. Ask your project admin to create a dedicated API user with the minimum permissions needed — this prevents disruption if someone's account changes.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Account for offline sync delays</strong></td><td>Mobile workers in low-connectivity areas may submit forms hours or days after collection. Set your scheduled refresh to run daily rather than hourly, and use a start date that overlaps your previous export window to catch late-arriving submissions.</td></tr><tr><td><strong>Refresh cases more frequently than forms</strong></td><td>Case status changes (open, closed, reassigned) happen continuously. If you're tracking active caseloads, refresh the Cases entity more often than Forms to keep your dashboards current.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Narrow date ranges for high-volume projects</strong></td><td>Projects with thousands of daily submissions can slow down or time out if you try to pull too much at once. Split large historical pulls into monthly chunks using the Append transformation to combine them afterward.</td></tr><tr><td><strong>Filter test submissions at the destination</strong></td><td>CommCare's API includes submissions from test users. Add a filter in Google Sheets or BigQuery to exclude rows where the username matches known test accounts — otherwise they'll skew your program metrics.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Do not use your personal CommCare login for the API connection. If your password changes or your account is deactivated, all connected data flows will break immediately.
{% endhint %}

{% columns %}
{% column %}

### Do

* Set a start date on every data flow — especially for mature projects
* Join Forms and Cases to build complete program records
* Use Append to combine data from multiple CommCare project spaces
* Account for UTC timestamps when building date-based reports
  {% endcolumn %}

{% column %}

### Don't

* Pull all historical data on every run — it's slow and wasteful
* Assume column names are consistent across different CommCare apps
* Treat form submission counts as a proxy for case counts — they're different things
* Ignore offline sync delays when comparing daily submission numbers
  {% endcolumn %}
  {% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/other/commcare/best-practices.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.