quest_back 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 71ac294356aae1fe3423d0cba13cb705a1245cfd
+  data.tar.gz: 99bf75d03a7984badd0291ba474d27e07b9796fd
+SHA512:
+  metadata.gz: 83d3d479391da098c8c62d9bc1d157c0fe14708c1ad320cb76d61605519b3404ce133648a8a38007c00cc9a436882f8f052d269786c05590e8b3ab56ce180d91
+  data.tar.gz: f030b1fa5a1f02645e39386cc630cde2c08d5f5e06d2a7dd02938bb941c15905192df38c24bfe467ae3bec4c645cdffb16d5a0fb299977aa8d5c223cfe7d9299

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+bin
+config.yml

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Thorbjørn Hermansen
+
+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,147 @@
+# QuestBack
+
+Simply Ruby client for QuestBack's SOAP API.
+
+### WARNING
+
+This gem is not complete and may lack many functions provided by QuestBack.
+Please feel free to contribute and make pull requests.
+
+It is also very simplistic, only using simple hashes for both sending in arguments to the API and returning responses.
+The hash you send as argument to operation methods is more or less sent on to QuestBack.
+Maybe this will change in the future with real objects sent in to the API.
+
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'quest_back'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install quest_back
+
+## Usage
+
+### Get access - test client in console
+
+1. Go to https://response.questback.com/soapdocs/integration/ and request white listing of the IP you will make requests from.
+2. Sign in to QuestBack. Go to your account's page and fill in "Integration username and password".
+   If you have no fields under Integration Information you have to contact QuestBack to get access.
+3. Copy config.example.yml to config.yml and insert your username and password.
+4. `QuestBack.conf!` to load config.yml as default config.
+5. `QuestBack::Client.new.test_connection` to make a test connection API call. On successful connection this returns string with current namespace of integration library.
+
+
+### Example of usage
+
+```ruby
+# Read quests
+api = QuestBack::Api.new
+response = api.get_quests
+irb(main):005:0> response.results
+=> [
+    {
+      :quest_id=>"4567668",
+      :security_lock=>"m0pI8orKJp",
+      :quest_title=>"Skalars spørreundersøkelse",
+      ...
+    },
+    {
+      ...
+    }
+  ]
+
+
+# Add email invitees
+response = api.add_email_invitees(
+  quest_info: {quest_id: 4567668, security_lock: 'm0pI8orKJp'},
+  emails: ['inviso@skalar.no', 'th@skalar.no'],
+  sendduplicate: true
+)
+
+response.result
+=> "Added 2 invitations to QuestId:4567668"
+
+
+# Add respondent data
+response = api.add_respondents_data(
+  quest_info: {quest_id: 4567668, security_lock: 'm0pI8orKJp'},
+  respondents_data: {
+    respondent_data_header: {
+      respondent_data_header: [
+        {
+          title: 'Epost',
+          type: QuestBack::Api.respondent_data_header_type_for(:text),
+          is_email_field: true,
+          is_sms_field: false,
+        },
+        {
+          title: 'Navn',
+          type: QuestBack::Api.respondent_data_header_type_for(:text),
+          is_email_field: false,
+          is_sms_field: false,
+        },
+        {
+          title: 'Alder',
+          type: QuestBack::Api.respondent_data_header_type_for(:numeric),
+          is_email_field: false,
+          is_sms_field: false,
+        },
+      ]
+    },
+    respondent_data: ['th@skalar.no;Thorbjorn;32'],
+    allow_duplicate: true,
+    add_as_invitee: true
+  }
+)
+
+response.result
+=> "Added 1 respondent data to QuestId :4567668"
+```
+
+### Debug XML without making a request
+
+If you ever need to see XML generated without sending the request it can be done by doing:
+
+```ruby
+QuestBack.debug!
+QuestBack::Api.new.test_connection
+
+  DEBUG -- : HTTPI GET request to integration.questback.com (net_http)
+   INFO -- : !!!!!!!!!
+   INFO -- : !!! SOAP request hijacked by QuestBack::DebugObserver.
+   INFO -- : !!!!!!!!!
+  DEBUG -- :
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="https://integration.questback.com/2011/03" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:array="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:enum="http://schemas.microsoft.com/2003/10/Serialization/Enums">
+    <env:Body>
+      <wsdl:TestConnection>
+        <wsdl:userInfo>
+          <wsdl:Username>inviso@skalar.no</wsdl:Username>
+          <wsdl:Password>xxxxx</wsdl:Password>
+        </wsdl:userInfo>
+      </wsdl:TestConnection>
+    </env:Body>
+  </env:Envelope>
+
+QuestBack.remove_debug! # Activates real requests again
+```
+
+
+
+## Contributing
+
+1. Fork it (https://github.com/Skalar/quest_back/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 new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/config.example.yml

@@ -0,0 +1,3 @@
+username: 'my-username'
+password: 'my-password'
+http_proxy: ~

data/lib/quest_back/api.rb

@@ -0,0 +1,310 @@
+module QuestBack
+  class Api
+    # This hash contains parts of request we can include in soap operation.
+    # For instance call(:some_action, attributes, include_defaults: [:paging_info]) will
+    # slice paging_info and include it in the request.
+    DEFAULTS = {
+      paging_info: {page_no: 0, page_size: 50},
+      quest_filter: '',
+      sendduplicate: false,
+      respondents_data: {
+        delimiter: ';',
+        order!: [:respondent_data_header, :respondent_data, :delimiter, :allow_duplicate, :add_as_invitee]
+      }
+    }
+
+    # The order of the elements in the SOAP body is important for the SOAP API.
+    # For operations with multiple arguments this hash gives savon the order of which
+    # it should .. well, order the elements.
+    ORDER = {
+      get_quests: [:user_info, :paging_info, :quest_filter],
+      add_email_invitees: [:user_info, :quest_info, :emails, :sendduplicate, :language_id],
+      add_respondents_data: [:user_info, :quest_info, :respondents_data, :language_id]
+    }
+
+    # In order to provide a simple response.result and response.results interface
+    # where the actual result we care about is returned we have to give knowledge to
+    # where this result is found. As it turns out, get_quests returns it's quests within
+    # quests/quest array, and at the same time get_quest_questions returns the questions
+    # within simply it's root result element. No nestings there.. So, it seems a bit randon
+    # and we need to have this configured. I though it would be put under quest_questions/quest_question,
+    # but no such luck.
+    RESULT_KEY_NESTINGS = {
+      test_connection: [],
+      get_quests: [:quests, :quest],
+      get_language_list: [:language],
+      add_email_invitees: [],
+      add_respondents_data: []
+    }
+
+    RESPONDENTS_HEADER_TYPE = {
+      numeric: 1,
+      text: 2
+    }
+
+    NAMESPACES = {
+      'xmlns:array' => 'http://schemas.microsoft.com/2003/10/Serialization/Arrays',
+      'xmlns:enum' => 'http://schemas.microsoft.com/2003/10/Serialization/Enums'
+    }
+
+    def self.respondent_data_header_type_for(type)
+      RESPONDENTS_HEADER_TYPE.fetch(type.to_sym) { fail ArgumentError, "#{type.to_s.inspect} is an unkown respondent data header type." }
+    end
+
+    # Public: Creates a new API gateway object.
+    #
+    # Attributes
+    #   config      - A QuestBack::Configuration object. May be nil if
+    #                 QuestBack.default_configuration has been set.
+    def initialize(attributes = {})
+      attributes = ActiveSupport::HashWithIndifferentAccess.new attributes
+
+      @config = attributes[:config]
+    end
+
+
+
+
+
+
+
+    # Public: Make a test connection call to QuestBack
+    #
+    # Returns QuestBack::Response
+    def test_connection
+      call :test_connection
+    end
+
+    # Public: Get quests
+    #
+    # attributes    -   Attributes sent to QuestBack
+    #
+    # Example
+    #
+    #   response = api.get_quests paging_info: {page_size: 2}  # Limits result to two
+    #   response.results
+    #   => [result, result]
+    #
+    # Returns QuestBack::Response
+    def get_quests(attributes = {})
+      call :get_quests, attributes, include_defaults: [:paging_info, :quest_filter]
+    end
+
+    # Public: Returns a list of languages from QuestBack.
+    #
+    #
+    # Returns QuestBack::Response
+    def get_language_list
+      call :get_language_list
+    end
+
+    # Public: Invites a set of emails to a quest.
+    #
+    # attributes    -   Attributes sent to QuestBack
+    #
+    # Example
+    #
+    #   response = api.add_email_invitees(
+    #     quest_info: {quest_id: 4567668, security_lock: 'm0pI8orKJp'},
+    #     emails: ['inviso@skalar.no', 'th@skalar.no'],
+    #     sendduplicate: true, # or false as default
+    #     language_id: 123, # optional
+    #   )
+    #
+    # Returns QuestBack::Response
+    def add_email_invitees(attributes = {})
+      call :add_email_invitees, attributes, include_defaults: [:sendduplicate]
+    end
+
+    # Public: Add respondent data to a quest - optionally send as invitee as well.
+    #
+    # attributes    -   Attributes sent to QuestBack
+    #
+    # QuestBack is doing a bit of CSV over XML here? As you need to serialize
+    # respondent_data as a string with a delimiter ala CSV. The order of the
+    # data must match the order of respondent_data_header. I guess simply using XML
+    # and named elements was too easy? :-)
+    #
+    # Example
+    #
+    #   response = api.add_respondents_data(
+    #     quest_info: {quest_id: 4567668, security_lock: 'm0pI8orKJp'},
+    #     respondents_data: {
+    #       respondent_data_header: {
+    #         respondent_data_header: [
+    #           {
+    #             title: 'Epost',
+    #             type: QuestBack::Api.respondent_data_header_type_for(:text),
+    #             is_email_field: true,
+    #             is_sms_field: false,
+    #           },
+    #           {
+    #             title: 'Navn',
+    #             type: QuestBack::Api.respondent_data_header_type_for(:text),
+    #             is_email_field: false,
+    #             is_sms_field: false,
+    #           },
+    #           {
+    #             title: 'Alder',
+    #             type: QuestBack::Api.respondent_data_header_type_for(:numeric),
+    #             is_email_field: false,
+    #             is_sms_field: false,
+    #           },
+    #         ]
+    #       },
+    #       respondent_data: ['th@skalar.no;Thorbjorn;32'], # According to QuestBack's doc you can only do one here
+    #       allow_duplicate: true,
+    #       add_as_invitee: true
+    #     }
+    #   )
+    #
+    # You may override respondent_data's delimiter in string too.
+    #
+    # Returns QuestBack::Response
+    def add_respondents_data(attributes = {})
+      call :add_respondents_data, attributes, include_defaults: [:respondents_data]
+    end
+
+
+
+
+
+    # Public: Savon client.
+    #
+    # Savon client all API method calls will go through.
+    def client
+      @client ||= begin
+        client_config = {
+          wsdl: config.wsdl,
+          namespace: config.soap_namespace,
+          log_level: config.log_level,
+          element_form_default: :qualified,
+          namespaces: NAMESPACES
+        }
+
+        client_config[:proxy] = config.http_proxy if config.http_proxy.present?
+
+        Savon::Client.new client_config
+      end
+    end
+
+
+    # Public: Configuration for the API.
+    #
+    # Returns a QuestBack::Configuration object
+    def config
+      @config || QuestBack.default_configuration || fail(QuestBack::Error, 'No configuration given or found on QuestBack.default_configuration.')
+    end
+
+
+
+
+    private
+
+    def call(operation_name, attributes = {}, options = {})
+      options[:operation_name] = operation_name
+
+      options_to_response = {
+        operation_name: options[:operation_name],
+        result_key_nestings: RESULT_KEY_NESTINGS.fetch(operation_name) { fail KeyError, "You must configure RESULT_KEY_NESTINGS for #{operation_name}" }
+      }
+
+      savon_response = client.call operation_name, build_hash_for_savon_call(attributes, options)
+
+      Response.new savon_response, options_to_response
+    end
+
+
+    # Private: Builds a hash for savon call - include user info and other defaults you ask it to
+    #
+    # attributes    -   A hash representing attributes the client sent to us which it expects us to send to QuestBack
+    # options       -   A hash where we can send in options:
+    #                     :include_defaults   -   Give an array with key names to slice from DEFAULTS and mix in with
+    #                                             the rest of the attributes.
+    #
+    # Returns a merged hash for Savon client
+    def build_hash_for_savon_call(attributes = {}, options = {})
+      user_info = {user_info: {username: config.username, password: config.password}}
+      message = user_info.merge attributes
+
+      if default_keys = options[:include_defaults]
+        message = DEFAULTS.slice(*Array.wrap(default_keys)).deep_merge message
+      end
+
+      if order = ORDER[options[:operation_name]]
+        unkown_keys = attributes.keys - order
+
+        if unkown_keys.any?
+          fail ArgumentError, "Unkown attributes given to #{options[:operation_name]}: #{unkown_keys.join(', ')}. Attributes' order needs to be configured in #{self.class.name}::ORDER."
+        end
+
+        message[:order!] = order & message.keys
+      end
+
+      {
+        message: transform_hash_for_quest_back(message)
+      }
+    end
+
+
+    # Private: Transforms given hash as how Savon needs it to build the correct SOAP body.
+    #
+    # Since QuestBack's API needs to have elements like this:
+    #
+    # <wsdl:TestConnection>
+    #   <wsdl:userInfo>
+    #     <wsdl:Username>
+    #     ...
+    #
+    # We cannot simply use Savon's convert_request_keys_to config, as it translate all keys.
+    # We need some keys camelcased (keys within nested hashes) and some lower_camelcased (keys in the outer most hash).
+    #
+    # Thus we map our inner attributes, for instance for userInfo to camelcase and keeps them
+    # as strings so Savon will not manipulate them.
+    #
+    # I guess this helper method here is kinda not optimal, and we may have a simple class / struct
+    # which can do this job for us, so the api class does not have multiple responsibilites. Oh well,
+    # works for now.
+    def transform_hash_for_quest_back(hash, transform_keys = false)
+      Hash[
+        hash.map do |key, value|
+          if key == :order!
+            # Key was :order! - it has special meaning: The symbols within it's array are used to
+            # dictate order of elements. If transform_keys is false we are on "root keys". These are
+            # keept as symbols and Savon does it's magic and we'll do nothing. If it is true it means that keys
+            # on this level is put to camelcase and the values in the :order! array must match this.
+            if transform_keys
+              value = value.map { |v| v.to_s.camelcase }
+            end
+          else
+            key = transform_keys ? key.to_s.camelcase : key
+
+            # Oh my god this is quick, dirty and mega hackish!
+            # Type element in the RespondentDataHeader must be in namespace enum.
+            key = "enum:Type" if key == "Type"
+
+            # In some cases we would like to transform values as well as the key
+            value = case value
+            when Hash
+              # Keep on transforming recursively..
+              transform_hash_for_quest_back value, true
+            when Array
+              if value.all? { |v| v.is_a? String }
+                # Put it in a structure QuestBack likes..
+                {'array:string' => value}
+              elsif value.all? { |v| v.is_a? Hash }
+                # Keep on transforming recursively..
+                value.map { |hash| transform_hash_for_quest_back(hash, true) }
+              end
+            else
+              # We don't know anything better - just let value fall through
+              value
+            end
+          end
+
+          [key, value]
+        end
+      ]
+    end
+  end
+end

data/lib/quest_back/configuration.rb

@@ -0,0 +1,34 @@
+module QuestBack
+  class Configuration
+    API_DEFAULTS = {
+      wsdl: 'https://integration.questback.com/integration.svc?wsdl',
+      soap_namespace: 'https://integration.questback.com/2011/03',
+      log_level: :debug
+    }
+
+    attr_accessor :http_proxy, :wsdl, :soap_namespace, :log_level, :username, :password
+
+    def initialize(attributes = {})
+      assign API_DEFAULTS
+      assign attributes
+    end
+
+    def []=(name, value)
+      public_send "#{name}=", value
+    end
+
+    def [](name)
+      public_send name
+    end
+
+
+
+    private
+
+    def assign(attributes)
+      attributes.each_pair do |name, value|
+        self[name] = value
+      end
+    end
+  end
+end

data/lib/quest_back/debug_observer.rb

@@ -0,0 +1,18 @@
+module QuestBack
+  # Public: Simple debug observer.
+  #
+  # Hijacks operations and pretty prints XML which could have been sent.
+  class DebugObserver
+    def notify(operation_name, builder, globals, locals)
+      logger = globals[:logger]
+
+      logger.info "!!!!!!!!!"
+      logger.info "!!! SOAP request hijacked by #{self.class.name}."
+      logger.info "!!!!!!!!!"
+
+      logger.debug "\n\n" + Nokogiri.XML(builder.to_s).to_xml + "\n"
+
+      HTTPI::Response.new(200, {}, '')
+    end
+  end
+end

data/lib/quest_back/error.rb

@@ -0,0 +1,7 @@
+module QuestBack
+  class Error < StandardError
+    # Public: Raised when you ask response object for a single result when response contained multiple
+    class MultipleResultsFound < self
+    end
+  end
+end

data/lib/quest_back/response.rb

@@ -0,0 +1,45 @@
+module QuestBack
+  # Public: Simple proxy object decorating Savon's response.
+  #
+  # Main motication for class is to have #result and #results as a common
+  # interface to get to respons' result(s), with all outer response nesting
+  # removed.
+  #
+  # At the moment you are still getting back simple hashes from both methods.
+  class Response
+    attr_reader :savon_response, :operation_name, :result_key_nestings
+
+    delegate *Savon::Response.instance_methods(false), to: :savon_response
+
+    def initialize(savon_response, options = {})
+      @savon_response = savon_response
+      @operation_name = options[:operation_name] or fail ArgumentError.new('Missing operation_name')
+      @result_key_nestings = options[:result_key_nestings] or fail ArgumentError.new('Missing result key nestings')
+    end
+
+    def result
+      extract_result.tap do |result|
+        fail QuestBack::Error::MultipleResultsFound if result.is_a? Array
+      end
+    end
+
+    def results
+      Array.wrap extract_result
+    end
+
+
+
+
+    private
+
+    def extract_result
+      result_container = savon_response.body["#{operation_name}_response".to_sym]["#{operation_name}_result".to_sym]
+
+      result = result_key_nestings.inject(result_container) do |result, key|
+        result.fetch key do
+          fail KeyError, "Expected #{result.inspect} to contain #{key_in_body}. Respons' result_key_nestings is wrong, or unexpected result from QuestBack."
+        end
+      end
+    end
+  end
+end

data/lib/quest_back/version.rb

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

data/lib/quest_back.rb

@@ -0,0 +1,57 @@
+require "quest_back/version"
+
+require "pathname"
+require "active_support/all"
+require "savon"
+
+
+module QuestBack
+  extend ActiveSupport::Autoload
+
+  autoload :Configuration
+  autoload :Error
+  autoload :Response
+  autoload :Api
+  autoload :DebugObserver
+
+
+  # Public: Default configuration is read from here.
+  #
+  # Returns a Configuration object
+  mattr_accessor :default_configuration
+
+
+
+
+
+  # :nodoc:
+  #
+  # Read config from file, just makes it easy for me to spin up
+  # a console, read API credentials and get going
+  def self.conf!
+    read_default_configuration_from_file 'config.yml'
+  end
+
+  # :nodoc:
+  #
+  # Injects a debug observer which hijacks requests so we don't send anything.
+  # We'll pretty print the SOAP body for inspection.
+  def self.debug!
+    remove_debug!
+    Savon.observers << DebugObserver.new
+  end
+
+  # :nodoc:
+  #
+  # Removes any debug observers.
+  def self.remove_debug!
+    Savon.observers.delete_if { |observer| observer.is_a? DebugObserver }
+  end
+
+  # :nodoc:
+  def self.read_default_configuration_from_file(pathname)
+    path = Pathname.new pathname
+    path = Pathname.new [Dir.pwd, pathname].join('/') unless path.absolute?
+    self.default_configuration = Configuration.new YAML.load_file(path)
+  end
+end