Creating and updating objects

Creating and updating objects - For creating new objects you will need to know the endpoint, the type format, and make sure that you have the required - authorities. As an example , we will create and update an constant. To figure out the format, we - can use the new schema endpoint for getting format description (this will be further improved in - 2.16). So we will start with getting that info:http://server/api/schemas/constant.json From the output, you can see - that the required authorities for create are F_CONSTANT_ADD (which can be found in user role mgmt section), and the important - properties (for our purpose) available are: name, value. So - lets create a JSON payload and send this to the server:{ + For creating new objects you will need to know the endpoint, the type format, and make + sure that you have the required authorities. As an example , we will create and update an + constant. To figure out the format, we can use the new + schema endpoint for getting format description (this + will be further improved in 2.16). So we will start with getting that + info:http://server/api/schemas/constant.json From the output, you can see + that the required authorities for create are F_CONSTANT_ADD, and the important properties + are: name and value. + From this we can create a JSON payload and save it as a file called + constant.json:{ "name": "PI", "value": "3.14159265359" } - Or as an XML + The same content as an XML payload:<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0"> <value>3.14159265359</value> </constant> - We are now ready create this new constant by sending a POST request to the constant endpoint, let's use JSON as the example (for XML you will need to change the content-type - header):curl -X POST -d @pi.json -H "Content-Type: application/json" -u user:password http://server/api/constants + We are now ready create the new constant by sending a + POST request to the constants endpoint with the JSON + payload using + curl:curl -d @constant.json "http://server/api/constants" -X POST -H "Content-Type: application/json" -u user:password + A specific example of posting the constant to the demo + server:curl -d @constant.json "https://apps.dhis2.org/api/constants" -X POST -H "Content-Type: application/json" -u admin:district If everything went well, you should see an output similar to:{ "status":"SUCCESS", @@ -645,7 +652,7 @@ To perform functional testing we will use the cURL tool () which provides an easy way of transferring data using HTTP. First we save the data value set XML content in a file called datavalueset.xml . From the directory where this file resides we invoke the following from the command line: - curl -d @datavalueset.xml "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -u admin:district -v + curl -d @datavalueset.xml "https://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 through the -u flag. @@ -671,7 +678,7 @@ ] } 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 + curl -d @datavalueset.xml "https://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"/> @@ -714,7 +721,7 @@ 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 + https://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"> @@ -780,7 +787,7 @@ This example will show how to send individual data values to be saved in a request. This can be achieved by sending a POST request to the dataValues resource: - http://apps.dhis2.org/demo/api/dataValues + https://apps.dhis2.org/demo/api/dataValues The following query parameters are supported for this resource: Data values query parameters @@ -849,16 +856,16 @@ Conflict status code and descriptive text message. If the operation lead to a saved or updated value, 200 OK will be returned. An example of a request looks like this: - curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12" -X POST -u admin:district -v + curl "https://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12" -X POST -u admin:district -vThis resource also allows a special syntax for associating the value to an attribute option combination. This can be done by sending the identifier of the attribute combination, together with the identifier(s) of the attribute option(s) which the value represents within the combination. An example looks like this: - curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&ou=DiszpKrYNg8&pe=201308&cc=dzjKKQq0cSO&cp=wbrDrL2aYEc;btOyqprQ9e8&value=26" -X POST -u admin:district -v + curl "https://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&ou=DiszpKrYNg8&pe=201308&cc=dzjKKQq0cSO&cp=wbrDrL2aYEc;btOyqprQ9e8&value=26" -X POST -u admin:district -vYou can retrieve a data value with a request using the GET method. The value, comment and followUp params are not applicable in this regard: - curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s" -X GET -u admin:district -v + curl "https://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s" -X GET -u admin:district -vYou can delete a data value with a request using the DELETE method. @@ -891,7 +898,7 @@

It is assumed that we have posted data values to DHIS according to the previous section called "Sending data values". We can now put together our request and send it using cURL: - curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/xml" -u admin:district -v + curl "https://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/xml" -u admin:district -v The response will look something like this: HTTP/1.1 200 OK Content-Type: application/xml @@ -908,7 +915,7 @@ </dataValueSet> 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. You can also request the same data with a JSON - payload:curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/json" -u admin:district -v + payload:curl "https://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/json" -u admin:district -v The response will look something like this:{ "dataSet": "pBOMPrpg1QX", @@ -968,7 +975,7 @@ The dataSet and orgUnit parameters can be repeated in order to include multiple data sets and organisation units. An example request looks like this: - curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt&startDate=2013-01-01&endDate=2013-01-31& + curl "https://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt&startDate=2013-01-01&endDate=2013-01-31& orgUnit=YuQRtpLP10I&orgUnit=vWbkYPRmKyS&children=true" -H "Accept:application/xml" -u admin:district -v You can get the response in xml and csv format. You can indicate which response format you prefer through the Accept HTTP header like in the example above. @@ -1007,7 +1014,7 @@ To perform some testing we can save the XML payload as a file called event.xml and send it as a POST request to the events resource in the API using curl with the following command: - curl -d @event.xml "http://apps.dhis2.org/demo/api/events" -H "Content-Type:application/xml" -u admin:district -v + curl -d @event.xml "https://apps.dhis2.org/demo/api/events" -H "Content-Type:application/xml" -u admin:district -v The same payload in JSON format looks like this: { "program": "eBAyeGv0exc", @@ -1338,7 +1345,7 @@ The dataSet and orgUnit parameters can be repeated in order to include multiple data sets and organisation units. An example request looks like - this:curl "http://apps.dhis2.org/dev/api/completeDataSetRegistrations?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt&startDate=2013-01-01&endDate=2013-01-31 + this:curl "https://apps.dhis2.org/dev/api/completeDataSetRegistrations?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt&startDate=2013-01-01&endDate=2013-01-31 &orgUnit=YuQRtpLP10I&orgUnit=vWbkYPRmKyS&children=true" -H "Accept:application/xml" -u admin:district -v You can get the response in xml and json format. You can indicate which response format you prefer @@ -1677,7 +1684,7 @@ </users> </message> To test this we save the XML content into a file called message.xml. We use cURL to dispatch the message the the DHIS 2 demo instance where we indicate that the content-type is XML and authenticate as the admin user: - curl -d @message.xml "http://apps.dhis2.org/demo/api/messageConversations" -H "Content-Type:application/xml" -u admin:district -X POST -v + curl -d @message.xml "https://apps.dhis2.org/demo/api/messageConversations" -H "Content-Type:application/xml" -u admin:district -X POST -v A corresponding payload in JSON and POST command look like this: { "subject": "Hey", @@ -1702,20 +1709,20 @@ ] } - curl -d @message.json "http://apps.dhis2.org/demo/api/messageConversations" -H "Content-Type:application/json" -u admin:district -X POST -v + curl -d @message.json "https://apps.dhis2.org/demo/api/messageConversations" -H "Content-Type:application/json" -u admin:district -X POST -v If all is well we receive a 201 Created HTTP status code. Also note that we receive a Location HTTP header which value informs us of the URL of the newly created message conversation resource - this can be used by a consumer to perform further action. We will now pretend to be the mobile user and read the message which was just sent by dispatching a GET request to the messageConversations resource. We supply an Accept header with application/xml as the value to indicate that we are interested in the XML resource representation and we authenticate as the mobile user: - curl "http://apps.dhis2.org/demo/api/messageConversations" -H "Accept:application/xml" -u mobile:district -X GET -v + curl "https://apps.dhis2.org/demo/api/messageConversations" -H "Accept:application/xml" -u mobile:district -X GET -v In response we get the following XML: <messageConversations xmlns="http://dhis2.org/schema/dxf/2.0" - link="http://apps.dhis2.org/demo/api/messageConversations"> + link="https://apps.dhis2.org/demo/api/messageConversations"> <messageConversation name="Mortality data reporting" id="ZjHHSjyyeJ2" - link="http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2"/> + link="https://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2"/> <messageConversation name="DHIS version 2.7 is deployed" id="GDBqVfkmnp2" - link="http://apps.dhis2.org/demo/api/messageConversations/GDBqVfkmnp2"/> + link="https://apps.dhis2.org/demo/api/messageConversations/GDBqVfkmnp2"/> </messageConversations> From the response we are able to read the identifier of the newly sent message which is ZjHHSjyyeJ2. Note that the link to the specific resource is embedded and can be followed in order to read the full message. From the description at we learned that we can reply directly to an existing message conversation once we know the URL by including the message text as the request payload (body). We are now able to construct a URL for sending our reply: - curl -d "Yes the Mortality data set has been reported" "http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2" -H "Content-Type:text/plain" -u mobile:district -X POST -v + curl -d "Yes the Mortality data set has been reported" "https://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2" -H "Content-Type:text/plain" -u mobile:district -X POST -v If all went according to plan you will receive a 200 OK status code.

Creating, updating and removing interpretation comments @@ -1950,16 +1957,18 @@ In this example we will see how we can embed good-looking, light-weight html pivot tables with data served from a DHIS back-end into a Web page. To accomplish this we will use the Pivot table 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 having a look at what the complete html file could look like. This setup puts two tables in our web page. The first one is referring to an existing table. The second is configured inline. - <!DOCTYPE html> + We start by having a look at what the complete html file could look like. This setup puts two + tables in our web page. The first one is referring to an existing table. The second is + configured inline. + <!DOCTYPE html> <html> <head> <link rel="stylesheet" type="text/css" href="http://dhis2-cdn.org/v215/ext/resources/css/ext-plugin-gray.css" /> - <script src="http://dhis2-cdn.org/v215/ext/ext-all.js"></script> - <script src="http://dhis2-cdn.org/v215/plugin/table.js"></script> + <script src="https://dhis2-cdn.org/v215/ext/ext-all.js"></script> + <script src="https://dhis2-cdn.org/v215/plugin/table.js"></script> <script> - var base = "http://apps.dhis2.org/demo"; + var base = "https://apps.dhis2.org/demo"; // Login - if OK, call the setLinks function @@ -2011,7 +2020,7 @@ <div id="table2"></div> </body> </html> - + Three files are included in the header section of the HTML document. The first two files are the Ext JS javascript library (we use the DHIS 2 content delivery network in @@ -2021,7 +2030,7 @@ <script src="http://dhis2-cdn.org/v215/ext/ext-all.js"></script> <script src="http://dhis2-cdn.org/v215/plugin/table.js"></script> To authenticate with the DHIS server we use the same approach as in the previous section. In the header of the HTML document we include the following Javascript inside a script element. The setLinks method will be implemented later. Make sure the base variable is pointing to your DHIS installation. - var base = "http://apps.dhis2.org/demo/"; + var base = "https://apps.dhis2.org/demo/"; Ext.onReady( function() { Ext.Ajax.request({ @@ -2196,8 +2205,10 @@ 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 having a look at what the complete html file could look like. This setup puts two charts in our web page. The first one is referring to an existing chart. The second is configured inline. - <!DOCTYPE html> + We start by having a look at what the complete html file could look like. This setup puts two + charts in our web page. The first one is referring to an existing chart. The second is + configured inline. + <!DOCTYPE html> <html> <head> <link rel="stylesheet" type="text/css" href="http://dhis2-cdn.org/v215/ext/resources/css/ext-plugin-gray.css" /> @@ -2205,7 +2216,7 @@ <script src="http://dhis2-cdn.org/v215/plugin/chart.js"></script> <script> - var base = "http://apps.dhis2.org/demo"; + var base = "https://apps.dhis2.org/demo"; // Login - if OK, call the setLinks function @@ -2258,7 +2269,7 @@ <div id="chart2"></div> </body> </html> - + Three files are included in the header section of the HTML document. The first two files are the Ext JS javascript library (we use the DHIS 2 content delivery network in @@ -2268,7 +2279,7 @@ <script src="http://dhis2-cdn.org/v215/ext/ext-all.js"></script> <script src="http://dhis2-cdn.org/v215/plugin/chart.js"></script> To authenticate with the DHIS server we use the same approach as in the previous section. In the header of the HTML document we include the following Javascript inside a script element. The setLinks method will be implemented later. Make sure the base variable is pointing to your DHIS installation. - var base = "http://apps.dhis2.org/demo/"; + var base = "https://apps.dhis2.org/demo/"; Ext.onReady( function() { Ext.Ajax.request({ @@ -2479,9 +2490,10 @@

Embedding maps with the GIS map plug-in In this example we will see how we can embed maps with data served from a DHIS back-end into a Web page. To accomplish this we will use the GIS map 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 having a look at what the complete html file could look like. This setup puts two maps in our web page. The first one is referring to an existing map. The second is configured inline. - - <!DOCTYPE html> + We start by having a look at what the complete html file could look like. This setup puts two + maps in our web page. The first one is referring to an existing map. The second is + configured inline. + <!DOCTYPE html> <html> <head> <link rel="stylesheet" type="text/css" href="http://dhis2-cdn.org/v215/ext/resources/css/ext-plugin-gray.css" /> @@ -2491,7 +2503,7 @@ <script src="http://dhis2-cdn.org/v215/plugin/map.js"></script> <script> - var base = "http://apps.dhis2.org/demo"; + var base = "https://apps.dhis2.org/demo"; // Login - if OK, call the setLinks function @@ -2772,10 +2784,10 @@ 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://dhis2-cdn.org/v213/ext/resources/css/ext-plugin-gray.css" /> -<link rel="stylesheet" type="text/css" href="http://apps.dhis2.org/demo/dhis-web-commons/javascripts/ext-ux/carousel/css/carousel.css" /> -<script type="text/javascript" src="http://extjs-public.googlecode.com/svn/tags/extjs-4.0.7/release/ext-all.js"></script> -<script type="text/javascript" src="http://apps.dhis2.org/demo/dhis-web-commons/javascripts/ext-ux/carousel/Carousel.js"></script> -<script type="text/javascript" src="http://apps.dhis2.org/demo/dhis-web-commons/javascripts/plugin/plugin.js"></script> +<link rel="stylesheet" type="text/css" href="https://apps.dhis2.org/demo/dhis-web-commons/javascripts/ext-ux/carousel/css/carousel.css" /> +<script type="text/javascript" src="https://extjs-public.googlecode.com/svn/tags/extjs-4.0.7/release/ext-all.js"></script> +<script type="text/javascript" src="https://apps.dhis2.org/demo/dhis-web-commons/javascripts/ext-ux/carousel/Carousel.js"></script> +<script type="text/javascript" src="https://apps.dhis2.org/demo/dhis-web-commons/javascripts/plugin/plugin.js"></script> The first file is the CSS stylesheet for the chart plug-in. The second file is the CSS stylesheet for the carousel widget. The third file is the Ext JavaScript framework which this plug-in depends on. The fourth file is the carousel plug-in JavaScript file. The fifth file is the chart plug-in JavaScript file. The paths in this example points at the DHIS 2 demo site, make sure you update them to point to your own DHIS 2 installation. Please refer to the section about the chart plug-in on how to do authentication. To create a chart carousel we will first render the charts we want to include in the carousel using the method described in the chart plug-in section. Then we create the chart carousel itself. The charts will be rendered into div elements which all have a CSS class called chart. In the carousel configuration we can then define a selector expression which refers to those div elements like this: @@ -2817,7 +2829,7 @@ 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. You can first look up the SQL view from the api/sqlViews resource, then POST using the following command: - curl "http://apps.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/execute" -X POST -u admin:district -v + curl "https://apps.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/execute" -X POST -u admin:district -v The next step in the process is the retrieval of the data.The basic structure of the URL is as follows http://{server}/api/sqlViews/{id}/data(.csv) The {server} parameter should be replaced with your own server. The @@ -2826,13 +2838,13 @@ 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 + above.curl "https://apps.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv" -u admin:district -v You can do simple filtering on the columns in the result set by appending criteria query parameters to the URL, using the column names and filter values separated by columns as parameter values, on the following format: /data?criteria=col1:value1&criteria=col2:value2 As an example, to filter the SQL view result set above to only return organisation units at level 4 you can use the following URL: - http://apps.dhis2.org/dev/api/sqlViews/dI68mLkP1wN/data.csv?criteria=level:4 + https://apps.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv?criteria=level:4

Dashboard @@ -2867,7 +2879,7 @@ "chart": { "name": "ANC: Visits by facility type", "created": "2013-05-30T09:58:42.023+0000", - "href": "http://apps.dhis2.org/demo/api/charts/iRCGbznvyG8", + "href": "https://apps.dhis2.org/demo/api/charts/iRCGbznvyG8", "id": "iRCGbznvyG8" }, "map": null, @@ -2885,12 +2897,12 @@ "reports": [{ "name": "ANC: 1st Visit Cumulative Chart", "created": "2012-11-13T13:49:45.007+0000", - "href": "http://apps.dhis2.org/demo/api/reports/Kvg1AhYHM8Q", + "href": "https://apps.dhis2.org/demo/api/reports/Kvg1AhYHM8Q", "id": "Kvg1AhYHM8Q" }, { "name": "ANC: Coverages This Year", "created": "2012-11-13T13:52:01.630+0000", - "href": "http://apps.dhis2.org/demo/api/reports/qYVNH1wkZR0", + "href": "https://apps.dhis2.org/demo/api/reports/qYVNH1wkZR0", "id": "qYVNH1wkZR0" }], "type": "reports",