Tutorial: Adding licensing support to your add-on
|Level of experience||BEGINNER|
Licensing add-ons for the Marketplace using UPM versions after 2.0
For demonstration, this tutorial uses JIRA 7.2.4 but it applies to
|Ecosystem Compatibility||This tutorial was tested on AMPS 6.2.11 and Atlassian SDK 6.2.14|
You'll learn how add-on licensing works in the Universal Plugin Manager (UPM). Without licensing, UPM treats your add-on as a free plugin – users aren't prompted to purchase or obtain licenses in order to use your plugin. In order for your add-on to be profitable, it needs to be licensable. In this tutorial, you'll create a simple plugin without licensing, and then add a license via the UPM. This tutorial uses JIRA to illustrate how licensing works, but the concepts presented are identical across any product that uses UPM 2.0+.
Your plugin will use the
Licensing API to ensure compatibility with UPM.
- Plugin licensing for UPM 2.0+
Complete the beginner tutorial, Set up the Atlassian Plugin SDK and Build a Project, before starting this one. Specific to this tutorial, we recommend reading through Plugin metadata files used by UPM and Marketplace.
Step 1. Create the plugin project
In this step you'll generate stub code for your plugin. You can ensure you have the latest version of the SDK installed by issuing the command
atlas-update and following the installation prompts.
Open a terminal and navigate to a directory to create a plugin.
Enter the following command to create a JIRA plugin skeleton:
When prompted, enter the following information to identify your plugin:
Confirm your entries when prompted with
Your terminal notifies you of a successful build:
Change to the
jiraLicensedPlugindirectory created by the previous step.
Step 2. Start up your host product
In this step, you'll start up a product instance to see your add-on in the UPM. Since you haven't added any licensing capabilities, UPM treats your add-on as a free plugin – customers can use it, but aren't prompted to use or purchase a license. In these steps, we use JIRA 6.0 here, but you can use any product that supports UPM 2.0+.
Ensure you're in your plugin directory. If you followed the steps above exactly, your directory should be
Run the following command to start up JIRA with the plugin installed:
In your terminal, JIRA's URL will be shown when it has finished starting up – the first time this may take a few minutes as all the files need to be downloaded.
Keep this JIRA instance running for the rest of this tutorial.
- In your web browser, navigate to your JIRA instance, usually at http://localhost:2990/jira.
- Log in with the credentials
- Navigate to the Universal Plugin Manager page where you can manage your add-ons: http://localhost:2990/jira/plugins/servlet/upm.
- Verify you can see your add-on listed in UPM. There's no label for Licensing because you have only created an unlicensed add-on so far. You'll add licensing in the next step.
Step 3. Make your plugin licensable
Your plugin hasn't conveyed to the product that it even should have a license, let alone provided an ability to accept licenses. Here, we'll add a dependency in your
pom.xml file to both the UPM API and the licensing API. Then, you'll declare your add-on as licensable in your descriptor file.
Add the following dependencies to the
Add the following parameter to the
atlas-mvn packagein the project home directory to repackage the plugin. QuickReload will then reload the plugin.
- Refresh the UPM page. Verify you see 2 big changes: a License details field, and a License key input box.
Step 4. Use
PluginLicenseManager to access licensing information
You can use
PluginLicenseManager to access licensing information within your plugin. In the following, we create a servlet that replies with the currently registered license (if there is one).
atlassian-plugin.xml, add the following
Add the class
com.atlassian.tutorial.LicenseServletand put the following code in it:
We constructor-inject an instance of
PluginLicenseManagerinto the servlet and use it to return the license string in response to GET requests.
atlas-mvn packageto reload the plugin.
Step 5. Add a license key and verify it all works
Here you'll verify that everything is wired properly. You'll input a test license to check that UPM responds the way it should to your add-on.
- Issue a GET request to our servlet with URL http://localhost:2990/jira/plugins/servlet/my/license. It should say "License missing!" since we haven't entered a license yet.
Enter the following into the License key field for our plugin on the UPM page:
This is a 60-second license key.
Click Update. If accepted, you should see a lozenge and a banner appear to notify you that your plugin license expires soon.
- Issue another GET request to our sevlet: http://localhost:2990/jira/plugins/servlet/my/license and you should see the license we entered.
- Test other license states using Timebomb Licenses for Testing.
If you run out of licenses, you can shut down your JIRA instance by clicking
CTRL+Din your terminal; and then running
atlas-mvn cleanto remove your