Notification 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.
You can make use of the following sets of notification placeholders: