Revision as of 18:11, 29 October 2011

Provisioning Modules, also referred to as Product or Server Modules, allow you to create modules to allow for the provisioning and management of products & services in WHMCS.

The core functionality of a module is for creating, suspending, unsuspending & terminating of products as various events occur such as new orders being paid for, items becoming overdue, overdue invoices being paid & cancellations being requested. But a module in WHMCS can do much more than just that, including automated password resets, upgrades/downgrades, renewals, admin based links, client area output, and more via custom functions.

Other types of modules that can be created in WHMCS are Payment Gateways, Domain Registrars and Addons.

Getting Started

Begin by downloading the Provisioning Module Template File here to refer to

Naming Conventions

Provisioning Modules are stored in the /modules/servers/ directory. The module name you choose must be unique, and should be all lowercase, containing only letters & numbers, always starting with a letter.

Within the module itself, all functions must be prefixed with the module filename, followed by an underscore, and then the function name. For example if your module was called "mymodule" the create function would be named as "mymodule_CreateAccount".

Product Configuration Options

The required function of all provisioning modules is the ConfigOptions function. This is what defines the settings that can be configured on a per product basis when assigning a product to the module. The name of this function must be mymodule_ConfigOptions matching the name of your module.

The supported field types are Text, Password, Yes/No Checkboxes, Dropdown Menus, Radio Buttons & Text Areas

Below are examples of the available parameters for each field type. Provisioning modules support up to 24 options defined in this way.

$configarray = array(
    "username" => array (
        "FriendlyName" => "UserName",
        "Type" => "text", # Text Box
        "Size" => "25", # Defines the Field Width
        "Description" => "Textbox",
        "Default" => "Example",
    ),
    "password" => array (
        "FriendlyName" => "Password",
        "Type" => "password", # Password Field
        "Size" => "25", # Defines the Field Width
        "Description" => "Password",
        "Default" => "Example",
    ),
    "usessl" => array (
        "FriendlyName" => "Enable SSL",
        "Type" => "yesno", # Yes/No Checkbox
        "Description" => "Tick to use secure connections",
    ),
    "package" => array (
        "FriendlyName" => "Package Name",
        "Type" => "dropdown", # Dropdown Choice of Options
        "Options" => "Starter,Advanced,Ultimate",
        "Description" => "Sample Dropdown",
        "Default" => "Advanced",
    ),
    "disk" => array (
        "FriendlyName" => "Disk Space",
        "Type" => "radio", # Radio Selection of Options
        "Options" => "100MB,200MB,300MB",
        "Description" => "Radio Options Demo",
        "Default" => "200MB",
    ),
    "comments" => array (
        "FriendlyName" => "Notes",
        "Type" => "textarea", # Textarea
        "Rows" => "3", # Number of Rows
        "Cols" => "50", # Number of Columns
        "Description" => "Description goes here",
        "Default" => "Enter notes here",
    ),
);
return $configarray;

Supported Functions

What follows here is a brief overview of all the possible functions that a product provisioning module in WHMCS can contain. All functions within a module are optional and can be omitted from the module if they don’t apply. Within the code itself, all functions are prefixed with the module filename, followed by an underscore, and then the function name as shown in bold in these descriptions.

• CreateAccount - This function is called when a new product is due to be provisioned. This can be invoked automatically by WHMCS upon checkout or payment for a new order, or manually by an admin user from the Products/Services tab under a clients profile within the admin area.
• SuspendAccount - This function is called when a suspension is requested. This is invoked automatically by WHMCS when a product becomes overdue on payment, or can be called manually by admin user.
• UnsuspendAccount - This function is called when an unsuspension is requested. This is invoked automatically upon payment of an overdue invoice for a product.
• TerminateAccount - This function is called when a termination is requested. This can be invoked automatically for long overdue products if enabled (auto termination is disabled by default in Setup > Automation Settings) or requested manually by an admin user.
• Renew - This function is called each time a renewal invoice for a product is paid.
• ChangePassword - This function is called when a client requests a password change from the client area. For this option to show up this function must be declared in the module, the status of the product must be active. Admins can also invoke this command from the admin area.
• ChangePackage - This function is used for upgrading and downgrading of products. This function will be called automatically when an upgrade or downgrade order placed by the client is paid for, or can be invoked manually by admin users from the product management pages. This same function is called for upgrades and downgrades of both products and configurable options.
• ClientArea - This function can be used to define module specific client area output. It accepts a return of HTML for display on the product details page of the client area. The output can alternatively be specified via a template file within the module folder named “clientarea.tpl” to allow for end user customisation. This function is discussed in more detail later on in the docs.
• AdminArea - This function is used to define HTML code to be displayed within the admin area server configuration page (Setup > Servers) and is commonly used to provide an automated shortcut/login link to the server control panel being integrated with.
• LoginLink - This function can be used to define HTML code used to link specifically to the customers account within a servers control panel. It is displayed on the product management page within the admin area if defined and must be an HTML output or link (no forms).
• ClientAreaCustomButtonArray - This function can be used to define custom functions that your module supports that customers are allowed to invoke and run from the client area. These functions can perform actions or product page output in the clientarea. Some example usages for this are to provide product management pages, bandwidth reporting pages, etc…
• AdminCustomButtonArray - This function can be used to define custom functions that your module supports, similar to the above, but that admin users are allowed to run. This can contain more functions than the client area is allowed.
• UsageUpdate - This function is used to perform a daily import of the disk and bandwidth usage for accounts from a server. The data imported is then used to display the usage stats both within the client and admin areas of WHMCS, and also in disk and bandwidth overage billing calculations if enabled for a product.
• AdminServicesTabFields - This function can be used to define additional fields and output to be displayed on the admin product management pages.
• AdminServicesTabFieldsSave - This function is used in conjunction with the above to handle the values submitted in any custom fields when a save request is submitted.

Module Parameters

The module parameters are the data/values passed into each function when called. Every module function is passed the same parameters. These variables provide information about the specific product/service the module command is being invoked for, along with the settings from the product itself as defined in the product configuration.

Config Options

Config options (not to be confused with Configurable Options) are the module settings defined on a per product basis. These are supplied as a numbered list, so the first option would be $params[‘configoption1’] , the second $params[‘configoption2’], etc… The order is defined by the order in which you specify the settings in the ConfigOptions function of the module.

Custom Fields & Configurable Options

The values from any custom fields & configurable options are loaded and passed into modules as parameters so that they can be easily used. They are passed as an array with the key being the name of the field or option.

For example if you created a custom field called “Username”, then that would be referenced using $params[‘customfields’][‘Username’] Similarly if you created a configurable option named “Disk Space”, then that would be referenced using $params[‘configoptions’][‘Disk Space’]

Core Module Functions

The core module functions are the Create, Suspend, Unsuspend, Terminate, Renew, ChangePassword and ChangePackage functions.

These 7 functions all operate in a very similar manner. They can all be invoked both manually and automatically, and they are all expected to return either a success or error response.

Response Handling

Each one of these functions after performing the actions they are required to, must either return a success message or error response.

For a successful result the code must actually return the word “success” to end the function. If WHMCS receives that it will know that the function completed as intended and continue on that basis.

However, should the function fail, what you return should be a user understandable error message, as it will be displayed directly to staff users.

Action Events

When a function is successful, there are various actions that are performed as follows:

• CreateAccount - Changes status to Active + Sends Product Welcome Email
• SuspendAccount - Changes status to Suspended
• UnsuspendAccount - UnsuspendAccount
• TerminateAccount - Changes status to Terminated
• ChangePassword - Updates password in database

In addition to the above actions, admin users are given a confirmation of successful functions completing, and errors in the case of them failing. If the functions were invoked automatically such as on payment of a new order, then that notification can be in the form of an email. And in the case of the ChangePassword function, any errors returned from that function are also displayed to end users within the client area also.

Client Area Output

Another key function of a module is to give the client access to options within the client area. This is done using the ClientArea function of a module, which can simply return HTML output to be displayed. But the recommended method is creating a template file and specifying for the module to use that. This is done as follows.

The template file will be called with all the same module parameters as other functions get defined, along with any custom variables you define from the _ClientArea function, ready to use as regular smarty template variables.

function mymodule_ClientArea($vars) {
    return array(
        'templatefile' => 'clientarea',
        'vars' => array(
            'test1' => 'hello',
            'test2' => 'world',
        ),
    );
}

The above example would use the clientarea.tpl template file from the module folder.

Custom Functions

Custom functions allow you to define additional operations that can be performed using the module. The custom functions can do anything you want, and return either a success or failed response. Permission can then be granted for who can use each custom function, be it just clients, just admins, or both.

The naming convention for custom functions follows the same as any other function within a module so it must begin with the module filename, followed by an underscore, and then the custom function name.

The easiest way to demonstrate this is with an example so let’s take an example of a reboot & shutdown function in a VM/VPS system:

function template_reboot($params) {

	# Code to perform reboot action goes here...

    if ($successful) {
		$result = "success";
	} else {
		$result = "Error Message Goes Here...";
	}
	return $result;

}

function template_shutdown($params) {

	# Code to perform shutdown action goes here...

    if ($successful) {
		$result = "success";
	} else {
		$result = "Error Message Goes Here...";
	}
	return $result;

}

In the above you can see how the custom functions are defined, being passed all the same module parameters as all other functions, & returning either “success” for a success or an error message to indicate a failure. Now let’s say we wanted to allow clients to perform reboots, but only admin users to be able to perform a shutdown, here’s how we would define that:

function template_ClientAreaCustomButtonArray() {
    $buttonarray = array(
	 "Reboot Server" => "reboot",
	);
	return $buttonarray;
}

function template_AdminCustomButtonArray() {
    $buttonarray = array(
	 "Reboot Server" => "reboot",
	 "Shutdown Server" => "shutdown",
	);
	return $buttonarray;
}

What we are saying here is that clients are allowed perform the “reboot” function, but admins can perform both “reboot” and “shutdown”.

The text that’s the key part of the array is what’s displayed on the button in the row of module command buttons to an admin user, and the value is the custom function name excluding the modulename_ prefix.

So now all that’s left is to give the client the option to perform the custom function from the client area, and for that we go back to the previous section on Client Area Output and within the template you can define a button to call the custom function as follows:

<form method="post" action="clientarea.php?action=productdetails">
<input type="hidden" name="id" value="{$serviceid}" />
<input type="hidden" name="modop" value="custom" />
<input type="hidden" name="a" value="reboot" />
<input type="submit" value="Reboot VPS Server" />
</form>