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. - As stated in the introduction there are three ways of indicating which resource representation format you prefer for the response. The most suitable alternative for direct use in web pages is to append a file suffix to the URL. We assume that we are interested in the PDF representation and indicate that by appending .pdf to our URL: . Go ahead and try out all valid extensions for this resource which are .html, .pdf, .xls and .csv. - The report table can be parameterized with an organisation unit and a period by supplying a ou and pe query parameter accompanied with an organisation unit identifier and period string in the URL. If not provided the Web API will use the top-most organisation unit in the hierarchy and the last period for the report table content. The organisation unit identifier can be looked up by going to the Web API entrypoint and follow the link to the organisationUnits resouce. For our example we will use Bo district whith identifier O6uvpzGd5pu as the organisation unit: . From the HTML representation we can see that the report now contains data for Bo district. These URLs can simply be used in links embedded in the web page like this: - <a href="http://apps.dhis2.org/demo/api/reportTables/xIWpSo5jjT1/data.pdf? -ou=O6uvpzGd5pu">Maternal Health Bo District 2012</a> - There are many ways to authenticate over the Web and each method has its advantages and disadvantages. For this example we will use an approach where we emulate a login from the web-based login form. To help us we will use the jQuery JavaScript library. This JavaScript code should be embedded in the head section of the Web page: - jQuery(document).ready(function() { - $.post( "http://apps.dhis2.org/demo/dhis-web-commons-security/login.action", { - j_username: "admin", j_password: "district" - } - ); -}); - 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. 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: - - - - - - - - - - - - - - - - - - - - - - - + Viewing analytical resource representations + DHIS 2 has several resources for data analysis. These resources include charts, maps, reportTables, reports and + documents. By visiting these resources you will retrieve + information about the resource. For instance, by navigating to api/charts/R0DVGvXDUNP the response will contain the name, last date of + modication and so on for the chart. To retrieve the analytical representation, for instance a + PNG representation of the chart, you can append /data to + all these resources. For instance, by visiting api/charts/R0DVGvXDUNP/data the system will return a PNG image of the + chart. + + Analytical resources + + + + + + + + Resource + Description + Data URL + Resource representations + + + + + charts + Charts + api/charts/<identifier>/data + png + + + maps + Maps + api/maps/<identifier>/data + png + + + reportTables + Pivot tables + api/reportTables/<identifier>/data + json | jsonp | html | xml | pdf | xls | csv + + + reports + Standard reports + api/reports/<identifier>/data + pdf | xls | html + + + documents + Resources + api/documents/<identifier>/data + <follows document> + + + +

+ The data content of the analytical represantations can be modified by providing a + date query parameter. This requires that the analytical + resource is set up for relative periods for the period dimension. + + Data query parameters + + + + + + + Query parameter + Value + Description + + + + + date + Date in yyyy-MM-dd format + Basis for relative periods in report (requires relative periods) + + + +

+ Some examples of valid URLs for retrieving various analytical representations are listed + below. + api/charts/R0DVGvXDUNP/data +api/charts/R0DVGvXDUNP/data?date=2013-06-01 + +api/reportTables/jIISuEWxmoI/data.html +api/reportTables/jIISuEWxmoI/data.html?date=2013-01-01 +api/reportTables/FPmvWs7bn2P/data.xls +api/reportTables/FPmvWs7bn2P/data.pdf + +api/maps/DHE98Gsynpr/data +api/maps/DHE98Gsynpr/data?date=2013-07-01 + +api/reports/OeJsA6K1Otx/data.pdf +api/reports/OeJsA6K1Otx/data.pdf?date=2012-01-01