...
| Excerpt |
|---|
|
The Universal Module is the module to use when no other module will do. It allows you to specify what fields to ask for during checkout, and can even interact with a 3rd party API for provisioning of services. This is a powerful replacement to the "none" module in previous versions of Blesta. |
| Table of Contents |
|---|
| Table of Contents |
|---|
| maxLevel | 4 |
|---|
| minLevel | 2 |
|---|
| outline | true |
|---|
| class | toc |
|---|
|
|
About The Universal Module
...
A Universal Module Product is a collection of package and service request fields, along with a few rules that apply to the product. The product acts as a template for creating packages and services.
Module Options
| Option | Description |
|---|
| Name | The name for the product, shown when creating or editing a package. |
Package Options
Package options are fields that are requested when a package is added or updated. A product can have any number of package options.
| Option | Description |
|---|
| Label | The display name of the form field. |
| Name | The name of the input field. This is the name of the value sent in all post and email notifications, and is also used when validating input rules. | Info |
|---|
If you've set the label to Email address then you'd likely want to set the name to email_address. |
|
| Type | The type of form field. | Option | Description |
|---|
| Text | A regular text input field. | | Textarea | A large text area field, for inserting multiple lines of text. | | Password | A password input field, masking the user's input. | | Select | A drop-down menu. | | Radio | A radio field. | | Checkbox | A checkbox field. | | Hidden | A hidden field not visible to the user. | | Secret | A field that is never rendered or stored for the package, but is sent in all post and email notifications. |
|
| Required | If enabled, will require that some value is given for the field. |
| Encrypt | If enabled, will store input values encrypted in the database. |
| Values | See Values Format. |
| Input Rules | See Input Rules. |
| Notifications | See Notifications. |
Service Options
Service options are fields that are requested when a service is added or updated. A product can have any number of service options.
| Option | Description |
|---|
| Label | The display name of the form field. |
| Name | The name of the input field. This is the name of the value sent in all post and email notifications, and is also used when validating input rules. | Info |
|---|
If you've set the label to Email address then you'd likely want to set the name to email_address. |
| Note |
|---|
A field name of qty has special meaning. It will set the quantity recorded for the service. |
|
| Type | The type of form field. | Option | Description |
|---|
| Text | A regular text input field. | | Textarea | A large text area field, for inserting multiple lines of text. | | Password | A password input field, masking the user's input. | | Select | A drop-down menu. | | Radio | A radio field. | | Checkbox | A checkbox field. | | Hidden | A hidden field not visible to the user. | | Secret | A field that is never rendered or stored for the service, but is sent in all post and email notifications. |
|
| Required | If enabled, will require that some value is given for the field. |
| Encrypt | If enabled, will store input values encrypted in the database. |
| Values | See Values Format. |
| Input Rules | See Input Rules. |
| Notifications | See Notifications. |
Values Format
The values field is a serialized list of field data in the format of name:value, delimited by the | (pipe) character. The name is the value stored for the field and value is the value displayed. For example, if you would like to request a list of check boxes of various flavors of ice cream you might enter: vanilla:Vanilla|chocolate:Chocolate|strawberry:Strawberry|rocky_road:Rocky Road
...
| Code Block |
|---|
|
{
"hostname":{
"valid":{
"rule":"isEmpty",
"negate":true,
"message":"Hostname must not be empty."
}
},
"password":{
"valid":{
"rule":["matches", "/^[a-z0-9]{10,20}$/i"],
"message":"Please enter a password using alphanumeric characters between 10 and 20 characters in length."
}
}
} |
In the above example we're validating the hostname field using the isEmpty rule and negating it using the negate attribute. This ensures that the hostname field is not empty when submitted. If the rule validation fails (hostname is empty) the message we defined using the message attribute will be displayed to the user. We are also validating the password field at the same time using the matches rule, which evaluates a given regular expression. This rule requires that the password contain between 10 and 20 characters, inclusive, all of which must be characters of any combination from A through Z, upper or lower case, and the digits 0 through 9.
Notifications
Notifications allow the universal module to post to a given URL or email a given address when a certain action occurs.
...
Package option notifications are executed when an action is performed on the package.
| Option | Description |
|---|
| Notice | The action triggers the notification. | Option | Description |
|---|
| Add | Executed when a package is created. | | Edit | Executed when a package is updated. |
|
| Post URL/Email | The URL to post to, or the email address to email, when the notice is triggered |
| HTTP Code | The HTTP Response Code returned by the URL that signifies a successful transmission. |
| Response Contains | Some portion of the output returned by the URL that signifies a successful transmission. This can be used separately, or in conjunction with the HTTP Code for more refined control over successful responses. |
| From Email | The address to send email notifications from. |
| Subject | The subject of the email notification. |
| HTML/Text | The HTML and Text body content for the email notification. |
Package Option Notification Tags
The package option notification emails allow for the following tags:
| Tags | Description | Notes | Version |
|---|
{*} | The value submitted for this custom field | {*} is NOT an actual tag. Every custom package field has a tag associated with it, this tag is labeled by the fields name represented here by * (e.g. {my_field}) |
|
|
| {*_name} | The label associated with the submitted value for fields of type select or radio | This tag is only available for radio and select fields (e.g. {my_field_name}) | 4.1 |
| {*_values} | A list of checked boxes for this field each containing the box's label and value | This tag is only available for checkbox fields (e.g. {my_field_values}) | 4.1 |
| {_action} | The code of the action for which this notification is being sent |
|
| 4.1 |
| {_package.id} | The system-level service ID | The _package tag is not available for the package addition notification | 4.1 |
| {_package.description} | The package's description |
|
| 4.1 |
| {_package.module_row} | The ID of the module row the package is associated with |
|
| 4.1 |
{_package.status}
| The status of the package |
| Info |
|---|
|
The {*_values} tag contains data in the following format. For a guide on using email tags in Blesta see the Customizing Emails page.
custom_1_values = array(
array(
'value' => '1',
'name' => 'Option 1'
),
array(
'value' => '2',
'name' => 'Option 2'
)
);
|
...
Service option notifications are executed when an action is performed on the service.
| Option | Description |
|---|
| Notice | The action triggers the notification. | Option | Description |
|---|
| Add | Executed when a service is created. | | Edit | Executed when a service is updated. | | Suspend | Executed when a service is suspended. | | Unsuspend | Executed when a service is unsuspended. | | Cancel | Executed when a service is canceled. | | Renew | Executed when a service is renewed. That is, the invoice generated for the service renewal is paid. | | Package Change | Executed when the package is changed for the service. |
|
| Post URL/Email | The URL to post to, or the email address to email, when the notice is triggered |
| HTTP Code | The HTTP Response Code returned by the URL that signifies a successful transmission. |
| Response Contains | Some portion of the output returned by the URL that signifies a successful transmission. This can be used separately, or in conjunction with the HTTP Code for more refined control over successful responses. |
| From Email | The address to send email notifications from. |
| Subject | The subject of the email notification. |
| HTML/Text | The HTML and Text body content for the email notification. |
Service Option Notification Tags
The service option notification emails allow for the following tags:
| Tags | Description | Notes | Version |
|---|
{*} | The value submitted for this custom field | {*} is NOT an actual tag. It is only a placeholder in this documentation. Every custom service field has a tag associated with it, this tag is labeled by the fields name represented here by * (e.g. {my_field}) |
|
|
| {*_name} | The label associated with the submitted value for fields of type select or radio | This tag is only available for radio and select fields (e.g. {my_field_name}) | 4.1 |
| {*_values} | A list of checked boxes for this field each containing the box's label and value | This tag is only available for checkbox fields (e.g. {my_field_values}) | 4.1 |
| {_action} | The code of the action for which this notification is being sent |
|
| 4.1 |
| {_service.id} | The system-level service ID | The _service tag is not available for the service addition notification | 4.1 |
| {_service.status} | The service status |
|
| 4.1 |
| {_service.date_added} | The UTC datetime stamp of the date the service was added | Formatted as "YYYY-MM-DD HH:MM:SS" | 4.1 |
| {_service.date_renews} | The UTC datetime stamp of the service renew date | Formatted as "YYYY-MM-DD HH:MM:SS" | 4.1 |
| {_service.date_last_renewed} | The UTC datetime stamp of the service's last renew date | Formatted as "YYYY-MM-DD HH:MM:SS" | 4.1 |
| {_service.date_suspended} | The UTC datetime stamp of the date the service was suspended | Formatted as "YYYY-MM-DD HH:MM:SS" | 4.1 |
| {_service.date_canceled} | The UTC datetime stamp of the date the service was canceled | Formatted as "YYYY-MM-DD HH:MM:SS" | 4.1 |
| {_package.id} | The system-level service ID |
|
| 4.1 |
| {_package.description} | The package's description |
|
| 4.1 |
| {_package.module_row} | The ID of the module row the package is associated with |
|
| 4.1 |
| {_package.status} | The status of the package |
|
| 4.1 |
| {_other.*} | The _other tag contains additional information, most of which is received through user input | Here * is the name of the field to access from the other tag (e.g. pricing_id) |
| Info |
|---|
|
The {*_values} tag contains data in the following format. For a guide on using email tags in Blesta see the Customizing Emails page.
custom_1_values = array(
array(
'value' => '1',
'name' => 'Option 1'
),
array(
'value' => '2',
'name' => 'Option 2'
)
);
|
...
| Expand |
|---|
|
Due to the nature of tag objects containing several fields, many of which are likely irrelevant for use in email templates, but may be useful to you in certain circumstances, a dump of the tags are shown below.
| Code Block |
|---|
| title | The {service} object |
|---|
| collapse | true |
|---|
| stdClass Object
(
[id] => 234
[parent_service_id] =>
[package_group_id] => 1
[id_format] => PD-{num}
[id_value] => 229
[pricing_id] => 22
[client_id] => 3
[module_row_id] => 6
[coupon_id] =>
[qty] => 1
[status] => in_review
[date_added] => 2013-05-13 18:33:14
[date_renews] => 2013-06-13 18:33:14
[date_last_renewed] =>
[date_suspended] =>
[date_canceled] =>
[id_code] => PD-229
[fields] => Array
(
[0] => stdClass Object
(
[key] => cpanel_confirm_password
[value] => password
[serialized] => 0
[encrypted] => 1
)
[1] => stdClass Object
(
[key] => cpanel_domain
[value] => domain.com
[serialized] => 0
[encrypted] => 0
)
[2] => stdClass Object
(
[key] => cpanel_password
[value] => password
[serialized] => 0
[encrypted] => 1
)
[3] => stdClass Object
(
[key] => cpanel_username
[value] => domainco
[serialized] => 0
[encrypted] => 0
)
)
[package_pricing] => stdClass Object
(
[id] => 22
[package_id] => 13
[term] => 1
[period] => month
[price] => 8.0000
[setup_fee] => 0.0000
[cancel_fee] => 0.0000
[currency] => USD
)
[package] => stdClass Object
(
[id] => 13
[id_format] => {num}
[id_value] => 1
[module_id] => 4
[name] => Bronze Standard
[description] =>
[description_html] => <p>
<span style="color:#008000;"><em>Good Value!</em></span></p>
[qty] =>
[module_row] => 6
[module_group] =>
[taxable] => 0
[status] => active
[company_id] => 1
)
[name] => domain.com
[coupon] => stdClass Object
(
[id] => 2
[code] => knW3Lesn
[company_id] => 1
[used_qty] => 16
[max_qty] => 0
[start_date] => 2017-02-02 08:00:00
[end_date] => 2018-02-03 07:59:59
[status] => active
[recurring] => 0
[limit_recurring] => 0
[apply_package_options] => 1
[internal_use_only] => 0
[type] => exclusive
[amounts] => Array
(
[0] => stdClass Object
(
[coupon_id] => 2
[currency] => USD
[amount] => 5.0000
[type] => amount
)
)
[packages] => Array
(
[0] => stdClass Object
(
[coupon_id] => 2
[package_id] => 80
)
)
)
) |
| Code Block |
|---|
| title | The {package} object |
|---|
| collapse | true |
|---|
| stdClass Object
(
[id] => '94'
[id_format] => '{num}'
[id_value] => '92'
[module_id] => '2'
[name] => 'Test Universal Package'
[description] => 'A test package for the universal module.'
[description_html] => '<p>A test package for the Universal Module.</p>'
[qty] => null
[module_row] => '1'
[module_group] => null
[taxable] => '1'
[single_term] => '0'
[status] => 'active'
[company_id] => '1'
[prorata_day] => null
[prorata_cutoff] => null
[id_code] => '92'
[email_content] => Array
(
[0] => stdClass Object
(
[lang] => 'en_us'
[html] => '<p>Welcome email for the Universal Module.</p>'
[text] => 'Welcome email for the Universal Module.'
)
)
[pricing] => Array
(
[0] => stdClass Object
(
[id] => '628'
[pricing_id] => '875'
[package_id] => '94'
[term] => '1'
[period] => 'month'
[price] => '2500.0000'
[setup_fee] => '0.0000'
[cancel_fee] => '0.0000'
[currency] => 'USD'
)
)
[meta] => stdClass Object
[groups] => Array
(
[0] => stdClass Object
(
[id] => '10'
[name] => 'Test Universal Package Group'
[description] => null
[type] => 'standard'
[company_id] => '1'
[allow_upgrades] => '1'
)
)
[option_groups] => Array
(
[0] => stdClass Object
(
[id] => '26'
[name] => 'Test Universal Option Group'
[description] => 'A list of options'
)
)
) |
|
...