Step 1: Determine which cases to update
To update your cases the first step is to determine which cases to update. To do so you need to use a unique ID so that CommCare can identify your cases. You have two options to do so:
Options to determine which cases to update | Steps to follow |
---|
Option 1: Use the CommCare case export feature to download your cases and update them (https://dimagi.atlassian.net/wiki/x/vCzKfw ). CommCare generates a unique ID for each case and stores it in a property called case_id. | Download your cases and make a case export, making sure you include the case_id column. Remove any cases that you don't want to change Remove any columns that you don't want to change/update Update the data in the columns that you want to change Add new columns for any new case properties you want to change
|
Option 2: If you already imported these cases using a unique ID (Creating New Cases - 1. Setup Excel File), you can use this ID to update the cases. For example, you may have used household number as a unique ID for importing cases. | Include your existing Unique ID column in your Excel document Add columns for other case properties you want to change or add. You do not need to include all columns for the case, just the ones you want to update or add.
|
Two example tables are shown below, one that using a downloaded case ID (option 1) and another that uses an existing Unique ID (option 2).
Option 1: No Existing Unique ID
name | is_pregnant | high_risk | info.case_id |
---|
Amelia Sagoff | no | yes | bcf3df0a-d19e-4701-86de-88f005aa258b |
Andrea Fletcher | yes | no | 4ddba071-7b1e-433d-871b-c6d9c89fc390 |
Jeremy Wacksman | no | no | b09bd9e8-cd9a-4a86-b14d-d0ac99d9a47a |
Sheel Shah | yes | no | 8bb2e7ad-d098-4929-a67f-1d8df22e9be5 |
Option 2: Existing Unique ID (household number)
name | is_pregnant | high_risk | household_number |
---|
Amelia Sagoff | no | yes | AS4398 |
Andrea Fletcher | yes | no | AF3933 |
Jeremy Wacksman | no | no | JW4380 |
Sheel Shah | yes | no | SS6654 |
Note
To update the value of an existing case property to blank/null, make sure to include at least one property in the sheet that is not null.
One way to accomplish this is to have a last column called "name" with a copy of the current cases' names. This will not change the names of the cases – since it should be the same as before – but it will force the upload to recognize and set the null values.
Commcare has the option to update a single case type or multiple case types for example in a single upload case for household and household_member can be updated.
Update A Single Case Type
In order to properly update the cases of a single case type, we recommend that you follow these steps:
Step 1: Setup the import file to update a single case type.
Step 2: Import the file.
Step 3: Map the Case Properties and Complete the Import.
Step 1: Setup the import file to update a single case type
Instead of renaming the tab to one of the cases in your project when updating a single case type, use a generic name such as Sheet_1.
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/image-2023-5-11_10-26-37.png?version=1&modificationDate=1713557311772&cacheVersion=1&api=v2&width=368&height=252)
Step 2: Import the file
You have now created the Excel file to import and decided what unique ID to use to identify your cases. The next steps are to select the file for import and to specify the case type and the Excel column where your case ID is (so that CommCare HQ knows in which column of your Excel file the unique case ID is located).
Step 2a: Select the File to upload
In your project, go to the Data tab and select Import Cases from Excel.
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/Screen%20Shot%202016-11-18%20at%2011.37.18%20AM.png?version=1&modificationDate=1713557311794&cacheVersion=1&api=v2&width=760&height=325)
Select your file and click on >> Next Step. This brings you to a page that looks like this
Step 2b: Determine the case identifier
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/Screen%20Shot%202016-11-18%20at%2011.41.10%20AM.png?version=1&modificationDate=1713557311802&cacheVersion=1&api=v2&width=763&height=459)
If you see a different page chances are that the name of the case was used to name one of the tabs in the Excel file and Commcare will automatically consider this file as an import that updates multiple case types in a single file, to rectify this rename the tab to a name that does not match any of the cases in the project.
On the page above of your project space, you will need to complete two actions 1. Specify the Case Type to Update/Create and 2. Identify the Case by Specifying the Case ID you want to use. We're now going to look at each of these action
First, you choose the case type that you want to update.
![958a07f0-1c4a-4c85-a247-565adf6f5bd0.png](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/958a07f0-1c4a-4c85-a247-565adf6f5bd0.png?version=1&modificationDate=1713557267533&cacheVersion=1&api=v2&width=479&height=110)
The next step is to tell CommCare HQ in which Excel column the unique ID is and what type of unique ID you're using. Follow the table below
IF | THEN |
---|
you're using case_id to update the cases (i.e. you did a case export from CommCareHQ), | choose info.case_id as your Excel column and the Corresponding case field as Case ID (see first screenshot below) |
you're using an existing Unique ID (ex. household number), | choose that column as your Excel column and the Corresponding case field as External ID. (see the second screenshot below) |
Using Case ID (CommCareHQ Export)
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/image2014-2-25%2016:47:34.png?version=1&modificationDate=1713557311809&cacheVersion=1&api=v2&width=550&height=180)
Using existing Unique ID (ex. household number)
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/image2014-2-25%2016:48:7.png?version=1&modificationDate=1713557311817&cacheVersion=1&api=v2&width=550&height=185)
Make sure you don't check "Create new cases if there is no matching case". This will ensure you don't accidentally create new cases if you mistype an ID.
Step 3: Map the Case Properties and Complete the Import
You should now be on a page with the following interface:
![9e87aefe-227c-460f-bdb7-e9ac69b7f41a.png](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/9e87aefe-227c-460f-bdb7-e9ac69b7f41a.png?version=1&modificationDate=1713557125568&cacheVersion=1&api=v2&width=760&height=463)
The next step is to map the columns in your Excel document to case properties that you want to create: you basically want to tell CommCare HQ what name to give to the new case property or match the Excel column header to an existing case property. Understand in which situation you are following the table below and then complete the steps specified
IF | AND | THEN DO THIS |
You're updating existing cases | your application already has case properties | you can choose these for each Excel column. (Note that the tool will only show case properties that have been submitted. If you have not created a case yet, it will not show any case properties). |
You're updating existing cases | your application doesn't have a case property | you can choose to create a new one for the appropriate Excel column. The Auto Fill button will automatically match your Excel headers to the existing case properties' names. |
You are creating new cases | | Map one of the columns to the case property called name, This will ensure that each case has a name. Map the owner_name column to the case property called owner_name. This will assign each case to a user, case-sharing group or location. You will need to check the box for "Create new property". If you are using a location for owner_name, then also go through https://dimagi.atlassian.net/wiki/x/ryXKfw.
|
Choose each Excel column you want to import and the case property you want to create or update. If you want to create a new case property, check "Create new property" and type in the name of the case property.
Once you've mapped all of your Excel columns, click on the Confirm Import button.
NOTE: If you're creating a new case property, following the above steps will only create the case property for the cases. It will not automatically create a case property under case management in the form builder.
Check for details in Recent Uploads
Upon starting an import, you will be returned to the landing page, and a new row will appear at the top of Recent Uploads, letting you view the progress of your import. Upon completion of the import, the following information will appear under details (messages only appear if the # isn't 0):
# rows matched and updated (corresponds to the number of cases updated for the Excel fields that you matched to case properties in the application)
# rows did not match any existing cases and had new cases created for them. If case_id's were used, these were ignored. (if you selected the option to create new cases, this indicates the number of new cases that were created where there were no matching Excel fields/case properties)
# rows matched more than one case at the same time (you may have multiple cases in your system with the same case_id, in which case the system will not update anything as it will not know to which case the new data corresponds)
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/image-2023-5-11_10-34-45.png?version=1&modificationDate=1713557311824&cacheVersion=1&api=v2&width=760&height=60)
The Form IDs and Case IDs download buttons will download a list of the corresponding ids that were created for that particular upload. These can then be used to bulk update cases or forms.
Update Multiple Case Types in a Single Import
Step 1: Setup the import file to update multiple case types
If you are importing multiple case types, format your file so that each tab corresponds to a unique case type. Each tab needs to be renamed to the corresponding CommCare case type so that CommCare can differentiate which case type is being updated.
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/image-2023-5-11_11-4-36.png?version=1&modificationDate=1713557872436&cacheVersion=1&api=v2&width=550&height=402)
Step 2: Select File to Import
You have now created the Excel file to import and decided what unique ID to use to identify your cases. Next steps are 2a. select the file for import and 2b. specify the case type and the Excel column where your case ID is (so that CommCare HQ knows in which column of your Excel file the unique case ID is located).
Step 2a: Upload file
In your project, go to the Data tab and select Import Cases from Excel.
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/image-2023-5-11_10-49-53.png?version=1&modificationDate=1713557872454&cacheVersion=1&api=v2&width=643&height=275)
Step 2b: Determine the identifier
Select your file and click on >> Next Step. This brings you to a page that looks like this
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/screenshot_2b.png?version=1&modificationDate=1713557872461&cacheVersion=1&api=v2&width=643&height=278)
CommCare will detect that there are multiple case types and instead of showing the case types it will show the label “commcare-all-case-types”,
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/screenshot_2b_casetype.png?version=1&modificationDate=1713557872467&cacheVersion=1&api=v2&width=717&height=53)
Step 3: Completing the Import
Then you should be on a page with the following interface, press confirm and the CommCare will show the result of the import.
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/screenshot_3a.png?version=1&modificationDate=1713557872473&cacheVersion=1&api=v2&width=672&height=170)
Once you press confirm, check for details in Recent Uploads
![](https://dimagi.atlassian.net/wiki/download/thumbnails/2143946828/image-2023-5-11_11-12-6.png?version=1&modificationDate=1713557872480&cacheVersion=1&api=v2&width=760&height=189)
Upon starting an import, you will be returned to the landing page, and a new row will appear at the top of Recent Uploads, letting you view the progress of your import. Upon completion of the import, the following information will appear under details (messages only appear if the # isn't 0):
# rows matched and updated (corresponds to the number of cases updated for the Excel fields that you matched to case properties in the application)
# rows did not match any existing cases and had new cases created for them. If case_id's were used, these were ignored. (if you selected the option to create new cases, this indicates the number of new cases that were created where there were no matching Excel fields/case properties)
# rows matched more than one case at the same time (you may have multiple cases in your system with the same case_id, in which case the system will not update anything as it will not know to which case the new data corresponds)