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:

1. query for tasks in Asana possibly with some filtering

2. query issues in Youtrack

3. create issues in Youtrack

4. 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

GET    /tasks
GET    /projects/project-id/tasks
GET    /workspaces/workspace-id/tasks

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.

Get issues in a project API

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

PUT /rest/issue?{project}&{summary}&{description}&{attachments}&{permittedGroup}

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.

Ramble on Internalization

Internalization is a tricky subject. It requires quite a lot of work to prepare product to be fully internalizationable. Translating text is the easiest part of the internalization process. Conforming to cultural norms is a tricky part. Unfortunately I have no prior experience with developing products available for example in arabic or asian countries but this seems like interesting challenge. Even though I haven’t done it I can notice that it requires a lot of work to test user interfaces across different languagues and keep them consistent. Having a graphic theme also may not be trivial task. But it’s not all about presentation. Having appropriate domain model which takes into account for example currency is important as well. That’s why it is important to think about these cases even though product is not going to be available worldwide at first. Otherwise adding dollars to yens might yield interesting results.

I18n in estimation

Internationalization is one of these things that I completely forgot when I try to give an estimation of time for particular task. It so happens that doing i18n is very tedious job which adds a lot of time for rest of the development time. During last project we left i18n as the last thing to do. I don’t know if that was a good choice because it requires a lot of time to go through every screen and translate all the labels. It’s also quite error prone. However when it can be done by less people and there are higher chances that key codes for labels are more consistent.

3 Approaches to design

There are 3 approaches to interaction design in mobile devices.

1. Platform dependent design
2. Own Cross-platform design
3. Adapted Cross-Platform design

Each approach has its merits and some of them might be even better in particular case of application. For example Own Cross-platform design might be suitable for game like application. Game does not require typical navigation, action bars and other GUI elements typical for a platform. Usually games offer neat looking menu in game’s theme so player can have immerse himself in a game’s world.

In the other case when application is more typical it’s better to go with platform dependent design because it offers similar experience that users already know. Such app feels natural to the users and can leverage components and interaction methods available only in one platform. The downside of that approach is that it is costly because then developers need to develop at least 2 platform specific applications which at most can share only the backend services.

If one decide to follow first approach then it is important to stick to the style guides of the platforms.

Style guides

Style guides are documents which contain pointers and sometimes requirements for interaction design of application. Requirements might include using elements for its intended purposes or using specific element in a given scenario.

Both major platforms Android and iOS have their style guides. Check them if you would like to know more Android style guide and iOS style guide. Some time ago Android didn’t really have a style guide. Now we see a positive change with clearly defined vision of the interaction with the mobile device. Both style guides go in depth about the gui elements and their intended purposes.

Let’s discuss Jakob Nielsen’s 10 usability heuristics. When you read these guidelines you probably nod and think “yes, that’s right”, but the problem is with execution because there are no concrete examples and correct solutions for them. I will try an example which illustrates that guideline is really about. Most of examples are from my experience while working on the enterprise application. I’ve spotted similar problems before I have heard about Nielsen’s heuristics so you probably might be already familiar with them even if you don’t know them.

1. Visibility of system status

The system should always keep users informed about what is going on, through appropriate feedback within reasonable time.

Imagine a form with a button at the end. Once you’ve filled all fields in the form you click the save button and

… nothing happens.

… you are redirected to some other page in the system.

… save button disappears and Ok button shows up.

You might have seen systems like this before. Each share the same problem. System status, concretely status of the operation is not shown. It would be much better if user sees notification message about successful operation. If action takes time then immediately after save button has been clicked some kind of in progress bar should be shown. These little things communicate to user that something actually is happening.

I had countless of situation where I was unsure whether I clicked the button or not. Then I clicked it again and after a while I could get an error because of operation in progress. Sounds familiar?

In short: React to user actions, show notifications upon success and error, show progress bars for time-consuming actions.

2. Match between system and the real world

The system should speak the users’ language, with words, phrases and concepts familiar to the user, rather than system-oriented terms. Follow real-world conventions, making information appear in a natural and logical order.

I would argue here and take this guildeline further. I would say that system should be oriented in real-world nomenclature so that interface and real-world convetions are natural consequence of whole approach to product development.

However to give an example. Let’s say that form from previous example was for opening a bank account. Let’s say that operation failed and we do see notification.

Instead of notification with generic message Operation has failed it’s much better to see We couldn’t process your account opening request because …

Giving the reason of the failure is not the point in this case, but using a words of the domain is.

3. User control and freedom

Users often choose system functions by mistake and will need a clearly marked “emergency exit” to leave the unwanted state without having to go through an extended dialogue. Support undo and redo.

This guideline acutally says exactly what we should do. However Undo and Redo is not always a valid options. Having a Cancel everywhere is a good idea. Closing modal windows with Escape key also. As well as with usual close icon. In the last system I’ve been working on modals could be discarded in every way mentioned. User should be familar with majority of them.

4. Consistency and standards

Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform conventions

This is very important guideline which can be breached easily when there are no clear standards and there are many developers implementing the system. The simplest example is the name of the save button. Is Add the same as Save? These inconsistencies were a commonly reported errors.

Placement is very important as well. If you have different actions on one page and similar set of actions on other page but in different order and/or different location relative to the content then user might be confused.

5. Error prevention

Even better than good error messages is a careful design which prevents a problem from occurring in the first place. Either eliminate error-prone conditions or check for them and present users with a confirmation option before they commit to the action.

Very good example is form validation. Obviosuly you need to check data at the backend so you already have one validation there. One might start questioning validation done at form level, but it greatly increases usability and decreases amount of errors user can see. Validating dynamically each form field is a right way to go. Once a user finishes with one field it should be validated and marked as valid or invalid (remember first rule?). If it’s invalid then message should be shown. Even better message with correct example.

6. Recognition rather than recall

Minimize the user’s memory load by making objects, actions, and options visible. The user should not have to remember information from one part of the dialogue to another. Instructions for use of the system should be visible or easily retrievable whenever appropriate.

I haven’t run into issues with the first part. It is a common sense to make a information visible if it is required to proceed later. I can however give a practical advice on the instructions.

Following standard conventions it might a good idea to put a small icon symbolising help for example question mark which when hovered displays instructions about how to proceed further. It is particularly good because instructions are then focused on the problem, they are always close to origin of the problem. Also the fact that they are hidden until needed is also good because otherwise user could be overwhelmed of information.

7. Flexibility and efficiency of use

Accelerators — unseen by the novice user — may often speed up the interaction for the expert user such that the system can cater to both inexperienced and experienced users. Allow users to tailor frequent actions.

I had no previous experience with that one. It is definitely a good idea. Shortcuts to everything is the reason I love IntellJ so much. However there is no easy way to help novice user advance on higher level. They must want to do that by themselves and so they will look at documentation for shortcuts.

In my point of view, this guideline is like a cherry on top. There are more urgent issuses to deal with first. Making navigation faster is a easy when there is a good navigation in the first place.

8. Aesthetic and minimalist design

Dialogues should not contain information which is irrelevant or rarely needed. Every extra unit of information in a dialogue competes with the relevant units of information and diminishes their relative visibility.

Nightmare of every enterprise application. How to cut down on all this required information? If user needs to fill 100 fields because business say so then there is no way around limiting these 100 fields. However there is a way of making it seems like less. Multipage forms are a good way to go. If we can divide these fields into related groups and in 99.99% it is possible then it is much better to ask user just for a bit of information and then advancing for the next step. Again it is important to remember about 1. and showing how many steps are ahead.

9. Help users recognize, diagnose, and recover from errors

Error messages should be expressed in plain language (no codes), precisely indicate the problem, and constructively suggest a solution.

I have already gave an example of this in 2. but then solution wasn’t the point. Look at the difference between these two messages:

1. You cannot order this item.
2. You cannot order this item because it is out of stock.

What are your thoughts on the first? Mine are like “Why? Am I not good enough for you or what?”

Second is better however it can be even more better. What is missing? Suggestion for a solution. How about something like:

“You cannot order this item because it is out of stock. Click here to be notified when item is back in stock”.

Now you have it all.

10. Help and documentation

Even though it is better if the system can be used without documentation, it may be necessary to provide help and documentation. Any such information should be easy to search, focused on the user’s task, list concrete steps to be carried out, and not be too large.

Writing a good documentation is a tough task and no one wants to do it. If it has to be done then it is done by the least experienced team member whos time is least expensive. That’s the reason why most of the documentation really sucks.

Using contextual help like that from 6. might a good idea. In that way there is no one big documentation but there is always a contextual documentation in hands reach.

Summary

At this point I am pretty sure that you have run across at least one of these issues and you knew what you could do. Knowing these guidelines might make you more consious about the problems. There are very easy solutions to most of them. In most cases there are already open source frameworks and collections of other components which can be used. It just requires a little more effort. It is something like Pareto rule “20% more effort gives 80% better usability”. Even though it’s not time consuming it is often something that it is done at the end when deadlines are already breached or close by and bug reports are already coming in so it might be hard to put that additional effort. At least that’s from my experience.