dhis2 2.3.8 → 3.0.0

data/lib/dhis2/api/creatable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Creatable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def create(client, args, raw_input = false)
+          if raw_input
+            client.post(path: resource_name, payload: args, raw_input: true).tap do |response|
+              validate_instance_creation(response)
+            end
+          else
+            args = creation_args(args)
+            with_valid_args(args) do
+              response = client.post(path: resource_name, payload: args)
+              validate_instance_creation(response)
+              new(client, args.merge(id: created_instance_id(response)))
+            end
+          end
+        end
+
+        private
+
+        def creation_defaults(_args)
+          {}
+        end
+
+        def creation_args(args)
+          creation_defaults(args).merge(args).keep_if { |_, v| !v.nil? }
+        end
+
+        def with_valid_args(args)
+          validator = self::Schema.call(args)
+          if validator.success?
+            yield
+          else
+            raise Dhis2::CreationError, "Validation Error: #{validator.messages}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/deletable.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Deletable
+      def delete
+        client.delete(path: "#{self.class.resource_name}/#{id}")
+        true
+      end
+    end
+  end
+end

data/lib/dhis2/api/event_creation_status.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    class EventCreationStatus
+      def initialize(hash)
+        @hash = hash
+      end
+
+      def creation_success?
+        base_success? && only_updates_and_imports?
+      end
+
+      def update_success?
+        base_success? && only_updates_and_imports?
+      end
+
+      def bulk_success?
+        base_success?
+      end
+
+      def imported_count
+        response["imported"]
+      end
+
+      def updated_count
+        response["updated"]
+      end
+
+      def ignored_count
+        response["ignored"]
+      end
+
+      def import_summaries
+        @import_summaries ||= response["import_summaries"].map do |hash|
+          Dhis2::Api::ImportSummary.new(hash)
+        end
+      end
+
+      private
+
+      attr_reader :hash
+
+      def response
+        hash["response"]
+      end
+
+      def only_updates_and_imports?
+        ignored_count == 0 && (updated_count > 0 || imported_count > 0)
+      end
+
+      def base_success?
+        response["response_type"] == "ImportSummaries" &&
+          response["status"] == "SUCCESS"
+      end
+    end
+  end
+end

data/lib/dhis2/api/findable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Findable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # https://docs.dhis2.org/2.25/en/developer/html/webapi_metadata_object_filter.html
+        def find(client, id, fields: :all, raw: false)
+          raise Dhis2::PrimaryKeyMissingError if id.nil?
+
+          if id.is_a? Array
+            list(client, { filter: "id:in:[#{id.join(',')}]", fields: fields, page_size: id.size }, raw)
+          else
+            if raw
+              client.get(path: "#{resource_name}/#{id}", raw: true)
+            else
+              new(client, client.get(path: "#{resource_name}/#{id}"))
+            end
+          end
+        end
+
+        # batch size is to prevent from sending get requests with uri too long
+        # max uri length is around 2000 chars, a dhis id is around 11 chars, 100 is a safe default
+        def find_paginated(client, ids, fields: :all, batch_size: 100, raw: false)
+          Enumerator.new do |yielder|
+            loop do
+              ids.each_slice(batch_size) do |array|
+                find(client, array, fields: fields, raw: raw).map do |item|
+                  yielder << item
+                end
+              end
+              raise StopIteration
+            end
+          end
+        end
+
+        def find_by(client, clauses, fields: :all, raw: false)
+          list(
+            client,
+            fields: fields,
+            filter: clauses.map { |field, value| "#{field}:eq:#{value}" },
+            raw: raw
+          ).first
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/import_summary.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    class ImportSummary
+      def initialize(hash)
+        @hash = hash
+      end
+
+      def reference
+        hash["reference"]
+      end
+
+      def creation_success?
+        base_success? && only_updates_and_imports?
+      end
+
+      def update_success?
+        base_success? && only_updates_and_imports?
+      end
+
+      def bulk_success?
+        base_success?
+      end
+
+      def imported_count
+        import_count["imported"]
+      end
+
+      def updated_count
+        import_count["updated"]
+      end
+
+      def ignored_count
+        import_count["ignored"]
+      end
+
+      def raw_status
+        hash
+      end
+
+      private
+
+      attr_reader :hash
+
+      def only_updates_and_imports?
+        ignored_count == 0 && (updated_count > 0 || imported_count > 0)
+      end
+
+      def import_count
+        hash["import_count"]
+      end
+
+      def base_success?
+        %w(ImportSummary ImportTypeSummary).include?(hash["response_type"]) &&
+          hash["status"] == "SUCCESS" &&
+          import_count
+      end
+    end
+  end
+end

data/lib/dhis2/api/listable.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Listable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+
+        PAGER_KEY = "pager"
+
+        def list(client, options = {}, raw = false)
+          json_response = client.get(path: resource_name, query_params: format_query_parameters(options), raw: raw)
+          if paginated
+            if raw
+              PaginatedArray.new(
+                json_response[resource_name],
+                json_response[PAGER_KEY]
+              )
+            else
+              PaginatedArray.new(
+                json_response[resource_key].map { |raw_resource| new(client, raw_resource) },
+                json_response[PAGER_KEY]
+              )
+            end
+          else
+            json_response
+          end
+        end
+
+        def fetch_paginated_data(client, params = {}, options = {})
+          raise InvalidMethodError, "this collection is not paginated" unless paginated
+          options = { raw: false, with_pager: false }.merge(options)
+          Enumerator.new do |yielder|
+            params[:page] ||= 1
+            loop do
+              results = list(client, params, options[:raw])
+              if options[:with_pager]
+                results.map { |item| yielder << [item, results.pager] }
+              else
+                results.map { |item| yielder << item }
+              end
+              raise StopIteration if results.pager.last_page?
+              params[:page] += 1
+            end
+          end
+        end
+
+        def paginated
+          true
+        end
+
+        private
+
+        def format_query_parameters(options)
+          ::Dhis2::QueryParametersFormatter.new(
+            options:          options,
+            query_parameters: query_parameters
+          ).call
+        end
+
+        def query_parameters
+          default_query_parameters + additional_query_parameters
+        end
+
+        def additional_query_parameters
+          []
+        end
+
+        def default_query_parameters
+          [:page, :page_size, :root_junction]
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/query_parameters_formatter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Dhis2
+  class QueryParametersFormatter
+    def initialize(options:, query_parameters:)
+      @options = options
+      @query_parameters = query_parameters
+    end
+
+    def call
+      RestClient::ParamsArray.new(formatted_options)
+    end
+
+    private
+
+    attr_reader :options, :query_parameters
+
+    def formatted_options
+      [].tap do |params|
+        query_parameters.each do |param|
+          Array(options[param]).each do |value|
+            params.push([::Dhis2::Case.camelize(param.to_s, false), value])
+          end
+        end
+        params.push([:fields, format_fields(options[:fields])]) if options[:fields]
+        params.concat(format_filter(options[:filter]))          if options[:filter]
+      end
+    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
+end

data/lib/dhis2/api/shared/analytic.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      class Analytic
+        def self.list(client, periods:, organisation_units:, data_elements: nil, filter: nil)
+          params = [
+            [:dimension, "ou:#{organisation_units}"],
+            [:dimension, "pe:#{periods}"]
+          ]
+          params << [:dimension, "dx:#{data_elements}"] if data_elements
+          params << [:filter, filter.to_s] if filter
+
+          client.get(path: "analytics", query_params: RestClient::ParamsArray.new(params))
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/category_combo.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module CategoryCombo
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        def default
+          self.class.default(client)
+        end
+
+        module ClassMethods
+          def default(client)
+            find_by(client, name: "default")
+          end
+
+          private
+
+          def creation_defaults(_args)
+            { data_dimension_type: "DISAGGREGATION" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/category_option_combo.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module CategoryOptionCombo
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        def default
+          self.class.default(client)
+        end
+
+        module ClassMethods
+          def default(client)
+            find_by(client, name: "default")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/constants.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module Constants
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def data_dimension_types
+            ::Dhis2::Api::Constants::DATA_DIMENSION_TYPES
+          end
+
+          def domain_types
+            ::Dhis2::Api::Constants::DOMAIN_TYPES
+          end
+
+          def feature_types
+            ::Dhis2::Api::Constants::DATA_DIMENSION_TYPES
+          end
+
+          def period_types
+            ::Dhis2::Api::Constants::PERIOD_TYPES
+          end
+
+          def program_types
+            ::Dhis2::Api::Constants::PROGRAM_TYPES
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/data_element_group.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module DataElementGroup
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        def data_element_ids
+          data_elements.map { |elt| elt["id"] }
+        end
+
+        module ClassMethods
+          def creation_defaults(args)
+            {
+              code: args[:short_name]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/data_set.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module DataSet
+        def add_data_elements(new_data_element_ids)
+          (new_data_element_ids - data_element_ids).tap do |additions|
+            (new_data_element_ids - data_element_ids).each do |data_element_id|
+              data_set_elements.push("data_element" => { "id" => data_element_id })
+            end
+            update if additions.any?
+          end
+        end
+
+        def data_element_ids
+          data_set_elements.map { |elt| elt["data_element"]["id"] }
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/data_value.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module DataValue
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def find(client, period:, organisation_unit:, data_element:)
+            client.get(
+              path: resource_name,
+              query_params: {
+                pe: period,
+                ou: organisation_unit,
+                de: data_element
+              }
+            ).first
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/data_value_set.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module DataValueSet
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def list(client, options = {}, raw = false)
+            response = super(client, options, raw)
+            if raw
+              response["dataValues"]
+            else
+              response["data_values"].map do |elt|
+                OpenStruct.new(elt)
+              end
+            end
+          end
+
+          def bulk_create(client, args, raw_input = false)
+            response = client.post(path: resource_name, payload: args, raw_input: raw_input)
+            ::Dhis2::Api::ImportSummary.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
+
+          private
+
+          def instance_creation_success?(response)
+            Dhis2::Api::ImportSummary.new(response).creation_success?
+          end
+
+          def created_instance_id(_response)
+            nil
+          end
+
+          def paginated
+            false
+          end
+
+          def additional_query_parameters
+            [
+              :data_set, :data_element_group, :period, :start_date, :end_date,
+              :org_unit, :children, :org_unit_group
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/event.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module Event
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        def id
+          # we use super because id is defined on creation
+          super || event
+        end
+
+        module ClassMethods
+          def list(client, options = {}, raw = false)
+            raise InvalidRequestError, new(list_error_message) if invalid_list_arguments?(options)
+            super
+          end
+
+          private
+
+          def additional_query_parameters
+            [:program, :org_unit, :tracked_entity_instance]
+          end
+
+          def instance_creation_success?(response)
+            response["status"] == "OK" &&
+              response["response"] &&
+              response["response"]["status"] == "SUCCESS" &&
+              response["response"]["imported"] == 1 &&
+              response["response"]["import_summaries"]
+          end
+
+          def created_instance_id(response)
+            response["response"]["import_summaries"][0]["reference"]
+          end
+
+          def invalid_list_arguments?(options)
+            %i(org_unit program tracked_entity_instance event).all? do |arg|
+              options[arg].nil?
+            end
+          end
+
+          def list_error_message
+            "At least one of the following query parameters are required:" \
+            "org_unit, program, tracked_entity_instance or event."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dhis2/api/shared/organisation_unit.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dhis2
+  module Api
+    module Shared
+      module OrganisationUnit
+        def parent_id
+          parent ? parent["id"] : nil
+        end
+
+        def children_ids
+          children ? children.map { |elt| elt["id"] } : []
+        end
+      end
+    end
+  end
+end