qualtrics_api 0.0.1

data/lib/qualtrics_api.rb

@@ -0,0 +1,23 @@
+require "faraday"
+require "faraday_middleware"
+
+require "qualtrics_api/version"
+require "qualtrics_api/url"
+
+require "qualtrics_api/request_error_handler"
+
+require "qualtrics_api/client"
+require "qualtrics_api/survey"
+require "qualtrics_api/survey_collection"
+require "qualtrics_api/response_export"
+require "qualtrics_api/response_export_collection"
+
+require "qualtrics_api/services/response_export_service"
+
+module QualtricsAPI
+
+  def self.new(token)
+    Client.new(api_token: token)
+  end
+
+end

data/lib/qualtrics_api/client.rb

@@ -0,0 +1,32 @@
+module QualtricsAPI
+
+  class Client
+    attr_reader :api_token
+
+    def initialize(options = {})
+      @api_token = options[:api_token]
+    end
+
+    def surveys(options = {})
+      @surveys ||= QualtricsAPI::SurveyCollection.new options.merge({ connection: connection })
+    end
+
+    def response_exports(options = {})
+      @response_exports ||= QualtricsAPI::ResponseExportCollection.new options.merge({ connection: connection })
+    end
+
+    def connection
+      @conn ||= Faraday.new(url: QualtricsAPI::URL,
+                            params: { apiToken: @api_token }) do |faraday|
+        faraday.request :json
+        faraday.response :json, :content_type => /\bjson$/
+
+        faraday.use FaradayMiddleware::FollowRedirects
+        faraday.use QualtricsAPI::RequestErrorHandler
+
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+  end
+
+end

data/lib/qualtrics_api/request_error_handler.rb

@@ -0,0 +1,37 @@
+module QualtricsAPI
+
+  class RequestErrorHandler < Faraday::Response::Middleware
+
+    def on_complete(env)
+      case env[:status]
+      when 404
+        raise NotFoundError, "Not Found"
+      when 400
+        raise BadRequestError, error_message(JSON.parse(env[:body]))
+      when 401
+        raise UnauthorizedError, error_message(JSON.parse(env[:body]))
+      when 500
+        raise InternalServerError, error_message(JSON.parse(env[:body]))
+      end
+    end
+
+    private
+
+    def error_message(response)
+      meta = response["meta"]
+      [ "[",
+        meta["status"], " - ",
+        meta["qualtricsErrorCode"] || meta["internalErrorCode"],
+        "] ",
+        meta["errorMessage"]
+      ].join
+    end
+
+  end
+
+  class NotFoundError < StandardError; end
+  class BadRequestError < StandardError; end
+  class UnauthorizedError < StandardError; end
+  class InternalServerError < StandardError; end
+
+end

data/lib/qualtrics_api/response_export.rb

@@ -0,0 +1,40 @@
+module QualtricsAPI
+
+  class ResponseExport
+
+    attr_reader :id
+
+    def initialize(options = {})
+      @conn = options[:connection]
+      @id = options[:id]
+    end
+
+    def update_status
+      res = @conn.get('surveys/responseExports/' + @id).body["result"]
+      @export_progress = res["percentComplete"]
+      @file_url = res["fileUrl"]
+      @completed = true if @export_progress == 100.0
+      self
+    end
+
+    def status
+      update_status unless completed?
+      "#{@export_progress}%"
+    end
+
+    def percent_completed
+      update_status unless completed?
+      @export_progress
+    end
+
+    def completed?
+      @completed == true
+    end
+
+    def file_url
+      update_status unless completed?
+      @file_url
+    end
+  end
+
+end

data/lib/qualtrics_api/response_export_collection.rb

@@ -0,0 +1,24 @@
+module QualtricsAPI
+  class ResponseExportCollection
+    extend Forwardable
+    include Enumerable
+
+    attr_reader :all
+
+    def_delegator :all, :each
+    def_delegator :all, :size
+
+    def initialize(options = {})
+      @conn = options[:connection]
+      @all = []
+    end
+
+    def [](export_id); find(export_id); end
+    def find(export_id)
+      @all.select do |response_export|
+        response_export.id == export_id
+      end.first || QualtricsAPI::ResponseExport.new(:id => export_id , connection: @conn)
+    end
+
+  end
+end

data/lib/qualtrics_api/services/response_export_service.rb

@@ -0,0 +1,90 @@
+module QualtricsAPI
+  module Services
+    class ResponseExportService
+      attr_reader :survey_id,
+                  :response_set_id,
+                  :file_type,
+                  :last_response_id,
+                  :start_date,
+                  :end_date,
+                  :limit,
+                  :included_question_ids,
+                  :max_rows,
+                  :use_labels,
+                  :decimal_format,
+                  :seen_unanswered_recode,
+                  :use_local_time,
+                  :spss_string_length,
+                  :result
+
+      def initialize(options = {})
+        @conn = options[:connection]
+        @survey_id = options[:survey_id]
+        @response_set_id = options[:response_set_id]
+        @file_type = options[:file_type] || 'CSV'
+        @last_response_id = options[:last_response_id]
+        @start_date = options[:start_date]
+        @end_date = options[:end_date]
+        @limit = options[:limit]
+        @included_question_ids = options[:included_question_ids]
+        @max_rows = options[:max_rows]
+        @use_labels = options.has_key?(:use_labels) ? options[:use_labels] : false
+        @decimal_format = options[:decimal_format] || '.'
+        @seen_unanswered_recode = options[:seen_unanswered_recode]
+        @use_local_time = options.has_key?(:use_local_time) ? options[:use_local_time] : false
+        @spss_string_length = options[:spss_string_length]
+        @id = options[:id]
+      end
+
+      def start
+        response = @conn.get("surveys/#{@survey_id}/responseExports", export_params)
+        export_id = response.body["result"]["exportStatus"].split('/').last
+        @result = ResponseExport.new(id: export_id, connection: @conn)
+      end
+
+      def export_configurations
+        {
+          response_set_id: @response_set_id,
+          file_type: @file_type,
+          last_response_id: @last_response_id,
+          start_date: @start_date,
+          end_date: @end_date,
+          limit: @limit,
+          included_question_ids: @included_question_ids,
+          max_rows: @max_rows,
+          use_labels: @use_labels,
+          decimal_format: @decimal_format,
+          seen_unanswered_recode: @seen_unanswered_recode,
+          use_local_time: @use_local_time,
+          spss_string_length: @spss_string_length
+        }
+      end
+
+      private
+
+      def param_mappings
+        {
+          response_set_id: "responseSetId",
+          file_type: "fileType",
+          last_response_id: "lastResponseId",
+          start_date: "startDate",
+          end_date: "endDate",
+          limit: "limit",
+          included_question_ids: "includedQuestionIds",
+          max_rows: "maxRows",
+          use_labels: "useLabels",
+          decimal_format: "decimalFormat",
+          seen_unanswered_recode: "seenUnansweredRecode",
+          use_local_time: "useLocalTime",
+          spss_string_length: "spssStringLength"
+        }
+      end
+
+      def export_params
+        export_configurations.map do |config_key, value|
+          [param_mappings[config_key], value] unless value.nil? || value.to_s.empty?
+        end.compact.to_h
+      end
+    end
+  end
+end

data/lib/qualtrics_api/survey.rb

@@ -0,0 +1,29 @@
+module QualtricsAPI
+
+  class Survey
+    attr_accessor :id, :name, :owner_id, :last_modified, :status
+
+    def initialize(options = {})
+      attributes_mappings.each do |key, qualtrics_key|
+        instance_variable_set "@#{key}", options[qualtrics_key]
+      end
+      @conn = options[:connection]
+    end
+
+    def export_responses(export_options = {})
+      QualtricsAPI::Services::ResponseExportService.new(export_options.merge(survey_id: id, connection: @conn))
+    end
+
+    private
+
+    def attributes_mappings
+      {
+        :id => "id",
+        :name => "name",
+        :owner_id => "ownerId",
+        :last_modified => "lastModified",
+        :status => "status"
+      }
+    end
+  end
+end

data/lib/qualtrics_api/survey_collection.rb

@@ -0,0 +1,64 @@
+module QualtricsAPI
+
+  class SurveyCollection
+    extend Forwardable
+    include Enumerable
+
+    attr_accessor :scope_id
+    attr_reader :all
+
+    def_delegator :all, :each
+    def_delegator :all, :size
+
+    def initialize(options = {})
+      @conn = options[:connection]
+      @scope_id = options[:scope_id]
+      @all = []
+    end
+
+    def fetch(options = {})
+      @all = []
+      update_query_attributes(options)
+      parse_fetch_response(@conn.get('surveys', query_params))
+      self
+    end
+
+    def query_attributes
+      {
+        :scope_id => @scope_id
+      }
+    end
+
+    def update_query_attributes(new_attributes = {})
+      @scope_id = new_attributes[:scope_id] if new_attributes.has_key? :scope_id
+    end
+
+    def [](survey_id); find(survey_id); end
+    def find(survey_id)
+      @all.select do |survey|
+        survey.id == survey_id
+      end.first || QualtricsAPI::Survey.new("id" => survey_id , connection: @conn)
+    end
+
+    private
+
+    def attributes_mapping
+      {
+        :scope_id => "scopeId"
+      }
+    end
+
+    def query_params
+      query_attributes.map do |k, v|
+        [attributes_mapping[k], v] unless v.nil? || v.to_s.empty?
+      end.compact.to_h
+    end
+
+    def parse_fetch_response(response)
+      @all = response.body["result"].map do |result|
+        QualtricsAPI::Survey.new result.merge(connection: @conn)
+      end
+    end
+  end
+
+end

data/lib/qualtrics_api/url.rb

@@ -0,0 +1,3 @@
+module QualtricsAPI
+  URL = "https://co1.qualtrics.com:443/API/v1/"
+end

data/lib/qualtrics_api/version.rb

@@ -0,0 +1,3 @@
+module QualtricsAPI
+  VERSION = "0.0.1"
+end

data/qualtrics_api.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'qualtrics_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "qualtrics_api"
+  spec.version       = QualtricsAPI::VERSION
+  spec.authors       = ["Yurui Zhang"]
+  spec.email         = ["yuruiology@gmail.com"]
+  spec.summary       = %q{A Ruby wrapper for Qualtrics REST API v3.0}
+  spec.description   = %q{A Ruby wrapper for Qualtrics REST API version 3.0.
+                          See https://co1.qualtrics.com/APIDocs/ for API documents.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 0.9.1"
+  spec.add_dependency "faraday_middleware", "~> 0.9.1"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.2.0"
+  spec.add_development_dependency "vcr", "~> 2.9.3"
+end

data/spec/lib/client_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe QualtricsAPI::Client do
+
+  subject { QualtricsAPI::Client.new(:api_token => "someToken") }
+
+  it "has an api token" do
+    expect(subject.api_token).to eq "someToken"
+  end
+
+  it "does not allow changing the token once initialized" do
+    expect(subject).to_not respond_to(:api_token=)
+  end
+
+  describe "#response_exports" do
+    it "returns a ResponseExportCollection" do
+      expect(subject.response_exports).to be_a QualtricsAPI::ResponseExportCollection
+    end
+
+    it "sets connection" do
+      expect(subject.surveys.instance_variable_get(:@conn)).to eq subject.connection
+    end
+
+    it "caches the collection" do
+      expect(subject.response_exports.object_id).to eq subject.response_exports.object_id
+    end
+  end
+
+  describe "#surveys" do
+    it "returns a SurveyCollection" do
+      expect(subject.surveys).to be_a QualtricsAPI::SurveyCollection
+    end
+
+    it "sets connection" do
+      expect(subject.surveys.instance_variable_get(:@conn)).to eq subject.connection
+    end
+
+    it "assigns scope_id if passed" do
+      expect(subject.surveys(:scope_id => "someId").scope_id).to eq "someId"
+    end
+
+    it "caches the surveys" do
+      expect(subject.surveys.object_id).to eq subject.surveys.object_id
+    end
+  end
+
+end

data/spec/lib/response_export_collection_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe QualtricsAPI::ResponseExportCollection do
+  let(:connection) { double('connection') }
+
+  subject { described_class.new connection: connection }
+
+  it "has no @all when initialized" do
+    expect(subject.all).to eq []
+  end
+
+  it "takes a connection" do
+    expect(subject.instance_variable_get(:@conn)).to eq connection
+  end
+
+  describe "#find, #[]" do
+    let(:export_1) { QualtricsAPI::ResponseExport.new :id => "export1" }
+    let(:export_2) { QualtricsAPI::ResponseExport.new :id => "export2" }
+
+    it "finds the export by id" do
+      subject.instance_variable_set :@all, [export_1, export_2]
+      expect(subject.find("export1")).to eq export_1
+      expect(subject["export2"]).to eq export_2
+    end
+
+    it "returns a new survey with the id" do
+      sut = subject["eee 3"]
+      expect(sut).to be_a QualtricsAPI::ResponseExport
+      expect(sut.id).to eq "eee 3"
+      expect(sut.instance_variable_get(:@conn)).to eq connection
+    end
+  end
+end