
	Version 9.6	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Working with Design/Change-Time Policies —

Working with EMail Notifications

Certain policy actions, such as the Send Email Notification action and the approval actions, send email messages to users when specified events occur. For example, you might use the Send Email Notification action to alert a certain group of administrators when an asset switches to a particular state. Or, you might issue an email alert to certain users when an approval request is rejected.

Setting the Email-Related Parameters in an Email Notification Action
Using a Custom Message in an Email Notification Action
Using Email Templates with Policy Actions
Predefined Email Templates Installed with CentraSite

Setting the Email-Related Parameters in an Email Notification Action

Actions that send email notifications to users (such as the Send Email Notification action) require you to specify the following input parameters.

Set this parameter... To specify...

Set this parameter...	To specify...
`Users` — AND/OR — `Groups`	The users to whom the email message is to be sent. You can use the `Users` parameter to specify individual users, the `Groups` parameter to specify groups of users, or both.
`Subject`	The text that will appear on the subject line of the email.
`Use Email Template` — OR — `Custom Message`	The body of the message. You can specify the body of the email by typing a message directly into the `Custom Message` parameter or by using an email template. For more information about these options, see Using a Custom Message in an Email Notification Action and Using Email Templates with Policy Actions.

Users

— AND/OR —

Groups

The users to whom the email message is to be sent. You can use the Users parameter to specify individual users, the Groups parameter to specify groups of users, or both.

Subject The text that will appear on the subject line of the email.

Use Email Template

— OR —

Custom Message

The body of the message. You can specify the body of the email by typing a message directly into the

Custom
                              Message

parameter or by using an email template. For more information about these options, see Using a Custom Message in an Email Notification Action and Using Email Templates with Policy Actions.

You can include substitution tokens in the subject line and/or the body of the email message. Substitution tokens enable you to incorporate run-time information into the email. For example, you can use the ${user.name} token to insert (into the email message or the subject line) the name of the user who triggered the policy. For a complete list of the supported substitution tokens, see the description of the action Send Email Notification in the section Built-In Actions for Design/Change-Time Policies of the document Built-In Design/Change-Time Actions Reference.

Using a Custom Message in an Email Notification Action

One way to specify the body of the email message is to simply type the message directly into the Custom Message parameter. If you specify the body of the message in this way, you must set the Format parameter to indicate whether the message is to be sent as plain text or as an HTML document. When you use HTML format, you must enclose the message text in <html> and <body> tags.

Example of a Plain Text Message

Virtual Service ${entity.name} has been placed in production by ${user.name}. 
To view the virtual service, go to: ${entity.URL}

Example of an HTML Message

<html>
<body>
<p>Virtual Service <b>${entity.name}</b> has been placed in production by <b>${user.name}</b>.</p>
<p>To view the virtual service, go to: <a href="${entity.URL}">${entity.URL}</a></p>
</body>
</html>

Using Email Templates with Policy Actions

To generate the body of an email message from an email template, the email template must exist in CentraSite's repository. If the template does not already exist, you must create it and upload it to the repository using the EmailTemplateManager command-line utility. (Several predefined templates are available for you to use with various policy actions. For a list, see Predefined Email Templates Installed with CentraSite.)

The following describes how to create an email template and upload it to the repository. It also describes how to edit a template, download a template, delete a template and obtain a list of the templates that already exist in the repository.

Note:
To work with email templates, you must have access to the command line on the machine where CentraSite is installed. Additionally, if you want to upload templates or delete templates, you must have a CentraSite user account that belongs to the CentraSite Administrator role. To view the list of email templates or to download a template, you simply need a CentraSite user account. (In other words, your CentraSite account does not require any explicit permissions. All CentraSite users have View permission on email templates.)

Creating a Custom Email Template

An email template is a text file that contains an HTML document. Your HTML document should include the <html> and <body> tags as shown in the example below. (The inclusion of a <head> tag is optional. CentraSite does not require this tag in an email template.)

Example of an Email Template

<html>
<body>
   <p>Virtual Service <b>${entity.name}</b> has been placed in production by <b>${user.name}</b>.</p>
   <p>To view the virtual service, go to: <a href="${entity.}">${entity.URL}</a></p>
</body>
</html>

Adding an Email Template to CentraSite

To add an email template to CentraSite, you must create a script file that executes the EmailTemplateManager utility. Then you must run the script file with the -t filename input parameter.

Important:
The template's filename is used to uniquely identify the template within CentraSite. If you upload a template that has the same filename name as a template that already resides in the repository, the new template will automatically replace the existing one.

From a Java Class
From a Command Line

From a Java Class

To add an Email Template to CentraSite from a Java Class

Create an email template file as described in Creating an Email Template. Copy the file somewhere within the file system of the machine where CentraSite is installed.
Create a script file as described in Creating a Script File for the EmailTemplateManager Utility.
Execute the script file with the following parameters:

yourScriptFile -t templateFile -dbuser yourCSUserID -dbpassword yourPassword

Example

myScript -t d:\myDirectory\myEmailTemplate.html -dbuser jcallen -dbpassword j45Hk19a

From a Command Line

To add an email template to CentraSite, run the utility with the following input parameters:

Under Windows:
Under Linux:
Input Parameters

Under Windows:

Use the following procedure to add an email template under Windows:

Open ConfigEmailTemplates.cmd in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.cmd -dbuser <USERNAME> -dbpassword <PASSWORD> [-dburl <CENTRASITE-URL>] -t <TEMPLATE-FILE>
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Under Linux:

Use the following procedure to add an email template under Linux:

Open ConfigEmailTemplates.sh in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.sh -dbuser <USERNAME> -dbpassword <PASSWORD> [-dburl <CENTRASITE-URL>] -t <TEMPLATE-FILE>
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Input Parameters

The following table describes the complete set of input parameters that you can use with the EmailTemplateManager utility:

Parameter	Description
`USERNAME`	Required. Your CentraSite user ID.
`PASSWORD`	Required. The password for your CentraSite user account.
`CENTRASITE-URL`	The fully qualified URL for the CentraSite registry/repository. If you omit this parameter, the importer assumes that the registry/repository resides at `http://localhost:53307/CentraSite/CentraSite`. Note: If the registry/repository is running on a different machine and port number, you can use this parameter to specify its location instead of using the individual -h and -p parameters. (If you specify the -dburl parameter with the -h and/or -p parameters, the -h and -p parameters will be ignored.)
`TEMPLATE-FILE`	The URI (file: or http:) of the email template.

Viewing the List of Email Templates on CentraSite

To list the email templates that exist in the CentraSite repository, do either of the following:

From a Java Class
From a Command Line

From a Java Class

To list the email templates in the repository

Create a script file as described in Creating a Script File for the EmailTemplateManager Utility.
Execute the script file with the following parameters:

yourScriptFile -list -dbuser yourCSUserID -dbpassword yourPassword

Example

myScript -list -dbuser jcallen -dbpassword j45Hk19a

From a Command Line

To list the email templates in the repository, run the utility with the following input parameters and options:

Under Windows:
Under Linux:
Input Parameters and Options

Under Windows:

Use the following procedure to list the email templates under Windows:

Open ConfigEmailTemplates.cmd in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.cmd -dbuser <USERNAME> -dbpassword <PASSWORD> -list
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Under Linux:

Use the following procedure to list the email templates under Linux:

Open ConfigEmailTemplates.sh in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.sh -dbuser <USERNAME> -dbpassword <PASSWORD> -list
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Input Parameters and Options

The following tables describe the complete set of input parameters and options that you can use with the EmailTemplateManager utility:

Parameter Description

USERNAME Required. Your CentraSite user ID.

PASSWORD Required. The password for your CentraSite user account.

CENTRASITE-URL

The fully qualified URL for the CentraSite registry/repository.

If you omit this parameter, the importer assumes that the registry/repository resides at http://localhost:53307/CentraSite/CentraSite.

Note:
If the registry/repository is running on a different machine and port number, you can use this parameter to specify its location instead of using the individual -h and -p parameters. (If you specify the -dburl parameter with the -h and/or -p parameters, the -h and -p parameters will be ignored.)

Option	Description
`-list`	Lists all the published email Templates.

Updating an Existing Email Template on CentraSite

To update an existing template in the repository, do the following:

Download the existing template from the repository using the procedure in Downloading an Email Template from CentraSite.
Edit the template as necessary.
Upload the updated template file to the repository using the procedure in Adding an Email Template to CentraSite.

Important:
If you want to update an existing template, make sure the template file that you upload has exactly the same filename as the one you want to replace.

Downloading an Email Template from CentraSite

To download a template from the CentraSite repository, do either of the following:

From a Java Class
From a Command Line

From a Java Class

To download an email template from the repository

Create a script file as described in Creating a Script File for the EmailTemplateManager Utility.
Execute the script file with the following parameters:

yourScriptFile -download templateName -tolocation targetDirectory -dbuser yourCSUserID -dbpassword yourPassword

Example

myScript -download myEmailTemplate.html -tolocation d:\myDir\mySubDir -dbuser jcallen -dbpassword j45Hk19a

From a Command Line

To download a template from the repository, run the utility with the following input parameters:

Under Windows:
Under Linux:
Input Parameters

Under Windows:

Use the following procedure to download a template under Windows:

Open ConfigEmailTemplates.cmd in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.cmd -dbuser <USERNAME> -dbpassword <PASSWORD> [-dburl <CENTRASITE-URL>] -download <EMAIL-TEMPLATE> -tolocation <LOCATION>
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Under Linux:

Use the following procedure to download a template under Linux:

Open ConfigEmailTemplates.sh in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.sh -dbuser <USERNAME> -dbpassword <PASSWORD> [-dburl <CENTRASITE-URL>] -download <EMAIL-TEMPLATE> -tolocation <LOCATION>
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Input Parameters

The following table describes the complete set of input parameters that you can use with the EmailTemplateManager utility:

Parameter	Description
`USERNAME`	Required. Your CentraSite user ID.
`PASSWORD`	Required. The password for your CentraSite user account.
`CENTRASITE-URL`	The fully qualified URL for the CentraSite registry/repository. If you omit this parameter, the importer assumes that the registry/repository resides at `http://localhost:53307/CentraSite/CentraSite`. Note: If the registry/repository is running on a different machine and port number, you can use this parameter to specify its location instead of using the individual -h and -p parameters. (If you specify the -dburl parameter with the -h and/or -p parameters, the -h and -p parameters will be ignored.)
`EMAIL-TEMPLATE`	The name of an existing email template.
`LOCATION`	The location to save an existing email template.

Deleting an Email Template from CentraSite

To delete an email template from the CentraSite repository, do either of the following:

Note:
The EmailTemplateManager utility will not allow you to delete any of the predefined email templates that are installed with CentraSite. Neither will it allow you to delete any template that is used by an existing policy.

From a Java Class
From a Command Line

From a Java Class

To delete an email template from the repository

Create a script file as described in Creating a Script File for the EmailTemplateManager Utility.
Execute the script file with the following parameters:

yourScriptFile -delete templateName -dbuser yourCSUserID -dbpassword yourPassword

Example

myScript -delete myEmailTemplate.html -dbuser jcallen -dbpassword j45Hk19a

From a Command Line

To delete an email template from the repository, run the utility with the following input parameters:

Under Windows:
Under Linux:
Input Parameters

Under Windows:

Use the following procedure to delete a template under Windows:

Open ConfigEmailTemplates.cmd in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.cmd -dbuser <USERNAME> -dbpassword <PASSWORD> [-dburl <CENTRASITE-URL>] -delete <EMAIL-TEMPLATE>
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Under Linux:

Use the following procedure to delete a template under Linux:

Open ConfigEmailTemplates.sh in a text editor.
Add the following property statement:
```
<CentraSiteInstallDir>\utilities\ ConfigEmailTemplates.sh -dbuser <USERNAME> -dbpassword <PASSWORD> [-dburl <CENTRASITE-URL>] -delete <EMAIL-TEMPLATE>
```
where, <CentraSiteInstallDir> is the CentraSite installation directory. By default, this is the CentraSite folder under <SuiteInstallDir>.

Input Parameters

The following table describes the complete set of input parameters that you can use with the EmailTemplateManager utility:

Parameter	Description
`USERNAME`	Required. Your CentraSite user ID.
`PASSWORD`	Required. The password for your CentraSite user account.
`CENTRASITE-URL`	The fully qualified URL for the CentraSite registry/repository. If you omit this parameter, the importer assumes that the registry/repository resides at `http://localhost:53307/CentraSite/CentraSite`. Note: If the registry/repository is running on a different machine and port number, you can use this parameter to specify its location instead of using the individual -h and -p parameters. (If you specify the -dburl parameter with the -h and/or -p parameters, the -h and -p parameters will be ignored.)
`EMAIL-TEMPLATE`	The name of an existing email template.

Creating a Script File for the EmailTemplateManager Utility

The EmailTemplateManager is a Java class whose main() method executes when you execute the EmailTemplateManager from the command line. To ensure that the CLASSPATH and other environment variables are set properly when you execute this utility, you must create a script file that calls the EmailTemplateManager as described below.

Creating a Script File for Windows (a .bat file)

Create a script file that looks as follows if CentraSite is running under Windows.

@echo off 
set JAVAEXE=fullPathToJava.exe
set REDIST=CentraSiteHomeDirectory\redist
set BASEDIR=%~dp0
cd /d %REDIST%

REM build CLASSPATH with all files from jar directory
set LOCAL_CLASSPATH= 
for %%I in (".\*.jar") do call "CentraSiteHomeDirectory\bin\cfg\lcp.cmd" %%I

%JAVAEXE% -cp %LOCAL_CLASSPATH% com.centrasite.util.EmailTemplateManager %* 
cd /d %BASEDIR%

Example

@echo off 
REM
REM Run Email Template Manager Utility 
REM
set JAVAEXE=D:\software\java\jdk1.5.0_12\bin\java
set REDIST=C:\SoftwareAG\CentraSite\redist 
set BASEDIR=%~dp0
cd /d %REDIST%

REM build CLASSPATH with all files from jar directory
set LOCAL_CLASSPATH= 
for %%I in (".\*.jar") do call "C:\SoftwareAG\CentraSite\bin\cfg\lcp.cmd" %%I

%JAVAEXE% -cp %LOCAL_CLASSPATH% com.centrasite.util.EmailTemplateManager %* 
cd /d %BASEDIR%

Creating a Script File for Unix (C-shell script)

Create a script file that looks as follows if CentraSite is running under Unix.

set javaexe="fullPathToJava.exe"
set redist="fullPathToJava.exe/redist"
set mainjar="CentraSiteUtils.jar" 
set delim='\:'
cd "$redist" 
set cl="" 
foreach j ( `ls *.jar` ) 
 if ($cl != "") set cl=${cl}${delim} 
 set cl=${cl}${j} 
end
setenv CLASSPATH ${mainjar}${delim}${cl}
$javaexe com.centrasite.util.EmailTemplateManager $*

Example

#!/bin/csh 
#
# Run Email Template Manager Utility 
#
set javaexe="/.../softwareag/cjp/v16/bin/java" 
set redist="/.../softwareag/CentraSite/redist" 
set mainjar="CentraSiteUtils.jar" 
set delim='\:' 
# build CLASSPATH with all files from jar directory
cd "$redist" 
set cl="" 
foreach j ( `ls *.jar` )
  if ($cl != "") set cl=${cl}${delim}
  set cl=${cl}${j}
end
setenv CLASSPATH ${mainjar}${delim}${cl} 
$javaexe com.centrasite.util.EmailTemplateManager $*

Executing the EmailTemplateManager Script File

To run the EmailTemplateManager, execute your script file on the machine where CentraSite is installed.

Note:
CentraSite must be running when you execute the script file.

When you execute your script file, you must include input parameters on the command line to specify what you want the EmailTemplateManager to do. You must also include parameters to specify your CentraSite user ID and password. For example, to delete a template from the directory, you would run your script as follows:

yourScriptFile -delete templateName -dbuser yourCSUserID -dbpassword yourPassword

Example

myScript -delete myEmailTemplate.html -dbuser jcallen -dbpassword j45Hk19a

Note:
If you execute your script without supplying any input parameters, the EmailTemplateManager will display the list of all supported parameters.

Using the -dburl Input Parameter

The EmailTemplateManager utility assumes that the CentraSite registry/repository is running at http://localhost:53307/CentraSite/CentraSite (i.e., it assumes that it is installed on the same machine as the EmailTemplateManager utility). If you installed the registry/repository component on a different machine than the CentraSite Application Server Tier (CAST) or if you configured the registry/repository to run on a different port than 53307, you will need to use the -dburl parameter to specify the address of the registry/repository when you run your script.

Example

myScript -delete myEmailTemplate.html -dburl http://rubicon:53307/CentraSite/CentraSite -dbuser jcallen -dbpassword j45Hk19a

Predefined Email Templates Installed with CentraSite

The following predefined email templates are installed with CentraSite. These templates are provided for you to use with the policy actions listed below if you do not want to create your own email templates. For information about the policy actions, see the section Built-In Actions for Design/Change-Time Policies in the document Built-In Design/Change-Time Actions Reference.

Template Name	Description	Meant to be used with...
ApprovalNotification.html	Default email template used when an approval request is approved.	The `Send Approval Email` parameter in the Initiate Approval or Initiate Group-Dependent Approval action.
AutoApprovalNotification.html	Template used in earlier versions of CentraSite to indicate that a request had been auto-approved. This template is no longer used by CentraSite.	The Send Approval Email parameter in the Initiate Approval or Initiate Group-Dependent Approval action. (This template would only be useful in cases where all approval requests processed by the policy action were expected to be auto-approved.)
ChangeNotification.html	Default email template used for change notifications.	The `Use Email Template` parameter in the Send Email Notification action.
PendingNotification.html	Default email template used when an approval request is submitted to approvers.	The `Send Pending Approval Email` parameter in the Initiate Approval or Initiate Group-Dependent Approval action.
RejectApprovalNotification.html	Default email template used when an approval request is rejected.	The `Send Rejection Email` parameter in the Initiate Approval or Initiate Group-Dependent Approval action.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT