This post opens a series about developing a custom intergration solution between two rather known tools. Project management tool Asana and issue tracker done by Jetbrains company Youtrack. Part I defines problem, constraints, functional requirements and gives ideas about the possible solution without going into implementation at this point. Whole point of the series is to show thinking process starting from identifying a problem, through possible solutions including design decisions up to final working software.
Why?
Company I work for uses Youtrack for issue tracking but mainly for time reporting. Time reports are presented to the client along with the invoice, client pays and I got paid down the line. However client uses Asana for project management which means that Asana’s tasks have to be duplicated in Youtrack. All communication is done at Asana while time is reported at the Youtrack. Mapping tasks to issues manually 1 to 1 would be too hard to do manually, therefore no one is doing that. End result – Youtrack contains some generic issues like “Project X development” where time is reported.
Obviously it would be better if there was a 1 to 1 mapping between Asana’s tasks and Youtrack’s issues and time reporting was done automatically.
Possible solution
Given the problems, let’s try to find a solution. Quick research didn’t yield any results. There is some kind of integration between Asana and Jira using Zapier but since we are using Youtrack we are out of luck. I haven’t seen this service before so it’s worth mentioning. Anyway it looks like there is a need for custom solution.
Vision statement
“We want devs to spent less time on manual work with time tracking therefore we want a easy to use solution which synchronizes Asana task’s with Youtrack’s issues and reports time on behalf of developer automatically with best accuracy possible.”
Workflow which enables automatic time reports
Copying tasks over must be possible with both APIs so it’s a no brainer. However automatic time reporting requires certain workflow with Asana. One of the recent clients actually requires workflow which might satisfy technical issues of time tracking.
It goes like this: when dev starts working on a task, he/she is supposed to tag it with “wip” and when he’s done working he/she can remove the tag.
I had a chance of trying this workflow in action and it’s not a bulletproof solution, because if work is quite short, trace of adding and removing tag is lost. It still might work if our solution registers the fact that work has been begun. It would be simpler if we had two events in the time, tag added and tag removed. Then time spent is just a difference between tag removal and assignment. However with tag traces disappearing solution needs be more complex.
Alternative solution is leaving a comment with “wip” token, but it seems like this might be obscuring rest of the communication.
API analysis
Before doing any work let’s see what can be done with a API. For starters this is what we want to do:
query for tasks in Asana possibly with some filtering
query issues in Youtrack
create issues in Youtrack
add time tracking information to issues on behalf developer
These are minimal requirements for one way integration.
Let’s take a look what’s actually possible with APIs.
1. Query for tasks in Asana possibly with some filtering
1 2 3 | |
We are in luck. API allows to query for tasks in a project or workspace or all of them. Also limited filtering is possible for example by modified_since attribute which might be useful. General idea of syncing service is that it will probably be run in some intervals therefore filtering by last run’s date seems useful.
2. query issues in Youtrack
This is required to check if given task has been already synchronized or not. In alternative to querying we could store already mapped tasks’ ids and created issues. However storing anything obviously requires some kind of storage. If solution can deal without storage it is even better assuming that it works the same and within limits of APIs requests per minute.
Allows to query for issues in a certain project. That’s enough. We can assume that project will be configurable later on so we know where to sync and create issues.
3. create issues in Youtrack
Create new issue API shows how to do it.
1
| |
Got it!
4. add time tracking information to issues on behalf developer
This one wasn’t obvious especially because of “on behalf” part. We want to see time tracking information as the developer himself would have added. There an specific API which allows to record time, but it adds it as the user who performs request. Is that ok? Well it depends. If you are ok with giving out your credentials so service performs requests as you then sure. Youtrack documentation doesn’t mention API keys so only login + cookie workflow is available, hence it requires your credentials. I think that better option is if we have some special user on Youtrack which will interact with API and make all requets. Same account can be used in Asana, although Asana supports API keys so that’s better. As for now we only query Asana therefore we can do that from special account and if we would need to make some changes on someone else behalf then API keys should be used.
So I found that doing some action as someone else is only possible by applying command to an issue. There is parameter called runAs which takes login of the user it should be run as. This runAs parameter requires some specific permissions which is fine if we use special account just for our application. Great! Now let’s look for adding time tracking information command.
A little bit more search and there it is, adding work item to issue via command
Deployment
APIs allow to implement our solution. Some details will be needing clarifications but general building blocks are there. Now before thinking how we would implement it let’s think where can we run it.
Let’s add another requirement: Running it shouldn’t cost money.
This might seem silly, because it’s impossible in the long term, but there are cloud providers which give some free time which might be just enough for our solution.
I checked Heroku and Amazon AWS. Heroku allows to run 1 web dyno which goes idle if there is no traffic. Web dyno is not exactly what we would require, but it could work. Problem is with it going idle if there is no traffic. There is another dyno type called worker. Workers never go idle but they cost money therefore are not applicable.
Amazon AWS gives 750 hours a month of Amazon EC2 service which really hits the spot, at least for first year. There is also no problem of anything going idle. Maybe there are better alternatives but for now I got one good candidate and I know I can move on.
Wrapping up first part
We identified problem, checked that there are no ready solutions around. Defined requirements for APIs. Checked that APIs satisfy these requirements therefore application can be created. We also found a place to run it for free for the first year.
In the next part I will describe implementation process. Spray with Akka stack is a good candidate for this integration component because of nice abstractions for interacting with APIs and scheduling built in. Whole application will be run using Docker so it will be easy to change the actual server it runs on.