...
| Excerpt |
|---|
Submit survey responses through other survey tools and an integration platform like Power Automate to automatically trigger submissions to CommCare for creating and/or updating cases! |
This is a powerful feature that allows for self-registration and update workflows on CommCare wherein respondents can directly fill out a survey on any device and once submitted, this will create a case in CommCare which can then be used for case management workflows. The same workflow applies for updating existing case data as well.
The following instructions should be followed for setting up CommCare, external survey tools and Power Automate to enable this workflow.
CommCare Setup
Step 1
Create an application on CommCare with a case management workflow. Be sure to map all case properties in the registration and follow-up forms.
...
Step 2
Submit a form for registration and follow up. Repeat the process for as many forms you need to setup this workflow for. Navigate to the Case List report and look at the Case History section and copy the raw XML of each submission for use later.
...
Survey Tool Setup
Step 1
Create surveys on external survey tools like MS Forms, Google Forms, Jotform or more with the questions that you built within the CommCare app. Please do any necessary due diligence before choosing the survey tool.
Step 2
Ensure that all the fields you need mapped to CommCare are included. In the case of followup forms, ensure that a “case id” question is always included in the survey. Test a few submissions (currently not connected to CommCare) to ensure the data is formatted the way you need it.
Step 3
Save the URL of the form for use later. Different survey tools have different ways to get the form link.
On MS Forms:
...
On Google Forms:
...
On Jotform:
...
Step 4
Create a pre-filled survey link where the case id question can be appended to the URL. We will need this to populate case ids when the link is shared with respondents for updating existing case data on CommCare.
In current testing, this can be achieved on Google Forms and Jotform. There may be other tools that allow appending the survey URL as well. Please feel free to test on your own.
On Google Forms:
...
On Jotform:
...
Step 5
After selecting prefill, fill the case id question with any arbitrary value. Note that we are only using the URL for generating a structured link from CommCare later.
On CommCare, the following approaches can be explored for sending the form links:
For new cases: Share the survey link generated above to respondents either manually (outside of CommCare) or via messaging workflows within CommCare. These could be SMS/emails that contain the survey link which the respondent can navigate to and submit responses.
For updating cases: Use the pre-filled URL and add the case id of the respondents to the end and use the same options above for sharing with the respondents.
See here for setting up messaging workflows on CommCare.
Known Limitations
| Note |
|---|
A known limitation of MS forms is the inability to append case ids to survey links so it cannot be used for any case update workflows. It can be used for case creation workflows. |
| Note |
|---|
A known limitation of Google forms is the inability to hide/hardcode the case id value which means that users can still make changes to it. You are encouraged to use relevant warning messages to ensure the value is not changed. |
| Note |
|---|
Setting up Google Forms integration requires additional steps as Power Automate does not have an existing connector for Google Forms. See Advanced Settings for Google Forms Integration for detailed instructions. |
Power Automate Setup
Step 1
Create an automated flow on Power Automate to capture survey responses and submit them back to CommCare. Note that the flow steps may vary slightly depending on which survey tool is chosen.
Understanding the flow structure:
The first step in any flow is essentially getting survey responses. This may look different for the three tools we have tested depending on the kind of workflow required to get the responses. See below for specifics:
Step 2
Set up the HTTP step using CommCare’s form submission API.
...
Populate the HTTP code. The easiest way to do this is to create a case on CommCare, navigate to the case list report, go to case history and pull up the raw XML file of the submission that created the case or updated the case.
...
Here’s a breakdown of all the sections.
...
In the first section, please choose the following fields
Method: POST
URI: https://www.commcarehq.org/a/{name of project space}/receiver/{APP ID}/
APP ID can be accessed from the URL when the app is being edited. This value is static and should be saved beforehand.
Here’s a breakdown of the code in the Body section of the HTTP operation.
...
Everything remains the same for the metadata (ie. the xmlns and app attributes right up to the form name (line 3).
...
Section 1: The first section in the body after the namespaces contains the individual responses to the form. Replace the values from the pasted XML with the responses listed in Power Automate.
Section 2: Starting at node 0 (<n0:…) will either show case creation or case update blocks. Again, remove the existing values and use the GUID() expression for the ID field and the utcNow() for creating new values. The user_id value remains the same. For case updates, use the case id value from the form submission as well.
Section 3: Starting at node 1 (<n1:…) will be metadata where timeStart, timeEnd and instanceID will require updates.
timeStart: utcNow()
timeEnd: utcNow()
instanceID: guid()
...
| Info |
|---|
See the Form Submission API link for more details on Form Submission APIs in CommCare and XML structure. |
Step 3
Finally, click on Show Advanced options and choose either Basic/API Key for authentication.
For basic authentication choose Basic and add email address/password.
...
For API key authentication, add header key and value like below:
...
Header Key: Authorization
Header Value: ApiKey [email address]:[API key from CommCare]
Ensure that the Authentication type at the bottom is selected as None.
...
Please follow the pages below to learn how to set up your PowerAutomate Integration, as well as information about how to leverage these capabilities with specific tools.
| Child pages (Children Display) | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|