> 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).

# Best Practices

## 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.