Every developer has the project. The one that began with an easy concept, but becomes a game of frustrations and ups and downs of technical issues, experiments with design, and learning to live with the peculiarities of the platform that you were to be working with. In my case, such undertaking was the migration of my Data Center app, ASiC Viewer, to the Atlassian Cloud.
Here is the narrative of that trip – a tale of struggling with UI Kit 2, authentication circles, and searching in vain after that native Jira feel.
The Issue: The lack of a Jira capability to recognize/read signatures from ASiC containers
Digital signatures are not only convenient in Europe but a legal obligation. Contracts, official submissions, and legal documents today are often handled in formats such as BDOC, EDOC, ASICS, and others. To check a signature, our users were forced to:
- Download the attachment.
- Open desktop application or use online validation platform.
- Upload the file there.
- Analyze the results.
It was cumbersome, bulky and interrupted the process. My Data Center application fixed this by allowing users to see the signatures in Jira. It worked beautifully. However, as Atlassian drove a definite “Cloud-first” strategy, I realized I had to “move” our plugin to Jira Cloud.
The Cloud Imperative: Not Just a Port
Initially, I believed that I would simply be able to port our Java application to the Cloud. I was wrong. Forge is a totally different animal. You are no longer dropping code into Jira, you are creating a sandboxed web app that communicates with Jira through APIs. It was a complete rewrite – Java to Node.js and React. This wasn’t just a port, I had to start from the very beginning.
UI/UX Odyssey: Pursuing the UIKit 2: The Jira Feel
Phase 1: The “Broken” Table
My initial effort of creating good attachment list was a mess. Columns didn’t line up. The Stack and Inline components of UI Kit 2 are not designed to work in hard tables – any attempt to make them do so caused everything to break.
Phase 2: The Over-engineered Accordion.
Then I experimented with an interactive accordion: a row is clicked, and one can expand it inline to read the details. Modern, but disruptive. The layout of the page was moved over-the-top and in order to just check the signature, it felt clunky.
Phase 3: Mimic, Don’t Reinvent
Finally, I asked myself: “How lists look originally in Jira Cloud? ” I abandoned my experiments and reproduced the well-known pattern. The component that came to the rescue of us was the Popup component which was lightweight, contextual and fast. On a single click of the View Signatures button, a nice pop-up was brought up attached to the button.
Agonizing with Forge: The notorious Authentication Loop
Every Forge developer will eventually bump into NEEDS_AUTHENTICATION_ERR. I was no exception. My application was properly using the secure asUser() API calls, but I kept getting the user consent prompt over and over again.
INFO 13:06:47.679 49458f07-ce56-4473-9d22-afa224615b33 [asic-cloud] handler route { action: 'getIssueAttachments', payloadKeys: [ 'issueId' ] }
INFO 13:06:47.679 49458f07-ce56-4473-9d22-afa224615b33 [asic-cloud] doGetIssueAttachments { issueId: '10000' }
INFO 13:06:47.680 49458f07-ce56-4473-9d22-afa224615b33 [asic-cloud] fetchIssueAttachmentsAsUser start { issueId: '10000' }
ERROR 13:06:47.998 49458f07-ce56-4473-9d22-afa224615b33 handler failed [NEEDS_AUTHENTICATION_ERR: Authentication Required] {
status: 401,
serviceKey: 'atlassian-token-service-key',
options: undefined
}
ERROR 13:06:47.998 49458f07-ce56-4473-9d22-afa224615b33 [NEEDS_AUTHENTICATION_ERR: Authentication Required] {
status: 401,
serviceKey: 'atlassian-token-service-key',
options: undefined
}
I chased every rabbit hole. I tried complex workarounds, manually catching and throwing 401 errors, believing it was a logic bug. Religiously repeated the clean uninstall and reinstall process, thinking there was a conflict between my local forge tunnel and the deployed development environment. Nothing worked.
The actual answer was simple and buried in the Forge permission scheme.
The problem wasn’t my code—it was manifest.yml. In my attempt to follow the “Principle of Least Privilege,” I had been too aggressive. I was only using the most granular scopes, like read:attachment:jira. It turns out that for the user consent flow to authorize and remember decisions across the app, a slightly broader scope was required.
permissions:
scopes:
- 'read:jira-work' # The key to solving the loop
- 'read:attachment:jira'
- 'read:jira-user'
Lessons Learned in the Forge
This trip was not only a code writing exercise, but also an exercise in learning a new way of developing Atlassian apps. Here are my key takeaways:
- Accept the Limitations: The limitations that UI Kit 2 has are not bugs; they are features that provide security, consistency and accessibility. Rather than struggling against the framework, application of its components (such as Popup and Grid) to their intended purpose will give the best results.
- The Compass is the User Feeling: It was the feeling that the design was a bit broken, or the feeling that the design was not quite right, which led me. The process of endless repetition of spacing, alignment, and micro-interactions is what makes a functional tool a professional product.
- Replicate the Native UI: Users are already experts in using Jira.
The outcome is the ASiC Viewer Cloud, which is an application that I am proud of. It is quick, safe and, above all, it seems to be part of Jira.
You can check out the final app on the Atlassian Marketplace here.
