responsys-api 0.0.3 → 0.0.4

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NThmNzcwNWU5NTEwYWJiNjNkMzA4NWE5ZDQ2MjFmOWRiZTMwNjM1Ng==
+    YjJjY2JmYjg3NDBmZmQ4NDBhMGM0ZWNiNDIxYzBlZjdmODQzYmQ5YQ==
   data.tar.gz: !binary |-
-    ZTdmYTg3YWUwYTExNTI0MGNjNGNhMTAxOTJkZTY0ODgyZjQyMzVhOQ==
+    OGIyMTU3ZmY5Mzg3NmIwYmJlMWFhZmViMGNhYWUxMWM5NGQ3MzMwMg==
 SHA512:
   metadata.gz: !binary |-
-    ZTE4MmE0NzZkMTRkY2E5MGE5NGMyZjJkY2FlOTE4ODNmY2UzYmY1YWQ4OWJj
-    MzQxZTJhODI4YzA2ZDg2NDZhZTBiNmEwMzRhZDcyM2Q5YTIzNzYzNTNmMTU3
-    YzlkZDRmMzhlOWE0ZWEwMDU1ZmVhMWM5ZWExMTVjMzEyZjJkOWE=
+    YjNiZjc5OTAwYjMwMWI2YzZjZjBkYTQyOGI0N2E4YTc5NjgzYjA4MDc5NGVj
+    YmFjMmIzYTQwYjQxMTIyNWQxY2NhZjNhZWJjMzY2NzcyZWE5MjcwMmM1ODll
+    ZmM1N2Q4MjJlZmZhMTdjMzAyMTA2Mjc0MjZhZWEzNTdiMmE0Nzk=
   data.tar.gz: !binary |-
-    NGM4OGYxNzg2MmFkZWI3MWRmZTZiOTliNmFhN2IzZjFkZWEwZTgyZTYxNTYx
-    ZWMyNjc3YWY0ZDdhNTVhNmRhZjJkNmVlYWZmMmIwNzM4NjM3ZTQ5YTM2M2M2
-    N2VlMWQyMGFkNzM1NzdmZDgyMWIxMGIxNTVmYzllZWY5NTU3ZTc=
+    N2YwNmFhY2RkZTNkZDdmZjA1N2E4ZjJhMDc3NTcxODk3ZmEwNDlmYjU0MDQ2
+    NzU4OTdlMTgxODcwMzMyYjIzYzQ1OTc5NjRlOWIyM2E2MGRjMTIzYTM4MDgy
+    OGFjNzMwNmUwZDNhM2JiZTExMmQzZmZmMDg1ZTIzZDc1Mjc5MzM=

data/.gitignore

@@ -19,3 +19,4 @@ tmp
 lib/.DS_Store
 lib/responsys/.DS_Store
 .rvmrc
+.idea/

data/Gemfile

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

data/README.md

@@ -1,29 +1,101 @@
-# Responsys::Api
+# ResponsysApi
 
-TODO: Write a gem description
+A gem to help you communicate to the Responsys Interact SOAP API.
 
-## Installation
+## Documentation
 
-Add this line to your application's Gemfile:
+Have a look at the [wiki](https://github.com/dandemeyere/responsys-api/wiki) to understand how it works as well as special tips specially prepared for you ! If you have any questions or if you want to report a bug please create an [issue](https://github.com/dandemeyere/responsys-api/issues).
 
-    gem 'responsys-api'
+## Installation
 
-And then execute:
+Add this line to your application"s Gemfile:
 
-    $ bundle
+    gem "responsys-api", "~> 0.0.4"
 
-Or install it yourself as:
+Or install it locally with:
 
     $ gem install responsys-api
 
 ## Usage
+### Configuration 
+
+```ruby
+# Configure ResponsysApi in your initializers (config/initializers/responsys_api.rb):
+Responsys.configure do |config|
+  config.settings = {
+    username: "your_responsys_username",
+    password: "your_responsys_password",
+    wsdl: "https://wsXXXX.responsys.net/webservices/wsdl/ResponsysWS_Level1.wsdl",
+    debug: false
+  }
+end
+```
+
+Note that the debug option is optional and is set to false by default.
+
+### Example
+```ruby
+#!/usr/bin/env ruby
+
+## Scenario : subscribe a user to a newsletter
+## Details : the user exists in the list of your users in Responsys @ "the_folder_containing_the_list/my_customers_list". He just decided to subscribe so let's update his status !
+
+# Require the gem
+require 'responsys_api'
 
-TODO: Write usage instructions here
+Responsys.configure do |config|
+  config.settings = {
+    username: "your_responsys_username",
+    password: "your_responsys_password",
+    wsdl: "https://wsXXXX.responsys.net/webservices/wsdl/ResponsysWS_Level1.wsdl"
+  }
+end
+
+# A list is an "InteractObject" according to the official API documentation
+list = Responsys::Api::Object::InteractObject.new("the_folder_containing_the_list", "my_customers_list")
+
+# The Member (or "user" for the example) record to update
+member = Responsys::Member.new('user@email.com')
+
+# Add the user to the list if he is not present.
+unless member.present_in_list?(list) 
+  puts "New user. Let's add it"
+  member.add_to_list(list)
+else
+  puts "The user is in the list"
+end
+
+# Subscribe the user if he hasn't subscribed yet
+unless member.subscribed?(list)
+  puts "Subscribing the user to the list"
+  member.subscribe(list)
+else
+  puts "The user already subscribed"
+end
+
+# Check the member has a subscribed status
+puts member.subscribed?(list) ? "#{member.email} has subscribed to #{list.object_name}" : "An error happened"
+```
+### Session
+The API client used by the gem logs in as soon as a the first method is called. The same session is used as it is valid. If you want to close the API session you can manually call the log out action :
+
+```ruby
+Responsys::Api::Client.instance.logout
+```
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some 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
+
+## To Do
+* Add thorough tests with properly mocked out API responses
+* Build out API functionality
+  * Member profile extension
+    * CRUD operations (create new key/value, update value by key, delete key/value by key)
+  * Tables
+    * CRUD operations (create new key/value, update value by key, delete key/value by key)
+  * Batch member profile updates

data/lib/responsys/api/all.rb

@@ -0,0 +1,17 @@
+require "responsys/api/folder"
+require "responsys/api/list"
+require "responsys/api/session"
+require "responsys/api/table"
+require "responsys/api/campaign"
+
+module Responsys
+  module Api
+    module All
+      include Responsys::Api::Folder
+      include Responsys::Api::List
+      include Responsys::Api::Session
+      include Responsys::Api::Table
+      include Responsys::Api::Campaign
+    end
+  end
+end

data/lib/responsys/api/campaign.rb

@@ -0,0 +1,26 @@
+require "responsys/api/object/all"
+
+module Responsys
+  module Api
+    module Campaign
+      include Responsys::Exceptions
+      
+      def trigger_message(campaign, recipients)
+        raise ParameterException, I18n.t("api.campaign.incorrect_recipients_type") unless recipients.is_a? Array
+        message = {
+          campaign: campaign.to_api,
+          recipientData: recipients.map(&:to_api) 
+        }
+        api_method(:trigger_campaign_message, message)
+      end
+
+      def check_failures(outcome, recipients)
+        if outcome.respond_to?(:each_index)
+          outcome.each_index { |i| puts "failed:\n" + recipients[i][:recipient].to_s unless outcome[i][:success] }
+        else
+          puts "failed:\n" + recipients[:recipient].to_s unless outcome[:success]
+        end
+      end
+    end
+  end
+end

data/lib/responsys/api/client.rb

@@ -0,0 +1,70 @@
+require "responsys/configuration"
+require "savon"
+require "responsys/helper"
+require "responsys/api/all"
+require "responsys/api/object/all"
+require "singleton"
+
+module Responsys
+  module Api
+    class Client
+      include Singleton
+      include Responsys::Api::All
+
+      attr_accessor :credentials, :client, :session_id, :jsession_id, :header
+
+      def initialize
+        settings = Responsys.configuration.settings
+        @credentials = {
+          username: settings[:username],
+          password: settings[:password]
+        }
+
+        if settings[:debug]
+          @client = Savon.client(wsdl: settings[:wsdl], element_form_default: :qualified, log_level: :debug, log: true, pretty_print_xml: true)
+        else
+          @client = Savon.client(wsdl: settings[:wsdl], element_form_default: :qualified)
+        end
+
+        login
+      end
+
+      def api_method(action, message = nil, response_type = :hash)
+        begin
+          response = run_with_credentials(action, message, jsession_id, header)
+
+          case response_type
+          when :result
+            Responsys::Helper.format_response_result(response, action)
+          when :hash
+            Responsys::Helper.format_response_hash(response, action)
+          end
+
+        rescue Exception => e
+          error_response = Responsys::Helper.format_response_with_errors(e)
+
+          if error_response[:error][:code] == "INVALID_SESSION_ID"
+            login
+            api_method(action, message, response_type)
+          else
+            error_response
+          end
+        end
+      end
+
+      def available_operations
+        @client.operations
+      end
+
+      private
+
+      def run(method, message)
+        @client.call(method.to_sym, message: message)
+      end
+
+      def run_with_credentials(method, message, cookie, header)
+        @client.call(method.to_sym, message: message, cookies: cookie, soap_header: header)
+      end
+    end
+  end
+end

data/lib/responsys/api/folder.rb

@@ -0,0 +1,25 @@
+module Responsys
+  module Api
+    module Folder
+      def list_folders
+        api_method(:list_folders)
+      end
+
+      def create_folder(name)
+        api_method(:create_folder, { :folderName => name })
+      end
+
+      def delete_folder(name)
+        api_method(:delete_folder, { :folderName => name })
+      end
+
+      def folder_exists?(name)
+        all = list_folders
+
+        all.select! { |curr_folder| curr_folder[:name] == name }
+
+        !all.empty?
+      end
+    end
+  end
+end

data/lib/responsys/api/list.rb

@@ -0,0 +1,39 @@
+require "responsys/api/object/all"
+
+module Responsys
+  module Api
+    module List
+      include Responsys::Api::Object
+      def retrieve_list_members(interact_object, query_column, field_list, ids_to_retrieve)
+        message = {
+          list: interact_object.to_api,
+          queryColumn: query_column.to_api,
+          fieldList: field_list,
+          idsToRetrieve: ids_to_retrieve
+        }
+
+        api_method(:retrieve_list_members, message)
+      end
+
+      def merge_list_members(interact_object, record_data, merge_rule = ListMergeRule.new)
+        message = {
+          list: interact_object.to_api,
+          recordData: record_data.to_api,
+          mergeRule: merge_rule.to_api
+        }
+
+        api_method(:merge_list_members, message)
+      end
+
+      def merge_list_members_riid(interact_object, record_data, merge_rule = ListMergeRule.new)
+        message = {
+          list: interact_object.to_api,
+          recordData: record_data.to_api,
+          mergeRule: merge_rule.to_api
+        }
+
+        api_method(:merge_list_members_riid, message)
+      end
+    end
+  end
+end

data/lib/responsys/api/object/all.rb

@@ -0,0 +1,11 @@
+require "responsys/api/object/interact_object"
+require "responsys/api/object/list_merge_rule"
+require "responsys/api/object/record"
+require "responsys/api/object/record_data"
+require "responsys/api/object/field"
+require "responsys/api/object/field_type"
+require "responsys/api/object/query_column"
+require "responsys/api/object/recipient"
+require "responsys/api/object/recipient_data"
+require "responsys/api/object/email_format"
+require "responsys/api/object/optional_data"

data/lib/responsys/api/object/email_format.rb

@@ -0,0 +1,23 @@
+module Responsys
+  module Api
+    module Object
+      class EmailFormat
+        include Responsys::Api::Object
+        attr_accessor :email_format_string
+        AVAILABLE_EMAIL_FORMAT = %w(TEXT_FORMAT HTML_FORMAT NO_FORMAT MULTIPART_FORMAT)
+
+        def initialize(email_format = "NO_FORMAT")
+          if AVAILABLE_EMAIL_FORMAT.include? email_format
+            @email_format_string = email_format
+          else
+            raise ParameterException, I18n.t("api.object.email_format.incorrect_email_format")
+          end
+        end
+
+        def to_api
+          @email_format_string
+        end
+      end
+    end
+  end
+end

data/lib/responsys/api/object/field.rb

@@ -0,0 +1,20 @@
+module Responsys
+  module Api
+    module Object
+      class Field
+        attr_accessor :field_name, :field_type, :custom, :data_extraction_key
+
+        def initialize(field_name, field_type, custom = false, data_extraction_key = false)
+          @field_name =  field_name
+          @field_type = field_type
+          @custom = custom
+          @data_extraction_key = data_extraction_key
+        end
+
+        def to_api
+          { fieldName: @field_name, fieldType: @field_type.to_api, custom: @custom, dataExtractionKey: @data_extraction_key }
+        end
+      end
+    end
+  end
+end

data/lib/responsys/api/object/field_type.rb

@@ -0,0 +1,23 @@
+module Responsys
+  module Api
+    module Object
+      class FieldType
+        include Responsys::Exceptions
+        attr_accessor :field_type_string
+        FIELD_TYPES = %w(STR500 STR4000 NUMBER TIMESTAMP INTEGER)
+
+        def initialize(field_type)
+          if FIELD_TYPES.include? field_type
+            @field_type_string = field_type
+          else
+            raise ParameterException, I18n.t("api.object.field_type.incorrect_field_type")
+          end
+        end
+
+        def to_api
+          @field_type_string
+        end
+      end
+    end
+  end
+end

data/lib/responsys/api/object/interact_object.rb

@@ -0,0 +1,18 @@
+module Responsys
+  module Api
+    module Object
+      class InteractObject
+        attr_accessor :folder_name, :object_name
+
+        def initialize(folder_name, object_name)
+          @folder_name = folder_name
+          @object_name = object_name
+        end
+
+        def to_api
+          { folderName: @folder_name, objectName: @object_name }
+        end
+      end
+    end
+  end
+end

data/lib/responsys/api/object/list_merge_rule.rb

@@ -0,0 +1,41 @@
+module Responsys
+  module Api
+    module Object
+      class ListMergeRule
+        attr_accessor :insert_on_no_match, :update_on_match, :match_column_name1, :match_column_name2, :match_column_name3, :match_operator, :optin_value, :optout_value, :html_value, :text_value, :reject_record_if_channel_empty, :default_permission_status
+
+        def initialize(options = {})
+          @insert_on_no_match = options[:insertOnNoMatch].nil? ? false : options[:insertOnNoMatch]
+          @update_on_match = options[:updateOnMatch] || "REPLACE_ALL"
+          @match_column_name1 = options[:matchColumnName1] || "EMAIL_ADDRESS_"
+          @match_column_name2 = options[:matchColumnName2] || ""
+          @match_column_name3 = options[:matchColumnName3] || ""
+          @match_operator = options[:matchOperator] || "AND"
+          @optin_value = options[:optinValue] || "I"
+          @optout_value = options[:optoutValue] || "O"
+          @html_value = options[:htmlValue] || "H"
+          @text_value = options[:textValue] || "T"
+          @reject_record_if_channel_empty = options[:rejectRecordIfChannelEmpty] || ""
+          @default_permission_status = options[:defaultPermissionStatus] || "OPTOUT"
+        end
+
+        def to_api
+          {
+            insertOnNoMatch: @insert_on_no_match,
+            updateOnMatch: @update_on_match,
+            matchColumnName1: @match_column_name1,
+            matchColumnName2: @match_column_name2,
+            matchColumnName3: @match_column_name3,
+            matchOperator: @match_operator,
+            optinValue: @optin_value,
+            optoutValue: @optout_value,
+            htmlValue: @html_value,
+            textValue: @text_value,
+            rejectRecordIfChannelEmpty: @reject_record_if_channel_empty,
+            defaultPermissionStatus: @default_permission_status
+          }
+        end
+      end
+    end
+  end
+end