License API for server apps

The License Management module in the Atlassian SDK lets your server and Data Center apps access UPM's license enforcement features 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 app 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 app if its license is invalid. The module modifies your app'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 to the project pom.xml file.

LicenseChecker class

The LicenseChecker class uses the UPM's licensing API to listen to app 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:

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

Customizing app behavior based on the app license

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

PluginLicenseManager

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

The class includes the getLicense() method, which lets you check the validity of the license for the current app. You can check the license validity using the getError() method, as in the following form:

1
2
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
}

If there are no error conditions, the license is valid.

We recommend that you check for license validity at each of the app's entry points. Upon detecting an invalid license you can either hide all UI elements, make your app read-only, disable your app, or any other behavior your define. See Server app license validation rules for details on the error values returned by the getError() method.

You can use the isDataCenter() method to check whether the app has a Data Center license installed, as follows:

1
2
PluginLicense license = licenseManager.getLicense().get();
if (license.isDataCenter())
{
     // handle Data Center scenario
     // (e.g., functionality specific to Data Center) 
}
else
{
     // handle server (non-Data Center) scenario
}

PluginLicenseEventRegistry

If you want your app 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

Customizing app behavior based on the host license

Your app can also have customized behavior based on the state of the host product license. For example, it can:

• Access the edition (user count) of the host license
• Determine whether the host license is an evaluation license
• Determine whether the host license is a Data Center license

The methods for retrieving this information will be available in UPM 3.0 and later. However, in order for your app to be backward compatible with older versions of UPM, you should use the Data Center Licensing Compatibility library to access this information.

Related topics

• Adding licensing support to your app
• Declaring marketing assets for server apps
• JavaDoc