dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #24974
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 816: Event analytics
------------------------------------------------------------
revno: 816
committer: Lars Helge Øverland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Sat 2013-09-28 18:32:42 +0200
message:
Event analytics
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 2013-09-28 14:03:02 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2013-09-28 16:32:42 +0000
@@ -2110,19 +2110,63 @@
<para>In order to query <emphasis role="italic">events</emphasis> captured in DHIS 2 you can
work with the <emphasis role="italic">analytics/events/query</emphasis> resource. This
resource lets you retrieve events based on a program and optionally a program stage, and lets
- you retrieve and filter events on any event item. Event items include data elements, person
- attributes and person identifiers. The query analytics resource will simply return events
- matching a set of criteria and does not perform any aggregation.</para>
+ you retrieve and filter events on any event dimensions. Event items include data elements,
+ person attributes, person identifiers, organisation units and periods. The query analytics
+ resource will simply return events matching a set of criteria and does not perform any
+ aggregation. The event dimensions are listed in the table below.</para>
+ <table frame="all">
+ <title>Event dimensions</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1" colwidth="2.49*"/>
+ <colspec colname="c2" colnum="2" colwidth="1*"/>
+ <colspec colname="c3" colnum="3" colwidth="5.42*"/>
+ <thead>
+ <row>
+ <entry>Dimension</entry>
+ <entry>Dimension id</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Data elements</entry>
+ <entry><uid></entry>
+ <entry>Data element identifiers</entry>
+ </row>
+ <row>
+ <entry>Person attributes</entry>
+ <entry><uid>, GENDER, ISDEAD</entry>
+ <entry>Person attribute identifiers and the fixed person attributes GENDER and
+ ISDEAD</entry>
+ </row>
+ <row>
+ <entry>Person identifiers</entry>
+ <entry><uid></entry>
+ <entry>Person identifier identifiers</entry>
+ </row>
+ <row>
+ <entry>Organisation units</entry>
+ <entry>ou</entry>
+ <entry>Organisation unit identifiers</entry>
+ </row>
+ <row>
+ <entry>Periods</entry>
+ <entry>pe</entry>
+ <entry>ISO periods and relative periods, see "date and period format"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<section>
<title>Request query parameters</title>
<para>The analytics event API let you specify a range of query parameters.</para>
<table frame="all">
<title>Query parameters</title>
<tgroup cols="4">
- <colspec colname="c1" colnum="1" colwidth="1.82*"/>
+ <colspec colname="c1" colnum="1" colwidth="1.8*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
- <colspec colname="c3" colnum="3" colwidth="4.35*"/>
- <colspec colname="c4" colnum="4" colwidth="1.71*"/>
+ <colspec colname="c3" colnum="3" colwidth="4.3*"/>
+ <colspec colname="c4" colnum="4" colwidth="1.69*"/>
<thead>
<row>
<entry><emphasis role="italic">Query parameter</emphasis></entry>
@@ -2157,11 +2201,13 @@
<entry>Date in yyyy-MM-dd format</entry>
</row>
<row>
- <entry>ou</entry>
+ <entry>dimension</entry>
<entry>Yes</entry>
- <entry>Organisation unit identifiers in a single parameter value separated by
- ":".</entry>
- <entry>Organisation unit identifiers </entry>
+ <entry>Dimension identifier including data elements, person attributes, person
+ identifiers, periods and organisation units. Parameter can be repeated any number of
+ times. Filters can be applied to a dimension on the format
+ <item-id>:<operator>:<filter>. Filter values are case-insensitive.</entry>
+ <entry>Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN</entry>
</row>
<row>
<entry>ouMode</entry>
@@ -2171,15 +2217,6 @@
SELECTED refers to the selected organisation units only.</entry>
<entry>DESCENDANTS, CHILDREN, SELECTED</entry>
</row>
- <row>
- <entry>item</entry>
- <entry>Yes</entry>
- <entry>Item identifier including data elements, person attributes and person
- identifiers. Can also be the fixed person attributes GENDER and ISDEAD. Parameter
- can be repeated any number of times. Filters can be applied to an item on the format
- <item-id>:<operator>:<filter>. Filter values are case-insensitive.</entry>
- <entry>Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN</entry>
- </row>
<row>
<entry>asc</entry>
<entry>No</entry>
@@ -2212,11 +2249,11 @@
<para>Event queries should be on the format described below. Item identifiers can refer to any
of data elements, person attributes and person identifiers. Items can optionally have a query
operator and a filter.</para>
- <screen>api/analytics/events/query/<program-id>?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&ou=<ou-id>:<ou-id>&item=<item-id>&item=<item-id>:<operator>:<filter></screen>
+ <screen>api/analytics/events/query/<program-id>?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&ou=<ou-id>;<ou-id>&item=<item-id>&item=<item-id>:<operator>:<filter></screen>
<para>For example, to retrieve events from the "Inpatient morbidity and mortality" program
between January and October 2012, where the "Gender" and "Age" data elements are included
and the "Age" item is filtered on "18", you can use the following query:</para>
- <screen>api/analytics/events/query/eBAyeGv0exc?startDate=2012-01-01&endDate=2012-10-31&ou=O6uvpzGd5pu:fdc6uOvgoji&item=oZg33kd9taw&item=qrur9Dvnyt5:EQ:18</screen>
+ <screen>api/analytics/events/query/eBAyeGv0exc?startDate=2012-01-01&endDate=2012-10-31&ou=O6uvpzGd5pu;fdc6uOvgoji&item=oZg33kd9taw&item=qrur9Dvnyt5:EQ:18</screen>
<para>To retrieve events for the "Birth" program stage of the "Child programme" program between
March and December 2012, where the "Weight" data element, filtered for values larger than
2000, and the "Address" person attribute are included:</para>
@@ -2421,18 +2458,18 @@
<para>In order to get aggregated numbers of <emphasis role="italic">events</emphasis> captured
in DHIS 2 you can work with the <emphasis role="italic">analytics/events/aggregate</emphasis>
resource. This resource lets you retrieve aggregate data based on a program and optionally a
- program stage, and lets you filter on any event item. Event items include data elements,
- person attributes and person identifiers.</para>
+ program stage, and lets you filter on any event dimension. Event dimensions include data
+ elements, person attributes, person identifiers, periods and organisation units.</para>
<para>The aggregate events resource follows much of the same semantics as the event query
resource which is described in the previous section. Please make sure you have read the
mentioned section before progressing.</para>
<para>Aggregate event queries should be on the format described below.</para>
- <screen>api/analytics/events/aggregate/<program-id>?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&ou=<ou-id>:<ou-id>&item=<item-id>&item=<item-id>:<operator>:<filter></screen>
+ <screen>api/analytics/events/aggregate/<program-id>?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&dimension=ou:<ou-id>;<ou-id>&dimension=<item-id>&dimension=<item-id>:<operator>:<filter></screen>
<para>For example, to retrieve aggregate numbers for events from the "Inpatient morbidity and
mortality" program between January and October 2012, where the "Gender" and "Age" data
elements are included, the "Age" item is filtered on "18" and the "Gender" item is filtered on
"Female", you can use the following query:</para>
- <screen>api/analytics/events/aggregate/eBAyeGv0exc?startDate=2012-01-01&endDate=2012-10-31&ou=O6uvpzGd5pu:fdc6uOvgo7ji&item=oZg33kd9taw:EQ:Female&item=qrur9Dvnyt5:EQ:18</screen>
+ <screen>api/analytics/events/aggregate/eBAyeGv0exc?startDate=2012-01-01&endDate=2012-10-31&dimension=ou:O6uvpzGd5pu;fdc6uOvgo7ji&dimension=oZg33kd9taw:EQ:Female&dimension=qrur9Dvnyt5:GT:50</screen>
<para>The response will look similar to this:</para>
<screen>{
"headers": [
@@ -2440,35 +2477,30 @@
"name": "oZg33kd9taw",
"column": "Gender",
"type": "java.lang.String",
- "hidden": false,
"meta": false
},
{
"name": "qrur9Dvnyt5",
"column": "Age",
"type": "java.lang.String",
- "hidden": false,
"meta": false
},
{
"name": "pe",
"column": "Period",
"type": "java.lang.String",
- "hidden": false,
"meta": false
},
{
"name": "ou",
"column": "Organisation unit",
"type": "java.lang.String",
- "hidden": false,
"meta": false
},
{
"name": "value",
"column": "Value",
"type": "java.lang.String",
- "hidden": false,
"meta": false
}
],
@@ -2477,30 +2509,51 @@
"eBAyeGv0exc": "Inpatient morbidity and mortality"
}
},
- "width": 4,
- "height": 2,
+ "width": 5,
+ "height": 39,
"rows": [
[
"Female",
- "19",
- "",
- "O6uvpzGd5pu",
- "51"
- ],
- [
- "Female",
- "20",
- "",
- "O6uvpzGd5pu",
- "83"
- ],
- [
- "Female",
- "18",
- "",
- "O6uvpzGd5pu",
- "57"
- ]
+ "95",
+ "",
+ "O6uvpzGd5pu",
+ "2"
+ ],
+ [
+ "Female",
+ "63",
+ "",
+ "O6uvpzGd5pu",
+ "2"
+ ],
+ [
+ "Female",
+ "67",
+ "",
+ "O6uvpzGd5pu",
+ "1"
+ ],
+ [
+ "Female",
+ "71",
+ "",
+ "O6uvpzGd5pu",
+ "1"
+ ],
+ [
+ "Female",
+ "75",
+ "",
+ "O6uvpzGd5pu",
+ "14"
+ ],
+ [
+ "Female",
+ "73",
+ "",
+ "O6uvpzGd5pu",
+ "5"
+ ],
]
}</screen>
<para>The response tells us that for the "Gender" item filtered on "Female" and organisation
