Notification configuration starts with preparing notification templates. A newly installed system has a basic set of generic templates that you can modify, or you can create new ones.
Using Placeholders
Placeholders are an important tool for creating customized messages. Custom messages include customer-specific (or subscription-specific, or order-specific) data that is retrieved from the database by means of placeholders. Each placeholder indicates which piece of data is retrieved from a database and inserted into a message.
There are four kinds of placeholders:
- Single data field: Such placeholders start with
@@and end with@. They represent a single value, such as an order number (@@DocNUM@). - Dataset: Such placeholders are always used twice, as a beginning placeholder (starting with ## and ending with #) and as an ending placeholder (starting with
##/and ending with#). They indicate that the message text between the beginning placeholder and the end placeholder must be repeated as many times for as many records are returned for the dataset represented by this placeholder. Such placeholders are used, for example, to retrieve order details:##DetailList#and##/DetailList#. - Subtemplate: A subtemplate is used in the same way as a single data field placeholder, though it is not strictly a placeholder. Subtemplates always have custom names, while placeholders cannot be edited. Subtemplates allow you identify general data used in a number of general templates, give it a custom name and then use it in any general template in the same way as placeholders. Common details in a subtemplate are AR document details, a footer and header, information on how to renew a subscription, order details, and style code (HTML). A subtemplate cannot be sent separately, but as a part of a notification template.
- Subplaceholder: Billing allows you to partition placeholders with a string type value. If a placeholder value contains the special character “|”, this placeholder is split into two or more (depending on the number of a special character occurrences) subplaceholders. A subplaceholder name is formed as follows:
PlaceholderName_SequenceNumber. The first subplaceholder value is data before the first special character occurrence, the second subplaceholder value is data between the first and the second special character occurrence, and so on. For example, a description for a subscription period setup fee is “Hosting package |Once-off Fee”. The@@Detail_Comment@placeholder value is “Hosting package Once-off Fee”. There is the only special character occurrence, so two subplaceholders are created:@@Detail_Comment_1@(Hosting package) and@@Detail_Comment_2@(Once-off Fee).
A placeholder is replaced with an actual parameter's value only if a Billing object and its parameters' values exist in a database. Otherwise, a placeholder value is an empty string.
Billing is delivered with a default set of placeholders; a provider can also create placeholders. Placeholder sources are notification templates (default set of placeholders), service templates and customer attributes.
A notification template type (Message Type parameter) determines data which can be used in messages. Namely, a set of placeholders is available. Each notification type has a unique set of placeholders that are not available to other notification types. For example, placeholders of the Order notification type represent order details: a type, number, set of order details, and so on.
Note: Placeholders of vendor and customer details are shared between all notification types.
Some external systems may require a customer to provide additional data as well as general information about their service plan purchase. This additional data is presented in Billing as service parameters and is managed on the service template side. For example, the DomainID parameter is for a domain service template, the LoginID and PasswordID parameters are for hosting service templates. These are system parameters added automatically on a service template creation. A provider can add parameters manually. After a service parameter is configured, a placeholder of the following kind is available: @@<ParameterID>@. For example, the @@DomainID@ placeholder corresponds with the DomainID service parameter that is required to purchase a domain.
Customer attributes hold optional customer information, for example, a birthday date, and ID number. Customer attributes are configured in System > Settings > Attributes. After an attribute is configured, a placeholder of the following kind is available: @@Cust_<AttributeID>@. For example, after you configure an attribute with a USPhone ID, the @@Cust_USPhone@ placeholder becomes available.
Important: For a reseller or vendor, a custom attribute must be prefixed with @@Vend_ (not @@Cust_) if they are used in placeholders.
Available Placeholders
For the full list of available placeholders per notification template:
- In the Provider Control Panel, in the top menu, go to Billing. Then go to System > Settings. In the System list, click Notifications. In the Notifications sub-list, click Notification Templates.
- Click the necessary notification template. The available placeholders are listed below the general template settings. For your convenience when creating or updating a notification template, the available placeholders are also listed in the HTML and Plain Text tabs.
Creating a Notification Template
To create a notification template, complete the following steps:
- Go to System > Settings > Notifications > Notification Templates.
-
Click Add New Notification Template and fill out a form:
- In the Message Type field, select a notification message type. For descriptions of available message types, refer to Managing Notifications.
- In the Template Name field, type a template name.
- In the Language field, select a language to be used for notification messages.
- Select the Message Category for which a notification template will be used.
- In the HTML Message field, type an HTML code that will be used for PDF attachments, paper mail and email messages in the HTML format. The HTML message size limit is 64 KB.
-
In the Plain Text Message field, type a message on which plain text email messages will be based.
Note:
1. If both HTML Message and Plain Text Message forms are set up, only the HTML message will be sent (with or without a PDF file). Whether the PDF file is sent as an attachment or not depends on the PDF sending settings. For additional information, refer to Configuring Message Send Methods.
2. Special symbols#and@are reserved for placeholders and must be used in a text only with a backslash (for example,\#).
3. Placeholders with three signs@in a row must be used with a backslash (for example,mailto:myname\@@@Subscription_Name@). - In the Message Subject field, type a message subject. You can include placeholders.
- In the To Address field, type a recipient email address. You can type several recipient email addresses separated with commas. You can also use placeholders. For example, type a
@@Cust_Account_BillingContact_Email@so that the same template can be used to send a notification to any customer. - In the To Name field, type a recipient name. You can use placeholders. For example, type a
@@Cust_Account_CompanyName@so that the same template can be used to send a notification to any customer. - (Optional) You can type one or more recipient email addresses separated with commas in the BCC Address field. You can use placeholders.
-
In the From Address field, type a sender email address. You can use placeholders (for example, a
@@Vend_Account_BillingContact_Email@) or type a definite email address.Important: If you intend to use custom placeholders such as a service parameter or attribute in this field, ensure the ID of a parameter ends with “
Email”. - In the From Name field, type a sender name. You can use placeholders (for instance, a
@@Vend_Account_companyName@) or type an actual name. -
In the PDF Attachment Filename field, type a name of a PDF notification file to be sent to a customer as a message attachment. Any symbols are acceptable for naming PDF attachments except the following:
<,>,:,",/,\,|,?, and*.Note:
1. The Send email in PDF format method must be enabled in the Message Send Methods settings. For additional information, refer to Configuring Message Send Methods.
2. Attachment naming is not available for notification subtemplates because they cannot be sent separately from related notification templates. - Select the Active checkbox if you want to use the template for a notification immediately after its creation. If you plan further configuration, leave this checkbox unselected. You can activate the template anytime after all the changes are done.
-
In the Condition field, type a regular expression to be used as a condition for sending notifications. A condition uses notification placeholders and regular expressions to parse a message for placeholder values.
Note: The supported regular expression standards are POSIX Basic and POSIX Extended. You can find the description of these standards, for example, http://www.regular-expressions.info/posix.html.
Placeholders and conditions vary depending on the notification template type. An example of a condition is
@@Subscription_Plan_ID@~="^(1)|(2)|(3)$". If a notification template contains such a condition, this means that notifications are to be sent if a subscription is set up in accordance with a service plan with ID 1, 2, or 3. -
Select the Visible to Resellers checkbox for resellers to be able to use the notification template.
Note: If you are going to assign the notification template to a service plan delegated to a reseller, the Visible to Resellers option must be ON for this notification template.
- Select the Secure Body checkbox to prevent an email message body from being logged. This is recommended for email messages that contain confidential information.
- Click Save.
Limitations
Please see limitations related to taxation configuration.