Notification Tags

Notification tags can only be used in Notification e-mail templates.

Note: All notification tags can be used in Notification e-mail templates for Service Level Agreements (SLAs); however, dynamic SLA-specific information cannot be returned.

Several Notification template tags are conditional tags. The condition for each of these tags is placed between parentheses after the $IF statement. The conditional tags can be used with $ELSE() and $ENDIF() tags to tailor the content of the e-mail message depending on whether the condition is true or false.

$ATTACHMENT()

Description
Adds all files attached to an item to the e-mail notification.
Usage
Attachments must be stored in the SBM database and not on the file system. (This setting is applied in SBM System Administrator.)

Files are not attached to messages if their combined size exceeds the limit specified in SBM Configurator.

Attachments are only included with a notification if users have privileges to view those attachments in the associated item.
Note: Use the $FILEATTACHMENTLINKS() tag to include links to attachments in the notification rather than actual files.
Parameters
None.

$ALLRECIPIENTS()

Description
Adds a comma-separated list of subscribers to the e-mail notification.
Usage
Use this tag to include a list of all the current users that are subscribed to the notification.
Note: To avoid sending a potential large list of subscribers, perform the following steps on the SBM server that hosts the Notification Server:
1. Edit the config.properties file located here:
```
installDir\SBM\Common\tomcat\server\default\webapps\
→notificationsrv\WEB-INF\classes
```
2. Search for the event.allrecipients.maxsize setting.
3. Enter the maximum number of subscribers that should appear. For example, to display only three subscribers, change the setting as follows:
```
event.allrecipients.maxsize=3
```
  In this example, the list in the notification shows the first three subscribers, followed by ellipses:
```
Hans Tester (hans@serena.com), Chad Support (chad@serena.com), 
Administrator (admin@serena.com),...
```
4. Save your changes. The new maximum size will take effect after the next SBM Tomcat restart.
Parameters
None.

Sample

$ALLRECIPIENTS()

Result:

Hans Tester (hans@serena.com), Chad Support (chad@serena.com), 
Administrator (admin@serena.com), Bill Admin (bill@serena.com)

$CHANGEACTION()

Descripton
Returns the action and user that caused the notification to be generated, along with the date and time the action occurred.
Usage
Change action examples include state changes, item updates, and attachment additions. Date and time action occurred is also returned.

Change actions are only sent to users who have privileges to view the change history for the item on which the notification is based. For delayed escalations, changes may not be available.
Parameters
None.

Sample

$BEGINSUBJECT()$NOTIFICATION() - $ITEMNUMBER()$CHANGEACTION()$ENDSUBJECT()

Result:

$CHANGES()

Description
Returns the change history entries for an item.
Usage
Change history records are only sent to users who have privileges to view the change history for the item on which the notification is based. For delayed escalations, changes may not be available.
Parameters
Insert the number of change history entries to return between the parentheses. If you do not specify a number in the parameter, all transitions and changed data are returned.
Sample
```
$CHANGES()
```
Result for HTML template:

You can optionally apply a cascading style sheet (CSS) to the $CHANGES() tag. For best results, place the CSS tags before the $CHANGES() tag, and place the $CHANGES() tag at the bottom of the template. For example:

<style media="screen" type="text/css">
table.serena_ns_changes_table {border: thin solid black;background-color:#0000ff;}
tr.serena_ns_changes_tr {background-color:#ff0000;}
td.serena_ns_changes_td_field {background-color:#777777;}
td.serena_ns_changes_td {background-color:#ffffff;}
</style>
$CHANGES()
</body>
</html>

Result:

$EMAILRESPONSE()

Description
Adds transition tokens to notification messages as discussed in E-mail Responses.
Usage
Add an $EMAILRESPONSE() tag for each e-mail response in a notification. Each response tag adds a unique token to the notification that represents a transition to be executed.
Parameters
The following parameters are available:
- Email
  Use the Email parameter to allow users to reply to the notification with a simple word that matches one of the aliases defined in the e-mail response. For example, when Bill receives an e-mail requesting his approval, he can reply to the message with a simple "Yes" or "No" and SBM will execute the matching Approve or Reject transition once his reply is received by the Mail Client. You configure the aliases and their matching transitions in the E-mail Responses tab of a notification.
- Mailto
  Use the Mailto parameter to allow users to click a link in the notification that pre-fills a reply with the Mail Client e-mail address and required token information. For example, a user can click an "approve" link, click send, and then the Mail Client will parse the reply and execute the matching Approve transition that is configured on the E-mail Responses tab of a notification.
- External and Internal links
  For HTML e-mail templates, you can insert the name of the e-mail response, followed by External or Internal. These parameters correspond to the Web server links that you configure for the Notification Server in SBM Configurator.
Important: For each parameter, you must enter the same response names that you specified in the E-mail Responses tab. For example, if you entered Approve for the "Manager Approval" transition, you must enter Approve in the $EMAILRESPONSE() parameter. Refer to the samples below for more detail.

Samples

Email

<body>
Reply to this e-mail with a YES or NO answer to approve or reject the request. Otherwise, 
the response with the highest priority is used.
<div>
$EMAILRESPONSE(Approve,Email)
</div>
<div>
$EMAILRESPONSE(Reject,Email)
</div>

Mailto

<body>
Click one of the following links to approve or reject, and then send the e-mail.
<div>
$EMAILRESPONSE(Approve,Mailto)
</div>
<div>
$EMAILRESPONSE(Reject,Mailto)
</div>

You can style the links that are created by the Mailto parameter using a defined css class in the template. For example:

<style type="text/css">
.approve {background-color:#060; color:White;}
.reject {background-color:#F00; color:White;}
</style>
<body>
Click one of the following links to approve or reject, and then send the e-mail.
<div class="approve">$EMAILRESPONSE(Approve,Mailto)</div>
<div class="reject">$EMAILRESPONSE(Reject,Mailto)</div>
</body>

External or Internal links:

$BEGINSUBJECT()$NOTIFICATION() - $ITEMNUMBER() $TTID()$ENDSUBJECT()
<meta http-equiv="Content-Type" content="text/html; charset=$GETSETTINGSSTR(CharSet,UTF-8)">
<title>$NOTIFICATION() - $ITEMNUMBER() $TTID()</title>
<style type="text/css">
a.attachlink:link { color: #0000FF }
a.attachlink:visited { color: #0000FF }
a.attachlink:hover { color: #006600 } 
</style>
$IF(AUXTABLE)$ELSE()$ENDIF()
<table>
<tbody>
<tr>
<td><b>$STRING(IDS_EMAIL_DISPLAYVALUE):</b></td>
<td>$ITEMNUMBER()</td>
</tr>
<tr>
<td><b>$SYSFIELDNAME(TS_SYSFLD_TEXT_DISPLAYID):</b></td>
<td>$ITEMNUMBER()</td>
</tr>
<tr>
<td><b>$SYSFIELDNAME(TS_SYSFLD_TITLE):</b></td>
<td>$TITLE()</td></tr>
</tbody>
</table>
<br>Dear $RECIPIENT(),<br><br><p align="left"> This ticket requires your approval.</p>
<p align="left"> To approve, click <a href="$EMAILRESPONSE(Approve, external)" 
style="background: #11356D; color: white; display: inline-block; width: auto; 
text-align: center;text-decoration:none;border:10px solid #11356D;">Approve</a></p>
<p align="left"> To reject, click <a href="$EMAILRESPONSE(Reject, external)" 
style="background: #11356D; color: white; display: inline-block; width: auto; 
text-align: center;text-decoration:none;border:10px solid #11356D;">Reject</a></p>
<br>$IF(CANVIEW)$IF(VIEWLINK)
<b>$STRING(IDS_EMAIL_TOVIEW) $ITEMTYPENAME():</b> $LINK( TRUE )$ENDIF()$ENDIF()<br>
<br>$IF(CANVIEW)$FIELDS()$ENDIF()<br>
<br>$FILEATTACHMENTLINKS()

In this example, the response names Approve and Reject are used. The second parameter (external or internal) configures the link for access outside or inside the firewall.

Result:

$FIELDS()

Description
Returns fields selected on the Fields page for each notification, as discussed in E-mail Field Settings.
Usage
Asterisks replace field values for users who do not have permission to view fields included in the notification. Fields in the Not Used fields section are not included in the e-mail notification.
Parameters
For HTML e-mail templates, insert the number of display columns between the parentheses. If you do not specify the parameter, the default number of display columns is 2. This parameter is ignored for text-formatted e-mail messages.
Sample
```
$IF(CANVIEW)
$FIELDS()
$ENDIF()
```
Result for user who cannot view specific fields:

$FILEATTACHMENTLINKS()

Description
Adds links to files attached to items associated with the e-mail notification.
Usage
Links to file attachments appear in the notification only if users have permissions to view those attachments in the associated item. Tag can be included in text-based messages, but links are not clickable.
Parameters
- external - Optional. Add link to attachments in an external instance of SBM.
Sample
```
$FILEATTACHMENTLINKS()
          
```
Result:

$IF() Tags

Use with the following parameters and the $ELSE() and $ENDIF() conditional tags.

Note: All line breaks and spaces are left in the message during template processing. For statements to display as one line in the e-mail message, the conditional statement must not include any line breaks.

$IF(auxtable) and $IF(pritable)
- Description
  Use to specify which information should appear in the e-mail message if the notification is associated with a primary table or auxiliary table.
- Sample
```
$IF(AUXTABLE)(IDS_EMAIL_DISPLAYVALUE):$ITEMNUMBER()
$ELSE()
$SYSFIELDNAME(TS_SYSFLD_TEXT_DISPLAYID):$ITEMNUMBER()
$SYSFIELDNAME(TS_SYSFLD_TITLE):$TITLE()
$ENDIF()
```
  Result (for primary items):
  
  Result (for auxiliary items with Item ID field included in table):
$IF(CANVIEW, fieldname)
- Description
  Use to determine if the subscriber has privileges to view a specific field.
- Usage
  Fields specified in this tag must be selected on the Fields page for each notification, as discussed in E-mail Field Settings.
  
  Use with the $FIELDVALUE(fieldname) tag to show the field's current value in the e-mail message.
- Parameters
  - fieldname
    Returns the logical field name.
- Sample
```
Item is assigned to 
      $IF(CANVIEW,Doc Lead)
      $FIELDVALUE(Doc Lead) 
      $ELSE()
      a Manager
      $ENDIF()
```
  Result for users who can view Doc Lead field:
  
  Results for users who cannot view Doc Lead field:
$IF(ITEMTYPE)
- Description
  Returns information based on the application to which the notification is related.
- Usage
  Parameters are based on table settings, which are available on the General tab of the Table property editor in SBM Composer.
- Parameters
  - singular item name
  - application prefix
- Sample
```
$IF(ITEMTYPE, Change Requests)
Send this information about Change Requests
$ELSE()
Send this information about all other item types
$ENDIF()
```
$IF(VIEWLINK)
- Description
  Returns a link to the item related to the notification to users who have the Include a Link to the Item check box selected in their user profile.
- Usage
  Must be used with $LINK tag, as shown in the following sample.
  
  When the $LINK tag is included in the template without the $IF(VIEWLINK) tag, users who do not have the Include a Link to the Item check box selected receive a message stating that the item was created, but they must select the check box in their user profile to receive links to items.
- Sample
```
$IF(VIEWLINK)
$LINK( TRUE )
$ELSE()
The item was created. However, if you would like to link back to 
this item you will need to go to your User Profile Page and 
select 'Include a link to the item'.  
$ENDIF()
```
  Result with Include a Link to the Item checked:
  
  Result without Include a Link to the Item checked:

$ITEMNUMBER()

Description
Returns the system-generated ID number.
Usage
For primary items, returns the prefix, if any, and ID number of the item associated with the e-mail notification. For auxiliary items, returns the ID number if the auxiliary table contains the system Item ID field. If it does not, the table's display name is returned.
Parameters
None.

Sample (Subject Line)

 $BEGINSUBJECT()$NOTIFICATION() - $ITEMNUMBER() $ENDSUBJECT()

Result:

$ITEMTYPENAME()

Description
Returns the singular item name for the primary or auxiliary table.
Usage
The singular item name is specified in SBM Composer and can be viewed in the General tab of the Edit Table property editor for the applicable table.
Parameters
None.

Sample

$STRING(IDS_EMAIL_TOVIEW) $ITEMTYPENAME(): $LINK( TRUE )

Result:

$MAILHEADERPARAM()

Description
Returns custom header information.
Usage
Use to add information to the e-mail header. For example, you can return sender information in the header.

For best results, use both the header name and header value parameters, as shown in the sample below.
Parameters
- MSG_
  Use to indicate message headers.
- BDY_
  Use to indicate body headers.
- Header Name
  Use to label header data.
- Header Value
  Use to provide header data.
- $FIELDVALUE
  Use $FIELDVALUE as a sub-tag to provide a Text or User field value.

Samples

$MAILHEADERPARAM(MSG_SENDER,admin@serena.com)

$MAILHEADERPARAM(BDY_SENDER,admin@serena.com)

Result

Or:
```
$MAILHEADERPARAM(MSG_TO,$FIELDVALUE(EMAILTO))
```
```
$MAILHEADERPARAM(MSG_CC,$FIELDVALUE(admin@serena.com))
```
In this example, EMAILTO is a Memo field that supplies a text value.

To use the email address from a user account, specify the user object on an item, and then the EMAIL parameter:
```
$MAILHEADERPARAM(MSG_TO,$FIELDVALUE(SUBMITTER.EMAIL))
```

$NOTES()

Description
Includes notes added to an item by users or by e-mail messages.
Usage
Individual notes that exceed the character limit specified in SBM Configurator are added to the notification as attachments.

Notes are only included with a notification if users have privileges to view those notes in the associated item.
Parameters
- $NOTES() or $NOTES(0) – Displays all notes on the item.
- $NOTES(N) – Returns the last N number of notes on the item. For example, $NOTES(3) returns the last three notes that were added to the item.
- $NOTES(-N) – Returns the first N number of notes on the item. For example, $NOTES(-3) returns the first three notes that were added to the item.
Sample
```
$NOTES()
        
```
Result:

$NOTIFICATION()

Description
Returns the name of the notification.
Usage
The notification name is available on the General page when you are adding or editing notifications and escalations.
Parameters
None.

Sample

$NOTIFICATION() - $ITEMNUMBER()

$PAUSESTATUS()

Description
Returns whether the item is paused or unpaused.
Usage
Use to indicate whether an item is paused or unpaused. If an item has been paused, the tag returns "Paused".
Parameters
None.
Sample
```
$PAUSESTATUS()
```

$RECIPIENT()

Description
Returns the name of the notification recipient.
Usage
The name specified in the Full Name box in the user's profile is used.
Parameters
None.
Sample
```
To $RECIPIENT():
        
```
Result:

$RECIPIENTEMAIL()

Description
Returns the e-mail address of the notification recipient.
Usage
All e-mail addresses specified for a user are returned. Mutiple e-mail addresses are separated by a semi-colon.
Parameters
None.

Sample

To $RECIPIENT() at $RECIPIENTEMAIL():

Result:

$REPEATCOUNTER()

Description
Returns the current number of repeated notifications.
Usage
Use this tag to display the number of times that the notification has been repeated.
Parameters
None.

Sample

Number of repeated notifications: $REPEATCOUNTER()

Result:

Number of repeated notifications: 5

$TITLE()

Description
Returns the title of the item associated with the notification.
Usage
Information provided in the system Title field is used.
Parameters
None.

Sample

$SYSFIELDNAME(TS_SYSFLD_TITLE): $TITLE()

Result:

$TRIGGEREDDATETIME()

Description
Returns the date and time the notification rule became "true" for an item.
Usage
Date and time are formatted for the locale set in each user's profile.
Parameters
None.

Sample

This notification was triggered at $TRIGGEREDDATETIME()

Result:

$TTID()

Description
Returns the identifier ([ttid: table ID, record ID]) required by the E-mail Recorder feature, which attaches replies to the e-mail notification to the item to which it pertains.
Usage
By default, the $TTID() tag is enclosed by the $BEGINSUBJECT() and $ENDSUBJECT() base template tags in the default.txt notification template. If the E-mail Recorder is not configured, this tag is ignored. For details on the E-mail Recorder, refer to the SBM Installation and Configuration Guide.
Parameters
None.

Sample

$BEGINSUBJECT()$NOTIFICATION() - $ITEMNUMBER() $TTID()$ENDSUBJECT()

Result: