dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #28584
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 981: TEI query docs
------------------------------------------------------------
revno: 981
committer: Lars Helge Øverland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Tue 2014-03-18 17:27:29 +0100
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-03-18 14:57:08 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2014-03-18 16:27:29 +0000
@@ -4130,40 +4130,45 @@
CSV resource representations.</para>
<table frame="all">
<title>Tracked entity instances query parameters</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1" colwidth="1.41*"/>
- <colspec colname="c2" colnum="2" colwidth="1*"/>
- <colspec colname="c3" colnum="3" colwidth="7.42*"/>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1.38*"/>
+ <colspec colname="c3" colnum="2" colwidth="7.25*"/>
<thead>
<row>
<entry>Query parameter</entry>
- <entry>Required</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>query</entry>
- <entry>No</entry>
- <entry>Query string.</entry>
- </row>
- <row>
- <entry>item</entry>
- <entry>No</entry>
- <entry>Query items referring to attributes. Param can be repeated any number of items.
- Filters can be applied to a dimension on the format
+ <entry>Query string. Attribute query parameter can be used to define which attributes to
+ include in the response. If no attributes but a program is defined, the attributes
+ from the program will be used. If no program is defined, all attributes will be
+ used.</entry>
+ </row>
+ <row>
+ <entry>attribute</entry>
+ <entry>Attributes to be included in the response. Can also be used a filter for the
+ query. Param can be repeated any number of times. Filters can be applied to a
+ dimension on the format <attribute-id>:<operator>:<filter>. Filter values are
+ case-insensitive. Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN. Filters
+ can be omitted in order to simply include the attribute in the response without any
+ constraints.</entry>
+ </row>
+ <row>
+ <entry>filter</entry>
+ <entry>Attributes to use as a filter for the query. Param can be repeated any number of
+ times. Filters can be applied to a dimension on the format
<attribute-id>:<operator>:<filter>. Filter values are case-insensitive.
- Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN. Filters can be omitted in
- order to simply include the attribute in the response without any constraints.</entry>
+ Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN.</entry>
</row>
<row>
<entry>ou</entry>
- <entry>Yes</entry>
<entry>Organisation unit idenfiers, separated by ";".</entry>
</row>
<row>
<entry>ouMode</entry>
- <entry>No</entry>
<entry>The mode of selecting organisation units, can be SELECTED | CHILDREN |
DESCENDANTS. Default is SELECTED, which refers to the selected organisation units
only. CHILDREN refers to immediate children in the hierarchy of the specified org
@@ -4172,53 +4177,65 @@
</row>
<row>
<entry>program</entry>
- <entry>No</entry>
<entry>Program identifier. Restricts instances to being enrolled in the given
program.</entry>
</row>
<row>
<entry>trackedEntity</entry>
- <entry>No</entry>
<entry>Tracked entity identifer. Restricts instances to the given tracked instance
type.</entry>
</row>
<row>
<entry>page</entry>
- <entry>No</entry>
<entry>The page number. Default page is 1.</entry>
</row>
<row>
<entry>pageSize</entry>
- <entry>No</entry>
- <entry>The page size. Default size is 50 items per page.</entry>
+ <entry>The page size. Default size is 50 rows per page.</entry>
</row>
</tbody>
</tgroup>
</table>
- <para>Note that you can specify items with filters for constraining the instances to return, or
- items without filters in order to include the attribute in the response without any
- constraints. The following rules apply to the query parameters.</para>
+ <para>Note that you can specify attributes with filters for constraining the instances to
+ 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. The following rules apply to the query parameters.</para>
<itemizedlist>
<listitem>
- <para>Exactly one of the <emphasis role="italic">query</emphasis> and <emphasis
- role="italic">item</emphasis> parameters must be specified in a query (not both).</para>
+ <para>At least one organisation unit must be specified using the <emphasis role="italic"
+ >ou</emphasis> parameter (one or many).</para>
+ </listitem>
+ <listitem>
+ <para>At least one of <emphasis role="italic">query</emphasis> and <emphasis role="italic"
+ >attribute</emphasis> parameters must be specified (one or both).</para>
</listitem>
<listitem>
<para>Only one of the <emphasis role="italic">program</emphasis> and <emphasis role="italic"
- >trackedEntity</emphasis> parameters can be specified in the same query (none or one,
- not both).</para>
+ >trackedEntity</emphasis> parameters can be specified (zero or one).</para>
</listitem>
</itemizedlist>
+ <para>A query in its simplest form which will return all attributes in the response looks like
+ this:</para>
+ <screen>api/trackedEntityInstances.json?query=wakiki&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&attribute=dv3nChNSIxy&attribute=AMpUYgxuCaE</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>
- <screen>api/trackedEntityInstances.json?item=zHXD5Ve1Efw:EQ:A&item=AMpUYgxuCaE&ou=DiszpKrYNg8;yMCshbaVExv</screen>
+ <screen>api/trackedEntityInstances.json?attribute=zHXD5Ve1Efw:EQ:A&attribute=AMpUYgxuCaE&ou=DiszpKrYNg8;yMCshbaVExv</screen>
+ <para>A query for instances where one attribute is included in the response and one attribute us
+ used as a filter can look like this:</para>
+ <screen>api/trackedEntityInstances.json?attribute=zHXD5Ve1Efw:EQ:A&filter=AMpUYgxuCaE:LIKE:Road&ou=DiszpKrYNg8</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?item=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu&ouMode=DESCENDANTS&program=uy2gU8kT1jF</screen>
+ <screen>api/trackedEntityInstances.json?attribute=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu&ouMode=DESCENDANTS&program=uy2gU8kT1jF</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&ou=O6uvpzGd5pu&ouMode=DESCENDANTS&trackedEntity=cyl5vuJ5ETQ</screen>
<para>By default the instances are returned in pages of size 50, to change this you can use the
page and pageSize query parameters like this:</para>
- <screen>api/trackedEntityInstances.json?item=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu&ouMode=DESCENDANTS&page=2&pageSize=3</screen>
+ <screen>api/trackedEntityInstances.json?attribute=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu&ouMode=DESCENDANTS&page=2&pageSize=3</screen>
<para>You can use a range of operators for the filtering:</para>
<table frame="all">
<title>Filter operators</title>
