Selling - License
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, SuiteCRM version, 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.
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 SuiteCRM 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 SuiteCRM admin can specify which users can use your add-on and purchase additional licenses when more are needed. All right from within SuiteCRM.
Adding License Validation to Your Add-on
Grab SampleLicenseAddon.zip. This sample module includes a library that talks back to the SuiteCRM Store, 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 SuiteCRM 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://store.suitecrm.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 https://store.suitecrm.com/addons/sampleaddon the shortname would be sampleaddon 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 SuiteCRM Store 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 SuiteCRM Store 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?
Even if you are charging just a one-time, flat-rate fee you should be validating an installation's license key 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 (via Add-on)
Under each pricing plan there is a Public Key (what you put into your license config) and a Customer Key. The Customer Key is what you will use to test your add-on as if you are the customer. Copy and paste this key into the license validation after your add-on is installed. You can see the latest successful ping under your Demo Keys page. From this page, you can suspend and unsuspend the key to test handling if the Customer Key does not successfully validate, mimicking an invalid or expired trial or subscription.
- Copy your Customer Key from the pricing plan
- Install your add-on
- Validate the license with your Customer Key
- View results on your demo keys page
Important note: Successful pings are stored in the config table in the CRM. Use the following SQL command to remove all cached license pings in order to get a fresh license validation test:
delete from config where category = 'SugarOutfitters' and name not like 'lic%';
How to Test (Directly)
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
index.php?module=SampleLicenseAddon&action=outfitterscontroller&method=test&to_pdf=1
Want to test for a specific user? Simply add a user_id param:
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 required 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 SuiteCRM Store 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!