Last updatedApr 1, 2019

Server app licensing validation rules

The UPM licensing API checks app licenses for validity, and returns an error that apps can use to enforce license validity in a custom manner. The error conditions are listed below.

By default, an invalid license is enforced differently between standard and evaluation licenses, as follows:

  • Non-evaluation licenses have maintenance termination dates. When a maintenance term expires for a standard license, the app continues to work but cannot be updated to new versions of the app. Also, vendor support for the app in no longer available after the maintenance period ends.
  • Evaluation licenses have expiration dates. The app can be updated as long as the evaluation license is valid. However, unlike a standard license, the app stops working when the license period for an evaluation license ends.

Checking for license errors

You can implement your own license enforcement behavior through the PluginLicenseManager class. For example, an invalid license may cause your app to function in read-only mode, or you might choose to display a renewal banner.

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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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.

Conditions that invalidate a app license

If there is a license error, the getError() method will return one of the following conditions:

ConditionsDescription

EXPIRED

A license is invalid if the current date is greater than or equal to the license's expiration date. Normally, only evaluation and subscription licenses have expiration dates. Perpetual licenses do not have expiration dates; instead, perpetual licenses have maintenance expiration dates after which the app should continue to be fully functioning, but the customer will no longer be eligible for app updates or support.

Suggested error message:

Invalid license: Your evaluation license of APP_NAME expired. Please use the 'Buy' button to purchase a new license.

TYPE_MISMATCH

A license is invalid if its type (commercial, developer, academic, etc.) is incompatible with the type of the application license:

  • If the application license is developer, all app license types are compatible.
  • If the application license is hosted, the app license type must be hosted, academic, commercial, community, or open source. (This license type was used for hosted installations prior to On-Demand; it will likely become obsolete.)
  • For all other application license types, the app license type must be the same as the application license type.

Starting with UPM 2.7, Enterprise license enforcement is also supported. Customers using UPM 2.7 or later will also have an incompatibility:

  • If the application license is an Enterprise license and the app license is not.

Suggested error message:

Invalid license: Your evaluation license of APP_NAME expired. Please use the 'Buy' button to purchase a new license.

USER_MISMATCH

A license is invalid if its maximum number of users property is less than that of the application license:

  • Application is licensed for an unlimited number of users; app license has a fixed user limit
  • Application is licensed for a fixed limit; app license has a fixed limit that is lower

Suggested error message:

Invalid license: Your APP_NAME is only licensed for LIMIT_VALUE users. Your ATLASSIAN_APPLICATION installation requires a license for LIMIT users. Please get a APP_NAME license for LIMIT_VALUE users and try again.

EDITION_MISMATCH

This error currently only applies to Bamboo app licenses. A license is invalid if its maximum number of remote agents property is less than that of the application license:

  • Application is licensed for an unlimited number of remote agents; app license has a fixed remote agent limit
  • Application is licensed for a fixed limit; app license has a fixed limit that is lower

Suggested error message:

Invalid license: Your APP_NAME is only licensed for LIMIT_VALUE remote agents. Your ATLASSIAN_APPLICATION installation requires a license for LIMIT remote agents. Please get a APP_NAME license for LIMIT_VALUE users and try again.

VERSION_MISMATCH

A license is invalid if the app's build date is greater than or equal to the license's maintenance expiration date. That is, if the license says that support is only available through 1/1/2012, then an existing installation of a app version with a build date of 1/1/2011 will continue working indefinitely, but if you install a new version built on 1/2/2012 or later it will not work with the old license.

The app build date is indicated by an Atlassian-specific property in the manifest of the app JAR, Atlassian-Build-Date. This property is added to the app manifest by the Plugins SDK. You should not remove the Atlassian-Build-Date property from the manifest.

Suggested error message:

Invalid license: Your license for maintenance of APP_NAME is not valid for version X.Y.Z. Please use the 'Renew' button to renew your APP_NAME license.

The system skips the type mismatch, user mismatch, and edition mismatch tests for evaluation licenses and considers all license types compatible. This is true if either or both of the app license and application license is an evaluation license.