Example: Sending data values

- Example: Sending data values + 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" dataSet="dataSetID" @@ -312,7 +312,7 @@ 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: Reading data values + Reading data values This section explains how to retrieve data values from the Web API by interacting with the dataValueSets resource. Data values can currently be retrieved in XML format. Since we want to read data we will use the GET HTTP verb. We will also specify that we are interested in the XML resource representation by including an Accept HTTP header with our request. The following query parameters are required: Data value set query parameters @@ -469,11 +469,11 @@ The header tells us that the request was processed successfully and that we are receiving a response in XML format. The XML message looks familiar - it is the data values we sent in the previous section.

- Example: Reading aggregated data values + Reading aggregated data values In order to read aggregated data values you can utilize the reportTables resource. This resource lets you retrieve data from predefined report tables as well as custom data responses for any number of indicators, data elements, data sets, periods and organisation units.

- Example: Writing and reading messages + 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: <message xmlns="http://dhis2.org/schema/dxf/2.0"> @@ -511,7 +511,7 @@ If all went according to plan you will receive a 200 OK status code.

- Example: Writing interpretations + Writing interpretations 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. We will start by writing an interpretation for the chart with identifier EbRN2VIbPdV. To write chart interpretations we will interact with the resource. The interpretation will be the request body. Based on this we can put together the following request using cURL:

curl -d "This chart shows a significant ANC 1-3 dropout" "http://apps.dhis2.org/demo/api/interpretations/chart/EbRN2VIbPdV" -H "Content-Type:text/plain" -u admin:district -v

@@ -521,7 +521,7 @@

curl -d "This table reveals poor data quality" "http://apps.dhis2.org/demo/api/interpretations/reportTable/xIWpSo5jjT1?ou=O6uvpzGd5pu" -H "Content-Type:text/plain" -u admin:district -v

- Example: Embedding reports in web pages + Embedding reports in web pages 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 . The Web API contains several resources which are useful for data analysis: report, reportTable, chart, map and document. 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 data 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 /data 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. We start as usual at the Web API entrypoint at . We look for a relevant report table by following the reportTables link to . We assume that we are interested in the "District Maternal Health" report and follow the link to . This resource provides meta-data information about the report table. From here we can follow the link to the default data view of aggregated data, which leads us to . As we can see we are provided with a report table in HTML format, which is the default representation format for report tables. @@ -564,7 +564,7 @@

- Example: Embedding charts with the Visualizer chart plug-in + Embedding charts with the Visualizer chart plug-in In this example we will see how we can embed good-looking Ext JS charts () with data served from a DHIS back-end into a Web page. To accomplish this we will use the DHIS Visualizer plug-in. The plug-in is written in Javascript and depends on the Ext JS library only. A complete working example can be found at . Open the page in a web browser and view the source to see how it is set up. We start by including three required Javascript files in the header section of the HTML document. The first file is the Ext JS Javascript library (we use the Google content delivery network in this case). The third file is the Visualizer plug-in. Make sure the path is pointing to your DHIS server installation. <script type="text/javascript" @@ -840,7 +840,7 @@ To see a complete working example please visit .

- Example: Creating a chart carousel with the carousel plug-in + Creating a chart carousel with the carousel plug-in The chart plug-in also makes it possible to create a chart carousel which for instance can be used to create an attractive front page on a Web portal. To use the carousel we need to import a few files in the head section of our HTML page: <link rel="stylesheet" type="text/css" href="http://apps.dhis2.org/demo/dhis-web-commons/javascripts/ext/resources/css/ext-plugin-gray.css" /> @@ -872,7 +872,7 @@ To see a complete working example please visit .

- Example: Embedding report tables with the table plug-in + Embedding report tables with the table plug-in In this example we will see how we can embed dynamic data tables in a Web page with data provided from a DHIS back-end server using the table plug-in. The table plug-in resides inside the same file as the chart plug-in so please refer to the section about the chart plug-in above on how to include the required JavaScript and CSS files and how to do authentication. The available table options are listed in the table below.

Table plug-in configuration @@ -1056,8 +1056,12 @@ To view a complete working example please visit .

- Example: Working with SQL views - Executing SQL Views and returning the results of these views has been made possible in version 2.9 of DHIS2. SQL Views are useful for presenting certain data views externally, which may be more easily constructed with SQL than by combining the multiple objects of the Web API. As an example, lets assume we have been asked to provide a view of all organization units with their names, parent names, organization unit level and name, and the coordinates listed in the database. The view might look something like this: + Working with SQL views + SQL Views are useful for presenting certain data views externally, which may be more + easily constructed with SQL than by combining the multiple objects of the Web API. As an + example, lets assume we have been asked to provide a view of all organization units with their + names, parent names, organization unit level and name, and the coordinates listed in the + database. The view might look something like this: SELECT ou.name, par.name as parent, ou.coordinates, ous.level,oul.name from organisationunit ou INNER JOIN _orgunitstructure ous @@ -1067,15 +1071,17 @@ where ou.coordinates IS NOT NULL ORDER BY oul.level,par.name,ou.name We will use curl to first execute the view on the DHIS2 server. This is essentially a materialization process, and ensures that we have the most recent data available through the SQL View when it is retrieved from the server. - curl "http://apps.dhis2.org/dev/ -dhis-web-maintenance-dataadmin/ -executeSqlViewQuery.action?id=1150154" --u admin:district -v - This curl command simply has the internal ID of the view as a single parameter. + curl "http://apps.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/execute" -X POST -u admin:district -v + This curl command simply has the internal identifier of the view as a + single parameter. The next step in the process is the retrieval of the data.The basic structure of the URL is as follows - http(s)://{server}/api/sqlViews/{uid}/data(.csv) - The {server} parameter should be replaced with your own server. The next part of the URL /api/sqlViews/ should be appended with the specific unique identifier (not the internal ID of the view). Append either data for XML data or data.csv for comma delimited values. As an example, the following URL would retrieve XML data for the SQL view defined above.curl -"http://apps.dhis2.org/dev/api/sqlViews/w11jeI9gGAr/data.csv" - -u admin:district -v + http://{server}/api/sqlViews/{uid}/data(.csv) + The {server} parameter should be replaced with your own server. The + next part of the URL /api/sqlViews/ should be appended with the + specific unique identifier (not the internal ID of the view). Append either + data for XML data or data.csv for comma + delimited values. As an example, the following command would retrieve XML data for the SQL + view defined + above.curl "http://apps.dhis2.org/dev/api/sqlViews/dI68mLkP1wN/data.csv" -u admin:district -v