highrise_assist 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,113 @@
+# Highrise Assist
+
+highrise_assist is command line tool for 37signals' highrise.
+
+## Description
+
+If you are using http://highrisehq.com/, you defiantly can notice that there are some processes in your company, that doesn't feet to the functionality implemented by 37signals' team. Fortunately they have quite strong API, that can be used for custom purposes. In our company we have bunch of such customizations, that we have decided to group in to the gem and deliver to the community. An the first tool is companies and contacts export by tag (read more below). So highrise_assist is a command line set of tools, which let you do custom operations with your data in highrise. 
+
+## Installation
+
+    $ gem install highrise_assist
+
+## Usage
+
+    Usage: ./bin/highrise_assist COMMAND [options]
+
+    Commands:
+      * export - export next highrise items:
+        * cases
+        * deals
+        * people
+        * companies
+        * emails
+        * notes
+        * comments
+        * attachments
+
+    Common options:
+            --domain DOMAIN              highrise subdomain or full domain name
+            --token TOKEN                highrise API authentication token
+
+    Export options:
+            --tag TAG                    filter items with given tag name
+            --directory DIRECTORY        working directory
+            --format FORMAT              data format (yaml,xml)
+            --skip-attachments           don't download attachments
+            --skip-cases                 don't export cases
+            --skip-deals                 don't export deals
+            --skip-notes                 don't export notes
+            --skip-emails                don't export emails
+            --skip-comments              don't export comments
+
+    Misc options:
+        -h, --help                       Show this message
+        -v, --version                    Show version
+
+## Export Command
+
+### Description
+
+If you are the using highrise for sales, human resources or some other activities, one day you will want to export data from the system. Here is the original article http://bit.ly/sTQr1W, which is describing the process. It's quite easy and works fine, but with highrise_assistexport you can do much better. This tool introduce you possibility to export companies and contacts with all the hierarchy of data including emails, notes, comments, cases, deals and even attachments (with web console you just don't have such  possibility) in xml or yaml formats. It is possible to mark exact business objects with the tag and then just export them.
+
+#### The use case 1:
+
+As user of higrise
+I want to archive old contacts and companies 
+So that my list will be clean
+
+Original help request: http://bit.ly/tIDlwk
+What 37signals' team recommends is: "Have you considered adding a tag to those contacts called "archived"?"
+With highrise_assistexport you can easily export all the data tagged as "archived", and than just remove data from the system.
+
+#### The use case2:
+
+As user of higrise
+I want to export all my data including attachments
+So that I can move data to the other management systems
+
+With highrise_assistexport you can easily do this operation.
+
+## Keep your higrise always clean!
+
+### Synopsis
+
+    $ highrise_assist export OPTIONS
+
+### Example
+
+    $ highrise_assist export \
+      --domain MYSUBDOMAIN \
+      --token 11111111111111111111111111111111 \
+      --directory highrise_data \
+      --tag old-clients \
+      --format xml \
+      --skip-attachments
+
+Export result:
+
+    $ tree --dirsfirst
+    .
+    ├── cases
+    │   ├── case-573785-test-case
+    │   │   ├── attachments
+    │   │   │   └── 22039573-20111111-p7km4bk33ugutcrrb5mxxw7fjj.jpeg
+    │   │   ├── case-573785-test-case.xml
+    │   │   └── note-78169727-test.xml
+    │   └── case-573786-what-is-highrise
+    │       ├── attachments
+    │       └── case-573786-what-is-highrise.xml
+    ├── deals
+    │   └── deal-1471928-test-deal
+    │       ├── attachments
+    │       ├── deal-1471928-test-deal.xml
+    │       └── note-78499917.xml
+    └── persons
+        └── person-92632832-test-test
+            ├── attachments
+            ├── cases
+            │   └── case-573785-test-case -> ../../../cases/case-573785-test-case
+            ├── deals
+            │   └── deal-1471928-test-deal -> ../../../deals/deal-1471928-test-deal
+            └── person-92632832-test-test.xml
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/highrise_assist

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "highrise_assist"
+
+HighriseAssist::Runner.run(ARGV)

data/highrise_assist.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "highrise_assist/version"
+
+Gem::Specification.new do |s|
+  s.name        = "highrise_assist"
+  s.version     = HighriseAssist::VERSION
+  s.authors     = ["Andriy Yanko"]
+  s.email       = ["andriy.yanko@gmail.com"]
+  s.homepage    = "https://github.com/railsware/highrise_assist"
+  s.summary     = %q{Assist for 37signals' highrise}
+  s.description = %q{Assist for 37signals' highrise}
+
+  s.rubyforge_project = "highrise_assist"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "highrise", "~>3.0.0"
+  s.add_runtime_dependency "net-http-persistent", "~>2.3"
+end

data/lib/highrise_assist/command/base.rb

@@ -0,0 +1,56 @@
+require "fileutils"
+
+module HighriseAssist
+  module Command
+    class Base
+      class << self
+        def inherited(klass)
+          Command.names.push klass.name.split("::").last.underscore
+          super(klass)
+        end
+      end
+
+      def initialize(options)
+        @options = options.dup
+        authenticate
+      end
+
+      attr_reader :options
+
+      def run
+        raise NotImplementedError, "'run' is not implemented by #{self.class.name}"
+      end
+
+      protected
+
+      def authenticate
+        require_option!(:domain, :token)
+
+        Highrise::Base.site = "https://" + options[:domain]
+        Highrise::Base.user = options[:token]
+      end
+
+      def require_option!(*names)
+        names.each do |name|
+          options[name].blank? and abort "#{name} option required"
+        end
+      end
+
+      def log(message)
+        puts message
+      end
+
+      def file_transfer
+        @file_transfer ||= FileTransfer.new(options)
+      end
+
+      def download_file(*args)
+        file_transfer.download(*args)
+      end
+
+      def upload_file(*args)
+        file_transfer.upload(*args)
+      end
+    end
+  end
+end

data/lib/highrise_assist/command/export.rb

@@ -0,0 +1,231 @@
+module HighriseAssist
+  module Command
+    class Export < Base
+
+      FORMATS = %w(yaml xml)
+
+      def initialize(*)
+        super
+
+        require_option!(:directory)
+        @root_dir = File.expand_path(options[:directory])
+
+        @format = options[:format] || FORMATS.first
+        FORMATS.include?(@format) or abort "Unsupported format: #{@format}"
+
+        @format_method = "to_#{@format}".to_sym
+
+        @tags = []
+
+        @parties = {}
+      end
+
+      attr_reader :root_dir, :format, :format_method
+
+      def run
+        authenticate
+
+        log "* Fetching data ..."
+
+        fetch_tags if options[:tag]
+
+        %w(Person Company).each do |type|
+          collection = fetch_collection(type)
+          store_collection(collection)
+          @parties[type] = collection
+        end
+
+        %w(Kase Deal).each do |type|
+          next if options[:skip_items].include?(type)
+          collection = fetch_collection(type)
+          filter_casedeal_collection!(collection)
+          store_collection(collection)
+          symlink_casedeal_collection(collection)
+        end
+
+        log "Done."
+      end
+
+      protected
+
+      def fetch_tags
+        log "* Fetching tags ..."
+        @tags = Highrise::Tag.find(:all).select { |t| t.name == options[:tag] }
+        @tags.empty? and abort "Unknown tag #{options[:tag]}"
+      end
+
+      def fetch_collection(type)
+        klass = Highrise.const_get(type)
+        if @tags.empty?
+          collection = klass.find(:all)
+        else
+          collection = []
+          @tags.each do |tag|
+            collection += klass.find(:all, :params => { :tag_id => tag.id } )
+          end
+          collection.uniq!
+        end
+        log ""
+        log "# #{type}: Found #{collection.size} items"
+        collection
+      end
+
+      # Person, Company, Kase, Deal
+      def store_collection(collection)
+        return if collection.empty?
+        base_dir = File.join(root_dir, item_dirname(collection.first))
+        FileUtils.mkdir_p(base_dir)
+
+        size = collection.size
+        collection.each_with_index do |item, index|
+          log ""
+          log("= #{index+1}of#{size}:")
+
+          dir = File.join(base_dir, item_filename(item))
+          FileUtils.mkdir_p(dir)
+
+          store_item(item, dir, "  * ")
+          store_item_collection(item, "Note",  :notes, dir) unless options[:skip_items].include?("Note")
+          store_item_collection(item, "Email", :emails, dir) unless options[:skip_items].include?("Email")
+        end
+      end
+
+      # Note, Email,
+      # Note Attachments, Email Attachments, 
+      # Note Comments, Email Comments,
+      # Note Comment Attachments, Email Comment, Attachments
+      def store_item_collection(item, type, collection_name, base_dir)
+        collection = item.send(collection_name)
+        log "  * Found #{collection.size} #{collection_name}"
+
+        attachment_dir = File.join(base_dir, "attachments")
+        FileUtils.mkdir_p(attachment_dir)
+
+        collection.each_with_index do |item, index|
+          attachments = item.attributes['attachments'] || []
+
+          unless options[:skip_items].include?("Comment")
+            comments = item.comments
+            item.attributes['comments'] = comments
+          else
+            comments = []
+          end
+
+          log "    * Found #{comments.size} comments, #{attachments.size} attachments"
+          store_item(item, base_dir, "    * ")
+
+          attachments.each do |attachment|
+            download_attachment(attachment, attachment_dir, "    * ")
+          end
+
+          comments.each do |comment|
+            (comment.attributes['attachments'] || []).each do |attachment|
+              download_attachment(attachment, attachment_dir, "    * ")
+            end
+          end
+        end
+      end
+
+      def store_item(item, dir, log_prefix = "")
+        file = "#{item_filename(item)}.#{format}"
+        path = File.join(dir, file)
+        log "#{log_prefix}Store #{file}"
+        File.open(path, "w") { |f| f << item.send(format_method) }
+      end
+
+      def download_attachment(attachment, dir, log_prefix = "")
+        return if options[:skip_attachments]
+
+        file = "#{attachment.attributes['id']}-#{attachment.attributes['name']}"
+        path = File.join(dir, file)
+
+        log "#{log_prefix}Download attachment #{file}"
+        download_file(attachment.attributes['url'], path)
+      end
+
+      def filter_casedeal_collection!(collection)
+        collection.reject! do |casedeal|
+          parties = casedeal_parties(casedeal)
+          not parties.any? { |party| fetched_party?(party) }
+        end
+
+        log "# Filtered to #{collection.size} items"
+      end
+
+      def symlink_casedeal_collection(collection)
+        collection.each do |casedeal|
+          casedeal_parties(casedeal).each do |party|
+            next unless fetched_party?(party)
+            symlink_casedeal_to_party(casedeal, party)
+          end
+        end
+      end
+
+      def casedeal_parties(casedeal)
+        parties = []
+        parties += casedeal.parties
+        parties.push(casedeal.party) if casedeal.is_a?(Highrise::Deal)
+        parties.compact!
+        parties.uniq!
+        parties
+      end
+
+      def fetched_party?(party)
+        !!@parties[party.attributes['type']].detect { |p| p.id == party.id }
+      end
+
+      def symlink_casedeal_to_party(casedeal, party)
+        source_name = item_filename(casedeal)
+        destination_name = item_filename(party)
+        source_path = File.join('..', '..', '..', item_dirname(casedeal), source_name)
+        party_dir = File.join(root_dir, item_dirname(party), item_filename(party))
+        destination_dir = File.join(party_dir, item_dirname(casedeal))
+
+        FileUtils.mkdir_p(destination_dir)
+        Dir.chdir(destination_dir) do
+          log "  Symlink #{source_name} to #{destination_name}"
+          FileUtils.ln_s(source_path, source_name)
+        end
+      end
+
+      def item_dirname(item)
+        case item
+        when Highrise::Party
+          item_dirname(item.type_object)
+        when Highrise::Person
+          "persons"
+        when Highrise::Company
+          "companies"
+        when Highrise::Kase
+          "cases"
+        when Highrise::Deal
+          "deals"
+        else
+          raise "Unknown #{item.class}"
+        end
+      end
+
+      def item_filename(item)
+        case item
+        when Highrise::Party
+          "#{item.attributes['type']}-#{item.id}-#{item.name}"
+        when Highrise::Person
+          "Person-#{item.id}-#{item.name}"
+        when Highrise::Company
+          "Company-#{item.id}-#{item.name}"
+        when Highrise::Kase
+          "Case-#{item.id}-#{item.name}"
+        when Highrise::Deal
+          "Deal-#{item.id}-#{item.name}"
+        when Highrise::Email
+          "Email-#{item.id}-#{item.title}"
+        when Highrise::Note
+          "Note-#{item.id}-#{item.body}"[0,64]
+        else
+          raise "Unknown #{item.class}"
+        end.parameterize
+      end
+
+    end
+  end
+end

data/lib/highrise_assist/command.rb

@@ -0,0 +1,20 @@
+module HighriseAssist
+  module Command
+    class << self
+      def names
+        @names ||= []
+      end
+
+      def defined?(name)
+        names.include?(name)
+      end
+
+      def run(name, options)
+        self.const_get(name.classify).new(options).run
+      end
+    end
+  end
+end
+
+require "highrise_assist/command/base"
+require "highrise_assist/command/export"

data/lib/highrise_assist/file_transfer.rb

@@ -0,0 +1,30 @@
+require "net/http/persistent"
+
+module HighriseAssist
+  class FileTransfer
+    def initialize(options)
+      @options = options
+
+      @http = Net::HTTP::Persistent.new('highrise-file-transfer')
+      @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      @http
+    end
+
+    def download(from, to)
+      uri = URI.parse(from)
+
+      get_request = Net::HTTP::Get.new(uri.request_uri)
+      get_request.basic_auth @options[:token], ''
+
+      @http.request(uri, get_request) do |response|
+        open(to, 'w') do |io|
+          response.read_body { |chunk| io.write chunk }
+        end
+      end
+    end
+
+    def upload(from, to)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/highrise_assist/runner.rb

@@ -0,0 +1,73 @@
+# encoding: utf-8
+
+$KCODE = 'u' if RUBY_VERSION =~ /^1.8/
+
+require "optparse"
+
+module HighriseAssist
+  class Runner
+    def self.run(*args)
+      new(*args).run!
+    end
+
+    def initialize(argv)
+      @argv = argv
+      @options = {}
+      @options[:skip_items] = []
+    end
+
+    def run!
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: #{$0} COMMAND [options]"
+
+        o.separator ""
+        o.separator "Commands:"
+        o.separator "  * export - export next highrise items:"
+        %w(cases deals people companies emails notes comments attachments).each do |item|
+          o.separator "    * #{item}"
+        end
+
+        o.separator ""
+        o.separator "Common options:"
+        o.on("--domain DOMAIN", "highrise subdomain or full domain name") { |v| set_domain_option(v) }
+        o.on("--token TOKEN", "highrise API authentication token") { |v| @options[:token] = v }
+        o.separator ""
+
+        o.separator "Export options:"
+        o.on("--tag TAG", "filter items with given tag name") { |v| @options[:tag] = v }
+        o.on("--directory DIRECTORY", "working directory") { |v| @options[:directory] = v }
+        o.on("--format FORMAT", "data format (#{Command::Export::FORMATS.join(',')}) ") { |v| @options[:format] = v }
+        o.on("--skip-attachments", "don't download attachments") { @options[:skip_attachments] = true }
+        o.on("--skip-cases", "don't export cases") { @options[:skip_items] << "Kase" }
+        o.on("--skip-deals", "don't export deals") { @options[:skip_items] << "Deal" }
+        o.on("--skip-notes", "don't export notes") { @options[:skip_items] << "Note" }
+        o.on("--skip-emails", "don't export emails") { @options[:skip_items] << "Email" }
+        o.on("--skip-comments", "don't export comments") { @options[:skip_items] << "Comment" }
+
+        o.separator ""
+        o.separator "Misc options:"
+        o.on_tail("-h", "--help", "Show this message") { puts o; exit }
+        o.on_tail('-v', '--version', "Show version")   { puts HighriseAssist::VERSION; exit }
+      end
+
+      parser.parse!(@argv)
+
+      command = @argv.first
+
+      Command.defined?(command) or raise OptionParser::ParseError, "Unknown command #{command.inspect}"
+
+      Command.run(command, @options)
+    rescue OptionParser::ParseError => e
+      warn e.message
+      puts parser.help
+      exit 1
+    end
+
+    private
+
+    def set_domain_option(value)
+      @options[:domain] = value.include?('.') ? value : "#{value}.highrisehq.com"
+    end
+
+  end
+end

data/lib/highrise_assist/version.rb

@@ -0,0 +1,3 @@
+module HighriseAssist
+  VERSION = "0.0.1"
+end

data/lib/highrise_assist.rb

@@ -0,0 +1,9 @@
+require "highrise_assist/version"
+
+require "highrise_ext"
+
+module HighriseAssist
+  autoload :Runner, "highrise_assist/runner"
+  autoload :Command, "highrise_assist/command"
+  autoload :FileTransfer, "highrise_assist/file_transfer"
+end

data/lib/highrise_ext.rb

@@ -0,0 +1,25 @@
+require "highrise"
+
+Highrise::Base.format = :xml
+
+Highrise::Party.class_eval do
+  def notes
+    Highrise::Note.find_all_across_pages(:from => "/#{type_collection_name}/#{id}/notes.xml")
+  end
+
+  def emails
+    Highrise::Email.find_all_across_pages(:from => "/#{type_collection_name}/#{id}/emails.xml")
+  end
+
+  def name
+    type_object.name
+  end
+
+  def type_object
+    Highrise.const_get(attributes['type']).new(attributes)
+  end
+
+  def type_collection_name
+    Highrise.const_get(attributes['type']).collection_name
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification 
+name: highrise_assist
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Andriy Yanko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-11-17 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: highrise
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: net-http-persistent
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 2
+        - 3
+        version: "2.3"
+  type: :runtime
+  version_requirements: *id002
+description: Assist for 37signals' highrise
+email: 
+- andriy.yanko@gmail.com
+executables: 
+- highrise_assist
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- bin/highrise_assist
+- highrise_assist.gemspec
+- lib/highrise_assist.rb
+- lib/highrise_assist/command.rb
+- lib/highrise_assist/command/base.rb
+- lib/highrise_assist/command/export.rb
+- lib/highrise_assist/file_transfer.rb
+- lib/highrise_assist/runner.rb
+- lib/highrise_assist/version.rb
+- lib/highrise_ext.rb
+homepage: https://github.com/railsware/highrise_assist
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: highrise_assist
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: Assist for 37signals' highrise
+test_files: []
+