dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #24898
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 810: include basic information about person crud operations, also update event section
------------------------------------------------------------
revno: 810
committer: Morten Olav Hansen <mortenoh@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Thu 2013-09-26 12:10:50 +0200
message:
include basic information about person crud operations, also update event section
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-25 15:27:11 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2013-09-26 10:10:50 +0000
@@ -360,18 +360,27 @@
<para>In a real-world scenario, looking up identifiers, constructing and dispatching XML messages would be the task of the client software application. This software would probably interact with the more machine-friendly XML and JSON resource representations and not the human-friendly HTML representations like we did in this example. Developing creative and robust consumers of the Web API services begins here.</para>
</section>
<section>
- <title>Sending single event with no registration data values</title>
+ <title>Sending event data values</title>
<para>DHIS 2 supports three kinds of events: single events with no registration (also referred
to as anonymous events), single event with registration and multiple events with registration.
Registration implies that the data is linked to a person which is identified using some sort
- of identifier. Only single event with no registration is supported in DXF 2 currently.</para>
- <para>To send events to DHIS 2 you must interact with the <emphasis role="italic">events</emphasis> resource. The approach to sending events is similar to sending aggregate
- data values. You will need a <emphasis role="italic">programId</emphasis> which can be looked
- up using the <emphasis role="italic">programs</emphasis> resource, an <emphasis role="italic">organisationUnitId</emphasis> which can be looked up using the <emphasis role="italic">organisationUnits</emphasis> resource, and a list of valid data element identifiers which
- can be looked up using the <emphasis role="italic">dataElements</emphasis> resource. </para>
- <para>An example payload in XML format where we send events from the "Inpatient morbidity and
- mortality" program for the "Ngelehun CHC" facility in the demo database can be seen
- below:</para>
+ of identifier.</para>
+ <para>To send events to DHIS 2 you must interact with the <emphasis role="italic"
+ >events</emphasis> resource. The approach to sending events is similar to sending aggregate
+ data values. You will need a <emphasis role="italic">program</emphasis> which can be looked up
+ using the <emphasis role="italic">programs</emphasis> resource, an <emphasis role="italic"
+ >orgUnit</emphasis> which can be looked up using the <emphasis role="italic"
+ >organisationUnits</emphasis> resource, and a list of valid data element identifiers which
+ can be looked up using the <emphasis role="italic">dataElements</emphasis> resource. For
+ events with registration, a <emphasis role="italic">person</emphasis> identifier is required,
+ read about how to get this in the section about the <emphasis role="italic">person</emphasis>
+ resource. For sending events to programs with multiple stages, you will need to also include
+ the <emphasis role="italic">programStage</emphasis> identifier, the identifiers for
+ programStages can be found in the <emphasis role="italic">programStages</emphasis>
+ resource.</para>
+ <para>A simple single event with no registration example payload in XML format where we send
+ events from the "Inpatient morbidity and mortality" program for the "Ngelehun CHC" facility in
+ the demo database can be seen below:</para>
<screen><?xml version="1.0" encoding="utf-8"?>
<event program="eBAyeGv0exc" orgUnit="DiszpKrYNg8" eventDate="2013-05-17" completed="true" storedBy="admin">
<coordinate latitude="59.8" longitude="10.9" />
@@ -404,7 +413,7 @@
<para>To send this you can save it to a file called <emphasis role="italic">events.json</emphasis> and use curl like this:</para>
<screen>curl -d @events.xml "localhost:8080/api/events" -H "Content-Type:application/json" -u admin:district -v</screen>
<para>We also support sending multiple events at the same time. A payload in XML format might
- look like this: (Caution: this format might change slightly in version 2.13)</para>
+ look like this: </para>
<screen><?xml version="1.0" encoding="utf-8"?>
<events>
<eventList>
@@ -459,8 +468,9 @@
] }
]
}</screen>
- <para>(From 2.13) As part of the import summary you will also get the UID reference to the event
- you just sent, together with a href element which points to the server location of this event. </para>
+ <para>(From 2.13) As part of the import summary you will also get the UID <emphasis
+ role="italic">reference</emphasis> to the event you just sent, together with a <emphasis
+ role="italic">href</emphasis> element which points to the server location of this event. </para>
<para><emphasis role="bold">Update</emphasis>: To update an existing event, the format of the
payload is the same, but the URL you are posting to must add the UID reference to the end of
the URL string and the request must be PUT.
@@ -2561,6 +2571,78 @@
to the URL similar to the one used above for retrieval.</para>
</section>
<section>
+ <title>CRUD operations for Persons</title>
+ <para>(From 2.13) we have full CRUD (create, read, update, delete) support in the Web-API.
+ Together with a new API for enrollment and updated event API, most operations needed for
+ working with persons and programs are supported.</para>
+ <section>
+ <title>Creating a new person</title>
+ <para>For creating a new person in the system, you will be working with the <emphasis
+ role="italic">persons</emphasis> resource. An template payload can be seen
+ below:<screen>{
+ "orgUnit": "Uid of the organisationUnit",
+ "name": "Name of Person",
+ "gender": "MALE / FEMALE / TRANSGENDER",
+ "dateOfBirth": {
+ "type": "VERIFIED / DECLARED / APPROXIMATE",
+ "age": "30", // only required for APPROXIMATE
+ "date": "2081-03-04" // required for VERIFIED, DECLARED
+ },
+ "contact": {
+ "phoneNumber": "PHONE_NUMBER"
+ },
+
+ "relationships": [
+ { "type": "Uid of the relationshipType", "person": "LhsYtC2Hmpi" }
+ ],
+
+ "identifiers": [
+ { "type": "Uid of the personIdentifier", "value": "uuid-13" }
+ ],
+
+ "attributes": [
+ { "type": "Uid of the personAttribute", "value": "This is my new address" }
+ ]
+}</screen></para>
+ <para>For getting the identifiers for <emphasis role="italic">relationship</emphasis>,
+ <emphasis role="italic">identifiers</emphasis>, <emphasis role="italic"
+ >attributes</emphasis> you can have a look at the respective resources <emphasis
+ role="italic">relationshipTypes</emphasis>, <emphasis role="italic"
+ >personIdentifiers</emphasis>, <emphasis role="italic">personAttributes</emphasis>.</para>
+ </section>
+ <section>
+ <title>Updating a person</title>
+ <para>For updating a person, the payload is the same as in the previous section. The only
+ different is that you must use the HTTP method <emphasis role="bold">PUT</emphasis> when
+ sending the payload, you will also need to add the person identifier (UID) to the <emphasis
+ role="italic">persons</emphasis> resource (i.e. /api/persons/UID).</para>
+ </section>
+ <section>
+ <title>Deleting a person</title>
+ <para>For deleting a person, no payload is required. All that is needed is to the the HTTP
+ method <emphasis role="bold">DELETE</emphasis> to the person resource, including the
+ identifier.</para>
+ </section>
+ <section>
+ <title>Enrolling a person into a program</title>
+ <para>For enrolling persons into a program, you will need to first get the identifier of the
+ person from the <emphasis role="italic">persons</emphasis> resource, then you will need to
+ get the program identifier from the <emphasis role="italic">programs</emphasis> resource. A
+ template payload can be seen
+ below:<screen>{
+ "person": "ZRyCnJ1qUXS",
+ "program": "S8uo8AlvYMz",
+ "dateOfEnrollment": "2013-09-17",
+ "dateOfIncident": "2013-09-17"
+}</screen></para>
+ <para>For cancelling or completing an enrollment, you can send a <emphasis role="bold"
+ >PUT</emphasis> request to the <emphasis role="italic">enrollments</emphasis> resource,
+ including the identifier and the action you want to perform. For
+ cancelling:<screen>PUT /api/enrollments/UID/cancelled</screen></para>
+ <para>For completing:<screen>PUT /api/enrollments/UID/completed</screen></para>
+ </section>
+ </section>
+ <section>
<title>FRED API</title>
<para>DHIS 2 from version 2.11 implements support for the current draft
of the FRED API version 1.0. The project defines itself as <quote>open standard for sharing and updating
