Licensing API Overview

Starting with the Atlassian SDK 3.7, you can add the license management module to your plugin projects. This module gives plugins access to the license enforcement features in the UPM across products.

Contents of the License Management module

You can use any of the atlas-create-APPLICATION-plugin commands to create a project (for example, atlas-create-jira-plugin). Once you have a plugin project, you use the SDK's atlas-create-APPLICATION-plugin-module to generate the Atlassian License Management module.

The module generator adds a LicenseChecker class to your project. This class listens for Atlassian licensing events and disables the plugin if its license is invalid. The module modifies your plugin's descriptor file (atlassian-plugin.xml) by:

  • enabling the atlassian-licensing-enabled parameter to true in <plugin-info>.
  • importing the com.atlassian.plugin.PluginController component
  • importing the com.atlassian.upm.api.license.PluginLicenseEventRegistry component
  • importing the com.atlassian.upm.api.license.PluginLicenseEventRegistry component

Finally, the generator adds the Maven dependencies on UPM 2.0 to the project pom.xml file.

The LicenseChecker class

The LicenseChecker class uses the UPM's licensing API to listen to plugin license events and enforce license validity. The class constructor takes a PluginController, a PluginLicenseManager, and a PluginEventRegistry. In addition to a constructor, this generated class contains the following methods:

handleEvent

An overloaded method that listens for:

  • Enable events - either at application startup time, or when the plugin is installed into an already-running application. The plugin may or may not have a license at this point.
  • Changes to the plugin license other than its complete removal.
  • Removal of an installed plugin.

checkLicense()

Checks for invalid licenses and disables the plugin if its license is invalid.

isValidLicense()

Determines if a license is valid. Logs appropriate messages.

Atlassian designed the class to handle basic license operations. After you add the module, no additional coding is required.

Custom license operations

You can customize the licensing behavior of your plugin using the PluginLicenseManager and the PluginLicenseEventRegistry interfaces. Both the PluginLicenseManager and the PluginLicenseEventRegistry instances are specific to your plugin.

PluginLicenseManager

To do this, you can override the plugin-disablement and implement your own enforcement behavior through the PluginLicenseManager class. Each plugin using UPM's Licensing API is given a PluginLicenseManager instance specific to their plugin. This class has two methods:

getLicense()

Fetches the current plugin's license.

getPluginKey()

Fetches the current plugin's key.

Using these methods, you can check the license status, as in the following form. If appropriate, the code can disable the plugin by its key.

if (licenseManager.getLicense().isDefined())
{
   PluginLicense license = licenseManager.getLicense().get();
   if (license.getError().isDefined())
   {
        // handle license error scenario
        // (e.g., expiration or user mismatch) 
   }
   else
   {
        // handle valid license scenario
   }
} 
else 
{
        // handle unlicensed scenario
}

We recommend that the plugin check license validity at each of the plugin's entry points. Upon detecting an invalid license you can either hide all UI elements, make your plugin read-only, disable your plugin, or any other behavior your define.

PluginLicenseEventRegistry

If you want your plugin to, for example, handle a license submission or expiration in a specific manner you can use PluginLicenseEventRegistry to listen for a variety of license events. The com.atlassian.upm.api.license.event package supports the following event types:

  • PluginLicenseAddedEvent
  • PluginLicenseChangeEvent
  • PluginLicenseCheckEvent
  • PluginLicenseExpiredEvent
  • PluginLicenseMaintenancePeriodExpiredEvent
  • PluginLicenseRemovedEvent
  • PluginLicenseUpdatedEvent
RELATED TOPICS
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport