Adapter Installation
This section describes how to install the Oracle Utilities Network Management System Generic IVR Adapter.
Ensure that the Generic IVR Adapter is installed.
• Verify that the following files are found in their respective folders
• $NMS_BASE/lib/libIVRAdapter.so
• $NMS_BASE/bin/IVRAdapter
• $NMS_BASE/bin/nms-ivr-gateway
• $NMS_SQL_FILES/nms_retain_ivr_interface.sql
• $NMS_SQL_FILES/nms_ivr_interface_head.sql
• $NMS_BASE/nms_ivr_interface_body.plb
• $NMS_BASE/bin/troubleCallCreate
• $NMS_BASE/bin/ivrCallPerPoll
• $NMS_BASE/bin/ivrPollPeriod
Setting Up the Generic IVR Adapter System Variables
Include the following variable in the system variables definition:
There are two options for configuring the IVR RDBMS:
• NMS RDBMS: If the IVR_RDBMS_HOST and RDBMS_HOST environment variables are the same, the Generic IVR Adapter will use the same RDBMS as the Oracle Utilities Network Management System environment for data.
• External RDBMS: If the IVR_RDBMS_HOST and RDBMS_HOST environment variables are different, the Generic IVR Adapter will use a separate RDBMS for data. The value of IVR_RDBMS_HOST must exist in the tnsnames.ora file and the Oracle Wallet.
Complete these steps to configure the IVR RDBMS:
1. If using an external RDBMS for IVR, edit tnsnames.ora to add an entry for the RDBMS connection the IVR Adapter you will use. The name of this entry must not match the RDBMS_HOST or RDBMS_ADMIN environment variables.
2. Run nms-env-config --adapter-config
3. If prompted if using the IVR adapter, choose "y".
Note: If IVR_RDBMS_HOST is already set, this prompt is skipped.
4. When prompted for IVR_RDBMS_HOST, either enter the entry name from step 1 if using an external RDBMS or $RDBMS_HOST if using the NMS RDBMS.
5. If using an external RDBMS, choose "y" when prompted to update wallet credentials for IVR and enter the wallet password, IVR RDBMS username, and IVR RDBMS password when prompted. Otherwise, choose "n".
6. When prompted to backup and replace .nmsrc, choose "y".
7. After nms-env-config is finished, log out and login as the administrative user again to ensure that IVR_RDBMS_HOST is set correctly in your environment.
Configure Adapter to run as NMS System Service
Configure the Generic IVR Adapter to run as an Oracle Utilities Network Management System service by updating the $NMS_HOME/etc/system.dat file to include the Generic IVR Adapter as a system service. There are three main sections where this service needs to be defined: the service, program, and instance sections. See the $NMS_BASE/templates/system.dat.template file for examples of how to configure the Generic IVR Adapter. Search for IVRAdapter in the file and copy those lines to $NMS_HOME/etc/system.dat file. Make sure all lines are uncommented so that they are active. You must restart the system services in order for the Generic IVR Adapter to be properly monitored by SMService. See the following section for details on command line options for the Generic IVR Adapter.
IVRAdapter Command Line Options
IVRAdapter startup options enable the Generic IVR Adapter data flows and configure trouble-call polling, callback processing, and completed-record cleanup. Enable the data flows required by the project and complete their database and system-service configuration before starting the adapter. The separate troubleCallCreate test utility has its own command reference; its switches are not IVRAdapter options.
Set startup options in the program or instance entries for the service in system.dat. Restart the affected service to apply changes. Startup options do not replace the database, rules, or interface configuration described elsewhere in this chapter.
The common Service startup options in the Configuration Guide also apply unless an adapter-specific option overrides them.
In the syntax below, angle brackets identify required values, square brackets identify optional values, and an ellipsis permits repetition. Enter values without the brackets and preserve the spelling and case shown.
The options are grouped below by data flow. A dependency identifies the flow or cleanup mode for which an option is meaningful; supplying a tuning option does not automatically enable that flow. The supported flow-enabling switches are -troublecall, -omscbreq, and -omscbresp. Defaults are compiled defaults unless a project configuration explicitly overrides them.
General Options
These options are independent of the selected data flows.
-help
Print IVR adapter usage and exit.
Depends on: No data-flow option. The process prints usage rather than starting adapter processing.
-debug [<level> | <facility> [level] ...]
Enable diagnostic output from IVRAdapter and its API toolkits. Supply a nonnegative integer level; higher levels increase diagnostic detail. The IVR troubleshooting convention uses levels 0, 1, and 2. This inherited Service option also accepts a registered facility and level; see the common Service reference for that syntax.
Depends on: No data-flow option; applies to the whole service.
Example: IVRAdapter -troublecall -debug 2
Trouble Call Data Flow
Use this group to enable and tune processing of incoming trouble calls. For the overall flow, see Trouble Calls in this chapter.
-troublecall
Enable trouble-call processing at startup.
Default: Disabled.
Integration requirement: Enable this flow for CC&B-NMS trouble-call integration. It reads new records from TROUBLE_CALLS and submits the call information to JMService for NMS processing.
-callperpoll <count>
Set the maximum number of trouble calls retrieved in one poll.
Default: 100.
Notes: The compiled default is 100; system.dat.template explicitly configures 200 calls per poll.
Depends on: -troublecall. The count is the maximum number of records processed from TROUBLE_CALLS during one poll; supply a positive integer.
-pollperiod <seconds>
Set the interval between trouble-call polls.
Default: 6 seconds.
Notes: The compiled default is 6 seconds; system.dat.template explicitly configures 9 seconds.
Depends on: -troublecall. Supply a positive integer number of seconds between successive queries of TROUBLE_CALLS. Changing this startup setting does not enable the trouble-call flow.
-docustquery
Obtain customer fields from the IVR customer lookup rather than taking every field directly from the TROUBLE_CALLS record before submitting the call to JMService. The current implementation queries IVR_CES_CUSTOMERS by customer ID for meter, telephone, address, city/state, account name, priority, account number, and area-code information.
Depends on: -troublecall.
Default: Disabled; use the data supplied on the trouble-call record.
Integration restriction: Do not enable this option for CC&B-NMS integration; that integration supplies the call data expected by its own flow.
Callback Requests Data Flow
Use this group to enable outgoing callback requests and choose which customer calls qualify. See Callback Requests in this chapter.
-omscbreq
Enable processing of OMS callback requests.
Default: Disabled. Enable this flow to retrieve NMS callback requests for delivery to the IVR system. Configure the callback agent and callback-selection policy below.
-cbreqinterval <seconds>
Set the polling interval for callback requests.
Default: 5 seconds.
Depends on: -omscbreq. Supply a positive integer number of seconds between checks for callback requests.
-cbAny
Select the callback policy in which a customer is eligible for a callback if a callback was requested during any matching call.
Depends on: -omscbreq.
Selection rule: This is an alternative to -cbLast. With neither option supplied, callback-all mode is used. If both switches are supplied, the last one on the command line wins.
-cbLast
Select the callback policy in which callback eligibility is determined by the customer's last matching call and whether that call requested a callback.
Depends on: -omscbreq.
Selection rule: This is an alternative to -cbAny. With neither option supplied, callback-all mode is used. If both switches are supplied, the last one on the command line wins.
Callback Responses Data Flow
Use this group to enable receipt and processing of IVR callback results. See Callback Responses in this chapter.
-omscbresp
Enable processing of OMS callback responses.
Default: Disabled. Enable this flow to read received IVR callback responses from TROUBLE_CALLBACKS and update NMS callback information.
-cbrespinterval <seconds>
Set the polling interval for callback responses.
Default: 5 seconds.
Depends on: -omscbresp. Supply a positive integer number of seconds between polls of TROUBLE_CALLBACKS for received callback responses.
Options Used by Multiple Data Flows
Callback identity and table maintenance are shared by the flows indicated in each entry.
-cbagent <name>
Select the NMS agent used to retrieve callback requests and save callback responses.
Depends on: -omscbreq or -omscbresp.
Default: IVR.
Agent configuration: The agent must exist in CES_USER, be configured as an external agent, and have access to the WCB product through ENV_ACCESS. Use the callback setup instructions to configure the applicable environment access. Where the account is intended only for integration, the documented access configuration can use a non-existing ENVIRONMENT value to prevent interactive Web Callbacks access with that username while retaining the required product access.
-cbpassword <password>
Set the agent password used by callback request and response processing.
Depends on: -omscbreq or -omscbresp. This value is used with the agent selected by -cbagent for callback processing; it does not select or enable a callback flow.
-cleantable
Enable periodic removal of completed records from the IVR interface tables. Use with the data flows enabled for the project (-troublecall, -omscbreq, or -omscbresp); cleanup is a shared maintenance function, not another flow-enabling switch.
Default: Disabled.
Cleanup criteria: Only eligible completed records older than -keepdbinfo are removed: TROUBLE_VERIFY requires PROCESS_STATUS = 'C'; TROUBLE_CALLS requires CALL_STATUS = 'C'; TROUBLE_CALLBACKS requires both PROCESS_STATUS = 'C' and CALLBACK_DONE = 'Y'. Cleanup does not run in a warm standby instance.
Related options: -cleaninterval selects the interval; -keepdbinfo selects the retention age. The cleantable high level message toggles cleanup while the adapter is running.
-cleaninterval <hours>
Set the integer number of hours between successive cleanup passes over the IVR tables.
Depends on: -cleantable, used with the project's enabled data flows (-troublecall, -omscbreq, or -omscbresp).
Default: 1 hour.
Notes: This controls when cleanup is attempted, not how old a completed record must be. Use -keepdbinfo for the retention age.
-keepdbinfo <days>
Set the integer retention age, in days, for completed IVR interface records eligible for cleanup.
Depends on: -cleantable, used with the project's enabled data flows (-troublecall, -omscbreq, or -omscbresp).
Default: 3 days.
Aging: Age is elapsed time, not a change of calendar date. A timestamp at 9:00 p.m. becomes one day old at 9:00 p.m. the next day, not at midnight. Cleanup compares the current database time with CALL_TIME in TROUBLE_CALLS or INCIDENT_TIME in the other cleanup tables and removes records whose age exceeds the configured value and whose completion flags qualify. Deletion occurs on a cleanup pass after that threshold is met.
troubleCallCreate Tool Command Line Options
Random trouble calls could be created and passed to the Generic IVR Adapter using the troubleCallCreate tool. The troubleCallCreate tool inserts entries to the TROUBLE_CALLS table. From here, the Generic IVR Adapter (through the Trouble Calls Data Flow) could fetch the new records from this table and pass this information to Oracle Utilities Network Management System, so Oracle Utilities Network Management System could apply the outage analysis algorithm to predict the outage device.
The following are the command line options for the troubleCallCreate tool:
Option | Usage | Description | Default Value |
|---|
help | troubleCallCreate –help | Displays the available command line options | |
debug | troubleCallCreate -debug | Runs this tool in debug mode, defaulting the debug level to 2. | Defaults to debug level 2 |
totalcalls | troubleCallCreate –totalcalls NUMBEROFCALLS (where NUMBEROFCALLS is an integer) | Specifies the number of trouble calls to be created | |
troublecall | troubleCallCreate –troublecall | Creates one trouble call | |
Testing Trouble Calls Data Flow with the troubleCallCreate Tool
As the troubleCallCreate tool randomly creates trouble calls, this tool could be used to test the Trouble Calls Data Flow. For more information about this Data Flow, see
Trouble Calls.
The troubleCallCreate tool uses the CES_CUSTOMERS table to retrieve some customer information that would be used as entries in the TROUBLE_CALLS table. The tool always begins querying the CES_CUSTOMERS table starting from the first row, each time it is invoked.
When multiple trouble calls would be created (using the 'totalcalls' command line option), the troubleCallCreate tool would place a different permutation of trouble code bits for each trouble call in the TROUBLE_CALLS table.
After running the troubleCallCreate tool, the results could be verified using the following database tables: '
• The TR OUBLE_CALLS table is populated with a new trouble call record (or with a certain number of trouble calls, assuming that the 'totalcalls' command line option was used).
• As the Generic IVR Adapter runs (using the Trouble Calls Data Flow), the INCIDENTS table is populated with new records.
Note: The number of new records in the INCIDENTS table is less than or equal to the total number of new trouble calls in the TROUBLE_CALLS table, as Oracle Utilities Network Management System outage analysis algorithms allow grouping of calls based on various criteria.
Testing Callback Requests Data Flow with the troubleCallCreate tool
The Callback Requests Data Flow could be tested as well using the troubleCallCreate tool, since all trouble calls generated by such tool requires callback. For more information about this Data Flow, see
Data Flow Details.
• For a generated trouble call, if part of the trouble code is described to be 'Power On', no record in the TROUBLE_CALLBACKS table will be generated even if the event is restored.
Loading the Generic IVR Adapter Database Tables and Stored Procedures
• The nms‑ivr‑gateway script is responsible for loading various SQL files responsible for creating the Generic IVR Adapter tables and stored procedures. The nms‑ivr‑gateway script could call some or all of the following scripts depending on how it was invoked:
• nms_retain_ivr_interface.sql: responsible for dropping and recreating the Generic IVR Adapter tables.
• nms_ivr_interface_head.sql: responsible for loading the Generic IVR Adapter stored procedure head.
• nms_ivr_interface_body.plb: responsible for loading the Generic IVR Adapter stored procedure body.
• To create the Generic IVR Adapter tables and stored procedure, run the following command:
nms‑ivr‑gateway ‑offline
Note: The command above recreates the Generic IVR Adapter tables by dropping and creating them, therefore wiping out the contents of the Generic IVR Adapter tables.
• To create the Generic IVR Adapter stored procedure without dropping and recreating the Generic IVR Adapter tables, run the following command:
nms‑ivr‑gateway
• If the Generic IVR Adapter is configured to use an external RDBMS, run the following command to the Generic IVR Adapter tables in the external RDBMS:
RDBMS_HOST=$IVR_RDBMS_HOST ISQL nms_retain_ivr_interface.sql
Note: The command above recreates the Generic IVR Adapter tables by dropping and creating them, therefore wiping out the contents of the Generic IVR Adapter tables.