Automatically Update Cases

Overview

This feature allows users with Edit Data access (see CommCareHQ Web Users) to configure updates to cases, including the ability to close cases. Without this feature, the only ways to close cases are by filling out a form that closes a case, finding the case in the Case List and manually using the Close Case button, or by using the Case Importer tool.

Note that automatic update rules will only trigger on cases that are currently open. If a case has already been closed, it will not be updated by a rule, even if it otherwise matches the filter criteria.

When should you automatically update cases?

Here are some examples of when this is useful:

• Automatically closing and removing stale cases from users' phones

• Regularly closing cases that have a specified combination of case properties (for example, a case updated by two apps where both users' protocols are completed)

Cases are closed by creating rules. 

The basic process of defining a rule is:

1. Define all of the criteria for the cases you want to match. 

2. Choose all of the actions to apply to the cases that match the criteria.

Rule List

Navigate to Data →  Automatically Updates Cases, you will see a list of all rules for the project along with the name, case type, status, and last time the rule has run to completion.

Open

If "Last Run" is not updated, it means that the rule has not yet run or did not run to completion on its last run. The completion could not have succeeded due to exceeding the maximum number of automatic updates per day (up to 50,000), due to exceeding the max run time (24 hours), or that there was an error during the run.

Open

Rules

Creating a New Rule

For example, imagine that you want to close any "Patient" cases which have not been updated in a year. You want to do this to reduce the caseload on the users' phones and to keep the reports accurate.

You can create a rule by navigating to Data → Automatically Update Cases → + Add Automatic Case Update Rule button: 

Fill out the basic information by giving the rule a name you can use to remember what it's for:

Choose the "Case Type" and "Run when". "ALL of the criteria are met" works when you want to apply all your filter criteria. "ANY of the criteria are met" works only when you want ANY of the filter criteria to apply in the Auto Update Cases. 

Next, add your filter criteria which define the cases that the rule will apply to. Notice that the wording "AND" "OR" next to the rule filter changes with the button. 
When selecting the Case Property filter, a data list will be displayed as you begin typing. This will search the applications Data Dictionary, and allow you to select the relevant Case Property.

1. Notes:

   1. Projects without the Data Dictionary flag will see a plain text field instead of a data list.

   2. The field will also accept free text if the Data Dictionary is out-of-date.

   3. The data list only retrieves project-defined case properties, from the Data Dictionary. The list will not contain System Properties, but this will be added at a future date.
      
      
      

And lastly, specify the actions that will be applied to the cases that match these criteria. These actions say to close the case and update case property "close_reason", setting it to the value "automatic" and save.

Case Filter Criteria

The following filter criteria are available for matching cases:

• Case Type - is always a required part of the criteria. Select the case type of the cases you want to update or close, and if you want to match more than one case type, you will need to create a rule for each case type.

• Case Not Modified Since - specify the number of days elapsed since the date the case was last modified. This last modified date is based on the time the last form to update the case was received (server time).

• Case Property - this filter allows you to match case property equality, inequality, or that a case property has a value.

• Date Case Property - this filter allows you to match when the current date comes after or before a date in a case property.

• Date Case Property (advanced) - this filter is similar to the Date Case Property filter, only it lets you add or subtract an offset to the value in the date case property before comparing to the current date. This filter could also be set up to be logically identical to the Case Not Modified Since filter by configuring it to 'when the current date is greater than the date in the case property modified_on plus X days', where modified_on corresponds to the case metadata property last_modified. However, for this purpose, Case Not Modified Since is advised instead for the sake of simplicity.

• Parent Case is Closed - this filter lets you match cases whose parent case is closed. 

NB: It is possible to reference parent/master case properties in any of the case property filters. The syntax follows the convention of "parent/<case_property>" or "host/<case_property>". Possible use case: Close the growth monitoring case when the parent (i.e., person case) turns 6.5 years old. 

Actions

The following actions can be performed on cases that match the filter criteria:

• Close the case - all cases that match the filter criteria will be closed when this action is chosen.

• Update case property - you can choose to update a case property with or without closing the case. If you are closing the case, this may be useful to specify why the case was closed for future data analysis. If you choose to update a case property, you also can set it to either an exact value or set it to the value from another case property. It is also possible to reference parent/master case properties in any of the actions. the syntax follows the convention of "parent/<case_property>" or "host/<case_property>".

Running a Rule

Rules run automatically every day at Midnight GMT. You cannot choose when a rule is run.

Managing Rules

You can update, delete, or deactivate a rule at any time from the list of rules.

Case References

In addition to the dynamic case properties created by your app(s), you can reference the following case properties in automatic update rule criteria:

Parent cases may also be referenced in the automatic update rule criteria by prefixing the property name with "parent/". So, for example, parent/name references the parent case's name.

Reporting and Case Actions

The case close action shows up in the case history as a form submission. You can view the form that closed the case by looking in the Submit History report or the Manage Forms tool. The form will also show up in the Case History of any cases closed by a rule. In the case history for the form name will show up as "Automatic Case Update Rule" and indicate which rule was executed as displayed below:

It is important to note that Automatic Case Update Rules may have duplicate names. For this reason, you should verify the rule that was executed by the system, via the Submit History page. Also, if a rule name is edited, the case history tab will display the name of the rule at the time it was executed, and not the updated rule name. 
This behaviour may be changed in the future.

Reversing a Rule

If a rule ran and closed cases and you want to undo that action, you should go to Manage Forms or Submit History report, locate the form submission that closed the cases, and archive it. This will restore the case to its prior status. For more information on archiving forms, please see Archive Forms.

To find the forms, you will want to use the following filters:

You can add the filter options in the following order:

1. Choose [admin], [Web Users] and [Unknown Users]

2. For application: select "Show all forms of this Application Type..."

3. Run the search, and the case update rule form will be listed as "http://commcarehq.org/hq_case_update_rule"