sendToNotifier

You can use the sendToNotifier command to manage email and web service subscriptions.

The sendToNotifier command sends a command (specified in an XML input file) to the Notifier Service for processing. You can create an email subscription, list existing subscriptions, delete subscriptions, and so forth. The command returns the response document returned by the Notifier Service. To issue additional commands, you must call sendToNotifier again, specifying an input file that contains a different command.

Command syntax for sendToNotifier is fairly simple, but creating the input command document can be complicated.

Business Transaction Management currently supports email and web service subscriptions only through the command line interface.

The command document, described at the end of this section, can contain an xml message (command) that accomplishes one of the following tasks:

Create an email subscription
Create a subscription to call a notification operation on a web service
List existing subscriptions
Delete a subscription from the notifier

Command Syntax

btmcli sendToNotifier -i inputFile [-o outputFile] 
                      -s sphereUrl -l username:password

Name	Long Name	Description
-i	-inputFile	An XML file containing the command to send to the Notifier Service. Each file can contain one command.
-o	-outputFile	A file to hold the response from the Notifier Service. If none is specified, the response is sent to stdout.
-s	-sphereUrl	The URL of the sphere. http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere.
-l	-userLogin	The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role. See Security Options in Accessing CLI Commands for information on furnishing login credentials. You can encrypt passwords using the `encryptPassword` command.

Setting up Email Notification

The use of sendToNotifier is one step in setting up email notification. The overall procedure also includes the following steps:

Select System Services from the Navigator and select AP_Notifier_Service from the services listed in the summary area.
Edit its setup data (from the Admin menu) to specify the mail host and the email sender to be used.

Use the sendToNotifier command to register a subscription to SLA alerts, condition alerts, and so on. (The input command document will contain a command that specifies which alerts you are interested in.) For example, the following document registers a subscription for condition alerts:

<ap:registerSubscription
   soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <ap:subscription name="All Exception Alerts" enabled="true" userID="testID">
    <ap:deliveryMechanism> 
      <ap:sendEmail format="long" style="html">
           <ap:from>BTM.TEST@oracle.com</ap:from> 
           <ap:recipient type="TO">your.name@yourdomain.com</ap:recipient> 
      </ap:sendEmail> 
  </ap:deliveryMechanism> 
  <ap:notificationFilters> 
      <ap:source> 
           <ap:value>ExM</ap:value> 
           <ap:operation>in</ap:operation> 
      </ap:source> 
   </ap:notificationFilters> 
  </ap:subscription> 
 </ap:registerSubscription>

Define SLA or condition alerts for the objects of interest.

Managing Email Notifications

You can also use sendToNotifier to list subscriptions and delete subscriptions. Here are sample command documents that illustrate how you would do this.

To list subscriptions

<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf"/>

To cancel subscriptions

<ap:cancelSubscription xmlns:ap="http://namespace.amberpoint.com/amf">
 <ap:subscription name="All Exception Alerts" userID="testID"/>
 <ap:subscription name="All SLA Alerts" userID="testID"/>
 <ap:subscription name="All System Alerts" userID="testID"/>
</ap:cancelSubscription>

Examples

The following example shows the sendToNotifier command.

btmcli sendToNotifier -i MyNotifierCommand -o MyNotifierReponse 
               -s http://localhost:8080/btmcentral/sphere -l admin:abracadabra

The Notifier Command Document

A Notifier Service command (xml message) can be included in a command document that is input to the sendToNotifier command. Notifier service commands are described in the following subsections; they allow you to do the following:

Create an email subscription
Create a web service subscription
List subscriptions
Delete a subscription
Get notification interest
Get a template

You may include only one command per document. To execute several commands, you must create a document for each command and invoke the sendToNotifier command for each document.

Notifier Service Commands

The following subsections describe the commands you can include in a Notifier Document.

Create an Email Subscription

This command supports the following variations:

Create a subscription for all alerts of a particular type (e.g. system alert, SLA alert, condition alert)
Create a subscription for all alerts on a particular object (e.g. transaction, service, endpoint, operation, consumer, system service)
Create a subscription for all alerts of a particular severity (e.g. failures and warnings, but not compliance or info alerts)
Create a subscription for all alerts generated by a particular policy (e.g. all alerts generated by the Baseline SLA Policy)
Create a subscription for all alerts generated by a particular condition (e.g. all condition alerts for the FaultMonitoring condition)

In addition to the sample commands below, you also need to be familiar with the metadata used to specify alert types. This is described in the next subsection.

<ap:registerSubscription xmlns:ap="http://namespace.amberpoint.com/amf"
                xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
                xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
                xmlns:xsd="http://www.w3.org/1999/XMLSchema"
                soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <ap:subscription name="All SLA Alerts" enabled="true" userID="testID">
   <ap:deliveryMechanism>
         <ap:sendEmail format="short" style="text">
           <ap:from>BTM.TEST@oracle.com</ap:from>
           <ap:recipient type="TO">your.email@oracle.com</ap:recipient>
         </ap:sendEmail>
   </ap:deliveryMechanism>
   <ap:notificationFilters>
         <ap:source>
           <ap:value>ASLM</ap:value>
           <ap:operation>in</ap:operation>
         </ap:source>
   </ap:notificationFilters>
 </ap:subscription>
</ap:registerSubscription>

Here is a more detailed example with comments:

<ap:registerSubscription xmlns:ap="http://namespace.amberpoint.com/amf"
             xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
             xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/1999/XMLSchema"
             soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <ap:subscription name="Warning and Failure SLA Alerts" enabled="true"
                                                          userID="testID">
    <ap:deliveryMechanism>
      <ap:sendEmail format="long" style="html">
        <ap:from>BTM.TEST@oracle.com</ap:from>
        <ap:recipient type="TO">your.name@oracle.com</ap:recipient>
      </ap:sendEmail>
    </ap:deliveryMechanism>
    <ap:notificationFilters>
     <ap:source>
        <ap:value>ASLM</ap:value><!-- subcribe to SLA alerts -->
        <ap:operation>in</ap:operation>
     </ap:source>
     <ap:severity>
      <ap:value>WARNING</ap:value> <!-- subcribe to WARNING and FAILURE alerts -->
      <ap:value>FAILURE</ap:value>
      <ap:operation>in</ap:operation>
     </ap:severity>
    </ap:notificationFilters>
 </ap:subscription>
 <ap:subscription name="Exception Alert transaction OrderService_submit"
                                           enabled="true" userID="testID">
 <ap:deliveryMechanism>
   <ap:sendEmail format="short" style="text">
      <ap:from>BTM.TEST@oracle.com</ap:from>
      <ap:recipient type="TO">your.name@oracle.com</ap:recipient>
   </ap:sendEmail>
 </ap:deliveryMechanism>
 <ap:notificationFilters>
     <ap:event>
      <ap:value>Exception Detected</ap:value> <!-- subscribe to Exception alert
                                                                  event-->
      <ap:operation>in</ap:operation>
     </ap:event>
   <ap:info>
     <ap:name>correlationName</ap:name> <!-- subcribe to tx by friendly name-->
     <ap:value>OrderService_submit</ap:value>
     <ap:operation>in</ap:operation>
   </ap:info>
  </ap:notificationFilters>
 </ap:subscription>
</ap:registerSubscription>

Create a Web Service Description

This command supports the following variations:

Create a subscription for all alerts of a particular type (e.g. system alert, SLA alert, condition alert)
Create a subscription for all alerts on a particular object (e.g. transaction, service, endpoint, operation, consumer, system service)
Create a subscription for all alerts of a particular severity (e.g. failures and warnings, but not compliance or info alerts)
Create a subscription for all alerts generated by a particular policy (e.g. all alerts generated by the Baseline SLA Policy)
Create a subscription for all alerts generated by a particular condition (e.g. all condition alerts for the FaultMonitoring condition)

<ap:registerSubscription xmlns:ap="http://namespace.amberpoint.com/amf"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/1999/XMLSchema"
    soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
       <ap:subscription name="Dispatch" enabled="true" userID="ABC">
         <ap:deliveryMechanism>
           <ap:callWebService>
              <ap:httpEndPoint>
            <ap:uri>http://10.148.118.72:8080/eProxy/svc/NotifPort_Proxy</ap:uri>
                   <!-- this is my test webService, replace with your own.-->
         <ap:soapAction>ReplaceWithRealSoapActionForDotNetService</ap:soapAction>
              </ap:httpEndPoint>
           </ap:callWebService>
         </ap:deliveryMechanism>
         <ap:notificationFilters>
            <ap:source>
                           <ap:value>ASLM</ap:value>
                           <ap:value>ExM</ap:value>
                           <ap:value>System</ap:value>
                           <ap:operation>in</ap:operation>
           </ap:source>
        </ap:notificationFilters>
    </ap:subscription>
 </ap:registerSubscription>

Get Subscriptions

This command supports the following variations:

List all email subscriptions
List all web service subscriptions
List all subscriptions for a particular email address
List all web service subscriptions for a particular web service
List all subscriptions for a particular object (transaction, service, endpoint, operation, system service, consumer)

Here are some examples for these actions:

Get all subscriptions

<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf"/>

Get subscriptions by subscription name

<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf">
         <ap:subscription name="Dispatch"/>
</ap:getSubscription>

Get subscriptions by user name

<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf">
    <ap:subscription userID="mary"/> 
</ap:getSubscription>

Cancel Subscription

This command supports the following variations:

Delete all subscriptions for a particular email address
Delete all web service subscriptions for a particular web service
Delete all subscriptions on a particular object (e.g. transaction, service, endpoint, operation, system service, consumer)

For example,

<ap:cancelSubscription xmlns:ap="http://namespace.amberpoint.com/amf">
          <ap:subscription name="Dispatch" userID="mary"/> </ap:cancelSubscription>

Get Format Information

This command returns available formats such as "long HTML", "short text." The following is sample output for the command:

<ap:getFormatInformationResponse xmlns:ap="http://namespace.amberpoint.com/amf"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
 <ap:for value="Email" xmlns:ap= "http://namespace.amberpoint.com/amf">
   <ap:format value="long"xmlns:ap="http://namespace.amberpoint.com/amf"/> 
   <ap:format value="short" xmlns:ap="http://namespace.amberpoint.com/amf"/>
   <ap:style value="html" xmlns:ap="http://namespace.amberpoint.com/amf"/> 
   <ap:style value="text" xmlns:ap="http://namespace.amberpoint.com/amf"/> 
  </ap:for> 
</ap:getFormatInformationResponse

Get Notification Interest

Use a command like the following:

<ap:getNotificationInterest xmlns:ap="http://namespace.amberpoint.com/amf"/>

Get Template

Use a command like the following:

<ap:getTemplate/>

Metadata for Alert Types

You will need to be familiar with metadata for SLA, Exception, and system alerts. You use this information to properly format a subscription for a particular type of information. Metadata information is shown in the following tables.

Metadata for SLA Alerts

The following table specifies metadata for SLA alerts.

Metadata	Available values	Sample subscription
(header) source	ASLM	<ap:notificationFilters> <ap:source> <ap:value>ASLM</ap:value> <ap:operation>in</ap:operation> </ap:source> </ap:notificationFilters>
(header) event	enforcement_condition	<ap:notificationFilters> <ap:event> <ap:value>enforcement_condition</ap:value> <ap:operation>in</ap:operation> </ap:event> </ap:notificationFilters>
(header) severity	WARNING FAILURE SUCCESS INFO	<ap:notificationFilters> <ap:severity> <ap:value>WARNING,FAILURE</ap:value> <ap:operation>in</ap:operation> </ap:severity> </ap:notificationFilters>
(header) templateSet	ASLM-Template	<ap:notificationFilters> <ap:templateSet> <ap:value>ASLM-Template</ap:value> <ap:operation>in</ap:operation> </ap:templateSet> </ap:notificationFilters>
(info) com.amberpoint.notification.enforcementValue	(value of SLA enforcement that triggered the alert)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. instrumentName</ap:name> <ap:value>85</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.instrument Name	(qualified name of instrument)	See Note below table.
(info) com.amberpoint.notification.objectType	Service, Endpoint, Transaction	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. objectType</ap:name> <ap:value>Service</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.objectId	(UUID of the object that SLA policy is applied on)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. objectId</ap:name> <ap:value>uuid:DA936829-98FF-11DF-828B- A3EAF532919E</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.policyId	(UUID of the SLA policy)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. policyId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753- 57E6CFA43E9B</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.senderId	(UUID of the AP_Enforcer_Service)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. senderId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753- 57E6CFA43E9B</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.senderUrl	(Location of AP_Enforcer_Service)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. senderUrl</ap:name> <ap:value>http://localhost:8080/ btmperformance/endorcer</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.transaction Id	UUID of transaction (only if the SLA is applied on a Transaction)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. transactionId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753 -57E6CFA43E9B</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) endpointId	(UUID of AP_Enforcer_Service system endpoint)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. endpointId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753- 57E6CFA43E9B</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) serviceID	(UUID of AP_Enforcer_Service)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification. serviceId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753- 57E6CFA43E9B</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>

Sample subscription for (info) com.amberpoint.notification.instrumentName is as follows:

<ap:notificationFilters> 
  <ap:info> 
     <ap:name>com.amberpoint.notification.instrumentName</ap:name>
     <ap:value>http://schemas.amberpoint.com/instruments/transactions/
                                      types:startedTransactionCount</ap:value> 
     <ap:operation>in</ap:operation> 
  </ap:info> 
<ap:notificationFilters>

Metadata for Condition Alerts

The following table specifies metadata for condition alerts.

Metadata	Available values	Sample subscription
(header) source	ExM	<ap:notificationFilters> <ap:source> <ap:value>ExM</ap:value> <ap:operation>in</ap:operation> </ap:source> </ap:notificationFilters>
(header) event	Exception Detected	<ap:notificationFilters> <ap:event> <ap:value>Exception Detected</ap:value> <ap:operation>in</ap:operation> </ap:event> </ap:notificationFilters>
(header) severity	FAILURE, WARNING, INFO	<ap:notificationFilters> <ap:severity> <ap:value>WARNING</ap:value> <ap:operation>in</ap:operation> </ap:severity> </ap:notificationFilters>
(header) templateSet	Exm-Template	<ap:notificationFilters> <ap:templateSet> <ap:value>Exm-Template</ap:value> <ap:operation>in</ap:operation> </ap:templateSet> </ap:notificationFilters>
(info) com.amberpoint.notification.objectType	Transaction	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification.objectType</ap:name> <ap:value>Transaction</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.objectId	(UUID of Transaction)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification.objectId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B </ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.transactionId	(UUID of Transaction)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification.transactionId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B </ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) correlationName	(Friendly name of function)	<ap:notificationFilters> <ap:info> <ap:name>correlationName</ap:name> <ap:value>testTransaction1</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) detectionTime	(Human readable time stamp. E.g. Thu Jul 22 12:25:49 PDT 2010)	<ap:notificationFilters> <ap:info> <ap:name>detectionTime</ap:name> <ap:value>Thu Jul 22 12:25:49 PDT 2010</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) exceptionPriority	failure, warning, informational	<ap:notificationFilters> <ap:info> <ap:name>exceptionPriority</ap:name> <ap:value>warning</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) exceptionTemplate	(friendly name of condition)	<ap:notificationFilters> <ap:info> <ap:name>exceptionTemplate</ap:name> <ap:value>condition2</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) exceptionType	(name of transaction + name of condition Or name of service + name of condition)	<ap:notificationFilters> <ap:info> <ap:name>exceptionType</ap:name> <ap:value>testTransaction1+condition2</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) exceptionsURL	(URL that links back to the exception instance UI page)	<ap:notificationFilters> <ap:info> <ap:name>exceptionsURL</ap:name> <ap:value>http://localhost:8080/btmui</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) instanceID	(UUID of exception instance)	<ap:notificationFilters> <ap:info> <ap:name>instanceId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B </ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>

Metadata for System Alerts

The following table specifies metadata for system alerts.

Metadata	Possible values	Sample subscription
(header) source	System	<ap:notificationFilters> <ap:source> <ap:value>System</ap:value> <ap:operation>in</ap:operation> </ap:source> </ap:notificationFilters>
(header) event	business_object_creation	<ap:notificationFilters> <ap:event> <ap:value>business_object_creation</ap:value> <ap:operation>in</ap:operation> </ap:event> </ap:notificationFilters>
(header) severity	INFO	<ap:notificationFilters> <ap:severity> <ap:value>INFO</ap:value> <ap:operation>in</ap:operation> </ap:severity> </ap:notificationFilters>
(header) templateSet	System-Template	<ap:notificationFilters> <ap:templateSet> <ap:value>System-Template</ap:value> <ap:operation>in</ap:operation> </ap:templateSet> </ap:notificationFilters>
(info) com.amberpoint.notification.senderId	(UUID of service that sends out this alert.)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification.senderId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>
(info) com.amberpoint.notification.senderUrl	(Location of service that sends out this alert.)	<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification.senderUrl</ap:name> <ap:value>http://localhost:8080/btmperformance/endorcer </ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters>