 |
Look what Java and SIP can do |
| (SIP)Java = ∞ | |
| Home News Projects Downloads Support Contact |
Terminology
Installation Howto
System Administration Howto
Velocity Templates User Guide
Configuring
Email Templates
This document explains how to customize the emails that are sent out by
the SipExchange server. To fully understand this document, you must
already be familiar with the SipExchange
administration fundamentals.Table of Content
Conventions followed in this document
- We have used the term "directory" to specify a file location. This is a common Unix convention. In the Windows environment, the term "folder" is used to mean the same thing.
- We have used the Unix directory naming convention in this
document. In the Unix environment, a directory hierarchy is specified
by the "/" separator. In the Windows environment, the "\" separator is
used. In addition, Unix systems do not use drive letters as in Windows.
If you are using Windows, you will need to modify the commands
accordingly. For example, if we stated $JIPLET_HOME/bin and you are
using Windows, it may translate to C:\jiplet-standalone\bin.
- We have used $SIPEXCHANGE_HOME or similar names to specify variables. While installing/configuring, you will need to replace these variables with the actual value. For example, in this document, the variable $SIPEXCHANGE_HOME has been used to specify the directory where the SipExchange code binary is unpackaged. We have commonly used the following variables:
- $JAVA_HOME - directory where the Java Runtime Environment (JRE) is installed.
- $SIPEXCHANGE_HOME - directory where the SipExchange software is unpacked.
- $JBOSS_HOME - directory where JBOSS is installed.
- $HOST - host name/IP address of the system where the jiplet container is installed.
- $RUN - the JBOSS run mode (default, minimal, all, etc.)
- Commands are specified using bold. You need to enter the command by typing/pasting the command and pressing the Enter/Return key. Although in the Unix world this may seem natural, in the Windows environment, lots of users are lost when it comes to entering a command. Also, the prompts "#" or "C:\>" are shown, do not enter them.
Overview
The SipExchange server sends emails to subscribers and administrators during various events. These emails notify the users when their account information has been created, modified, etc. The SipExchange system constructs the email based on templates that have been included in the SipExchange installation. The templates are text files that contains the text and format of the email message. The text also includes reference notations that are replaced with actual values before sending the email. In addition, it also contains additional directives like conditional inclusion of text segments, loops, etc. that are processed before sending out the email. SipExchange uses the Velocity Template Engine from Apache to convert the templates into email text.You can replace these templates with your own templates so that the email body contains customized messages that you want to send to your subscribers. The templates can be added on a per-domain basis. That is, for each of your domains, you can have a set of email templates that is different from templates for another domain. In order to do this you will have to create templates as per the syntax specified by the Velocity engine and following the rules specified in this page. To learn more about the Velocity template syntax, click here.
The following sections explain how to setup the templates.
Modifying the global templates
As mentioned above, SipExchange comes with a set of email templates. These templates are global. That is, unless you override these templates with domain-specific template (see below), all emails sent by SipExchange uses these templates to format the email body. These templates are stored in files in the $JBOSS_HOME/server/$RUN/conf/sipex/template directory.The following list describes the available template files:
- auth_info.vm:
Contains the template for the email that is sent when the user has
forgotten his/her account information (login/password) and requests
passwords to be emailed to him/her.
- subscriber_account_created.vm
: Contains the template for
the email that is sent to the subscriber when a new subscriber account
is created.
- subscriber_account_modified.vm: Contains the template for the email that is sent to the subscriber when a new subscriber account is modified.
- subscriber_cfw_modified: Contains the template for the email that is sent to the subscriber when the call forward feature has been enabled/disabled or a call forwarding address has been changed by the administrator on behalf of the subscriber.
- subscriber_cscr_modified:
Contains the template for the
email that is sent to the subscriber when the administrator enables or
disables the call screening feature.
- password_own_modified.vm: Contains the template for the email that is sent to the subscriber when he/she changes his/her password.
- profile_own_modified.vm: Contains the template for the email that is sent to the subscriber when he/she changes his/her profile.
- add_to_contacts.vm : Contains the template for the email that is sent to the subscriber when another user adds the subscriber to his/her list of contacts.
- cfw_own_modified: Contains the template for the email that is sent to the subscriber when the subscriber modifies the call forwarding profile.
Setting up
domain-specific templates
If you want domain-specific email templates, for each domain, you can
specify a directory name in the server where
the template files are stored. The template directory must exist on the
server and must contain one or more of the files discussed in the above
section. The file names must match exactly including the case. The directory and
files within it must be readable by the Unix/Windows system user that
started SipExchange. If you don't have all the above files, the system
will use the global templates.To configure the template directory for a domain, follow the steps below:
- Select the domain you want to add templates to from the
list of domains from the top menu.
- Click on the "modify" icon to Modify the domain
information.
- Click on the "Next" button to go to the Domain Properties
section. The system will display a list of
properties for the domain.
- Click on the "Add" icon to add a new property and a new blank property line will be created. The name of the property that you must enter is "domainTemplateDir" (spelled exactly the same way) and add a value must contain the full path name of the template directory. For example, if the templates are store in C:\templates, specify the value as such. If the property has been created by you and you want to change the value, you can modify the value and the next set of emails sent out will use the new templates specified by the new directory.
Use of Java objects
This section describes the Java objects that are available for the
templates that you can use. The first column specifies the Java object
that is available for the Velocity template. The second column
specifies the Java Bean properties for the object (private attribute
with public getters and setters). The third column contains the
templates for which this object is available. Note that some of the
reference variables are String objects and therefore do not have any
associated Java bean properties:| Reference
Variable |
Java
Bean Properties and Description |
Applicable
Template(s) |
| subscriber |
userId : contains the user id password : contains the password. Only available when the password has been entered by the subscriber or administrator domain : contains the domain name name : Full name of the user email : Email address of the user homePhone : Home phone number for the user workPhone : Work phone number for the user mobilePhone : Mobile phone number for the user webUrl : User's web URL additonalInfo : Any additional information |
|
| user |
This is a string object.
The variable contains the login user name for the subscriber for the
Subscriber Console. The user name is in the format name@domain where
name is the provisioned user name and the domain is the name of the
domain. For example: amit@cafesip.org. |
|
| sipServerHost |
This is a String object.
The variable contains the host name/IP address of the SipExchange
server. By default, it uses the IP address of the system. If you want
to change it, you can add a parameter called sipServerHost to the system
properties. You can also override this value on a per-domain basis by
adding a property called sipServerHost
to the domain properties. That way, specific domains
can have specific host names although they may resolve to the same IP
address. |
|
| sipServerPort |
This is a String object.
The variable contains the port number
of the SipExchange server. By default, it contains the value 5060. If
you want to change it, you can add a parameter called sipServerPort to
the system properties. You can also override this value on a per-domain
basis by adding a property called sipServerPort
to
the domain properties. |
|
| sipServerTransport |
This is a String object. The variable contains the transport protocol name used by the SipExchange server. By default, it contains the value "udp". If you want to change it, you can add a parameter called sipServerTransport to the system properties. You can also override this value on a per-domain basis by adding a property called sipServerTransport to the domain properties. |
|
| sipexUrl |
This is a String object. The variable contains the URL for the Subscriber Console. By default, it contains the value "http://server-ip:8080/sipex" where server-ip is the IP address of the server. If you want to change it, you can add a parameter called sipexUrl to the system properties. You can also override this value on a per-domain basis by adding a property called sipexUrl to the domain properties. |
|
| cfw |
userId : contains the user id domain : contains the domain name enableCfw: "Yes" if call forwarding is enabled, "No" if not enabled cfwAddress: The SIP address to which the call is forwarded to enableCfna: "Yes" if call forwarding on no availability is enabled, "No" if not enabled cfnaAddress: The SIP address to which the call is forwarded to when the subscriber is not available. |
|
| cfw | cfwForward: The SIP address to which
the call is forwarded to cfnaForward: The SIP address to which the call is forwarded to when the subscriber is not available. |
|
| cscr |
userId : contains the user id domain : contains the domain name enableCallScreening: "Yes" if call screening is enabled, "No" if not enabled |
|
Note: All the Java object names used above can be referred to from your templates using the convention explained in the Velocity User Guide. For example, Velocity uses the syntax $subscriber.UserId to refer to the userId property for the subscriber object. Note that the convention is different from the convention used by some expression languages where it uses the convention - $subscriber.userId.
Template example
The following example illustrates a template for the condition when the administrator modifies the subscriber profile or password. This email is sent out to the subscriber.Your
SIP account has been modified.
If necessary, please reconfigure your SIP phone as per the following information.
SIP address: sip:${subscriber.UserId}@${subscriber.Domain}
User name: ${subscriber.UserId}
#if (${subscriber.Password} && ${subscriber.Password} != "")
New password: $!{subscriber.Password}
#else
Password: Not modified
#end
SIP server: ${sipServerHost} port=${sipServerPort}, transport=${sipServerTransport}
In addition, the following information has also been entered as your personal profile:
Full name: $!{subscriber.Name}
Email address: $!{subscriber.Email}
Home phone: $!{subscriber.HomePhone}
Work phone: $!{subscriber.WorkPhone}
Mobile phone: $!{subscriber.MobilePhone}
URL: $!{subscriber.WebUrl}
Additional information: $!{subscriber.AdditionalInfo}
To modify your profile, password or to manage the features that you have
subscribed, please use the "Subscriber Console". To access the Subscriber
console, use any browser and open the following URL:
${sipexUrl}
When prompted for the user name and password, enter the following information:
User Name: ${subscriber.UserId}@${subscriber.Domain}
#if (${subscriber.Password} && ${subscriber.Password} != "")
New password: $!{subscriber.Password}
#else
Password: Not modified
#end
If necessary, please reconfigure your SIP phone as per the following information.
SIP address: sip:${subscriber.UserId}@${subscriber.Domain}
User name: ${subscriber.UserId}
#if (${subscriber.Password} && ${subscriber.Password} != "")
New password: $!{subscriber.Password}
#else
Password: Not modified
#end
SIP server: ${sipServerHost} port=${sipServerPort}, transport=${sipServerTransport}
In addition, the following information has also been entered as your personal profile:
Full name: $!{subscriber.Name}
Email address: $!{subscriber.Email}
Home phone: $!{subscriber.HomePhone}
Work phone: $!{subscriber.WorkPhone}
Mobile phone: $!{subscriber.MobilePhone}
URL: $!{subscriber.WebUrl}
Additional information: $!{subscriber.AdditionalInfo}
To modify your profile, password or to manage the features that you have
subscribed, please use the "Subscriber Console". To access the Subscriber
console, use any browser and open the following URL:
${sipexUrl}
When prompted for the user name and password, enter the following information:
User Name: ${subscriber.UserId}@${subscriber.Domain}
#if (${subscriber.Password} && ${subscriber.Password} != "")
New password: $!{subscriber.Password}
#else
Password: Not modified
#end
Note the use of the Java objects as well as the conditional statement with the #if and #end block.
Search this website
Send
questions or comments about this web site to
webmaster@cafesip.org.
Copyright © 2005, CafeSip.org.
Licensed under the CafeSip License.
The CafeSip.org projects,
web site and web facilities have been sponsored by QUIK Computing