home > Configuring Notifications

Configuring Notifications

OSCARS includes the ability to send notifications of events that occur as reservations are processed. See createReservation state diagram. The OSCARS Notification broker is the service that listens to the various OSCARS processes and distributes the notifications. Notifications may take many forms including emails, web service messages, or domain-specific API calls to a monitoring service. OSCARS comes pre-installed with a module for sending email notifications, but it is possible to write custom modules that send other types of notifications. This section describes how to run the notification server and how to customize email messages sent by the default module.

Starting the Notification Server

The OSCARS notification broker is included in the distribution is built by the ant task build-all, and deployed by deployall. It is started by the oscars.sh script along with everything else.

Event Types

An event may be triggered each time a reservation changes state. Below is a list of possible events that may trigger notifications to be sent. The ones used by your host are set in conf/notify/idc-topicnamespace.xml where they are catagorized by the topicsets defined in conf/notify/topicset.xml: IDC, INFO, DEBUG, ERROR. A user may subscibe to notifications that correspond to a specific topic set. The IDC set is the minum required set of messages that an IDC must see. INFO is the minimum set for end users. DEBUG are event useful for  monitoring or debugging, and ERRORs are the failure messages.

Operations on Reservations

Event Name
Description
RESERVATION_CREATE_RECEIVED
DEBUG
RESERVATION_CREATE_ACCEPTED
DEBUG
RESERVATION_CREATE_STARTED DEBUG
RESERVATION_CREATE_FORWARD_STARTED DEBUG
RESERVATION_CREATE_FORWARD_ACCEPTED DEBUG
RESERVATION_CREATE_COMPLETED IDC INFO
RESERVATION_CREATE_CONFIRMED IDC
RESERVATION_CREATE_FAILED IDC INFO ERROR
RESERVATION_MODIFY_RECEIVED
DEBUG
RESERVATION_MODIFY_ACCEPTED
DEBUG
RESERVATION_MODIFY_STARTED DEBUG
RESERVATION_MODIFY_FORWARD_STARTED DEBUG
RESERVATION_MODIFY_FORWARD_ACCEPTED DEBUG
RESERVATION_MODIFY_COMPLETED IDC INFO
RESERVATION_MODIFY_CONFIRMED IDC
RESERVATION_MODIFY_FAILED IDC INFO ERROR
RESERVATION_CANCEL_RECEIVED
DEBUG
RESERVATION_CANCEL_ACCEPTED
DEBUG
RESERVATION_CANCEL_STARTED DEBUG
RESERVATION_CANCEL_FORWARD_STARTED DEBUG
RESERVATION_CANCEL_FORWARD_ACCEPTED DEBUG
RESERVATION_CANCEL_COMPLETED IDC INFO
RESERVATION_CANCEL_CONFIRMED IDC
RESERVATION_CANCEL_FAILED IDC INFO  ERROR
RESERVATION_QUERY_RECEIVED
DEBUG
RESERVATION_QUERY_STARTED DEBUG
RESERVATION_QUERY_FORWARD_STARTED DEBUG
RESERVATION_QUERY_FORWARD_COMPLETED DEBUG
RESERVATION_QUERY_RETURNED DEBUG
RESERVATION_QUERY_COMPLETED DEBUG
QUERY_RESERVATION_FAILED ERROR
RESERVATION_LIST_RECEIVED
DEBUG
RESERVATION_LIST_STARTED DEBUG
RESERVATION_LIST_FORWARD_STARTED DEBUG
RESERVATION_LIST_FORWARD_COMPLETED DEBUG
RESERVATION_LIST_RETURNED DEBUG
RESERVATION_LIST_COMPLETED DEBUG
LIST_RESERVATION_FAILED ERROR



Operations on paths

Event Name
Description
PATH_SETUP_RECEIVED
DEBUG
PATH_SETUP_ACCEPTED
DEBUG
PATH_SETUP_STARTED
DEBUG
PATH_SETUP_FORWARD_STARTED
DEBUG
PATH_SETUP_FORWARD_ACCEPTED
DEBUG
DOWNSTREAM_PATH_SETUP_CONFIRMED
IDC
UPSTREAM_PATH_SETUP_CONFIRMED
IDC
PATH_SETUP_COMPLETED
IDC INFO
PATH_SETUP_FAILED
IDC INFO ERROR
PATH_TEARDOWN_RECEIVED
DEBUG
PATH_TEARDOWN_ACCEPTED
DEBUG
PATH_TEARDOWN_STARTED
DEBUG
PATH_TEARDOWN_FORWARD_STARTED
DEBUG
PATH_TEARDOWN_FORWARD_ACCEPTED DEBUG
DOWNSTREAM_PATH_TEARDOWN_CONFIRMED
IDC
UPSTREAM_PATH_TEARDOWN_CONFIRMED
IDC
PATH_TEARDOWN_COMPLETED
IDC INFO
PATH_TEARDOWN_FAILED
IDC INFO ERROR
PATH_REFRESH_RECEIVED
DEBUG
PATH_REFRESH_ACCEPTED
DEBUG
PATH_REFRESH_STARTED
DEBUG
PATH_REFRESH_FORWARD_STARTED
DEBUG
PATH_REFRESH_FORWARD_ACCEPTED
DEBUG
DOWNSTREAM_PATH_REFRESH_CONFIRMED
IDC
UPSTREAM_PATH_REFRESH_CONFIRMED
IDC
PATH_REFRESH_COMPLETED IDC INFO
PATH_REFRESH_FAILED
IDC INFO ERROR


Miscellaneous

Event Name Description
IDC_STARTED
DEBUG
IDC_FAILED ERROR
RESERVATION_EXPIRES_IN_1DAY
DEBUG
RESERVATION_EXPIRES_IN_7DAYS
DEBUG
RESERVATION_EXPIRES_IN_30DAYS
DEBUG
RESERVATION_PERIOD_STARTED
DEBUG
RESERVATION_PERIOD_FINISHED
DEBUG

Email Notifications

OSCARS comes pre-installed with a module that sends email notifications of events. This module has customization capabilites that allow administrators to tailor messages to their specific needs. The format of messages is determined by the templates found in $CATALINA_HOME/shared/classes/server/mail_templates. The name of each template file takes the form of of EVENT_NAME.xml where EVENT_NAME corresponds to the event that triggers the email message using the template. If no template file exists for a particular event then no email notifications will be sent for that event. The distribution inlcudes these templates in conf/mail_templates.

The template files follow a very simple XML format. The template is wrapped inside an oscarsMail element that has the following subelements:

The templates support the use of dynamic fields that are populated with event-specific information at the time the event occurs. Dynamic fields are surround by ## characters and take the form ##FIELD_NAME## where FIELD_NAME is the name of the dynamic field. Dynamic fields may be used in the subject or messageBody of a template. Below is a list of supported dynamic fields:

Field Name
Description
##event##
A string representation of all the event fields.
##eventType##
The type of event that occurred
##eventTimestamp##
The UTC date and time indicating when the reported event ocurred
##eventUserLogin##
The login of the user that triggered the event. (NOTE: This may be different that the user that created a reservation originally)
##eventSource##
The OSCARS component that caused the event. Currently the value may be API, WBUI, or SCHEDULER>
##errorCode##
An error code identifying an error, if one occurred.
##errorMessage##
A description of an error, if one occurred.
##reservation##
A string representation of the reservation the event affects.
##gri##
The global reservation identifier of the affected reservation
##startTime##
The UTC start time of the affected reservation
##endTime##
The UTC end time of the affected reservation
##createdTime##
The UTC time that the affected reservation was created
##bandwidth##
The bandwidth of the affected reservation
##resvUserLogin##
The login of the user that created the affected reservation
##status##
The status of the affected reservation
##description##
The description field of the affected reservation
##pathSetupMode##
The path setup mode (timer-automatic or signal-xml) of the affected reservation
##isExplicitPath##
A flag ndicating whether the reservation path was explicitly set by the user
##nextDomain##
The next domain a reservation traverses beyond the current domain
##l2Source##
For layer 2 reservations, the URN of the reservation source
##l2Dest##
For layer 2 reservations, the URN of the reservation destination
##l3Source##
For layer 3 reservations, the hostname/IP address of the reservation source
##l3Dest##
For layer 3 reservations, the hostname/IP address of the reservation destination
##l3SrcPort##
For layer 3 reservations, the TCP/UDP port of the source
##l3DestPort##
For layer 3 reservations, the TCP/UDP port of the destination
##protocol##
For layer 3 reservations, the transport protocol (i.e. TCP or UDP)
##dscp##
For layer 3 reservations, the differentiated services code point
##dscp##
For MPLS reservations, the burst limit of the reservation
##lspClass##
For MPLS reservations, the LSP class of the reservation
##TAG:TAG_NAME##
A special dynamic field for including user-defined tags identified by TAG_NAME in email messages. User-defined tags may be included in the reservation description at creation between square brackets[]. This field is useful for triggering the OSCARS email module to search for tags and include them in other areas of the message, such as the subject. For example, including the dynamic field ##TAG:PRODUCTION CIRCUIT## in a template will search each reservation description for the tag [PRODUCTION CIRCUIT]. If present in the reservation description, the string [PRODUCTION CIRCUIT] will be included in the resulting email message at the location of this field in the template. If not found, this field will be replaced with an empty string in the email message.