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:

  1. Select System Services from the Navigator and select AP_Notifier_Service from the services listed in the summary area.

  2. Edit its setup data (from the Admin menu) to specify the mail host and the email sender to be used.

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

    The input command document is described in The Notifier Command Document.

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