intercom_export 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8bfa036eb91da48e7b33e0a4259435df6174a24a
+  data.tar.gz: defb9580a26925e535c00468a9c307d071cb0e6c
+SHA512:
+  metadata.gz: 0ab1c73df7e26588d6e19d9f71d4d628614b5e0370baadd93f062dd7de03c7bc81f4f88bfc34f6b02cb626d3c266962dec038433fdadc7f1a54653f3fea6011e
+  data.tar.gz: 3eaf29055fbab7c1cdb5f03dac77041afd388615d1b776d9e0e617fd44d9b2f81ed1c4515dea5c62ca92d6861721ee2bb9f6d928a6988c66bd724283147cc5a0

data/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2016 Ignition Works Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+Intercom Export
+===============
+
+System to help export Intercom.io conversations into Zendesk tickets. The codebase is designed to be adaptable
+for importing into other systems or even exporting from things other than Intercom.
+
+Usage
+-----
+
+```
+$ intercom_export --intercom-app-id <APP ID> --intercom-api-key <APP KEY> \
+                  --zendesk-address <DOMAIN>.zendesk.com --zendesk-username <USERNAME> --zendesk-token <TOKEN>
+```
+
+Design
+------
+
+The `coordinator` is the heart of the import. This breaks the problem down into several discrete stages.
+
+ 1. `source` - This is simple an enumerable, currently this is an enumerable of all Intercom conversations
+ 2. `splitter` - This takes an item from the source and splits it into several `parts` that make syncying
+    easier. For instance an Intecom conversation will be split into all of the users involved in the
+    conversation, and the conversation itself with the users replaced by references.
+ 3. `finder` - This takes a part (something in the land of Intercom), and tries to find it's equivalent in
+    Zendesk
+ 4. `differ` - This compares the Intercom part, with the search result from Zendesk and then creates commands.
+ 5. `executor` - This executes each command, replacing references to Intercom items, with ids from Zendesk.
+
+The idea of breaking it into these components is to allow other front-ends (Intercom), to be slotted in by
+only adding a few classes. It should also be possible to slot in other back-ends (Zendesk) with a small amount
+of modification.
+
+Tests
+-----
+
+```
+$ rspec
+```
+
+Status
+------
+
+This has worked for us importing around 5000 tickets from Intercom to Zendesk. Performance is slow due to the
+number of queries required.

data/bin/intercom_export

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'intercom_export/cli'
+
+IntercomExport::Cli.new($PROGRAM_NAME, ARGV).run

data/lib/intercom_export/cli.rb

@@ -0,0 +1,126 @@
+require 'optparse'
+require 'intercom'
+require 'zendesk_api'
+
+require 'intercom_export/coordinator'
+require 'intercom_export/differ/intercom_zendesk'
+require 'intercom_export/executor/zendesk'
+require 'intercom_export/executor/dry_run'
+require 'intercom_export/finder/intercom_zendesk'
+require 'intercom_export/source/intercom_conversations'
+require 'intercom_export/splitter/intercom'
+require 'intercom_export/listener/std'
+
+module IntercomExport
+  class Cli
+    def initialize(
+      program_name,
+      argv,
+      coordinator_class: IntercomExport::Coordinator,
+      stdout: STDOUT,
+      stderr: STDERR
+    )
+      @program_name = program_name
+      @argv = argv
+      @coordinator_class = coordinator_class
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run
+      coordinator_class.new(
+        source: IntercomExport::Source::IntercomConversations.new(intercom_client),
+        splitter: IntercomExport::Splitter::Intercom.new(intercom_client),
+        finder: IntercomExport::Finder::IntercomZendesk.new(zendesk_client),
+        differ: IntercomExport::Differ::IntercomZendesk.new,
+        executor: executor
+      ).run
+    rescue KeyError
+      stderr.puts options_parser
+    end
+
+    private
+
+    attr_reader :coordinator_class, :argv, :program_name, :stdout, :stderr
+
+    def listener
+      @listener ||= IntercomExport::Listener::Std.new(stdout: stdout, stderr: stderr)
+    end
+
+    def executor
+      if options.fetch(:dry_run, false)
+        IntercomExport::Executor::DryRun.new(listener)
+      else
+        IntercomExport::Executor::Zendesk.new(zendesk_client, listener)
+      end
+    end
+
+    def zendesk_client
+      @zendesk_client ||= ZendeskAPI::Client.new do |c|
+        c.url = "https://#{options.fetch(:zendesk_address)}/api/v2"
+        c.username = options.fetch(:zendesk_username)
+        c.token = options.fetch(:zendesk_token)
+      end
+    end
+
+    def intercom_client
+      @intercom_client ||= Intercom::Client.new(
+        api_key: options.fetch(:intercom_api_key),
+        app_id: options.fetch(:intercom_app_id)
+      )
+    end
+
+    def options
+      # If a method has side-effects but no one can see it - is it really a query?
+      @options ||= begin
+        @opts = {}
+        options_parser.parse(argv)
+        @opts
+      end
+    end
+
+    def options_parser
+      @options_parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: #{program_name} [options]"
+
+        options_intercom(opts)
+        options_zendesk(opts)
+        options_generic(opts)
+      end
+    end
+
+    def options_generic(opts)
+      opts.on('-d', '--dry-run') do
+        @opts[:dry_run] = true
+      end
+
+      opts.on('-h', '--help') do
+        stderr.puts opts
+      end
+    end
+
+    def options_intercom(opts)
+      opts.on('--intercom-app-id APP_ID', 'Intercom App Id') do |v|
+        @opts[:intercom_app_id] = v
+      end
+
+      opts.on('--intercom-api-key API_KEY', 'Intercom API Key') do |v|
+        @opts[:intercom_api_key] = v
+      end
+    end
+
+    def options_zendesk(opts)
+      opts.on('--zendesk-address ADDRESS', 'Zendesk address e.g. example.zendesk.com') do |v|
+        @opts[:zendesk_address] = v
+      end
+
+      opts.on('--zendesk-username USERNAME', 'Zendesk username e.g. admin@example.com') do |v|
+        @opts[:zendesk_username] = v
+      end
+
+      opts.on('--zendesk-token TOKEN', 'Zendesk token') do |v|
+        @opts[:zendesk_token] = v
+      end
+    end
+  end
+end

data/lib/intercom_export/coordinator.rb

@@ -0,0 +1,47 @@
+module IntercomExport
+  class Coordinator
+
+    module EnumeratorLazyUniqParts
+      refine Enumerator::Lazy do
+        require 'set'
+        def uniq
+          set = Set.new
+          select { |part|
+            val = "#{part.class.to_s}-#{part.id}"
+            !set.include?(val).tap { |exists| set << val unless exists }
+          }
+        end
+      end
+    end
+
+    using EnumeratorLazyUniqParts
+
+    def initialize(source:, splitter:, finder:, differ:, executor:)
+      @source = source
+      @splitter = splitter
+      @finder = finder
+      @differ = differ
+      @executor = executor
+    end
+
+    def run
+      source.lazy.flat_map { |source|
+        splitter.split(source)
+      }.uniq.map { |source_object|
+        [source_object, finder.find(source_object)]
+      }.map { |source_object, remote_object|
+        differ.diff(source_object, remote_object)
+      }.each { |commands|
+        executor.call(commands)
+      }
+    end
+
+    private
+
+    attr_reader :source, :finder, :splitter, :differ, :executor
+  end
+end
+
+
+
+

data/lib/intercom_export/differ/intercom_zendesk.rb

@@ -0,0 +1,109 @@
+require 'intercom_export/model/intercom_admin'
+require 'intercom_export/model/intercom_user'
+require 'intercom_export/model/intercom_conversation'
+
+require 'nokogiri'
+
+module IntercomExport
+  module Differ
+    class IntercomZendesk
+      def diff(intercom_source, zendesk_destination)
+        case intercom_source
+        when Model::IntercomUser, Model::IntercomAdmin
+          diff_user(intercom_source, zendesk_destination)
+        when Model::IntercomConversation
+          diff_ticket(intercom_source, zendesk_destination)
+        end
+      end
+
+      private
+
+      def diff_user(intercom_user, zendesk_user)
+        if zendesk_user
+          [reference(intercom_user, zendesk_user)]
+        else
+          [import_user(intercom_user)]
+        end
+      end
+
+      def diff_ticket(intercom_conversation, zendesk_ticket)
+        if zendesk_ticket
+          []
+        else
+          [import_ticket(intercom_conversation)]
+        end
+      end
+
+      def reference(intercom_source, zendesk_destination)
+        { name: :reference, details: zendesk_destination.id, reference: intercom_source.reference }
+      end
+
+      def import_user(intercom_user)
+        {
+          name: :import_user,
+          details: {
+            external_id: intercom_user.reference.value,
+            name: intercom_user.name || intercom_user.email,
+            email: intercom_user.email
+          },
+          reference: intercom_user.reference
+        }
+      end
+
+      def import_ticket(intercom_conversation)
+        {
+          name: :import_ticket,
+          details: {
+            external_id: intercom_conversation.reference.value,
+            tags: intercom_conversation.tags,
+            status: intercom_conversation.open ? 'pending' : 'solved',
+            requester_id: intercom_conversation.user,
+            assignee_id: intercom_conversation.assignee,
+            subject: strip_html(intercom_conversation.conversation_message.fetch(:subject)),
+            comments: [
+              author_id: intercom_conversation.user,
+              html_body: intercom_conversation.conversation_message.fetch(:body),
+              created_at: time(intercom_conversation.created_at)
+            ] + intercom_conversation.conversation_parts.map { |part|
+              {
+                author_id: part.fetch(:author),
+                value: html_to_ascii(part.fetch(:body)),
+                public: part.fetch(:part_type) != 'note',
+                created_at: time(part.fetch(:created_at))
+              }
+            },
+            created_at: time(intercom_conversation.created_at),
+            updated_at: time(intercom_conversation.updated_at)
+          }
+        }
+      end
+
+      def time(posix)
+        Time.at(posix).strftime('%Y-%m-%dT%H:%M:%SZ')
+      end
+
+      def strip_html(html_string)
+        Nokogiri::HTML(html_string).text
+      end
+
+      def html_to_ascii(html_string)
+        node = Nokogiri::HTML(html_string)
+        blocks = %w[p div address]                          # els to put newlines after
+        swaps  = { 'br' => "\n", 'hr' => "\n#{'-'*70}\n" }  # content to swap out
+        dup = node.dup                                      # don't munge the original
+
+        # Get rid of superfluous whitespace in the source
+        dup.xpath('.//text()').each { |t| t.content = t.text.gsub(/\s+/, ' ') }
+
+        # Swap out the swaps
+        dup.css(swaps.keys.join(',')).each { |n| n.replace(swaps[n.name]) }
+
+        # Slap a couple newlines after each block level element
+        dup.css(blocks.join(',')).each { |n| n.after("\n\n") }
+
+        # Return the modified text content
+        dup.text.strip
+      end
+    end
+  end
+end

data/lib/intercom_export/executor/dry_run.rb

@@ -0,0 +1,19 @@
+module IntercomExport
+  module Executor
+    class DryRun
+      def initialize(listener)
+        @listener = listener
+      end
+
+      def call(commands)
+        commands.each do |c|
+          listener.executing c
+        end
+      end
+
+      private
+
+      attr_reader :listener
+    end
+  end
+end

data/lib/intercom_export/executor/zendesk.rb

@@ -0,0 +1,70 @@
+module IntercomExport
+  module Executor
+    class Zendesk
+      ReferenceResult = Struct.new(:id)
+
+      def initialize(client, listener=nil)
+        @client = client
+        @listener = listener
+        @references = {}
+      end
+
+      def call(commands)
+        commands.each do |command|
+          executing(command)
+          details = resolve_reference(command.fetch(:details))
+          result = case command.fetch(:name)
+          when :reference
+            ReferenceResult.new(details)
+          when :import_user
+            import_user(details)
+          when :import_ticket
+            import_ticket(details)
+          end
+          save_reference(command[:reference].value, result.id) if command.fetch(:reference, nil)
+        end
+      end
+
+      private
+
+      attr_reader :client, :references, :listener
+
+      def import_user(details)
+        client.users.create!(details)
+      end
+
+      def import_ticket(details)
+        client.tickets.import!(details)
+      end
+
+      def save_reference(local_id, remote_id)
+        references[local_id] = remote_id
+      end
+
+      def deep_resolve_references(details)
+        details.each do |key, value|
+          resolved_value = resolve_reference(value)
+          details[key] = resolved_value unless resolved_value === value
+        end
+      end
+
+      def executing(command)
+        return unless listener
+        listener.executing(command)
+      end
+
+      def resolve_reference(value)
+        case value
+        when Hash
+          deep_resolve_references(value)
+        when Array
+          value.map { |v| resolve_reference(v) }
+        when Reference
+          references.fetch(value.value)
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/intercom_export/finder/intercom_zendesk.rb

@@ -0,0 +1,42 @@
+require 'intercom_export/model/intercom_admin'
+require 'intercom_export/model/intercom_user'
+require 'intercom_export/model/intercom_conversation'
+require 'intercom_export/model/zendesk_ticket'
+require 'intercom_export/model/zendesk_user'
+
+module IntercomExport
+  module Finder
+    class IntercomZendesk
+      def initialize(zendesk_client)
+        @zendesk_client = zendesk_client
+      end
+
+      def find(intercom_source)
+        case intercom_source
+        when IntercomExport::Model::IntercomUser, IntercomExport::Model::IntercomAdmin
+          lookup_zendesk_user(intercom_source)
+        when IntercomExport::Model::IntercomConversation
+          lookup_zendesk_ticket(intercom_source)
+        end
+      end
+
+      private
+
+      attr_reader :zendesk_client
+
+      def lookup_zendesk_user(intercom_user)
+        value = zendesk_client.users.search(query: "email:#{intercom_user.email}").first
+        return unless value
+        IntercomExport::Model::ZendeskUser.new(value.to_hash)
+      end
+
+      def lookup_zendesk_ticket(intercom_ticket)
+        value = zendesk_client.search(
+          query: "type:ticket external_id:#{intercom_ticket.reference.value}"
+        ).first
+        return unless value
+        IntercomExport::Model::ZendeskTicket.new(value.to_hash)
+      end
+    end
+  end
+end