=== modified file 'src/docbkx/en/dhis2_user_man_web_api.xml'
--- src/docbkx/en/dhis2_user_man_web_api.xml 2013-11-07 19:03:46 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2013-11-08 19:14:48 +0000
@@ -3404,91 +3404,101 @@
to the URL similar to the one used above for retrieval.
- CRUD operations for Persons
- (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.
+ Person management
+ Persons have full CRUD (create, read, update, delete) support in the Web-API. Together
+ with the API for enrollment most operations needed for working with persons and programs are
+ supported.
Creating a new person
For creating a new person in the system, you will be working with the persons resource. An template payload can be seen
below:{
- "orgUnit": "Identifier of the organisationUnit",
- "name": "Name of Person",
- "gender": "MALE / FEMALE / TRANSGENDER",
- "dateOfBirth": {
- "type": "VERIFIED / DECLARED / APPROXIMATE",
- "age": "30", // only required for APPROXIMATE
+ "orgUnit": "Organisation unit identifier",
+ "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": "Identifier of the relationshipType", "person": "LhsYtC2Hmpi" }
- ],
-
- "identifiers": [
- { "type": "Identifier of the personIdentifier", "value": "123" }
- ],
-
- "attributes": [
- { "type": "Identifier of the personAttribute", "value": "This is my new address" }
- ]
+ },
+ "contact": {
+ "phoneNumber": "PHONE_NUMBER"
+ },
+ "relationships": [ {
+ "type": "Relationship type identifier",
+ "person": "Person identifier"
+ } ],
+ "identifiers": [ {
+ "type": "Person id identifier",
+ "value": "1234"
+ } ],
+ "attributes": [ {
+ "type": "Person attribute identifier",
+ "value": "My new address"
+ } ]
}
For getting the identifiers for relationship,
identifiers, attributes you can have a look at the respective resources relationshipTypes, personIdentifiers, personAttributes.
+ >personIdentifiers, personAttributes. To
+ create a person you must use the HTTP POST method. You can
+ post the payload the the following URL:
+ /api/persons
Updating a person
- 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 PUT when
- sending the payload, you will also need to add the person identifier to the persons resource (i.e. /api/persons/<id>).
+ For updating a person, the payload is the equal to the previous section. The difference
+ is that you must use the HTTP PUT method for the request
+ when sending the payload. You will also need to append the person identifier to the
+ persons resource in the URL like this, where
+ <person-identifier> should be replaced by the identifier of the person:
+ /api/persons/<person-id>
Deleting a person
- For deleting a person, no payload is required. All that is needed is to the the HTTP
- method DELETE to the person resource, including the
- identifier.
+ To delete a person you can make a request to the URL identifiying the person with the
+ HTTP DELETE method. The URL is equal to the one above used
+ for update.
Querying for persons
There are several parameter available on the persons
resource for querying for persons, orgUnit paramter is
always required (unless querying for identifiers, please see below).
- Query for org
- unit:GET /api/persons?orgUnit=<orgunit-id>
- Query for org
- unit/nameLike:GET /api/persons?orgUnit=<orgunit-id>&nameLike=sen
- Query for org
- unit/program:GET /api/persons?orgUnit=<orgunit-id>&program=<program-id>
- Query for system
- identifier:GET /api/persons?identifier=SYSTEM_ID
- Query for specific identifier
- type:GET /api/persons?identifierType=<id-type-id>&identifier=<person-id>
+ Query for persons can be done in these ways. All requests should use the HTTP GET
+ method:/api/persons?orgUnit=<orgunit-id>
+ Query for org unit and like
+ name:/api/persons?orgUnit=<orgunit-id>&nameLike=<name>
+ Query for org unit and
+ program:/api/persons?orgUnit=<orgunit-id>&program=<program-id>
+ Query for system identifier:/api/persons?identifier=SYSTEM_ID
+ Query for specific identifier
+ type:/api/persons?identifierType=<id-type-id>&identifier=<person-id>
Enrolling a person into a program
For enrolling persons into a program, you will need to first get the identifier of the
- person from the persons resource, then you will need to
+ person from the persons resource. Then, you will need to
get the program identifier from the programs resource. A
template payload can be seen
below:{
- "person": "ZRyCnJ1qUXS",
- "program": "S8uo8AlvYMz",
- "dateOfEnrollment": "2013-09-17",
- "dateOfIncident": "2013-09-17"
+ "person": "ZRyCnJ1qUXS",
+ "program": "S8uo8AlvYMz",
+ "dateOfEnrollment": "2013-09-17",
+ "dateOfIncident": "2013-09-17"
}
- For cancelling or completing an enrollment, you can send a This payload should be used in a POST request to the
+ enrollments resource identified by the following URL:
+ POST /api/enrollments
+ For cancelling or completing an enrollment, you can make a PUT request to the enrollments resource,
- including the identifier and the action you want to perform. For
- cancelling:PUT /api/enrollments/<enrollment-id>/cancelled
- For completing:PUT /api/enrollments/<enrollment-id>/completed
+ including the identifier and the action you want to perform. For cancelling an enrollment
+ for a person:PUT /api/enrollments/<enrollment-id>/cancelled
+ For completing a program for a person you can make a PUT request to the following
+ URL:PUT /api/enrollments/<enrollment-id>/completed