Using Cisco IPICS for External Notifications [Cisco IPICS Server Software]

Table Of Contents

Using Cisco IPICS for External Notifications

Requirements for Implementing External Notifications

Dedicated Dial Engine

Recipient List

Message File

Invoking External Notifications

Invoking an External Notification by Sending an HTTP Request

Invoking an External Notification by Posting a CAP XML File

Reviewing External Notification Results

Using Cisco IPICS for External Notifications

The Cisco policy engine notification action, which is described in Chapter 7, "Using the Cisco IPICS Policy Engine," contacts designated recipients and provides them with information that you specify. Those recipients must be configured in Cisco IPICS.

You can also use Cisco IPICS to send notifications to recipients who are not configured in Cisco IPICS. This type of notification is called an external notification and does the following:

1. Simultaneously calls many external users at telephone numbers that Cisco IPICS obtains from a file that you specify.

2. Plays a designated message to each user who answers the call.

3. Captures results of each call in a log file that you can review at any time.

You invoke an external notification by sending an HTTP request or by posting a Common Alerting Protocol (CAP) .xml file to the appropriate server.

This appendix describes how to set up Cisco IPICS for external notifications and how to invoke external notifications. It includes these sections:

•Requirements for Implementing External Notifications

•Invoking External Notifications

•Reviewing External Notification Results

Requirements for Implementing External Notifications

To use Cisco IPICS for external notifications, you must configure one or more dedicated dial engines, designate a list of recipients, and designate a message file to play to the recipients.

The following sections describe these requirements in detail.

Dedicated Dial Engine

A dedicated dial engine is a Cisco IPICS server that handles dialing out and playing messages to external notification recipients. These servers enable distribution of the call load so that notifications to a large number of recipients can be made efficiently.

To use this notification functionality, you must designate one or more dedicated dial engines. Any Cisco IPICS server in a network can be a dedicated dial engine.

One dedicated dial engine must be designated as the primary dial engine. The primary dial engine is the system to which you send the request to invoke an external notification.

To configure a Cisco IPICS server as a primary dial engine, you edit a .xml configuration file on that server and set the dialEngine sub-element attributes for each dedicated dial engine, including the primary dial engine. To do so, perform the following procedure:

Procedure

Step 1 On the Cisco IPICS server that you want to be the primary dial engine, edit the dedicated-dial-engines.xml file, which is stored in this folder:

/opt/cisco/ipics/tomcat/current/webapps/ipics_server/WEB-INF/classes

Step 2 In the dedicated-dial-engines.xml file, uncomment the "dialEngine" sub-element, and set the following attributes for one of the dedicated dial engines:

•id—Set a unique identifier for a dedicated dial server (the identifier can be the host name of the server)

•bulkNotifyApp—Set to BulkNotifyDialer

•host—IP address or host name of a dedicated dial engine

Step 3 For each additional dedicated dial engine that you want to deploy, copy the "dialEngine" sub-element, paste it below the sub-element that you just configured and repeat Step 2.

Step 4 Save the dedicated-dial-engines.xml file

Step 5 Restart the Cisco IPICS service by entering the following command from the root user ID:

service ipics restart.

Recipient List

A recipient list is a .xml file that contains a list of each person who should receive the external notification message. To invoke an external notification that contacts these recipients, you must know the URL of the server on which the recipient list resides.

A recipient list should be in the format that is shown in this section and should follow these guidelines:

•"id" is required and must be unique for each recipient.

•"name" is optional.

•"contacts" is a list of recipients in the order that they should be called.

•"phone type" is optional.

•"dn" is required. The dn value is sent to the voice gateway exactly as entered.

The following is an example of a valid recipient list:
<users>
  <user id="5" name="Kim Smith">
    <contacts>
      <phone type="mobile" dn="14085554444" />
      <phone type="home" dn="14085555555" /> 
    </contacts>
  </user>
  <user id="7" name="Bob Jo"> 
    <contacts> 
      <phone type="work" dn="1342433534" /> 
      <phone type="home" dn="14085543255" /> 
    </contacts>
  </user>
</users>
Message File

A message file is a .wav file in pulse code modulation (PCM) or CCITT u-Law format that contains the recorded message to play to recipients. Cisco recommends that the message be no longer than 90 seconds.

To invoke an external notification that plays this message, you must know the URL of the server on which the message file resides.

Invoking External Notifications

You can invoke a notification action by sending an HTTP get request to the primary dial engine or by posting a valid CAP .xml file over HTTP to the primary dial engine.

Invoking an External Notification by Sending an HTTP Request

To invoke an external notification with an HTTP request, send the following request to the server that is designated as the primary dial engine:

http://<Primary_Dial_Engine>:8080/ipics_server/BulkNotify?method=httpNotify&capId=<CAP_ID_#>&userListURL=<User_List_URL>&waveFileURL=<Wave_File_URL>

where:

•Primary_Dial_Engine is the host name or IP address of the primary dial engine.

•CAP_ID_# is a unique identifier that you assign to this invocation request.

•User_List_URL is the HTTP URL from which the recipient list can be retrieved.

•Wave_File_URL is the HTTP URL from which the message file can be retrieved.

Note Parameter that include spaces or special characters must use standard HTTP escape codes.

Invoking an External Notification by Posting a CAP XML File

You can invoke an external notification by posting a valid CAP .xml file to this URL:

http://<Primary_Dial_Engine>:8080/ipics_server/BulkNotify?method=
capNotify

where Primary_Dial_Engine is the host name or IP address of the primary dial engine.

To use this notification method, the following guidelines must be followed:

•A resource with the resource description IPICSUserList must exist. The Uniform Resource Identifier (URI) for this resource must specify the HTTP URL of the server from which the recipient list can be retrieved. The mimeType for this resource must be text/xml.

•A resource with the resource description waveFileURL must exist. The URI for this resource must specify the HTTP URL of the server from which the message file can be retrieved. The mimeType for this resource must be audio/wav.

The following is an example of a valid CAP file:
 <?xml version = "1.0" encoding = "UTF-8"?>
<alert xmlns = "urn:oasis:names:tc:emergency:cap:1.1">
<identifier>KAR0-0306112239-SW</identifier>
<sender>sender_email_address</sender>
<sent>sent_date</sent>
<status>Actual</status>
<msgType>Alert</msgType>
<source>SW</source>
<scope>Public</scope>
<info>
        <category>Rescue</category>
        <event>Earthquake</event>
        <urgency>Immediate</urgency>
        <severity>Severe</severity>
        <certainty>Likely</certainty>
        <eventCode>
                <valueName>SAME</valueName>
                <value>CAE</value>
        </eventCode>
        <senderName>Earthquake Prevention</senderName>
        <headline>Earthquake</headline>
        <description>Earthquake in Downtown</description>
         <contact>Earthquake Prevention - 408-555-1111</contact>
         <resource>
                <resourceDesc>IPICSUserList</name> 
                <uri>http://bcg.com/getResource?resource=userList?capI
d=5</uri>
                <mimeType>text/xml</mimeType>
         </resource>
         <resource>
                <resourceDesc>waveFileURL</resourceDesc> 
                
<uri>http://bcg.com/getResource?resource=waveFile?capId=5</uri>
                <mimeType>audio/wav</mimeType>
         </resource>
         <area>
                 <areaDesc>Anytown</areaDesc>
                 <geocode>
                 <valueName>SAME</valueName>
                 <value>006037</value>
                 </geocode>
         </area>
 </info>
</alert>
Reviewing External Notification Results

Cisco IPICS captures and stores the results of calls that it makes when an external notification executes. This information is stored in the ipics.log file, which is stored on the Cisco IPICS server in this folder:

/opt/cisco/ipics/tomcat/current/logs

To stop/terminate an external notification with an HTTP request, send the following request to the server that is designated as the primary dial engine:

http://<Primary_Dial_Engine>:8080/ipics_server/BulkNotify?method=stopNotification&capId=<CAP_ID_#>&

where

•Primary_Dial_Engine is the host name or IP address of the primary dial engine.

•CAP_ID_# is a unique identifier that you assign to this invocation request.


	Using Cisco IPICS for External Notifications
	Download this chapter Using Cisco IPICS for External Notifications Feedback Table Of Contents Using Cisco IPICS for External Notifications Requirements for Implementing External Notifications Dedicated Dial Engine Recipient List Message File Invoking External Notifications Invoking an External Notification by Sending an HTTP Request Invoking an External Notification by Posting a CAP XML File Reviewing External Notification Results Using Cisco IPICS for External Notifications The Cisco policy engine notification action, which is described in Chapter 7, "Using the Cisco IPICS Policy Engine," contacts designated recipients and provides them with information that you specify. Those recipients must be configured in Cisco IPICS. You can also use Cisco IPICS to send notifications to recipients who are not configured in Cisco IPICS. This type of notification is called an external notification and does the following: 1. Simultaneously calls many external users at telephone numbers that Cisco IPICS obtains from a file that you specify. 2. Plays a designated message to each user who answers the call. 3. Captures results of each call in a log file that you can review at any time. You invoke an external notification by sending an HTTP request or by posting a Common Alerting Protocol (CAP) .xml file to the appropriate server. This appendix describes how to set up Cisco IPICS for external notifications and how to invoke external notifications. It includes these sections: •Requirements for Implementing External Notifications •Invoking External Notifications •Reviewing External Notification Results Requirements for Implementing External Notifications To use Cisco IPICS for external notifications, you must configure one or more dedicated dial engines, designate a list of recipients, and designate a message file to play to the recipients. The following sections describe these requirements in detail. Dedicated Dial Engine A dedicated dial engine is a Cisco IPICS server that handles dialing out and playing messages to external notification recipients. These servers enable distribution of the call load so that notifications to a large number of recipients can be made efficiently. To use this notification functionality, you must designate one or more dedicated dial engines. Any Cisco IPICS server in a network can be a dedicated dial engine. One dedicated dial engine must be designated as the primary dial engine. The primary dial engine is the system to which you send the request to invoke an external notification. To configure a Cisco IPICS server as a primary dial engine, you edit a .xml configuration file on that server and set the dialEngine sub-element attributes for each dedicated dial engine, including the primary dial engine. To do so, perform the following procedure: Procedure Step 1 On the Cisco IPICS server that you want to be the primary dial engine, edit the dedicated-dial-engines.xml file, which is stored in this folder: /opt/cisco/ipics/tomcat/current/webapps/ipics_server/WEB-INF/classes Step 2 In the dedicated-dial-engines.xml file, uncomment the "dialEngine" sub-element, and set the following attributes for one of the dedicated dial engines: •id—Set a unique identifier for a dedicated dial server (the identifier can be the host name of the server) •bulkNotifyApp—Set to BulkNotifyDialer •host—IP address or host name of a dedicated dial engine Step 3 For each additional dedicated dial engine that you want to deploy, copy the "dialEngine" sub-element, paste it below the sub-element that you just configured and repeat Step 2. Step 4 Save the dedicated-dial-engines.xml file Step 5 Restart the Cisco IPICS service by entering the following command from the root user ID: service ipics restart. Recipient List A recipient list is a .xml file that contains a list of each person who should receive the external notification message. To invoke an external notification that contacts these recipients, you must know the URL of the server on which the recipient list resides. A recipient list should be in the format that is shown in this section and should follow these guidelines: •"id" is required and must be unique for each recipient. •"name" is optional. •"contacts" is a list of recipients in the order that they should be called. •"phone type" is optional. •"dn" is required. The dn value is sent to the voice gateway exactly as entered. The following is an example of a valid recipient list: <users> <user id="5" name="Kim Smith"> <contacts> <phone type="mobile" dn="14085554444" /> <phone type="home" dn="14085555555" /> </contacts> </user> <user id="7" name="Bob Jo"> <contacts> <phone type="work" dn="1342433534" /> <phone type="home" dn="14085543255" /> </contacts> </user> </users> Message File A message file is a .wav file in pulse code modulation (PCM) or CCITT u-Law format that contains the recorded message to play to recipients. Cisco recommends that the message be no longer than 90 seconds. To invoke an external notification that plays this message, you must know the URL of the server on which the message file resides. Invoking External Notifications You can invoke a notification action by sending an HTTP get request to the primary dial engine or by posting a valid CAP .xml file over HTTP to the primary dial engine. Invoking an External Notification by Sending an HTTP Request To invoke an external notification with an HTTP request, send the following request to the server that is designated as the primary dial engine: http://<Primary_Dial_Engine>:8080/ipics_server/BulkNotify?method=httpNotify&capId=<CAP_ID_#>&userListURL=<User_List_URL>&waveFileURL=<Wave_File_URL> where: •Primary_Dial_Engine is the host name or IP address of the primary dial engine. •CAP_ID_# is a unique identifier that you assign to this invocation request. •User_List_URL is the HTTP URL from which the recipient list can be retrieved. •Wave_File_URL is the HTTP URL from which the message file can be retrieved. Note Parameter that include spaces or special characters must use standard HTTP escape codes. Invoking an External Notification by Posting a CAP XML File You can invoke an external notification by posting a valid CAP .xml file to this URL: http://<Primary_Dial_Engine>:8080/ipics_server/BulkNotify?method= capNotify where Primary_Dial_Engine is the host name or IP address of the primary dial engine. To use this notification method, the following guidelines must be followed: •A resource with the resource description IPICSUserList must exist. The Uniform Resource Identifier (URI) for this resource must specify the HTTP URL of the server from which the recipient list can be retrieved. The mimeType for this resource must be text/xml. •A resource with the resource description waveFileURL must exist. The URI for this resource must specify the HTTP URL of the server from which the message file can be retrieved. The mimeType for this resource must be audio/wav. The following is an example of a valid CAP file: <?xml version = "1.0" encoding = "UTF-8"?> <alert xmlns = "urn:oasis:names:tc:emergency:cap:1.1"> <identifier>KAR0-0306112239-SW</identifier> <sender>sender_email_address</sender> <sent>sent_date</sent> <status>Actual</status> <msgType>Alert</msgType> <source>SW</source> <scope>Public</scope> <info> <category>Rescue</category> <event>Earthquake</event> <urgency>Immediate</urgency> <severity>Severe</severity> <certainty>Likely</certainty> <eventCode> <valueName>SAME</valueName> <value>CAE</value> </eventCode> <senderName>Earthquake Prevention</senderName> <headline>Earthquake</headline> <description>Earthquake in Downtown</description> <contact>Earthquake Prevention - 408-555-1111</contact> <resource> <resourceDesc>IPICSUserList</name> <uri>http://bcg.com/getResource?resource=userList?capI d=5</uri> <mimeType>text/xml</mimeType> </resource> <resource> <resourceDesc>waveFileURL</resourceDesc> <uri>http://bcg.com/getResource?resource=waveFile?capId=5</uri> <mimeType>audio/wav</mimeType> </resource> <area> <areaDesc>Anytown</areaDesc> <geocode> <valueName>SAME</valueName> <value>006037</value> </geocode> </area> </info> </alert> Reviewing External Notification Results Cisco IPICS captures and stores the results of calls that it makes when an external notification executes. This information is stored in the ipics.log file, which is stored on the Cisco IPICS server in this folder: /opt/cisco/ipics/tomcat/current/logs To stop/terminate an external notification with an HTTP request, send the following request to the server that is designated as the primary dial engine: http://<Primary_Dial_Engine>:8080/ipics_server/BulkNotify?method=stopNotification&capId=<CAP_ID_#>& where •Primary_Dial_Engine is the host name or IP address of the primary dial engine. •CAP_ID_# is a unique identifier that you assign to this invocation request.
	Terms & Conditions \| Privacy Statement \| Cookie Policy \| Trademarks