Atlassian is dedicated to helping teams build better software faster. We believe that every team deserves the best tools. And often, the best tool is the one that is custom-fit for you. So from very early on, we encouraged our customers to modify and enhance our applications using the Atlassian Plugins framework.
Many thousands of developers did, and a broad ecosystem of Atlassian Add-ons and Add-on developers was born. We helped developers share and customers discover Add-ons with the Atlassian Plugin Exchange.
More and more customers came to depend on these powerful additions, and businesses were born around many of them. In 2012, we launched the Atlassian Marketplace to make it simple for customers to purchase useful Add-ons and easy for Add-on developers to profit from their great work. Today hundreds of developers are building thriving business in the Atlassian Marketplace, selling add-ons to our 25,000 commercial customers, hundreds of thousands of teams and millions of developers all over the world.
Atlassian OnDemand is the cloud-hosted and Atlassian-managed version of the Atlassian product family. Introduced in 2011, OnDemand applications seem externally similar to a user, but they are fundamentally different, running on our custom-built platform and serving millions of users. Atlassian OnDemand is our fastest growing deployment option, and large numbers of our BTF customers first evaluate in OnDemand.
The additional demands of managing software at such scale mean that we need to significantly enhance the Add-on Framework to ensure stability and scalability. We need to bring Atlassian add-ons into the modern world of web services, to match OnDemand. And we need to decouple add-ons from the host application, making the host more robust and the add-on more resilient to change.
Atlassian OnDemand represents over 24,000 instances, and it’s growing fast. When you consider the size of Atlassian OnDemand’s customer base, its recurring monthly billing mode, the number of customers who evaluate there and its runaway growth we recognize it as a market that no add-on developer should ignore.
Enter Atlassian Connect
At AtlasCamp in Amsterdam, we officially introduced Atlassian Connect. Atlassian Connect is a new distributed add-on technology for developers to extend Jira, Confluence, and all our applications in a world where software runs wherever, whenever, and however. Completely re-thought and re-imagined, Atlassian Connect is powerful and protected enough for the scale of the Atlassian OnDemand platform. Atlassian Connect works using standard web protocols and APIs (HTTP, REST, etc.) and gives developers new choices of programming language and deployment options. Regardless of delivery model or location, Atlassian products can be extended with Atlassian Connect add-ons so developers are confident their applications can solve anyone’s business problem. With Atlassian Connect, you can customize your Atlassian products in powerful ways, enhance them with new capabilities and integrate them with other applications from around the web or inside a company.
What is Atlassian Connect?
- UI Integration Points – Insert content or surface features in dozens of different places in the application UI.
- Remote APIs – Use powerful remote REST APIs to get data from and manipulate the host application.
- Authentication – Using OAuth, authenticate the end-users of the host application without requiring their password or a separate account in your add-on.
- In-product Add-on Discovery – List your Atlassian Connect add-on in Atlassian Marketplace to make it easy for customers to discover it, right in their product.
- One-click Add-on Installation – Install and try an Atlassian Connect add-on with a single click inside a host application.
- Automatic Licensing – Use the Atlassian Licensing provider to ensure that customers are appropriately licensed. The license state is reported to you in every request and you can query each customer’s license as needed.
- Automatic Billing – Sell your Atlassian Connect add-on using Atlassian’s automatic subscription billing. Registering your add-on for sale and Atlassian will handle the billing, payment processing, and credit cards for our customers..
- Behind-the-firewall Communication Protocol (coming soon) – Make requests from your Atlassian Connect add-on to the host-application’s remote API, even when that API is not accessible over the public internet.
What is not in Atlassian Connect?
- Any access to the internal Java APIs.
- The ability to modify the host product’s DOM or override any of its components or actions.
- A hosting platform provided by Atlassian. Atlassian Connect authors can use any of the established providers like Heroku or AWS.
- A web container. You can bring your own stack and use any of the many modern web frameworks and web servers available today.
- Access to customers on secure internal networks, i.e., with no outbound internet access.
How it Works
Let’s start with your Add-on. Most basically, your add-on is a web application that displays content within or interacts with an Atlassian product. It could be an existing application or a new one you write from scratch. You can write it in any language, choose any web framework, and use any libraries you wish. You can bring your own database and host it wherever you like, including free starter PaaS or SaaS hosts. You can choose popular frameworks like Node, Play, Rails, or Django. But crucially, your app will communicate with an Atlassian host product entirely over HTTP, using our Add-on Framework and REST APIs.
Register your Add-on. Your add-on must “register” itself with each product instance in which it is to be used. That is accomplished by installing a plugin description, similar to the ones you might be familiar with from Atlassian Plugins 2. The add-on descriptor describes basic details about the add-on, such as where it is hosted, its authentication details and how it should be integrated into the target Atlassian application.
Request the right permissions. Your add-on must specify what types of access it intends to use. For example, can it delete an issue? Can it listen for an event? Can it use resources in the admin section of the API? You declare these needed permissions in your descriptor file.
Add elements to the application UI. Atlassian Connect describes many places in the host application UI in which an add-on can insert content. These are referred to as modules. Some examples are macros in Confluence pages, issue panels in Jira or even entire pages in any application. You describe the modules you wish to insert in your descriptor file, a location for each, and a URL from which your add-on will serve content. When an appropriate page is loaded, the iframe makes a call to your application, which returns HTML/CSS/JS.
Recognize the user. Because your add-on has been authenticated via OAuth, each request from the target application to your add-on contains the details about the user currently viewing that iframe. That allows you to serve the right context, respect necessary permissions and make other decisions based on the user’s identity.
Call the application’s remote API. Your add-on can call the target application’s API via REST, either on behalf of a given user using OAuth or, in some circumstances, as the add-on itself. You can use this to retrieve data (for example, to build a report) or to push information into the target application (for example, to create an issue in response to an external event).
Respond to the application’s web hooks. An add-on can register a webhook in the target application, so that your add-on receives a notification for certain events (for example, when a Jira issue is transitioned). The webhook payload includes information about the triggering event, allowing your add-on to take appropriate action.
List your add-on for sale in the Atlassian Marketplace. When you’re ready, you can make your Atlassian Connect add-on available in the Marketplace for sale to OnDemand users (and soon, to BTF instances as well). This works much as it does today for Plugins 2 add-ons, with the additional requirement of metadata related to OnDemand.
Respect add-on licensing. Every request from the target application to your add-on will contain the license state for that add-on in that instance. Your add-on can then respond appropriately, for example, by alerting the user, locking down functionality, or encouraging an upgrade.
What can you do with Atlassian Connect?
- Create and insert rich content into Confluence pages with Macros
- Insert rich content into Jira issues with tabs and panels
- Build and display reports based on Jira data
- Add sections to a user’s profile
- Add links to the application menus
- Build custom search results pages for sets of issues.
- Trigger actions based on changes in the host application
- Create links between Jira issues and remote entities
- Listen for changes and update state in an external system
- And many more….
How does this compare with Atlassian Plugins 2
Atlassian’s traditional, in-process plugins (known as Plugins 2) are not going away — they still represent a useful way to extend the product for behind the firewall customers. However, there are lots of advantages to Atlassian Connect, and we hope that lots of developers will adopt Atlassian Connect as the platform grows.
|Plugins 2||Atlassian Connect|
|Full access to the private (non-stable) internal Java API. Unexpected changes to these APIs can break add-ons.||Access to Remote REST APIs, which have public/private/experimental designations, are explicitly versioned, and have a generous deprecation policy|
|Full access to the DOM, CSS and JS. Misbehaving or conflicting add-ons can make a whole page inaccessible.||All UI integration points are explicitly sandboxed (usually inside an iframe)|
|Mixed code (yours, ours, other plugins) in the page. Product changes can break add-ons||Each add-on is isolated|
|Plugins depend on host product for libraries. Library upgrades can break plugins.||You can include the correct version of any libraries (e.g., JQuery or AUI) you might require.|
|Written in Java, all code run in-process.||Write in any language, choose any framework and use any library you want. Benefit from the combined efforts of the whole development community.|
|No direct database access.||Full powered database in your app, limited structured data store in the host product|
|No bounds on resource consumption.||Remote APIs are limited by design to protect the host app. The add-on can observe and fully control its own resource usage.|
|Vulnerable to security holes (XSS, XSRF, et al.)||Add-on sandboxing and the inherent cross-domain security model prevent exploits of the host product.|
|Local installation means developers can’t make changes to your plugin unless your customer (or Atlassian) is willing to update your add-on.||The only thing locally installed is the descriptor. Developers can change their remote service any time they want. Any updates to the descriptor can be pushed out automatically to all customers.|
|App restart required for many development changes.||Never restart the the host product app – your development inner loop is as fast as your chosen framework can make it.|
How can you help?
We depend on your feedback to ensure that Atlassian Connect continues to evolve in the right direction. Please be active in filing issues and requesting new capabilities. Join the Atlassian Connect discussion group and make your voice heard. Share with us what you want to build, and where you might be blocked. Get to know the Atlassian Connect team. Your involvement is crucial.
Atlassian Connect gives developers a powerful new way to enhance, extend and integrate with every Atlassian customer, regardless of whether they are running on our cloud platform or (soon) in a customer’s datacenter. The architecture laid out here will help decouple add-ons from the host product, freeing everyone to move at a faster pace without fear of incompatibiltiy. Over the next several years, Atlassian will be investing heavily in this platform and adding more remote APIs to make it even more powerful.
We believe that it will attract new developers, opening the doors to new programmers in every language community. It will give every developer the ability to build on the newest and best open-source technology available. And it opens the doors for much simpler integrations between Atlassian and the thousands of useful hosted services already available.
Atlassian Connect will spur a whole new era of growth for our Add-on Ecosystem and the businesses built on it. We’re incredibly excited about this revolution and we can’t wait to see what you build with these new tools.