Getting started

In this tutorial, you’ll learn how to use the External Assets Platform in Jira. To do this, you’ll configure Jira to use the external asset platform custom field, add assets using the REST API, and create an app that uses the asset issue panel module to display an iframe in the asset panel of an issue.

What you'll need

• A running web server serving your app (we will describe what you need to serve shortly), or use ngrok to serve your locally running app.
• curl or postman or a similar tool to perform REST API calls.
• Create a Jira API Token and store it somewhere safe. Follow this tutorial to learn how to create one. You will use this for curl commands in this tutorial.
• A modern web browser.

Get an Atlassian Cloud instance

For this guide, you'll set up and use a new Atlassian Cloud developer instance. Feel free to use your own instance instead, but don't use a production site.

1. Follow the Set up your development environment steps in Jira platform Getting started guide.
2. Next, create a Service Desk project, click on Create Project icon on the top-right corner and choose Company-managed project.
3. On the next page, click Change Template.
4. Choose a service desk template. For this tutorial, use IT Service Desk.

Set up your external asset platform custom field

Now that you have an Atlassian Cloud instance, the next step is to add the custom field that is used for assets.

1. Follow the steps in Create a custom field to create a custom field. When it prompts you to Select a Field type, click All from the left panel and then choose the External asset platform field (not to be confused with the Assets Objects field).
2. Name your field whatever you want and click Create. In this guide, it will be named Assets.
3. Select all Service Desk-related screens. These are the ones with names prefixed by SD:. For example, SD: Jira Service Desk Screen.
4. Click Update at the bottom. On the next page, you'll see the Assets field amongst the other fields.
5. Click on the Jira icon at the top left corner to get back to the browse projects page.
6. Open the service desk project.
7. Go to the Queues from the left side panel, then open the issue called What am I looking at?. Alternatively, you can use any other issue you see.
8. On the right hand panel of the issue view, you'll see the list of fields. Locate the Assets field.
9. Click Link asset, then on the panel that opens, click Link asset again.

You've now added the assets field to Jira but it's empty. In the next section, you'll add some assets.

Add assets via the REST endpoint

In this section, you'll create assets via the assets REST API. The procedure below uses curl to send requests, but feel free to use your own REST client.

1. Make the request shown below. It will create one asset using the asset PUT Endpoint:

   1
   2
   $ curl -X PUT \
     https://${YOUR_ATLASSIAN_DOMAIN}.atlassian.net/rest/assetapi/asset \
     -H 'Content-Type: application/json' \
     -H 'cache-control: no-cache' \
     -d '{
       "origin": {
           "appKey": "my-app",
           "originId": "randomoriginid"
       },
       "label": {
           "value": "iPad 12 pro"
       }
   }'
   --user ${USERNAME}@atlassian.com:${TOKEN}
   

   You should see an output similar to this:

   1
   2
   {
     "origin": {
       "appKey": "my-app",
       "originId": "randomoriginid"
     },
     "label": {
       "value": "iPad 12 pro"
     },
     "fields": []
   }
   

2. Navigate to the issue view again. Open the Assets field and try searching one more time. You should see the asset we added the list.

   

Create an app - Create and deploy a web application

You have added the assets custom field and added an asset to Jira via the REST API. Next, you'll create an app to show the asset in Jira. The asset will be displayed in an iframe in the Assets panel of an issue.

The most basic app consists of an HTML page and the app descriptor. In this section, you'll create the web application for the HTML page.

1. Install nodejs and npm. This guide uses version 10.15.

2. Install http-server globally in nodejs:

   1
   2
   $ npm install -g http-server
   

3. Create a new directory to serve the sample HTML page that will be used as the iframe (note, the module descriptor will also be served from this directory):

   1
   2
   $ mkdir ${HOME}/public/my-app
   

4. Create a sample HTML file for the iframe:

   1
   2
   $ vim sample_iframe.html
   

5. Add the following content to the file and save it:

   1
   2
   <!DOCTYPE html>
   <html lang="en">
   <head>
     <link rel="stylesheet" href="https://unpkg.com/@atlaskit/css-reset@2.0.0/dist/bundle.css" media="all">
     <script src="https://connect-cdn.atl-paas.net/all.js" async></script>
   </head>
   <body>
     <section id="content" class="ac-content">
       <h1>Welcome to my app!</h1>
       <p id="appKey"></p>
       <p id="originId"></p>
     </section>
     <script type="text/javascript">
       const urlParams = new URLSearchParams(window.location.search);
       const appKey = urlParams.get('appKey');
       const originId = urlParams.get('originId');
       document.getElementById("appKey").textContent = `The App Key Is: ${appKey}`;
       document.getElementById("originId").textContent = `The Origin Id Is: ${originId}`;
     </script>
   </body>
   </html>
   

6. Serve the newly created page:

   1
   2
   $ http-server -p 8000
   

   This will start a webserver running on localhost port 8000.

7. Create an ngrok tunnel to your local server:

   1
   2
   $ ngrok http 8000
   

   You’ll see output in your terminal similar to what’s shown below.

8. Use the https URL from the output above and construct a URL for your sample page, as shown below:

1
2
https://${NGROK_SUBDOMAIN}.ngrok.io/sample_iframe.html?appKey=my-app&originId=123

1. Enter the URL in your browser and you'll see output similar the screenshot below.

Create an app - Create a module descriptor

Now that you have created a web application, the next part of creating an app is to create the module descriptor. The module descriptor will provide information about our app and, most importantly, it provides the callback URL that will fetch the iframe to be displayed in the asset panel.

1. Create a file named atlassian-connect.json in your app's directory (the same directory that you created the HTML file in):

1
2
$ vim atlassian-connect.json

1. Add the following JSON to the new file and replace the details with your own. This is just a sample descriptor, which you should not use in production:

1
2
{
  "key": "my-app",
  "name": "My App",
  "description": "My asset Management app",
  "baseUrl": "${YOUR_BASE_URL}",
  "authentication": {
    "type": "none"
  },
  "modules": {
    "assetPanels": [
      {
        "key": "my-app",
        "url": "/sample_iframe.html?appKey={asset.appKey}&originId={asset.originId}",
        "name": {
          "value": "Asset panel"
        }
      }
    ]
  }
}

1. The module descriptor is now available via the ngrok tunnel:

1
2
https://${NGROK_SUBDOMAIN}.ngrok.io/connect_module.json

Install your app

You've created the app. Now you just need to install it.

1. Follow the Install and test your app step in Atlassian Connect's Getting started.

2. Open the issue view again and add the asset you created.

3. Click the chevron to expand the panel.

The asset that you added via the REST API should show in the iframe provided by the app you created.

Congratulations, you’ve completed this guide. You should now know how to use the External Assets Platform in Jira. You can use the app you’ve created in this guide to add your own logic and implement your own asset management flow.

Extra reading

1. External Assets Platform rest API
2. Integrating with Jira Cloud (provides an overview of Atlassian Connect)
3. External Assets Platform Connect module

Notes

• If your app is whitelisted in our list of apps, once you install your app, the Assets custom field will be created automatically. Also your icon will be displayed next to the asset's label in the assets field.