Revision as of 14:16, 21 December 2015

Provisioning Modules, enable provisioning and management of services in WHMCS.

Provisioning Modules are also referred to as Product or Server Modules. The core function of a module is creating, suspending, unsuspending, and terminating of products. This happens as various events occur. These events include:

• New order payment
• Items becoming overdue
• Overdue invoice payment
• Cancellation requests.

A WHMCS module 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: https://github.com/WHMCS/sample-provisioning-module

Naming Conventions

Provisioning Modules are found in the /modules/servers/ directory. The module name chosen must be unique and should be all lowercase. The name must only contain letters & numbers whilst always starting with a letter.

Inside the module, function naming will follow a certain format. Functions have a prefix of the module filename, underscore, then the function name. For example a module "mymodule" would have the create function "mymodule_CreateAccount".

Product Configuration Options

The required function of all provisioning modules is the ConfigOptions function. This defines the settings that are configurable on a per product basis when a product uses the module. The name of this function must be mymodule_ConfigOptions matching the name of your module

There is a limited number of supported field types. These 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

Here is an overview of all functions that a WHMCS provisioning module can contain. Functions within a module are optional and need not be in the module if they don’t apply. Remember, all functions should have the prefix filename_ and then the function name. This is below in bold in the function descriptions.

• CreateAccount - This function runs when a new product provisions. This can be by WHMCS upon checkout or payment for a new order. Also, by an admin user from the Products/Services tab in a clients profile of the admin area.
• SuspendAccount - This function runs when a suspension is requested. Requested by the WHMCS Cron when a product becomes overdue, or by admin user in the Client Profile.
• UnsuspendAccount - This function runs when an unsuspension is requested. Requested upon payment of an overdue invoice for a product.
• TerminateAccount - This function runs when a termination is requested. Requested by the WHMCS Cron for long overdue products when enabled ([Automation_Settings#Enable_Termination]). Also requested by an admin user in the Client Profile.
• Renew - This function runs each time a renewal invoice for a product becomes paid.
• ChangePassword - This function runs as a client requests a password change. The option will not show up if the function is not defined in the module. The status of the product must also be active. Admins can also invoke this command from the admin area.
• ChangePackage - This function runs for upgrading and downgrading of products. This function runs when an upgrade or downgrade order placed by the client becomes paid. Admins can also invoke this from the product management pages. The same function runs 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. Output via a template file within the module folder named "clientarea.tpl" is also possible. Discussion of this function in more detail later on in the docs.
• AdminArea - Used to define HTML code that displays on server configuration page (Setup > Servers). Used to provide an automated shortcut/login link to the integrated server control panel.
• LoginLink - Used to define HTML code to link to the customers account on a server control panel. Displayed on the product management page of the admin area. The return must be HTML output or link (no forms).
• ClientAreaCustomButtonArray - Used to define custom functions that your module supports. Customers can invoke and run these from the client area. The functions can perform actions or product page output in the client area. Example usages for this are to provide product management pages, bandwidth reporting pages, etc…
• ClientAreaAllowedFunctions - Like the above, used to define custom functions. Customers can invoke, but are not shown as buttons by default. (i.e. custom client area output will invoke them).
• AdminCustomButtonArray - Used to define custom functions in your module for admin users. This can contain more functions than the client area equivalent.
• UsageUpdate - Used to perform a daily import of the disk and bandwidth usage from a server. The data imported is then used to display the usage stats both within the client and admin areas of WHMCS. The data is also used in disk and bandwidth overage billing calculations if enabled for a product.
• AdminServicesTabFields - Used to define extra fields or output to display within admin product pages.
• AdminServicesTabFieldsSave - Used in conjunction with the above. This function handles the values submitted in any custom fields when a save occurs.

Module Parameters

The module parameters are the data/values passed into each function when called. Every module function receives the same parameters. These parameters provide information about the specific product/service the module command runs for. The parameters also contains the settings from the product itself.

Config Options

Config Options (do not confuse with Configurable Options) are the module's settings. These are defined in the ConfigOptions function of the module. Config Options are set on a per product basis. Supplied as a numbered list: $params[‘configoption1’], $params[‘configoption2’], etc. Defined by the order specified in the ConfigOptions function of the module.

Custom Fields & Configurable Options

Values from any custom fields & configurable options are passed into modules as parameters. Passed as an array with the key being the name of the field or option.

For example for a custom field called “Username”, would become $params[‘customfields’][‘Username’]. Likewise, a configurable option named “Disk Space”, would become $params[‘configoptions’][‘Disk Space’]

Core Module Functions

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

These 7 functions all operate in a similar manner. They can run both manually and automatically. Each expected to return either a success or error response.

Response Handling

Each of these functions after running actions must either return a success or error.

For a successful result the code must actually return the word “success” to end the function. When WHMCS receives "success" it knows the function completed and continues on that basis.

Should the function fail, the return should be a user understandable error message, as it will display to staff users.

Action Events

When a function is successful, there are various actions that run 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

Besides the above actions, admin users receive a confirmation of functions completing, or errors in the case of failure. Functions invoked through automation, such as payment of a new order, that notification can be via email. In the case of ChangePassword, any errors returned are also displayed to client users.

Single Sign-On

Single sign-on can occur for a service or server.

Whichever method being used, the return should be the same.

The return from either function should always be an array and contain two keys of a possible three.

• success - This is a boolean value and should indicate success or failure
• redirectTo - This should be a fully formatted URL return from your SSO request
• errorMsg - Any appropriate error message to be displayed to whoever is making the request

Service Single Sign-On

Service single sign-on is to allow admin and client users to login to the control panel of the service automatically.

/**
 * Perform single sign-on for a given instance of a product/service.
 *
 * Called when single sign-on is requested for an instance of a product/service.
 *
 * When successful, returns a URL to which the user should be redirected.
 *
 * @param array $params common module parameters
 *
 * @see http://docs.whmcs.com/Provisioning_Module_SDK_Parameters
 *
 * @return array
 */
function mymodule_ServiceSingleSignOn(array $params)
{
	$return = array(
		'success' = false,
	);
	try {
        /**
         * all the service's single sign-on token retrieval function, using the
         * values provided by WHMCS in `$params`.
         * The variables and response format would depend on your server API
         */

        $response = $formattedResponse = custom_call_to_server();

        $return = array(
            'success' => true,
            'redirectTo' => $response['redirectUrl'],
        );
    } catch (Exception $e) {        
        $return['errorMsg'] = $e->getMessage();
        $response = $e->getMessage();
        $formattedResponse = $e->getTraceAsString();
    }

    /**
     * Log any call to the server
     */
	logModuleCall(
        'provisioningmodule',
        __FUNCTION__,
        $params,
        $response,
        $formattedResponse,
        array('username', 'password')
    );

}

Server Single Sign-On

Server single sign-on allows for Admin users to login to the associated server management panel (like WHM for cPanel) automatically.

/**
 * Perform single sign-on for a server.
 *
 * Called when single sign-on is requested for a server assigned to the module.
 *
 * This differs from ServiceSingleSignOn in that it relates to a server
 * instance within the admin area, as opposed to a single client instance of a
 * product/service.
 *
 * When successful, returns a URL to which the user should be redirected to.
 *
 * @param array $params common module parameters
 *
 * @see http://docs.whmcs.com/Provisioning_Module_SDK_Parameters
 *
 * @return array
 */
function mymodule_AdminSingleSignOn(array $params)
{
	$return = array(
		'success' = false,
	);
	try {
        /**
         * all the service's single sign-on token retrieval function, using the
         * values provided by WHMCS in `$params`.
         * The variables and response format would depend on your server API
         */

        $response = $formattedResponse = custom_call_to_server();

        $return = array(
            'success' => true,
            'redirectTo' => $response['redirectUrl'],
        );
    } catch (Exception $e) {        
        $return['errorMsg'] = $e->getMessage();
        $response = $e->getMessage();
        $formattedResponse = $e->getTraceAsString();
    }

    /**
     * Log any call to the server
     */
	logModuleCall(
        'provisioningmodule',
        __FUNCTION__,
        $params,
        $response,
        $formattedResponse,
        array('username', 'password')
    );

}

The UsageUpdate Function

The UsageUpdate function performs a daily import of the disk and bandwidth usage for accounts of a server. The data imported is then used to display the usage stats both within the client and admin areas of WHMCS. The data is also used in disk and bandwidth overage billing calculations if enabled for a product.

The UsageUpdate function runs via WHMCS Cron, for any active, enabled server. (important: Runs per server not per product). So, this can only run if your module has a server created in WHMCS for it - products alone do not invoke it.

The function receives the id, ip, hostname, username/hash, & password variables. The function will query the disk and bandwidth usage for the server, and updates the database. The database update should be a single call for speed and efficiency. An example of how to do this is below.

function mymodule_UsageUpdate($params) {

	$serverid = $params['serverid'];
	$serverhostname = $params['serverhostname'];
	$serverip = $params['serverip'];
	$serverusername = $params['serverusername'];
	$serverpassword = $params['serverpassword'];
	$serveraccesshash = $params['serveraccesshash'];
	$serversecure = $params['serversecure'];

	# Run connection to retrieve usage for all domains/accounts on $serverid

	# Now loop through results and update DB

	foreach ($results AS $domain=>$values) {
        update_query("tblhosting",array(
         "diskused"=>$values['diskusage'],
         "disklimit"=>$values['disklimit'],
         "bwusage"=>$values['bwusage'],
         "bwlimit"=>$values['bwlimit'],
         "lastupdate"=>"now()",
        ),array("server"=>$serverid,"domain"=>$values['domain']));
    }

}

Custom Functions

Custom functions allow definition of extra operations that run using the module. The custom functions can perform actions, or define extra client area pages/output. Permissions can be granted for who can use each custom function, be it just clients, just admins, or both.

The convention for custom function names follow the same as any other function of a module. It must begin with the module filename_, and then the custom function name.

The easiest way to show 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;

}

The above shows how to define custom functions and to used the passed variables. The custom function returns either “success” or an error message to show a failure. If we wanted to allow clients to perform reboots, but only admins to be able to perform a shutdown. We would define that like:

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

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

The above allows a clients to run the “reboot” function, and admins “reboot” and “shutdown”.

The key value of the array is what displays to admins/clients on the button or menu options for the commands. And the value is the custom function name excluding the modulename_ prefix.

A description of how to provide a button or way to invoke a custom function is in the Client Area Output section:

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

Client Area Output

Another key function of a module is to give clients access to extra options and output within the client area. Done either on the product details page (using the ClientArea function of a module), or as a custom function/action as above.

Product Details Page Output

Creating output to display on the same page as the product details in the client area is easy. Create a template file named “clientarea.tpl” within the module folder. This template file will process as a Smarty template file. This means it can make use of Smarty variables. The variables will be the same module vars as passed to every module function. Also, other smarty functions such as logic functions are available.

More advanced actions, such as performing API Calls or defining variables for the output are possible. A ClientArea function within the module that runs any code and returns an array with the template file to use, and any variables desired besides the defaults. Returning different template file values based on data in the $_GET or $_POST array data, allows for many pages which can have direct links.

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

Custom Pages

Situations that need a custom page, rather than output on the existing product details page, are possible. Done using functions as described earlier in this article, with that function returning an array as follows:

function mymodule_mycustomfunction($vars) {
    return array(
        'templatefile' => 'customfunc',
        'breadcrumb' => array(
            'stepurl.php?action=this&var=that' => 'Custom Function',
        ),
        'vars' => array(
            'test1' => 'hello',
            'test2' => 'world',
        ),
    );
}

Clients then need access to use this function, and a link in the product details page. Do this using the methods described in the ‘Custom Functions’ section above.

Admin Services Tab

Admin Services Tab functions allow definition of extra fields to appear on the product details in the admin area. Used for informational output, or for settings and values stored in custom tables or outside WHMCS.

WHMCS uses this in the core system for our licensing addon module. The license specific fields of the allowed system are set and viewed from the product details.

There are 2 functions relating to the services tab - AdminServicesTabFields and AdminServicesTab-FieldsSave. The first of these allows definition of the extra fields to output. The latter allows handling any input on submission/save, if required.

So on to an example, below we show you how to define 4 extra fields. This example shows an input, dropdown, textarea and info only output. The examples continues to update them in a custom table of the database via the save event.

function mymodule_AdminServicesTabFields($params) {

    $result = select_query("mod_customtable","",array("serviceid"=>$params['serviceid']));
    $data = mysql_fetch_array($result);
    $var1 = $data['var1'];
    $var2 = $data['var2'];
    $var3 = $data['var3'];
    $var4 = $data['var4'];

    $fieldsarray = array(
     'Field 1' => '<input type="text" name="modulefields[0]" size="30" value="'.$var1.'" />',
     'Field 2' => '<select name="modulefields[1]"><option>Val1</option</select>',
     'Field 3' => '<textarea name="modulefields[2]" rows="2" cols="80">'.$var3.'</textarea>',
     'Field 4' => $var4, # Info Output Only
    );
    return $fieldsarray;

}

function mymodule_AdminServicesTabFieldsSave($params) {
    update_query("mod_customtable",array(
        "var1"=>$_POST['modulefields'][0],
        "var2"=>$_POST['modulefields'][1],
        "var3"=>$_POST['modulefields'][2],
    ),array("serviceid"=>$params['serviceid']));
}

Module Logging

To make reviewing and debugging module calls easier, WHMCS has a built in logging function. This allows the record of the request and response strings for every call the module makes. This becomes available in an accessible way via the WHMCS admin interface. If you plan to release the module, this allows end users to troubleshoot and debug issues experienced using the module. This also allows you to be able to debug issues experienced while using it.

Logging is not something that is always enabled. This is to avoid logs growing too large, so it's something that needs enabling for the logging to occur. To toggle logging, goto Utilities > Logs > Module Debug Log. This is the same place to review the logs.

To utilise this functionality, the module needs to make a call as follows:

logModuleCall($module,$action,$requeststring,$responsedata,$processeddata,$replacevars);

• $module - The name of the module, for example "cpanel", "plesk", "resellerclub", etc...
• $action - This should be the action running, ie. create, suspend, register, etc...
• $requeststring - This should be the variables passed to the remote API. This can be in either string or array format.
• $responsedata - The return of the raw API response. This can be in either string or array format also.
• $processeddata - Like the above, Used for a post processing API response. Such as after conversion into a friendly format, an array for example.
• $replacevars - This accepts an array of strings to replace. So, for example, the module might want to pass the username and password for the API into this function. The function replaces the data with *'s wherever they appear in the request or response strings for extra security.

App Store

WHMCS offers an app store which accepts submission of the completed module. Displayed listed are found under the Addons tab within the administration area and online at http://www.whmcs.com/appstore . This is a great way to make WHMCS users aware of the module.

Submission of a listing requires a login for whmcs.com/members, if you do not have one please Contact Us. Once logged in, visit the app store page at the above URL and click the "Submit your Addon" link. We aim to review submissions in 1-2 weeks.