asana_snapshot 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 97597233f2dbc17a8f86f9cfc588a979b308e37b
+  data.tar.gz: 4e0e25b7f25414548ae8bb5f1b74dbcbe2b38bc6
+SHA512:
+  metadata.gz: 6e53bae9059fb06962becb66404d8f895c5e414f8bb873395558fac80206fadb7d06db3175cc996e8ebc957122c54aa1010d3aeafb6bf2d7bfcb71959d57af13
+  data.tar.gz: 88eed4add936e327f4a7cb47448996ebe3bfc095693e91a2ac3b2d7538d0bb528c443f1eae079ba971081ed8cce530c7746f3b7ef23605f04d67266c66e0b1ed

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2018 Matt Yeh
+
+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,115 @@
+## Asana Snapshot
+
+[Asana](https://www.asana.com) is a great, versatile task management system.  However, like many similar task management systems, being able to track meaningful progress across one or more projects; burn-down charts are great, but are not built to extract any immediate, actionable decisions.  Tracking the progress of a project over a specified period of time can be quite cumbersome, if not impossible.  This becomes even more difficult in Asana when using Boards that might all have different names for the swim lanes/columns or that have different terminology for what tasks are 'complete' and 'incomplete'.
+
+Asana Snapshot has chosen to solve this issue by leveraging a change-tracking tool that is likely a part of most of our daily lives: [git](https://git-scm.com/).  Using git comparisons, one can gather information to drive useful & productive conversations about the progress of a given project, such as, overall velocity, project completeness and burndown, which specific tasks were completed in that time period, which specific tasks are at-risk (eg, which ones are assigned, but not completed or which remain unassigned within that given time period), etc.
+
+From a technical side, this gem will fetch all tasks based on a specific set of user-provided conditions, write to a text-based project snapshot file (ie, using Markdown), commit & tag those project snapshot files into a git repository, while doing so in a simple and repeatable manner.
+
+### Sample snapshot
+
+```
+## Stats
+Complete: 12
+Incomplete: 23 (12 unassigned)
+
+## Tasks
+[X] 473716394 ["Done"] - Joe Smith - provision test server
+[ ] 473716485 ["In Progress"] - John Doe - implement authentication service
+[ ] 473164858 ["Ready To Dev"] - Unassigned - develop profitable feature
+```
+
+Tasks are ordered by Asana task id, and so should almost always remain on the same line within a snapshot file, making tasks updates easier to parse out from the git tag comparisons.
+
+### Installation
+
+```
+gem install asana_snapshot
+```
+
+or if you are using Bundler add the following to your Gemfile
+
+```
+gem 'asana_snapshot'
+```
+
+### Configuration
+
+| Config        | Description                                                           | Default             |
+| ------------- | --------------------------------------------------------------------- | -------------------:|
+| logger        | gem logging destination                                               |  Logger.new STDOUT  |
+| token         | Asana API Personal Access Token                                       |  nil                |
+| base_dir      | file directory where snapshots will be saved                          |  Dir.pwd            |
+| persistence   | Hash specifying the persistence store (requires an `adapter` key)     |  {adapter: :git}    |
+
+Example:
+```
+AsanaSnapshot.configure do |config|
+  config.logger   = Logger.new('logfile.log')
+  config.token    = '_my_personal_token_'
+  config.base_dir = '/path/to/where/i/save/snapshots'
+end
+```
+
+### Usage
+
+There are two primary entry points for executing AsanaSnapshot: via its Ruby API or via the shipped executable file.
+
+In both cases, it expects the presence of a YAML config file which supplies information about the Asana workspace & projects upon which it will search for tasks.  AsanaSnapshot will only search for tasks (as opposed to sub-tasks) that belong to the projects in the YAML file and which contain any tags defined in the YAML file.
+
+#### Anatomy of a snapshot YAML file
+
+```
+title: 'Acme Boards'
+```
+The `title` key identifies how the snapshots will be organized.  The sub-directory of the configured `base_dir` in which snapshots are saved will be an underscored version of this `title`.
+
+```
+workspace: 123456789
+```
+The `workspace` key identifies which Asana workspace id to query for tasks.
+
+```
+filters:
+  tags: 234567890, 345678901
+```
+The `filters` key groups the possible query filters.  As of now, only `tags` are supported.  `tags` are a comma-delimited list of Asana tag id's that a task may contain.
+
+```
+projects:
+  - id: 4567890123
+    name: 'Phase 2 Widgets'
+    columns:
+      complete:
+        - 'Done'
+      incomplete:
+        - 'In Discovery'
+        - 'In Progress'
+```
+The `projects` key identifies the set of projects that will be searched.  It contains the Asana project id, a helpful `name` to identify it in the YAML file (which would likely match the name of the project in Asana, but it can be anything you want), and a `columns` key which identifies the names of the Asana sections of the project board should be considered as `complete` or `incomplete`.
+
+#### Ruby API
+
+Example:
+```
+AsanaSnapshot.configure do |config|
+  config.token = '_my_personal_token_'
+end
+
+AsanaSnapshot.execute './config/acme_boards.yml'
+```
+
+#### Executable
+
+The gem ships with an executable named `snap`.  `snap` takes a single argument, which is the path to the `asana_snapshot` config file.
+
+The `snap` executable uses the following environment variables to override the default AsanaSnapshot configuration:
+
+| ENV                     | Config  |
+| ----------------------- |:-------:|
+| ASANA_SNAPSHOT_TOKEN    | token   |
+
+Example:
+```
+ASANA_SNAPSHOT_TOKEN='_my_personal_token_' snap './config/acme_boards.yml'
+```

data/bin/snap

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require 'asana_snapshot'
+
+AsanaSnapshot.configure do |config|
+  config.token  = ENV['ASANA_SNAPSHOT_TOKEN'] if ENV['ASANA_SNAPSHOT_TOKEN']
+end
+
+AsanaSnapshot.execute ARGV[0]

data/lib/asana_snapshot/configuration.rb

@@ -0,0 +1,14 @@
+require 'logger'
+
+class AsanaSnapshot::Configuration
+  attr_accessor :logger, :token, :base_dir, :persistence
+
+  def initialize
+    @logger       = Logger.new STDOUT
+    @token        = nil
+    @base_dir     = Dir.pwd
+    @persistence  = {
+      adapter: :git
+    }
+  end
+end

data/lib/asana_snapshot/persistence/git.rb

@@ -0,0 +1,23 @@
+require 'git'
+
+class AsanaSnapshot::Persistence::GitAdapter
+  def initialize
+    @repo = Git.init(AsanaSnapshot.configuration.base_dir, log: AsanaSnapshot.configuration.logger)
+  end
+
+  def mark_for_save(file)
+    @repo.add file
+    true
+  end
+
+  def save(group)
+    today = Time.now.strftime('%Y-%m-%d')
+    @repo.commit "[#{group}] Snapshot: #{today}"
+
+    if @repo.tags.include?(today)
+      @repo.delete_tag today
+    end
+    @repo.add_tag today
+    true
+  end
+end

data/lib/asana_snapshot/persistence.rb

@@ -0,0 +1,17 @@
+class AsanaSnapshot::Persistence
+  extend Forwardable
+
+  attr_reader :adapter
+
+  def_delegators :adapter, :mark_for_save, :save
+
+  def initialize(adapter: :git)
+    case adapter.to_sym
+    when :git
+      require 'asana_snapshot/persistence/git'
+      @adapter = AsanaSnapshot::Persistence::GitAdapter.new
+    else
+      raise ArgumentError, "Unknown persistence adapter: #{adapter}"
+    end
+  end
+end

data/lib/asana_snapshot/snapshot_generator.rb

@@ -0,0 +1,67 @@
+require 'fileutils'
+
+module AsanaSnapshot
+  class SnapshotGenerator
+    attr_reader :snapshot_directory, :file, :project_id, :project
+
+    def initialize(tasks, group:, project_id:)
+      @project_id = project_id
+      @project = compile tasks
+
+      directory_name = group.downcase.gsub(' ', '_')
+      @snapshot_directory = "#{AsanaSnapshot.configuration.base_dir}/snapshots/#{directory_name}"
+
+      file_name = project[:name].gsub(' ', '_').gsub('&', 'and')
+      @file = "#{snapshot_directory}/#{file_name}.md"
+    end
+
+    def write
+      setup_directory
+
+      File.open(file, "w") do |f|
+        f.puts '## Stats'
+        f.puts "Complete: #{project[:stats][:complete]}"
+        f.puts "Incomplete: #{project[:stats][:incomplete]} (#{project[:stats][:unassigned]} unassigned)"
+        f.puts ''
+
+        f.puts '## Tasks'
+        project[:tasks].each do |task|
+          f.puts "[#{task.completed? ? 'X' : ' '}] #{task}"
+        end
+      end
+
+      AsanaSnapshot.persistence_store.mark_for_save file
+    end
+
+    private
+
+    def setup_directory
+      return if ::File.directory? snapshot_directory
+      ::FileUtils.mkdir_p(snapshot_directory)
+      ::FileUtils.chmod 0755, snapshot_directory
+    end
+
+    def compile(tasks)
+      tasks.sort_by(&:id).reduce({
+        name: nil,
+        tasks: [],
+        stats: {
+          complete: 0,
+          incomplete: 0,
+          unassigned: 0
+        }
+      }) do |memo, task|
+        task.project_columns.reject do |project_column|
+          project_column.project_id.to_i != project_id.to_i
+        end.each do |project_column|
+          memo[:name] ||= project_column.project_name
+          memo[:tasks].push task
+          memo[:stats][:complete]+=1 if task.completed?
+          memo[:stats][:incomplete]+=1 unless task.completed?
+          memo[:stats][:unassigned]+=1 if task.assignee_name.nil?
+        end
+        memo
+      end
+    end
+  end
+end

data/lib/asana_snapshot/task.rb

@@ -0,0 +1,46 @@
+module AsanaSnapshot
+  class Task
+    extend Forwardable
+
+    def_delegators :@task, :id, :name
+
+    def initialize(task_response)
+      @task = OpenStruct.new(task_response)
+    end
+
+    def assignee_name
+      @task.assignee&.send(:[], 'name')
+    end
+
+    def completed?
+      completed_task? || completed_column?
+    end
+
+    def project_columns
+      @project_columns ||= @task.memberships.map do |m|
+        OpenStruct.new(
+          project_id: m['project']['id'],
+          project_name: m['project']['name'],
+          column_name: m['section']['name']
+        )
+      end
+    end
+
+    def to_s
+      "#{id} #{project_columns.map(&:column_name)} - #{assignee_name || 'Unassigned'} - #{name}"
+    end
+
+    def completed_task?
+      @task.completed
+    end
+
+    def completed_column?
+      project_columns.map do |project_column|
+        project_config = AsanaSnapshot.projects.detect do |project|
+          project['id'] == project_column.project_id
+        end
+        project_config && project_config['columns']['complete']&.include?(project_column.column_name)
+      end.any?
+    end
+  end
+end

data/lib/asana_snapshot/task_searcher.rb

@@ -0,0 +1,35 @@
+require 'asana'
+require_relative './task'
+
+module AsanaSnapshot
+  class TaskSearcher
+    include Asana::Resources::ResponseHelper
+    extend Asana::Resources::ResponseHelper
+
+    attr_reader :client, :workspace_id
+
+    TASK_FIELDS = {
+      fields: [
+        'completed',
+        'name',
+        'assignee.name',
+        'memberships.(project|section).name'
+      ]
+    }.freeze
+
+    def initialize(token: required('token'), workspace_id: required('workspace_id'))
+      @client = Asana::Client.new do |c|
+        c.authentication :access_token, token
+      end
+      @workspace_id = workspace_id
+    end
+
+    def search(search_options = {})
+      endpoint = "/workspaces/#{workspace_id}/tasks/search"
+      search_results = parse client.get(endpoint, params: search_options, options: TASK_FIELDS)
+      search_results.first.map do |search_result|
+        AsanaSnapshot::Task.new search_result
+      end
+    end
+  end
+end

data/lib/asana_snapshot.rb

@@ -0,0 +1,59 @@
+require 'yaml'
+require 'logger'
+
+require 'asana_snapshot/task_searcher'
+require 'asana_snapshot/snapshot_generator'
+require 'asana_snapshot/configuration'
+require 'asana_snapshot/persistence'
+
+module AsanaSnapshot
+  class << self
+    attr_accessor :projects
+    attr_writer :configuration, :persistence_store
+  end
+
+  def self.configuration
+    @configuration ||= AsanaSnapshot::Configuration.new
+  end
+
+  def self.persistence_store
+    @persistence_store ||= AsanaSnapshot::Persistence.new(adapter: AsanaSnapshot.configuration.persistence[:adapter])
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.execute(config_file)
+    unless self.configuration.token
+      self.configuration.logger.error "No Asana token configured."
+    else
+      config = YAML.load_file config_file
+
+      self.projects = config['projects']
+      self.projects.each do |project|
+        tasks = AsanaSnapshot::TaskSearcher.new(
+          token: self.configuration.token,
+          workspace_id: config['workspace']
+        ).search(
+          'tags.any' => config['filters']['tags'],
+          'projects.any' => project['id'],
+          'is_subtask' => false
+        )
+
+        if tasks.any?
+          AsanaSnapshot::SnapshotGenerator.new(
+            tasks,
+            group: config['title'],
+            project_id: project['id']
+          ).write
+          self.configuration.logger.info "Successfully created snapshot for #{project['name']}"
+        else
+          self.configuration.logger.info "No tasks found for #{project['name']}"
+        end
+      end
+
+      self.persistence_store.save config['title']
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: asana_snapshot
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Matt Yeh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-09-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asana
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+description: "    AsanaSnapshot wraps the official Asana ruby client to search for
+  tasks, write them to text files, and check them into a git repository.\n"
+email: dev.mtyeh411@gmail.com
+executables:
+- snap
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/snap
+- lib/asana_snapshot.rb
+- lib/asana_snapshot/configuration.rb
+- lib/asana_snapshot/persistence.rb
+- lib/asana_snapshot/persistence/git.rb
+- lib/asana_snapshot/snapshot_generator.rb
+- lib/asana_snapshot/task.rb
+- lib/asana_snapshot/task_searcher.rb
+homepage: https://github.com/mtyeh411/asana_snapshot
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Save snapshots of Asana tasks.
+test_files: []