Virtual Data Instances

There are certain data instances that CommCare makes available in the CommCare Session based on the user input in the session. These dynamic instances are referred as "Virtual" data instances inside CommCare. The primary use case of these virtual instances is to allow complex, structured user input from session steps available in a structured form that can be queried through Xpath expressions later in the session.

Types of Virtual Instances

CommCare currently supports 2 distinct types of virtual instances -

1. Selected Entities Instance
2. Search Input Instance

Selected Entities Instance

This virtual instance represents the entities selected on a entity list screen backed by a instance-datum that allows the user to select multiple entities at once into the session.

This instance has following xml structure -

<results id="selected_cases">
    <value>SADF2343223I4IU43A0C0305E82C3301</value>
    <value>3F2504E04F8911D39A0C0305E82C3301</value>
</results>

and with the corresponsding instance connector defined as - <instance id="selected_cases" src="jr://instance/selected-entities"/>

The value nodes above represents the selected entities on the entity list screen and @id is the id of instance-datum that the multi-select entity list screen represents.

When user makes a selection on a multi-select entity list screen, CommCare represents this selection in the form of selected-entities instance. This instance is then stored in memory along with the stack frame step that supplies the value for the instance-datum in the session (represented as SessionFrame.STATE_MULTIPLE_DATUM_VAL in the stack frame). Therefore the lifecycle of the instance is tied to the lifecycle of the corresponding step in the stack frame and it's accessible as long as the stack frame step is there in the session.

Search Input Instance

This instance represents the search data entered by user on the case search screen and has following xml structure -

<input id="search-input">
	<field name="key0">val0</field>
	<field name="key1">val1</field>
	<field name="key2">val2</field>
</input>

The instance connector for this instance is defined as - <instance id="search-input" src="jr://instance/search-input"/>

The field nodes here represent user input for every query datum prompt on the case search screen with @name corresponding to the query prompts key attributes.

CommCare forms this instance as soon as user gets to any case search screen in the session. As soon as user inputs any of the case search fields, CommCare updates the corresponding field value in the search input instance making this instance useful in cases when you want to calculate a search input field based on the value of some other search input. For eg. you can filter the list of cities based on the value entered for the state field by making use if this instance in a Xpath query.

Similar to Selected Entities instance, this instance is coupled with the stack frame step satisfying the value for the "query datum" in the session and is available as long as the corresponding query datum step is part of the session.