redcap-survey-api 0.0.1

data/.gitignore

@@ -0,0 +1 @@
+/*.gem

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 mmcrockett
+
+MIT License
+
+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,35 @@
+# Usage
+
+This is an api to utilize RedCAP api with ruby.
+
+To start:
+
+Test cases are the best place to look for examples. Here are some simple examples.
+
+```ruby
+r = RedcapSurveyApi::RedcapApi.new({:token => "abc123", :url => "http://localhost/redcap/api"}) # Authentication token provided by RedCAP, server API url.
+r = RedcapSurveyApi::RedcapApi.new({:token => "abc123", :url => "http://localhost/redcap/api", :parser => JSON}) # Set the parser, default is JSON, other parsers are Nokogiri::XML, CSV, RedcapSurveyApi::EmptyParser. See tests for examples.
+
+r.export() # returns all records in 'parser' format, provide additional hash of parameters in you want to override or add any additional RedCAP options.
+
+r.export_metadata() # returns all metadata records in JSON format, provide additional hash of parameters in you want to override or add any additional RedCAP options.
+
+r.export_metadata_fields() # returns all fields (this is a sub-set of metadata). 
+
+r.import() # imports new records.
+
+r.export({:parser => RedcapSurveyApi::EmptyParser}) # returns the raw data, this allows you to get data without going through the parser.
+
+There is also a helper class added to ruby Hash allowing you to convert a ruby array to a http-post style array. I created this after having some issues filtering on 'forms' and 'fields'
+Example:
+params = {:fields => ['record_id', 'lab_id'], :forms => ['slide_tracking', 'id_shipping']} # This is the data I want to send to RedCAP, limiting the fields and forms
+r.export_metadata(params.to_http_post_array()) # This gets the metadata for only those fields/forms by using the newly added method on Hash 'to_http_post_array'.
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/redcap-survey-api/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/redcap-survey-api.rb

@@ -0,0 +1,59 @@
+require 'json'
+require 'mechanize'
+require 'redcap-survey-api/hash_extension'
+require 'redcap-survey-api/empty_parser'
+
+module RedcapSurveyApi
+  class RedcapApi
+    DEFAULT_PARAMS = {
+      :content => 'record',
+      :format  => 'json',
+      :type    => 'flat',
+      :parser  => JSON
+    }
+
+    def initialize(params = {})
+      @payload = DEFAULT_PARAMS.merge(params)
+    end
+
+    def export(params = {})
+      return api(params)
+    end
+
+    def export_metadata(params = {})
+      payload = {:content => 'metadata'}.merge(params)
+      return export(payload)
+    end
+
+    def export_metadata_fields
+      response = export_metadata()
+      if response
+        response.collect {|r| r['field_name'] if r }
+      end
+    end
+
+    def import(params = {})
+      return api(params)
+    end
+
+    private
+    def api(params = {})
+      payload = @payload.merge(params)
+      validate(payload)
+
+      return payload[:parser].parse(Mechanize.new.post(@url, payload).body)
+    end
+
+    def validate(params)
+      [:token, :url].each do |required_param|
+        if (false == params.include?(required_param))
+          raise "!ERROR: '#{required_param}' is a required parameter."
+        end
+      end
+
+      if ((false == "#{params[:parser]}".include?("EmptyParser")) && (false == "#{params[:parser]}".downcase.include?(params[:format])))
+        $stderr.puts "!WARNING: Your parser '#{params[:parser]}' and your default format '#{params[:format]}' don't seem to match."
+      end
+    end
+  end
+end

data/lib/redcap-survey-api/empty_parser.rb

@@ -0,0 +1,7 @@
+module RedcapSurveyApi
+  class EmptyParser
+    def self.parse(data)
+      return data
+    end
+  end
+end

data/lib/redcap-survey-api/hash_extension.rb

@@ -0,0 +1,17 @@
+class Hash
+  def to_http_post_array
+    r = {}
+
+    self.each_key do |k|
+      if (false == self[k].is_a?(Array))
+        raise "!ERROR: Expecting hash value to be an Array."
+      end
+
+      self[k].each_with_index do |v,i|
+        r["#{k}[#{i}]"] = v
+      end
+    end
+
+    return r
+  end
+end

data/redcap-survey-api.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+  s.name        = 'redcap-survey-api'
+  s.version     = '0.0.1'
+  s.platform    = Gem::Platform::RUBY
+  s.homepage    = "https://github.com/mmcrockett/redcap-survey-api"
+  s.date        = '2014-09-02'
+  s.summary     = %q{REDCap Survey API - Welcome to easy interaction with REDCap through Ruby.}
+  s.description = %q{REDCap Survey API provides a ruby-style interface for interacting with the REDCap survey system from Vanderbilt.}
+  s.authors     = ["Mike Crockett"]
+  s.email       = "redcap@mmcrockett.com"
+  s.license     = "MIT"
+
+  s.files            = `git ls-files`.split("\n")
+  s.test_files       = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables      = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths    = ["lib"]
+  s.extra_rdoc_files = ["README.md"]
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency "csv"
+  s.add_development_dependency "nokogiri"
+  s.add_dependency "mechanize"
+  s.add_dependency "json"
+end

data/test/test_errors_and_warnings.rb

@@ -0,0 +1,29 @@
+require 'test/unit'
+
+class RedcapSurveyApiTest < Test::Unit::TestCase
+  def test_no_url
+    begin
+      RedcapSurveyApi::RedcapApi.new({:token => "blah"}).export()
+    rescue => e
+    end
+
+    assert_equal("!ERROR: 'url' is a required parameter.", "#{e}")
+  end
+
+  def test_no_token
+    begin
+      RedcapSurveyApi::RedcapApi.new({:url => "lala"}).export()
+    rescue => e
+    end
+
+    assert_equal("!ERROR: 'token' is a required parameter.", "#{e}")
+  end
+
+  def test_warning
+    $stderr   = StringIO.open('','w')
+
+    RedcapSurveyApi::RedcapApi.new({:token => "x", :url => "y", :format => 'invalid'}).export()
+
+    assert_equal("!WARNING: Your parser 'JSON' and your default format 'invalid' don't seem to match.", $stderr.string.chomp)
+  end
+end

data/test/test_hash_extension.rb

@@ -0,0 +1,9 @@
+require 'test/unit'
+
+class RedcapSurveyHashExtensionTest < Test::Unit::TestCase
+  def test_hash_extension
+    t = {:a => [1,2,3], :b => ["h", "i", "j"]}
+    e = {"a[0]" => 1, "a[1]" => 2, "a[2]" => 3, "b[0]" => "h", "b[1]" => "i", "b[2]" => "j"}
+    assert_equal(e, t.to_http_post_array)
+  end
+end

data/test/test_redcap_api.rb

@@ -0,0 +1,110 @@
+require 'test/unit'
+require 'redcap-survey-api'
+require 'csv'
+require 'Nokogiri'
+require 'StringIO'
+
+class Hash
+  def body
+    return self[:body]
+  end
+end
+
+class Mechanize
+  def post(url, payload)
+    v = {}
+
+    if ('json' == payload[:format])
+      if ('metadata' == payload[:content])
+        v[:body] = '[{"field_name":"record_id", "form_name":"form0"},{"field_name":"first_name", "form_name":"form0"},{"field_name":"trc_id", "form_name":"form0"}]'
+      else
+        v[:body] = '[{"record_id":"1", "trc_id":"b", "first_name":"bob"},{"record_id":"2", "trc_id":"c", "first_name":"chris"}]'
+      end
+    elsif ('xml' == payload[:format])
+      v[:body] = '<?xml version="1.0" encoding="UTF-8" ?><records><item><record_id><![CDATA[1]]></record_id><trc_id>b</trc_id><first_name>bob</first_name></item><item><record_id><![CDATA[2]]></record_id><trc_id>c</trc_id><first_name>chris</first_name></item></records>'
+    elsif ('csv' == payload[:format])
+      v[:body] = 'record_id,trc_id,first_name'
+      v[:body] << "\n"
+      v[:body] << '"1","b","bob"'
+      v[:body] << "\n"
+      v[:body] << '"2","c","chris"'
+    else
+      v[:body] = '[{"record_id":"1", "trc_id":"b", "first_name":"bob"},{"record_id":"2", "trc_id":"c", "first_name":"chris"}]'
+    end
+
+    return v
+  end
+end
+
+class RedcapSurveyApiTest < Test::Unit::TestCase
+  DEFAULT_CONNECTION = {:url => "http://localhost:8080/redcap/api", :token => "ABC123"}
+
+  def test_default_parser
+    default   = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION).export()
+    json_data = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION.merge({:parser => JSON})).export({:format => 'json'})
+
+    assert_equal(json_data, default)
+  end
+
+  def test_xml_parser
+    xml_data  = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION.merge({:parser => Nokogiri::XML::Document})).export({:format => 'xml'})
+    json_data = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION.merge({:parser => JSON})).export({:format => 'json'})
+    xml_to_json_data = []
+
+    xml_data.xpath(".//item").each do |item_node|
+      json_record = {}
+      item_node.children().each do |value_node|
+        json_record[value_node.name()] = value_node.content()
+      end
+      xml_to_json_data << json_record
+    end
+
+    assert_equal(json_data, xml_to_json_data)
+  end
+
+  def test_csv_parser
+    csv_data  = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION.merge({:parser => CSV})).export({:format => 'csv'})
+    json_data = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION.merge({:parser => JSON})).export({:format => 'json'})
+    csv_to_json_data = []
+
+    csv_data.each_with_index do |record,i|
+      if (0 != i)
+        json_record = {}
+        record.each_with_index do |value,j|
+          json_record[csv_data[0][j]] = value
+        end
+        csv_to_json_data << json_record
+      end
+    end
+
+    assert_equal(json_data, csv_to_json_data)
+  end
+
+  def test_none_parser
+    $stderr   = StringIO.open('','w')
+    none_data = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION.merge({:parser => RedcapSurveyApi::EmptyParser})).export({:format => 'xml'})
+
+    assert_equal('<?xml version="1.0" encoding="UTF-8" ?><records><item><record_id><![CDATA[1]]></record_id><trc_id>b</trc_id><first_name>bob</first_name></item><item><record_id><![CDATA[2]]></record_id><trc_id>c</trc_id><first_name>chris</first_name></item></records>', none_data)
+    assert_equal("", $stderr.string.chomp)
+  end
+
+  def test_param_override
+    metadata = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION).export_metadata()
+    data     = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION).export_metadata({:content => 'record'})
+
+    assert_not_equal(data, metadata)
+  end
+
+  def test_metadata
+    metadata = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION).export_metadata()
+    data = [{"field_name"=>"record_id", "form_name"=>"form0"},{"field_name"=>"first_name", "form_name"=>"form0"},{"field_name"=>"trc_id", "form_name"=>"form0"}]
+
+    assert_equal(data, metadata)
+  end
+
+  def test_metadata_fields
+    fields = RedcapSurveyApi::RedcapApi.new(DEFAULT_CONNECTION).export_metadata_fields()
+
+    assert_equal(["record_id", "first_name", "trc_id"], fields)
+  end
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: redcap-survey-api
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mike Crockett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mechanize
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: REDCap Survey API provides a ruby-style interface for interacting with
+  the REDCap survey system from Vanderbilt.
+email: redcap@mmcrockett.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- .gitignore
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/redcap-survey-api.rb
+- lib/redcap-survey-api/empty_parser.rb
+- lib/redcap-survey-api/hash_extension.rb
+- redcap-survey-api.gemspec
+- test/test_errors_and_warnings.rb
+- test/test_hash_extension.rb
+- test/test_redcap_api.rb
+homepage: https://github.com/mmcrockett/redcap-survey-api
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: REDCap Survey API - Welcome to easy interaction with REDCap through Ruby.
+test_files:
+- test/test_errors_and_warnings.rb
+- test/test_hash_extension.rb
+- test/test_redcap_api.rb