Building an Atlassian Connect add-on

Avisi werknemer

Avisi werknemer

Published: 29 July, 2014

As Atlassian experts, we're invested in keeping up to speed with all the hip new things Atlassian delivers. The Connect platform is certainly one of those hip new things. But it's more than that... actually, it just might change the way we build all our plugins in the future. Therefore, we are currently looking into migrating our plugins to this new platform. These are our findings...

Because Connect is mainly about HTTP requests going back and forth (with a bunch of authentication, logging and other magic around it) you can choose the stack you want to develop on. The good guys at Atlassian offer two pre-defined stacks so you can get going real fast: one is based on the Play! framework and the other on express.

An Atlassian Connect definition:
Originally built as a solution to the difficulty of making plugins for the OnDemand platform, you can use the Atlassian Connect framework to build add-ons for Atlassian applications like JIRA, Confluence, and HipChat. An add-on could be an integration with another existing service, new features for the Atlassian application, or even a new product that runs within the Atlassian application.

Simply put, Atlassian Connect add-ons are web applications. They operate remotely over HTTP and can be written with any programming language and web framework.

Fundamentally, Atlassian Connect add-ons have three major capabilities:

  1. Inserting content in certain defined areas of the Atlassian application's UI.
  2. Making calls to the Atlassian application's REST API.
  3. Listening and responding to WebHooks fired by the Atlassian application.

Getting started
So now that we know what Connect is about, we will cover the absolute basics you will need to help you get started with your own plugin. In this case, the absolute basics would be to create a simple HTML page that displays the famous words: Hello World! 

(This is based on the getting started guide from the Connect docs).

1. Create your add-on descriptor, a JSON file that describes the add-on to the Atlassian application (only JIRA, Confluence and HipChat are supported at the time of writing).

{
"name": "Hello World",
"description": "Atlassian Connect add-on",
"key": "com.example.myaddon",
"baseUrl": "http://localhost:8000",
"vendor": {
"name": "Example, Inc.",
"url": "http://example.com"
},
"authentication": {
"type": "none"
},
"version": "1.0",
"modules": {
"generalPages": [
{
"url": "/helloworld.html",
"key": "hello-world",
"name": {
"value": "Greeting"
}
}
]
}
}

2. Create an awesome web page:

<!DOCTYPE html>
<html lang="en">
<head>
<script src="https://www.avisi.nl//HOSTNAME:PORT/CONTEXT/atlassian-connect/all.js" type="text/javascript"></script>
</head>
<body>
<div>
<h1>Hello World!</h1>
</div>
</body>
</html>

Make sure to replace these values to suit your environment:

  • HOSTNAME: The hostname for the Atlassian application.
  • PORT: The port number on which the Atlassian application serves its web interface.
  • CONTEXT: The application context for the application, such as /jira or /confluence.

3. Start your add-on.
Done with coding.... what, already? Yeah! it's that simple.
For the server side we'll use a simple one that ships with Python.

python -m SimpleHTTPServer 8000

Make sure that the following files are available:

http://localhost:8000/atlassian-connect.json
http://localhost:8000/helloworld.html

You're almost done, hang in there!

4. Start the target Atlassian application with the SDK.
For Jira:

atlas-run-standalone --product jira --version 6.3-OD-03-012 --bundled-plugins com.atlassian.plugins:atlassian-connect-plugin:1.0.2,com.atlassian.jwt:jwt-plugin:1.0.0,com.atlassian.bundles:json-schema-validator-atlassian-bundle:1.0-m0 --jvmargs -Datlassian.upm.on.demand=true

For Confluence:

atlas-run-standalone --product confluence --version 5.5-OD-23-004 --bundled-plugins com.atlassian.plugins:atlassian-connect-plugin:1.0.2,com.atlassian.jwt:jwt-plugin:1.0.0,com.atlassian.bundles:json-schema-validator-atlassian-bundle:1.0-m0 --jvmargs -Datlassian.upm.on.demand=true

You made it all the way here, there is just one more step!

5. Register your freshly made add-on in the target application.

  1. Visit the target application we started in step 4.
  2. Choose the Manage add-ons option from the side menu.
  3. Click the Upload Add-on link
  4. Enter the URL of the hosted location of your add-on descriptor that we created in step 3. In this example, the URL is similar to the following: http://localhost:8000/atlassian-connect.json.
  5. Press Upload. The application will display the 'Installed and ready to go' dialog when installation is complete.

After step 5 you should see a 'Greetings' menu item. Congratulations, you're now a Connect add-on ninja!

Now, it sure is great to have build your very own add-on, but it's nothing but a static page after all... so what's next?

For most Atlassian Connect add-ons, the next step would be to add code that relies on the Atlassian application REST APIs. This requires implementing the authentication used between Atlassian applications and Atlassian Connect add-ons.

The issues we ran into
Now this is the part where it gets really interesting and sadly, this is where most of the awesomeness stops. We noticed that throughout the building process there are quite a lot of things missing still, preventing us from migrating our plugins in their entirety.

Most of our plugins need the current state of the (REST) API's within Confluence or JIRA. This is unfortunately a showstopper since we need those resources and they are not always available. The most important one in our case was the absence of user related REST resources.

Next to the API related issues we came across another showstopper which we didn't find a workaround for. The specific case was using a web-item to flag content, we'll use a simple comment for this example. The following problems arose:

  1. Getting the ID from the comment you want to flag.
  2. Changing the text of the flag link to 'flagged' once clicked, which requires dom manipulation which you just can't do.

We also wanted to create an admin screen to manage which users (and groups of users) would receive a notification (e.g an e-mail). Since the creation of an admin screen is dead simple we thought 'oh well, this should be a breeze'. But then came another bump in the road: there is no user REST resource (at the time of writing at least). So since we're missing functionality on both sides (front- and backend) were out of luck and we just have to wait until this much needed functionality becomes available.

Conclusion
To close I would like to state the following: The Atlassian connect platform is an awesome next step for developing kick ass plugins. It offers a good base which can still be improved a whole lot, but the potential is certainly there! As long as we as developers contribute to making the platform even more awesome (and with a little help from Atlassian of course) I predict a bright future for the plugins and the platform as a whole.

We would love for you to share your experiences with developing new add-ons or with migrations to Connect, so please don't hesitate to comment or to get in touch with us!

Did you enjoy reading?

Share this blog with your audience!