Revision as of 18:17, 19 April 2022

About this Addon Module

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.

Activating WHMCS cPanel Licensing Module

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

1. Download the latest version from the WHMCS Marketplace.
2. Extract the zip file.
3. Upload the cpanellicensing directory to the /modules/addons folder of your WHMCS installation.
4. Go to Configuration () > System Settings > Addon Modules or, prior to WHMCS 8.0, Setup > Addon Modules.
5. Click Activate for cPanel Licensing.
6. Click Configure.
7. Select the admin role groups who will have access to this addon.
8. Select the admin users who can configure settings within the addon.
9. Click Save Changes.

Using WHMCS cPanel Licensing Module

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.

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 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 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 () > 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:

1. Go 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 menu.
5. Click Save Changes.

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.

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

1. Go to Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services > Products/Services.
   

   Configure Pricing
2. Click Create a New Product.
3. Select Other for Product Type.
4. Enter a Product Name.
5. Select Auto Release for Module Name.
6. Click Continue.
7. Select the Pricing tab.
8. Choose Recurring for Payment Type.
   

   Configure the Auto Release Module
9. Check the checkboxes in the One Time/Monthly column.
10. Specify Setup and Price values of 0.00.
11. Select the Module Settings tab.
12. Choose the Automatically setup the product as soon as the first payment is received option.
13. Select the Configurable Options tab.
14. Click the configurable option group for the cPanel license types. The cPanel Licensing Addon creates this.
15. Configure any other options are desired.
16. 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.

Upgrading

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

1. Download the latest version from the WHMCS Marketplace.
2. Extract the zip file.
3. 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:

1. Navigate to the client's Products/Services tab for the service.
2. Check whether the cPanel Licenses configurable option appears. If it does not:
   1. Go to Configuration () > System Settings > Configurable Options or, prior to WHMCS 8.0, Setup > Products/Services > Configurable Options.
   2. Click Edit for the cPanel licensing option group.
   3. 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.
   4. Click Save Changes.
3. If the cPanel License configurable option is displayed, select the desired cPanel license tier.
4. Click Save Changes.
5. 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:

1. Go to the client's Products/Services tab for the service.
2. Use the cPanel License configurable option to select the desired cPanel license tier.
3. Click Save Changes.
4. Use the Assign or Link buttons again to complete the task successfully.

Change Log

N/A