Revision as of 20:04, 10 April 2017

WHMCS 7.2 introduced the ability to associate Product Add-ons with Provisioning Modules.

Many provisioning modules require storing of additional information relating to a product. To make it easier to work with this extra data, and to aide module developers, WHMCS 7.2 introduces the concept of Service Properties.

A Service Property is a key/value pair relating to a given instance of a product or add-on. Stored in custom fields, service properties allow module developers to interact with these fields in a simple programmatic way that is consistent for both products and add-ons.

Using Service Properties

A model instance (see https://developers.whmcs.com/advanced/db-interaction/) that represents the Service or Addon that an action is being performed against is passed to all module function invocations as part of the module parameters.

An example scenario of how this might be used can be seen below.

/**
 * @param array $params
 *
 * @return string
 */
function samplemodule_CreateAccount(array $params)
{
    try {
        // Perform actions to provision service and receive back an order number
        $orderNumber = '12345';

        // Save order number to Service Properties
        $params['model']->serviceProperties->save(['Order Number' => $orderNumber]);

        return 'success';
    } catch (\Exception $e) {
        return $e->getMessage();
    }
}

function samplemodule_SuspendAccount(array $params)
{
	try {
		// Utilise Service Properties to retrieve the Order Number
		$orderNumber = $params['model']->serviceProperties->get('Order Number');

		// Perform actions using order number here

		return 'success';
        } catch (\Exception $e) {
            return $e->getMessage();
        }
}

The 'save' method will lookup a custom field with the given name. If no existing field is found, a new custom field will be created to store the value.

Supported Fields

When using Service Properties against a Service (ie a directly created product, and not an add-on), sometimes a dedicated core field will be used rather than a custom field. This occurs for the following field names.

• Username
• Password
• Domain
• License Key
• Dedicated IP
• Disk Usage
• Disk Limit
• Bandwidth Usage
• Bandwidth Limit
• Last Update

Using these field names with an add-on will create a custom field.