CommCare is a powerful data collection platform developed by Dimagi. It is an open-source platform, and is primarily best for mobile case management.
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.
- Case management:
- Form and case data in CommCare: https://confluence.dimagi.com/display/commcarepublic/CommCare+Fundamentals+-+Data+in+CommCare
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.
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.
- Go to "Project Settings".
- Click "Data Forwarding".
- "Add a forwarding location" for Cases, Forms, or both.
- Specify JSON, using your OpenFn inbox URL as the target. See the CommCare documentation.
- Create a message-filter trigger like this.
- Set up a
jobrunning 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
- CommCare docs on installing the mobile app: https://confluence.dimagi.com/display/commcarepublic/Install+CommCare+for+Android+Smartphones
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.
to export form contents. This will give you access to all the
labels in the CommCare form that are helpful for designing your
integration and mapping data elements.
As CommCare data is stored in forms and cases, there are two types of UIDs in CommCare:
form id. You can search for a particular case or form submission in CommCare by using the
Find Data by IDfeature 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
In the OpenFn message:
idis the unique identifier for the form submission
case_idis the unique identifier for the case being updated by the form. For example, the
case_idcan be the UID for a person.
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:
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
Ids however, represent actual data that should be mapped.
- When mapping
multiple choicequestions, make sure to consider how the answer choices should map to the source/destination system.
To connect to CommCare you'll need a username, password, host URL, and the "appId".
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:
The raw JSON of your credential (for use in the CLI or when inspecting
state.configuration) is defined in the
Docs in progress!
OpenFn implementations can leverage both the
CommCare adaptors to connect
with the CommCare API.
- MiracleFeet (CommCare-to-Salesforce sync): https://github.com/OpenFn/miracle-feet
- Lwala (CommCare-Salesforce 2-way sync): https://github.com/OpenFn/lwala
- Grassroot Soccer (CommCare-to-Salesforce sync): https://github.com/OpenFn/grassroot-soccer