Sometimes when browsing issues on Jira we want to make quick notes, add some TODOs, create draft of an comment, but we don’t want to share everything with others. Unfortunately everything that we input on issue is publicly visible with others on Jira.

We wanted to change that and add user some space where one can add some quick personal notes about issues. That lead us to our idea for My Issue Notes app.

What it does

My Issue Notes allow users to create their personal notes on Jira issues. Those notes, unlike other fields on Jira, are visible only for users that create them, thus allow them to quickly add their personal todo lists, thoughts about issue, temporary drafts of comments, etc. Each created note can be easily edited or deleted.

Additionally each note can be published as public comment with a click of a button. This gives user ability to create comment drafts as a notes and publish it later. Despite on what computer or browser he/she created that note - notes are saved on Jira issues and can be accessed and published from other devices!

Notes accepts standard markdown syntax. It even keeps proper formatting when publishing them as comments!

How we built it

We built our app using Forge and Jira Cloud API. We tried to use best of what Forge and Jira Cloud could give. With Forge API we build UI and business logic for an app, while Jira Cloud API was used to help us store and retrieve data for issue notes.

With the help of the TypeScript we managed to develop maintainable code base for an app, that we want to publish in future to Atlassian Marketplace.

Challenges we ran into

It was our second Jira Cloud + Forge app, so we were already familiar with things that we can and can’t do in this environment. This helped us a lot to avoid problems on early design stage.

When we get to the developing phase everything was going smooth. Until we get to the publishing notes as comments part. We found out that v3 version of Jira Cloud endpoint for creating comments accepts only Atlassian Document Format - document format stored in JSON. It was totally not compatible with pure string markdown format that we were using in notes.

So we search a little to find out easiest solution for this case, and we found it! At least it looked like so. Version 2 of this endpoit accepted plain string, so we were full of hope that it would also recognize markdown syntax. But nope - it was plain text only. Anyway, it was endpoint from old version of API, so it could be used as a temporary solution.

We wanted proper solution for this problem, so we get back to v3 endpoint. Unfortunately there’s no direct Markdown → ADF converters, but we were able to find neat Markdown-it library, which helped us tokenize markdown text. With that tokens it was relatively easy to quickly develop converter that would convert Markdown tokens to Atlassian Document Format JSON.

And that we managed to provide this functionality in our current version of app. It definitely need some more care and tweaks, but from our initial tests it was working flawless!

We also got some minor issues with buttons. Unfortunately buttons in standard Forge UI cannot by styled in any way nor we could add any icons to them. So we end up with four gray buttons for saving, deleting, cancelling and help in a row. It was a bad UI choice, as they were not easily recognizable, especially saving.

But luckily we came up with an idea: emojis❗ We added some of them to buttons labels (✔ 🗙 🗑️ 💬 📝) and suddenly each button was easily recognizable.

Accomplishments that we're proud of

We are happy about time that we need to implement fully fledged app to Jira Cloud. Even with some issues with Markdown to Atlassian Document Format converter, we managed to build our app from scratch in couple of days.

What we learned

Quick app development and quick problem solving! We managed to design an app and estimate time to ship all its features that we wanted in given deadline.

Additionally with this being our second Jira Cloud and Forge app we learned a lot about these technologies, so we looking forward to develop some more apps for Jira Cloud in Forge. 😊

What's next for Absence Tracker

We want to expand on some ideas that we had while developing our app.

First of all we want to add user an ability to create multiple notes per issue. This would help him track multiple ideas on issue without needing to keep them all in one note.

We also want to expand on idea about sharing notes with others. Currently its only available by publishing it as comment, but we are seeing neat feature in collaborating on notes with other selected users.

At the end we also want to add some panel, where user can browse and find all his notes.

And just like our other Forge app, we are looking forward to get Forge out of beta and share our work with other Jira users!

Share this project: