Advanced Case Actions
Advanced Case Actions allow app builders to perform advanced case operations — such as creating, updating, closing, or linking cases — directly within a form, without requiring standard case management setup.
Most concretely, advanced case actions allows you to make changes to cases that are not currently open in the form. This gives you much more flexibility when designing applications, especially in complex workflows or survey-style forms that don’t rely on case lists.
Why use Advanced Case Actions?
Standard Case Management ties each form to a single case — the case loaded from the module's case list, of the module's configured case type. That's the right tool for most workflows, but it's restrictive when you need any of the following:
Act on a case of a different case type than the module's case list. For example, a Visit form inside a Patient module that needs to register a new Visit case (and link it to the Patient) while also updating the Patient. Standard case management can only touch cases of the module's configured case type.
Use case management inside a Survey form. Survey forms have no case list, so standard case management isn't available at all. Advanced Case Actions is the only way to create or update cases from a Survey form.
Manipulate cases inside a repeat group. For example, registering one new case per row of a repeat group. Standard case management can only act on a single loaded case.
Update a case whose ID is computed at form-fill time rather than loaded from the case list — for example, a case looked up via a fixture or a lookup table.
Change relationships between existing cases
Change a case's case type by updating the case_type property on an existing case.
Because Advanced Case Actions is configured inside the form, it has no effect on case loading or case list/detail configuration.
Advanced Case Actions lets a form create, update, close, or link cases without following the typical Case Management workflow.
What you can do with an Advanced Case Actions question
A single Advanced Case Actions question can perform one or more of the following on one case:
Create a new case of any case type
Update an existing case's properties
Close an existing case
Link / Unlink the case to or from a parent or host case
To act on more than one case type in the same form, add one Advanced Case Actions question per case type.
Note: you cannot use Create and Update actions together in the same question.
Using the Advanced Case Actions
Advanced Case Actions is located in the Advanced questions submenu. Unlike a regular question, an Advanced Case Actions question is not shown to the mobile worker — instead, it runs when the form is submitted and writes the configured case transactions to CommCare.
When you select an Advanced Case Actions question, the configuration panel shows a set of shared fields at the top.
The Case Actions field allows you to select all actions you want to perform in this question. You must select at least one action.
Note: Create and Update are mutually exclusive on a single Advanced Case Actions question. To create a new case and update its parent in the same form, add two Advanced Case Actions questions.
Case Type is a dual mode field. By default you should use the dropdown menu to select from an existing case type or create a new case type. For advanced workflows, you can click on the “select case type with XPath” toggle, which will turn the dropdown into an XPath input field that allows you to drag and drop a question to it.
Note: commcare-user cases can only be updated — they cannot be created, closed, or linked.
Case ID sets the ID for a case yet to be created or identifies an existing case (for update/close/link actions). It is required and must be an XPath expression, hardcoding a Case ID like 7148a26f-49a0-40fc-fake-1bdcfca9434b is not supported. Generating a new case ID is typically done by calling uuid(). For any other actions, it must reference an existing case.
Date Modified and User ID are two advanced fields, in most cases, you can leave it as it is.
Date Modified sets the date/time of the case transaction. It will be auto populated with its default value
/data/meta/timeEnd, indicating the time that the form is submitted.User ID stores the ID of the user who created or updated the case. It will be auto populated with its default value
instance('commcaresession')/session/context/userid, indicating the current logged-in mobile worker.
Actions
Create Action
Open Case Condition (optional) — a boolean expression that determines whether the case is actually opened. Leaving this blank means the case will always be opened.
Case Name (required) — the display name for the new case.
Owner ID (optional) — the user or location ID that should own the case. Leave it blank to use the id in User ID field.
Owner ID Condition (optional) — a boolean expression that determines whether the Owner ID is applied.
Case Properties To Create — a list of additional case properties to set on the new case. Add as many property cards as you need. Setting up case properties for an Advanced Case Actions question involves working with three fields per property card:
Property Name — the name for the case property, following CommCare naming rules (must start with a letter, and contain only letters, numbers, -, and _).
Calculation — defines how the value for the property is computed.
Condition — determines whether the property should be updated. It expects a boolean expression. Leaving this blank means the property is always saved.
You will also need to set the shared Case Type field in the top section.
Tip: In previous versions of Advanced Case Actions, properties on Create actions had to be added through the Update section. With the new UI, all properties to be set when creating a case go directly into Case Properties To Create. The Update action is no longer used for this purpose.
Update Action
To update an existing case:
Set the ID of the case you want to update in the top section’s Case ID field. For example it can be determined dynamically by a look up table.
Enable the Update chip.
Add at least one card to Case Properties To Update, defining the properties to change.
The property card structure is identical to the one used for case creation.
Close Action
To close an existing case:
Set the ID of the case you want to update in the top section’s Case ID field. For example it can be determined dynamically by a look up table.
Enable the Close chip.
The closure can be made conditional by entering a boolean expression in the Close Condition field; leaving this blank means the case is always closed when the form is submitted.
Link / Unlink Action
Linking a case means attaching it to another case as a child or an extension. For this to work, the parent or host case ID must be known.
Enable the Link / Unlink chip and add at least one Relationship card. Each card has:
Relationship Name (required) — the name of the relationship (for example, mother).
Relationship Type (required) — either child or extension. (If the current case is linked as a child case, then the other case you linked to is a parent case. If the current case is linked as an extension case, then the other case you linked to is a host case.)
Parent / Host Case ID (optional) — an XPath expression that resolves to the linked case's ID. To unlink an existing relationship, leave this blank or set it to an empty string.
Parent / Host Case Type (optional) — the case type of the linked case