Using Variables in Parallels H-Sphere E-Mail Notifications

Parallels H-Sphere e-mail notifications can be customized directly in CP admin interface in the Settings->E-Mail Notifications menu.

This document aims at advanced customization of these messages. It contains the description of basic notification variables.

Below is the table illustrating which variables are used in which notifications. The notifications are grouped and named according to their XML configuration file, user_emails.xml. The Tag column corresponds to the names of the notifications set in the tag attributes in user_emails.xml. In the Variables column, only variables specific to that particular notifications are listed. Standard variables are variables common for all notifications. Properties and methods for variables are listed below.

The List of Notification Variables


Tag	Description	Variables
Misc
LOST_PASSWORD	Lost Password Message	standard variables
OVERLIMIT	Overlimit Notification	suspend over_limit_res standard variables
SSH_NOTIFICATION	Shell Access Notification	result subject standard variables
VPS_INIT	Virtual Private Server Initialization Notification	vpsname ips ci standard variables
Custom Domain Registration
ASYNC_CANCELED	Async. Manager Canceled Transactions	Not implemented
ASYNC_DONE	Async. Manager Processed Transactions	d toolbox
CUSTOM_REGISTRAR_CONTACT_CHANGED	User Information Changed Message	registrant tech admin billing domain_name renew_days email_days standard variables
CUSTOM_REGISTRAR_REGISTRATION	Custom Domain Registration Request Message	registrant tech admin billing domain_name renew_days email_days standard variables
CUSTOM_REGISTRAR_RENEW	Custom Renew Domain Registration Message	registrant domain_name renew_days email_days period standard variables
Managing Debtors
DEBT_DEL_NOT	Deletion Warning	bill negative_date current_date suspend_date delete_date standard variables
DEBT_DEL_REASON	Account Deletion	bill negative_date current_date suspend_date delete_date standard variables
DEBT_SUSP_NOT	Suspension Warning	bill negative_date current_date suspend_date delete_date standard variables
DEBT_SUSP_REASON	Account Suspension	Not implemented
DEBT_WARN_NOTIFICATION	Outstanding Balance Notification	bill negative_date current_date suspend_date delete_date standard variables
TRIAL_SUSP_REGISTER	Trial Suspension Notification	standard variables
Welcome Messages
FAILED_SIGNUP	Failed Signup Notification	failed_signups_q accounts lang
NEW_ACCOUNT	Welcome Letter	bi ci standard variables
NEW_MODERATED	Welcome Letter For Moderated Accounts	bi ci reseller_url standard variables
NEW_MODERATED_CC	Welcome Letter For Moderated Account with CC	bi ci reseller_url standard variables
TRIAL_MODERATED	Welcome Letter For Trial/Moderated Account	bi ci reseller_url standard variables
TRIAL_REGISTER	Trial Registration	standard variables
Tax Exemptions
ACCOUNT_TEXEMPT_APPROVED	Tax Exemption Approved Notification (Live Accounts)	bi ci date standard variables
ACCOUNT_TEXEMPT_REJECTED	Tax Exemption Rejected Notification (Live Accounts)	bi ci date standard variables
MODERATED_TEXEMPT_APPROVED	Tax Exemption Approved Notification (Moderated Accounts)	bi ci date request standard variables
MODERATED_TEXEMPT_REJECTED	Tax Exemption Rejected Notification (Moderated Accounts)	bi ci date request standard variables
NEW_MODERATED_TEXEMPT	Welcome Letter (Tax Exemption)	bi ci reseller_url standard variables
Domain Registration
DOMAIN_TRANSFER	Domain Transfer Message	domain standard variables
REGISTRAR_EXPIRED_WARN	Expired Domain Registration Notification	osrs standard variables
REGISTRAR_RENEW_WARN	Domain Registration Renew Warning	osrs standard variables
Managing Trials
TRIAL_APPROACH_NOT	Trial Expiry Warning	current_date delete_date suspension_date trial_days_till standard variables
TRIAL_DEL_NOT	Deletion Warning	current_date delete_date suspension_date trial_days_till standard variables
TRIAL_DEL_REASON	Account Deletion	current_date delete_date suspension_date trial_days_till standard variables
TRIAL_SUSP_NOT	Suspension Warning	current_date delete_date suspension_date trial_days_till standard variables
Trouble Ticket System
INTERNAL_TICKET	Internal Ticket	standard variables
Accounting
ACCOUNTING_ERROR	Accounting Error letter	error date stack error_subject standard variables
INVOICE	Order Confirmation	entries taxes subtotal total reseller_url standard variables
MONEY_BACK	Money Back Notification	standard variables
Suspend/Resume
RESUME	Account Resumed Notification	standard variables
SUSPEND	Account Suspended Notification	reason standard variables

Standard Variables

Variable	Description
account	The instance of the Account object
user	The instance of the User object
plan	The instance of the Plan object
toolbox	The instance of the Toolbox object
config	Values from hsphere.properties
settings	Current reseller settings
lang	The Lang object

Special Variables

Variable	Description
suspend	The date when account will be suspended
over_limit_res	The list of overlimited resources: Traffic, Quota, SummaryQuota
result	The result of the request (OK, REFUSED, DISABLED), used only in SSH_NOTIFICATION
subject	The result description, used in SSH_NOTIFICATION
vpsname	VPS server name
ips	List of VPS server IPs
d	The instance of the AsyncDescriptor object, used only in ASYNC_DONE
registrant	The same as ContactInfo
tech	Tech info
admin	Admin info
billing	Registrar Billing Info
domain_name	Domain name
renew_days	Renew domains that many days before domain expiration
email_days	Warn users about domain expiration that many days in advance
period	Renewal period, in years
bill	The instance of the Bill object
negative_date	Outstanding balance date
current_date	Current date
suspend_date	The date when account will be suspended
delete_date	The date when account will be deleted
failed_signups_q	Failed signups counter, only for FAILED_SIGNUP
accounts	List of accounts with failed signup, only for FAILED_SIGNUP
bi	The instance of the BillingInfo object
ci	The instance of the ContactInfo object
date	Current date
request	Fake request object
reseller_url	Reseller URL
suspension_date	The date when the account will be suspended
trial_days_till	Days left till the end of the trial period
error	Error message
stack	Java stack trace
error_subject	Error's short description
entries	The list of bill entries
taxes	List of taxes
subtotal	The total, without taxes
total	The total, with taxes
reason	Reason for suspension, used only in SUSPEND

Properties and Methods

Many variables used in e-mail notifications are instances of Parallels H-Sphere objects. Below is the table with the description of methods and properties of respective objects (in bold).

Account

Property/Method	Description
id	Account ID
description	Description
periodId	Billing period ID
bi	The BillingInfo object
ci	The ContactInfo object
bill	The Bill object
plan	The Plan object
planId	Plan ID
receive_invoice	Flag indicating if the invoice is received
suspend_reason	Reason for suspension
password	Password
login	Login
trial_time_left	Time left from trial account creation
p_end	Billing period end date
exhaustion_date	Exhaustion date
created	Account creation date

User

Property/Method	Description
login	Login
password	Password
reseller_id	Reseller ID
reseller_url	Reseller's CP URL
reseller_context_url	Reseller Context URL
prefix	Prefix for databases
isdemo	Flag indicating that the account is in demo mode

Plan

Property/Method	Description
id	Plan ID
description	Description
reseller_id	Reseller ID
disabled	Flag indicating that plan is disabled
isPromocodeApplicable	Flag indicating if promocode is available
type	Plan type

Toolbox

Property/Method	Description
getInvoice(modId)	Returns an Invoice object
calculateTaxes(total[,bi_id])	Calculates taxes
currency(value)	Returns a string with currency representation
numberToCurLocale(value,useGrouping)	Converts a number to current locale
getPaymentLink(gateway, sbalance, prefix, account, description)	Returns payment link
int2ext(ip)	Converts internal IP to external
lt(val1,val2)	Compares two variables. Returns 1 if val<val2, else 0
sub(val1,val2)	Subtracts val2 from val1
mul(val1,val2)	Multiplies val1 and val2
taxes	The list of taxes
displayBalance(balance)	Returns a string with the balance
now	Current date
date	Current date

Traffic

Property/Method	Description
traffic	Current traffic
size	Traffic limit
tt_type	Traffic type
text_traffic	Text representation of traffic amount
info	Current traffic status
start_date	Date when traffic calculation is started

Quota

Property/Method	Description
limitMb	Quota size, in MB
limitFiles	Limit of used files
usedMb	Disk space now in use, in MB
usedFiles	Used files counter
info	Current quota status
start_date	Date when disk usage calculation is started

SummaryQuota

limitMb	Disk usage limit
usedMb	Current disk usage, in MB
lastDayUsedMb	The last day usage, in MB
info	Current disk usage status
start_date	Date when disk usage calculation is started
short_start_date	Disk usage calculation starting date, short format

ContactInfo

Property/Method	Description
first_name	First name
last_name	Last name
org_name	Company name
address1	Address
address2	Second address
address3	Third address
city	City
state	State
country	Country
postal_code	ZIP code
phone	Phone number
fax	Fax number
email	E-mail address

BillingInfo

Property/Method	Description
id	Billing contact info identifier
bi_id	Bill id
name	Name
first_name	First name
last_name	Last name
org_name	Company name
address1	Address
address2	Second address
city	City
state	State
state2	Second state
country	Country
postal_code	ZIP code
phone	phone number
fax	Fax number
email	E-mail address
reason	Reason for suspension
type	Payment type: CC - credit card, CHECK - check, TRIAL - trial account.
pi	The PaymentInfo object
exemption_code	Tax exemption code
negative_date	Outstanding balance date

PaymentInfo

Property/Method	Description
number	CC number
hNumber	Hidden number
cvv_checked	Flag indicating that CVV is checked
exp	CC expiration date
exp_year	CC expiration year
exp_month	CC expiration month
exp_day	CC expiration day
start_date	CC creation date
start_year	CC creation year
start_month	CC creation month
start_day	CC creation day
issue_no	Issue number
name	CC name
expired	Flag indicating if CC is expired
info	CC info
type	CC type
fatts	Failed Charge Attempts Counter
fatts_info	Failed Charge Attempts info
is_fatts_checked	Flag indicating if Fatts control is activated

AsyncDescriptor

Property/Method	Description
user_id	User id
user	the User object
rid	Resource id
description	Description
start_date	Start date
last_check	Last check
state	State
max_delay	Maximum delay
interval	Interval
error	Error message
error_code	Error code

Bill

Property/Method	Description
id	Bill id
opened	Date when the billing period is opened
closed	Date when the billing period is closed
entries	List of billing entries
description	Description
desc_plan	Plan description
desc_short	Short description
start_balance	Start of the billing period
end_balance	End of the billing period
debits	Debit
credits	Credit
change	Difference
amount	Amount
subamount	Amount without taxes
balance	Balance
credit	Credit
customCredit	Custom credit
negativeDate	Outstanding balance
format_opened	Formatted date when the billing period was opened
format_closed	Formatted date when the billing period was closed
to_pay	Negative balance
taxes	List of taxes
total_taxes	Taxes, total

BillEntry

Property/Method	Description
id	Billing entry id
bill_id	Billing period id
description	Description
is_credit	Flag indicating if credit is added
tax	Tax
amount	Amount
balance	Balance
note	Note
type	Payment type
canceled	Flag indicating if the billing entry is canceled
billing_info_id	Billing info id
date	Date when the billing entry is added
format_date	Formatted date when the billing entry was added

Invoice

Property/Method	Description
localized_total	The total in local currency
total	The total
subtotal	The total without taxes
entries	Billing entries
taxes	List of taxes

Examples of Usage

Labels from language bundles

Labels from the hsphere_lang.properties language bundles are called by means the lang variable.

For example, the massmail.welcome_login label is called:

${lang.massmail.welcome_login}

In more complex cases, labels may contain arguments within their text, for example:

massmail.welcome_header = Dear {0} {1},

where the arguments {0} and {1} stand for a customer's first name and last name, respectively.

To call such labels with arguments:

${lang.massmail.welcome_header(account.ci.first_name,account.ci.last_name)}

Please refer to the description of account and ci.

Getting credit card information

The pi variable returns information about user credit card. For example, to get credit card number:

${account.bi.pi.number}