dhis2 2.3.8 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 31237affd866d0b4d8f2f3d206ee0f4e87fc0887
-  data.tar.gz: 3342245ed20209d6cf8d14b43b6afd84c1a2195f
+  metadata.gz: bbd753676f45e7c6c2463428dae5bc1efd78ece2
+  data.tar.gz: f6fb3aba7601265b2671cecfb7f278f1d3635c2a
 SHA512:
-  metadata.gz: 7b92380e27981c30c95779d27b2cfa9310280c29e672859428a638e7bd1f801ca27d4c1106d8ba3ae9cda577e7785f575d43c9dde777a725576cda4047100b39
-  data.tar.gz: a0cd65724a439e6467aac2673bf21bc853cb1ebdc0d21ca3d2dafccb0a1be7c7db0e4a3719bf3372b2a98e814a318e842bc3c8746965f20b893c31a15305c8f3
+  metadata.gz: a319ce37b00057817630ddd0929e6abfaa711e71dddccdd6ac39e86326c0529860092fe12a93f8d28edef621ca732f52ad2336c1aa126a5c6daa5cd90c614bd4
+  data.tar.gz: cc02f664d800aa80ce1768336614dc2d2ca6fced9151118c823d2f3d3c43ba51ea17829f3db729f49726395da592df1ebdf5ac2eece873f21ed6ab0d129f2b3c

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Self proof reading checklist
+
+- [ ] Did I run Pronto and fixed all warnings
+- [ ] Make sure all naming and code will remain understandable in 6 month by someone new to the project or by you.
+- [ ] Did I test the right thing?
+- [ ] Did I test corner cases, non happy path (defensive testing)?
+- [ ] Check that I used the ad-hoc patterns and created files accordingly (Presenters, Services, Search object, Form object,...)
+- [ ] Check code efficiency with record intensive project (eg: DRC)
+- [ ] Update documentation,readme accordingly
+
+Thanks!

data/Gemfile

@@ -1,4 +1,5 @@
-source 'https://rubygems.org'
+# frozen_string_literal: true
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in dhis2.gemspec
 gemspec

data/README.md

@@ -32,102 +32,189 @@ The functionalities are available as a module. First thing you need to do is to
 
 * Global configuration (to call a single Dhis2 instance):
 
-  ```ruby
-  Dhis2.configure do |config|
-    config.url      = "https://play.dhis2.org/demo"
-    config.user     = "admin"
-    config.password = "district"
-  end
-  Dhis2.client.data_elements.list # => Array[<DataElement>,..]
-
-  # Or alternatively
-  Dhis2.configure do |config|
-    config.url = "https://admin:district@play.dhis2.org/demo"
-  end
-  Dhis2.client.data_elements.list # => Array[<DataElement>,..]
-  ```
+```ruby
+Dhis2.configure do |config|
+  config.url      = "https://play.dhis2.org/2.28"
+  config.user     = "admin"
+  config.password = "district"
+  config.version  = "2.28"
+end
+::Dhis2.client.data_elements.list # => Array[<DataElement>,..]
+
+# Or alternatively
+::Dhis2.configure do |config|
+  url:     "https://admin:district@play.dhis2.org/2.28",
+  version: "2.28"
+)
+::Dhis2.clientt.data_elements.list # => Array[<DataElement>,..]
+```
 
 * Local configuration: (in case you need to access different Dhis2 instances inside a single project):
 
-  ```ruby
-  client = Dhis2::Client.new(url: "https://play.dhis2.org/demo", user: "admin", password: "district")
-  client.data_elements.list # => Array[<DataElement>,..]
-
-  # Or alternatively
-  client = Dhis2::Client.new("https://admin:district@play.dhis2.org/demo")
-  client.data_elements.list # => Array[<DataElement>,..]
-  ```
+```ruby
+configuration = Dhis2::Configuration.new.tap do |config|
+  config.url      = "https://play.dhis2.org/2.28"
+  config.user     = "admin"
+  config.password = "district"
+  config.version  = "2.28"
+end
+client = ::Dhis2::Client.new(configuration.client_params)
+client.data_elements.list # => Array[<DataElement>,..]
+
+# Or alternatively
+client = ::Dhis2::Client.new(
+  url:     "https://admin:district@play.dhis2.org/2.28",
+  version: "2.28"
+)
+client.data_elements.list # => Array[<DataElement>,..]
+```
 
 Regarding SSL, there is an option to disregard SSL error messages (such as bad certificates). USE THIS AT YOUR OWN RISK - it may allow you to access a server that would return in error without it... but you cannot trust the response.
 
 ```ruby
-  dangerous_client = Dhis2::Client.new(url: "https://play.dhis2.org/demo", user: "admin", password: "district", no_ssl_verification: true);
+dangerous_configuration = Dhis2::Configuration.new.tap do |config|
+  config.url      = "https://play.dhis2.org/2.28"
+  config.user     = "admin"
+  config.password = "district"
+  config.version  = "2.28"
+  config.no_ssl_verification = true
+end
+```
+
+* Not sure of your version? Check it
+
+```ruby
+Dhis2.get_version({ user: 'admin', password: 'district', url: 'https://play.dhis2.org/demo'})
 ```
 
+
 ### Search for meta elements
 
 All subsequent calls can be done on the objects themselves and are going to use the provided url and credentials
 
-    org_unit_levels = Dhis2.client.organisation_unit_levels.list
+```ruby
+org_unit_levels = Dhis2.client.organisation_unit_levels.list
+```
 
 The various methods are taking an optional hash parameter to be used for ´filter´ and ´fields´ values:
 
-    org_units = Dhis2.client.organisation_units.list(filter: "level:eq:2", fields: %w(id level displayName parent))
+```ruby
+org_units = Dhis2.client.organisation_units.list(filter: "level:eq:2", fields: %w(id level displayName parent))
+```
 
 If you want all fields, simply specify `:all`
 
-    org_units = Dhis2.client.organisation_units.list(filter: "level:eq:2", fields: :all)
+```ruby
+org_units = Dhis2.client.organisation_units.list(filter: "level:eq:2", fields: :all)
+```
 
 Notes that any field found in the resulting JSON will be accessible from the object.
 
+### Raw data
+
+By default, the gem transforms data from the api so you get underscore case. But this may not be needed and can hurt performance.
+
+If you simply need raw data from your Dhis2:
+
+```ruby
+org_units = Dhis2.client.organisation_units.list({}, true)
+```
+
 ### Pagination
 
 Following the DHIS2 API, all calls are paginated - you can access the page info using the `pager` property on the returned list:
 
-    org_units = Dhis2.client.organisation_units.list(filter: "level:eq:2", fields: %w(id level displayName parent))
-    org_units.pager.page       # current page
-    org_units.pager.page_count # number of pages
-    org_units.pager.total      # number of records
+```ruby
+org_units = Dhis2.client.organisation_units.list(filter: "level:eq:2", fields: %w(id level displayName parent))
+org_units.pager.page       # current page
+org_units.pager.page_count # number of pages
+org_units.pager.total      # number of records
+```
+
+### Get all paginated elements
+
+It can be tedious to iterate over a paginated collection. Thus you can use `fetch_paginated_data` which will get all pages for you and yield each element automatically.
+
+```ruby
+Dhis2.client.organisation_units.fetch_paginated_data(
+  filter: "level:eq:2",
+  fields: %w(id level displayName parent)
+).each do |organisation_unit, pager|
+  # do what you need here
+end
+
+# If you want pagination info in the loop:
+Dhis2.client.organisation_units.fetch_paginated_data({
+  filter: "level:eq:2",
+  fields: %w(id level displayName parent)
+},
+{ with_pager: true}
+).each do |organisation_unit, pager|
+  # do what you need here
+end
+
+# Dhis2.client.organisation_units.fetch_paginated_data is an Enumerable. If you want all objects in an array, without pager:
+Dhis2.client.organisation_units.fetch_paginated_data.to_a
 
 ### Retrieve a single element
 
 You can also retreive a single element using its id with `find`(in this case, all fields are returned by default):
 
-    ou = Dhis2.client.organisation_units.find(id)
+```ruby
+ou = Dhis2.client.organisation_units.find(id)
+```
 
 `find` also accepts multiple ids - query will not be paginated and will return all fields for the given objects:
 
-    ous = Dhis2.client.organisation_units.find([id1, id2, id3])
+```ruby
+ous = Dhis2.client.organisation_units.find([id1, id2, id3])
+```
+
+An issue could arise if you try to get too many elements at once.
+
+```ruby
+ous = Dhis2.client.organisation_units.find(super_long_array)
+#=> would raise an exception because the generated url would be too long
+
+# instead do
+ous = Dhis2.client.organisation_units.find_paginated(super_long_array)
+```
 
 If you have an equality condition or set of equality conditions that should return a single element, you can use `find_by` instead of the longer list option:
 
-    # Instead of this:
-    data_element = Dhis2.client.data_elements.list(filter: "code:eq:C27", fields: :all).first
+```ruby
+# Instead of this:
+data_element = Dhis2.client.data_elements.list(filter: "code:eq:C27", fields: :all).first
 
-    # Just do:
-    data_element = Dhis2.client.data_elements.find_by(code: "C27")
+# Just do:
+data_element = Dhis2.client.data_elements.find_by(code: "C27")
+```
 
 ### Manage relations
 
 You can add or remove items in collections using `add_relation` and `remove_relation`:
 
-    data_set = Dhis2.client.data_sets.list(page_size:1).first
-    data_element = Dhis2.client.data_elements.list(page_size: 1).first
-    data_set.add_relation(:dataSetElements, data_element.id)
-    ...
-    data_set.remove_relation(:dataSetElements, data_element.id)
+```ruby
+data_set = Dhis2.client.data_sets.list(page_size:1).first
+data_element = Dhis2.client.data_elements.list(page_size: 1).first
+data_set.add_relation(:dataSetElements, data_element.id)
+...
+data_set.remove_relation(:dataSetElements, data_element.id)
+```
 
 ### Values
 
 You can retreive data values this way:
 
-    ds                = Dhis2.client.data_sets.find_by(name: "Child Health")
-    organisation_unit = Dhis2.client.organisation_units.find_by(name: "Baoma")
-    period            = "201512"
-    value_sets        = Dhis2.client.data_value_sets.list(
-      data_sets: [ds.id],
-      organisation_unit: organisation_unit.id, periods: [period]
-    )
+```ruby
+ds                = Dhis2.client.data_sets.find_by(name: "Child Health")
+organisation_unit = Dhis2.client.organisation_units.find_by(name: "Baoma")
+period            = "201512"
+value_sets        = Dhis2.client.data_value_sets.list(
+  data_sets: [ds.id],
+  organisation_unit: organisation_unit.id, periods: [period]
+)
+```
 
 ## Supported items
 
@@ -161,9 +248,11 @@ The API is currently limited to actions on the following elements:
 
 You can update a given item by retreiving it using its id, making any modification on it then calling "update":
 
-    org_unit = Dhis2.client.organisation_units.find(id)
-    org_unit.short_name = "New Short Name"
-    org_unit.update
+```ruby
+org_unit = Dhis2.client.organisation_units.find(id)
+org_unit.short_name = "New Short Name"
+org_unit.update
+```
 
 This uses DHIS2 "full update" ('PUT') and not the "partial update" feature (see below), so it requires a fully formed object to work (get it either with `find` which takes all the fields or with the `fields: :all´ option).
 
@@ -171,32 +260,58 @@ This uses DHIS2 "full update" ('PUT') and not the "partial update" feature (see
 
 You can update a single or more attributes via the "update_attributes" method:
 
-    org_unit         = Dhis2.client.organisation_units.list(fields: :all, filter: "name:eq:#{org_unit_name}").first
-    new_attributes   = { name: "New name" }
-    org_unit.update_attributes(new_attributes)
+```ruby
+org_unit         = Dhis2.client.organisation_units.list(fields: :all, filter: "name:eq:#{org_unit_name}").first
+new_attributes   = { name: "New name" }
+org_unit.update_attributes(new_attributes)
+```
 
 Note that partial updates will no work with custom attributes at this time (while the full update will)
 
 ## Create
 
-A very basic **write** use case exists for `DataElement` and `DataSet`:
+A very basic **write** use case exists for `DataElement`:
+
+```ruby
+data_element = Dhis2.client.data_elements.create({
+  name: "TesTesT1",
+  short_name: "TTT1"
+})
+```
+
+We do validate arguments and the response status. `Dhis2::CreationError` exception is raised in case of error.
+
+### Bulk create
 
-    elements = [
-      { name: "TesTesT1", short_name: "TTT1" },
-      { name: "TesTesT2", short_name: "TTT2" }
-    ]
-    status = Dhis2.client.data_elements.create(elements)
-    status.success? # => true
-    status.total_imported # => 2
+Whenever you need to create many elements at the same time, you can use `bulk_create`:
 
-DHIS2 API does not return the ids of the created elements, but you can retreive them with their (unique) name or code.
+```ruby
+elements = [
+  { name: "TesTesT1", short_name: "TTT1" },
+  { name: "TesTesT2", short_name: "TTT2" }
+]
+summary = Dhis2.client.data_elements.bulk_create(elements)
+# would raise Dhis2::BulkCreationError on error
+summary.imported_count # => 1
+summary.updated_count  # => 1
+summary.ignored_count  # => 0
+```
+
+### Raw input
 
-    elements = [
-      { name: "TesTesT2", short_name: "TTT2" }
-    ]
-    status = Dhis2.client.data_elements.create(elements)
-    element = Dhis2.client.data_elements.find_by(name: "TesTesT2")
+You might have data in camel case already and need to use it as is. In this case, we do not validate your input and do not create an object out of the response. Yet we validate the object has been properly created and return the plain response from the API.
 
+```ruby
+response = Dhis2.client.data_elements.create({
+  name: "TesTesT1",
+  shortName: "TTT1"
+}, true)
+
+summary = Dhis2.client.data_elements.bulk_create([{
+  name: "TesTesT1",
+  shortName: "TTT1"
+}], true)
+```
 
 ## Trigger analytics
 
@@ -204,6 +319,31 @@ You can trigger Analytics with
 
 Dhis2.client.resource_tables.analytics
 
+## Raw output
+
+To get raw data from Dhis2, ie no underscore case, no object, just plain json, you can specify you want the raw output:
+
+```ruby
+client.data_elements.list({}, true)
+#returns a PaginatedArray which elements look like:
+{"id"=>"FTRrcoaog83", "displayName"=>"Accute Flaccid Paralysis (Deaths < 5 yrs)"}
+
+client.data_elements.fetch_paginated_data({}, { raw: true }) do |data_element|
+  # use data_element as hash
+end
+```
+
+## Instantiating objects
+
+It can be tedious to manually type `Dhis2::Api::Version228::DataElement` (or any other class) and adapt it for each version number.
+
+There is a convenient method to get it directly:
+
+```ruby
+Dhis2::DataElement["2.28"]
+#=> Dhis2::Api::Version228::DataElement
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` and `bundle exec rspec` to run the tests. Note that the tests are using the DHIS2 demo server, which is reset every day but can be updated by anyone - so if someone change the password of the default user, the tests are going to fail.

data/Rakefile

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList['test/**/*_test.rb']
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task :default => :test
+task default: :test

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "bundler/setup"
 require "dhis2"

data/changelog.md

@@ -0,0 +1,7 @@
+# Version 3
+- passing version is mandatory: we use dedicated classes for each Dhis2 versions. This lets us adapt validations, constants and methods.
+- we can get raw json from Dhis2 (skip class instantiation and case change)
+- we can send raw json to Dhis2 (skip case change and validations)
+- to complement `list`, `fetch_paginated_data` iterates over all elements requesting each page if necessary
+- `root_junction` is now an allowed query param
+- fixtures contain payload from versions 2.24 to 2.28 to help you check what data is received

data/dhis2.gemspec

@@ -1,7 +1,8 @@
 # coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'dhis2/version'
+require "dhis2/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "dhis2"
@@ -9,8 +10,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Martin Van Aken"]
   spec.email         = ["mvanaken@bluesquare.org"]
 
-  spec.summary       = %q{Simple Ruby wrapper on DHIS2 API.}
-  spec.description   = %q{Allows to retreive items from a DHIS2 server in a more "Ruby way".}
+  spec.summary       = "Simple Ruby wrapper on DHIS2 API."
+  spec.description   = 'Allows to retreive items from a DHIS2 server in a more "Ruby way".'
   spec.homepage      = "http://github.com/blsq/dhis2"
   spec.license       = "MIT"
 
@@ -19,17 +20,16 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'rest-client'
+  spec.add_dependency "rest-client"
+  spec.add_dependency "dry-validation", "0.11.1"
 
-  spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "minitest-reporters"
   spec.add_development_dependency "faker", "~> 1.6", ">= 1.6.3"
   spec.add_development_dependency "byebug"
 
   spec.add_development_dependency "rspec"
-  spec.add_development_dependency "webmock"
+  spec.add_development_dependency "webmock", "3.1.0"
   spec.add_development_dependency "simplecov"
   spec.add_development_dependency "rest-client-logger"
 end

data/lib/dhis2/api/base.rb

@@ -4,118 +4,29 @@ module Dhis2
   module Api
     class Base < OpenStruct
       class << self
-        def inherited(base)
-          Dhis2::Client.register_resource(base)
-        end
-
-        def find(client, id, options = {})
-          raise "Missing id" if id.nil?
-
-          if id.class == Array
-            list(client, filter: "id:in:[#{id.join(',')}]", fields: :all, page_size: id.size)
-          elsif options.any?
-            params = []
-            options.each do |name, value|
-              params << [name, value]
-            end
-            params        = client.class.deep_change_case(params, :camelize)
-            json_response = client.get("#{resource_name}/#{id}", RestClient::ParamsArray.new(params))
-            new(client, json_response)
-          else
-            response = client.get("#{resource_name}/#{id}")
-            new(client, response)
-          end
-        end
-
-        def find_by(client, clauses)
-          filter = []
-          clauses.each do |field, value|
-            filter << "#{field}:eq:#{value}"
-          end
-          list(client, fields: :all, filter: filter).first
-        end
-
-        def list(client, options = {})
-          json_response = client.get(resource_name, format_query_parameters(options))
-          resource_key  = client.class.underscore(resource_name)
-          PaginatedArray.new(
-            json_response[resource_key].map { |raw_resource| new(client, raw_resource) },
-            json_response["pager"]
-          )
+        def resource_key
+          Dhis2::Case.underscore(resource_name)
         end
 
         def resource_name
           simple_name = name.split("::").last
           simple_name[0].downcase + simple_name[1..-1] + "s"
         end
-
-        def format_query_parameters(options)
-          params = []
-          params.push([:page, options[:page]])                    if options[:page]
-          params.push([:pageSize, options[:page_size]])           if options[:page_size]
-          params.push([:fields, format_fields(options[:fields])]) if options[:fields]
-          params.concat(format_filter(options[:filter]))          if options[:filter]
-
-          RestClient::ParamsArray.new(params)
-        end
-
-        def format_fields(fields)
-          if fields.respond_to?(:join)
-            fields.join(",")
-          elsif fields == :all
-            ":all"
-          else
-            fields
-          end
-        end
-
-        def format_filter(filter)
-          if filter.respond_to?(:map)
-            filter.map do |subfilter|
-              [:filter, subfilter]
-            end
-          else
-            [[:filter, filter]]
-          end
-        end
       end
 
       def initialize(client, raw_data)
-        raw_data["display_name"] ||= raw_data["name"] # for backward compatbility with v2.19
         super(raw_data)
-        self.client = client
-      end
-
-      def update_attributes(attributes)
-        client.patch("#{self.class.resource_name}/#{id}", attributes)
-        attributes.each do |key, value|
-          self[key] = value
-        end
-        self
-      end
-
-      def add_relation(relation, relation_id)
-        client.post("#{self.class.resource_name}/#{id}/#{relation}/#{relation_id}", {})
-        self
-      end
 
-      def remove_relation(relation, relation_id)
-        client.delete("#{self.class.resource_name}/#{id}/#{relation}/#{relation_id}", {})
-        self
+        self.client = client
       end
 
-      def delete
-        client.delete("#{self.class.resource_name}/#{id}")
-        true
+      def to_h
+        super.tap {|h| h.delete(:client) }
       end
 
       def ==(other)
         self.class == other.class && id == other.id
       end
-
-      def update
-        client.put("#{self.class.resource_name}/#{id}", to_h)
-      end
     end
   end
 end

data/lib/dhis2/api/bulk_creatable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module BulkCreatable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+
+        BulkCreationStatusClass = ::Dhis2::Api::ImportSummary
+
+        # args is a hash like: { data_element_groups: [{ name: "foo" }, { name: "bar" }] }
+        def bulk_create(client, args, raw_input = false)
+          response = client.post(path: "metadata", payload: args, raw_input: raw_input)
+          self::BulkCreationStatusClass.new(response).tap do |summary|
+            unless summary.bulk_success?
+              exception = Dhis2::BulkCreationError.new("Didnt create bulk of data properly.\n Response: #{response.to_json}")
+              exception.import_summary = summary
+              raise exception
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/constants.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Constants
+      DATA_DIMENSION_TYPES = %w(ATTRIBUTE DISAGGREGATION).freeze
+      DOMAIN_TYPES  = %w(TRACKER AGGREGATE).freeze
+      FEATURE_TYPES = %w(SYMBOL POLYGON MULTI_POLYGON NONE POINT).freeze
+      PERIOD_TYPES  = %w(Daily Weekly Monthly BiMonthly Quarterly SixMonthly Yearly).freeze
+      PROGRAM_TYPES = %w(WITHOUT_REGISTRATION WITH_REGISTRATION).freeze
+    end
+  end
+end