Placeholders are an important tool for customizing Billing workflow. It allows using specific data retrieved from the database for setting conditions and creating personal messages. Each placeholder indicates what particular piece of data should be retrieved from the database. There are four kinds of placeholders:
- Single data field. Such placeholders start with
@@and end with@; it represents a single value, such as order number (@@DocNUM@) and the like. - Dataset. Such placeholders are always used two times - as beginning placeholder (starts with ## and ends with #) and as ending placeholder (starts with
##/and ends with#); it indicates that the part of message text between the beginning placeholder and the ending placeholder should be repeated as many times as many records are returned for the dataset, represented by this placeholder. Such placeholders are used, for example, to retrieve all order details:##DetailList#and##/DetailList#. - Subtemplates. Subtemplate is used in the same way as single data field placeholder, though they are no placeholders as such. The major difference is that subtemplates always have custom names, while placeholders can not be edited. Subtemplate allows you to single out general data used in a number of general templates, give it a name and then use in any general template in the same way as placeholders. It is common to put document details, footer, header, information on how to renew the subscription, order details, and style code (HTML) in subtemplate. Subtemplate cannot be sent separately, only as part of notification template.
- Subplaceholder. Billing allows partitioning of placeholders with value of string type. If placeholder value contains special character '|', placeholder is splitted on two or more (depends on number of special character occurrence) subplaceholders. Subplaceholder name is formed as following
PlaceholderName_SequenceNumber. The first subplaceholder value is data before 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 subscription period setup fee description is 'Collaboration tools package |Once-off Fee'. The@@Detail_Comment@placeholder value is 'Collaboration tools package Once-off Fee'. There is one special character occurrence, so two subplaceholders are created:@@Detail_Comment_1@ ='Collaboration tools package ' and@@Detail_Comment_2@= 'Once-off Fee'.
Placeholder is replaced with actual parameter value only if Billing object and its parameters values exist in database. Otherwise, placeholder value is empty string.
Billing is delivered with default set of placeholders, but provider can create placeholders for his own needs as well. Placeholders sources are notification templates (default set of placeholders), service templates and customer attributes.
Notification template type (Message Type parameter) determines what data can be used in messages. Namely, the set of placeholders available. Each type of notification has its own set of placeholders, not available to other notification types. For example, placeholders of the Order notification type represent order details: type, number, set of order details and the like.
Note: Placeholders of vendor and customer details are common for all notification types.
Some external systems may require customer to provide an additional data alongside with the general information on service plan purchase. This additional data is presented in Billing as service parameters and is managed from the service template side. For example, the DomainID parameter for domain service template, the LoginID and the PasswordID parameters set for service templates. These are system parameters added automatically by gate on service template creation. Provider can add parameters manually. After service parameter is configured, a placeholder of the following kind is available: @@<ParameterID>@. For example, the @@DomainID@ placeholder corresponds the DomainID service parameter required for purchasing domain.
Customer attributes hold optional customer information, for example birthday, instant messenger number and the like. The customer attributes are configured under the System > Settings > Attributes submenu of the Navigation tree. After attribute is configured, a placeholder of the following kind is available: @@Cust_<AttributeID>@. For example, you have configured attribute with USPhone ID, the @@Cust_USPhone@ placeholder is instantly available.
Note: If applied to reseller (or Vendor), custom attributes must be prefixed with "@@Vend_" (not "@@Cust_") in case they are used in placeholders.