dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 530
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Fri 2012-06-15 20:20:45 +0200
message:
  Docs for interpretations in web api
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	2012-06-13 18:30:00 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml	2012-06-15 18:20:45 +0000
@@ -272,6 +272,16 @@
     <para>If all went according to plan you will receive a <emphasis role="italic">200 OK</emphasis> status code.</para>
   </section>
   <section>
+    <title>Example: Writing interpretations</title>
+    <para>For certain analysis-related resources in DHIS, like charts and report tables, one can share a data interpretation. An interpretation is simply a link to the the relevant resource together with a text expressing some insight about the data. Currently an interpretation can be viewed by all users in the system.</para>
+    <para>We will start by writing an interpretation for the chart with identifier <emphasis role="italic">EbRN2VIbPdV</emphasis>. To write chart interpretations we will interact with the <ulink url="http://apps.dhis2.org/demo/api/interpretations/chart/{chartId}"/> resource. The interpretation will be the request body. Based on this we can put together the following request using cURL:</para>
+    <para><code>curl -d &quot;This chart shows a significant ANC 1-3 dropout&quot; &quot;http://apps.dhis2.org/demo/api/interpretations/chart/EbRN2VIbPdV&quot; -H &quot;Content-Type:text/plain&quot; -u admin:district -v</code></para>
+    <para>Second we will write a comment on the interpretation we just wrote. By looking at the interpretation response you will see that a <emphasis role="italic">Location</emphasis> header is returned. This header tells us the URL of the newly created interpretation and from that we can read its identifier. This identifier is randomly generated so you will have to replace the one in the command below with your own. To write a comment we can interact with the <ulink url="http://apps.dhis2.org/demo/api/interpretations/{interpretationId}/comment"/> like this:</para>
+    <para><code>curl -d &quot;An intervention is needed&quot; &quot;http://apps.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comment&quot; -H &quot;Content-Type:text/plain&quot; -u admin:district -v</code></para>
+    <para>You can also write interpretations for report tables in a similar way by interacting with the <ulink url="http://app.dhis2.org/demo/api/interpretations/reportTable/{reportTableId}"/>. For report tables you can also provide an optional <emphasis role="italic">ou</emphasis> query parameter to supply an organisation unit identifier in the case where the report table has an organisation unit report parameter:</para>
+    <para><code>curl -d &quot;This table reveals poor data quality&quot; &quot;http://apps.dhis2.org/demo/api/interpretations/reportTable/xIWpSo5jjT1?ou=O6uvpzGd5pu&quot; -H &quot;Content-Type:text/plain&quot; -u admin:district -v</code></para>
+  </section>
+  <section>
     <title>Example: Embedding reports in web pages</title>
     <para>In this example we will see how we can build a simple web page  where dynamic data such as tabular reports is pulled from the DHIS Web API. A full example on how this can done is available at <ulink url="http://apps.dhis2.org/portal"/>.</para>
     <para>The Web API contains several resources which are useful for data analysis: <emphasis role="italic">report</emphasis>, <emphasis role="italic">reportTable</emphasis>, <emphasis role="italic">chart</emphasis>, <emphasis role="italic">map</emphasis> and <emphasis role="italic">document</emphasis>. Dispatching  GET requests to the mentioned resources will return meta-data information such as name and the date it was last updated. All these resources have an associated <emphasis role="italic">data</emphasis> resource which produces a data view of  related aggregated data - also  known as  reports, charts and maps. You can follow the links or simply append <emphasis role="italic">/data</emphasis> to the URL to arrive at it. This information can be represented in a variety of formats including HTML, PDF, Excel, PNG and Jasper, as we will see in the next section.</para>