zensana 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ea308a2a19d3adbe4fbd80bca3ddc3a09042668b
+  data.tar.gz: fa62e437c65bd88ebf8a2ec4ff0d716ae04813f8
+SHA512:
+  metadata.gz: d0383bcc73118353f5c0bacf11beb5fd10ce72bd6b663ceafddf5ca521b5a6387d80aec6b221a6646f5104a93ec1bc51fe9e7db65428b71def38b6c11a8132a2
+  data.tar.gz: 1b81528f9917e9f6982e81355c0fa595711625c26fe286f1ec209920b9b0c5ffef6772d5cd9e890ca8d836e60cbe30e83f0d85939e66e5732175103f76140ebb

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.1

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,55 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.("routing/#{m[1]}_routing"),
+      rspec.spec.("controllers/#{m[1]}_controller"),
+      rspec.spec.("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end

data/LICENCE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Warren Bain
+
+MIT License
+
+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,165 @@
+# Zensana
+
+This gem provides access to the Asana API and ZenDesk Ticket Import API
+for the purpose of importing tasks from Asana Projects into ZenDesk
+tickets.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zensana'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install zensana
+
+## Usage
+
+I had a specific use-case in developing this: to get off Asana as a
+support ticketing system and onto ZenDesk. So there aren't many tests
+(I know, I know) and there are only a few commands available in the cli.
+
+### CLI
+
+This uses Thor so follows the general pattern of
+
+    $ zensana COMMAND SUBCOMMAND OPTIONS
+
+The help is pretty self-explanatory around the options so just try that
+
+    $ zensana help
+      Commands:
+        zensana help [COMMAND]      # Describe available commands or one specific command
+        zensana project SUBCOMMAND  # perform actions on Asana projects
+
+#### project command
+
+The primary use for zensana is to convert an Asana project's tasks into
+ZenDesk tickets. The `convert` subcommand has quite a few options to
+control what gets converted.
+
+    $ zensana project help convert
+      Usage:
+        zensana convert PROJECT
+
+      Options:
+        -a, [--attachments], [--no-attachments]  # download and upload any attachments
+                                                 # Default: true
+        -c, [--completed], [--no-completed]      # include tasks that are completed
+        -u, [--default-user=DEFAULT_USER]        # set a default user to assign to tickets
+        -s, [--stories], [--no-stories]          # import stories as comments
+                                                 # Default: true
+        -v, [--verified], [--no-verified]        # `false` will send email to zendesk users created
+                                                 # Default: true
+
+      Convert PROJECT tasks to ZenDesk tickets (exact ID or NAME required)
+
+#### idempotentcy
+
+To ensure robustness of the conversion, especially given that internet
+connection issues may interrupt it, the project conversion is idempotent
+and can be restarted as many times as necessary. In particular
+
+* tasks that have already been successfully created will not be
+  recreated as tickets (the Asana task_id is stored as the Zendesk
+  ticket external_id)
+* attachments will only be downloaded if they do not exist in the
+  download directory
+
+### Classes
+
+You can also directly access classes which model Asana data objects.
+
+```ruby
+require 'zensana'
+
+my_project = Zensana::Asana::Project.new('My awesome Asana Project')
+
+my_project.full_tasks.each do |task|
+  puts "Task #{task.name} has tags: #{task.tags}"
+end
+```
+
+Check ../commands/project.rb for examples in action.
+
+#### Asana
+
+There is support for reading:
+* user
+* project
+* task
+* attachment - downloading
+
+#### ZenDesk
+
+There is support for accessing and updating:
+* user
+* ticket - via the Ticket Import API only
+* comment
+* attachment - uploading
+
+## Authenticating
+
+### Asana
+
+Asana users can connect to the API using their username / password or
+by creating an API key. The following environment vars are required:
+
+```ruby
+ASANA_API_KEY
+  or
+ASANA_USERNAME
+ASANA_PASSWORD
+```
+
+### ZenDesk
+
+ZenDesk by default requires username / password to connect to the API,
+and the endpoint is defined by the organisation domain name. The following
+environment vars are required:
+
+```ruby
+ZENDESK_USERNAME
+ZENDESK_PASSWORD
+ZENDESK_DOMAIN
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/thoughtcroft/zensana/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+# License
+
+### This code is free to use under the terms of the MIT license.
+
+Copyright (c) 2015 Warren Bain
+
+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/Rakefile

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

data/bin/zensana

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path("../../lib", __FILE__)
+
+require "zensana"
+
+Zensana::Cli.start

data/lib/zensana/cli.rb

@@ -0,0 +1,8 @@
+module Zensana
+  class Cli < Zensana::Command
+
+    desc 'project SUBCOMMAND', 'perform actions on Asana projects'
+    subcommand 'project', Project
+
+  end
+end

data/lib/zensana/command.rb

@@ -0,0 +1,7 @@
+require 'thor'
+
+module Zensana
+  class Command < Thor
+    include Thor::Actions
+  end
+end

data/lib/zensana/commands/project.rb

@@ -0,0 +1,293 @@
+module Zensana
+  class Command::Project < Zensana::Command
+
+    desc 'find PROJECT', 'List projects that match PROJECT (by ID or NAME, regexp accepted)'
+    def find(name)
+      puts Zensana::Asana::Project.search(name).collect { |p| p['name'] }.sort
+    end
+
+    desc 'show PROJECT', 'Display details of PROJECT (choosing from list matching ID or NAME, regexp accepted)'
+    option :tasks, type: 'boolean', aliases: '-t', default: true, desc: 'display project task summary'
+    def show(project)
+      candidates = Zensana::Asana::Project.search(project)
+
+      if candidates.empty?
+        say "\nNo project found matching '#{project}'", :red
+      else
+        result = select_project(candidates)
+        candidate = Zensana::Asana::Project.new(result)
+        say "\nProject attributes...", :green
+        puts candidate.attributes.pretty
+
+        if options[:tasks]
+          say "Associated tasks...", :green
+          puts candidate.task_list.pretty
+        end
+      end
+    end
+
+    desc 'convert PROJECT', 'Convert PROJECT tasks to ZenDesk tickets (exact ID or NAME required)'
+    option :attachments,  type: 'boolean', aliases: '-a', default: true,  desc: 'download and upload any attachments'
+    option :completed,    type: 'boolean', aliases: '-c', default: false, desc: 'include tasks that are completed'
+    option :default_user, type: 'string',  aliases: '-u', default: nil,   desc: 'set a default user to assign to tickets'
+    #    option :followers,    type: 'boolean', aliases: '-f', default: false, desc: 'add followers of tasks to tickets'
+    option :stories,      type: 'boolean', aliases: '-s', default: true,  desc: 'import stories as comments'
+    option :verified,     type: 'boolean', aliases: '-v', default: true,  desc: '`false` will send email to zendesk users created'
+    def convert(project)
+      @asana_project = Zensana::Asana::Project.new(project)
+      say <<-BANNER
+
+This will convert the following Asana project into ZenDesk:
+
+     id: #{@asana_project.id}
+   name: #{@asana_project.name}
+
+using options #{options}
+
+      BANNER
+
+      unless yes?("Do you wish to proceed?", :yellow)
+        say "\nNothing else for me to do, exiting...\n", :red
+        exit
+      end
+
+      # LIFO tags for recursive tagging
+      #
+      # `project_tag_list` holds the project tags
+      # and also the tags for the current task and
+      # its parent tasks which are all added to the ticket
+      #
+      # `section_tag_list` holds the tags for the last
+      # section task which are also added to tickets
+      #
+      tags = [ 'zensana', 'imported' ]
+      project_tags = [] << tags
+      section_tags = []
+
+      @asana_project.full_tasks.each do |task|
+        task_to_ticket task, project_tags, section_tags
+      end
+      say "\n\n ---> Finished!\n\n", :green
+    end
+
+    private
+
+    # display list of projects by name
+    # and prompt for selection by index
+    #
+    # returns selected project_id
+    #
+    def select_project(array)
+      return array.first['id'] if array.size == 1
+
+      str_format   = "\n %#{array.count.to_s.size}s: %s"
+      question     = set_color "\nWhich project should I use?", :yellow
+      answers      = {}
+
+      array.sort_by { |e| e['name'] }.each_with_index do |project, index|
+        i = (index + 1).to_s
+        answers[i] = project['id']
+        question << format(str_format, i, project['name'])
+      end
+
+      puts question
+      reply = ask("> ").to_s
+      if answers[reply]
+        answers[reply]
+      else
+        say "Not a valid selection, I'm out of here!", :red
+        exit 1
+      end
+    end
+
+    # convert and asana task into a zendesk ticket
+    # calls itself recursively for subtasks
+    #
+    def task_to_ticket(task, project_tags, section_tags )
+      if task.attributes['completed'] && !options[:completed]
+        say "\nSkipping completed task: #{task.name}! ", :yellow
+        return
+      end
+
+      # sections contribute their tags but nothing else
+      # and the same is true of tasks already created
+      if task.is_section?
+        say "\nProcessing section: #{task.section_name} "
+        section_tags.pop
+        section_tags.push task.tags << snake_case(task.section_name)
+      else
+        say "\nProcessing task: #{task.name} "
+        project_tags.push snake_case(task.tags)
+
+        if Zensana::Zendesk::Ticket.external_id_exists?(task.id)
+          say "\n >>> skip ticket creation, task already imported ", :yellow
+        else
+          requester = asana_to_zendesk_user(task.created_by, true)
+
+          # create comments from the task's stories
+          if options[:stories]
+
+            comments = []
+            task.stories.each do |story|
+              if story['type'] == 'comment' &&
+                  (author = asana_to_zendesk_user(story['created_by'], true))
+                comments << Zensana::Zendesk::Comment.new(
+                  :author_id  => author.id,
+                  :value      => story['text'],
+                  :created_at => story['created_at'],
+                  :public     => true
+                ).attributes
+              end
+            end
+
+            # process attachments on this task
+            if options[:attachments]
+              download_attachments task.attachments
+              if tokens = upload_attachments(task.attachments)
+                comments << Zensana::Zendesk::Comment.new(
+                  :author_id => requester.id,
+                  :value     => 'Attachments from original Asana task',
+                  :uploads   => tokens,
+                  :public    => true
+                ).attributes
+              end
+            end
+          end
+
+          # if assignee is not an agent then leave unassigned
+          if (assignee_key = options[:default_user] || task.attributes['assignee'])
+            unless (assignee = asana_to_zendesk_user(assignee_key, false)) &&
+                (assignee.role != 'end-user')
+              assignee = nil
+            end
+          end
+
+          # ready to import the ticket now!
+          ticket = Zensana::Zendesk::Ticket.new(
+            :requester_id => requester.id,
+            :external_id  => task.id,
+            :subject      => task.name,
+            :description  => <<-EOF,
+            This is an Asana task imported using zensana @ #{Time.now}
+
+                    Project:  #{@asana_project.name} (#{@asana_project.id})
+
+                 Task notes:  #{task.notes}
+
+            Task attributes:  #{task.attributes}
+            EOF
+            :assignee_id  => assignee ? assignee.id : '',
+            :created_at   => task.created_at,
+            :tags         => flatten_tags(project_tags, section_tags),
+            :comments     => comments
+          )
+          ticket.import
+        end
+
+        # rinse and repeat for subtasks and their subtasks and ...
+        # we create a new section tag list for each recursed level
+        sub_section_tags = []
+        task.subtasks.each do |sub|
+          task_to_ticket Zensana::Asana::Task.new(sub.attributes['id']), project_tags, sub_section_tags
+        end
+
+        # this task's tags are now no longer required
+        project_tags.pop
+      end
+    end
+
+    # lookup up asana user on zendesk and
+    # optionally create new if not exists
+    #
+    # return: zendesk user or nil
+    #
+    def asana_to_zendesk_user(spec, create)
+      key = spec.is_a?(Hash) ? spec['id'] : spec
+      asana   = Zensana::Asana::User.new(key)
+      zendesk = Zensana::Zendesk::User.new
+      zendesk.find(asana.email)
+    rescue NotFound
+      if create
+        zendesk.create(
+          :email => asana.email,
+          :name  => asana.name,
+          :verified => options[:verified]
+        )
+        zendesk
+      else
+        nil
+      end
+    else
+      zendesk
+    end
+
+    # download the attachments to the local file system
+    # and retry a few times because internet
+    # the download process is restartable (idempotent)
+    #
+    def download_attachments(attachments)
+      return if attachments.nil? || attachments.empty?
+      say "\n >>> downloading attachments "
+
+      attachments.each do |attachment|
+        tries = 3
+        begin
+          attachment.download
+          print '.'
+        rescue
+          retry unless (tries-= 1).zero?
+          raise
+        end
+      end
+    end
+
+    # upload all of the attachments from the local file system
+    # and retry a few times because internet
+    #
+    # return: array of tokens
+    #
+    def upload_attachments(attachments)
+      return if attachments.nil? || attachments.empty?
+      say "\n >>> uploading attachments "
+
+      [].tap do |tokens|
+        attachments.each do |attachment|
+          tries = 3
+          begin
+            uploader = Zensana::Zendesk::Attachment.new
+            tokens << uploader.upload(attachment.full_path)['token']
+            print '.'
+          rescue
+            retry unless (tries-= 1).zero?
+            raise
+          end
+        end
+      end
+    end
+
+    # take multiple arrays and flatten them
+    #
+    # return: single array of unique tags
+    #
+    def flatten_tags(*args)
+      tags = []
+      args.each { |a| tags << a }
+      tags.flatten.uniq
+    end
+
+    def snake_case(thing)
+      case
+      when thing.is_a?(String)
+        snake_case_it thing
+      when thing.is_a?(Array)
+        thing.map { |a| snake_case a }
+      else
+        raise ArgumentError, "I don't know how to snake_case instances of #{thing.class}"
+      end
+    end
+
+    def snake_case_it(thing)
+      thing.gsub(/(.)([A-Z])/,'\1_\2').gsub(' ', '_').downcase
+    end
+  end
+end

data/lib/zensana/models/asana/attachment.rb

@@ -0,0 +1,62 @@
+module Zensana
+  class Asana
+    class Attachment
+      include Zensana::Asana::Access
+
+      attr_reader :attributes
+
+      def initialize(id)
+        @attributes = fetch(id)
+      end
+
+      def download
+        download_file unless downloaded?
+      end
+
+      def download!
+        File.delete full_path if downloaded?
+        download_file
+      end
+
+      def downloaded?
+        File.exist? full_path
+      end
+
+      def full_path
+        File.join(file_dir, attributes['name'])
+      end
+
+      def method_missing(name, *args, &block)
+        attributes[name.to_s] || super
+      end
+
+      private
+
+      def file_dir
+        File.join(temp_dir, 'downloads', parent)
+      end
+
+      def temp_dir
+        ENV['ZENSANA_TEMP_DIR'] || '/tmp/zensana'
+      end
+
+      def parent
+        attributes['parent']['id'].to_s
+      end
+
+      def fetch(id)
+        asana_service.fetch("/attachments/#{id}")
+      end
+
+      def download_file
+        FileUtils.mkdir_p file_dir
+        result = File.open(full_path, "wb") do |f|
+          f.write HTTParty.get(self.download_url)
+        end
+
+        Zensana::Error.handle_https result
+        Zensana::Response.new(result).ok?
+      end
+    end
+  end
+end