Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

 

I am a...

referencing my...

syntax in forms

outlet

own location's name

 instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/name

outletown location's type instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@type
outletown location's site code instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/site_code
outletown location's custom data instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/location_data/custom_field_id

outlet

parent block's id

 instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@block_id

outletparent block's nameinstance('locations')/locations/location[@id =  instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@block_id]/name
outletparent block's nameinstance('locations')/locations/location[@id =  instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@block_id]/site_code

outlet

parent district's id

instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@district_id

outletparent district's nameinstance('locations')/locations/location[@id =  instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@district_id]/name
blockparent district's idinstance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@district_id
blockparent district's nameinstance('locations')/locations/location[@id =  instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@district_id]/name

district

parent state's id

instance('locations')/locations/location[@id = instance('commcaresession')/session/user/data/commcare_location_id]/@state_id

Accessing the location additional information (Location Fields)

Once you have the location's ID you can access it to get other information.

These examples assume your ID is stored in a hidden value called location_id

Referencing...syntax in forms
The gps of the location

instance('locations')/locations/location[@id = /data/location_id]/latitude

instance('locations')/locations/location[@id = /data/location_id]/longitude

Any custom location fields you may have (ex. admin name)instance('locations')/locations/location[@id = /data/location_id]/location_data/admin_name

Making select questions with locations as choices

You can use the location hierarchy to make select questions that allow you to choose a location in a form. The process is similar to setting up Multiple Choice Questions with Cases as Choices.

  1. Go to Application Settings to turn on the Custom Single and Multiple Answer Add-On in the "Calculations" section.
  2. Add a new "multiple choice lookup table" question
  3. In the "lookup table data" choose the 3 dots next to the list of lookup tables

  4. Set the query to: instance('locations')/locations/location[@type = 'TYPE OF LOCATION']  NOTE:  "type of location" is given for each organization level by the "type code." You can see the type code when you click on "Advanced Mode" on the Organization Levels page. 
  5. Set the instance ID to locations

  6. Set the instance URI to jr://fixture/locations
  7. Hit save
  8. Set the value to "@id" and the label to "name"

Tiered Location Selection

You can also add tiered selection (e.g. select state, then district, then block) by adding multiple select questions after each other as described above.  Assuming the example of districts and block:

  1. Setup the district list as described above  (this example assumes the question_id is district)
  2. Add a second multiple choice question, and configure it to display a list of blocks
    1. In the filter section, add a filter with the following: @district_id = /data/district 

Example location fixture structure

Code Block
languagexml
titleExample locations fixture
collapsetrue
<fixture id="locations" indexed="true" user_id="b43e50ca1c3174fe0bbcf36cfd93a1eb">
  <locations>

    <location id="999dc78d9ca84ea8749dc75b44542332"
              type="country"
              country_id="999dc78d9ca84ea8749dc75b44542332"
              state_id=""
              county_id=""
              city_id="">
      <name>USA</name>
      <site_code>usa</site_code>
      <external_id/>
      <latitude/>
      <longitude/>
      <location_type>country</location_type>
      <supply_point_id/>
      <location_data>
        <name-en>USA</name-en>
        <name-es>USA</name-es>
        <is_test/>
      </location_data>
    </location>

    <location id="999dc78d9ca84ea8749dc75b44541bdc"
              type="state"
              country_id="999dc78d9ca84ea8749dc75b44542332"
              state_id="999dc78d9ca84ea8749dc75b44541bdc"
              county_id=""
              city_id="">
      <name>Massachusetts</name>
      <site_code>massachusetts</site_code>
      <external_id/>
      <latitude/>
      <longitude/>
      <location_type>state</location_type>
      <supply_point_id/>
      <location_data>
        <is_test/>
      </location_data>
    </location>

    <location id="999dc78d9ca84ea8749dc75b44540257"
              type="county"
              country_id="999dc78d9ca84ea8749dc75b44542332"
              state_id="999dc78d9ca84ea8749dc75b44541bdc"
              county_id="999dc78d9ca84ea8749dc75b44540257"
              city_id="">
      <name>Middlesex</name>
      <site_code>middlesex</site_code>
      <external_id/>
      <latitude/>
      <longitude/>
      <location_type>county</location_type>
      <supply_point_id/>
      <location_data>
        <name-en>Middlesex</name-en>
        <name-es>Middlesex</name-es>
        <is_test/>
      </location_data>
    </location>

    <location id="999dc78d9ca84ea8749dc75b4453ff5b"
              type="city"
              country_id="999dc78d9ca84ea8749dc75b44542332"
              state_id="999dc78d9ca84ea8749dc75b44541bdc"
              county_id="999dc78d9ca84ea8749dc75b44540257"
              city_id="999dc78d9ca84ea8749dc75b4453ff5b">
      <name>Cambridge</name>
      <site_code>cambridge</site_code>
      <external_id/>
      <latitude/>
      <longitude/>
      <location_type>city</location_type>
      <supply_point_id/>
      <location_data>
        <is_test/>
      </location_data>
    </location>

  </locations>
</fixture>

Syncing more of location hierarchy to users

By default, CommCare will only send each user the list of their assigned locations and those location's ancestors and descendants.  For example, if I'm assigned to a block,  I will get a list of my state, my district, my block and all that blocks outlets.  

In some situations, you may want to get a list of locations outside of the ancestors and descendants.  In the example above, if a user is assigned to a block, they may want to see all districts in that state anyway. This is controlled using the "Expand From" options outlined on the Advanced Organization Level Configuration page

...