dhis2 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 77af2d4ee9db850966b8fe67375be8554acfbe72
+  data.tar.gz: 79a9fccf546c3e1b5d94e85ca17718dcfb520c44
+SHA512:
+  metadata.gz: 91d423b15b3adcd7371f281b908170ac12a902a408957e18c3b78be32973a3435e1d2479d1c34bd1f0273aea785ece0b368ce183d37291f70529c109b5760065
+  data.tar.gz: 5dafa945e708eea647ec1b097f10c32b6b83d886bab1f33b9f1741ec0f8719490a81f291e0807fbdbfebd066caad95361c1890ba89b1b534efd5ce87471af636

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,42 @@
+Rails:
+  Enabled: true
+AlignHash:
+  # Alignment of entries using hash rocket as separator. Valid values are:
+  #
+  # key - left alignment of keys
+  # 'a' => 2
+  # 'bb' => 3
+  # separator - alignment of hash rockets, keys are right aligned
+  # 'a' => 2
+  # 'bb' => 3
+  # table - left alignment of keys, hash rockets, and values
+  # 'a' => 2
+  # 'bb' => 3
+  EnforcedHashRocketStyle: table
+  # Alignment of entries using colon as separator. Valid values are:
+  #
+  # key - left alignment of keys
+  # a: 0
+  # bb: 1
+  # separator - alignment of colons, keys are right aligned
+  # a: 0
+  # bb: 1
+  # table - left alignment of keys and values
+  # a: 0
+  # bb: 1
+  EnforcedColonStyle: table
+IfUnlessModifier:
+  MaxLineLength: 100
+LineLength:
+  Max: 100
+StringLiterals:
+  EnforcedStyle: double_quotes
+WhileUntilModifier:
+  MaxLineLength: 100
+MethodCalledOnDoEndBlock:
+  Description: 'Avoid chaining a method call on a do...end block.'
+  Enabled: true
+ClassLength:
+  Max: 400
+Documentation:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.12.5

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at martin@joyouscoding.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Martin Van Aken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# Dhis2
+
+Basic DHIS2 API client for Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dhis2', :github => 'BLSQ/dhis2' # not published yet, so get it from github
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dhis2
+
+## Usage
+
+### Connection
+
+The functionalities are available as a module. First thing you need to do is to connect to the instance:
+
+    Dhis2.connect(url: "https://play.dhis2.org/demo", user: "admin", password: "district")
+
+### Search for elements
+
+All subsequent calls can be done on the object themselves and are going to use the provided url and credentials
+
+    org_unit_levels = Dhis2::OrganisationUnitLevel.list
+
+The various methods are taking an optional hash parameter to be used for ´filter´ and ´fields´ values:
+
+    org_units = Dhis2::OrganisationUnit.list(filter: "level:eq:2", fields: %w(id level displayName parent))
+
+If you want all fields, simply specify `:all`
+
+    org_units = Dhis2::OrganisationUnit.list(filter: "level:eq:2", fields: :all)
+
+Notes that any field found in the resulting JSON will be accessible from the object.
+
+### 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::OrganisationUnit.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
+
+### Retreive 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.Dhis2::OrganisationUnit.find(id)
+
+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::DataElement.list(filter: "code:eq:C27", fields: :all).first
+
+    # Just do:
+    data_element = Dhis2::DataElement.find_by(code: "C27")
+
+## Supported features
+
+The API is currently limited to **read** actions on the following elements:
+
+* Organisation Units
+* Organisation Units Levels
+* Data Elements
+* Data Sets
+
+A very basic **write** use case exists for Data Elements and Data Sets:
+
+    elements = [
+          { name: "TesTesT1", short_name: "TTT1" },
+          { name: "TesTesT2", short_name: "TTT2" }
+        ]
+    status = Dhis2:DataElement.create(elements)
+    status.success? # => true
+    status.total_imported # => 2
+
+DHIS2 API does not return the ids of the created elements, but you can retreive them with their (unique) name or code.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/BLSQ/dhis2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+z

data/Rakefile

@@ -0,0 +1,10 @@
+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']
+end
+
+task :default => :test

data/TODO.md

@@ -0,0 +1,18 @@
+# Improvements
+
+## Reading
+
+Convert the CamelCase JSON field names to more Ruby-like snake_case fields.
+
+Ex: shortName => short_name
+
+## API Structure
+
+Have a look to Stripe API to use the objects themselves as starting point:
+
+    data_elements = DataElement.list(filter: "...", fields: [...])
+    data_element = DataElement.find(id)
+
+This would make the "write/update" API better:
+
+    DataElement.create(name: "", short_name: "")

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dhis2"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dhis2.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dhis2/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "dhis2"
+  spec.version       = Dhis2::VERSION
+  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.homepage      = "http://github.com/blsq/dhis2"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'rest-client'
+
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/lib/base.rb

@@ -0,0 +1,49 @@
+module Dhis2
+  class Base
+    def initialize(raw_data)
+      @raw_data = raw_data
+      @id = raw_data["id"]
+      @display_name = raw_data["displayName"]
+    end
+
+    def method_missing(m, *args, &block)
+      return @raw_data[m.to_s] if @raw_data[m.to_s]
+      super
+    end
+
+    class << self
+      def find(id)
+        response = Dhis2.get_resource("#{resource_name}/#{id}").get
+        json_response = JSON.parse(response)
+        new(json_response)
+      end
+
+      def find_by(clauses)
+        filter = []
+        clauses.each do |field, value|
+          filter << "#{field}:eq:#{value}"
+        end
+        list(fields: :all, filter: filter.join("&")).first
+      end
+
+      def list(options = {})
+        options[:fields] = default_fields if default_fields && !options[:fields]
+        response = Dhis2.get_resource(resource_name, options).get
+        json_response = JSON.parse(response)
+        PaginatedArray.new(
+          json_response[resource_name].map { |raw_org_unit| new(raw_org_unit) },
+          json_response["pager"]
+        )
+      end
+
+      def resource_name
+        simple_name = name.split("::").last
+        simple_name[0].downcase + simple_name[1..-1] + "s"
+      end
+
+      def default_fields
+        nil
+      end
+    end
+  end
+end

data/lib/data_element.rb

@@ -0,0 +1,39 @@
+require "base"
+
+module Dhis2
+  class DataElement < Base
+    attr_reader :id, :display_name
+
+    def initialize(params)
+      super(params)
+    end
+
+    class << self
+      def create(elements)
+        elements = [elements].flatten
+        category_combo_id = JSON.parse(Dhis2.resource["categoryCombos"].get)["categoryCombos"]
+                            .first["id"]
+        data_element = {
+          dataElements: elements.map do |element|
+            {
+              name:            element[:name],
+              shortName:       element[:short_name],
+              code:            element[:code] || element[:short_name],
+              domainType:      element[:domain_type] || "AGGREGATE",
+              valueType:       element[:value_type] || "INTEGER_POSITIVE",
+              aggregationType: element[:aggregation_type] || "SUM",
+              categoryCombo:   { id: category_combo_id }
+            }
+          end
+        }
+        json_response = Dhis2.resource["metadata"].post(
+          JSON.generate(data_element),
+          content_type: "application/json"
+        )
+        response = JSON.parse(json_response)
+
+        Dhis2::Status.new(response)
+      end
+    end
+  end
+end

data/lib/data_set.rb

@@ -0,0 +1,35 @@
+require "base"
+
+module Dhis2
+  class DataSet < Base
+    def initialize(params)
+      super(params)
+    end
+
+    class << self
+      def create(sets)
+        sets = [sets].flatten
+
+        data_set = {
+          dataSets: sets.map do |set|
+            {
+              name:              set[:name],
+              shortName:         set[:short_name],
+              code:              set[:code],
+              periodType:        "Monthly",
+              dataElements:      set[:data_element_ids] ? set[:data_element_ids].map { |id| { id: id } } : [],
+              organisationUnits: set[:organisation_unit_ids] ? set[:organisation_unit_ids].map { |id| { id: id } } : []
+            }
+          end
+        }
+        json_response = Dhis2.resource["metadata"].post(
+          JSON.generate(data_set),
+          content_type: "application/json"
+        )
+        response = JSON.parse(json_response)
+
+        Dhis2::Status.new(response)
+      end
+    end
+  end
+end

data/lib/dhis2/version.rb

@@ -0,0 +1,3 @@
+module Dhis2
+  VERSION = "0.1.0"
+end

data/lib/dhis2.rb

@@ -0,0 +1,47 @@
+require "dhis2/version"
+require "rest-client"
+require "json"
+require "organisation_unit"
+require "data_element"
+require "data_set"
+require "organisation_unit_level"
+require "status"
+require "paginated_array"
+
+module Dhis2
+  class << self
+    attr_reader :url
+
+    def connect(options)
+      raise "Missing #{url}" unless options[:url]
+      raise "Missing #{user}" unless options[:user]
+      raise "Missing #{password}" unless options[:password]
+
+      @url = options[:url]
+      @user = options[:user]
+      @password = options[:password]
+    end
+
+    def get_resource(name, options = {})
+      arguments = []
+      if options[:fields]
+        arguments << "fields=" + options[:fields].join(",") if options[:fields].respond_to?(:join)
+        arguments << "fields=:#{options[:fields]}" if options[:fields].class == Symbol
+      end
+      arguments << "filter=" + options[:filter] if options[:filter]
+      arguments << "pageSize=#{options[:page_size]}" if options[:page_size]
+      arguments << "page=#{options[:page]}" if options[:page]
+
+      path = "#{name}?#{arguments.join('&')}"
+      resource[path]
+    end
+
+    def resource
+      @resource ||= RestClient::Resource.new("#{@url}/api", headers: { accept: "application/json" }, user: @user, password: @password)
+    end
+
+    def camelize(str)
+      str.gsub(/\_([a-z])/, "")
+    end
+  end
+end

data/lib/organisation_unit.rb

@@ -0,0 +1,14 @@
+require "base"
+
+module Dhis2
+  class OrganisationUnit < Base
+    attr_reader :id, :display_name, :level, :parent_id, :children_ids
+
+    def initialize(params)
+      super(params)
+      @level = params["level"]
+      @parent_id = params["parent"]["id"] if params["parent"]
+      @children_ids = params["children"] ? params["children"].map { |raw| raw["id"] } : []
+    end
+  end
+end

data/lib/organisation_unit_level.rb

@@ -0,0 +1,19 @@
+require "base"
+
+module Dhis2
+  class OrganisationUnitLevel < Base
+    attr_reader :id, :name, :level
+
+    def initialize(params)
+      super(params)
+      @name = params["name"]
+      @level = params["level"]
+    end
+
+    class << self
+      def default_fields
+        %w(id name level)
+      end
+    end
+  end
+end

data/lib/pager.rb

@@ -0,0 +1,10 @@
+class Pager
+  attr_reader :page, :page_count, :total, :next_page
+
+  def initialize(hash)
+    @page = hash["page"]
+    @page_count = hash["pageCount"]
+    @total = hash["total"]
+    @next_page = hash["nextPage"]
+  end
+end

data/lib/paginated_array.rb

@@ -0,0 +1,11 @@
+require "delegate"
+require "pager"
+
+class PaginatedArray < DelegateClass(Array)
+  attr_reader :pager
+
+  def initialize(array, raw_pager = nil)
+    super(array)
+    @pager = Pager.new(raw_pager) if raw_pager
+  end
+end

data/lib/status.rb

@@ -0,0 +1,53 @@
+module Dhis2
+  class Status
+    attr_reader :raw_status
+
+    def initialize(raw_status)
+      @raw_status = raw_status
+    end
+
+    def success?
+      @raw_status["importTypeSummaries"].all? { |summary| summary["status"] == "SUCCESS" }
+    end
+
+    def import_count
+      @raw_status["importCount"]
+    end
+
+    def total_imported
+      total = 0
+      import_count.each do |_, count|
+        total += count
+      end
+      total
+    end
+
+    def last_imported_ids
+      @raw_status["importTypeSummaries"].map { |summary| summary["lastImported"] }
+    end
+  end
+end
+
+# {
+#   "importCount"=>{
+#     "imported"=>1, 
+#     "updated"=>0, 
+#     "ignored"=>0, 
+#     "deleted"=>0
+#   }, 
+#   "importTypeSummaries"=>[
+#     {
+#       "responseType"=>"ImportTypeSummary", 
+#       "status"=>"SUCCESS", 
+#       "importCount"=>
+#       {
+#         "imported"=>1, 
+#         "updated"=>0, 
+#         "ignored"=>0, 
+#         "deleted"=>0
+#       }, 
+#       "type"=>"DataElement", 
+#       "lastImported"=>"lMadHjxdo5q"
+#     }
+#   ]
+# }

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: dhis2
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Martin Van Aken
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-08-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Allows to retreive items from a DHIS2 server in a more "Ruby way".
+email:
+- mvanaken@bluesquare.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO.md
+- bin/console
+- bin/setup
+- dhis2.gemspec
+- lib/base.rb
+- lib/data_element.rb
+- lib/data_set.rb
+- lib/dhis2.rb
+- lib/dhis2/version.rb
+- lib/organisation_unit.rb
+- lib/organisation_unit_level.rb
+- lib/pager.rb
+- lib/paginated_array.rb
+- lib/status.rb
+homepage: http://github.com/blsq/dhis2
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Simple Ruby wrapper on DHIS2 API.
+test_files: []