Co-authored by Johnny Niu
We tasked a new Atlassian engineer with rebuilding a Connect app on Forge. In this post, we'll share what happened – bumps and all.
Atlassian Labs apps are personal projects built by Atlassians, available to install in the Marketplace. The program gets useful solutions into the hands of customers, but there's also a secondary benefit: putting Atlassians in the shoes of app builders. Building (or in this case, rebuilding) a Marketplace app forces us to confront the rough edges and blockers, and it helps us prioritize improvements. We'll detail a few of those learnings here, and what we're doing to address them.
For Marketplace Partners considering moving a Connect app to Forge, we know the stakes are high. That's why it's so important to test, learn, and improve the process, to ensure that real-world app developers have a smooth and pleasant journey.
Building the pathway to Forge
Since the early days, we knew it would be important to provide a way for existing Connect apps to adopt Forge – we want everyone who wants to take advantage of Forge to be able to do so. The Forge team is made up of multiple squads, and ours is responsible for building this migration pathway.
For developers who want to move a Connect app to Forge, it's essential that rebuilding on Forge doesn't mean creating a duplicate listing or abandoning existing reviews and installs. In the future, we plan to enable intermediary states, reducing the amount of rebuilding necessary.
Several partners have already completed the process of moving an app to Forge, but it's still early days. As we open the gates for more developers to transition apps from Connect to Forge, we have to thoroughly test the process ourselves.
So, we decided to move an Atlassian Labs app, built on Connect, to Forge. We considered several candidates before choosing Who's Looking for Jira Cloud, an app that displays the name and avatar of users who are viewing the same issue in real time. We chose this app for two reasons: 1) it has a sizable install base at 3,000+ users, and 2) it's a relatively simple app. We chose a simple app to learn as much as possible as quickly as possible, but as you'll see, we still encountered some roadblocks.
We divided the project into three phases:
- Analyze the Connect version of the app and create a set of criteria for equivalent functionality on Forge.
- Rebuild Who's Looking on Forge, reproducing the features and functionality of the original app.
- Transfer the Marketplace listing from the Connect version of the app to the Forge version.
A look inside Who’s Looking
Before we could recreate Who's Looking on Forge, we needed to take stock of the existing Connect app. Who's Looking was built by Atlassian engineer Robin Fernandes, and it's hosted on Heroku. The original app uses Postgres for installation metadata storage and Redis for transient storage of viewer-to-issue maps. The backend is written in Java using the Play Framework.
Johnny Niu led the project to transition Who's Looking to Forge, along with Richa Agrawal. At the time, Johnny was new to the Forge team. His fresh perspective helped bring us closer to recreating the experience an external developer would have when going through this process. We’re mindful that internal resources aren't available to most app developers, and although Johnny did have team knowledge to lean on, publicly available resources like the community forum and docs were used for research and troubleshooting.
The team kicked things off by meeting with Robin to understand the basic functions of Who's Looking. We summarized the existing app's functionality to create a list of requirements for the Forge version, boiled down to three main specifications:
- As a user, when I open a Jira issue, then click Who's Looking, I can see list of users (including name and avatar) who currently have the same issue open.
- As a user, when another user opens the same Jira issue page, that user should be shown on my Who's Looking list. When another user closes the Jira issue page, that user should disappear from my Who's Looking list.
- When open, the Who's Looking list should update every 20 seconds.
Finally, we created a rubric to compare the Connect version with the Forge version across 6 categories: functionality, user experience, security, scalability and performance, operation, and maintainability. We used this rubric to measure how successfully the Forge app recreated the capabilities of the Connect app.
When it comes to successfully reproducing the app on Forge, we aim for functional parity: a user or developer of the original app would reasonably agree that the Forge version of the app provides the same feature set. The look and feel of the app may vary slightly and still be considered a successful rebuild, as long as the app works the same way.
What changed when we moved to Forge?
Now we get to the part of the story I'm sure you're most keen to hear. What was it like to rebuild the app on Forge?
There were a few areas where we encountered differences in behavior between Connect and Forge that challenged us to come up with creative solutions. We'll list a few of those – and the solutions we put in place – below.
Capturing issue view events
One challenge we uncovered was related to differences in how issue view events are captured. In Connect, the script can run when a user lands on the issue page (a behavior specific to issue glances). In Forge, the user needs to click on the issue glance panel in order to show up as a viewer. Because of this difference, the Forge version of the app offers slightly less real-time accuracy than the Connect version. In the Forge app, issue viewers are registered in two ways. Users who open the issue glance are registered via API request (every 20 seconds). Users who don't open the issue glance are registered via issue-viewed event (only once).
While users of the Who's Looking app might not notice the slight disparity, this was the sort of roadblock we set out to identify with this project. We're tracking the issue via FRGE-566. This project is a public issue tracker where members of the community can submit blockers, bugs, and feature requests as well.
Keeping the viewer list up to date
Another feature that required a different approach was removing a viewer once they'd left the page. The Connect app uses polling to refresh the views if the user is still on the page. The client sends an AJAX call to the Heroku backend and updates the value stored in the cache. It repeatedly polls the server to check whether a user is still on the issue page.
The Forge version of the app decides if a user is still watching the page based on the last view time on the issue. It calls storage on an interval to "renew" the expiry time of the viewer.
What we gained with Forge
There were some features Forge offered "for free" that made the building and operationalizing the app easier than it had been on Connect.
The most obvious of these benefits was infrastructure. With Forge, we no longer needed to maintain our own hosting on Heroku, which cost about USD $440/month. While the cost wasn't unmanageable, it was nevertheless something we were happy to offload, and hosting on Forge made Who's Looking more sustainable for our team to support. As an added bonus, the app is now fully contained within the Atlassian cloud, and no data is egressed to external web services.
Another advantage was the ease of getting started. We built the first iteration of the app using UI kit, which was fast to use and made it easy to fetch and display information like a user's details and avatar. Later, when we added more complex custom logic, we found custom UI was a better fit for our use case. The takeaway was that UI kit is a powerful starting point if you need a minimal UI, but it's nice to be able to switch to custom UI if a more complicated need arises.
Finally, Forge provided a few useful security features that would have required greater effort to set up in Connect. Users should only be able to access Who's Looking for issues they have access to – not other issues or tenants. In Connect, it was necessary to implement permission management to prevent users from accessing other Who's Looking users or issues lists from a remote server. Forge provides the ability to make requests on behalf of the user with the asUser API out of the box.
Going live in the Marketplace
At this point, we had Who's Looking running on Forge, but there was still one important bridge we needed to cross: replacing the Connect version of the app in the Marketplace. The Marketplace Listing for the app still pointed to the Connect version. After completing an internal security review, we published the Forge version of the app, replacing the Connect version. This process allows all existing customers to switch to the Forge version on their next upgrade, and all new customers going forward will install the Forge version.
Now, the Forge version of the app is live on our Marketplace listing. If you're curious about the step-by-step process, check out the docs on listing a Forge successor to a Connect app.
What we learned
In the end, we moved Who's Looking from Connect to Forge, but that was only part of our goal. We also identified areas where we can improve the experience for all developers building on Forge.
For example, we found that it would have been helpful to have more example apps that use custom UI. We're sharing this feedback internally to help our teams weigh this need against other priorities, using our first-hand experience to bring attention to pain points.
During the migration, we also ran into a bug that prevented the app system user from accessing the correct permissions for restricted resources, tracked here in a public ticket. We know that this issue impacted many partners as well, and we're happy to share that a fix was recently released.
One piece of advice the team wished we'd had was to do a performance assessment upfront. We ran into some friction when the app was limited by the 10 operations/second allowed by the Storage API. After completing our app migration, storage quotas and API limits have been increased, which should ease the challenges for future Forge developers.
Last but not least, differences in the issue view event behavior and storage required creative workarounds, and our solution was not quite as elegant as the Connect version of the app. Addressing all of the issues we raised won't happen overnight, but we made progress by identifying where we need to focus our efforts. We'll be working closely with the other squads that make up the Forge team to improve the pain points we've identified.
Conclusion
We've been working closely with a group of Marketplace Partners who are interested in moving Connect apps to Forge, and we've learned a great deal from their feedback. However, there's no substitute for going through the process ourselves.
In moving Who's Looking to Forge, we were able to reduce the amount of overhead needed to maintain and host the app, and we've upgraded the app's security posture. This benefits us as developers, as well as the 3,000+ customers who use the app.
We also identified areas for improvement. Our work now is to share these learnings across the Forge team and use them to help prioritize our roadmaps.
If you're interested in learning more about our team's work to build pathways between Connect and Forge, get in touch with us via the Community. Whether you have feedback to share about your own experience or want to take the first steps to move one of your own apps to Forge, we want to hear from you.