Look what Java and SIP can do
 (SIP)Java = ∞
Home     News     Projects     Downloads     Support     Contact
SipExchange Home

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
    1. Conventions followed in this document
    2. Overview
    3. Setting up a template directory
    4. References
    5. Template example

Conventions followed in this document

  1. 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.
  2. 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.
  3. 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:
    1. $JAVA_HOME - directory where the Java Runtime Environment (JRE) is installed.
    2. $SIPEXCHANGE_HOME - directory where the SipExchange software is unpacked.
    3. $JBOSS_HOME - directory where JBOSS is installed.
    4. $HOST - host name/IP address of the system where the jiplet container is installed.
    5. $RUN - the JBOSS run mode (default, minimal, all, etc.)
  4. 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 on various occasions. These emails notify the users want their account information has been created, modified, etc. The SipExchange system constructs the email based on default templates that have been created by the SipExchange project. 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 as well as follow the rules specified by this document. To learn more about the Velocity template syntax, click here.

The following sections explain how to setup the templates.

Setting up a template directory

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 following files with the same file name (the file name is case-sensitive). The directory and files within it must be readable by the Unix/Windows system user that started SipExchange.
  1. subscriber_account_created.vm : Contains the template for the email that is sent to the subscriber when a new subscriber account is created.
  2. subscriber_account_modified.vm: Contains the template for the email that is sent to the subscriber when a new subscriber account is modified.
  3. 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.
  4. 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.
  5. password_own_modified.vm : Contains the template for the email that is sent to the subscriber when he/she changes his/her password.
  6. profile_own_modified.vm :  Contains the template for the email that is sent to the subscriber when he/she changes his/her profile.
  7. 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.
  8. cfw_own_modified: Contains the template for the email that is sent to the subscriber when the subscriber modifies the call forwarding profile.
If you don't have all the above files, the system will use the default templates provided by us.

To setup the template directory for a domain, follow the steps below:
  1. Select the domain you want to add templates to from the list of domains from the top menu or from the hyper-link in the home page. Click on the drill-down icon to view the domain information.
  2. Click on the "Properties" button from the screen where the domain information is displayed. The system will display a list of properties for the domain.
  3. Add the property "domainTemplateDir" (spelled eexactly the same way) and add a value containing the full path name of the 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.

References

This section describes the reference variables 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
  1. subscriber_account_created.vm
  2. subscriber_account_modified.vm
  3. password_own_modified.vm
  4. profile_own_modified.vm
  5. add_to_contacts.vm
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.
  1. password_own_modified.vm
  2. profile_own_modified.vm
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.
  1. subscriber_account_created.vm
  2. subscriber_account_modified.vm
  3. password_own_modified.vm
  4. profile_own_modified.vm
  5. add_to_contacts.vm
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.
  1. subscriber_account_created.vm
  2. subscriber_account_modified.vm
  3. password_own_modified.vm
  4. profile_own_modified.vm
  5. add_to_contacts.vm
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.
  1. subscriber_account_created.vm
  2. subscriber_account_modified.vm
  3. password_own_modified.vm
  4. profile_own_modified.vm
  5. add_to_contacts.vm
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.
  1. subscriber_account_created.vm
  2. subscriber_account_modified.vm
  3. password_own_modified.vm
  4. profile_own_modified.vm
  5. add_to_contacts.vm
  6. subscriber_cfw_modified
  7. cfw_own_modified
  8. subscriber_cscr_modified
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.
  1. subscriber_cfw_modified
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.
  1. cfw_own_modified
cscr
 userId : contains the user id
domain : contains the domain name
enableCallScreening:  "Yes" if call screening is enabled, "No" if not enabled
  1. subscriber_cscr_modified


Note: All the reference names used above can be referred to from your templates as explained in the Velocity User Guide. But for the Java Bean properties, Velocity uses the syntax $subscriber.UserId to refer to the userId property for the subscriber object above instead of using $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

Note the use of the reference variables and Java beans 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