Difference between revisions of "WHMCS cPanel Licensing Module"

Revision as of 13:56, 23 August 2019

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.

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 can be any of the five Email Types. 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.

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

Pricing

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.

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

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

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

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.

@@ Line 122: / Line 122: @@
 ====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.

Documentation