Background
Atlassian has multiple products Jira. Confluence, Hipchat, Crucible etc. Jira is one of the widely used issues tracking system. In this post we are going to see how to create a plugin for Jira cloud. This would include creating a small demo app on your local and deploying it.
NOTE : I will be using words addon and plugin interchangeably. Both mean the same thing.
There are two different ways to create Atlassian addon -
- Atlassian Connect
- Plugins 2 framework
Plugins built with Atlassian Connect are meant to be run on Jira cloud instance where as plugins developer with Plugins2 framework are supposed to run in Jira server.
Jira cloud is the cloud version of Jira in which all you need is create an account and get started with Jira products where as Jira server is on premise counterpart where you run your own Jira Server with licenses. As you must have guessed running an onprem version gives you more flexibility in creating and developing the addons where as there are lot of constraints developing plugin for cloud jira instance since developer does not have control over the Jira system and everything happens remotely.
In this post we are going to see how to develop a simple app using Atlassian connect and deploy it in Jira cloud instance. All apps developed with this work remotely from your hosted server. Jira cloud makes it possible to integrate your hosted app with Jira. To an end user it will look like the plugin is running on Jira itself. That's the power of Atlassian connect framework. We will see these in details in a moment.
Step 1. Get an Atlassian Cloud instance
- Go to http://go.atlassian.com/cloud-dev and create your jira cloud instance for local plugin development.
- This is a common account and you get multiple products with it like Jira,Confluence etc.
- Note that there are various limitation on this cloud development account. So you cannot add lot of user and do stuff around it. You can read about these limitation in the same page.
- Go through the steps shown and get your account setup. For me it is - https://athakur.atlassian.net
- Next go to Jira. You should already be an administrator. You can do stuff like create project, add users etc.
- Now go to setting (cog icon at the top) > Add-ons > Manage add-ons
- Next select Manage add-ons page and then settings.
- Here enable Development mode
Your cloud jira instance is all setup for plugin deployment. We will come to this later. Let's go ahead and see plugin development.
Step 2. Setting up your local development environment
Now we are going to setup our local environment that is needed to develop out Jira cloud addon.
We will need 2 npm modules to be installed. This obviously expects nodejs and npm installed on your machine. If it's not please do that first.
As I mentioned before Jira cloud apps based in atlassian connect are hosted remotely on your own servers and Jira cloud just integrates it with the cloud instance. So we will need http-server to host our jira plugin on a server and we need ngrok to make our local traffic accessible to internet where the actual jira cloud instance is running (
https://athakur.atlassian.net in this case). ngrok helps tunnel local ports to public URLs and inspect traffic. You can just run the following commands to set up above modules -
sudo npm install -g http-server
sudo npm install -g ngrok
ngrok help
This should suffice out local setup for now. We will again come back to this when we develop our app and need deploying.
Step 3. Building your app
The most basic file that is needed is named - atlassian-connect.json. It is called plugin descriptor file. This basically tells Jira cloud instance what your plugin is, where it resides etc. This needs to be supplied to the cloud instance while configuring your Jira addon there which is why we need this file to be available over the internet. Hence the http-server and ngrok.
For now create a folder for your app. Let's call it helloworld-jira. Navigate to this folder and create a file called atlassian-connect.json with following content -
{
"name": "Hello World Jira",
"description": "Sample Atlassian Connect app",
"key": "com.osfg.helloworld",
"baseUrl": "https://<YOUR-APP-URL>",
"vendor": {
"name": "OSFG",
"url": "http://opensourceforgeeks.blogspot.in/"
},
"authentication": {
"type": "none"
},
"apiVersion": 1,
"modules": {
"generalPages": [
{
"url": "/helloworld.html",
"key": "hello-world",
"location": "system.top.navigation.bar",
"name": {
"value": "Welcome"
}
}
]
}
}
Couple of important points -
- baseUrl is the url where your app is hosted. We will supply our ngrok url here. So leave it like a placeholder for now.
- Other setting are really description about your plugin and your company
- Next we have generalPages section which defines which pages are part of your plugin. Here we are defining just one page. We also give it'e relative path (relative to base URL), location and a unique key.
- You can have multiple type of pages like -
- generalPages
- adminPages
- profilePages
- You can see more details on these - https://developer.atlassian.com/cloud/confluence/modules/page/
- Save your file with above contents.
Next let's create our actual app page helloworld.html we defined in the plugin descriptor file above. Create a file named
helloworld.html and add following content to it -
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" href="//aui-cdn.atlassian.com/aui-adg/5.9.12/css/aui.min.css" media="all">
</head>
<body>
<section id="content" class="ac-content">
<div class="aui-page-header">
<div class="aui-page-header-main">
<h1>Hello World from Jira!</h1>
</div>
</div>
</section>
<script id="connect-loader" data-options="sizeToParent:true;">
(function() {
var getUrlParam = function (param) {
var codedParam = (new RegExp(param + '=([^&]*)')).exec(window.location.search)[1];
return decodeURIComponent(codedParam);
};
var baseUrl = getUrlParam('xdm_e') + getUrlParam('cp');
var options = document.getElementById('connect-loader').getAttribute('data-options');
var script = document.createElement("script");
script.src = baseUrl + '/atlassian-connect/all.js';
if(options) {
script.setAttribute('data-options', options);
}
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>
You need a to understand couple of things from above html page before we proceed -
- AUI is Atlassian user interface. It gives you css to make your plugin look like standard Jira page. For more details refer - https://docs.atlassian.com/aui/
- Next is just a HTML content showing "Hello World from Jira!" as the content. We should be able to see this when we deploy our app in Cloud Jira instance.
- Next and last section is just adding a script to the DOM. This script is the Atlassian Connect JavaScript API. It simplifies client interactions with the Atlassian application. Eg making an XMLHttpRequest. This file can be found the URL -https://<yourhostname.atlassian.net>/atlassian-connect/all.js
- In my case it is https://athakur.atlassian.net/atlassian-connect/all.js. This should be present for all accounts.
- You can read more about javascript API - https://developer.atlassian.com/cloud/jira/platform/about-the-javascript-api/
Once you have saved this file your app is ready. Let's see how we can deploy this.
Step 4. Deploy your app
First step would be to host your app on the server. So go to helloworld-jira directory where our app resides and execute following command -
This should host your app on localhost domain on port 8000.
You can make sure your URLs are accessible -
- http://localhost:8000/atlassian-connect.json
- http://localhost:8000/helloworld.html
Next you need to make this accessible from internet and for this we will use ngrok we have already set up. Just run following command -
This will redirect our local traffic to internet. You should be able to see the URL that you can refer.
We are interested in https part of this URL -
You can again test your URLs with this to check your file is available. In my case they are -
- https://8d543c3d.ngrok.io/atlassian-connect.json
- https://8d543c3d.ngrok.io/helloworld.html
Once this is done you are pretty much all setup. You app is build and is accessible from the internet. Last thing that you do this update this url in the baseUrl field in the descriptor file where we left as placeholder. So your baseUrl is as follows -
- "baseUrl": "https://8d543c3d.ngrok.io/"
Now simply go to Manage Addons in the Jira cloud instance we created in Step1 and click on upload addon. Provide the URL to the atlassian-connect json. In my case it is -
- https://8d543c3d.ngrok.io/atlassian-connect.json
and your addon should get installed.
Now you can easily test out your addon. Just reload the page and you should see Welcome in the header section. You can click on it and you should see our content - "Hello world from Jira!"
Production Deployment
This was local deployment and testing. For production you need a proper webserver to host your App. You can use service like Heroku or AWS services like S3 , EC2 or Elastic beanstalk.
Related Links
