DHIS2 Developer guide

2.29

Warranty:  THIS DOCUMENT IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS MANUAL AND PRODUCTS MENTIONED HEREIN, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License:  Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the source of this documentation, and is available here online: http://www.gnu.org/licenses/fdl.html.

Revision History
Revision HEAD@32cd8a22017-10-13 13:09:40
Version 2.29

Table of Contents

1. Web API
1.1. Introduction
1.2. Authentication
1.2.1. Basic Authentication
1.2.2. OAuth2
1.3. Error and info messages
1.4. Date and period format
1.5. Identifier schemes
1.6. Browsing the Web API
1.6.1. Translation
1.6.2. Translation API
1.6.3. Web API versions
1.7. Metadata object filter
1.7.1. Logical operators
1.8. Metadata field filter
1.8.1. Field transformers
1.9. Metadata create, read, update, delete, validate
1.9.1. Create / update parameters
1.9.2. Creating and updating objects
1.9.3. Deleting objects
1.9.4. Adding and removing objects in collections
1.9.5. Validating payloads
1.9.6. Partial updates
1.10. Metadata export
1.10.1. Metadata export examples
1.10.2. Metadata export with dependencies
1.11. Metadata import
1.12. Metadata audit
1.13. AMQP/RabbitMQ integration
1.14. CSV metadata import
1.14.1. Data elements
1.14.2. Organisation units
1.14.3. Validation rules
1.14.4. Option sets
1.14.5. Collection membership
1.14.6. Other objects
1.15. Deleted objects
1.16. File resources
1.16.1. File resource constraints
1.17. Metadata versioning
1.17.1. Get metadata version examples
1.17.2. Get list of all metadata versions
1.17.3. Create metadata version
1.17.4. Download version metadata
1.18. Metadata Synchronization
1.18.1. Sync metadata version
1.19. Data values
1.19.1. Sending data values
1.19.2. Sending bulks of data values
1.19.3. Import parameters
1.19.4. CSV data value format
1.19.5. Generating data value set template
1.19.6. Reading data values
1.19.7. Sending, reading and deleting individual data values
1.20. ADX data format
1.20.1. The adx root element
1.20.2. The group element
1.20.3. ADX period definitions
1.20.4. Data values
1.20.5. Importing data - HTTP POST
1.20.6. Exporting data - HTTP GET
1.21. Events
1.21.1. Sending events
1.21.2. CSV Import / Export
1.21.3. Querying and reading events
1.22. Program rules
1.22.1. Program rule model
1.22.2. Creating program rules
1.23. Forms
1.24. Validation
1.25. Validation Results
1.26. Data integrity
1.26.1. Running data integrity
1.26.2. Fetching the result
1.27. Indicators
1.27.1. Aggregate indicators
1.27.2. Program indicators
1.27.3. Expressions
1.28. Complete data set registrations
1.28.1. Completing data sets
1.28.2. Reading complete data set registrations
1.28.3. Un-completing data sets
1.29. Data approval
1.29.1. Get approval status
1.29.2. Approve data
1.29.3. Bulk approve data
1.30. Auditing
1.30.1. Aggregate data value audits
1.30.2. Tracked entity data value audits
1.30.3. Tracked entity attribute value audits
1.30.4. Data approval audits
1.31. Message conversations
1.31.1. Writing and reading messages
1.31.2. Managing messages
1.31.3. Tickets
1.32. Interpretations
1.32.1. Reading interpretations
1.32.2. Writing interpretations
1.32.3. Updating and removing interpretations
1.32.4. Creating interpretation comments
1.32.5. Updating and removing interpretation comments
1.32.6. Liking interpretations
1.33. Viewing analytical resource representations
1.34. Plugins
1.34.1. Embedding pivot tables with the Pivot Table plug-in
1.34.2. Embedding charts with the Visualizer chart plug-in
1.34.3. Embedding maps with the GIS map plug-in
1.34.4. Creating a chart carousel with the carousel plug-in
1.35. SQL views
1.35.1. Criteria
1.35.2. Variables
1.35.3. Filtering
1.36. Dashboard
1.36.1. Browsing dashboards
1.36.2. Searching dashboards
1.36.3. Creating, updating and removing dashboards
1.36.4. Adding, moving and removing dashboard items and content
1.37. Analytics
1.37.1. Request query parameters
1.37.2. Dimensions and items
1.37.3. The dx dimension
1.37.4. Response formats
1.37.5. Constraints
1.37.6. Data value set format
1.37.7. Raw data format
1.37.8. Debugging
1.38. Event analytics
1.38.1. Dimensions and items
1.38.2. Request query parameters
1.38.3. Event query analytics
1.38.4. Event aggregate analytics
1.38.5. Event clustering analytics
1.38.6. Event count and extent analytics
1.39. Data set report
1.40. Push Analysis
1.41. Data usage analytics
1.41.1. Request query parameters
1.41.2. Create view events (POST)
1.41.3. Retrieve aggregated usage analytics report (GET)
1.41.4. Retrieve top favorites
1.41.5. Response format
1.41.6. Retrieve statistics for a favorite
1.42. Geospatial features
1.42.1. GeoJSON
1.43. Generating resource and analytics tables
1.44. Maintenance
1.45. System resource
1.45.1. Generate identifiers
1.45.2. View system information
1.45.3. Check if username and password combination is correct
1.45.4. View asynchronous task status
1.45.5. Get appearance information
1.46. Locales
1.46.1. UI locales
1.46.2. Database content locales
1.47. Translations
1.47.1. Create translation
1.47.2. Get translations
1.48. Short Message Service (SMS)
1.48.1. Outbound SMS service
1.48.2. Inbound SMS service
1.48.3. Gateway service administration
1.48.4. Gateway configuration
1.49. SMS Commands
1.49.1. API End Points
1.50. Program Messages
1.50.1. Sending program messages
1.50.2. Retrieving and deleting program messages
1.50.3. Querying program messages
1.51. Users
1.51.1. User query
1.51.2. User credentials query
1.51.3. User account create and update
1.51.4. User account invitations
1.51.5. User replication
1.52. Current user information and associations
1.53. System settings
1.54. User settings
1.55. Organisation units
1.55.1. Get list of organisation units
1.55.2. Get organisation unit with relations
1.56. Data sets
1.56.1. DataSet Notification Template
1.57. Filled organisation unit levels
1.58. Static content
1.59. Configuration
1.60. Read-Only configuration service
1.61. Internationalization
1.62. SVG conversion
1.63. Tracked entity instance management
1.63.1. Creating a new tracked entity instance
1.63.2. Updating a tracked entity instance
1.63.3. Deleting a tracked entity instance
1.63.4. Enrolling a tracked entity instance into a program
1.63.5. Update strategies
1.63.6. Create and enroll tracked entity instances
1.63.7. Generated tracked entity instance attributes
1.64. Tracked entity instance query
1.64.1. Request syntax
1.64.2. Response format
1.65. Tracked entity instance grid query
1.65.1. Request syntax
1.65.2. Response format
1.66. Enrollment instance query
1.66.1. Request syntax
1.66.2. Response format
1.67. Tracker bulk deletion
1.68. Email
1.68.1. System notification
1.68.2. Outbound emails
1.68.3. Test message
1.69. Sharing
1.69.1. Get sharing status
1.69.2. Set sharing status
1.70. Scheduling
1.71. Schema
1.72. UI customization
1.72.1. Javascript
1.72.2. CSS
1.73. Synchronization
1.73.1. Data push
1.73.2. Metadata pull
1.73.3. Availability check
1.74. Apps
1.74.1. Get apps
1.74.2. Install an app
1.74.3. Delete an app
1.74.4. Reload apps
1.74.5. Apps shared between instances
1.75. App store
1.75.1. Get apps
1.75.2. Install apps
1.76. Data store
1.76.1. Data store structure
1.76.2. Get keys and namespaces
1.76.3. Create values
1.76.4. Update values
1.76.5. Delete keys
1.77. User data store
1.77.1. User data store structure
1.77.2. Get namespaces
1.77.3. Get keys
1.77.4. Get value
1.77.5. Create value
1.77.6. Update existing value
1.77.7. Delete key
1.77.8. Delete namespace
1.78. Predictors
1.78.1. Creating a predictor
1.78.2. Generating predicted values
1.79. Min-max data elements
1.79.1. Add/Update min-max data element
1.79.2. Delete min-max data element
1.80. Lock exceptions
1.81. Tokens
1.81.1. Google Service Account
1.82. Metadata repository
2. Apps
2.1. Purpose of packaged Apps
2.2. Creating Apps
2.3. Installing Apps into DHIS2
2.4. Launching Apps
3. Development Infrastructure
3.1. Release process
4. DHIS2 Technical Architecture
4.1. Overview
4.2. Technical Requirements
4.3. Project Structure
4.4. Project Dependencies
4.5. The Data Model
4.6. The Persistence Layer
4.7. The Business Layer
4.7.1. The JDBC Service Project
4.7.2. The Reporting Project
4.7.3. The External Project
4.7.4. The System Support Project
4.8. The Presentation Layer
4.8.1. The Portal
4.9. Definitions
A. DHIS2 and R integration
A.1. Introduction
A.2. Installing R
A.3. Using ODBC to retrieve data from DHIS2 into R
A.4. Using R with MyDatamart
A.5. Mapping with R and PostgreSQL
A.6. Using R, DHIS2 and the Google Visualization API
A.7. Using PL/R with DHIS2
A.8. Using this DHIS2 Web API with R

List of Figures

4.1. Data values
4.2. Core Diagram

List of Tables

1.1. WebMessage properties
1.2. Period format
1.3. Scheme Values
1.4. Query parameters
1.5. Translate options
1.6. Available Operators
1.7. Property operators
1.8. Field presets
1.9. Available Transformers
1.10. Available Query Filters
1.11. Export Parameter
1.12. Import Parameter
1.13. Data Element CSV Format
1.14. Organisation Unit CSV Format
1.15. Validation Rule CSV Format
1.16. Option Set CSV Format
1.17. Collection membership CSV Format
1.18. Data Element Group, Category Option, Category Option Group, Organisation Unit Group CSV Format
1.19. Query Parameters
1.20. Query Parameters
1.21. Query Parameters
1.22. Path parameters
1.23. Query parameters
1.24. Import parameters
1.25. Value type requirements
1.26. CSV format of DHIS2
1.27. Data values query parameters
1.28. Data value set query parameters
1.29. Data values query parameters
1.30. ADX Periods
1.31. Events resource format
1.32. Import parameters
1.33. CSV column
1.34. Events resource query parameters
1.35. programRule
1.36. programRuleAction
1.37. programRuleVariable
1.38. Form query parameters
1.39. Operators
1.40. Missing value strategies
1.41. Indicator variables
1.42. Program indicator variables
1.43. Complete data set registrations query parameters
1.44. Data value set query parameters
1.45. Complete data set registrations query parameters
1.46. Data approval query parameters
1.47. Data approval query parameters
1.48. Data approval states
1.49. Data approval action parameters
1.50. Aggregate data value query parameters
1.51. Tracked entity data value query parameters
1.52. Tracked entity attribute value query parameters
1.53. Data approval query parameters
1.54. A list of valid status and priority values
1.55. Interpretation fields
1.56. Analytical resources
1.57. Data query parameters
1.58. Query parameters for png / image types (charts, maps)
1.59. Pivot table plug-in configuration
1.60. Pivot table configuration
1.61. Chart plug-in configuration
1.62. Chart configuration
1.63. GIS map plug-in configuration
1.64. Map plug-in configuration
1.65. Items content parameters
1.66. Query parameters
1.67. Dimensions and dimension items
1.68. Data dx dimension types
1.69. Query parameters
1.70. Event dimensions
1.71. Query parameters for both event query and aggregate analytics
1.72. Query parameters for event query analytics only
1.73. Query parameters for aggregate event analytics only
1.74. Query parameters for cluster event analytics only
1.75. Filter operators
1.76. Accepted parameters of /dataSetReport resource
1.77. Push analysis properties
1.78. Supported event types
1.79. Query parameters for aggregated usage analytics (data statistics)
1.80. Query parameters for top favorites
1.81. Geo features response
1.82. Analytics tables optional query parameters
1.83. HTTP Status codes
1.84. Task categories
1.85. Property names
1.86. Class names
1.87. Gateway response codes
1.88. User query parameters
1.89. Gateway api end points
1.90. Program message payload
1.91. Query program messages API
1.92. User query parameters
1.93. System settings
1.94. User settings
1.95. Organisation units query parameters
1.96. Organisation unit parameters
1.97. Static content keys
1.98. Configuration values
1.99. SettingType values
1.100. Query parameters
1.101. Available tracker strategies
1.102. Tracked entity reserved values
1.103. Tracked entity instances query parameters
1.104. Organisation unit selection modes
1.105. Filter operators
1.106. Tracked entity instances query parameters
1.107. Organisation unit selection modes
1.108. Filter operators
1.109. Tracked entity instances query parameters
1.110. Organisation unit selection modes
1.111. Task strategies
1.112. Data store structure
1.113. User data store structure
1.114. Min-max data element data structure
1.115. Token response
2.1. App types

List of Examples

1.1.