Cisco IPICS サーバ アドミニストレーション ガイド リリース 4.0
Cisco IPICS を使用した外部通知
Cisco IPICS を使用した外部通知
発行日;2012/01/31 | 英語版ドキュメント(2010/05/03 版) | ドキュメントご利用ガイド | ダウンロード ; この章pdf , ドキュメント全体pdf (PDF - 3MB) | フィードバック

目次

Cisco IPICS を使用した外部通知

外部通知の実装要件

ダイヤル エンジン

受信者リスト

メッセージ ファイル

外部通知の呼び出し

HTTP 要求の送信による外部通知の呼び出し

CAP XML ファイルの送信による外部通知の呼び出し

外部通知の結果の取得

外部通知の結果の確認

外部通知用の XML ファイル パラメータ

Cisco IPICS を使用した外部通知

シスコ製ポリシー エンジンの通知アクション( 第 6 章「Cisco IPICS ポリシー エンジンの使い方」 を参照)では、指定した受信者に連絡し、指定した情報を提供できます。それらの受信者は、Cisco IPICS に設定する必要があります。

Cisco IPICS では、Cisco IPICS に設定されていない受信者に通知を送ることもできます。このような通知を 外部通知 といいます。外部通知では次のことを実行できます。

1. Cisco IPICS が指定されたファイルから取得した電話番号で同時に複数の外部ユーザを呼び出す。

2. コールに応答した各ユーザに対して、指定したメッセージを再生する。

3. 各コールの結果をログ ファイルに取り込み、内容を随時確認する。

外部通知を呼び出すには、HTTP 要求を送信するか、適切なサーバに Common Alerting Protocol(CAP).xml ファイルを送信します。

この付録では、外部通知を使用するための Cisco IPICS の設定方法と、外部通知を呼び出す方法について説明します。この付録は、次の項で構成されています。

「外部通知の実装要件」

「外部通知の呼び出し」

「外部通知の結果の取得」

「外部通知の結果の確認」

「外部通知用の XML ファイル パラメータ」

外部通知の実装要件

外部通知に Cisco IPICS を使用するためには、ダイヤル エンジンを設定して、受信者のリストを指定し、受信者に対して再生するメッセージ ファイルを指定する必要があります。

これらの要件について、以降の各項で詳しく説明します。

ダイヤル エンジン

ダイヤル エンジンは、外部通知の受信者に対するダイヤルアウトとメッセージ再生を処理する Cisco IPICS サーバです。ユーザはこのシステムに、外部通知を呼び出す要求を送信します。このサーバによって、コールの負荷を分散し、多数の受信者に対して効率的に通知を送信できます。ネットワーク内のどの Cisco IPICS サーバでも、ダイヤル エンジンとして指定できます。

Cisco IPICS サーバをダイヤル エンジンとして設定するには、そのサーバの .xml 設定ファイルを開き、ダイヤル エンジンについて dialEngine サブ要素のアトリビュートを設定します。これを行うには、次の手順を実行します。

手順


ステップ 1 ダイヤル エンジンにする Cisco IPICS サーバで、次のフォルダにある dedicated-dial-engines.xml ファイルを開きます。

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

ステップ 2 dedicated-dial-engines.xml ファイルで、「dialEngine」サブ要素をアンコメントし、ダイヤル エンジンについて次のアトリビュートを設定します。

id:ダイヤル サーバの固有識別情報を設定します(識別情報はサーバのホスト名でもかまいません)。

bulkNotifyApp:BulkNotifyDialer に設定します。

host:ダイヤル エンジンの IP アドレスまたはホスト名。

ステップ 3 dedicated-dial-engines.xml ファイルを保存します。

ステップ 4 ルート ユーザ ID から次のコマンドを入力して、Cisco IPICS サービスを再起動します。

service ipics restart


 

受信者リスト

受信者リストは、外部通知メッセージを受信する必要のある各ユーザのリストが含まれる .xml ファイルです。これらの受信者に連絡する外部通知を呼び出すためには、受信者リストが存在するサーバの URL がわかっている必要があります。

受信者リストは、この項に示す形式であり、次のガイドラインに従っている必要があります。

「id」は必須であり、各受信者に固有であることが必要です。

「name」はオプションです。

「contacts」は、呼び出す順序どおりに並べられた受信者のリストです。

「phone type」はオプションです。

「dn」は必須です。dn 値は、入力したとおりに音声ゲートウェイに送信されます。

次に、有効な受信者リストの例を示します。

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

メッセージ ファイル

メッセージ ファイルは、パルス符号変調(PCM)形式または CCITT u-Law 形式の .wav ファイルで、受信者に対して再生する録音メッセージが含まれています。メッセージの長さは 90 秒を超えないようにすることをお勧めします。

このメッセージを再生する外部通知を呼び出すためには、メッセージ ファイルが存在するサーバの URL がわかっている必要があります。

外部通知の呼び出し

通知アクションを呼び出すには、ダイヤル エンジンに HTTP get 要求を送信するか、HTTP によってダイヤル エンジンに有効な CAP .xml ファイルを送信します。

HTTP 要求の送信による外部通知の呼び出し

HTTP 要求によって外部通知を呼び出すには、ダイヤル エンジンに指定されたサーバに次の要求を送信します。

http://< Dial_Engine_Server >:8080/ipics_server/BulkNotify?
method=httpNotify?capId=<
CAP_ID_# >&userListURL=< User_List_URL >
&waveFileURL=<
Wave_File_URL >
&announcementText=<
Announcement_Text >
&questionWaveURL
<number> =< Question_Wave_URL >

表示の意味は次のとおりです。

<Dial_Engine_Server> は、ダイヤル エンジンを含む Cisco IPICS サーバの完全修飾ホスト名または IP アドレスです。

<CAP_ID_#> は、この呼び出し要求に割り当てる固有識別情報です。

<User_List_URL> は、受信者リストを取得できる HTTP URL です。

<Wave_File_URL> は、メッセージ ファイルを取得できる HTTP URL です。

(オプション) <Announcement_Text> は、Cisco Unified IP Phones に表示されるテキストです。

<number> は質問番号です。この値は 1 で始まって、1 ずつ増えていく必要があります。

(オプション) <Question_Wave_URL> は、質問ファイルを取得できる HTTP URL です。取得する質問ファイルの名前は、次の形式でなければなりません。

Question< number >_< dtmf_choices >.wav

表示の意味は次のとおりです。

< number > は質問番号です。この番号は、questionWaveURL アトリビュート内の番号と一致する必要があります。

< dtmf_choices > は、次の questionWaveURL パラメータ例のように、電話の受信者が入力できるキーパッドの桁数になります。

- パラメータ &questionWaveURL1=Question1_1234.wav が設定された HTTP 要求では、オーディオが再生され、電話の受信者はキーパッドの 1、2、3、または 4 を押すとそれに応答できます。

- パラメータ &questionWaveURL2=Question2_12.wav が設定された HTTP 要求では、オーディオが再生され、電話の受信者は 1 または 2 を押すとそれに応答できます。

- パラメータ &questionWaveURL3=Question3_1.wav が設定された HTTP 要求では、オーディオが再生され、電話の受信者は 1 を押した場合だけそれに応答できます。このタイプの要求は、ユーザがこの通知を受信したことを確認するために使用できます。


) スペースや特殊文字が含まれるパラメータでは、標準の HTTP エスケープ コードを使用する必要があります。


CAP XML ファイルの送信による外部通知の呼び出し

有効な CAP .xml ファイルを次の URL に送信することにより、外部通知を呼び出すことができます。

http://< Dial_Engine_Server >:8080/ipics_server/BulkNotify?
method=capNotify?&cap=<1010336075.8398
CAP_XML >

表示の意味は次のとおりです。

<Dial_Engine_Server> は、ダイヤル エンジンを含む Cisco IPICS サーバのホスト名または IP アドレスです。

<CAP_XML> は有効な CAP ファイルです。

この通知方式を使用する場合は、次のガイドラインに従う必要があります。

リソースの説明が IPICSUserList であるリソースが存在している必要があります。このリソースのユニフォーム リソース識別子(URI)は、受信者リストを取得できるサーバの HTTP URL を示している必要があります。このリソースの mimeType は text/xml でなければなりません。

リソースの説明が IPICSWaveFile であるリソースが存在している必要があります。このリソースの URI は、メッセージ ファイルを取得できるサーバの HTTP URL を示している必要があります。このリソースの mimeType は audio/wav でなければなりません。

(オプション)リソースの説明が AnnouncementText であるリソースが存在している可能性があります。このリソースの URI は、テキスト メッセージを取得できるサーバの HTTP URL を示している必要があります。このリソースの mimeType は text/plain でなければなりません。

(オプション)リソースの説明が QuestionWaveURL<number> であるリソースが存在している可能性があります。このリソースの URI は、質問ファイルを取得できるサーバの HTTP URL を示している必要があります。質問ファイルの指定方法の詳細については、HTTP 呼び出しの項を参照してください。このリソースの mimeType は audio/wav でなければなりません。

次に、有効な CAP リストの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<alert xmlns="urn:oasis:names:tc:emergency:cap:1.1">
<identifier>5</identifier>
<sender>mycontact@mycompany.com</sender>
<sent>2003-06-11T22:39:00-07:00</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>San Jose Earthquake Prevention</senderName>
<headline>SJ Earthquake</headline>
<description>Earthquake in SJ Downtown</description>
<contact>Earthquake Prevention - 408-555-1212</contact>
<resource>
<resourceDesc>IPICSUserList</resourceDesc>
<uri>http://ipics-server:8080/BulkCapSimulator/BulkCapSimulator?method=userList</uri>
</resource>
<resource>
<resourceDesc>IPICSWaveFile</resourceDesc>
<uri>http://ipics-server:8080/BulkCapSimulator/BulkCapSimulator?method=waveFile&amp;p=announcement</uri>
<mimeType>audio/wav</mimeType>
</resource>
<resource>
<resourceDesc>QuestionWaveURL1</resourceDesc>
<uri>http://ipics-server:8080/BulkCapSimulator/BulkCapSimulator?method=waveFile&amp;p=q1</uri>
<mimeType>audio/wav</mimeType>
</resource>
<resource>
<resourceDesc>AnnouncementText</resourceDesc>
<uri>http://ipics-server:8080/BulkCapSimulator/BulkCapSimulator?method=announcementText</uri>
<mimeType>text/plain</mimeType>
</resource>
<area>
<areaDesc>San Jose, Ca</areaDesc>
<geocode>
<valueName>SAME</valueName>
<value>006037</value>
</geocode>
</area>
</info>
</alert>
 

外部通知の結果の取得

外部通知を呼び出したら、その通知の結果を表示したファイルを取得できます。外部通知の結果を取得するには、ダイヤル エンジンの機能を含む Cisco IPICS サーバに次の要求を送信します。

http://<Dial_Engine_Server>:8080/ipics_server/BulkNotify?method=incidentStatus&capId= <CAP_ID_#>
&statusType=<SUMMARY | DETAILED>

表示の意味は次のとおりです。

<Dial_Engine_Server> は、ダイヤル エンジンを含む Cisco IPICS サーバのホスト名または IP アドレスです。

<CAP_ID_#> は、結果を要求する呼び出し要求の一意の ID 番号です。

SUMMARY または DETAILED は、受信するステータス情報のレベルです。

要約タイプ SUMMARY では、開始時間、完了時間、通知のステータスなどを含む、インシデントに関する基本的情報が提示されます。要約タイプ DETAILED では、正常に到達できたユーザと、それらのユーザが質問にどのように応答したかのリストが提示されます。

次に、DETAILED レベル ステータスの .xml ファイルによる出力例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<NotificationStatus>
<Incident capId="5">
<Status>SUCCESSFULLY_FINISHED</Status>
<StartTime>Mon Nov 19 15:25:07 PST 2007</StartTime>
<FinishTime>Mon Nov 19 15:25:17 PST 2007</FinishTime>
<UserSummary failedToNotify="0" successfullyNotified="1" totalUsers="1">
<User id="1028">
<Contacts>
<Phone dialNumber="1029" extn="" shared="false">
<Status>SUCCESSFUL</Status>
<Time>Tue Dec 04 16:35:55 PST 2007</Time>
<QuestionResponses>
<Response promptId="q1">
<Value>1</Value>
</Response>
</QuestionResponses>
</Phone>
</Contacts>
</User>
<User id="1028-3">
<Contacts>
<Phone dialNumber="1028" extn="" shared="true">
<Status>SUCCESSFUL</Status>
<Time>Tue Dec 04 16:35:50 PST 2007</Time>
<QuestionResponses>
<Response promptId="q1">
<Value>1</Value>
</Response>
</QuestionResponses>
</Phone>
</Contacts>
</User>
<User id="1028-1">
<Contacts>
<Phone dialNumber="1028" extn="" shared="true">
<Status>SUCCESSFUL</Status>
<Time>Tue Dec 04 16:35:50 PST 2007</Time>
<QuestionResponses>
<Response promptId="q1">
<Value>1</Value>
</Response>
</QuestionResponses>
</Phone>
</Contacts>
</User>
<!-- End detailed summary>
</UserSummary>
</Incident>
</NotificationStatus>
 

表 B-1 は、.xml ファイルに表示される要約レポートの各フィールドについて説明したものです。

 

表 B-1 .xml ファイルの要約レポートのフィールド

フィールド
説明

Incident

この要素には capId アトリビュートが含まれます。capId アトリビュートは、結果を要求する呼び出し要求の一意の ID 番号を表します。

Status

この要素は、呼び出し要求のステータスを表します。このフィールドの有効なエントリは、SUCCESSFULLY_FINISHED、PROCESSING、ABORTED_NO_CONFIGURED_DE、ABORTED_TIMEOUT_WAITING_ON_DE、ABORTED_FAILED_UPLOAD_PROMPT_TO_DE、ABORTED_PROMPT_DOWNLOADED_TRANSCODE_FAILURE、ABORTED_USER_LIST_PARSE_ERROR、および ABORTED_UNKNOWN になります。

StartTime

この要素は、呼び出し要求が開始された日時を表します。

FinishTime

この要素は、呼び出し要求が完了した日時を表します。

UserSummary

UserSummary 要素には次のアトリビュートが含まれます。

failedToNotify は、通知できなかった参加者の数を示します。

successfullyNotified は、正常に通知された参加者の数を示します。

totalUsers は、通知に含まれるユーザの総数を示します。

詳細レポートを指定した場合、XML ファイルには 表 B-2 で説明する追加フィールドが含まれます。

 

表 B-2 詳細レポートの .xml ファイルの要約レポートの追加フィールド

フィールド
説明

User id

この要素は、呼び出された電話番号の ID を表します。

複数のユーザが電話番号を共有している場合は、shared アトリビュートが true に設定され、そうでない場合は false に設定されます。

Phone

Phone 要素には次のアトリビュートが含まれます。

dialNumber フィールドは、呼び出された電話番号を表します。

extn フィールドは、呼び出された番号の内線を表します。番号に内線が含まれない場合、このフィールドは空白になります。

[shared] フィールドは、番号が複数のユーザによって共有されているかどうかを示します。[shared] フィールドが true に設定されている場合、番号は複数の受信者によって共有されています。そうでない場合、このフィールドは false に設定されます。

Status

この要素は、コールのステータスを表します。有効なフィールドは、SUCCESSFUL、NO_ANSWER、BUSY、INVALID、NO_RESOURCE、ANSWERED_NO_ACKNOWLEDGEMENT、および UNSUCCESSFUL です。

Time

エンド ユーザのデバイスが通知を受信した時間です。

QuestionResponses

QuestionResponses 要素には次のフィールドが含まれます。

[Response promptId] は、HTTP 呼び出し要求で設定した質問の ID です。この ID は、.wav ファイルの名前に含まれる番号に対応します。たとえば、.wav ファイルの名前が Question1_< dtmf_choices >.wav の場合、[Response promptId] は q1 になります。

[Value] は、ダイヤル パッド上でユーザが押した番号です。


) summaryType パラメータを指定しない場合、Cisco IPICS ではデフォルト値として SUMMARY が使用されます。


外部通知の結果の確認

Cisco IPICS は、外部通知の実行時に行ったコールの結果を取り込み、保存します。この情報は ipics.log ファイルに書き込まれます。このファイルは、Cisco IPICS サーバの次のフォルダに保存されています。

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

HTTP 要求による外部通知を中止するには、ダイヤル エンジンに指定されたサーバに次の要求を送信します。

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

表示の意味は次のとおりです。

<Dial_Engine> は、ダイヤル エンジンのホスト名または IP アドレスです。

<CAP_ID_#> は、この呼び出し要求に割り当てる固有識別情報です。

外部通知用の XML ファイル パラメータ

dedicated-dial-engines.xml ファイルには、 表 B-3 で説明する設定可能パラメータが含まれています。

シスコでは、ネットワーク設定のために必要にならない限り、これらの値を変更しないことをお勧めしています。たとえば、ネットワークの高遅延のためコールがタイムアウト値を超過してしまう場合は、タイムアウト値を大きくすることができます。

また、シスコではこの XML ファイル内の他の値も一切変更しないことをお勧めしています。これは具体的には、maxDialEngineWaitForDialing、maxDialEngineWaitForAck、maxDialEngineWaitForIPPhone、および maxDialEngineWaitForOnCall の各ファイルになります。

 

表 B-3 dedicated-dial-engines.xml ファイル内の新しい設定可能パラメータ

説明

connectTimeout

この値は、プライマリ ダイヤル エンジンが専用ダイヤル エンジンに接続する際の最大タイムアウト値(ミリ秒単位)を表します。プライマリ ダイヤル エンジンが指定した時間内に専用ダイヤル エンジンに接続しない場合、Cisco IPICS ではこのエラーが ipics.log ファイルにダイヤル エンジンの障害として報告され、通知要求は再度キューに配置されます。

ipics.log ファイルを表示するには、Cisco IPICS Administration Console で [Serviceability] > [System Logs] ウィンドウに移動し、に表示される情報を確認します。

dialEngineFailure
CapForDuration

この値は、Cisco IPICS で複数のダイヤル エンジン障害が 1 つのダイヤル エンジン障害としてカウントされる時間ウィンドウ(ミリ秒単位)を表します。デフォルト値の 500 を使用すると、Cisco IPICS では 0.5 秒の時間ウィンドウ内に発生するすべてのダイヤル エンジン障害が、1 つのダイヤル エンジン障害としてカウントされます。

initialEngineFaliure
ReattemptDuration

この値は、Cisco IPICS がダイヤル エンジン障害の後、プライマリ ダイヤル エンジンに接続するまでに待つ時間(ミリ秒単位)を表します(たとえば、通知を送信するために使用可能なダイヤル エンジン リソースがない場合など)。

(注) 以降は、1 回再試行するたびに値が倍になります。デフォルト値の 2000 を使用して、Cisco IPICS がプライマリ ダイヤル エンジン障害のために通知アクションを完了できなかった場合、Cisco IPICS は 2 秒間待ってからダイヤル エンジンに接続し、通知アクションを再試行します。Cisco IPICS で再度ダイヤル エンジン障害が検出されると、今度は 4 秒間の待機後、ダイヤル エンジンへの再接続が行われます。

ダイヤル エンジンへのコールが成功すると、この値は設定値にリセットされます。

maxDialEngine
FailureWaitTimeCap

この値は、Cisco IPICS がダイヤル エンジンへの接続を試みる最大累積時間(ミリ秒単位)を表します。この値は、initialEngineFaliureReattemptDuration の値が無制限に増加し、ダイヤル エンジンが使用不能になることを防止します。

指定した時間内にダイヤル エンジンに接続できない場合、Cisco IPICS は外部通知を停止し、ipics.log ファイルにエラーを報告します。

maxDialRetryCount

この値は、Cisco IPICS がユーザへの通知アクションの初回の送信が失敗したときに(たとえば電話がビジーの場合や応答がなかった場合など)、再送信を試行する最大回数を表します。

maxWaitForAcquiring
DialEngine

この値は、使用可能な専用ダイヤル エンジンがない場合に、プライマリ ダイヤル エンジンが外部通知を停止するまでに待つ最大時間(ミリ秒単位)を表します。

phoneDialReadTimeout

この値は、専用ダイヤル エンジンがプライマリ ダイヤル エンジンからのユーザのダイヤル要求に応答する際の、最大タイムアウト値(ミリ秒単位)を表します。専用ダイヤル エンジンが指定した時間内にプライマリ ダイヤル エンジンに応答しない場合は、通知アクションが停止され、ipics.log ファイルにエラーが報告されます。

promptUploadRead
Timeout

この値は、専用ダイヤル エンジンがプライマリ ダイヤル エンジンからのメディア(.wav ファイルなど)を完全にアップロードする際の、最大タイムアウト値(ミリ秒単位)を表します。専用ダイヤル エンジンが指定した時間内にメディアをアップロードしない場合は、通知アクションが停止され、ipics.log ファイルにエラーが報告されます。

redialPeriod

この値は、ユーザへの通知アクションの初回の送信が失敗したときに、Cisco IPICS が再送信までに待つ時間(ミリ秒単位)を表します。