Modify Notification Methods

This article contains the following topics:
casm1401
This article contains the following topics:
The CA SDM automatic notification methods notify personnel at key points in the service desk management process. The standard notification methods are shown as follows:
  • Email
  • Notification (Log)
  • Pager_Email
You can define modified notification methods to specify new methods of transmission. For example, voice mail, display boards, or a specific printer. You can also access data from another application and include it in the notification message.
The Notification Process
Ticket notifications (applicable to issues, change orders, and requests) are processed when the ticket is saved:
  • If the notification method is other than Notification, such as Email, the notification processor executes the notification method for each contact in the list. This method is typically an executable or shell script, which is launched in a new process. Details about the notification are stored in environment variables for easy access by the executable/script.
  • For each notification requested, the notification processor sets the NX_NTF_MESSAGE and NX_NTF_SUMMARY environment variables using the Notification Message Title and Notification Message Body information that is provided on the Message Template notebook page of the Activity Notifications Detail window. If the recipient is a valid contact, other environment variables are created using information in their Contact Detail record.
  • If the Write To File option is selected for the notification, a text file is created. The text file indicates that the notification method can use to obtain more detailed information.
  • A list of contacts to receive the notification is built from the information that is provided on the Objects, Contacts, Types, and Survey notebook pages of the Activity Notifications Detail window. For those having a notification method matching the Notify Level and the log_all_notify Options Manager option that is installed, a notification is generated first to the notification log.
Notification Method Variables
Two sets of variables are created and made available to the notification method.
Basic Environment Variables
The first set of variables is created for every notification that is sent, independent of whether you select the Write To File option for the notification. They are written to the environment as environment variables that the notification method can access in the standard way.
The following environment variables give you basic information about the notification. They are always defined, even if the corresponding value is empty:
Environment Variable
Description
NX_NTF_MESSAGE
The completed message template text, including full expansion of all variables
NX_NTF_SUMMARY
The completed message template header, including full expansion of all variables
NX_NTF_URGENCY
The notification urgency (1 is low, 4 is emergency)
The following environment variables are created only if the recipient is a valid CA SDM contact. The variables are set using values from the Contact Detail record of the recipient as shown in the following table:
Variable
Contact Detail Window Fields
NX_NTF_BEEPER_PHONE
Pager Number
NX_NTF_COMBO_NAME
Last Name, First Name, Middle Name
NX_NTF_CONTACT
Contact ID
NX_NTF_EMAIL_ADDRESS
Email or Pager Email Address (depending on notification type)
NX_NTF_FAX_PHONE
Fax Number
NX_NTF_PUBLIC_PHONE
Phone Number
NX_NTF_USERID
User ID
NX_NTF_VOICE_PHONE
Alt. Phone #
These variables are not created if the corresponding values are empty (except for NX_NTF_CONTACT, which cannot be empty).
Attribute Variables
The second set of variables is available only if you select the Write To File option when you define the notification method.  The following attributes are called attribute variables and are written to the notification file only -- not to the environment. They are of the form:
NX_NTF_attribute[
.
secondary_attribute]=value
  • attribute
    The name of the attribute whose value you want to obtain. This value is the attribute name as defined for the object. For a complete list of all attribute names for any object, see CA Service Desk Manager Reference Commands. The most common objects that are associated with notifications are the ticket, which has an object name dependent of the type of ticket (for example, cr for requests), and the contact identifying the recipient, which has an object name of cnt. For example, the environment variable for the description attribute of a ticket can look as follows in the notification file:
    • NX_NTF_DESCRIPTION=<sample description>
  • secondary_attribute
    If the first
    attribute
    is an internal identifier for another object, a secondary attribute is attached to give more meaningful information using the dot notation. In database terms, attribute is a foreign key that points to a row in another table, rather than a simple data value. Using this raw key value would probably have little meaning. Many of these types of fields are resolved or de-referenced for you. The secondary_attribute is the value in the referenced table. For example, instead of writing the value for the assignee attribute, which is stored as the unique ID of the contact record for the assignee, the assignee’s combined name is the combo_name attribute for the contact object, as shown in the following example:
    NX_NTF_ASSIGNEE.COMBO_NAME=Armstrong, Beth
    If an attribute does not have a value, the corresponding value is usually (NULL) or blank. For example:
    NX_NTF_CALL_BACK_DATE=(NULL)
    NX_NTF_GROUP.COMBO_NAME=
An attribute variable that exists for both the ticket and the recipient is NX_NTF_ID (the id attribute), which is the unique database ID for the object.
The Notification File
If you select the Write To File option when you define a notification method, all the basic environment and attribute variables are written to a text file. This file is closed before executing the notification method script or program. This notification file is updated every time the notification method is invoked for a contact. This method is a handy mechanism for passing relevant information to the notification script that is not otherwise available in the environment.
The full path of the notification file is set in the NX_NTF_FILENAME environment variable, which is available to the notification method  . The file name is also added to the end of value you enter in the Notification Method field when defining the notification method. For example, if the Notification Method is ‘pdm_perl - w mymethod.pl’, then the actual process executes ‘pdm_perl - w mymethod.pl
unique_notification_file_name
’.
The administrator can clean up the notification files. This clean-up is especially important for a site using a high volume of notifications. The files are located in the standard temporary directory (TEMP on Windows and TMP on UNIX). One suggestion is to delete the file at the end of the notification method script/program.
The notification file is a standard text file that is divided into sections. Each line contains either an attribute/value pair or a section marker. Each notification file has three sections. All sections begin with “-----” followed by a new line.
  • SECTION=obj
    , where obj identifies the object type of the ticket
    • Iss
      Provides information about the issue.
    • Chg
      Provides information about the change order.
    • Cr
      Provides information about the request.
  • SECTION=cnt
    Provides information about the recipient.
  • SECTION=notification
    Provides the same information that is available from the basic environment variables.
The section names for the ticket and recipient are actually the object names for the attributes in that section. For a complete list of all attribute names for any object, see the CA Service Desk Manager Reference Commands section.
Several lines of attribute/value pairs, each of which represents an attribute of the corresponding object, are contained in each section. The Attribute Variables in this section provide the detailed information about how these lines are formatted and what they mean.
Line breaks in an attribute value are reproduced as new lines in the notification file. Your notification method process can only use the attribute or value lines that begin with NX_NTF, and section markers. Generate a sample file and look at its contents before working with a notification file in your notification method process.
Using Perl Scripts
Most notification methods invoke an executable or shell script to read the environment variables and send the message. This action works well on most UNIX servers, but difficulties arise reading the environment variables on a Windows server.
You can use a Perl script to overcome environment problems on Windows. CA SDM includes a ready-to-use installation of the Perl interpreter named pdm_perl. Any Perl script that is invoked with pdm_perl as a notification method can reliably obtain the environment variables. The Perl script can read and format the environment variable values. The script can also carry on with the rest of the notification, such as invoking a pager or sending an email.
For Windows-based servers, consider using the launchit utility. You can invoke your scripts or programs in a shell environment with the proper environment variables set.
For example, suppose that you write a Perl script that is named read_env.pl to read several of the environment variables. You can invoke this script for a notification by entering the following command in the Notification Method field on the Notification Method Detail window:
pdm_perl
script_path
/read_env.pl
This notification method starts the Perl interpreter and executes the instructions in read_env.pl script.
Create a Notification Method
Follow these steps:
  1. Create a script to process the message template and transmit it to the recipient. The script can be any executable, depending on the platform. Third-party or public domain interpreters can also be used. Typically, Bourne shell scripts are used on UNIX and .bat files are used on Windows. If your script requires a special template, create it.
  2. Add the new notification method to your site using the web interface.
Create a Script
You can create a notification method script.
Follow these steps:
  1. Determine how you want the notification to be delivered (for example, printed on a particular printer).
  2. Determine the contents of the notification message.
  3. Specify what information from the message template to include in the notification.
  4. Set up a script to transmit the notification.
  5. Place the script in an executable file in the path of the CA SDM server.
Add the Notification Method
After you create a script, define the new notification method to CA SDM. You can use
one
of the following methods to add a notification method:
  • Using the web interface
  • Using a UNIX shell script
Add a Notification Method Using the Web Interface
Use the web interface to add a notification method.
Add a Notification Method Using a UNIX Shell Script
The following steps create a notification method shell script that sends the notification message to the service desk printer, SDPR2. In this example, the notification message consists of the message header and the message text from the message template:
  1. Set up the shell script to assemble the notification text and transmit it, as follows:
    #!/bin/sh echo " TO: $NX_NTF_USERID SUBJECT: $NX_NTF_SUMMARY MESSAGE: $NX_NTF_MESSAGE" |lp -dSDPR2
  2. Name the executable file sd_print. Place it in any directory that is used for common scripts at your site, such as /usr/local/netbin.
  3. Make the shell script an executable file using chmod.
  4. Select Notification Methods from Notifications on the Administration Interface.
  5. Select New from the File menu.
  6. Enter data in these fields:
    • Symbol
      SDPR2
    • Description
      Send backup notification to service desk printer SDPR2
    • Notification Method
      /usr/local/netbin/sd_print
  7. Click the Save button to save the new record. Then click Close Window to close the detail window.