Enabling License Validation

We provide the flexibility to have different logical groupings of files for an add-on which we call "plans". Plans may be used for anything from organizing versions of your add-on to releasing different pricing bundles.

Licensing validation is a great way to ensure that your customers are always up-to-date on their payments. No having to chase them around to renew their purchase. We handle all of that automatically on your behalf. With it enabled it also gives you insight into some key information so that you will know exactly which host url, sugar version, sugar edition and more that they are using. This is both essential for providing top-notch (and even proactive) support and also to see the type of customers that are using your products.

If your plan's pricing is subscription based (monthly/yearly), per-user based, or offers a free trial then using the License API is required. You can turn on the license validation for any plan by editing the add-on plan and setting "Require a License Key" to yes. Upon save you will see your add-on plan's key. This is the key that you would then include in your distribution. See below for more information on how to include the key and how to add validation hooks to your add-on.

image

User Count Validation

If your add-on billing structure is "Per User" you can optionally turn on "Require User Count Verification" for the add-on plan. Without it, the purchaser will only be prompted for the user count at the time of the purchase. With it, you can add validation from your add-on within SugarCRM to see if the purchaser is under the user count that they have paid for. In addition, you can make it easy for the purchaser to add additional users to their purchase right from within their install. For example, if you are doing a marketing-like add-on you may wish to only count a subset of users who will actually be using it.

License for Specific Users

Many times you will only want to charge for those who use your add-on. We provide a user management tool so that a SugarCRM admin can specify which users can use your add-on and purchase additional licenses when more are needed. All right from within SugarCRM.

image

Adding License Validation to Your Add-on

Download: SampleLicenseAddon.zip
Current Version: 1.4.1
Last Updated: 2016-07-25

Grab SampleLicenseAddon.zip. This sample module includes a library that talks back to SugarOutfitters, an admin configuration page for you module used to validate a license, and a post-install redirect to the config page to make configuring a module easy after installation. Alter it however you would like. For example, you could have ask the user for more information at the time of entering the license key or change the sample code to support dual licensing.

This Sample License Add-on can be installed as-is right into a SugarCRM install. Try it out by altering the shortname and public_key as described below for your add-on and see how it works. Post install you will be redirected right to the license configuration (and user management tool, if enabled).

To configure for your add-on edit /license/license/config.php (Note: /license/license gets copied into the module's directory as just /license):

$outfitters_config = array(
    'name' => 'SampleLicenseAddon',
    'shortname' => 'samplelicenseaddon',
    'public_key' => '', 
    'api_url' => 'https://www.sugaroutfitters.com/api/v1',
    'validate_users' => false,
    'manage_licensed_users' => false,
    'validation_frequency' => 'weekly',
    'continue_url' => '',
);

name
    The name of the Add-on should be the same as the name of your add-on in your manifest.php file. Adding this will allow you to see exactly which version of your add-on your customer is using when they validate their license.
shortname
    The short name of the Add-on. e.g. For the url http://www.sugaroutfitters.com/addons/sugaroutfitters the shortname would be sugaroutfitters
public_key
    The public key associated with the plan. If you have multiple plans that all share the same code then you can pass a comma separated list of the public keys from each plan.
api_url
    The SugarOutfitters API url
validate_users
    true if your add-on plan requires user count validation
manage_licensed_users
    true to enable the user management tool to determine which users will be allowed to use the add-on
validation_frequency
    How often should the license validate against the SugarOutfitters License API? Options are hourly, daily, and weekly [default]
continue_url
    [optional] Will show a button after license validation that will redirect to this page. Could be used to redirect to a configuration page such as index.php?module=MyCustomModule&action=config

Where and How Often Should You Validate?

This is largely dependent on your pricing structure. If you are charging just a one-time, flat-rate fee then just upon install may be enough. However, if you are doing subscription-based pricing or any sort of per-user pricing then validating an installation's license key should be done on an on-going basis.

The SampleLicenseAddon.zip comes with helpers that will make it easy to check to see if a key is still active or not. You just need to find the right touch points in your code where it makes sense to trigger a license key check. If it fails, you then can proceed to notify the user and alter functionality as you feel is appropriate.

For example, if your add-on includes a standalone module you may wish to validate the key at the point of someone accessing that module. Or if your add-on is a Twitter dashlet you may validate the key whenever the dashlet is loaded. Your check may then look like this:

require_once('modules/SampleLicenseAddon/license/OutfittersLicense.php');
$validate_license = OutfittersLicense::isValid('SampleLicenseAddon');
if($validate_license !== true) {
    if(is_admin($current_user)) {
        SugarApplication::appendErrorMessage('SampleLicenseAddon is no longer active due to the following reason: '.$validate_license.' Users will have limited to no access until the issue has been addressed.');
    }
    echo '< h2>< p class="error">SampleLicenseAddon is no longer active</p></h2>< p class="error">Please renew your subscription or check your license configuration.</p>';

    //functionality may be altered here in response to the key failing to validate
}

Then you may choose to disable the feature until the key is entered in the License Configuration tool. OutfittersLicense::isValid() in the SampleLicenseAddon that is provided will check the last validation result that is cached. If enough time has passed, per your validation_frequency setting, it will then connect to the License API to refresh the cached value. However, whenever anyone uses the License Configuration screen to update the key that always connects to the License API to get the latest result.

How to Validate for a Specific User

If you are using validate_users and manage_licensed_users then you can validate for a specific user by passing the user_id as the second parameter to the isValid check:

global $current_user;
require_once('modules/SampleLicenseAddon/license/OutfittersLicense.php');
$validate_license = OutfittersLicense::isValid('SampleLicenseAddon',$current_user->id);
if($validate_license !== true) {
    echo '< h2>< p class="error">SampleLicenseAddon is no longer active</p></h2>< p class="error">'.$validate_license.'</p>';

    //functionality may be altered here in response to the key failing to validate
}

How to Test

If you want a more direct way to test whether a license is valid other than by just using your add-on with licensing enabled you can hit a specific URL to see if the license is currently valid and also if a given user is also actively licensed (if using manage_licensed_users).

Test URL - Sugar 7

#bwc/index.php?module=SampleLicenseAddon&action=outfitterscontroller&method=test&to_pdf=1

Test URL - Sugar 6

index.php?module=SampleLicenseAddon&action=outfitterscontroller&method=test&to_pdf=1

Want to test for a specific user? Simply add a user_id param:

#bwc/index.php?module=SampleLicenseAddon&action=outfitterscontroller&method=test&to_pdf=1&user_id=7eef99dd-5b60-1a5b-c123-53ac8394d21b

Avoiding Conflicts

To help ensure that OutfittersLicense isn't going to conflict with some other add-on's version it is recommended to rename the class to the name of your module. For example, SampleAddonOutfittersLicense. Your license validation would then use SampleAddonOutfittersLicense::isValid('SampleLicenseAddon');

This will be deprecated and unneeded in the future when the SugarOutfitters in-app management/store add-on is released.

Conclusion

With the SampleLicenseAddon example it should be fairly quick and easy to get up and running. As for how each add-on handles license validation (on each page request, upon login, once a week, etc along with what to do if validation fails) we leave that up to each developer as everyone has their own preference. If you find something that works well for you let us know!

Keep up to date on the latest additions

We'll send you an email every month with handpicked add-ons, reviews, tricks and tips. Don't worry, we hate spam as much as you do.