dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 1018
committer: Lars Helge Øverland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Tue 2014-04-08 17:26:54 +0200
message:
  TEI query docs
modified:
  src/docbkx/en/dhis2_user_man_web_api.xml


--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs

Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription

=== modified file 'src/docbkx/en/dhis2_user_man_web_api.xml'
--- src/docbkx/en/dhis2_user_man_web_api.xml	2014-04-08 09:24:10 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml	2014-04-08 15:26:54 +0000
@@ -4137,8 +4137,12 @@
   </section>
   <section>
     <title>Tracked entity instance query</title>
-    <para>To query for tracked entity instances you can interact with the <emphasis role="italic">/api/trackedEntityInstances</emphasis>
-      resource.</para>
+    <para>To query for tracked entity instances you can interact with the <emphasis role="italic"
+        >/api/trackedEntityInstances</emphasis> resource. There are two types of queries: One where
+      a <emphasis role="italic">query</emphasis> query parameter and optionally <emphasis
+        role="italic">attribute</emphasis> parameters are defined, and one where <emphasis
+        role="italic">attribute</emphasis> and <emphasis role="italic">filter</emphasis> parameters
+      are defined.</para>
     <section>
     <title>Request syntax</title>
     <table frame="all">
@@ -4229,11 +4233,23 @@
       return, or attributes without filters in order to include the attribute in the response
       without any constraints. Attributes will be included in the response, while filters will only
       be used as criteria. </para>
-    <para>If specifying a query with no attributes or program, the attributes defined to be
-        displayed in lists with no program will be included in the response. You can specify queries
-        with words separated by space - in that situation the system will query for each word
-        independently and return records where each word is contained in any attribute. The query is
-        case insensitive. The following rules apply to the query parameters.</para>
+      <para>Certain rules apply to which attributes are defined when no attributes are specified in
+        the request:</para>
+      <itemizedlist>
+        <listitem>
+          <para>If not specifying a program, the attributes defined to be displayed in lists with no
+            program will be included in the response.</para>
+        </listitem>
+        <listitem>
+          <para>If specifying a program, the attributes linked to the program will be included in
+            the response.</para>
+        </listitem>
+      </itemizedlist>
+    <para>You can specify queries with words separated by space - in that situation the system will
+        query for each word independently and return records where each word is contained in any
+        attribute. A query item can be specified once as an attribute and once as a filter if
+        needed. The query is case insensitive. The following rules apply to the query
+        parameters.</para>
     <itemizedlist>
       <listitem>
         <para>At least one organisation unit must be specified using the <emphasis role="italic"
@@ -4249,10 +4265,13 @@
               role="italic">program</emphasis> must also be specified.</para>
         </listitem>
         <listitem>
-          <para>Attributes and filters can only be specified once.</para>
-        </listitem>
-        <listitem>
-          <para>An item cannot be specified as attribute and filter.</para>
+          <para>A query cannot be specified together with filters.</para>
+        </listitem>
+        <listitem>
+          <para>Attribute items can only be specified once.</para>
+        </listitem>
+        <listitem>
+          <para>Filter items can only be specified once.</para>
         </listitem>
     </itemizedlist>
     <para>A query for all instances associated with a specific organisation unit can look like
@@ -4262,10 +4281,10 @@
     <screen>api/trackedEntityInstances.json?query=scott&amp;ou=DiszpKrYNg8</screen>
       <para>You can query on multiple words separated by the the URL character for space which is
         %20:</para>
-      <screen>api/trackedEntityInstances.json?query=isabel%20may&amp;ou=ImspTQPwCqd</screen>
+      <screen>api/trackedEntityInstances.json?query=isabel%20may&amp;ou=DiszpKrYNg8</screen>
     <para>A query where the attributes to include in th response are specified looks like
       this:</para>
-    <screen>api/trackedEntityInstances.json?query=wakiki&amp;attribute=dv3nChNSIxy&amp;attribute=AMpUYgxuCaE&amp;ou=DiszpKrYNg8</screen>
+    <screen>api/trackedEntityInstances.json?query=isabel&amp;attribute=dv3nChNSIxy&amp;attribute=AMpUYgxuCaE&amp;ou=DiszpKrYNg8</screen>
     <para>To query for instances using one attribute with a filter and one attribute without a
       filter, with one organisation unit using the descendants organisation unit query mode, you can
       issue a query like this:</para>
@@ -4278,9 +4297,9 @@
       <screen>api/trackedEntityInstances.json?ou=DiszpKrYNg8&amp;attribute=dv3nChNSIxy:IN:Scott;Jimmy;Santiago</screen>
     <para>To constrain the response to instances which are part of a specific program you can
       include a program query parameter like this:</para>
-    <screen>api/trackedEntityInstances.json?attribute=zHXD5Ve1Efw:EQ:A&amp;ou=O6uvpzGd5pu&amp;ouMode=DESCENDANTS&amp;program=ur1Edk5Oe2n</screen>
+    <screen>api/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&amp;ou=O6uvpzGd5pu&amp;ouMode=DESCENDANTS&amp;program=ur1Edk5Oe2n</screen>
       <para>To specify program enrollment dates as part of the query you can use this syntax:</para>
-      <screen>api/trackedEntityInstances.json?attribute=zHXD5Ve1Efw:EQ:A&amp;ou=O6uvpzGd5pu&amp;ouMode=DESCENDANTS&amp;program=ur1Edk5Oe2n&amp;programDate=GT:2013-01-01&amp;programDate=LT:2013-09-01</screen>
+      <screen>api/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&amp;ou=O6uvpzGd5pu&amp;ouMode=DESCENDANTS&amp;program=ur1Edk5Oe2n&amp;programDate=GT:2013-01-01&amp;programDate=LT:2013-09-01</screen>
     <para>To constrain the response to instances of a specific tracked entity you can include a
       tracked entity query parameter like this:</para>
     <screen>api/trackedEntityInstances.json?attribute=zHXD5Ve1Efw:EQ:A&amp;ou=O6uvpzGd5pu&amp;ouMode=DESCENDANTS&amp;trackedEntity=cyl5vuJ5ETQ</screen>