Authentication

Example: Sending data values A common use-case for system integration is the need to send a set of data values from a third-party system into DHIS. In this example we will use the DHIS 2 demo on as basis and we recommend that you follow the provided links with a web browser while reading (log in with admin/district as username/password). We assume that we have collected case-based data using a simple software client running on mobile phones for the Mortality <5 years data set in the community of Ngelehun CHC (in Badjia chiedom, Bo district) for the month of January 2012. We have now aggregated our data into a statistical report and want to send that data to the national DHIS 2 instance. The entry point for the Web API running on the demo instance is . The entry point provides a convenient HTML page with links to all of the available resources in the Web API. The resource which is most appropriate for our purpose of sending data values is the dataValueSets resource. A data value set represents a set of data values which have a logical relationship, usually from being captured off the same data entry form. We follow the link to the HTML representation which will take us to . The default representation is a HTML page which provides us with useful instructions on how to interact with this resources. It tells us that we can use the POST verb to send values using a XML format defined by the http://dhis2.org/schema/dxf/2.0 namespace: - <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" period="periodISODate" dataSet="dataSetID" orgUnit="orgUnitID"> + <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="dataSetID" completeDate="ISODate" period="periodISODate" orgUnit="orgUnitID"> <dataValue dataElement="dataElementID" value="1" /> <dataValue dataElement="dataElementID" value="2" /> <dataValue dataElement="dataElementID" value="3" /> @@ -36,7 +41,7 @@ To obtain the identifier for the data set we return to the the entry point at and follow the embedded link pointing at the dataSets resource located at . From there we find and follow the link to the Mortality < 5 years data set which leads us to . What we did was effectively to retrieve the HTML representation of our data set of interest, and from it we can easily see the identifier, which is pBOMPrpg1QX. The resource representation for the Mortality < 5 years data set conveniently advertises links to the data elements which are members of it. From here we can follow these links and obtain the identifiers of the data elements. For brevity we will only report on three data elements: Measles with id f7n9E0hX8qk, Dysentery with id Ix2HsbDMLea and Cholera with id eY5ehpbEsB7. What remains is to get hold of the identifier of the facility (org unit). Again the dataSet representation conveniently provides link to org units which report on it so we search for Ngelehun CHC and follow the link to the HTML representation at , which tells us that the identifier of this org unit is DiszpKrYNg8. From our case-based data we assume that we have 12 cases of measles, 14 cases of dysentery and 16 cases of cholera. We have now gathered enough information to be able to put together the XML data value set message: - <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" period="201201" dataSet="pBOMPrpg1QX" orgUnit="DiszpKrYNg8"> + <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX" completeDate="2012-02-03" period="201201" orgUnit="DiszpKrYNg8"> <dataValue dataElement="f7n9E0hX8qk" value="12" /> <dataValue dataElement="Ix2HsbDMLea" value="14" /> <dataValue dataElement="eY5ehpbEsB7" value="16" /> @@ -45,10 +50,75 @@

curl -d @datavalueset.xml "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -u admin:district -v

The command will dispatch a request to the demo Web API, set application/xml as the content-type and authenticate using admin/district as username/password. If all goes well this will return a 200 OK HTTP status code. You can verify that the data has been received by opening the data entry module in DHIS 2 and select the org unit, data set and period used in this example. The API follows normal semantics for error handling and HTTP status codes. If you supply an invalid username or password, 401 Unauthorized is returned. If you supply a content-type other than application/xml, 415 Unsupported Media Type is returned. If the XML content is invalid according to the DXF namespace, 400 Bad Request is returned. If you provide an invalid identifier in the XML content, 409 Conflict is returned together with a descriptive message. - In this example, cURL will authenticate to the server through basic authentication using our supplied username and password as credentials. Basic authentication is a technique for clients to send login credentials over HTTP to a web server. Technically speaking, the username is appended with a colon and the password, Base64-encoded and supplied as the value of the Authorization HTTP header. An important note is that this authentication scheme provides no security since the username and password is sent in plain text and can be easily decoded. Using it is recommended only if the server is using SSL/TLS (HTTPS) to encrypt communication between itself and the client. + In this example, cURL will authenticate to the server through Basic authentication using our supplied username and password as credentials through the -u flag. 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.

+ Example: Sending large bulks of data values + The previous example showed us how to send a set of related data values sharing the same period and organisation unit. This example will show us how to send large bulks of data values which don't necessarily are logically related. + Again we will interact with the with resource. This time we will not specify the dataSet and completeDate attributes. Also, we will specify the period and orgUnit attributes on the individual data value elements instead of on the outer data value set element. This will enable us to send data values for various periods and org units: + <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0"> + <dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="DiszpKrYNg8" value="12" /> + <dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="FNnj3jKGS7i" value="14" /> + <dataValue dataElement="f7n9E0hX8qk" period="201202" orgUnit="DiszpKrYNg8" value="16" /> + <dataValue dataElement="f7n9E0hX8qk" period="201202" orgUnit="Jkhdsf8sdf4" value="18" /> +</dataValueSet> + We test by using cURL to send the data values: +

curl -d @datavalueset.xml "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -u admin:district -v

+ The data value set resource provides an XML response which is useful when you want to verify the impact your request had. The first time we send the data value set request above the server will respond with the following import summary: + <importSummary> + <dataValueCount imported="2" updated="1" ignored="1"/> + <dataSetComplete>false</dataSetComplete> +</importSummary> + This message tells us that 3 data values were imported, 1 data value was updated while zero data values were ignored. The single update comes as a result of us sending that data value in the previous example. A data value will be ignored if it references a non-existing data element, period, org unit or data set. In our case this single ignored value was caused by the last data vaue having an invalid reference to org unit. The data set complete element will display the date of which the data value set was completed, or false if no data element attribute was supplied. + The import process can be customized using a set of import parameters: + + Import parameters + + + + + Parameter + + + Values (default first) + + + Description + + + + dataElementIdScheme + uid | name | code + Which property on the data element object to reference from the XML attribute + + + orgUnitIdScheme + uid | name | code + Which property on the org unit object to reference from the XML attribute + + + dryRun + false | true + Whether to save changes on the server or just return the import summary + + + importStrategy + new_and_updates | new | updates + Save objects of all, new or update import status on the server + + + +

+ All parameters are optional and can be supplied as query parameters in the request URL like this: + http://apps.dhis2.org/demo/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=name&dryRun=true&importStrategy=new + They can also be supplied as XML attributes on the data value set element like below. XML attributes will override query string parameters. + <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataElementIdScheme="code" orgUnitIdScheme="name" dryRun="true" importStrategy="new"> + .. +</dataValueSet> + Regarding the id schemes, by default the identifiers used in the XML messages refer to the DHIS stable object identifiers. In certain interoperability situations we might experience that the external system decides the identifiers of the objects. In that case we can use the code property of the organisation unit and data element objects to set fixed identifiers dictated by the other system. When importing data values we hence need to reference the code property instead of the uid property, and can do so using the dataElementIScheme and orgUnitIdScheme paramaters. +

Example: Writing and reading messages DHIS 2 features a mechanism for sending messages for purposes such as user feedback, notifications and general information to users. Messages are delivered to the DHIS 2 message inbox but can also be sent to the user's email addresses and mobile phones as SMS. In this example we will see how we can utilize the Web API to send and read messages. We will pretend to be the DHIS Administrator user and send a message to the Mobile user. We will then pretend to be the mobile user and read our new message. The resource we need to interact with when sending and reading messages is the messageConversations resource. We start by visiting the Web API entry point at where we find and follow the link to the messageConversations resource at . The description tells us that we can use a POST request to create a new message using the following XML format: @@ -99,7 +169,7 @@ ); }); In this code block we ask jQuery to send a POST request to the standard authentication point with two name-value pairs containing the username and password information. We assume that the user has the necessary authorities to view reports in the DHIS 2 Web API. If authentication was successful the server will send a HTTP cookie in the response with a session identifier. This will make sure that the current user is authorized to view reports for up to 60 minutes. - Caveat: The username and password will be present in the web page in plain text. Make sure you create a dedicated user in DHIS 2 for this purpose provided only with the minimum authorities required. + Caveat: The username and password will be present in the web page in plain text. Make sure you create a dedicated user in DHIS 2 for this purpose provided only with the minimum authorities required. For a more robust way of exposing resources without requiring authentication see the the section on reverse proxy setup in the installation chapter. For a full example visit and view the page source in a browser. Note that the example web page is hosted within the same domain (apps.dhis2.org) as the demo DHIS 2 instance. This is done to avoid issues related to the "same origin policy", a concept which prevents scripts hosted on one domain to access resources running on another. While one can circumvent this through techniques such as CORS, there are none which have wide browser support at the moment. Therefore we recommend hosting web pages and portals on the same domain. Techniques using reverse proxies described in the "installation" chapter can be useful in this regard. Finally we provide some sample URLs pointing to various data resources for your inspiration: === modified file 'src/docbkx/en/resources/css/docbook_bsd.css' --- src/docbkx/en/resources/css/docbook_bsd.css 2012-03-19 15:46:00 +0000 +++ src/docbkx/en/resources/css/docbook_bsd.css 2012-04-17 10:58:49 +0000 @@ -68,7 +68,16 @@ DIV.PROCEDURE P B { color: #990000; } - + +TABLE { + border: 1px solid #aaa; + border-collapse: collapse; +} + +TABLE TD { + padding: 5px; +} + BODY H1, BODY H2, BODY H3, BODY H4, BODY H5, BODY H6 { line-height: 1.3; margin-left: 0;