| Table of Contents |
|---|
About The Universal Module
The Universal Module is the module to use when no other module will do. In some cases you may find that you need a module to request fields from a client for a particular service that will be provisioned manually. Dedicated servers are a perfect example of this. With the Universal Module you can create these fields dynamically, and even have them send a post or email notification when the package or service is created or changes.
Using the Universal Module
Installing the Universal Module
- Visit [Settings] > [Company] > [Modules] > Available.
- Click the "Install" button within the Universal Module module listing.
When the module is installed, it should automatically load the "Manage" screen for the module. You can get back here any time by visiting [Settings] > [Company] > [Modules] > Installed and by clicking the "Manage" button for the module.
Products
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. 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.
| ||||||||||||||||||
| 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. If you've set the label to Email address then you'd likely want to set the name to email_address. A field name of qty has special meaning. It will set the quantity recorded for the service. | ||||||||||||||||||
| Type | The type of form field.
| ||||||||||||||||||
| 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
Using ':' or '|' in your fields
Both : and | are reserved characters, so if you'd like to use them in your value entry you must escape those characters with a \ (back slash).
Input Rules
Input rules are a JSON encoded object of input validation rules. They allow you to specify how each field should be validated against errors on input. For additional details on input rules see Error Checking. Let's take a look at an example:
{"hostname":{
"valid":{
"rule":"isEmpty",
"negate":true,
"message":"Hostname must not be empty"
}
}}
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.
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
Package option notifications are executed when an action is performed on the package.
| Option | Description | ||||||
|---|---|---|---|---|---|---|---|
| Notice | The action triggers the notification.
| ||||||
| 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 Notifications
Service option notifications are executed when an action is performed on the service.
| Option | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Notice | The action triggers the notification.
| ||||||||||||||||
| 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. |
Creating Packages
Email Tags
Universal Module product service field names are used for the email tag. For example, a service field with the name "hostname" would result in a tag available to the welcome email of {service.hostname}. Universal module products are unique in this regard because each product may have different tags, defined by the staff member who created them.