dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #29836
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 1058: Update user manual 30.13, Web API for Data Approval
------------------------------------------------------------
revno: 1058
committer: jimgrace@xxxxxxxxx
branch nick: dhis2-docbook-docs
timestamp: Sun 2014-05-04 19:30:05 -0400
message:
Update user manual 30.13, Web API for Data Approval
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-25 13:08:46 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2014-05-04 23:30:05 +0000
@@ -1344,93 +1344,226 @@
<para>This section explains how to approve, unapprove and check approval status using the
<emphasis role="italic">dataApprovals</emphasis> resource. Approval is done per data set,
period, organisation unit and attribute option combo. </para>
- <table frame="all">
- <title>Data approval query parameters</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1" colwidth="1*"/>
- <colspec colname="c2" colnum="2" colwidth="1.15*"/>
- <colspec colname="c3" colnum="3" colwidth="3.92*"/>
- <thead>
- <row>
- <entry>Query parameter</entry>
- <entry>Required</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>ds</entry>
- <entry>Yes</entry>
- <entry>Data set identifier</entry>
- </row>
- <row>
- <entry>pe</entry>
- <entry>Yes</entry>
- <entry>Period identifier</entry>
- </row>
- <row>
- <entry>ou</entry>
- <entry>Yes</entry>
- <entry>Organisation unit identifier</entry>
- </row>
- <row>
- <entry>cc</entry>
- <entry>No (must combine with cp)</entry>
- <entry>Attribute combo identifier</entry>
- </row>
- <row>
- <entry>cp</entry>
- <entry>No (must combine with cp)</entry>
- <entry>Attribute option identifiers, separated with ; for multiple values</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>To check the status for approval you can issue a <emphasis role="italic">GET</emphasis>
- request to the dataApprovals resource:</para>
- <screen>api/dataApprovals</screen>
- <para>To get approval state for a data set you can issue a GET request similar to this:</para>
+ <para>To get approval information for a data set you can issue a GET request similar to this:</para>
<screen>api/dataApprovals?ds=aLpVgfXiz0f&pe=2013&ou=DiszpKrYNg8</screen>
- <para>To approval a data set which has attributes you can issue a <emphasis role="italic"
- >POST</emphasis> request like this:</para>
- <screen>curl "http://apps.dhis2.org/demo/api/dataApprovals?ds=lyLU2wR22tC&pe=201312&ou=DiszpKrYNg8&cc=O4VaNks6tta&cp=C6nZpLKjEJr;i4Nbp8S2G6A"; -X POST -u admin:district -v</screen>
- <table frame="all">
- <title>Approval status</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="1*"/>
- <colspec colname="c2" colnum="2" colwidth="2.21*"/>
- <thead>
- <row>
- <entry>Approval status</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>"APPROVED"</entry>
- <entry>Data in this data set is approved for this period and organisation unit</entry>
- </row>
- <row>
- <entry>"READY_FOR_APPROVAL"</entry>
- <entry>Data in this data set is ready to be approved for this period and organisation
- unit</entry>
- </row>
- <row>
- <entry>"WAITING_FOR_LOWER_LEVEL_APPROVAL"</entry>
- <entry>Data is not ready to be approved because it is waiting for approval at a
- lower-level organisation unit</entry>
- </row>
- <row>
- <entry>"APPROVAL_NOT_NEEDED"</entry>
- <entry>Data does not need approval because approval is not required or data set is not
- collected at organisation unit</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <table frame="all">
+ <title>Data approval query parameters</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="1.15*"/>
+ <colspec colname="c3" colnum="3" colwidth="3.92*"/>
+ <thead>
+ <row>
+ <entry>Query parameter</entry>
+ <entry>Required</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>ds</entry>
+ <entry>Yes</entry>
+ <entry>Data set identifier</entry>
+ </row>
+ <row>
+ <entry>pe</entry>
+ <entry>Yes</entry>
+ <entry>Period identifier</entry>
+ </row>
+ <row>
+ <entry>ou</entry>
+ <entry>Yes</entry>
+ <entry>Organisation unit identifier</entry>
+ </row>
+ <row>
+ <entry>cog</entry>
+ <entry>No</entry>
+ <entry>Attribute category option group identifier</entry>
+ </row>
+ <row>
+ <entry>cp</entry>
+ <entry>No</entry>
+ <entry>Attribute category option identifier(s), repeat the parameter for multiple values</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>This will give you a response something like this:</para>
+ <screen>{
+ "mayApprove": false,
+ "mayUnapprove": false,
+ "mayAccept":false,
+ "mayUnaccept":false,
+ "state":"UNAPPROVED_ELSEWHERE"
+}</screen>
+ <para>The returned parameters are:</para>
+ <table frame="all">
+ <title>Data approval query parameters</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="3*"/>
+ <thead>
+ <row>
+ <entry>Return Parameter</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>mayApprove</entry>
+ <entry>Whether the current user may approve this data selection.</entry>
+ </row>
+ <row>
+ <entry>mayUnapprove</entry>
+ <entry>Whether the current user may unapprove this data selection.</entry>
+ </row>
+ <row>
+ <entry>mayAccept</entry>
+ <entry>Whether the current user may accept this data selection.</entry>
+ </row>
+ <row>
+ <entry>mayUnaccept</entry>
+ <entry>Whether the current user may unaccept this data selection.</entry>
+ </row>
+ <row>
+ <entry>state</entry>
+ <entry>One of the data approval states from the table below.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table frame="all">
+ <title>Data approval states</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1.5*"/>
+ <colspec colname="c2" colnum="2" colwidth="3*"/>
+ <thead>
+ <row>
+ <entry>State</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>UNAPPROVABLE</entry>
+ <entry>Data approval does not apply to this selection. (Data is neither "approved" nor "unapproved".)</entry>
+ </row>
+ <row>
+ <entry>UNAPPROVED_WAITING</entry>
+ <entry>Data could be approved for this selection, but is waiting for some lower-level approval before it is ready to be approved.</entry>
+ </row>
+ <row>
+ <entry>UNAPPROVED_ELSEWHERE</entry>
+ <entry>Data is unapproved, and is waiting for approval somewhere else (not approvable here.)</entry>
+ </row>
+ <row>
+ <entry>UNAPPROVED_READY</entry>
+ <entry>Data is unapproved, and is ready to be approved for this selection.</entry>
+ </row>
+ <row>
+ <entry>APPROVED_HERE</entry>
+ <entry>Data is approved, and was approved here (so could be unapproved here.)</entry>
+ </row>
+ <row>
+ <entry>APPROVED_ELSEWHERE</entry>
+ <entry>Data is approved, but was not approved here (so cannot be unapproved here.) This covers the following cases:
+ <itemizedlist>
+ <listitem>Data is approved at a higher level.</listitem>
+ <listitem>Data is approved for wider scope of category options.</listitem>
+ <listitem>Data is approved for all sub-periods in selected period.</listitem>
+ </itemizedlist>
+ In the first two cases, there is a single data approval object that covers the selection. In the third case there is not.
+ </entry>
+ </row>
+ <row>
+ <entry>ACCEPTED_HERE</entry>
+ <entry>Data is approved and accepted here (so could be unapproved here.)</entry>
+ </row>
+ <row>
+ <entry>ACCEPTED_ELSEWHERE</entry>
+ <entry>Data is approved and accepted, but elsewhere.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Note that when querying for the status of data approval, you may specify any combination of the query parameters.
+ The combination you specify does not need to describe the place where data is to be approved at one of the approval levels.
+ For example:</para>
+ <itemizedlist>
+ <listitem>
+ The organisation unit might not be at an approval level. The approval status is determined by
+ whether data is approved at an approval level for an ancestor of the organisation unit.
+ </listitem>
+ <listitem>
+ You may specify individual attribute category options. The approval status is determined by whether
+ data is approved for an attribute category option combination that includes one or more of these options.
+ </listitem>
+ <listitem>
+ You may specify a time period that is longer than the period for the data set at which the data is entered and approvede.
+ The approval status is determined by whether the data is approved for all the data set periods within the period you specify.
+ </listitem>
+ </itemizedlist>
<para>To approve data you can issue a <emphasis role="italic">POST</emphasis> request to the
dataApprovals resource. To un-approve data you can issue a <emphasis role="italic"
- >DELETE</emphasis> request.</para>
+ >DELETE</emphasis> request to the dataApprovals resource.</para>
+ <para>To accept data you can issue a <emphasis role="italic">POST</emphasis> request to the
+ dataApprovals/acceptances resource. To un-accept data you can issue a <emphasis role="italic"
+ >DELETE</emphasis> request to the dataApprovals/acceptances resource.</para>
+ <para>These requests contain the following parameters:</para>
+ <table frame="all">
+ <title>Data approval action parameters</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="1.15*"/>
+ <colspec colname="c3" colnum="3" colwidth="3.92*"/>
+ <thead>
+ <row>
+ <entry>Action parameter</entry>
+ <entry>Required</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>ds</entry>
+ <entry>Yes</entry>
+ <entry>Data set identifier</entry>
+ </row>
+ <row>
+ <entry>pe</entry>
+ <entry>Yes</entry>
+ <entry>Period identifier</entry>
+ </row>
+ <row>
+ <entry>ou</entry>
+ <entry>Yes</entry>
+ <entry>Organisation unit identifier</entry>
+ </row>
+ <row>
+ <entry>cog</entry>
+ <entry>No</entry>
+ <entry>Attribute category option group identifier. Required if approving for an approval level that contains a category option group set, otherwise must not be present.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Note that, unlike querying the data approval status, you must specify parameters that correspond to a selection of data that could be approved.
+ In particular, all of the following must be true:</para>
+ <itemizedlist>
+ <listitem>
+ The organisation unit's level must be specified by an approval level.
+ </listitem>
+ <listitem>
+ The category option group (if specified) must be a member of an approval level's category option group set (if specified)
+ for an approval level with the same organisation unit level.
+ </listitem>
+ <listitem>
+ The time period specified must match the period type of the data set.
+ </listitem>
+ <listitem>
+ The data set must specify that data can be approved for this data set.
+ </listitem>
+ </itemizedlist>
</section>
<section>
<title>Writing and reading messages</title>
