home > Configuring Notifications

Configuring Notifications

OSCARS includes the ability to send notifications of events that occur as reservations are processed. The OSCARS notification server is the component 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 server is included in the distribution and can be found in the tools/notify directory. Run the following commands to start the notification server:

Event Types

Below is a list of events that may trigger notifications to be sent.

Basic Operations:
Event Name
Description
RESERVATION_CREATE_STARTED

RESERVATION_CREATE_COMPLETED

RESERVATION_MODIFY_STARTED

RESERVATION_MODIFY_COMPLETED

RESERVATION_CANCEL_STARTED

RESERVATION_CANCEL_COMPLETED

PATH_SETUP_STARTED

PATH_SETUP_COMPLETED

PATH_TEARDOWN_STARTED

PATH_TEARDOWN_COMPLETED

LIST_RESERVATION_STARTED

LIST_RESERVATION_COMPLETED

QUERY_RESERVATION_STARTED

QUERY_RESERVATION_COMPLETED

RESERVATION_PERIOD_STARTED

RESERVATION_PERIOD_FINISHED

RESERVATION_CANCELLED

RESERVATION_EXPIRES_IN_1DAY

RESERVATION_EXPIRES_IN_7DAYS

RESERVATION_EXPIRES_IN_30DAYS



Messaging:
Event Name
Description
RESERVATION_CREATE_RECEIVED

RESERVATION_CREATE_RETURNED

RESERVATION_MODIFY_RECEIVED

RESERVATION_MODIFY_RETURNED

RESERVATION_CANCEL_RECEIVED

RESERVATION_CANCEL_RETURNED

PATH_SETUP_RECEIVED

PATH_SETUP_RETURNED

PATH_TEARDOWN_RECEIVED

PATH_TEARDOWN_RETURNED

LIST_RESERVATION_RECEIVED

LIST_RESERVATION_RETURNED

QUERY_RESERVATION_RECEIVED

QUERY_RESERVATION_RETURNED



Forwarding:
Event Name
Description
RESERVATION_CREATE_FORWARD_STARTED

RESERVATION_CREATE_FORWARD_COMPLETED

RESERVATION_MODIFY_FORWARD_STARTED

RESERVATION_MODIFY_FORWARD_COMPLETED

RESERVATION_CANCEL_FORWARD_STARTED

RESERVATION_CANCEL_FORWARD_COMPLETED

PATH_SETUP_FORWARD_STARTED

PATH_SETUP_FORWARD_COMPLETED

PATH_TEARDOWN_FORWARD_STARTED

PATH_TEARDOWN_FORWARD_COMPLETED

LIST_RESERVATION_FORWARD_STARTED

LIST_RESERVATION_FORWARD_COMPLETED

QUERY_RESERVATION_FORWARD_STARTED

QUERY_RESERVATION_FORWARD_COMPLETED



Errors:
Event Name
Description
RESERVATION_CREATE_FAILED

RESERVATION_MODIFY_FAILED

RESERVATION_CANCEL_FAILED

PATH_SETUP_FAILED

PATH_TEARDOWN_FAILED

LIST_RESERVATION_FAILED

QUERY_RESERVATION_FAILED

IDC_FAILED

FORWARDING_FAILED


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 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.