Revision as of 10:38, 6 April 2017

Introduced in WHMCS 7.2 is the ability to associate a module with a product addon. As part of this, custom fields were also added. To make it simple to integrate with Custom Fields and modules, WHMCS has added serviceProperties to the Service and Addon models so that a custom field can by dynamically created as it is needed. This removes the need for module developers to instruct on specific custom fields to be created.

Service Properties can also save specific fields that may be directly associated with a service, but might not exist with an addon. See Supported Fields below for more detail.

Using Service Properties

Included in the params array passed to each module function is now a model key. This is the model of either the Service or Addon that the action is being run against.

Scenario

As a module developer, I wish to store an Order Number in a custom field which may be used for future commands.

/**
 * @param array $params
 *
 * @return string
 */
function samplemodule_CreateAccount(array $params)
{
    try {
        //Actions already completed here to create the order and provision it
        //The data is being stored in the $order variable.

        $orderNumber = $order['order_number'];

        // store order number against the current model and 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 get the data from the name Order Number
        $orderNumber = $params['model']->serviceProperties->get('Order Number');

        //Actions to be completed here to suspend the order

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

}

The 'save' method looks for a custom field with the name "Order Number" and saves the data passed to it. If the custom field does not exist, then it is created as an Admin Only field, and the data is stored. The 'get' method will find the data for the passed field name.

Supported Fields

When using service properties on a Service (ie a directly created product, and not an addon), the appropriate field in tblhosting will be updated, and a custom field will not be created.

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

Using these field names with an addon will still create the appropriate custom field.