View source for WHMCS cPanel Licensing Module

== About this Addon Module ==

<div class="docs-alert-warning">
<span class="title">Licensing Addon</span><br />
* The cPanel Licensing Automation module is not associated with the WHMCS [[Licensing Addon]].
* This module is for cPanel Partners. If you are not yet a partner, see [https://www.cpanel.net/partners/ the cPanel website].
</div>

The cPanel Licensing Automation module for WHMCS is a tool that utilizes the cPanel Manage2 API to provide an automated solution for cPanel Partners to provision, manage, and bill for cPanel & WHM licenses.

For help to get started, see [[WHMCS cPanel Licensing Module Getting Started Guide]].

<table class="table" style="text-align:center;margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;width:100%;">
<tr>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Addon Name</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Latest Release</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Current Version</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Compatible With</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Included in WHMCS</th>
</tr>
<tr>
<td style="border:1px #AAA solid;padding:0.2em;">WHMCS cPanel Licensing Module</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;color:darkred;">No</td>
</tr>
</table>

== Activating WHMCS cPanel Licensing Module ==

You will need to download and upload the module before you can activate the addon through the Admin Area.

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the <tt>cpanellicensing</tt> directory to the <tt>/modules/addons</tt> folder of your WHMCS installation.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Addon Modules]]''' or, prior to WHMCS 8.0, '''Setup > Addon Modules'''.
# Click '''Activate''' for '''cPanel Licensing'''.
# Click '''Configure'''.
# Select the admin role groups who will have access to this addon.
# Select the admin users who can configure settings within the addon.
# Click '''Save Changes'''.

== Using WHMCS cPanel Licensing Module ==

[[File:CPLic_AuthenticatingIntoManage2.png|thumb|Manage2 Login Prompt]]

After configuring the module, you will need to authenticate into Manage2.

To do this, navigate to '''Addons > cPanel Licensing''' and log in using your Manage2 username and password. The system will import your Manage2 data into WHMCS. This may take several minutes depending on the amount of licenses associated with the Manage2 account.

=== Autoscale ===

'''Autoscale''' allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of accounts associated with its cPanel license. Use the Autoscale settings below when you want WHMCS to automatically upgrade a license to the next tier based on usage. 

Autoscale uses the following procedure:

# A server administrator provisions an extra cPanel account which in turn pushes the server into the next cPanel license tier.
# cPanel's Manage2 software detects this and changes the license tier for billing purposes in the cPanel Partner account.
# WHMCS  performs a synchronisation with Manage2 at specific intervals that picks up this change.
# The Control Panel configurable option in WHMCS changes to match the new cPanel license tier and as a result of this, the service price is auto recalculated to include the additional cost of the new license tier.
# The next renewal invoice generated by the service (per the Next Due Date) will reflect the new cPanel license tier.

This ensures that the client is always billed appropriately for their current cPanel license tier without any manual intervention.

=== Settings ===

[[File:CPLic_Settings.png|thumb|Settings Tab]]

The cPanel Licensing addon offers further configuration settings concerning Data and API Permissions, as well as Invoice and Cart Display Options.

These can be accessed by navigating to '''Addons > cPanel Licensing''', and then clicking on the '''Settings''' tab. The settings seen on this page are detailed below.

==== Data and API Permissions ====

*'''Manage2 Account''' - Your Manage2 Registered Email. Here you will see the logged in user and a '''Logout''' button.
*'''Provisioning Default Group''' - The default group to assign new licenses to.
*'''Permissions''' - Access controls for functionality within this addon.

==== Invoice and Cart Display Options ====

*'''Invoicing Line Item Format''' - The line item description used for invoicing by packages that offer bulk cPanel accounts.
*'''Option Info Tooltip''' - Optional tooltip text to display near license configurable options during checkout. HTML is supported.
*'''Option Description Format''' - The configurable option selection format for display on the order form for packages that offer bulk cPanel accounts.
*'''Autoscale Label''' - The label to be displayed on the order form.
*'''Autoscale Notification Email''' - The email template to be sent upon an autoscale change. For more information, see the [[WHMCS cPanel Licensing Module#Autoscale Notification Email|Autoscale Notification Email]] section.

==== Autoscale Notification Email ====

The cPanel Licensing module can be configured to send a custom email notification to a client upon an Autoscale Change.

To configure this functionality you will need to first create the custom email to be used. You can do this at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates'''. This custom email template type must be either '''Product/Service Messages''' or '''Notification Messages'''. 

The custom template to be used will have access to the following merge fields:

*'''newOption''' - The display name of the configurable option being upgraded to.
*'''oldOption''' - The display name of the configurable option being upgrade from.
*'''isUsageUpgrade''' - A boolean indicating whether or not the upgrade is due to usage activity.

Once the custom email template has been created, it can be set as the ''Autoscale Notification Email'' template. 

To do this:

# Go to '''Addons > cPanel Licensing'''.
# Click on the '''Settings''' tab.
# Locate the '''Autoscale Notification Email''' setting.
# Select the custom email template from the menu.
# Click '''Save Changes'''.

=== Pricing ===

[[File:CPLic_Pricing.png|thumb|Pricing Tab]]

cPanel licenses are sold as configurable options of products. This interface allows you to set pricing for those options as well as respective metric pricing for cPanel accounts.

Typically the configurable option would be assigned to a product with which a cPanel license would beneficial; a VPS or Dedicated Server. It can also be sold as a [[#Standalone_Product|standalone product]].

On this tab you will see the ''ID'', ''Configuration Name'', ''Selections'', and ''Auto-Scale'' columns displayed for each option that has been created with, or imported into, the cPanel Licensing addon.

Additionally, you will see buttons labelled ''New'', ''Import'', and ''Manage'' which allow you to create, import, and manage options respectively. The functionality of these buttons is detailed below.

==== Create New Option ====

[[File:CPLic_CreateNewOption.png|thumb|Create New Option Modal]]

Clicking on the ''New'' button will bring up the ''Create New Option'' modal. It is within this modal that you can create a new [[Configurable Options|configurable option]] to be used for offering cPanel licenses to your customers via this module.

The following configuration settings are displayed on this modal:

*'''Parent Group''' - The option group to create the new option within. Should the ''Create New Group'' option be selected, then the ''Group Name'' option will appear.
*'''Group Name''' - The name for the new configurable option group. This option will only appear when the ''Create New Group'' option has been selected from the ''Parent Group'' drop-down menu.
*'''Option Name''' - The display name for the new configurable option.
*'''Option Type''' - The type to be used by the new configurable option. Only drop-down and radio option types are supported.
*'''Auto-Populate''' - Automatically populate the new option with the default cPanel license package offerings and recommended retail pricing.
*'''Hardware Type''' - Offers a selection between the ''Dedicated/Metal'' and ''VPS/Cloud'' options.
*'''Default Visibility''' - Toggles whether or not the option is visible from the Order Form.

Once the settings have been completed, clicking on the ''Create'' button will generate the Configurable Option Group, create Configurable Options if the ''Auto-Populate'' option was selected, and display the option group in the Pricing tab of the module.

==== Import Existing Option ====

[[File:CPLic_ImportExistingOption.png|thumb|Import Existing Option Modal]]

If you have an existing '''Configurable Option Group''' and '''Configurable Options''' that you would like to be used for the provisioning and billing of cPanel licenses, then these can be imported for use with the cPanel Licensing addon.

During this process you will be prevented with a list of configurable options, and be asked to associate them with a cPanel Package. If a configurable option is not related to a cPanel license, then leave the dropdown at the ''Not a cPanel License Option'' value. Options left at this value will not be used by the cPanel Licensing module, and will continue to function as a normal configurable option.

<div class="docs-alert-warning">Only ''Dropdown'' or ''Radio'' configurable options are supported for import. Other option types will not be available for import.</div>

Clicking on the ''Import'' button will bring up the ''Import Existing Option'' modal. It is within this modal that you can import an existing configurable option to be used for the provisioning and billing of cPanel licenses via this module.

Within the ''Import Existing Option'' modal you will be presented with the ''Option Name'' drop-down menu. This menu allows you to select which Configurable Option you would like to import.

Selecting the desired option from the drop-down and clicking the ''Continue'' button will bring you to the ''Configure Import'' section. Here you will see a list of ''Selectable Options'' displayed. For each selectable option, please select a cPanel Package below that it relates to. If an option is not related to a cPanel license, leave the dropdown at the default value.

Clicking the ''Import'' button will import the configurable options into the module, and make them available for further configuration via the ''Pricing'' tab.

====Option & Price Management====

[[File:CPLic_OptionPriceManagement.png|thumb|Option & Price Management Modal]]

Within the ''Manage'' column for each associated option a button with a wrench icon exists. This is the ''Manage'' button, and clicking on this button will bring up the ''Option & Price Management'' modal. It is within this modal that you can modify options within the group, as well as modify the cPanel related options themselves.

This modal is made up of three elements: the ''Configurable Option Settings'' section in the top-left, the ''Selectable Options'' section in the bottom-left, and the ''Selectable Option Content'' panel on the right.

===== Configurable Option Settings =====

The '''Configurable Option Settings''' section provides the ability to alter the ''Configurable Option Type'', and toggle both the ''Visibility'' and ''Autoscale'' Option.

The '''Autoscale Option''' toggle allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of licenses associated with its cPanel account. This should be used when you want WHMCS to automatically upgrade a license to the next tier based on usage. Enabling this option requires that all configurable options associated with a cPanel Package have pricing configured.

All changes made in this section are automatically saved.

===== Selectable Options =====

The '''Selectable Options''' section displays the full list of existing configurable options, and offers the ability to create new options via the ''Add Option'' button. Clicking on an option from this list will display that option's content within the ''Selectable Option Content'' panel.

Additionally, in Version 7.7 and later, dragging the options allow you to rearrange their order as desired. All changes made in this section are automatically saved.

===== Selectable Option Content =====

The '''Selectable Option Content''' section provides both an overview of that option, as well as the ability to configure it further. The ''Name'', ''Visibility'', and ''Package'' details are immediately displayed at the top, and can all be altered as desired. Additionally, the ''Configurable Option ID'' is displayed in the top-left corner.

The Pricing section is offers the ability to configure pricing for the option. Here the ''Base Recurring'', and ''Setup Fee'' values can be modified. The ''Metric: cPanel Accounts'' and ''Threshold'' values can also be modified for packages that support them.

The ''Auto populate other billing cycles based on monthly pricing'' toggle will render the Billing Cycle tabs un-clickable and will automatically populate their pricing based on the pricing present in the Monthly pricing tab.

Changes to this section are not automatically saved, and clicking on the ''Save'' button will commit the changes. Inversely, clicking on the ''Delete'' button will delete the configurable option.

===== Metric: cPanel Accounts =====

The '''Metric: cPanel Accounts''' setting is displayed when configuring pricing for packages that offer an unlimited number of cPanel accounts. This setting provides the ability to set a per-account value that the customer will be billed for, as well as a threshold to define the number of accounts a customer must have before they are billed on a per-account basis.

When a customer orders a package, with the ''Metric: cPanel Accounts'' offering, a snapshot of the current price is taken. This snapshot is then stored, and used when generating renewal invoices for the customer's service in the future. This is done to ensure that changes can be made to a package's metric pricing without affecting existing customer orders.

If you need to ensure that the pricing snapshot is updated to the current metric pricing, then this can be achieved by selecting the [[Clients:Products/Services_Tab#Auto_Recalculate_on_Save|''Auto Recalculate on Save'']] checkbox and saving the service. This will see the existing snapshot discarded, and a new one created with the current metric pricing for the associated package.

The cPanel Licensing Addon retrieves the cPanel account value from the cPanel licensing system (Manage2) at the time of invoice generation. This is to ensure use of the most accurate value relative to Manage2, to which the license reseller is accountable. Manage2 doesn't provide the historical data necessary to calculate any prior month's usage. At this time, the cPanel Licensing Addon doesn't have historical snapshot capabilities that can augment this canonical data source.

The ''Auto Recalculate on Save'' option will continue to function as normal. When used a service's ''Recurring Amount'' will be populated with current pricing based on the service and configurable options selected.

====Standalone Product====

To present a standalone product that provisions a cPanel license, use the cPanel licensing module with the Auto Release provisioning module:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.[[File:Cpanel standalone2.png|thumb|Configure Pricing]]
#Click '''Create a New Product'''.
#Select '''Other''' for '''Product Type'''.
#Enter a '''Product Name'''.
#Select ''Auto Release'' for '''Module Name'''.
#Click '''Continue'''.
# Select the '''Pricing''' tab.
#Choose '''Recurring''' for '''Payment Type'''.[[File:Cpanel standalone3.png|thumb|Configure the Auto Release Module]]
# Check the checkboxes in the '''One Time/Monthly''' column.
#Specify '''Setup''' and '''Price''' values of <tt>0.00</tt>.
#Select the '''Module Settings''' tab.
#Choose the '''Automatically setup the product as soon as the first payment is received''' option.
#Select the '''Configurable Options''' tab.
#Click the configurable option group for the cPanel license types. The cPanel Licensing Addon [[#Pricing|creates this]].
#Configure any other options are desired.
#Click '''Save Changes'''.

When this product is ordered, clients will be presented with the cPanel License Tier configurable option at the product configuration stage of the shopping cart and a license provisioned upon payment. The price of the configurable option will form the amount invoiced to the client each month.

===Manage2 Data===
The data imported from Manage2 is displayed within the module itself. This information is located within the ''Licenses'', ''Groups'', and ''Packages'' tabs. This allows you to quickly review and action your Manage2 data without leaving WHMCS.

====Licenses====
[[File:CPLic_Manage2DataLicenses.png|thumb|Licenses Tab]]

Licenses are associated with a clients' services. This interface allows modification of the license data stored at Manage2. The WHMCS data can be managed at the linked service.

On this tab you will see ''License ID'', ''Package/Group'', ''IP/Hostname'', ''Assigned Service'', and ''Status'' columns displayed for each license associated with your Manage2 account.
 
The '''Actions''' column offers the ability to perform the following actions against the associated license.

*'''Assign License''' - Assign the license to an existing service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.
*'''Change IP''' - Change the license's IP Address.
*'''Change group''' - Change the license's Group.
*'''Change package''' - Change the license's Package.
*'''Expire''' - Expire the license within Manage2.
*'''View License Details''' - Review a detailed output of license information.

====Groups====
[[File:CPLic_Manage2DataGroups.png|thumb|Groups Tab]]

Groups are arbitrary categories. They are unique to your Company. They can help keep your licenses organised by modeling how you sell and manage the product-customer lifecycle.

On this tab you will see the ''Group ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each group associated with your Manage2 account.

The '''Actions''' column offers the ability to perform the following actions against the associated group.

*'''Change name''' - Change the group's name within Manage2.
*'''Change tax status''' - Change the group's tax status within Manage2.
*'''Show Licenses''' - Display a filtered list of licenses associated with the specific group.

====Packages====
[[File:CPLic_Manage2DataPackages.png|thumb|Packages Tab]]

Packages are SKUs. They represent the product, features, or bundled options that are granted to the license holder.

On this tab you will see the ''Package ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each package associated with your Manage2 account.

The ''Actions'' column offers the ability to perform the following actions against the associated package.

*'''Show Licenses''' - Display a filtered list of licenses associated with the specific package.

===Service Management===
[[File:CPLic_ServiceManagement.png|thumb|cPanel Licensing Service Panel]]

Services associated with a cPanel Licensing related Option Group will see a panel labeled ''cPanel Licensing'' when viewing that service via the Admin Area.

When a service is associated with a cPanel license, an overview if the license details is displayed along with the following buttons:

*'''Sync IP''' - Change the license's IP Address to the value displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Sync Package''' - Change the license's Package to the value displayed in the cPanel Licensing configurable option.
*'''View Details''' - Display a modal containing the cPanel License Information.
*'''Expire''' - Expire the license within Manage2.

The following buttons will be displayed within the panel at all times:

*'''Provision New cPanel License''' - Automatically provision a new license from Manage2 using the package displayed in the cPanel Licensing configurable option and the IP address displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Link to Existing License''' - Display a modal that allows for the search of existing licenses to be assigned to the service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.

===Handling Manual License Cancellations===
Expiring a license, either by clicking '''Expire''' in the '''[[Clients:Products/Services_Tab|Products/Services]]''' tab of the client profile or in Manage2, does not automatically update the '''Recurring Amount''' for the parent service. The system cannot determine whether to bill a license using the license's state.

To cancel a license and ensure that the system updates the '''Recurring Amount''' value correctly:
# Click '''Expire''' in the '''Service Management''' section.
# Set the parent service's [[WHMCS cPanel Licensing Module#Configurable Option Settings|configurable option]] to ''None''.
# Set '''Recalculate on Save''' to ''ON''.
# Click '''Save Changes'''.

The system will update the parent service's '''Recurring Amount''' to no longer include the cost of the expired license.

===Assign License & Link to Existing License===
[[File:CPLic_AssignLicense.png|thumb|Assign License Modal]]
[[File:CPLic_LinkExistingLicense.png|thumb|Link to Existing License Modal]]

Both the Licenses tab, seen on the cPanel Licensing module page, and the cPanel Licensing panel, seen on the Service page, offer the ability to manually assign a service to a license and vice versa.

The '''Assign License''' modal provides a searchable drop-down menu that can be used to locate and select the desired service. Once the service has been selected, clicking on the ''Assign'' button will assign the service to that specific license.

The '''Link to Existing License''' modal provides a searchable drop-down menu that can be used to locate and select the desired license. Once the license has been selected, clicking on the ''Assign'' button will assign the license to that specific service.

In both cases, it is important to note that the configurable option will not be automatically selected. You must navigate to the Service page in the Admin Area, set the configurable option to coincide with the appropriate package if fixed, or enable the autoscale option if applicable. '''This is necessary for automated billing to occur.'''

Additionally, only a singular active license can be assigned to a service. Using the ''Link to Existing License'' or ''Assign License'' functionality to assign a new license to a service already in possession of an active license will result in the replacement of that active license. In this instance, a prompt will appear to confirm this action.

===Updating Manage2 Account Credentials===

The cPanel Licensing Addon uses your Manage2 username and password to authenticate with the Manage2 API. To facilitate this, the system encrypts and stores your Manage2 credentials in WHMCS's database. Because updating your credentials in Manage2 does not automatically trigger an update in WHMCS, the system will no longer be able to successfully authenticate requests.

After updating your Manage2 credentials, ensure that the system can communicate with Manage2:

# In the Admin Area, go to '''Addons > cPanel Licensing''' and click on the '''Settings''' tab.
# In the '''Manage2 Account''' section, click '''Logout'''.
# Log in using your Manage2 account credentials.

After successfully logging in, the system will store your new Manage2 login details in the database.

== Upgrading ==

If you have an earlier version of the cPanel Licensing Module installed, follow the steps below:

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the 'cpanellicensing' directory to the '/modules/addons' folder of your WHMCS installation.

==Troubleshooting==
This section covers the error messages which may be encountered during license assignment.

===A license was deactivated on the same IP last month before billing could occur===
This response indicates that the previous cPanel license associated with the service's IP address accrued usage, and was deactivated before billing could occur within Manage2.

A reactivation fee must be paid before a new license can be provisioned for that IP address. This must be done via Manage2 directly.

===This license is already assigned to another service===
Review the '''Addons > cPanel Licensing''' page to see the current service to which the license is assigned in WHMCS.

Click the ''Assign'' button a second time to remove the current assignment and assign to the current service.

===You cannot assign a license to this service===
'''You cannot assign a license to this service as the product to which it is assigned does not have a configurable option for a cPanel license'''

There is no license pricing configuration assigned to the product in use, a license can only be assigned when a pricing scheme is associated with the product. The following steps will make the necessary adjustments to the product/service configuration:

# Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Check whether the cPanel Licenses configurable option appears. If it does not:
## Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
## Click '''Edit''' for the cPanel licensing option group.
## Press Ctrl + Click to select all the applicable products that will offer a cPanel license option. Make certain to select the product that is currently exhibiting the error.
## Click '''Save Changes'''.
# If the cPanel License configurable option is displayed, select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

===cPanel Licensing options of product are not set for this service===

'''cPanel Licensing options of product are not set for this service. Review and save the cPanel licensing options for this service and try again'''

A license pricing configuration is assigned to the product in use, but the desired option has not been selected for the individual service record. WHMCS needs to know the desired license tier to invoice the client correctly. 

The following steps will make the necessary adjustments to the service record:

# Go to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Use the cPanel License configurable option to select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

== Change Log ==

''N/A''
No results found.