Best Practices

Recommended setup

Always set a start date

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.

Use separate entities for forms and cases

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.

Create a dedicated API user

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.

Data refresh and scheduling

Account for offline sync delays

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.

Refresh cases more frequently than forms

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.

Performance optimization

Narrow date ranges for high-volume projects

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.

Filter test submissions at the destination

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.

Common pitfalls

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.

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

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