0.0
No commit activity in last 3 years
No release in over 3 years
AsanaSnapshot wraps the official Asana ruby client to search for tasks, write them to text files, and check them into a git repository.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

>= 0.8.0, ~> 0.8
>= 1.5.0, ~> 1.5.0
 Project Readme

Asana Snapshot

Asana 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. 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'