Revision as of 19:01, 28 April 2021

Introduction

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.

A Getting Started guide, which covers the basics of the cPanel Licensing Automation module, can be found on the WHMCS cPanel Licensing Module Getting Started Guide documentation page.

This module is intended for use by cPanel Partners. If you are not yet a partner, visit https://www.cpanel.net/partners/ to learn more.

Installation & Setup

Installation

Once downloaded, perform the following actions.

1. Extract the archive to a directory on your computer.
2. Upload the cpanellicensing directory to the ~/modules/addons/ directory within your WHMCS installation.

Upgrading

If you have an earlier version of the cPanel Licensing Module installed follow the steps below to upgrade to the latest version. The process is the same as installation.

Once downloaded, perform the following actions.

1. Extract the archive to a directory on your computer.
2. Upload the cpanellicensing directory to the ~/modules/addons/ directory within your WHMCS installation, overwriting all existing files.

Activation & Module Permissions

Addon Module Configuration

To activate the cPanel Licensing addon module, navigate to Configuration () > System Settings > Addon Modules or, prior to WHMCS 8.0, Setup > Addon Modules and click on the Activate button.

Following activation of the module, click on the Configure button. You will be presented with Master Admin Users and Access Control options which are detailed below. Select the desired options, and click on the Save Changes button.

• Master Admin Users - This series of checkboxes is where you define who you want to be able to access and configure the settings found within the cPanel Licensing addon module itself.
• Access Control - These checkboxes allow you to define which role groups you want to allow to access and use the features offered by the cPanel Licensing addon module.

Authenticating into Manage2

Manage2 Login Prompt

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

To do this, navigate to Addons > cPanel Licensing where you will be presented with a Manage2 login prompt. Enter your Manage2 username and password into the respective fields, and then click on the Login button.

After successful authentication, the Manage2 data will begin to be imported into WHMCS. This may take several minutes depending on the amount of licenses associated with the Manage2 account.

Once the import has completed, you will be redirected to the primary interface for the cPanel Licensing addon where you will immediately see a list of licenses associated with your Manage2 account.

In the event that Manage2 authentication is not successful, you will see a red box appear containing the related error.

Settings

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, as well as 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. Only used 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. Only used by 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. More information can be found in the 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. This can be done via the Setup > Email Templates section of the WHMCS Admin Area. This custom email template must be either the Product or Notification Email Type. More information about templates can be found via the Email Templates documentation page.

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, take the following steps from the Admin Area.

1. Navigate to Addons > cPanel Licensing
2. Click on the Settings tab
3. Locate the Autoscale Notification Email setting
4. Select the custom email template from the drop-down menu
5. Click on the Save Changes button

Pricing

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.

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

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 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

Import Existing Option Modal

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

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.

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.

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.

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.

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 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 which can be ordered to provision a cPanel license, the cPanel Licensing Module can be used in conjunction with the Auto Release provisioning module:

1. Navigate to 'Setup > Products/Services > Products/Services
   

   Configure Pricing
2. Click Create a New Product
3. Select the Product Type value Other
4. Enter a Product Name as desired; for example cPanel License
5. Select the Module Name value Auto Release
6. Click Continue and select the Pricing tab
7. Choose the Payment Type value Recurring
   

   Configure the Auto Release Module
8. Tick the checkboxes in the One Time/Monthly column
9. Specify Setup and Price values of 0.00
10. Select the Module Settings tab
11. Choose the Automatically setup the product as soon as the first payment is received option
12. Select the Configurable Options tab
13. Click the Configurable Option Group for the cPanel license types (created by the cPanel Licensing Addon as described above)
14. Finally, configure any other options are desired
15. 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

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 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

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

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

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 Assign License & Link to Existing License section.

Assign License & Link to Existing License

Assign License Modal

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.

Error Messages

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 clients Products/Services tab for the service in question
• Assert the cPanel Licenses configurable option is displayed (dropdown or radio options depending upon your choice during pricing configuration)
  • If not, Navigate to Setup > Products/Services > Configurable Options
  • Click Edit for the cPanel licensing option group
  • Ctrl + Click to select all the applicable products which should offer a cPanel license option (be sure to select the product currently exhibiting the error)
  • Click Save Changes
• If the cPanel License configurable option is displayed, select the desired cPanel license tier
• Click Save Changes
• Then use the Assign or Link button 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. Please 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:

• Navigate to the client's Products/Services tab for the service in question
• Use the cPanel License configurable option to select the desired cPanel license tier
• Click Save Changes
• Then use the Assign or Link button again to complete the task successfully