markety 1.4.3 → 2.0

data/lib/markety/command.rb

@@ -0,0 +1,11 @@
+require 'markety/command/get_lead'
+require 'markety/command/sync_lead'
+require 'markety/command/list_operation'
+
+module Markety
+  # All Command submodules are included in the Markety::Client class.
+  # They are implemented in separate modules only for maintainability
+  # (specifically, to keep Markety::Client from becoming huge).
+  module Command
+  end
+end

data/lib/markety/command/get_lead.rb

@@ -0,0 +1,27 @@
+module Markety
+  module Command
+
+    # GetLead commands return Response::GetLeadResponse objects
+    module GetLead
+
+      # IDs are unique per lead, so the response can only contain one lead.
+      def get_lead_by_idnum(idnum)
+        get_lead(LeadKey.new(LeadKeyType::IDNUM, idnum))
+      end
+
+      # Multiple leads can share an email address,
+      # so this may result in more than one lead in the response.
+      def get_leads_by_email(email)
+        get_lead(LeadKey.new(LeadKeyType::EMAIL, email))
+      end
+
+
+    private
+
+      def get_lead(lead_key)
+        send_request(:get_lead, {"leadKey" => lead_key.to_hash})
+      end
+
+    end
+  end
+end

data/lib/markety/command/list_operation.rb

@@ -0,0 +1,68 @@
+module Markety
+  module Command
+    # ListOperation commands return Response::ListOperationResponse objects.
+    #
+    # In all these functions:
+    # * An exception will be thrown if you pass in a Lead and it doesn't have an idnum
+    # * Allowed options:
+    #   [strict]  From {Marketo's docs}[http://developers.marketo.com/documentation/soap/listoperation/]: <em>Strict mode will fail for the entire operation if any subset of the call fails.  Non-strict mode will complete everything it can and return errors for anything that failed.</em>
+    #
+    # All ListOp failures look similar, and all successes look similar.
+    module ListOperation
+
+      # note: If you add something that's already in the list, ListOperationResponse::list_operation_success? will be +true+
+      def add_to_list(list_name, lead_or_idnum, options={})
+        list_operation(list_name, "ADDTOLIST", lead_or_idnum, options)
+      end
+
+      # note: If you remove something that's not in the list, ListOperationResponse::list_operation_success? will be +false+
+      def remove_from_list(list_name, lead_or_idnum, options={})
+        list_operation(list_name, "REMOVEFROMLIST", lead_or_idnum, options)
+      end
+
+      # ListOperationResponse::list_operation_success? is the result of this query
+      def is_member_of_list(list_name, lead_or_idnum, options={})
+        list_operation(list_name, "ISMEMBEROFLIST", lead_or_idnum, options)
+      end
+
+    private
+
+      ADD_TO       = 'ADDTOLIST'        # :nodoc:
+      REMOVE_FROM  = 'REMOVEFROMLIST'   # :nodoc:
+      IS_MEMBER_OF = 'ISMEMBEROFLIST'   # :nodoc:
+      private_constant :ADD_TO
+      private_constant :REMOVE_FROM
+      private_constant :IS_MEMBER_OF
+
+      ALLOWED_OPS = [ADD_TO,REMOVE_FROM,IS_MEMBER_OF]   # :nodoc:
+      private_constant :ALLOWED_OPS
+
+      def list_operation(list_name, list_operation_type, lead_or_idnum, options)
+        raise "Unknown list operation type" unless ALLOWED_OPS.include?(list_operation_type)
+        idnum = lead_or_idnum
+        if lead_or_idnum.is_a? Markety::Lead
+          raise "Lead has no idnum, which this command needs" unless lead_or_idnum.idnum
+          idnum = lead_or_idnum.idnum
+        end
+
+        strict = options.has_key?(:strict) ? !!options[:strict] : true
+
+        strict = !!options[:strict]
+        send_request(:list_operation, {
+          list_operation: list_operation_type,
+          strict: strict,
+          list_key: {
+            key_type: 'MKTOLISTNAME',
+            key_value: list_name
+          },
+          list_member_list: {
+            lead_key: [{
+              key_type: 'IDNUM',
+              key_value: idnum
+            }]
+          }
+        })
+      end
+    end
+  end
+end

data/lib/markety/command/sync_lead.rb

@@ -0,0 +1,55 @@
+module Markety
+  module Command
+    # SyncLead commands return Response::SyncResponse objects
+    module SyncLead
+
+      # Create a new lead or update an existing lead in Marketo.
+      # * +lead+ - the lead to create or sync
+      # * +sync_method+ - a SyncMethod enum value
+      def sync_lead(lead, sync_method)
+        request_hash = create_sync_lead_request_hash(lead,sync_method)
+        send_request(:sync_lead, request_hash)
+      end
+
+    private
+  
+      def create_sync_lead_request_hash(lead, sync_method)
+        raise "missing sync method" unless sync_method
+  
+        case sync_method
+          when SyncMethod::MARKETO_ID
+            raise "lead has no idnum" unless lead.idnum
+          when SyncMethod::FOREIGN_ID
+            raise "lead has no foreign_sys_person_id" unless lead.foreign_sys_person_id
+          when SyncMethod::EMAIL
+            raise "lead has no email" unless lead.email
+          else
+            raise "unrecognized Markety::SyncMethod '#{sync_method}'"
+        end
+  
+        # note from gbirchmeier:
+        #   A Marketo support guy told me the fields must come in a very particular order,
+        #     thus why this flow is a little janky.
+        #   I've since come to doubt this advice (the Marketo support guys do not appear to
+        #     actually be very technical), but I'm not going to fix something that's not broke.
+
+        request_hash = {
+          lead_record: { },
+          return_lead: true,
+        }
+  
+        # id fields must come first in lead_record
+        request_hash[:lead_record][:id]=lead.idnum if sync_method==SyncMethod::MARKETO_ID
+        use_foreign_id = lead.foreign_sys_person_id && [SyncMethod::MARKETO_ID,SyncMethod::FOREIGN_ID].include?(sync_method)
+        request_hash[:lead_record][:foreignSysPersonId]=lead.foreign_sys_person_id if use_foreign_id
+        request_hash[:lead_record]["Email"]=lead.email if lead.email
+  
+        # now lead attributes (which must be ordered name/type/value) (type is optional, but must precede value if present)
+        request_hash[:lead_record][:lead_attribute_list] = { attribute: lead.send(:attributes_soap_array) }
+  
+        request_hash
+      end
+
+    end
+  end
+end

data/lib/markety/enums.rb

@@ -1,21 +1,23 @@
 module Markety
-  # Types of operations you can do on a marketo list
-  module ListOperationType
-    ADD_TO       = 'ADDTOLIST'
-    REMOVE_FROM  = 'REMOVEFROMLIST'
-    IS_MEMBER_OF = 'ISMEMBEROFLIST'
-  end
-
-  # Types of keys that can be used to look up a lead
+  # Types of keys that can be used to look up a lead.
+  # (Other key types exist, but Markety only supports these at this time.)
   module LeadKeyType
     IDNUM           = "IDNUM"
-    COOKIE          = "COOKIE"
     EMAIL           = "EMAIL"
-    LEADOWNEREMAIL  = "LEADOWNEREMAIL"
-    SFDCACCOUNTID   = "SFDCACCOUNTID"
-    SFDCCONTACTID   = "SFDCCONTACTID"
-    SFDCLEADID      = "SFDCLEADID"
-    SFDCLEADOWNERID = "SFDCLEADOWNERID"
-    SFDCOPPTYID     = "SFDCOPPTYID"
+
+#    COOKIE          = "COOKIE"
+#    LEADOWNEREMAIL  = "LEADOWNEREMAIL"
+#    SFDCACCOUNTID   = "SFDCACCOUNTID"
+#    SFDCCONTACTID   = "SFDCCONTACTID"
+#    SFDCLEADID      = "SFDCLEADID"
+#    SFDCLEADOWNERID = "SFDCLEADOWNERID"
+#    SFDCOPPTYID     = "SFDCOPPTYID"
+  end
+
+  # a parameter type to Markety::Command::SyncLead
+  module SyncMethod
+    MARKETO_ID = "MARKETO_ID"
+    FOREIGN_ID = "FOREIGN_ID"
+    EMAIL = "EMAIL"
   end
-end
+end

data/lib/markety/lead.rb

@@ -0,0 +1,69 @@
+module Markety
+  # Represents a record of the data known about a lead within Marketo
+  class Lead
+    attr_reader :types, :idnum, :attributes
+    attr_accessor :foreign_sys_person_id, :email
+
+    def initialize(email:nil, idnum:nil, foreign_sys_person_id:nil)
+      @idnum      = idnum
+      @foreign_sys_person_id = foreign_sys_person_id
+      @email = email
+      @attributes = {}
+      @types      = {}
+    end
+
+    def ==(other)
+      @attributes==other.send(:attributes) &&
+      @idnum==other.idnum &&
+      @email==other.email &&
+      @foreign_sys_person_id==other.foreign_sys_person_id
+    end
+
+    # hydrates an instance from a savon hash returned from the marketo API
+    def self.from_hash(savon_hash)
+      lead = Lead.new(email: savon_hash[:email], idnum:savon_hash[:id].to_i)
+      
+      unless savon_hash[:lead_attribute_list].nil?
+        if savon_hash[:lead_attribute_list][:attribute].kind_of? Hash
+          attributes = [savon_hash[:lead_attribute_list][:attribute]]
+        else
+          attributes = savon_hash[:lead_attribute_list][:attribute]
+        end
+        
+        attributes.each do |attribute|
+          lead.set_attribute(attribute[:attr_name], attribute[:attr_value], attribute[:attr_type])
+        end
+      end
+      
+      lead
+    end
+
+
+    # update the value of the named attribute
+    def set_attribute(name, value, type = "string")
+      @attributes[name] = value
+      @types[name] = type
+    end
+
+    # get the value for the named attribute
+    def get_attribute(name)
+      @attributes[name]
+    end
+
+    # get the type of the named attribute
+    def get_attribute_type(name)
+      @types[name]
+    end
+
+
+  private
+    def attributes_soap_array()
+      arr = []
+      @attributes.each_pair do |name,value|
+        arr << {attr_name: name, attr_type: self.get_attribute_type(name), attr_value: value }
+      end
+      arr
+    end
+
+  end
+end

data/lib/markety/lead_key.rb

@@ -1,14 +1,15 @@
 module Markety
   # Encapsulates a key used to look up or describe a specific marketo lead.
+  # Markety users should not use this class directly.
   class LeadKey
-    # - *key_type* the type of key to use see LeadKeyType
-    # - *key_value* normally a string value for the given type
+    # - *key_type* - value of LeadKeyType enum; the type of key to use see LeadKeyType
+    # - *key_value* - a string value for the given type
     def initialize(key_type, key_value)
       @key_type = key_type
       @key_value = key_value
     end
 
-    # get the key type
+    # get the key type (a LeadKeyType enum value)
     def key_type
       @key_type
     end
@@ -26,4 +27,4 @@ module Markety
       }
     end
   end
-end
+end

data/lib/markety/response.rb

@@ -0,0 +1,15 @@
+require 'markety/response/response_factory'
+
+require 'markety/response/generic_response'
+require 'markety/response/get_lead_response'
+require 'markety/response/sync_lead_response'
+require 'markety/response/list_operation_response'
+
+
+module Markety
+  # Each Command returns a corresponding Response.
+  # All Response classes are derived from GenericResponse,
+  # which contains some common accessor methods.
+  module Response
+  end
+end

data/lib/markety/response/generic_response.rb

@@ -0,0 +1,45 @@
+module Markety
+  module Response
+
+    # Parent class for all response types.
+    #
+    # SOAP requests sent by Markety result in either
+    # a <tt>Savon::Response</tt> or a <tt>Savon::SOAPFault</tt>.
+    # This class hides those boring details from you,
+    # unless you want to use its methods to see them.
+    class GenericResponse
+      #if the response is a <tt>Savon::SOAPFault</tt>, this is its error message
+      attr_reader :error_message
+
+      # * +cmd_type+ - a symbol
+      # * +response+ - a <tt>Savon::Response</tt> or a <tt>Savon::SOAPFault</tt>
+      def initialize(cmd_type,response)
+        @response = response
+        @success = response.is_a? Savon::Response
+        @error_message = @success ? nil : response.to_s
+      end
+
+      # True if Marketo's response indicates that the SOAP request
+      # was successful.
+      #
+      # *Note:* This is not the same as the a result from
+      # a Marketo command itself!  To see the command's result,
+      # consult the command-specific Response class.
+      def success?
+        @success
+      end
+
+      # Return the xml from the underlying <tt>Savon::Response</tt> or
+      # <tt>Savon::SOAPFault</tt>
+      def to_xml
+        @success ? @response.to_xml : @response.http.raw_body
+      end
+
+      # The underlying <tt>Savon::Response</tt> or
+      # <tt>Savon::SOAPFault</tt>'s content as a hash
+      def to_hash
+        @response.to_hash
+      end
+    end
+  end
+end

data/lib/markety/response/get_lead_response.rb

@@ -0,0 +1,35 @@
+require 'markety/lead'
+require 'markety/response/generic_response'
+
+module Markety
+  module Response
+    # Response class for Command::GetLead calls.
+    class GetLeadResponse < GenericResponse
+      # Array of leads returned by the GetLead command
+      attr_reader :leads
+
+      def initialize(response)
+        super(:get_lead_response,response)
+        h = self.to_hash
+        @leads = []
+
+        if self.success?
+          count = h[:success_get_lead][:result][:count].to_i
+          lead_hashes = h[:success_get_lead][:result][:lead_record_list][:lead_record]
+          lead_hashes = [lead_hashes] if count==1
+          lead_hashes.each {|leadhash| @leads << ::Markety::Lead.from_hash(leadhash) }
+        else
+          # overwrite super's crap error message with useful one
+          @error_message = h[:fault][:detail][:service_exception][:message]
+        end
+      end
+
+      # Convenience shortcut to get first element of #leads (or nil if none).
+      # Appropriate for responses to Command::GetLead#get_lead_by_idnum, which cannot
+      # result in more than one lead.
+      def lead
+        @leads.first
+      end
+    end
+  end
+end

data/lib/markety/response/list_operation_response.rb

@@ -0,0 +1,30 @@
+require 'markety/response/generic_response'
+
+module Markety
+  module Response
+    # Response class for Command::ListOperation calls
+    class ListOperationResponse < GenericResponse
+
+      def initialize(response)
+        super(:list_operation_response,response)
+        @list_operation_success = false
+
+        if self.success?
+          h = self.to_hash
+          @list_operation_success = h[:success_list_operation][:result][:success]
+        end
+      end
+
+      # Whether the operation was successful.
+      #
+      # *Note:* this is not the same as parent's success? method.
+      # For list operations, success? almost always true
+      # (because Marketo accepted the request and gave you a response).
+      def list_operation_success?
+        @list_operation_success
+      end
+      alias list_op_success? list_operation_success?
+      alias lop_success? list_operation_success?
+    end
+  end
+end

data/lib/markety/response/response_factory.rb

@@ -0,0 +1,27 @@
+require 'markety/response/generic_response'
+require 'markety/response/get_lead_response'
+require 'markety/response/sync_lead_response'
+require 'markety/response/list_operation_response'
+
+module Markety
+  module Response
+    # Factory that creates the appropriate Response object depending on the command type
+    class ResponseFactory
+
+      # Create the appropriate Response object depending on the command type
+      def self.create_response(cmd_type,savon_response)
+        case cmd_type
+          when :get_lead
+            GetLeadResponse.new(savon_response)
+          when :sync_lead
+            SyncLeadResponse.new(savon_response)
+          when :list_operation
+            ListOperationResponse.new(savon_response)
+          else
+            GenericResponse.new(cmd_type,savon_response)
+        end
+      end
+
+    end
+  end
+end