Skip to main content

CommCare

App Overview​

CommCare is a powerful data collection platform developed by Dimagi. It is an open-source platform, and is primarily best for mobile case management.

Data Model​

CommCare data is primarily stored in forms and cases. Forms are the building blocks of applications and cases are used to track data on objects, usually people. Learn more about CommCare forms and cases at the links below.

Integration Use Cases​

Example user stories:

  • As a community health worker I want to store patient data that was collected in rural areas with no internet access in Salesforce so I can better analyze the data being collected and make more informed recommendations.
  • As a teacher I want to set up automatic message alerts to my students in order to increase participation.

APIs & Integration Options​

CommCare offers a number of integration options for extracting and/or loading data to and from CommCare HQ.

Web API​

CommCare has different APIs for reading vs. updating data. Some helpful links:

Webhook: Forward cases and/or forms from CommCare to OpenFn using REST service​

See CommCare docs on how to configure this webhook to "push" data to an external system like OpenFn. This option is great for real-time data forwarding.

Quick instructions:

  1. Go to "Project Settings".
  2. Click "Data Forwarding".
  3. "Add a forwarding location" for Cases, Forms, or both.
  4. Specify JSON, using your OpenFn inbox URL as the target. See the CommCare documentation.
  5. Create a message-filter trigger like this.
  6. Set up a job running on that filter to process CommCare submissions or case updates.

We recommend updating the Connection Settings to list emails that should be alerted if there is a data forwarding error. See the CommCare docs for more on this..

App Setup & Integration Tips​

App installation and configuration​

App Versioning​

Ensure that you are always using the latest app version when testing, by updating your app and checking that the version matches the latest version in CommCare HQ.

Exporting Metadata​

Use this link to export form contents. This will give you access to all the question ids and labels in the CommCare form that are helpful for designing your integration and mapping data elements.

Unique Identifiers​

  • As CommCare data is stored in forms and cases, there are two types of UIDs in CommCare: case_id & form id. You can search for a particular case or form submission in CommCare by using the Find Data by ID feature here: https://confluence.dimagi.com/display/commcarepublic/Find+Data+by+ID. For example, if you received a submission in the OpenFn inbox that you would like to find in CommCare, search by form id. If you'd like to find a particular case (i.e. person, event, etc) search by case id.
    image

  • In the OpenFn message: id is the unique identifier for the form submission image

  • case_id is the unique identifier for the case being updated by the form. For example, the case_id can be the UID for a person. image

N.B. Unique identifiers and hidden fields in CommCare forms: Make sure that unique identifiers for forms and objects are always in the form. If the unique identifier isn't relevant for the user, it can be added to the form as a hidden field. Learn more about hidden fields here: https://confluence.dimagi.com/display/commcarepublic/Hidden+Value+Calculations+Tutorial

Data Element Mapping Notes​

Labels are generally not mapped in an integration because they represent text that is displayed to the CommCare user to facilitate easy use of the application. Ids however, represent actual data that should be mapped.

  • When mapping multiple choice questions, make sure to consider how the answer choices should map to the source/destination system.

CommCare Credentials​

To connect to CommCare you'll need a username, password, host URL, and the "appId".

CommCare Credentials Menu

The username is your full email address and the "appId" is the UUID which designates your CommCare project as different from everyone elses. It can be found in the URL of your application when you first enter it from the project screen. I.e., the last part of this URL: https://www.commcarehq.org/a/YOUR_PROJECT/apps/view/YOUR_APP_ID/

CommCare Cred

The raw JSON of your credential (for use in the CLI or when inspecting state.configuration) is defined in the CommCare Configuration section.

Common Errors​

Docs in progress!

OpenFn Adaptors​

OpenFn implementations can leverage both the HTTP and CommCare adaptors to connect with the CommCare API.

Implementation Examples​