Tutorial: Adding licensing support to your add-on (up to UPM version 2.0)
|Level of experience||BEGINNER|
|Time estimate||45 MINUTES|
UPM versions prior to 2.0, and libraries compatible with:
For older product versions, specify a Plugin Licensing Support plugin version older than 2.15 in step 4.7.
You'll learn how add-on licensing works in the Universal Plugin Manager (UPM). In this tutorial, you'll create a simple plugin and install it in JIRA. You'll add a license to your plugin via the UPM. Your plugin will use the Plugin Licensing Support API to ensure compatibility with UPM. You'll add a plugin module that automatically creates a "Hello, World!" servlet. Finally, you'll add a license to your add-on, and verify your servlet reflects the license.
This tutorial demonstrates how to write a license-aware plugin that is compatible with Atlassian products that are not yet supported by UPM 2.0. You can also use this pattern with products that support UPM 2.0 but which do not come bundled with it. If and when your customers with these products upgrade to UPM 2.0, the licensing pattern in this sample continues to work. By supporting situations where UPM 2.0 is not yet installed, this library also increases the potential audience of a plugin. All the components in this tutorial are contained within a single JAR file.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you are done, you can find the plugin source code on Atlassian bitbucket. bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
If you aren't sure how to use Git, see the Bitbucket Getting started guide. Alternatively, you can download the source using the get source option here: https://bitbucket.org/atlassian_tutorial/upm-licensing-compatibility/overview.
Before working through this tutorial, you may read Plugin metadata files used by UPM and Marketplace. You should also have an understanding the following:
You should have installed the following software on your local system:
OS & IDE
You can use any supported combination of OS and IDE with this tutorial. These instructions assume Eclipse Classic Version 3.7.1 on a MacBook Air running Mac OS X Version 10.7.2. If you are using another combination of OS and IDE, you should use the equivalent operations for your specific environment.
It may help to be familiar with the following plugin modules:
Of course, you should also understand the Java development basics including classes, interfaces, methods, how to compile source into a JAR file, and so on.
Step 1. Create the plugin project
Before working through this procedure, make sure you have the latest version of the Atlassian SDK. Then:
- Open a terminal and navigate to your Eclipse workspace directory.
Enter the following command to create a JIRA plugin skeleton:
When prompted, enter the following information to identify your plugin:
- Confirm the properties configuration when prompted.
Change to the
tutorial-licensing-compatibilitydirectory created by the previous step.
Run the command:
- Start Eclipse.
- Select File > Import.
Eclipse starts the Import wizard.
- Expand the General folder tree.
- Filter for Existing Projects into Workspace and press Next.
- Choose Select root directory and then Browse to the root directory of your workspace.
Your Atlassian plugin folder should appear under Projects.
- Select your plugin project and click Finish.
Eclipse imports your project.
Step 2. Review and tweak the stub code
Familiarize yourself with the generated stub plugin code. In this section, you'll check (and potentially tweak) the generated files. Open your plugin project in Eclipse and follow along in the next sections to tweak some values.
Edit your <properties> section
When you created the stub files, the generator created the
<properties> of your
pom.xml file (project object model). The generator lists the Atlassian host product version you chose when you ran the plugin command. The
<amps.version> value specifies the
atlas- commands you are running. Take a moment and examine these values:
- Scroll to the bottom of the
- Find for the
<properties>element and review the
- Make sure the
<jira.version>value is set to the 5.0 release.
Make sure the
<amps.version>is set to
3.10.2(or higher, if you have a more recent SDK).
When you are done, the section should look like the following:
- Save the
Add plugin metadata
Add some metadata about your plugin and your company or organization. If you haven't already, open the
pom.xml file in the root folder of your plugin and do the following.
- Scroll to the top of the
- Locate the
Add your company or organization name and your website to the element:
- Save the file.
Review the generated plugin descriptor
Your stub code contains a plugin descriptor file
atlassian-plugin.xml. This is an XML file that identifies the plugin to the host application (JIRA) and defines the required plugin functionality. The descriptor references the metadata in your
pom.xml file. In your IDE, open the
PROJECT_DIR/src/main/resources/atlassian-plugin.xml file. You should see something like this:
project.artifactId that make up the
key attribute you defined when you ran the
atlas-create-jira-plugin command. The actual values you entered live in the
pom.xml file, they are just referenced here. Every reference in the descriptor that starts with
project reference information from the
Step 3. Update your project and refresh your IDE
If you change your Atlassian project, Eclipse is not automatically aware of the changes. Moreover, sometimes your project dependencies require an update. You can use the Atlassian SDK commands to do this update:
- Switch to a terminal window.
Change directory to the project root.
This is the directory with the
Update the on-disk project metadata with the new POM information.
- Back in Eclipse, refresh the plugin project to pickup the changes.
Remember to do this update and refresh step each time you edit your
pom.xmlor otherwise modify your plugin source with an Atlassian command.
Step 4. Add a licensing support module
Add the Atlassian Plugin Licensing support to your plugin. To do this, you add a
Licensing Support API module to your plugin. This module contains a servlet that act as your license administration screen. You can use this screen to test your licensing.
To add the module:
- Open a command window and go to the plugin root folder (where the
- Choose the option labeled
Licensing API Support.
Supply the following information as prompted and hit Return/Enter.
License Servlet Classname
License Servlet URL Path
Include Example Code
Hello World Servlet URL Path
The system generates the module and prints out an informational message similar to the following:
Nwhen prompted with Add Another Plugin Module.
- Open your
upm.license.compatibility.versionproperty to the latest stable target version, such as
Open the plugin descriptor file,
atlassian-plugin.xml, in the project's resources directory and add a
plugin-infothat identifies the license configuration servlet. The element should have a
configure.urland identify the location of the servlet in the body of the element, as in the following example:
For a full example of the descriptor file, see Plugin metadata files used by UPM and Marketplace.
Update the on-disk project metadata with the new POM information created by the generator.
- Back in Eclipse, refresh your plugin project to pickup the changes.
What did the module generator do?
The module generator does a lot under the covers for you. It adds code dependencies to your POM, adds components to your
atlassian-plugin.xml file, and adds two servlet classes for you. For now, we are just going to mention these changes and move onto seeing how your new plugin operates. If you want to review the details of the module generation now or in the future, see Understanding the generated license API support.
Step 5. Build and verify your plugin installation
At this point, you've edited a few metadata files and generated some new code with Atlassian's SDK. You can test your new modules easily through the SDK's
atlas-run command. This command builds your plugin code, starts a JIRA instance, and installs your plugin in it.
- Make sure you have saved all your code changes to this point.
- Open a terminal window and navigate to the plugin root folder (where the
Run the following command:
The code generator creates some test classes but we skipping the tests for now. The command can take several seconds or even a minute or two. When the process completes, you see several status lines in the terminal concluding with something like the following:
You can see that this output includes the URL of the JIRA instance.
Log into JIRA using the following credentials:
- Navigate to the Administration > Plugins page (http://myhost.local:2990/jira/plugins/servlet/upm).
- Locate the tutorial-licensing-compatibility plugin in User-installed Plugins.
- Click the listing to expand the details. You should see something like the following:
Confirm the UPM version JIRA is running by doing the following:
- Locate the Show System Plugins option on the page and click it.
JIRA refreshes and displays a list of system plugins.
- Locate the Atlassian Universal Plugin Manager entry and click it to open the details.
- Locate the Plugin Version field.
If you have followed this tutorial exactly to this point, you should see version 1.6.3.
Step 6. Test the plugin licensing
When you added the Licensing Support module, you generated a
LicenseHelloWorldServlet servlet that represents the actual plugin functionality. You also generated a
LicenseServlet that provides you (and your customers) with the means for entering a license in the pre-2.0 world. Upon starting up JIRA, your plugin is not licensed. In this step, you test how licensing works in a pre-2.0 version of UPM.
- Verify the plugin is unlicensed by visiting the LicenseHelloWorldServlet page.
You should see a message like the following:
- Go to the LicenseServlet page.
The servlet displays a Tutorial Plugin License Administration page like this:
You need a license.
Copy the 60 second license string as noted below:
- Paste the license into the Enter a new license field.
- Press Update.
The system displays an image similar to the following:
Now that your plugin has a valid license, you should be able to see "Hello, World!".
- Return the LicenseHelloWorldServlet page and you should now see:
Step 7. Get some additional licenses and test a bit
A 60 second license does not give you much time. We also realize you might want to test various license error conditions. So, if you need more licenses go to Timebomb licenses for testing.
To clear out a license on the Tutorial Plugin License Administration page and add a new license, do the following:
- Select the contents of the Enter a new license field and press Delete on your keyboard.
The system should provide you with a message that Your license has successfully been removed.
- Copy and paste a new license into the field.
- Press Update.
You cannot reuse licenses by entering them multiple times. If you exhaust your test licenses:
- Log out of JIRA.
- Return to the terminal where you ran
- Press Ctrl-D on your keyboard to end JIRA.
atlas-mvnclean to clear out your target instance.
Step 8. Test how the plugin behaves after an upgrade to UPM 2.0.1
Recall that the JIRA 5.0 bundled UPM 1.6.3. UPM version 1.6 and later are capable of updating to newer UPM versions. In this step, you upgrade your JIRA instance from UPM 1.6.x to UPM 2.x. Then, you test the license administration interaction after the upgrade to see how it is different.
If you haven't already done so, start JIRA and do the following:
- Login as
adminwith a password of
- Go to the Plugins page in JIRA .
- Navigate to the Upgrade tab.
- Locate the Atlassian Universal Plugin Manager entry in the list.
- Click the entry to view the details.
- Click Upgrade Now.
JIRA downloads and installs the new version of the UPM:
- When prompted, Refresh the page.
- Navigate to the Manage my Plugins tab.
Note that the tab navigation is different than it was prior to the UPM update.
- Scroll down to User-Installed Plugins and locate the plugin-license-compatibility-tutorial entry.
- Click the entry to view its details:
You should now see a License Key value and a pencil icon.
- Click on the pencil icon to reveal the license:
If you set a license already using the
LicenseServletyou should see the same license here.
- Go to the LicenseServlet page.
You should see a response with a link back to the UPM like the following:
Step 9. Add some branding
You can add branding materials to your license aware plugin. This branding material appears only when UPM 2.0 is installed together with your plugin in the Atlassian product. If you want to try adding this, go ahead and skip to Step 7. of How to Create a Submission-ready JAR