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_without_email_invitation: [: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_without_email_invitation: [],
  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.



68
69
70
71
72
 
# File 'lib/quest_back/api.rb', line 68

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

  @config = attributes[:config]
end

Class Method Details

.respondent_data_header_type_for(type) ⇒ Object 



57
58
59
60
61
 
# File 'lib/quest_back/api.rb', line 57

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



124
125
126
 
# File 'lib/quest_back/api.rb', line 124

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



173
174
175
 
# File 'lib/quest_back/api.rb', line 173

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



268
269
270
 
# File 'lib/quest_back/api.rb', line 268

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

#add_respondents_data_without_email_invitation(attributes = {}) ⇒ Object

Public: Add respondent data to a quest - optionally send as invitee as well.

This will not send an email invitation through Questback's platform

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_without_email_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: '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



223
224
225
 
# File 'lib/quest_back/api.rb', line 223

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

#client ⇒ Object

Public: Savon client.

Savon client all API method calls will go through.



279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/quest_back/api.rb', line 279

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



299
300
301
 
# File 'lib/quest_back/api.rb', line 299

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



106
107
108
 
# File 'lib/quest_back/api.rb', line 106

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



98
99
100
 
# File 'lib/quest_back/api.rb', line 98

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



83
84
85
 
# File 'lib/quest_back/api.rb', line 83

def test_connection
  call :test_connection
end