Service Properties - Revision history

SarahK at 20:54, 3 May 2022

2022-05-03T20:54:02Z

John at 16:47, 24 April 2017

2017-04-24T16:47:58Z

Matt: Matt moved page ServiceProperties to Service Properties without leaving a redirect

2017-04-10T20:04:40Z

Matt moved page ServiceProperties to Service Properties without leaving a redirect

Matt at 20:03, 10 April 2017

2017-04-10T20:03:02Z

Andrew at 10:38, 6 April 2017

2017-04-06T10:38:49Z

Andrew: Created page with "Service Properties 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 int..."

2017-04-06T10:38:39Z

Created page with "Service Properties 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 int..."

New page

Service Properties

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.

<syntaxhighlight lang="php">

/**
* @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();
}

}

</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 '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.

@@ Line 1: / Line 1: @@
-<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.2 and above</div>
+<div class="docs-alert-info"><i class="fa fa-question-circle"></i>We added service properties in WHMCS 7.2.</div>
-WHMCS 7.2 introduced the ability to associate Product Add-ons with Provisioning Modules.
+In WHMCS 7.2 and later, you can associate [[Product Addons|product addons]] 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.
+Many provisioning modules require storage of additional information relating to a product. Service properties are key/value pairs for a specific instance of a product or addon, and they facilitate storing and working with extra data. Service properties use custom fields to store this data in a consistent format that provisioning modules can access programmatically.
 ===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.
+A [https://developers.whmcs.com/advanced/db-interaction/ model instance] that represents the service or addon that the module is performing an action 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.
+For example:
 <syntaxhighlight lang="php">
@@ Line 51: / Line 49: @@
 </syntaxhighlight>
-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 <tt>save</tt> method will look up a custom field with the given name. If it does not find an existing field, it will create a new custom field 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.
+When using service properties against a service (for example, a directly-created product and not an addon), the system may use a dedicated core field rather than a custom field. This occurs for the following field names.
 * Username
@@ Line 68: / Line 66: @@
 * Last Update
-Using these field names with an add-on will create a custom field.
+Using these field names with an addon will create a custom field.

← Older revision		Revision as of 16:47, 24 April 2017
Line 1:		Line 1:
		+	<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.2 and above</div>
		+
	WHMCS 7.2 introduced the ability to associate Product Add-ons with Provisioning Modules.		WHMCS 7.2 introduced the ability to associate Product Add-ons with Provisioning Modules.

← Older revision		Revision as of 10:38, 6 April 2017
Line 1:		Line 1:
−	~~Service Properties~~

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

← Older revision	Revision as of 20:04, 10 April 2017
(No difference)

@@ Line 1: / Line 1: @@
-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===
-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.
 <syntaxhighlight lang="php">
@@ Line 21: / Line 21: @@
+{
      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
          $params['model']->serviceProperties->save(['Order Number' => $orderNumber]);
@@ Line 38: / Line 36: @@
+{
 	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
+}
 </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.
 ===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
@@ Line 70: / Line 66: @@
 * 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.