Class: QuestBack::Api

Inherits:
Object
  • Object
show all
Defined in:
lib/quest_back/api.rb

Constant Summary collapse

DEFAULTS =

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.

{
  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]
  }
}
ORDER =

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.

{
  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],
  add_respondents_data_with_sms_invitation: [
    :user_info, :quest_info, :respondents_data, :language_id,
    :sms_from_number, :sms_from_text, :sms_message
  ]
}
RESULT_KEY_NESTINGS =

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.

{
  test_connection: [],
  get_quests: [:quests, :quest],
  get_language_list: [:language],
  add_email_invitees: [],
  add_respondents_data: [],
  add_respondents_data_with_sms_invitation: []
}
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'
}

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes = {}) ⇒ Api

Public: Creates a new API gateway object.

Attributes

config      - A QuestBack::Configuration object. May be nil if
              QuestBack.default_configuration has been set.



66
67
68
69
70
 
# File 'lib/quest_back/api.rb', line 66

def initialize(attributes = {})
  attributes = ActiveSupport::HashWithIndifferentAccess.new attributes

  @config = attributes[:config]
end

Class Method Details

.respondent_data_header_type_for(type) ⇒ Object 



55
56
57
58
59
 
# File 'lib/quest_back/api.rb', line 55

def self.respondent_data_header_type_for(type)
  RESPONDENTS_HEADER_TYPE.fetch(type.to_sym) do
    fail ArgumentError, "#{type.to_s.inspect} is an unkown respondent data header type."
  end
end

Instance Method Details

#add_email_invitees(attributes = {}) ⇒ Object

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: ['[email protected]', '[email protected]'],
  sendduplicate: true, # or false as default
  language_id: 123, # optional
)

Returns QuestBack::Response



122
123
124
 
# File 'lib/quest_back/api.rb', line 122

def add_email_invitees(attributes = {})
  call :add_email_invitees, attributes, include_defaults: [:sendduplicate]
end

#add_respondents_data(attributes = {}) ⇒ Object

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: ['[email protected];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



171
172
173
 
# File 'lib/quest_back/api.rb', line 171

def add_respondents_data(attributes = {})
  call :add_respondents_data, attributes, include_defaults: [:respondents_data]
end

#add_respondents_data_with_sms_invitation(attributes = {}) ⇒ Object

Public: Add respondent data to a quest with SMS invitation

attributes - Attributes sent to QuestBack

Example

response = api.add_respondents_data_with_sms_invitation(
  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: 'Phone',
          type: QuestBack::Api.respondent_data_header_type_for(:text),
          is_email_field: false,
          is_sms_field: true,
        }
      ]
    },
    # According to QuestBack's doc you can only do one respondent data,
    # even though it for sure is an array. Phone numbers must be given
    # on with country code first.
    respondent_data: ['[email protected];4711223344'],
    allow_duplicate: true,
    add_as_invitee: true
  },
  sms_from_number: 11111111,
  sms_from_text: 'Inviso AS',
  sms_message: 'Hello - please join our quest!'
)

You may override respondent_data’s delimiter in string too.

Returns QuestBack::Response



216
217
218
 
# File 'lib/quest_back/api.rb', line 216

def add_respondents_data_with_sms_invitation(attributes = {})
  call :add_respondents_data_with_sms_invitation, attributes, include_defaults: [:respondents_data]
end

#client ⇒ Object

Public: Savon client.

Savon client all API method calls will go through.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/quest_back/api.rb', line 227

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

#config ⇒ Object

Public: Configuration for the API.

Returns a QuestBack::Configuration object



247
248
249
 
# File 'lib/quest_back/api.rb', line 247

def config
  @config || QuestBack.default_configuration || fail(QuestBack::Error, 'No configuration given or found on QuestBack.default_configuration.')
end

#get_language_list ⇒ Object

Public: Returns a list of languages from QuestBack.

Returns QuestBack::Response



104
105
106
 
# File 'lib/quest_back/api.rb', line 104

def get_language_list
  call :get_language_list
end

#get_quests(attributes = {}) ⇒ Object

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



96
97
98
 
# File 'lib/quest_back/api.rb', line 96

def get_quests(attributes = {})
  call :get_quests, attributes, include_defaults: [:paging_info, :quest_filter]
end

#test_connection ⇒ Object

Public: Make a test connection call to QuestBack

Returns QuestBack::Response



81
82
83
 
# File 'lib/quest_back/api.rb', line 81

def test_connection
  call :test_connection
end