Asanawarrior

From Dgraph Wiki
Jump to: navigation, search

Asanawarrior

Asanawarrior[1] (nicknamed AW) provides bi-directional sync between Asana[2] and Taskwarrior[3], so you can use Taskwarrior as a command line interface to Asana. Using AW, you can rely entirely on Taskwarrior, to handle your and your team members' Asana tasks.

Why did we build this?

AW is written by an overworked CEO to manage the tasks of his team, out of frustration with Asana's slow browser interface and lack of a desktop or command line based solution. The original idea was to build a credible command line tool for Asana. But, the more thought was given to the problem, the more Taskwarrior affirmed to be the right solution.

Taskwarrior is an excellent command line based solution for handling tasks, but it doesn't work for teams yet. While Asana is an excellent solution for teams but doesn't have a command line or handy desktop tool. AW bridges this gap, with the idea that you wouldn't need ever to open up app.asana.com to handle your and your entire teams' tasks.

Installation

Using Go

$ go get -v -u github.com/manishrjain/asanawarrior

$ asanawarrior --help
Usage of asanawarrior:
 -db string
 	File path for db which stores certain sync information. (default "$HOME/.task/asanawarrior.db")
 -deletes int
 	If Asanawarrior sees more than these number of deletes, it's going to crash to protect your Asana from mass deletion. (default 5)
 -domain string
 	Workspace name, generally your domain name in Asana.
 -dur int
 	How often to run sync, specified in minutes. (default 1)
 -interval int
 	Minimum duration in seconds between successive notifications. Set to zero for no notifications. (default 10)
 -token string
 	Token provided by Asana.

Github Releases

You can pick up the precompiled binary for your platform from the Github releases page[4]. Once downloaded, unzip it and store it somewhere in your $PATH.

For e.g. - If you downloaded asanawarrior_darwin_amd64.gz. You can do

# To extract the gzipped file.
gunzip asanawarrior_darwin_amd64.gz
# To make the binary executable
chmod +x asanawarrior_darwin_amd64
# Put it in your $PATH
mv asanawarrior_darwin_amd64 /usr/local/bin/asanawarrior

Arch Linux

TODO: Add asanawarrior in AUR packages.

Usage

Before you run Asanawarrior, do set these lines in your taskrc, which should be located at $HOME/.taskrc.

# Required by Asanawarrior.
uda.xid.type=string

You can now run AW with just a token and domain, like so.

$ asanawarrior --token 'ASANA_PERSONAL_ACCESS_TOKEN_HERE' --domain YOUR_COMPANY_DOMAIN_HERE

Flags

--token (required) To get the personal access token, follow these steps:

  1. Go to https://app.asana.com
  2. Click on your profile icon on top right
  3. Select My Profile Settings
  4. Select Apps
  5. Click on Manage Developer Apps
  6. Click on Create New Personal Access Token
  7. Set the description. Suggested: Asanawarrior
  8. Click on Create
  9. An access token will be generated. Copy it over and store it somewhere
  10. Provide this access token in single quotes to asanawarrior as specified above

--domain (required) Your domain name is as specified on the top right corner in app.asana.com. For example, for Dgraph, it's dgraph.io.

--db Set the db flag to the directory which stores Taskwarrior tasks. This typically is $HOME/.task. The advantage of putting this in the same directory as TW tasks is that if you delete that directory to clear out TW and start from a new slate, the sync information stored by AW would also be cleared out.

--deletes This is the number of Asana tasks that can be deleted per AW sync. This is set to 5 by default, which means if more than five tasks are deleted in between two AW syncs, then AW would complain and crash. This is an important safety fuse. We've seen some people delete all Taskwarrior tasks by running `task delete`, which on sync used to delete all Asana tasks. This setting avoids that issue.

If you want to completely avoid syncing any deletions from TW to Asana, set this flag to zero.

--dur This flag specifies how often to run the sync. By default, it's set to a sync per minute.

--interval Asanawarrior also provides sync notifications. To avoid sending too many notifications, it would buffer them up in the specified time interval. By default, this is set to 10 seconds. If you don't want any notifications, set this to zero.

Sync

Asanawarrior runs bi-directional syncs. That means it would sync any changes from Asana to Taskwarrior and from Taskwarrior to Asana. AW keeps track of modification times to figure out which system has changed and syncs those changes to the other.

Currently, these are the Asana features that are synced.

Feature Sync Create Delete
Tasks ✔ [Issue/18]
Project
Tags
Assignee
Section ✘ [Issue/14]
Description ✘ [Issue/6]
Comments ✘ [Issue/5]
Due Date ✘ [Issue/8]

Taskwarrior

Taskwarrior is an incredible command line app. It allows a lot of flexibility in how you add, view and manage your tasks. Here're some settings that we've found to be useful.

# Search
search.case.sensitive = no  # Allow case insensitive search over tasks.

# Urgency coefficients
urgency.age.coefficient                       = 2.0   # coefficient for age
urgency.user.tag.upcoming.coefficient         = 7.5
urgency.user.tag._SomedayMaybe.coefficient    = -15.0 # Tasks in SomedayMaybe section.
urgency.user.tag._WaitingFor.coefficient      = -10.0 # Tasks in WaitingFor section.
urgency.user.tag.v0.4.coefficient             = 3.0   # Prioritize tasks tagged for Dgraph's current release v0.4
urgency.user.tag.v0.5.coefficient             = -13.0 # De-prioritize tasks tagged for Dgraph's next release v0.5
urgency.user.project.Learning.coefficient     = -7.0  # Coefficients for various Dgraph projects.
urgency.user.project.Technical.coefficient    = 2.0
urgency.user.project.Development.coefficient  = 5.0

# Colors
rule.color.merge          = no                    # If a task matches multiple color settings, only pick one. Don't merge them.
color.alternate           =                       # By default, background colors alternate per line. Avoid that.
color.tag.next            = bold white on red     # White text on red background for tasks with tag next.
color.tag.upcoming        = bold white on rgb010
color.project.Development = rgb332                # Different colors for different Dgraph projects.
color.project.Learning    = gray10
color.project.Company     = rgb233
color.project.Technical   = rgb023
color.active              = black on bright green # Setting for task marked as started.

View Tasks

$ task                                # View all tasks sorted by urgency score.
$ task project:Learning               # View tasks for 'Learning' project.
$ task [email protected]                       # View tasks assigned to 'manish'.
$ task project:Company +_SomedayMaybe # View tasks in 'Someday Maybe' section of 'Company' project.

Add Tasks

$ task add "Make Asanawarrior package in Arch Linux AUR" project:Technical [email protected] +blue +_SomedayMaybe
# Add a new task in project 'Technical', section 'Someday Maybe', assign it to [email protected] and set tag as blue.

Modify Tasks

$ task 11 modify [email protected] [email protected] -blue +red
# Reassign task from [email protected] to [email protected] Remove tag blue, add tag red.

$ task 11 modify "Change the name of the task."
$ task 11 modify project:Technical # Move task to project Technical.

Delete Tasks

$ task 11 delete     # Delete a particular task.
$ task 12-14 delete  # Delete tasks 12, 13 and 14.
$ task [email protected] delete # Delete tasks assigned to [email protected]

Troubleshooting

I need a certain feature. How do I get that?

If you want some feature, feel free to create an issue in Github issues[5]. You can also upvote any existing issue, so we know it's important to you. While the focus is on building the features that Dgraph team needs, if we have spare cycles, we'll do our best to add a feature for you. And of course, we always appreciate Pull Requests.

I accidentally deleted all TW tasks, and AW crashed to avoid syncing that. What should I do?

If you do accidentally delete all tasks from TW, and AW crashes due to it's --delete fail-safe flag; the best way to bring yourself back in sync with Asana is to delete your TW task directory. This is typically located at $HOME/.task/. Just run cd $HOME/.task && rm *. Run Asanawarrior again, and you should have your TW synced up to Asana in no time.

If however, you did intend to delete all Asana tasks, and are using TW to achieve that, set the --delete flag to some very high number, and run AW again. It would then delete all Asana tasks.

I accidentally deleted many Asana tasks, how do I recover them?

If you did end up somehow deleting your Asana tasks, and want to recover them, look for Show recents and more -> Deleted Items in app.asana.com. You should be able to see them there. You can batch select them, and click on Undelete.

References

  1. https://github.com/manishrjain/asanawarrior
  2. https://asana.com
  3. https://taskwarrior.org/
  4. https://github.com/manishrjain/asanawarrior/releases
  5. https://github.com/manishrjain/asanawarrior/issues