survey-gizmo-ruby 4.1.0 → 5.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 00dc389fa6c3415227ed3ea344c8ec1b7152eaa8
-  data.tar.gz: 342bda557eb8df193f19958de0337a23504c5a49
+  metadata.gz: 49463d6fa875d93712a1da0951dac1e0053747ee
+  data.tar.gz: 339404fe4dae766bd04abc675cd7fbd34f244488
 SHA512:
-  metadata.gz: 35695df30398092c26e8fdb48eead2e669753df6cddd4a615eb70688ede385a80e6731adfd29d33bc83ae93b25a15d875c5cf3d2efa7519cb3124e02b018f6a5
-  data.tar.gz: 434990416b53a6cdd22c00f102f888125ec5a501c800c2c8df41fe1a8a126d510228595f8d9b4fd7a6482fb6644235d029564ca476c9166ccb14a7ccea3940c5
+  metadata.gz: 38c186f0d5e12964b5b559aeb0c674c2291d1ade6f0518c7ed681e806cb3a56cb05d791b5f9374655cc81fe491853406c74d5dab72ba126aa668195963d4ca08
+  data.tar.gz: ea37139f7d8fdad647d2b38db73cef15a065b6b6098a05efbbd911e8dda70404b8979bb42e6fad9f1b9eeaa41f1df49e8ddb8e0f7f34708569255f1823ebd388

data/README.md

@@ -6,14 +6,22 @@ Currently supports SurveyGizmo API **v4** (default) and **v3**.
 
 ## Versions
 
+### Major Changes in 5.x
+
+* **BREAKING CHANGE**: `.all` returns an `Enumerator`, not an `Array`. This will break your code if you are using the return value of `.all` without iterating over it.
+* **BREAKING CHANGE**: `SurveyCampaign` has been renamed `Campaign` to be in line with the other model names.
+* FEATURE: `.all` will automatically paginate responses for you with the `:all_pages` option. There are also some built in methods like `Survey#responses` that will auto paginate.
+* FEATURE: Built in retries. 1 retry with a 60 second backoff is the default but can be configured.
+* FEATURE: `Response#parsed_answers` returns an array of `Answers` (new class) that are sane, stable Ruby objects instead of the sort of wild and wooly way SurveyGizmo has chosen to represent survey responses.
+
 ### Major Changes in 4.x
 
-* BREAKING CHANGE: There is no more error tracking.  If the API gives an error or bad response, an exception will be raised.
-* BREAKING CHANGE: There is no more ```copy``` method
+* **BREAKING CHANGE**: There is no more error tracking.  If the API gives an error or bad response, an exception will be raised.
+* **BREAKING CHANGE**: There is no more ```copy``` method
 
 ### Major Changes in 3.x
 
-* BREAKING CHANGE: Configuration is completely different
+* **BREAKING CHANGE**: Configuration is completely different
 * Important Change: Defaults to using the v4 SurveyGizmo API endpoint to take advantage of various API bug fixes (notably team ownership is broken in v3)
 
 ### Old versions
@@ -30,7 +38,7 @@ Currently supports SurveyGizmo API **v4** (default) and **v3**.
 gem 'survey-gizmo-ruby'
 ```
 
-## Basic Usage
+## Configuration
 
 ```ruby
 require 'survey-gizmo-ruby'
@@ -43,14 +51,58 @@ SurveyGizmo.configure do |config|
   # Optional - Defaults to v4, but you can probably set to v3 safely if you suspect a bug in v4
   config.api_version = 'v4'
 
+  # Optional - Set if you need to hit a different base URL (e.g. the .eu domain)
+  config.api_url = 'https://restapi.surveygizmo.eu'
+
   # Optional - Defaults to 50, maximum 500. Setting too high may cause SurveyGizmo to start throwing timeouts.
   config.results_per_page = 100
 end
+```
+
+### Retries
+
+The [Pester](https://github.com/lumoslabs/pester) gem is used to manage retry strategies.  By default it will be configured to handle 1 retry with a 60 second timeout upon encountering basic net timeouts and rate limit errors, which is enough for most people's needs.
+
+If, however, you want to specify more retries, a longer backoff, new classes to retry on, or otherwise get fancy with the retry strategy, you can configured Pester directly.  SurveyGizmo API calls are executed in Pester's `survey_gizmo_ruby` environment, so anything you configure there will apply to all your requests.
+
+```ruby
+# For example, to change the retry interval, max attempts, or exception classes to be retried:
+Pester.configure do |config|
+  # Retry 10 times
+  config.environments[:survey_gizmo_ruby][:max_attempts] = 10
+  # Backoff for 2 minutes
+  config.environments[:survey_gizmo_ruby][:delay_interval] = 120
+  # Retry different exception classes
+  config.environments[:survey_gizmo_ruby][:retry_error_classes] = [MyExceptionClass, MyOtherExceptionClass]
+end
+
+# To set Pester to retry on ALL exception classes, do this (use with caution! Can include exceptions Rails likes to throw on SIGHUP)
+Pester.configure do |config|
+  config.environments[:survey_gizmo_ruby][:retry_error_classes] = nil
+end
+```
+
+## Usage
+
+### Retrieving Data
 
-# Retrieve the first page of your surveys
-surveys = SurveyGizmo::API::Survey.all
-# Retrieve ALL your surveys (handle pagination for you)
-surveys = SurveyGizmo::API::Survey.all(all_pages: true)
+`SurveyGizmo::API::Klass.first` returns a single instance of the resource.
+
+`SurveyGizmo::API::Klass.all` returns an `Enumerator` you can use to loop through your results/questions/surveys etc.  It will actually iterate through ALL your results (pagination will be handled for you) if you pass `all_pages: true`.
+
+Because `.all` returns an `Enumerator`, you have to call `.to_a` or some other enumerable method to trigger actual API data retrieval.
+```ruby
+SurveyGizmo::API::Survey.all(all_pages: true)      # => #<Enumerator: #<Enumerator::Generator>:each>
+SurveyGizmo::API::Survey.all(all_pages: true).to_a # => [Survey, Survey, Survey, ...]
+```
+
+### Examples
+
+```ruby
+# Iterate over your all surveys directly with the iterator
+SurveyGizmo::API::Survey.all(all_pages: true).each { |survey| do_something_with(survey) }
+# Iterate over the 1st page of your surveys
+SurveyGizmo::API::Survey.all(page: 1).each { |survey| do_something_with(survey) }
 
 # Retrieve the survey with id: 12345
 survey = SurveyGizmo::API::Survey.first(id: 12345)
@@ -61,10 +113,10 @@ survey.server_has_new_results_since?(Time.now.utc - 2.days) # => true
 survey.team_names # => ['Development', 'Test']
 survey.belongs_to?('Development') # => true
 
-# Retrieving Questions for a given survey.  Note that page_id is a required parameter.
-questions = SurveyGizmo::API::Question.all(survey_id: survey.id, page_id: 1)
-# Or just retrieve all questions for all pages of this survey
+# Retrieve all questions for all pages of this survey
 questions = survey.questions
+# Strip out instruction, urlredirect, logic, media, and other non question "questions"
+questions = survey.actual_questions
 
 # Create a question for your survey.  The returned object will be given an :id parameter by SG.
 question = SurveyGizmo::API::Question.create(survey_id: survey.id, title: 'Do you like ruby?', type: 'checkbox')
@@ -74,34 +126,41 @@ question.save
 # Destroy a question
 question.destroy
 
-# Retrieve 2nd page of SurveyResponses for a given survey.
-responses = SurveyGizmo::API::Response.all(survey_id: 12345, page: 2)
-# Retrieve all responses for a given survey.
-responses = SurveyGizmo::API::Response.all(all_pages: true, survey_id: 12345)
-# Retrieving page 3 of completed, non test data SurveyResponses submitted within the past 3 days
-# for contact id 999. This example shows you how to use some of the gem's built in filters and
-# filter generators as well as how to construct your own raw filter.
+# Iterate over all your Responses
+survey.responses.each { |response| do_something_with(response) }
+# Use filters to limit results - this example will iterate over page 3 of completed, non test data
+# SurveyResponses submitted within the past 3 days for contact 999. It demonstrates how to use some of the gem's
+# built in filters/generators as well as how to construct a filter.
 # See: http://apihelp.surveygizmo.com/help/article/link/filters for more info on filters
-responses = SurveyGizmo::API::Response.all(
-  survey_id: 12345,
-  page: 3,
-  filters: [
-    SurveyGizmo::API::Response::NO_TEST_DATA,
-    SurveyGizmo::API::Response::ONLY_COMPLETED,
-    SurveyGizmo::API::Response.submitted_since_filter(Time.now - 72.hours),
-    {
-      field: 'contact_id',
-      operator: '=',
-      value: 999
-    }
-  ]
-)
+filters = [
+  SurveyGizmo::API::Response::NO_TEST_DATA,
+  SurveyGizmo::API::Response::ONLY_COMPLETED,
+  SurveyGizmo::API::Response.submitted_since_filter(Time.now - 72.hours),
+  {
+    field: 'contact_id',
+    operator: '=',
+    value: 999
+  }
+]
+survey.responses(page: 3, filters: filters).each { |response| do_stuff_with(response) }
+
+# Parse the answer hash into a more usable format.
+# Answers with keys but empty values will not be returned.
+# "Other" text for some questions is parsed to Answer#other_text; all other answers to Answer#answer_text
+# Custom table question answers have the question_pipe string parsed out to Answer#question_pipe.
+# See http://apihelp.surveygizmo.com/help/article/link/surveyresponse-per-question for more info on answers
+response.parsed_answers => # [#<SurveyGizmo::API::Answer @survey_id=12345, @question_id=1, @option_id=2, @answer_text='text'>]
+
+# Retrieve all answers from all responses to all surveys, write rows to your database
+SurveyGizmo::API::Survey.all(all_pages: true).each do |survey|
+  survey.responses.each do |response|
+    response.parsed_answers.each do |answer|
+      MyLocalSurveyGizmoResponseModel.create(answer.to_hash)
+    end
+  end
+end
 ```
 
-## On API Timeouts
-
-API timeouts are a regular occurrence with the SurveyGizmo API.  At Lumos Labs we use our own [Pester gem](https://github.com/lumoslabs/pester) to manage retry strategies.  It might work for you.
-
 ## Debugging
 
 The GIZMO_DEBUG environment variable will trigger full printouts of SurveyGizmo's HTTP responses and variable introspection for almost everything.
@@ -114,7 +173,7 @@ bundle exec rails whatever
 
 ## Adding API Objects
 
-Currently, the following API objects are included in the gem: `Survey`, `Question`, `Option`, `Page`, `Response`, `EmailMessage`, `SurveyCampaign`, `Contact`, `AccountTeams`. If you want to use something that isn't included you can easily write a class that handles it. Here's an example of the how to do so:
+Currently, the following API objects are included in the gem: `Survey`, `Question`, `Option`, `Page`, `Response`, `EmailMessage`, `Campaign`, `Contact`, `AccountTeams`. If you want to use something that isn't included you can easily write a class that handles it. Here's an example of the how to do so:
 
 ```ruby
 class SomeObject
@@ -128,15 +187,16 @@ class SomeObject
   attribute :type,        String
   attribute :created_on,  DateTime
 
-  # defing the paths used to retrieve/set info
-  route '/something/:id', via: [:get, :update, :delete]
-  route '/something',     via: :create
-
-  # this must be defined with the params that would be included in any route related
-  # to an instance of SomeObject
-  def to_param_options
-    { id: self.id }
-  end
+  # define the paths used to retrieve/set info
+  # if the routing is such that :get, :update, and :delete only append /:id to the main route, do this
+  @route = '/something'
+  # but if the class needs special routing, specify each method route with a hash:
+  @route = {
+    get: '/something/:id',
+    update: '/something/weird/:id',
+    create: '/something',
+    delete: /something/delete/:id'
+  }
 end
 ```
 
@@ -154,14 +214,12 @@ The [Virtus](https://github.com/solnic/virtus) gem is included to handle the att
 
 ## Desirable/Missing Features
 
+* Better specs with VCR/Webmock
+* OAuth authentication
 * Better foreign language support
-* Use Faraday instead of Httparty (partied too hard)
-* Better specs with VCR/Webmock would be nice.
 * There are several API objects that are available and not included in this gem.  AccountTeams, for instance, has some skeleton code but is untested.
-* OAuth authentication ability.
 
 # Copyright
 
 Copyright (c) 2012 RipTheJacker. See LICENSE.txt for
 further details.
-

data/lib/survey-gizmo-ruby.rb

@@ -1,27 +1,19 @@
-require 'active_support/core_ext/string'
-require 'active_support/core_ext/module'
+require 'active_support/concern'
+require 'active_support/core_ext/array'
 require 'active_support/core_ext/hash'
+require 'active_support/core_ext/module'
 require 'active_support/core_ext/object/blank'
-require 'active_support/concern'
+require 'active_support/core_ext/string'
 require 'active_support/time_with_zone'
+
 require 'awesome_print'
 require 'digest/md5'
-require 'httparty'
+require 'faraday'
+require 'faraday_middleware'
+require 'logger'
+require 'pester'
 require 'virtus'
 
-require 'survey_gizmo/version'
-require 'survey_gizmo/survey_gizmo'
-require 'survey_gizmo/configuration'
-require 'survey_gizmo/multilingual_title'
-require 'survey_gizmo/resource'
-require 'survey_gizmo/rest_response'
-
-require 'survey_gizmo/api/account_teams'
-require 'survey_gizmo/api/contact'
-require 'survey_gizmo/api/email_message'
-require 'survey_gizmo/api/option'
-require 'survey_gizmo/api/page'
-require 'survey_gizmo/api/question'
-require 'survey_gizmo/api/response'
-require 'survey_gizmo/api/survey'
-require 'survey_gizmo/api/survey_campaign'
+path = File.join(File.expand_path(File.dirname(__FILE__)), 'survey_gizmo')
+Dir["#{path}/*.rb"].each { |f| require f }
+Dir["#{path}/**/*.rb"].each { |f| require f }

data/lib/survey_gizmo/api/account_teams.rb

@@ -13,12 +13,7 @@ module SurveyGizmo
       attribute :default_role,  String
       attribute :status,        String
 
-      route '/accountteams/:id', via: [:get, :update, :delete]
-      route '/accountteams',     via: :create
-
-      def to_param_options
-        { id: self.id }
-      end
+      @route = '/accountteams'
     end
   end
 end

data/lib/survey_gizmo/api/answer.rb

@@ -0,0 +1,59 @@
+module SurveyGizmo
+  module API
+    class Answer
+      include Virtus.model
+
+      attribute :key,           String
+      attribute :value,         String
+      attribute :survey_id,     Integer
+      attribute :response_id,   Integer
+      attribute :question_id,   Integer
+      attribute :option_id,     Integer
+      attribute :submitted_at,  DateTime
+      attribute :answer_text,   String
+      attribute :other_text,    String
+      attribute :question_pipe, String
+
+      def initialize(attrs = {})
+        self.attributes = attrs
+
+        case key
+        when /\[question\((\d+)\),\s*option\((\d+|"\d+-other")\)\]/
+          @question_id, @option_id = $1, $2
+
+          if @option_id =~ /other/
+            @option_id.delete!('-other"')
+            self.other_text = value
+          end
+        when /\[question\((\d+)\),\s*question_pipe\("(.*)"\)\]/
+          @question_id = $1
+          @question_pipe = $2
+        when /\[question\((\d+)\)\]/
+          @question_id = $1
+        else
+          fail "Can't recognize pattern for #{attrs[:key]} => #{attrs[:value]} - you may have to parse your answers manually."
+        end
+
+        self.question_id = @question_id.to_i
+        if @option_id
+          fail "Bad option_id #{option_id}!" if option_id.to_i == 0 && option_id != '0'
+          self.option_id = @option_id.to_i
+        end
+      end
+
+      # Strips out the answer_text when there is a valid option_id
+      def to_hash
+        {
+          response_id: response_id,
+          question_id: question_id,
+          option_id: option_id,
+          question_pipe: question_pipe,
+          submitted_at: submitted_at,
+          survey_id: survey_id,
+          other_text: other_text,
+          answer_text: option_id || other_text ? nil : answer_text
+        }.reject { |k,v| v.nil? }
+      end
+    end
+  end
+end

data/lib/survey_gizmo/api/{survey_campaign.rb → campaign.rb}

@@ -1,6 +1,6 @@
 module SurveyGizmo; module API
   # @see SurveyGizmo::Resource::ClassMethods
-  class SurveyCampaign
+  class Campaign
     include SurveyGizmo::Resource
 
     attribute :id,              Integer
@@ -23,11 +23,10 @@ module SurveyGizmo; module API
     attribute :surveycampaign,  Integer
     attribute :copy,            Boolean
 
-    route '/survey/:survey_id/surveycampaign/:id', via: [:get, :update, :delete]
-    route '/survey/:survey_id/surveycampaign', via: :create
+    @route = '/survey/:survey_id/surveycampaign'
 
-    def to_param_options
-      { id: self.id, survey_id: self.survey_id }
+    def contacts(conditions = {})
+      Contact.all(conditions.merge(children_params).merge(all_pages: !conditions[:page]))
     end
   end
 end; end

data/lib/survey_gizmo/api/contact.rb

@@ -36,11 +36,6 @@ module SurveyGizmo; module API
     attribute :scustomfield9,           String
     attribute :scustomfield10,          String
 
-    route '/survey/:survey_id/surveycampaign/:campaign_id/contact/:id', via: [:get, :update, :delete]
-    route '/survey/:survey_id/surveycampaign/:campaign_id/contact', via: :create
-
-    def to_param_options
-      { id: self.id, survey_id: self.survey_id, campaign_id: self.campaign_id }
-    end
+    @route = '/survey/:survey_id/surveycampaign/:campaign_id/contact'
   end
-end; end
+end; end

data/lib/survey_gizmo/api/email_message.rb

@@ -20,11 +20,6 @@ module SurveyGizmo; module API
     attribute :datecreated,       DateTime
     attribute :datemodified,      DateTime
 
-    route '/survey/:survey_id/surveycampaign/:campaign_id/emailmessage/:id', :via => [:get, :update, :delete]
-    route '/survey/:survey_id/surveycampaign/:campaign_id/emailmessage', :via => :create
-
-    def to_param_options
-      { id: self.id, survey_id: self.survey_id, campaign_id: self.campaign_id }
-    end
+    @route = '/survey/:survey_id/surveycampaign/:campaign_id/emailmessage'
   end
 end; end

data/lib/survey_gizmo/api/option.rb

@@ -11,11 +11,6 @@ module SurveyGizmo; module API
     attribute :value,         String
     attribute :properties,    Hash
 
-    route '/survey/:survey_id/surveypage/:page_id/surveyquestion/:question_id/surveyoption',     via: :create
-    route '/survey/:survey_id/surveypage/:page_id/surveyquestion/:question_id/surveyoption/:id', via: [:get, :update, :delete]
-
-    def to_param_options
-      { id: self.id, survey_id: self.survey_id, page_id: self.page_id, question_id: self.question_id }
-    end
+    @route = '/survey/:survey_id/surveypage/:page_id/surveyquestion/:question_id/surveyoption'
   end
-end; end
+end; end

data/lib/survey_gizmo/api/page.rb

@@ -1,3 +1,5 @@
+require 'survey_gizmo/api/question'
+
 module SurveyGizmo; module API
   # @see SurveyGizmo::Resource::ClassMethods
   class Page
@@ -9,21 +11,23 @@ module SurveyGizmo; module API
     attribute :properties,    Hash
     attribute :after,         Integer
     attribute :survey_id,     Integer
+    attribute :questions,     Array[Question]
 
-    # routing
-    route '/survey/:survey_id/surveypage', via: :create
-    route '/survey/:survey_id/surveypage/:id', via: [:get, :update, :delete]
+    @route = '/survey/:survey_id/surveypage'
 
     def survey
-      @survey ||= SurveyGizmo::API::Survey.first(id: survey_id)
+      @survey ||= Survey.first(id: survey_id)
     end
 
     def questions
-      @questions ||= SurveyGizmo::API::Question.all(survey_id: survey_id, page_id: id, all_pages: true)
-    end
+      # See note about broken subquestions in resource.rb
+      @questions.flat_map { |q| q.sub_question_skus }.each do |sku|
+        sku = sku[1] if sku.is_a?(Array)
+        next if @questions.find { |q| q.id == sku }
+        @questions << Question.first(children_params.merge(id: sku))
+      end
 
-    def to_param_options
-      { id: self.id, survey_id: self.survey_id }
+      @questions.each { |q| q.attributes = children_params }
     end
   end
 end; end