Difference between revisions of "Service Properties"

From WHMCS Documentation

m
Line 1: Line 1:
 +
WHMCS 7.2 introduced the ability to associate Product Add-ons with Provisioning Modules. 
  
−
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.
+
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.
  
−
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.
+
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===
 
===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.
+
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.
  
−
====Scenario====
+
An example scenario of how this might be used can be seen below.
−
As a module developer, I wish to store an Order Number in a custom field which may be used for future commands.
 
  
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
Line 21: Line 21:
 
{
 
{
 
     try {
 
     try {
−
         //Actions already completed here to create the order and provision it
+
         // Perform actions to provision service and receive back an order number
−
         //The data is being stored in the $order variable.
+
         $orderNumber = '12345';
  
−
        $orderNumber = $order['order_number'];
+
         // Save order number to Service Properties
−
 
 
−
         // store order number against the current model and service properties
 
 
         $params['model']->serviceProperties->save(['Order Number' => $orderNumber]);
 
         $params['model']->serviceProperties->save(['Order Number' => $orderNumber]);
  
Line 38: Line 36:
 
{
 
{
 
try {
 
try {
−
//Utilise Service Properties to get the data from the name Order Number
+
// Utilise Service Properties to retrieve the Order Number
−
        $orderNumber = $params['model']->serviceProperties->get('Order Number');
+
$orderNumber = $params['model']->serviceProperties->get('Order Number');
  
−
        //Actions to be completed here to suspend the order
+
// Perform actions using order number here
−
 
 
−
        return 'success';
 
−
    } catch (\Exception $e) {
 
−
        return $e->getMessage();
 
−
    }
 
  
 +
return 'success';
 +
        } catch (\Exception $e) {
 +
            return $e->getMessage();
 +
        }
 
}
 
}
  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
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 '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.
−
The 'get' method will find the data for the passed field name.
 
  
 
===Supported Fields===
 
===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.
+
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
 
* Username
Line 70: Line 66:
 
* Last Update
 
* Last Update
  
−
Using these field names with an addon will still create the appropriate custom field.
+
Using these field names with an add-on will create a custom field.

Revision as of 20:03, 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.

Retrieved from "http://3.17.75.209/index.php?title=Service_Properties&oldid=22255"