Installing an add-on

This document has Atlassian Cloud applications as its focus, but the steps also apply for Server and Data Center add-ons.

You can install an add-on with the UPM as follows. Note, these instructions were written for UPM version 2.14 or later.

  1. Log in to the Atlassian application interface as an admin or a system administrator. If you started the application with Atlassian's SDK, the  default username/password combination is admin/admin.
  2. Choose   > Add-ons from the menu. The Administration page will display.
  3. Choose the Manage add-ons option.
  4. Scroll to the page's bottom and click the Settings link. The Settings dialog will display. 
  5. Make sure the Private listings option is checked and click Apply.
  6. Scroll to the top of the page and click the Upload Add-on link.
  7. Enter the URL to the hosted location of your plugin descriptor. In this example, the URL is similar to the following:  http://localhost:8000/atlassian-plugin.xml. (If you are installing to a cloud site, the URL must be served from the Marketplace, and will look like https://marketplace.atlassian.com/download/plugins/com.example.add-on/version/39/descriptor?access-token=9ad5037b)
  8. Press Upload. The system takes a moment to upload and register your plugin. It displays the Installed and ready to go dialog when installation is complete.
  9. Click Close.
  10. Verify that your plugin appears in the list of User installed add-ons. For example, if you used Hello World for your plugin name, that name will appear in the list.

Installing an add-on using the REST API

You can also install an add-on using the UPM's REST API. You'll find this method useful if you want to install add-ons programmatically, say from a script, or simply want to quickly install an add-on from the command line. Broadly speaking, installing an add-on (or performing any operation against the REST API of the UPM) is a two-step process:

First get a UPM token. Next, issue the request to the REST API, including the token you received.

The following steps walk you through these steps in detail:

Send a GET request to the following resource: 

http://HOST_NAME:PORT/CONTEXT/rest/plugins/1.0/?os_authType=basic

In your request:

  1. Replace HOST_NAME and PORT with the actual host name and port of the target Atlassian application. If applicable (i.e., if using a development instance), include the CONTEXT with the application context (/jira or /confluence).
  2. Include the username and password for a system administrator user in the target Atlassian application as HTTP Basic Authentication credentials.
  3. Set the Accept header for the request to: "application/vnd.atl.plugins.installed+json"

Capture the header named upm-token in the response. This is the UPM token you need for the next request.

Now install your add-on by issuing a POST request to the following resource:

http://HOST_NAME:PORT/CONTEXT/rest/plugins/1.0/?token=${upm-token}

In your request:

  1. Again use the actual host name and port and path for your target Atlassian application.
  2. The token value should be the value of the upm-token header you just received.
  3. In the request, set the Accept header to: "application/json"
  4. Set the Content-Type for the data to: "application/vnd.atl.plugins.install.uri+json"
  5. In the body of the POST, include the following JSON data:

    {
      "pluginUri": "${plugin-xml-url}",
      "pluginName": "the plugin name"
    }

    Replace plugin-xml-url with the hosted location of your descriptor file, and the plugin name with the name by which you want the add-on to be registered in the application.

This registers the add-on declared by the atlassian-plugin.xml file at the URL.

You should not rely on the response returned from the POST request to confirm that the plugin has been installed. Instead, the best way to confirm that the plugin has been installed is to add a webhook to your add-on descriptor that listens for the add-on installation event. The webhook declaration in the atlassian-plugin.xml file would look something like this:

<webhook key="installed" event="remote_plugin_installed" url="/your-url-here" />

Troubleshooting authentication

When registering from the command line using cURL, keep in mind that cURL does not perform session maintenance across calls (unlike other clients, such as Apache HttpClient). Thus, you need to either:

Send the authentication credentials in both requests, or have curl save any cookies from the first request and send them in the second.

To set curl to save any cookies from the first request to use in the second:

  1. To save cookies, use the -c switch: curl -c cookiesfile.txt ...
  2. And then include the cookies in the second request: curl -b cookiesfile.txt ...
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport