fixtures

Fixture External Instance Definition

The Fixture External Instance defines an artificial instance interface for XForms in CommCare to access fixtures.

Fixture Instance Structure

Fixtures are inherently self-structured XML documents. The root element of a fixture's instance is simply the root element of the defined document

Fixture URI's

The following URI's can be used to reference fixtures.

jr://fixture/FIXTUREID

Creates an instance which references the fixture defined by FIXTUREID. Fixtures may be defined both for a particular user on a device as well as globally, in which case the current session's userid value is used to index the appropriate fixture.

Providing Fixtures to a CommCare Application

Fixtures can be loaded onto the phone in one of two ways. Either the fixture will be included as part of a Structured OpenRosa Response payload, or it can be included in the suite file declaration for an application for fixtures which are not user specific.

Fixture declarations contain a unique ID for a fixture as well as an optional id for a specific user which the fixture is assigned to. CommCare will maintain one fixture per ID/User, and if another with the same id and user_id is provided (during a restore for instance) it will overwrite the current fixture all-at-once (not incrementally).

The fixture declaration XML is

<fixture id="" user_id="">                  <!-- id is the unique id for this fixture. user_id is optional -->
    <*>                                     <!-- Exactly One: The root node of the fixture. treated as the root node of an independent XML document -->
      ....                                  <!-- The rest of the fixture structure is an arbitrary XML doc -->
    </*>
</fixture>

Fixture Schemas

Optional for Implementations

Since: CommCare 2.33

Some fixtures have a highly homogenous data set defined for which CommCare platforms can provide optimizations on high volume lookups, like indexing an ID attribute into a database.

A CommCare Platform may or may not choose to implement any optimizations. Behavior should be identical if not, but may be less performant.

To define an "indexed fixture", the app should provide two changes to the default definition. First is a <schema> definition to define what elements should be indexed. The second is a directive on the fixture declaration specifying that it should be indexed.

An example is provided here:

	<schema id="id_goes_here">
		<indices>
			<index>CHILD_ELEMENT_REFERENCE_ONE</index>
			<index>@CHILD_ELEMENT_ATTRIBUTE_REFERENCE</index>
		</indices>
	</schema>
       <fixture id="id_goes_here" indexed="true">
           <root_element_name>
               <child_element_name attribute="">
                    <!-- BODY -->
               </child_element_name>
               <child_element_name attribute="">
                    <!-- BODY -->
               </child_element_name>
               <!--....-->
         </root_element_name>
       </fixture>

of note

• The block @id and block @id must match.
• There should only be one schema block per fixture
• The schema should come before the fixture declaration in the document order
• The fixture should contain between 1 and N homogenous blocks inside of its root element.
• The blocks can have an arbitrary number of sub-elements, but only the children of the "child" (in the example child_element_name), including its attributes, can be included as schema indexes.