Oracle Utilities Network Management System

Adapters Guide

Release 1.11.0.4

E36989-01

March 2013

Oracle Utilities Network Management System Adapters Guide, Release 1.11.0.4

E36989-01

Copyright © 1991, 2013 Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS

Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

This software or software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Preface

Please read through this guide thoroughly before beginning an installation or configuration of any supported adapters for the Oracle Utilities Network Management System.

Audience

This document is intended for the administrator and the engineers responsible for installing and configuring Oracle Utilities Network Management System adapters.

Related Documents

•

Oracle Utilities Network Management System Installation Guide

•

Oracle Utilities Network Management System Configuration Guide

•

Oracle Utilities Network Management System User’s Guide

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Common Terminology

The following terms and acronyms are used in one or more adapter descriptions.

CIS

Customer Information System

DTD

Document type definition, used to define XML documents

Generic IVR Adapter

A Unix application that generally executes on the OMS server machine. It supports the Trouble Call, Event Status, Affected Customers, Callback Request and Callback Response Data Flows.

HA

High availability, where Oracle Utilities Network Management System is configured with a pair of redundant servers. This is usually in the form of a hardware cluster and a shared drive that contains the database.

Isis

Clients access services and tools through a central concurrency management and messaging system called Isis. Isis is a real-time implementation of message oriented middleware and comprises the backbone of the system, providing access to the server for each client and the communication required between tools and services. Isis delivers the organized information to the client applications.

IVR

Interactive Voice Response system

JMService

Job Management Service. The Oracle Utilities Network Management System call processing and outage prediction engine.

MQSeries

A queue-based messaging system developed by IBM. This system has been renamed to WebSphere MQ.

NMS

Oracle Utilities Network Management System

ODService

Object Directory Service. ODService improves performance of the Oracle Utilities Network Management System by caching large amounts of device information that is likely to be requested by applications. This caching allows the requests to be handled very quickly without directly accessing the database.

OMS

Outage Management System

SCADA

Supervisory Control and Data Acquisition system

SMService

System Monitor Service. SMService monitors the core processes in the system, essentially the services and interfaces.

XML

Extensible Markup Language

XML Schema

An XML standard for defining XML documents

XSL

XML Style Sheet, used to reformat XML documents

Generic IVR Adapter

This chapter includes the following topics:

•

Introduction

•

Supported Application Data Flows

•

Interaction Diagram

•

Data Flow Details

•

Adapter Installation

•

Software Configuration

•

SRS Rules Configuration

•

Database Schema

•

Terminology

Introduction

The purpose of this document is to provide an administration guide for the Oracle Utilities Network Management System Generic IVR Adapter. This document will discuss the required process for installing and configuring the Oracle Utilities Network Management System Generic IVR Adapter to run with various applications. This adapter has the following attributes:

•

It is one of the adapters and tools that Oracle offers for integration with other product suites. It is a Unix application that generally executes on the Oracle Utilities Network Management System services server and is monitored through SMService.

•

It has the ability to accept trouble calls from an external application and provide that external application with updates about existing outages.

•

It can submit callback requests to an external application and receive callback responses from the external application.

•

It can communicate with several external applications, such as Interactive Voice Response (IVR) systems, Customer Information System (CIS) and Callback applications.

Supported Application Data Flows

IVR Data Flows with Oracle Utilities Network Management System

The following are the Data Flows between an IVR system and Oracle Utilities Network Management System using the Generic IVR Adapter

•

Creation of trouble calls from the IVR system to Oracle Utilities Network Management System

•

Callback request information from Oracle Utilities Network Management System to the IVR system

•

Callback response information from the IVR system to Oracle Utilities Network Management System

CIS Data Flows with Oracle Utilities Network Management System

The following are the Data Flows between a CIS and Oracle Utilities Network Management System using the Generic IVR Adapter

•

Creation of trouble calls from the CIS application to Oracle Utilities Network Management System

Callbacks Application Data Flows with Oracle Utilities Network Management System

The following are the Data Flows between a Callback application and Oracle Utilities Network Management System using the Generic IVR Adapter

•

Callback request information from Oracle Utilities Network Management System to the Callback application

•

Callback response information from Callback application to Oracle Utilities Network Management System

Interaction Diagram

Below is a diagram of the interaction between Oracle Utilities Network Management System and various external applications via the Generic IVR Adapter.

Note: In this document, it is assumed that the Generic IVR Adapter's tables and stored procedures would reside in the database used by Oracle Utilities Network Management System.

Data Flow Details

Overview

This section discusses in detail the data flows that are relevant to the Generic IVR Adapter. The data flows generally involve bilateral database tables that are populated or polled by the adapter or stored procedures that access internal NMS tables directly. The adapter data flows are turned on through command line switches, but the actual data transfer may be affected through the use of stored procedures.

Trouble Calls

New trouble calls need to be sent to Oracle Utilities Network Management System to apply the outage analysis algorithm to predict the outage device. The Generic IVR Adapter provides the submit_call stored procedure to pass trouble call information from the external application to Oracle Utilities Network Management System.

There are two PL/SQL packages available for interacting with the Generic IVR Adapter. Package pk_ivr_interface allows a full range of functionality provided by the adapter to be used. Package pk_ccb, which supports integration of NMS to Customer Information System (CIS), provides procedure for submitting trouble calls through Generic IVR Adapter.

Data Flow Characteristics

The following are characteristics of the Trouble Calls Data Flow

Characteristics

Value

Table

TROUBLE_CALLS. For schema information, see TROUBLE_CALLS Table Schema .

Stored Procedures

pk_ivr_interface.pr_trouble_calls and pk_ccb.submit_call

For stored procedure parameter information, see pk_ccb.submit_call and pr_trouble_calls .

Direction

external application to Oracle Utilities Network Management System

Generic IVR Adapter Data Retrieval Frequency to Oracle Utilities Network Management System

Periodic (configurable)

Data Flow Steps

1.

The external application invokes the submit_call stored procedure to submit a trouble call.

2.

The submit_call stored procedure inserts the trouble call in the TROUBLE_CALLS table. Upon insertion, the TROUBLE_CALLS.CALL_STATUS field will be set to 'N' signifying a new trouble call.

3.

The Generic IVR Adapter polls a configurable number of new records from the TROUBLE_CALLS table within a configurable poll period. The TROUBLE_CALLS.CALL_STATUS field is updated to 'I' (in progress) signifying that the trouble call is in the process of being submitted to the NMS Job Management Service (JMService).

4.

Once processed, the retrieved records are submitted to NMS' JMService so the outage analysis algorithms could be used for the submitted trouble calls. The TROUBLE_CALLS.CALL_STATUS field is updated to 'C' (complete) signifying the trouble call has been successfully submitted from the external application to NMS.

Below is a summary of the information required to submit a trouble call via the pk_ccb.submit_call stored procedure.

If no numeric trouble code is provided, the default trouble code, which is generally a 1 followed by however many zeros are necessary to satisfy the project defined trouble code, will be used. The length of the trouble code is defined by the number of distinct " group_order" entries in the srs_trouble_codes table.

Note that the pr_trouble_calls stored procedure is also provided to accomplish essentially the same goal - inserting a trouble call record into the trouble_calls table.

The pk_ccb.submit_call stored procedure is used to submit:

•

Trouble calls for a particular customer (known premise/service point). This includes entering the meeting time for job site appointments when there needs to be a planned outage to perform non-utility work at a location, such as tree removal near a power line or house painting.

•

Fuzzy calls

When a fuzzy call is created at least one of the following call identifiers must be provided:

•

The caller's name

•

The caller's phone number

•

The caller's ID (i.e., 911 reference ID provided by the caller (911)).

•

Location must also be provided. A Location can be:

•

a street intersection (provide two street names) or

•

a street segment (provide a block number and a street name)

•

City and State are optional

Callback Requests

A customer may request that he/she be called back as soon as the outage that he/she reported has been restored. The Generic IVR Adapter provides the stored procedure pr_trouble_callback_requests to be used by an external application that is managing the callback process. This procedure returns a list of calls where the customer has requested a callback.

Data Flow Characteristics

The following are characteristics for the Callback Request Data Flow:

Characteristics

Value

Table

TROUBLE_CALLBACKS. For schema information, see TROUBLE_CALLBACKS Table Schema .

Stored Procedure

pr_trouble_callback_requests. For stored procedure parameter information, see pr_trouble_callback_requests

Direction

Oracle Utilities Network Management System to external application

Generic IVR Adapter Data Retrieval Frequency from Oracle Utilities Network Management System

Periodic (configurable)

Data Flow Steps

1.

When an outage with a corresponding callback request is restored, Oracle Utilities Network Management System builds a callback list.

2.

From the list, callback requests could be assigned to callback agents or to the external application, either in a manual (using Oracle Utilities Network Management System Web Callbacks) or an automated manner (via SRS rules).

3.

The Generic IVR Adapter retrieves all callback requests assigned to the external application and inserts the callback requests to the TROUBLE_CALLBACKS table. The PROCESS_STATUS field of the callback request in the table would be set to 'N' signifying that the callback request is new. The CALLBACK_DONE field of the callback request in the table would be set to 'N' signifying that the callback has not yet been done.

4.

The Generic IVR Adapter provides the pr_trouble_callback_requests stored procedure, which picks new callback requests from the TROUBLE_CALLBACKS table.

5.

The external application could use the pr_trouble_callback_requests stored procedure to pick new callback requests. Callback requests that were picked are marked with a PROCESS_STATUS field equal to ‘I’ (callback response in progress) on the TROUBLE_CALLBACKS table.

Callback Request Notes

Once an outage event or a non-outage event is restored, callbacks are generated if the call is marked for a callback. All events have a restoration, either explicit or implicit, so any event can generate a callback. Also, in the event that the customer called multiple times, the customer will receive multiple callbacks if he requested a callback on each call. JMService gathers every call associated with an event, without filtering duplicate callers. Every call that is marked for callback will receive a callback.

Callback Responses

The external application calls the customer to confirm if power has been restored or not. The result of this call is passed from the external application to Oracle Utilities Network Management System via the pr_trouble_callback_responses stored procedure.

Data Flow Characteristics

The following are characteristics of the Callback Responses Data Flow:

Characteristics

Value

Table

TROUBLE_CALLBACKS. For schema information, see TROUBLE_CALLBACKS Table Schema .

Stored Procedure

pr_trouble_callback_responses. For stored procedure parameter information, see pr_trouble_callback_requests .

Direction

external application to Oracle Utilities Network Management System

Generic IVR Adapter Data Update Frequency to Oracle Utilities Network Management System

Periodic (configurable)

Data Flow Steps

1.

The external application calls the customer to confirm if power has been restored. The result of this call is passed back to Oracle Utilities Network Management System via the pr_trouble_callback_responses stored procedure.

2.

The stored procedure uses the incident number and premise ID combination (or the external ID and premise ID combination if the first combination is not provided) to identify a callback record in the TROUBLE_CALLBACKS table that would be receiving a response.

3.

The stored procedure updates the identified callback in the TROUBLE_CALLBACKS table by updating the following fields:

•

The callback's CALLBACK_DONE field to 'Y' signifying that the callback was already done.

•

The callback's CALLBACK_TIME field. CALLBACK_TIME field defaults to the system date if no value was provided.

•

The callback's CALLBACK_STATUS field with the appropriate callback response code.

4.

The Oracle Utilities Network Management System Generic IVR Adapter queries the TROUBLE_CALLBACKS table for new callback responses received and sends this information to Oracle Utilities Network Management System.

5.

In Oracle Utilities Network Management System, the callback could get completed or cancelled or a new event (with the original call information) will be created, depending on the callback response.

Callback Response Notes

When a callback is made and no response from customer is received, a callback time will still be recorded. Any callback time that is submitted with a status is propagated, even if the status is no reply from the customer. It is understood in this case to be the last attempted callback. Also, when a nested outage is found, the new call and event are backdated to the original outage time.

Note: NMS does not track callback history.

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

•

$CES_HOME/lib/libIVRAdapter.so

•

$CES_HOME/bin/IVRAdapter

•

$CES_HOME/bin/ces_ivr_gateway.ces

•

$CES_HOME/sql/product_retain_ivr_interface.sql

•

$CES_HOME/sql/product_ivr_interface_head.sql

•

$CES_HOME/sql/product_ivr_interface_body.plb

•

$CES_HOME/bin/troubleCallCreate

•

$CES_HOME/bin/ivrCallPerPoll.ces

•

$CES_HOME/bin/ivrPollPeriod.ces

Setup the Generic IVR Adapter System Variables

Include the following variables in the system variables definition:

Variable

Value

IVR_RDBMS_HOST

same as $RDBMS_HOST defined in the system

IVR_ORACLE_SID

same as $ORACLE_SID defined in the system

Note that this is setup in the .nmsrc file located in the $NMS_HOME (and configured by running config_nmsrc.pl). After the setup of the system variables, make sure that the .nmsrc is rerun or a new terminal is opened. The above setup assumes that the database where the Generic IVR Adapter tables and stored procedures would reside would be the same database used by the Oracle Utilities Network Management System environment.

Note also that the IVR RDBMS can be setup to be a completely separate RDBMS from the production RDBMS instance (hence these environment variables). This option may be considered if a project wants to maintain separation between the call taking process and the call processing process. With a separate RDBMS instance trouble calls can still be captured even if the production NMS RDBMS instance is down - for example. This is considered an advanced form of configuration and generally requires certain tables be replicated between the two RDBMS instances to guarantee calls can still be properly captured when the NMS RDBMS is down. Please consult Oracle support or your project engineer for more information if this type of configuration is desired.

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 3 main sections where this service needs to be defined: the service, program and instance sections. See the $CES_HOME/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

The section below lists the possible command line options for the Generic IVR Adapter. This section also introduces a tool that randomly creates trouble calls, along with its command line options. Performance tuning and high-level diagnostic messages that could be used on the Generic IVR Adapter will be discussed in this section as well.

The Generic IVR Adapter provides various command line options that enables Data Flows and configures Data Flow behavior. The following enumerates the command line options of the Generic IVR Adapter.

IVRAdapter -help

-troublecall

-omscbreq

-omscbresp

-cleantable

-debug [0-2]

-callperpoll NUMBERCALLS

-pollperiod SECONDS

-docustquery

-cbreqinterval SECONDS

-cbrespinterval SECONDS

-cleaninterval HOURS

-keepdbinfo DAYS

-cbagent AGENTNAME

[ -cbAny | -cbLast ]

This section groups the Generic IVR Adapter command line options under the context of the Data Flow or Data Flows it is associated to.

Generic IVR Adapter Generic Command Line Options

The following are the Generic IVR Adapter command line options that are independent from any Data Flow:

Option

Usage

Description

help

IVRAdapter -help

Displays the available command line options

debug

IVRAdapter -debug LEVEL(where LEVEL is 0, 1 or 2)

Runs gateway in debug mode. Associated number represents the debug level range from 0 to 2.

Trouble Call Data Flow Command Line Options

The following are the Generic IVR Adapter command line options that are related to the Trouble Calls Data Flow. For more information, see Trouble Calls .

Option

Usage

Description

Depends On

Default Value

troublecall

IVRAdapter -troublecall

Enables the Trouble Calls Data Flow.

Note : This option must be enabled for CC&B - NMS integration.

callperpoll

IVRAdapter -callperpoll NUMBERCALLS(where NUMBERCALLS is an integer)

Specifies the number of calls processed in the TROUBLE_CALLS table per poll of information.

troublecall

100 calls per poll of information

pollperiod

IVRAdapter -pollperiod SECONDS(where SECONDS is an integer)

Specifies the interval (in seconds) between two successive polls or queries from the TROUBLE_CALLS table

troublecall

a 6 second interval between two successive polls

docustquery

IVRAdapter -docustquery

If this option is selected, not all fields in the TROUBLE_CALLS table are directly fed to JMService. Instead, some of the fields would come from the CES_CUSTOMERS table.

Note : This option should not be used in combination with the CC&B - NMS integration.

troublecall

Callback Requests Data Flow Command Line Options

The following are the Generic IVR Adapter command line options that are related to the Callback Requests Data Flow. For more information, see Callback Requests .

Option

Usage

Description

Depends On

Default Value

omscbreq

IVRAdapter -omscbreq

Enables the Callback Requests Data Flow

cbreqinterval

IVRAdapter -cbreqinterval SECONDS(where SECONDS is an integer)

Specifies the interval (in seconds) between two successive polls from the list of callback requests

omscbreq

a 5 second interval between two successive polls.

cbAny

IVRAdapter -cbAny

Callback is submitted to IVR if requested by the customer during any call.

omscbreq

cbLast

IVRAdapter -cbLast

Callback is submitted to IVR if requested by the customer during the last call.

omscbreq

Callback Responses Data Flow Command Line Options

The following are the Generic IVR Adapter command line options that are related to the Callback Responses Data Flow. For more information, see Callback Responses .

Option

Usage

Description

Depends On

Default Value

omscbresp

IVRAdapter -omscbresp

Enables the Callback Responses Data Flow

cbrespinterval

IVRAdapter -cbrespinterval SECONDS (where SECONDS is an integer)

Specifies the interval (in seconds) between two successive polls from the TROUBLE_CALLBACKS table for received callback responses

omscbresp

a 5 second interval between two successive polls.

Command Line Options Used by Multiple Data Flows

The following are the Generic IVR Adapter command line options that are related to multiple Data Flows. On the ‘Depends On’ section, the term ‘any option that enables a Data Flow’ would pertain to either one of the following command line options: ‘troublecall’, ‘omscbreq’ and ‘omscbresp’.

Option

Usage

Description

Depends On

Default Value

cleantable

IVRAdapter -cleantable

Could be used for any of the five Data Flows. A flag that allows the Generic IVR Adapter to remove some completed records from its tables.

any option that enables a Data Flow

cleaninterval

IVRAdapter -cleaninterval HOURS(where HOURS is an integer)

Could be used for any of the five Data Flows.Specifies the interval (in HOURS) between two successive attempts to delete old (i.e., completed) records from the Oracle Utilities Network Management System Generic IVR Adapter tables.

Cleantable and any option that enables a Data Flow

1 hour between to successive delete attempts

keepdbinfo

IVRAdapter -keepdbinfo DAYS (where DAYS is an integer)

Could be used for any of the five Data Flows.Completed records on the Generic IVR Adapter tables older than the specified number of days will be deleted. Certain criteria apply on which records of the Oracle Utilities Network Management System Generic IVR Adapter tables are removed and how the records are aged.

Cleantable and any option that enables a Data Flow

3 days

cbagent

IVRAdapter -cbagent AGENTNAME (where AGENTNAME is a string)

Could be used for the Callback Requests and Callback Responses Data Flows.

The agent name that the Generic IVR Adapter uses in retrieving calls from the callback list. Valid agent names are located in CES_USER and ENV_ACCESS tables. The agent name used should be an external agent, as indicated in the CES_USER table.

omscbreq or omscbresp

IVR

For the keepdbinfo command line options, a record that starts aging on a given day, say 9:00 p.m. would be considered one day old at 9:00 p.m. the next day (and not 12:00 a.m., which is just 3 hours from the time the record started aging).

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.

Note : It is important for the Generic IVR Adapter System Variables to be setup to run the troubleCallCreate tool. For more information, see Setup the Generic IVR Adapter System Variables.

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

troubleCallCreate tool on testing Trouble Calls Data Flow

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.

troubleCallCreate tool on testing Callback Requests Data Flow

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.

Load the Generic IVR Adapter Database Tables and Stored Procedures

•

The ces_ivr_gateway.ces script is responsible for loading various SQL files responsible for creating the Generic IVR Adapter tables and stored procedures. The ces_ivr_gateway.ces script could call some or all of the following scripts depending on how it was invoked:

•

product_retain_ivr_interface.sql - responsible for dropping and recreating the Generic IVR Adapter tables.

•

product_ivr_interface_head.sql - responsible for loading the Generic IVR Adapter stored procedure head.

•

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

ces_ivr_gateway.ces -offline

Note: The command above recreates the Generic IVR Adapter table by dropping and creating it, 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:

ces_ivr_gateway.ces

Software Configuration

This section is intended to help the user configure the Generic IVR Adapter that was installed on the previous section. This includes the default configuration used, and the modifications to the base configurations that need to be done in order to customize the adapter's behavior.

Overview

This section will discuss how to map pieces of trouble call information sent by the external application to specific database fields within Oracle Utilities Network Management System via the Trouble Call Mapping Properties Configuration file. Moreover, this section will discuss various SRS rules that could be used for the Generic IVR Adapter.

Trouble Call Mapping Configuration

The fields of the Generic IVR Adapter's TROUBLE_CALLS table could be mapped with the fields of Oracle Utilities Network Management System' INCIDENTS and JOBS table. This is done through column matching of TROUBLE_CALLS fields with JMS Input String (JMS.h), which is the standard product column and user-defined configuration through SRS_RULES.

For more information about the Generic IVR Adapter's TROUBLE_CALLS table, see TROUBLE_CALLS Table Schema .

Mapping to the Base Fields in Oracle Utilities Network Management System Tables

The following table explains how the base fields of the INCIDENTS and the JOBS tables of Oracle Utilities Network Management System are mapped with the fields of the TROUBLE_CALLS table of the Generic IVR Adapter.

Below is a description of each column

•

The JMS Input String (first column) is the standard product column found in JMS.h, which is used to create calls with the JMS::sendJMSinput() API, within the Oracle Utilities Network Management System.

•

The ‘Description’ column (second column) describes the content of the field.

•

The ‘Mapping to Oracle Utilities Network Management System Tables’ column (third column) identifies to what fields of the INCIDENTS table or the JOBS table a given JMS Input String is tied up to. In this column, INC.<database field name> indicates that the field name is part of the INCIDENTS table; JOBS.<database field name> indicates that the field name is part of the JOBS table.

•

The ‘Mapping to TROUBLE_CALLS table’ column (fourth column) identifies the TROUBLE_CALLS table column the JMS Input String is currently mapped to.

JMS Input String

Description

Mapping to System Tables

Mapping to TROUBLE_CALLS table

ADDR_BUILDING

Customer building address. The building number portion of the street address of the customer.

INC.ADDR_BUILDING

ADDR_BUILDING

ADDR_CITY

Customer city. The city or city/state portion of the address of the customer.

INC.ADDR_CITY

ADDR_CITY

ADDR_CROSS_STREET

Intersection cross street name. Name of the second cross street should be in ADDR_STREET field.

INC.ADDR_CROSS_STREET

ADDR_CROSS_STREET

ADDR_STREET

Customer street address. The full street address of the customer.

INC.ADDRESS

JOBS.ADDR_STREET

ADDR_STREET

ALTERNATE_PHONE

Alternative contact number. Alternate phone number for contacting the customer.

INC.ALTERNATE_PHONE

ALTERNATE_PHONE

APPT_RANGE

Appointment Range.

INC.APPT_RANGE

APPT_RANGE

APPT_TIME

Time of appointment.

INC.APPT_TIME

APPT_TIME

APPT_TYPE

Type of appointment.

INC.APPT_TYPE

APPT_TYPE

CALL_TIME

Input time of call. The input time of the incident. If not provided, the current time will be used.

INC.INPUT_TIME

CALL_TIME

CALL_TYPE

Type of call.

INC.TYPE

CALL_TYPE

CALLBACK_LATE

Callback late indicator. Indicates that it is OK to call back the customer beyond a defined ‘late’ time. This information is only stored in Oracle Utilities Network Management System. No other action is taken by Oracle Utilities Network Management System.

INC.CALLBACK_LATE

CALLBACK_LATE

CALLBACK_REQUEST

Indicates either a callback is requested or not.

INC.CALLBACK_REQUEST

CALLBACK_REQUEST

CALLBACK_TIME

Time callback requested. Time for which callback or a follow-up call was requested.

INC.CALLBACK_TIME

CALLBACK_TIME

CHECK_CUTOFF

Check cutoff customer indicator. If set to Y, check if the customer is disconnected, using the CES_DISCONNECTS table. If the customer is disconnected, the call will not be saved, an error will be returned and the VERIFY_DISCONNECTS table will be populated.

CHECK_CUTOFF

CID_ALIAS

Not used.

CID_ALIAS

CLUE

Indicates if call is clue if set to Y.

INC.CLUE

CLUE

COMBINE_PRI

Total priority of call.

COMBINE_PRI

COMMENT

Call-taker Comments. Comments provided by the customer or call-taker about the incident.

INC.OP_COMMENT

CALL_COMMENT

CUST_CALL_CANCEL

Call cancel indicator.

INC.CALL_CANCEL

CUST_CALL_CANCEL

CUST_CRITICAL

Critical customer indicator. This is added to the critical C count of the outage.

INC.CRITICAL_CUST

CUST_CRITICAL

CUST_DEVICE_ALIAS

The name of the device to which the customer is connected. This must be the alias of the device handle provided with CUST_DEVICE_CLS and CUST_DEVICE_IDX. If not provided, the service will query ODService to get this information, incurring a performance penalty in call processing.

INC.OBJECT

CUST_DEVICE_ALIAS

CUST_DEVICE_CLS

Customer device class. The class part of the handle for the device to which the customer is connected. If CUST_ID is provided, but the device is not, JMService will look up the customer device in the CES_CUSTOMERS table. If the provided device is a supply node, it will be put in SUPPLY_CLS & SUPPLY_IDX and the first stage device will be put in H_CLS & H_IDX.

INC.H_CLS

CUST_DEVICE_CLS

CUST_DEVICE_IDX

Customer device index. The index part of the handle for the device to which the customer is connected. See CUST_DEVICE_CLS above.

INC.H_IDX

CUST_DEVICE_IDX

CUST_DEVICE_NCG

NCG of customer device.

INC.NCG

CUST_DEVICE_NCG

CUST_DEVICE_PARTITION

Partition of customer device.

INC.PARTITION

CUST_DEVICE_PARTITION

CUST_FIRST_NAME

Customer first name. The first name of the customer. If CUST_FIRST_NAME and CUST_LAST_NAME are both provided, they will be appended together with a space. The concatenated customer first and last name (with a space in the middle) may not be larger than 75 characters. This may be used for the full name of the customer if CUST_LAST_NAME is omitted.

INC.CUSTOMER_NAME

JOBS.CUSTOMER_NAME

CUST_FIRST_NAME

CUST_ID

Unique identifier of a customer record in NMS. See CUST_DEVICE_CLS above.

INC.CID

CUST_ID

CUST_INTERSECT_CLS

Intersecting device class.

CUST_INTERSECT_CLS

CUST_INTERSECT_IDX

Intersecting device index.

CUST_INTERSECT_IDX

CUST_INTERSECT_NCG

Intersecting NCG.

CUST_INTERSECT_NCG

CUST_INTR_X

Intersecting X coordinate. X coordinate used for intersection grouping. See streetXsectionOffset SRS Rule for more information.

CUST_INTR_X

CUST_INTR_Y

Intersecting Y coordinate. Y coordinate used for intersection grouping. See streetXsectionOffset SRS Rule for more information.

CUST_INTR_Y

CUST_KEY

Customer account number.

INC.ACCOUNT_NUM

CUST_KEY

CUST_LAST_NAME

The last name of the customer. See CUST_FIRST_NAME above.

INC.CUSTOMER_NAME

JOBS.CUSTOMER_NAME

CUST_LAST_NAME

CUST_LIFE_SUPPORT

Life support customer. If set to ‘Y’, indicates a life support customer. This is added to the critical K count of the outage.

INC.LIFE_SUPPORT

CUST_LIFE_SUPPORT

CUST_ORDER_NUM

Customer order number. Not used in the Oracle Utilities Network Management System.

INC.ORDER_NUMBER

CUST_ORDER_NUM

CUST_PHONE

Customer phone number. The non-area code portion of the customer phone number. If both CUST_PHONE and CUST_PHONE_AREA are provided, they will be appended according to the customerPhoneParentheses SRS rule. The concatenated customer phone number and area (including parentheses) may not be larger than 32 characters. This field may be used for the full customer phone number if CUST_PHONE_AREA is omitted. See customerPhoneParentheses SRS Rule for more information.

INC.CUSTOMER_PHONE

JOBS.CUSTOMER_PHONE

CUST_PHONE

CUST_PHONE_AREA

Customer phone area code. The area code portion of the customer phone number. See CUST_PHONE above.

INC.CUSTOMER_PHONE

JOBS.CUSTOMER_PHONE

CUST_PHOHE_AREA

CUST_PHONE_UPDATE

Whether to update customer phone. If set to Y, the customer phone number will be updated in the CUSTOMER_PHONE_OVERRIDE table.

CUST_PHONE_UPDATE

CUST_PRIORITY

Customer priority. This string is used to determine the critical customer type and priority of the customer.

INC.CUSTOMER_TYPE

CUST_PRIORITY

CUST_STATUS

Condition status of call.

CUST_STATUS

CUST_TROUBLE_CODE

Customer complaint. The customer complaint (trouble code). This is a required field and must correspond with values in the SRS_TROUBLE_CODES table.

INC.COMPLAINT

CUST_TROUBLE_CODE

CUST_TROUBLE_QUEUE

Customer trouble queue.

INC.TROUBLE_QUEUE

JOBS.TROUBLE_QUEUE

CUST_TROUBLE_QUEUE

DRV_INST

Driving instructions.

INC.DRV_INSTR1

DRV_INST

EXTERNAL_ID

Unique call identifier. The unique identifier for the incident.

INC.EXTERNAL_ID

JOBS.EXTERNAL_ID

EXTERNAL_ID

FUZZY_NCG_CLS

Fuzzy control zone class.

FUZZY_NCG_CLS

FUZZY_NCG_IDX

Fuzzy control zone index.

FUZZY_NCG_IDX

GENERAL_AREA

General Area. Not Used in the Oracle Utilities Network Management System.

INC.GENERAL_AREA

GENERAL_AREA

GROUP_BY_NAME

Fuzzy control zone name.

GROUP_BY_NAME

GROUPABLE

If set to Y, the call is groupable.

INC.GROUPABLE

GROUPABLE

MEET_TIME

Time of customer meet. If provided, meet created will be a future meet for the given time. Otherwise, if a meet is created it will be a critical meet. MEET_TYPE must be provided to create a meet.

INC.MEET_TIME

MEET_TIME

MEET_TYPE

Customer meet type. If set to 1, a new meet will be created. If set to 2, an existing meet will be rescheduled. If set to 3, an existing meet will be canceled. If any other value is provided, no meet will be created. May be used in conjunction with MEET_TIME.

INC.MEET_CODE

MEET_TYPE

METER_ID

Customer meter number.

INC.METER_ID

METER_ID

POWER_UP

Power-up call. Used for power-up messages from CellNet. Used for AMR.

POWER_UP

RELATED_EVT_APP

Related event application.

RELATED_EVT_APP

RELATED_EVT_CLS

Related event class.

INC. RELATED_CLS

RELATED_EVT_CLS

RELATED_EVT_IDX

Related event index.

INC. RELATED_IDX

RELATED_EVT_IDX

REPORTED_ERT

Est rest time reported to caller.

INC. REPORTED_EST_REST_TIME

REPORTED_ERT

SHORT_DESC

Short description of trouble.

INC.SHORT_DESC

SHORT_DESC

TROUBLE_LOC

Incident's trouble location.

INC.TROUBLE_LOC

TROUBLE_LOC

UPDATE_EXISTING_INC

Whether to update an existing incident. If set to 1, then JMService will replace an existing incident for the same customer with the values passed in this call.

UPDATE_EXISTING_INC

USER_NAME

Call-taker user name. The name of the call-taker or interface that created the call.

INC.USER_NAME

USER_NAME

X_REF

Customer X coordinate. X coordinate of customer or customer device.

INC.X_COORD

X_REF

Y_REF

Customer Y coordinate. Y coordinate of customer or customer device.

INC.Y_COORD

Y_REF

During initialization of IVRAdapter, TROUBLE_CALLS column are matched with the standard product column (JMS.h). If TROUBLE_CALLS field does not match, error will be logged and IVRAdapter will exit.

The following are some exceptions when matching TROUBLE_CALLS columns with JMS Input String:

•

TROUBLE_CALLS.CALL_COMMENT - JMS Input String COMMENT

•

TROUBLE_CALLS.CALL_STATUS - special column in TROUBLE_CALLS table that indicates that the call is new (N) or already processed (C).

•

TROUBLE_CALLS.SUPPLY_ID - if this column exists, it replaces the value of TROUBLE_CALLS. CUST_DEVICE_IDX and TROUBLE_CALLS. CUST_DEVICE_CLS is set to 994.

Mapping to Customer-Defined Fields in Oracle Utilities Network Management System's INCIDENTS table

A configurable TROUBLE_CALLS column can also be done through SRS_RULES.

The following are the steps to map a new field in the TROUBLE_CALLS table with a new field in the INCIDENTS table:

1.

Change the TROUBLE_CALLS table schema to include the customized field, for instance, TC_FIELD_ONE.

2.

Change the INCIDENTS table schema to include a new field that will be mapped to TC_FIELD_ONE. For instance the new field on the INCIDENTS table would be INC_FIELD_ONE.

3.

Create a new SRS Rule that maps the ‘201’ (TROUBLE_CALLS reserve name) with the new field in the INCIDENTS table, INC_FIELD_ONE. See the Map Customer-Defined Fields in the INCIDENTS Table SRS rule for more information.

4.

Restart JMService and the Generic IVR Adapter.

Note: Before considering the option of introducing new fields in the TROUBLE_CALLS table and the INCIDENTS table, it is advisable to discuss such option with your Project Engineer.

Trouble Callback Mapping Configuration

IVR Adapter allows arbitrary information from the PICKLIST_INFO_UPD_TR table to be included into callback request. Columns CB_DETAIL1, CB_DETAIL2, CB_DETAIL3 and CB_DETAIL4 in the TROUBLE_CALLBACKS database table are used for this purpose. Database table IVR_ADAPTER_CONFIG is used to define if/how these columns should be populated.

Field Name

Nullable

Data Type

Description

CONFIG_ITEM

N

VARCHAR2(32)

Column name in the TROUBLE_CALLBACKS database table, which should be populated from the PICKLIST_INFO_UPD_TR table. Valid values are

CONFIG_VALUE

N

VARCHAR2(32)

Column name in the PICKLIST_INFO_UPD_TR table, which should be used as the data source.

SRS Rules Configuration

The following are SRS rules that could be used with the Generic IVR Adapter. These SRS rules can be included in the <project>_srs_rules.sql file.

Map Customer-Defined Fields in the INCIDENTS Table

Oracle Utilities Network Management System and the Generic IVR Adapter provides a mechanism to receive additional trouble call information from the external application and have this information stored in a new customer-defined field in the INCIDENTS table of Oracle Utilities Network Management System.

The configurable TROUBLE_CALLS column name has special names ‘201’, ‘202’, up to ‘209’ to serve this purpose. Normally, a regular column name in TROUBLE_CALLS like CALL_COMMENT or COMMENT in JMS Input String is tied to a specific field of the INCIDENTS table by default. For this case, it's the OP_COMMENT field. A special name like ‘201’ could be mapped to a new field in the INCIDENTS table by using an SRS rule. The table below details how an SRS rule could be used to do this mapping. An SRS rule like this has to be used for each mapping. See Map Customer-Defined Fields in the INCIDENTS Table for more information.

Field Name

Value

SET_NAME

‘config_incident’

INCIDENT_TYPE

‘customer_defined’

RULE_NAME

the name of the new column in the INCIDENTS table

RULE_VALUE_1

‘str’, ‘date’, ‘int’, ‘float’

‘str’ is for strings, ‘date’ is for dates, ‘int’ is for integers, and ‘float’ is for floats. This represents the data type of the new column.

RULE_VALUE_2

An integer, representing the value of the SRS input configuration item specifying this field -- must have a value of 200 or greater

RULE_VALUE_INTEGER_1

0 (not used)

RULE_VALUE_INTEGER_2

0 (not used)

RULE_VALUE_INTEGER_3

0 (not used)

RULE_VALUE_INTEGER_4

0 (not used)

RULE_VALUE_INTEGER_5

0 (not used)

callbackInterfaceEnabled SRS Rule

If set to ‘yes’ then SRS APIs for manipulating callback information will become available. It has to be set to ‘yes’ for Web Callback GUI to operate. This rule holds outage information in JMService memory on a special data structure until this time expires OR all customer callbacks for the outage are complete.

Field Name

Value

SET_NAME

‘config’

INCIDENT_TYPE

‘any’

RULE_VALUE_1

‘yes’ or ‘no’ (default: ‘no’)

RULE_VALUE_2

0 (not used)

RULE_VALUE_INTEGER_1

0 (not used)

RULE_VALUE_INTEGER_2

0 (not used)

RULE_VALUE_INTEGER_3

0 (not used)

RULE_VALUE_INTEGER_4

0 (not used)

RULE_VALUE_INTEGER_5

0 (not used)

useExternalCause SRS Rule

If set to ‘yes’ then the IVR Adapter’s callback requests data flow will include the cause code when it populates the TROUBLE_CALLBACKS table. The cause code value will be taken from JOBS.CAUSE.

Field Name

Value

SET_NAME

‘config’

INCIDENT_TYPE

‘any’

RULE_VALUE_1

‘yes’ or ‘no’ (default: ‘yes’)

RULE_VALUE_2

0 (not used)

RULE_VALUE_INTEGER_1

0 (not used)

RULE_VALUE_INTEGER_2

0 (not used)

RULE_VALUE_INTEGER_3

0 (not used)

RULE_VALUE_INTEGER_4

0 (not used)

RULE_VALUE_INTEGER_5

0 (not used)

customerPhoneParentheses SRS Rule

If rule_value_1 set to ‘yes’, parentheses will be added to customer call phone numbers in the following format: (AREA)NUMBER. Otherwise, the number and area will be concatenated together without parentheses.

Field Name

Value

SET_NAME

‘config’

INCIDENT_TYPE

‘any’

RULE_VALUE_1

‘yes’ or ‘no’ (Default: ‘yes’)

RULE_VALUE_2

0 (not used)

RULE_VALUE_INTEGER_1

0 (not used)

RULE_VALUE_INTEGER_2

0 (not used)

RULE_VALUE_INTEGER_3

0 (not used)

RULE_VALUE_INTEGER_4

0 (not used)

RULE_VALUE_INTEGER_5

0 (not used)

defaultCallbackAgent SRS Rule

Specifies username of the default callback agent. All new callbacks will be automatically assigned to this agent. If this rule is not set then new callbacks will be left unassigned.

Note: This rule only takes effect if the rule callbackInterfaceEnabled set to ‘yes’. See callbackInterfaceEnabled SRS Rule for more information. The agent name used should be considered as an external agent in the CES_USER and ENV_ACCESS tables. Also, it is recommended that ‘IVR’ be used as a value of RULE_VALUE_1, as this is the default callback agent name that the Generic IVR Adapter uses when the adapter runs.

Field Name

Value

SET_NAME

‘config’

INCIDENT_TYPE

‘any’

RULE_VALUE_1

callback agent username

RULE_VALUE_2

0 (not used)

RULE_VALUE_INTEGER_1

0 (not used)

RULE_VALUE_INTEGER_2

0 (not used)

RULE_VALUE_INTEGER_3

0 (not used)

RULE_VALUE_INTEGER_4

0 (not used)

RULE_VALUE_INTEGER_5

0 (not used)

callbackFeederTimeout SRS Rule

The maximum time allowed (in minutes) between the current time and the restoration time of a resolution in callback module before the resolution is deemed too old to remain or be loaded into the callback module. This rule holds outage info in JMService memory in a special data structure until this time expires OR all customer callbacks for the outage are complete.

If this rule is set to 0 then resolutions will be kept in JMService until all callbacks are completed.

Note: This rule must be used in conjunction with the callbackInterfaceEnabled SRS Rule .

Field Name

Value

INCIDENT_TYPE

‘flowControlGeneral’

RULE_VALUE_1

"" (not used)

RULE_VALUE_2

An integer, representing a number of minutes (Default: 2880 -- 48 hours)

RULE_VALUE_INTEGER_1

0 (not used)

RULE_VALUE_INTEGER_2

0 (not used)

RULE_VALUE_INTEGER_3

0 (not used)

RULE_VALUE_INTEGER_4

0 (not used)

RULE_VALUE_INTEGER_5

0 (not used)

streetXsectionOffset SRS Rule

Specifies the size of the maximum bounding rectangle to be used in grouping street intersection fuzzy calls to supply nodes. The rectangle will be the area where:

x E [xsection_x - THIS RULE VALUE, xsection_x + THIS RULE VALUE]

and

y E [xsection_y - THIS RULE VALUE, xsection_y + THIS RULE VALUE]

This is an integer. Check your world coordinate system for a reasonable integer value.

This rule is used once for each rectangle desired (i.e., multiple instances of this rule may exist in a single rule set). For example, a larger rectangle size may be desired in a rural control zone and a smaller rectangle in an urban control zone.

Field Name

Value

RULE_VALUE_1

‘‘ (not used)

RULE_VALUE_2

integer (Default: none)

RULE_VALUE_INTEGER_1

0 (not used)

RULE_VALUE_INTEGER_2

0 (not used)

RULE_VALUE_INTEGER_3

0 (not used)

RULE_VALUE_INTEGER_4

0 (not used)

RULE_VALUE_INTEGER_5

0 (not used)

NCG_CLS

integer, representing ncg_cls of desired applicable control zone level

NCG_IDX

integer, representing ncg_idx of desired applicable control zone level

Generic IVR Adapter Trouble Call Performance

The maximum rate at which the Generic IVR Adapter injects trouble calls into the Oracle Utilities Network Management System is initially determined using the -callperpoll and -pollperiod command line parameters in the system.dat file. If these parameters are not set, the Generic IVR Adapter will, by default, retrieve a maximum of 100 trouble calls from the TROUBLE_CALLS table every six seconds and send these calls into the MMM via JMService. This corresponds to a maximum hourly call rate of 60,000 calls per hour.

If it is necessary to change this call rate while the adapter is running, two scripts are provided: ivrCallPerPoll.ces and ivrPollPeriod.ces. These scripts may be used to adjust the number of calls retrieved during each poll cycle and the period between poll cycles while the adapter is running.

Note : If the adapter is restarted, these parameters (and the corresponding call rate) will revert to the command line parameters specified in the system.dat file (or the default values if no command line options are specified).

Command

Usage

Description

ivrCallPerPoll.ces

ivrCallPerPoll.ces NUM_CALLS_PER_POLL

Changes the number of calls retrieved from the TROUBLE_CALLS table during one poll cycle.

IvrPollPeriod.ces

IvrPollPeriod.ces NUM_SECONDS

Changes the period between poll cycles where calls are retrieved from the TROUBLE_CALLS table and submitted to JMService.

Generic IVR Adapter Troubleshooting

This section identifies high-level messages that could be sent to the Generic IVR Adapter using the Action command for troubleshooting purposes.

Command

Usage

Description

report

Action -services any.IVRGateway report

Reports back if the Generic IVR Adapter has started.

stop

Action -services any.IVRGateway stop

Stops the Generic IVR Adapter

debug

Action -services any.IVRGateway debug LEVEL

(where LEVEL is 0, 1 or 2)

Sets the Generic IVR Adapter’s debug level

cleantable

Action -services any.IVRGateway cleantable

Toggles the ‘cleantable’ command line option. Instructs if the Generic IVR Adapter should remove some records from its tables or not.

Note: It is important that the Generic IVR Adapter is already included in the System Data file to run high-level messages properly. For more information, see Configure Adapter to run as NMS System Service .

Database Schema

Overview

The following section defines in detail the schema of each database tables used by the Generic IVR Adapter. These Generic IVR Adapter tables however are not captured by performance mart. Moreover, this section defines the parameters used by the Generic IVR Adapter's stored procedures.

Database Table Schema

TROUBLE_CALLS Table Schema

The TROUBLE_CALLS table stores the trouble calls that are submitted by the external application. The Generic IVR Adapter polls this table and submits new trouble call records to Oracle Utilities Network Management System, so Oracle Utilities Network Management System could apply the outage analysis algorithm to predict the outage device. The external application indirectly inserts records to the TROUBLE_CALLS table by invoking the pr_trouble_calls stored procedure. See pr_trouble_calls for more information.

Each field of the TROUBLE_CALLS table is matched with SRSinput field. The mapping is configurable. A column names are directly tied up to a specific field of the INCIDENTS table or the JOBS table of Oracle Utilities Network Management System.

In effect, each field in the TROUBLE_CALLS table is mapped (and the mapping is configurable) to a particular field of the INCIDENTS table or the JOBS table of Oracle Utilities Network Management System. For more information, see Trouble Call Mapping Configuration .

In the 'Description' column, take note that field names prefixed with 'INC.' would come from the INCIDENTS table. Field names prefixed by 'JOBS.' would come from the JOBS table. Field names prefixed by 'CC.' would come from the CES_CUSTOMERS table.

Field Name

Nullable

Data Type

Description (JMS Input String Reference)

ADDR_BUILDING

Y

VARCHAR2(10)

Customer building address. Refer to ADDR_BUILDING for more information.

Map to INC.ADDR_BUILDING

ADDR_CITY

Y

VARCHAR2(45)

Customer City/State. Refer to ADDR_CITY for more information.

Maps to INC.ADDR_CITY

ADDR_CROSS_STREET

Y

VARCHAR2(255)

Intersection cross street name.

Maps to INC.ADDR_CROSS_STREET.

ADDR_STREET

Y

VARCHAR2(255)

Customer address. Refer to ADDR_STREET for more information.

Maps to INC.ADDRESS and JOBS.ADDR_STREET

ALTERNATE_PHONE

Y

VARCHAR2(32)

Alternative contact number. Refer to ALTERNATE_PHONE for more information.

Maps to INC.ALTERNATE_PHONE

APPT_RANGE

Y

NUMBER

Appointment Range. Refer to APPT_RANGE for more information.

Maps to INC.APPT_RANGE.

APPT_TIME

Y

DATE

Time of appointment. Refer to APPT_TIME for more information.

Maps to INC.APPT_TIME.

APPT_TYPE

Y

VARCHAR2(16)

Type of appointment. Refer to APPT_TYPE for more information.

Maps to INC.APPT_TYPE.

CALL_COMMENT

Y

VARCHAR2(255)

Customer Comment. Refer to COMMENT Property Name for more information.

Maps to INC.OP_COMMENT.

CALL_ID

Y

VARCHAR2(16)

Not used.

CALL_STATUS

Y

VARCHAR2(1)

Status of the trouble call in the TROUBLE_CALLS table. The Generic IVR Adapter uses this internally to identify the status of this trouble call.

The possible values are as follows:

‘N’ - New trouble call

‘I’ - The Generic IVR Adapter is in the process of submitting this trouble call to Oracle Utilities Network Management System

‘C’ - Trouble call submission to Oracle Utilities Network Management System is completed.

The Generic IVR Adapter uses this field as one of the criteria in purging the TROUBLE_CALLS table for 'old' records. Records with CALL_STATUS field = 'C' will be purged.

CALL_TIME

N

DATE

Input time of call. Refer to CALL_TIME for more information.

Maps to INC.INPUT_TIME

The Generic IVR Adapter uses this field as one of the criteria in purging the TROUBLE_CALLS table for 'old' records. The TROUBLE_CALL record is 'aged' based on the system date/time and the CALL_TIME field. Any record older than a predefined number of days will be removed. See keepdbinfo for more information.

CALL_TYPE

Y

VARCHAR2(8)

Type of call. Refer to CALL_TYPE for more information.

Maps to INC.TYPE

CALLBACK_LATE

Y

VARCHAR2(1)

Callback late indicator. Refer to CALLBACK_LATE for more information.

The possible values are as follows:

‘Y’ - It is OK to call back even when it is already late.

‘N’ - It is not OK to call back when it is already late.

If no value was supplied, this field will default to 'N'.

This information is only passed from the external application to Oracle Utilities Network Management System (using the Trouble Calls Data Flow), and back to the external application (using the Callback Requests Data Flow). No other action is taken.

CALLBACK_REQUEST

Y

NUMBER

Callback request indicator. Refer to CALLBACK_REQUEST for more information.

The possible values are as follows:

‘0’ - callback not requested

‘1’ - callback requested

Maps to INC.CALLBACK_REQUEST

CALLBACK_TIME

Y

DATE

Callback Before Time. Refer to CALLBACK_TIME for more information.

Maps to INC.CALLBACK_TIME

CHECK_CUTOFF

Y

VARCHAR2(1)

Check cut-off customer indicator. Refer to CHECK_CUTOFF for more information.

The possible values are as follows:

‘Y’ - check if the customer is disconnected

‘N’ - do not perform checking.

CLUE

Y

NUMBER

Indicates if call is clue if set to Y. Refer to CLUE for more information.

Maps to INC.CLUE

COMBINE_PRI

Y

NUMBER

Total priority of call. Refer to COMBINE_PRI for more information.

CUST_CALL_CANCEL

Y

VARCHAR2(1)

Call cancel indicator. Refer to CUST_CALL_CANCEL for more information.

Maps to INC.CALL_CANCEL

CUST_CRITICAL

Y

VARCHAR2(1)

Critical customer indicator. This is added to the critical C count of the outage. Refer to CUST_CRITICAL for more information.

Maps to INC.CRITICAL_CUST

CUST_DEVICE_ALIAS

Y

VARCHAR2(32)

Customer Device Alias. Refer to CUST_DEVICE_ALIAS for more information.

Maps to INC.OBJECT

CUST_DEVICE_CLS

Y

NUMBER

Corresponding CC.H_CLS field for the given CC.SERV_LOC_ID. This field does not have a corresponding input parameter in the pr_trouble_calls stored procedure. The stored procedure itself populates this field. Refer to CUST_DEVICE_CLS for more information.

Maps to INC.H_CLS

CUST_DEVICE_IDX

Y

NUMBER

Corresponding CC.H_IDX field for the given CC.SERV_LOC_ID. This field does not have a corresponding input parameter in the pr_trouble_calls stored procedure. The stored procedure itself populates this field. Refer to CUST_DEVICE_IDX for more information.

Maps to INC.H_IDX

CUST_DEVICE_NCG

Y

NUMBER

NCG of customer device. Refer to CUST_DEVICE_NCG for more information.

Maps to INC.NCG

CUST_DEVICE_PARTITION

Y

NUMBER

Partition of customer device. Refer to CUST_DEVICE_ PARTITION for more information.

Maps to INC.PARTITION

CUST_FIRST_NAME

Y

VARCHAR2(75)

Customer Name. Refer to CUST_FIRST_NAME for more information.

Maps to INC.CUSTOMER_NAME and

JOBS.CUSTOMER_NAME

CUST_ID

Y

VARCHAR2(64)

Unique customer record identifier. Maps to INC.CID.

CUST_INTERSECT_CLS

Y

NUMBER

Intersecting device class. Refer to CUST_INTERSECT_ CLS for more information.

CUST_INTERSECT_IDX

Y

NUMBER

Intersecting device index. Refer to CUST_INTERSECT_ IDX for more information.

CUST_INTERSECT_NCG

Y

NUMBER

Intersecting NCG. Refer to CUST_INTERSECT_ NCG for more information.

CUST_INTR_X

Y

NUMBER

Intersecting X coordinate. X coordinate used for intersection grouping.

CUST_INTR_Y

Y

NUMBER

Intersecting Y coordinate.Y coordinate used for intersection grouping.

CUST_KEY

Y

VARCHAR2(16)

Corresponding CC.ACCOUNT_NUMBER field for the given CC.SERV_LOC_ID. This field does not have a corresponding input parameter in the pr_trouble_calls stored procedure. The stored procedure itself populates this field. Refer to CUST_KEY for more information.

Maps to INC.ACCOUNT_NUM

CUST_LAST_NAME

Y

VARCHAR2(75)

The last name of the customer. Refer to CUST_LAST_NAME for more information.

Maps to INC.CUSTOMER_NAME and

JOBS.CUSTOMER_NAME

CUST_LIFE_SUPPORT

Y

VARCHAR2(1)

Life support customer. Refer to CUST_LIFE_SUPPORT for more information.

Maps to INC.LIFE_SUPPORT

CUST_ORDER_NUM

Y

VARCHAR2(16)

Customer order number. Refer to CUST_ORDER_NUM for more information.

Maps to INC.ORDER_NUMBER

CUST_PHONE

Y

VARCHAR2(32)

Customer phone number. Refer to CUST_PHONE for more information.

Maps to INC.CUSTOMER_PHONE and JOBS.CUSTOMER_PHONE

CUST_PHONE_AREA

Y

VARCHAR2(8)

Customer phone area code. Refer to CUST_PHONE_AREA for more information.

Maps to INC.CUSTOMER_PHONE and

JOBS.CUSTOMER_PHONE

CUST_PHONE_UPDATE

Y

VARCHAR2(1)

Whether to update customer phone. Refer to CUST_PHONE_ UPDATE for more information.

CUST_PRIORITY

Y

VARCHAR2(4)

Customer Priority. Refer to CUST_PRIORITY for more information.

This is defined by customer and needs to be an integer string.

Maps to INC.CUSTOMER_TYPE

CUST_STATUS

Y

NUMBER

Condition status of call.

CUST_TROUBLE_CODE

N

VARCHAR2(10)

Trouble code or customer complaint. Refer to CUST_TROUBLE_ CODE for more information.

This is the trouble or complaint that the customer reports when making a call. The trouble code determines the priority of the incident.

Trouble code mapping setup in Oracle Utilities Network Management System should be synchronized with the trouble code mapping setup on the external application. This is to ensure that the trouble code sent from the external application is interpreted similarly when the trouble code is received by Oracle Utilities Network Management System.

Maps to INC.COMPLAINT

CUST_TROUBLE_QUEUE

Y

VARCHAR2(10)

Customer trouble queue. Refer to CUST_TROUBLE_ QUEUE for more information.

This field contains the name of the work group queue that the event has been referred to.

Maps to INC.TROUBLE_QUEUE and JOBS.TROUBLE_QUEUE

DRV_INST

Y

VARCHAR2(180)

Driving instructions.

Maps to INC.DRV_INSTR1

EXTERNAL_ID

N

VARCHAR2(16)

External ID. Refer to EXTERNAL_ID for more information

If it is used, its value should be unique.

Maps to INC.EXTERNAL_ID and

JOBS.EXTERNAL_ID

FUZZY_NCG_CLS

Y

NUMBER

Fuzzy control zone class.

FUZZY_NCG_IDX

Y

NUMBER

Fuzzy control zone index.

GENERAL_AREA

Y

VARCHAR2(32)

General Area. Not Used in the SPL OMS System.

Maps to INC.GENERAL_AREA

GROUP_BY_NAME

Y

VARCHAR2(127)

Fuzzy control zone name.

GROUPABLE

Y

NUMBER

Indicates if call is groupable if set to 1.

Maps to INC.GROUPABLE

MEET_TIME

Y

DATE

Time of customer meet. Refer to MEET_TIME for more information.

Maps to INC.MEET_TIME

MEET_TYPE

Y

NUMBER

Customer meet type. Refer to MEET_TYPE for more information.

Maps to INC.MEET_CODE

METER_ID

Y

VARCHAR2(32)

Customer meter number.

Maps to INC.METER_ID

RELATED_EVT_APP

Y

NUMBER

Related event application.

RELATED_EVT_CLS

Y

NUMBER

Related event class.

Maps to INC. RELATED_CLS

RELATED_EVT_IDX

Y

NUMBER

Related event index.

Maps to INC. RELATED_IDX

REPORTED_ERT

Y

DATE

Estimated restoration time reported to caller.

Maps to INC. REPORTED_EST_REST_TIME

SHORT_DESC

Y

VARCHAR2(128)

Trouble short description.

Maps to INC.SHORT_DESC

TROUBLE_LOC

Y

VARCHAR2(255)

Incident's trouble location.

Maps to INC.TROUBLE_LOC

UPDATE_EXISTING_INC

Y

NUMBER

Whether to update an existing incident. Refer to UPDATE_EXISTING_ INC for more information.

USER_NAME

Y

VARCHAR2(32)

Call-taker user name. Refer to USER_NAME for more information.

Maps to INC.USER_NAME

X_REF

Y

NUMBER

Customer X coordinate. Refer to X_REF for more information.

Maps to INC.X_COORD

Y_REF

Y

NUMBER

Customer Y coordinate. Refer to Y_REF for more information.

Maps to INC.Y_COORD

TROUBLE_CALLBACKS Table Schema

The TROUBLE_CALLBACKS table contains callback request information that has to be reported to the external application. The table also stores the corresponding callback response received from the external application. The Generic IVR Adapter directly inserts new callback requests to the said table. It also directly picks up processed callbacks from the same table. The external application is provided two stored procedures for indirectly reading and updating callback information from the table.

From the table below, on the 'Description' column, take note that field names prefixed with 'INC.' would come from the INCIDENTS table.

Column Name

Nullable

Data Type

Description

EVENT_CLS

Y

NUMBER(38)

Populated by the Callback Requests Data Flow from INC.EVENT_CLS.

EVENT_IDX

Y

NUMBER(38)

Populated by the Callback Requests Data Flow from INC.EVENT_IDX.

INCIDENT_NUMB

N

NUMBER(38)

Populated by the Callback Requests Data Flow from INC.NUMB.

PREMISE_ID

N

VARCHAR2(50)

Populated by the Callback Requests Data Flow from INC.ACCOUNT_NUM.

CUSTOMER_NAME

Y

VARCHAR2(75)

Populated by the Callback Requests Data Flow from INC.CUSTOMER_NAME.

CUSTOMER_PHONE

Y

VARCHAR2(38)

Populated by the Callback Requests Data Flow from INC.CUSTOMER_PHONE.

CUSTOMER_ADDRESS

Y

VARCHAR2(255)

Populated by the Callback Requests Data Flow by concatenating INC.ADDR_BUILDING, INC.ADDRESS and INC.ADDR_CITY

ALTERNATE_PHONE

Y

VARCHAR2(38)

Populated by the Callback Requests Data Flow from INC.ALTERNATE_PHONE.

TROUBLE_CODE

Y

VARCHAR2(32)

Populated by the Callback Requests Data Flow from INC.COMPLAINT.

This is the trouble code (e.g., '10000000') of the incident rather than the clue (e.g., 'Out'). 'Out' is short for 'All Power Out'.

SHORT_DESCRIPTION

Y

VARCHAR2(128)

Populated by the Callback Requests Data Flow from INC.SHORT_DESC

This is the clue (e.g., 'Out') of the incident rather than the trouble code (e.g., '10000000'). 'Out' is short for 'All Power Out'.

CUSTOMER_COMMENT

Y

VARCHAR2(255)

Populated by the Callback Requests Data Flow from INC.OP_COMMENT.

INCIDENT_TIME

Y

DATE

Populated by the Callback Requests Data Flow from INC.INPUT_TIME.

The Generic IVR Adapter uses this field as one of the criteria in purging the TROUBLE_CALLBACKS table for 'old' records. The TROUBLE_CALLBACKS table record is 'aged' based on the system date/time and the INCIDENT_TIME field. Any record older than a predefined number of days will be removed. See keepdbinfo for more information.

EXTERNAL_ID

Y

VARCHAR2(16)

Populated by the Callback Requests Data Flow from INC.EXTERNAL_ID.

CALLBACK_STATUS

Y

VARCHAR2(10)

Initially populated by the Callback Requests Data Flow as NULL;

The field is repopulated by the external application (using pr_trouble_callback_responses stored procedure). The valid values are as follows:

'F' - Not Restored Callback

'R' - Restored Callback

'N' - Cancel Callback, unable to get a response

The Callback Response Data Flow is responsible for sending the updated value to Oracle Utilities Network Management System. A remapped value is placed in INC.CALLBACK_STATUS.

CALLBACK_TIME

Y

DATE

Initially populated by the Callback Requests Data Flow as NULL;

The field could be repopulated by the external application (using pr_trouble_callback_responses stored procedure). The stored procedure defaults this field to the system date if no information was supplied by the external application.

The Callback Response Data Flow is responsible for sending the updated value to Oracle Utilities Network Management System. The value is placed in INC.CB_CALL_TIME.

CALL_TAKER_ID

Y

VARCHAR2(32)

Populated by the Callback Requests Data Flow from INC.USER_NAME.

CALLBACK_LATE

Y

VARCHAR2(1)

Populated by the Callback Requests Data Flow from INC.CALLBACK_LATE

The possible values are as follows:

‘Y’ - It is OK to call back even when it is already late.

‘N’ - It is not OK to call back when it is already late.

This information is only passed from the external application to Oracle Utilities Network Management System (using the Trouble Calls Data Flow), and back to the external application (using the Callback Requests Data Flow). No other action is taken.

CALLBACK_LATE_TIME

Y

DATE

Populated by the Callback Requests Data Flow from INC.CALLBACK_TIME.

This information is only passed from the external application to Oracle Utilities Network Management System (using the Trouble Calls Data Flow), and back to the external application (using the Callback Requests Data Flow). No other action is taken.

CALLBACK_REASON

Y

VARCHAR2(100)

This is used by the Generic IVR Adapter to indicate the source of the callback request. This will default to 'OMS'.

PROCESS_STATUS

Y

VARCHAR2(1)

Initially populated by the Callback Requests Data Flow as 'N', signifying that the record is a new callback

Once the record was fetched by the external application (using pr_trouble_callback_requests stored procedure), the field is automatically updated by the stored procedure to 'I' signifying that the external system is currently processing the callback response.

As soon as the external application successfully returns the callback response to the Generic IVR Adapter (using pr_trouble_callback_responses stored procedure), the field is updated to 'C', signifying that the external application has completed the processing of the callback response.

This field is internally maintained by the Generic IVR Adapter. Below is a list of valid values for this field.

'N' - New Callback

'I' - In Processing Of Callback Response

'C' - Completed The Processing Of Callback Response

The Generic IVR Adapter uses this field as one of the criteria in purging the TROUBLE_CALLBACKS table for 'old' records. Records with PROCESS_STATUS field = 'C' will be purged.

CALLBACK_DONE

Y

VARCHAR2(1)

Initially populated by the Callback Requests Data Flow as 'N', signifying that the callback is not yet done.

As soon as the external application successfully returns the callback response to the Generic IVR Adapter (using pr_trouble_callback_responses stored procedure), the field is updated to 'Y', signifying that the callback has been done.

Below is a list of valid values for this field.

'N' - Callback Has Not Been Done

'Y' - Callback Has Been Done

The Generic IVR Adapter uses this field as one of the criteria in purging the TROUBLE_CALLBACKS table for 'old' records. Records with CALLBACK_DONE field = 'Y' will be purged.

CAUSE_CODE

Y

VARCHAR2(32)

This is used to relay back to customers the cause of an outage when a callback is performed.

Populated by the Callback Requests Data Flow from JOBS.CAUSE when the useExternalCause rule is set to ‘yes’ in the SRS_RULES.

OUTAGE_DURATION

Y

NUMBER

Outage duration in seconds.

Populated by the Callback Requests Data with the difference between JOBS.RESTORE_TIME and JOBS.BEGIN_TIME.

CUSTOMER_COUNT

Y

NUMBER

Populated by the Callback Requests Data Flow from INC.USER_NAME.

CB_DETAIL_1

Y

VARCHAR2(80)

Populated by the Callback Requests Data Flow from a column in the PICKLIST_INFO_UPD_TR database table. Column name is configured in the IVR_ADAPTER_CONFIG database table.

CB_DETAIL_2

Y

VARCHAR2(80)

Populated by the Callback Requests Data Flow from a column in the PICKLIST_INFO_UPD_TR database table. Column name is configured in the IVR_ADAPTER_CONFIG database table.

CB_DETAIL_3

Y

VARCHAR2(80)

Populated by the Callback Requests Data Flow from a column in the PICKLIST_INFO_UPD_TR database table. Column name is configured in the IVR_ADAPTER_CONFIG database table.

CB_DETAIL_4

Y

VARCHAR2(80)

Populated by the Callback Requests Data Flow from a column in the PICKLIST_INFO_UPD_TR database table. Column name is configured in the IVR_ADAPTER_CONFIG database table.

Stored Procedure Parameters

pk_ccb.submit_call

Data structures and parameters of the PK_CCB.SUBMIT_CALL stored procedure:

SUBTYPE udf_field IS VARCHAR2(256);

TYPE input_call_rec IS RECORD (

call_source_id VARCHAR2(3),

service_point_id trouble_calls.cust_id%TYPE,

external_id trouble_calls.external_id%TYPE,

account_number trouble_calls.cust_key%TYPE,

trouble_code trouble_calls.cust_trouble_code%TYPE,

first_name trouble_calls.cust_first_name%TYPE,

last_name trouble_calls.cust_last_name%TYPE,

phone trouble_calls.cust_phone%TYPE,

phone_area trouble_calls.cust_phone_area%TYPE,

alt_phone trouble_calls.alternate_phone%TYPE,

priority trouble_calls.cust_priority%TYPE,

critical_flag trouble_calls.cust_critical%TYPE,

life_support_flag trouble_calls.cust_life_support%TYPE,

call_id trouble_calls.general_area%TYPE,

call_time trouble_calls.call_time%TYPE,

call_comment trouble_calls.call_comment%TYPE,

call_taker trouble_calls.usename%TYPE,

call_type trouble_calls.call_type%TYPE,

addr_building trouble_calls.addr_building%TYPE,

addr_street trouble_calls.addr_street%TYPE,

addr_cross_street trouble_calls.addr_street%TYPE,

addr_city_state trouble_calls.addr_city%TYPE,

drive_instr trouble_calls.drv_inst%TYPE,

meet_time trouble_calls.meet_time%TYPE,

meet_type trouble_calls.meet_type%TYPE,

group_by_name trouble_calls.group_by_name%TYPE,

device_id trouble_calls.cust_device_alias%TYPE,

meter_id trouble_calls.meter_id%TYPE,

trouble_queue trouble_calls.cust_trouble_queue%TYPE,

trouble_location trouble_calls.trouble_loc%TYPE,

x_coord trouble_calls.x_ref%TYPE,

y_coord trouble_calls.y_ref%TYPE,

appt_type trouble_calls.appt_type%TYPE,

appt_time trouble_calls.appt_time%TYPE,

appt_range trouble_calls.appt_range%TYPE,

callback_flag trouble_calls.callback_request%TYPE,

callback_before_time trouble_calls.callback_time%TYPE,

callback_late_flag trouble_calls.callback_late%TYPE,

intersection_cls trouble_calls.cust_device_cls%TYPE,

intersection_idx trouble_calls.cust_device_idx%TYPE,

cancel_flag trouble_calls.cust_call_cancel%TYPE,

update_flag trouble_calls.update_existing_inc%TYPE,

udf1 udf_field,

udf2 udf_field,

udf3 udf_field,

udf4 udf_field,

udf5 udf_field

);

-- new/updated trouble call

PROCEDURE submit_call (

p_call IN input_call_rec,

p_err_no OUT NUMBER,

p_err_msg OUT VARCHAR2

);

Description of the parameters of the PK_CCB.SUBMIT_CALL stored procedure.

Parameter Name

Parameter Type

Description

p_call.call_source_id

VARCHAR2(2)

Id unique to the call capture mechanism (always set to 2 for CCB, 3 for IVR - for example), Value will be prefixed to p_call.external_id field in this stored procedure. Used to allow NMS to maintain unique call ids (incidents.external_id) across multiple call taking systems submitting independent (overlapping) sets of external_ids. Generally an integer (to better support Interactive Voice Response systems) - but can be project specific.

p_call.service_point_id

VARCHAR2(64)

Service point id.

p_call.external_id

VARCHAR2(16)

Call external id unique ID from call capture system (CCB). To ensure uniqueness a given NMS implementation needs to agree on a fixed length field (12 characters for example).

p_call. account_number

VARCHAR2(30)

Customer account number.

p_call.trouble_code

VARCHAR2(32)

Call trouble code. Integer passed as a string - each character (0-9) indicates a specific selection (or 0 for non-selection) from each of 1 to 32 different trouble call categories. Project configurable.

p_call.first_name

VARCHAR2(75)

Customer first name or full name (if customer name is passed in a single field).

p_call.last_name

VARCHAR2(75)

Customer last name.

p_call.phone

VARCHAR2(32)

Customer phone number.

p_call.phone_area

VARCHAR2(8)

Customer phone area code.

p_call.alt_phone

VARCHAR2(32)

Alternative/callback phone number.

p_call.priority

VARCHAR2(4)

The same value as ces_customers.priority should be passed in. This is used to determine critical customer type.

p_call.critical_flag

VARCHAR2(1)

Critical customer (Y/N)

p_call.life_support_flag

VARCHAR2(1)

Life support flag (Y/N).

p_call.call_id

VARCHAR2(32)

Call identifier (for example, 911 call id) - mapped to general_area.

p_call.call_time

DATE

Call capture time from external call capture system

p_call.call_comment

VARCHAR2(255)

Comments

p_call.call_taker

VARCHAR2(32)

Call taker id.

p_call.call_type

VARCHAR2(8)

Call type.

CC&B should leave this field empty.

p_call.addr_building

VARCHAR2(10)

Building/block number.

p_call.addr_street

VARCHAR2(255)

Street address or name of the first intersection street.

p_call.addr_cross_street

VARCHAR2(255)

Name of the second intersection (cross) street.

p_call.addr_city_state

VARCHAR2(45)

City and (optionally) state.

p_call.drive_instr

VARCHAR2(180)

Driving instructions.

p_call.meet_time

DATE

Meet time.

p_call.meet_type

NUMBER

Meet action code.

Possible values:

•

0 - for non-meet calls

•

1 - create new meet

•

2 - reschedule existing meet

•

3- cancel existing meet

p_call.group_by_name

VARCHAR2(127)

Optional control zone name for fuzzy calls.

p_call.device_id

VARCHAR2(32)

Device alias.

p_call.meter_id

VARCHAR2(32)

Meter number.

p_call.trouble_queue

VARCHAR2(10)

Trouble queue (Tree Trimming, Underground, etc)

p_call.trouble_location

VARCHAR2(255)

Trouble location.

p_call.x_coord

NUMBER

X coordinate in the NMS electrical network model coordinate system (generally NOT lat/long). If not provided JMService will default to the coordinates for the supply_node from the point_coordinates table.

p_call.y_coord

NUMBER

Y coordinate - match for X coordinate above.

p_call.appt_type

NUMBER

Appointment type.

p_call.appt_time

DATE

Appointment time.

p_call.appt_range

NUMBER

Appointment time window in minutes.

p_call.callback_flag

NUMBER

Callback request flag.

•

0 - callback has not been requested

•

1 - callback has been requested.

p_call.callback_before_time

DATE

Callback requested before this time.

p_call.callback_late_flag

VARCHAR2(1)

Callback late ok flag (Y/N)

p_call.intersection_cls

NUMBER

If p_call.service_point_id is NOT null this field is ignored. If not null and p_call.service_point_d is null interpreted as att_street_intersection.h_cls. Used to help identify an intersection (when paired with p_call.intersection_idx)

p_call.intersection_idx

NUMBER

If p_call.service_point_id is NOT null this field is ignored. If not null and p_call.service_point_id is null interpreted as att_street_intersection.h_idx - to help identify an intersection (when paired with p_call.intersection_cls).

p_call.cancel_flag

VARCHAR2(1)

Call cancel flag (Y/N).

p_call.update_flag

NUMBER

If 0 then this is a new call, otherwise this is an update to an existing call.

p_call.udf1

VARCHAR2(255)

User-defined call field 1.

p_call.udf2

VARCHAR2(255)

User-defined call field 1.

p_call.udf3

VARCHAR2(255)

User-defined call field 1.

p_call.udf4

VARCHAR2(255)

User-defined call field 1.

p_call.udf5

VARCHAR2(255)

User-defined call field 1.

p_err_no

NUMBER

Error code.

In case of successful execution 0 is returned.

p_err_msg

VARCHAR2(200)

Internal error message.

pk_ccb.job_history

Stored procedure PK_CCB.JOB_HISTORY allows caller to retrieve list of jobs matching passed in search condition.

The following types of search conditions are supported:

•

Search for specific customer by service point id, premise id or account number.

•

Location-based search. Search for jobs at or nearby specified location. Location can be street intersection or street segment (block).

•

Fuzzy outage search. Search for fuzzy jobs by external id, call identifier, caller name or caller phone.

•

Custom search. To use custom search the stored procedure has to be modified by the project. Additional search parameters are passed in the 'p_custom' field.

CREATE OR REPLACE TYPE customer_search_obj AS OBJECT (

serv_point_id VARCHAR2(64),

premise_id NUMBER,

account_number VARCHAR2(30)

)

CREATE OR REPLACE TYPE location_search_obj AS OBJECT (

city VARCHAR2(200),

state VARCHAR2(30),

street1 VARCHAR2(200),

street2 VARCHAR2(200),

block_number NUMBER

)

CREATE OR REPLACE TYPE fuzzy_search_obj AS OBJECT (

external_id VARCHAR2(200),

call_id VARCHAR2(200),

caller_name VARCHAR2(200),

caller_phone VARCHAR2(200)

)

CREATE OR REPLACE TYPE custom_search_obj AS OBJECT (

field1 VARCHAR2(200),

field2 VARCHAR2(200),

field3 VARCHAR2(200),

field4 VARCHAR2(200),

field5 VARCHAR2(200)

)

TYPE nms_cursor IS REF CURSOR;

-- Get job history.

PROCEDURE job_history (

p_cust IN customer_search_obj,

p_loc IN location_search_obj,

p_fuzzy IN fuzzy_search_obj,

p_custom IN custom_search_obj,

p_num_days IN NUMBER,

p_jobs OUT nms_cursor,

p_err_no OUT NUMBER,

p_err_msg OUT VARCHAR2

);

Description of the parameters of the PK_CCB.JOB_HISTORY stored procedure.

Parameter Name

Parameter Type

Description

p_cust.serv_point_id

VARCHAR2(64)

Service point id.

p_cust.premise_id

NUMBER

Service location (premise id).

p_cust.account_number

VARCHAR2(30)

Customer account number.

p_loc.city

VARCHAR2(200)

City.

p_loc.state

VARCHAR2(30)

State.

p_loc.street1

VARCHAR2(200)

Street name. This field is used in both street intersection search and street segment search.

p_loc.street2

VARCHAR2(200)

Second street name for street intersection search.

p_loc.block_number

NUMBER

Block number for street segment search.

p_fuzzy.external_id

VARCHAR2(200)

Call external id.

p_fuzzy.call_id

VARCHAR2(200)

Call identifier (for example, id for 911 calls).

p_fuzzy.caller_name

VARCHAR2(200)

Caller name.

p_fuzzy.caller_phone

VARCHAR2(200)

Caller phone number.

p_custom.xxx

Implementation-defined search parameters.

p_cmp_days

NUMBER

If greater than 0 then switching plans completed within specified number of days in the past will be returned in addition to current and future switching plans.

p_jobs

nms_cursor

Returned jobs information.

p_err_no

NUMBER

Error code.

In case of successful execution 0 is returned.

p_err_msg

VERCHAR2(200)

Internal error message.

For each returned job the following information is included.

TYPE job_rec IS RECORD (

serv_point_id ces_customers.id%TYPE,

serv_point_addr ces_customers.address%TYPE,

event_idx jobs.event_idx%TYPE,

begin_time jobs.begin_time%TYPE,

est_rest_time jobs.est_rest_time%TYPE,

est_rest_time_source jobs.est_source%TYPE,

restore_time jobs.restore_time%TYPE,

cust_out jobs.num_cust_out%TYPE,

comments jobs.operator_comment%TYPE,

alarm_state jobs.alarm_state%TYPE,

alarm_state_desc te_valid_states.description%TYPE,

trouble_location jobs.display_name%TYPE,

status jobs.status%TYPE,

device_class jobs.devcls_name%TYPE,

trouble_code jobs.trouble_code%TYPE,

feeder_name jobs.feeder_name%TYPE,

cause jobs.cause%TYPE,

description jobs.description%TYPE,

referral_group jobs.referral_group%TYPE,

last_update_time jobs.last_update_time%TYPE,

udf1 udf_field,

udf2 udf_field,

udf3 udf_field,

udf4 udf_field,

udf5 udf_field

);

Field Name

Field Type

Description

serv_point_id

VARCHAR2(64)

Service point id.

serv_point_addr

VARCHAR2(200)

Service point address

event_idx

NUMBER

Event index.

begin_time

DATE

Outage begin time.

est_rest_time

DATE

Estimated restoration time (ERT).

est_rest_time_source

VARCHAR2(1)

ERT source.

Possible values:

•

N - no ERT

•

I - Initial ERT

•

C - manually entered ERT (from crew or NMS operator)

•

S - ERT calculated by Storm Management

•

O - ERT calculated by Storm Management (crew on-site)

•

P - Non-publisher ERT

•

G - ERT override is in effect

•

D - ERT delay is in effect

restore_time

DATE

Outage restoration time.

cust_out

NUMBER

Number of customers affected by the outage.

comments

VARCHAR2(255)

Operator's comment. Note some customers increase this to max allowed (4k).

alarm_state

VARCHAR2(32)

Outage state.

alarm_state_desc

VARCHAR2(80)

Description of the outage state.

trouble_location

VARCHAR2(255)

status

NUMBER

Job type.

Possible values:

•

0 - Fuzzy outage.

•

1 - Probable/predicted service outage.

•

2 - Probable/predicted device outage.

•

3 - Real service outage.

•

4 - Real device outage.

•

7 - Non-outage.

•

8 - Critical meet.

•

9 - Future meet.

•

10 - Confirmed service outage.

•

11 - Confirmed secondary outage.

•

13 - Probable/predicted momentary outage.

•

14 - Real momentary outage.

•

15 - Planned outage.

•

16 - Non-electric event.

•

17 - Master switching job.

•

18 - Fault current event.

device_class

VARCHAR2(32)

Outage device class name (e.g., fuse)

trouble_code

VARCHAR2(128)

Trouble code.

feeder_name

VARCHAR2(32)

Feeder name.

cause

VARCHAR2(32)

Outage cause.

description

VARCHAR2(128)

Job description.

referral_group

VARCHAR2(32)

Referral group.

last_update_time

DATE

Timestamp of the latest update to the outage record.

udf1

VARCHAR2(255)

Job user-defined field 1.

udf2

VARCHAR2(255)

Job user-defined field 2.

udf3

VARCHAR2(255)

Job user-defined field 3.

udf4

VARCHAR2(255)

Job user-defined field 4.

udf5

VARCHAR2(255)

Job user-defined field 5.

pk_ccb.call_history

Stored procedure PK_CCB.CALL_HISTORY will allow caller to retrieve list of calls matching search condition.

Following types of search conditions will be supported:

•

Search for calls for a specific customer by service point id, premise id or account number.

•

Location-based search. Search for calls at or nearby specified location. Location can be street intersection or street segment (block).

•

Fuzzy outage search. Search for fuzzy calls by external id, call identifier, caller name or caller phone.

Custom search. To use custom search the stored procedure has to be modified by the project. Additional search parameters are passed in the 'p_custom' field.

PROCEDURE call_history (

p_cust IN customer_search_obj,

p_loc IN location_search_obj,

p_fuzzy IN fuzzy_search_obj,

p_custom IN custom_search_obj,

p_num_days IN NUMBER,

p_calls OUT nms_cursor,

p_err_no OUT NUMBER,

p_err_msg OUT VARCHAR2

);

For each returned call the following information is included.

-- call history record

TYPE call_rec IS RECORD (

external_id incidents.external_id%TYPE,

call_id incidents.general_area%TYPE,

serv_point_id incidents.cid%TYPE,

call_time incidents.input_time%TYPE,

address incidents.address%TYPE,

short_desc incidents.short_desc%TYPE,

comments incidents.op_comment%TYPE,

call_taker incidents.user_name%TYPE,

cust_name incidents.customer_name%TYPE,

status incidents.active%TYPE,

udf1 udf_field,

udf2 udf_field,

udf3 udf_field,

udf4 udf_field,

udf5 udf_field

);

Field Name

Field Type

Description

external_id

VARCHAR2(16)

Call external id.

call_id

VARCHAR2(32)

Call identifier (for example, id for 911 calls).

serv_point_id

VARCHAR2(64)

Service point id.

call_time

DATE

Call time.

Address

VARCHAR2(255)

Address for the call.

short_desc

VARCHAR2(256)

Trouble code.

Comments

VARCHAR2(255)

Comments.

call_taker

VARCHAR2(32)

Call taker id.

cust_name

VARCHAR2(75)

Customer/caller name.

Status

VARCHAR2(1)

Call status. Possible values (other values can exist in NMS but they would not be returned by this procedure):"Y - active call "N - inactive/restored call "C - canceled call "E - call belongs to canceled job

udf1

VARCHAR2(255)

Call user-defined field 1.

udf2

VARCHAR2(255)

Call user-defined field 2.

udf3

VARCHAR2(255)

Call user-defined field 3.

udf4

VARCHAR2(255)

Call user-defined field 4.

udf5

VARCHAR2(255)

Call user-defined field 5.

pk_ccb.switching_history

The stored procedure PK_CCB.SWITCHING_HISTORY allows a caller to retrieve a list of current, future, and (optionally) past switching plans affecting a given customer.

.

PROCEDURE switching_history (

p_cust IN customer_search_obj,

p_custom IN custom_search_obj,

p_num_days IN NUMBER,

p_sw_plans OUT nms_cursor,

p_err_no OUT NUMBER,

p_err_msg OUT VARCHAR2

);

Description of the parameters of the PK_CCB.SWITCHING_HISTORY stored procedure.

Parameter Name

Parameter Type

Description

p_cust.serv_point_id

VARCHAR2(64)

Service point id.

p_cust.premise_id

NUMBER

Service location (premise id).

p_cust.account_number

VARCHAR2(30)

Customer account number.

p_custom

Implementation-defined search parameters.

p_sw_plans

nms_cursor

Returned switching plan information.

p_err_no

NUMBER

Error code

In case of successful execution 0 is returned.

p_err_msg

VARCHAR2(200)

Error message.

For each returned switching plan following information is included.

-- switching plan record

TYPE switching_plan_rec IS RECORD (

plan_class swman_sheet_cls.switch_sheet_type%TYPE,

plan_number swman_sheet.switch_sheet_idx%TYPE,

start_date swman_sheet.start_date%TYPE,

end_date swman_sheet.finish_date%TYPE,

device_alias swman_sheet.device_alias%TYPE,

state te_valid_states.state_name%TYPE,

work_district swman_sheet_extn.string_value%TYPE,

work_location swman_sheet_extn.string_value%TYPE,

work_description swman_sheet_extn.string_value%TYPE,

serv_point_id ces_customers.id%TYPE,

serv_point_addr ces_customers.address%TYPE,

udf1 udf_field,

udf2 udf_field,

udf3 udf_field,

udf4 udf_field,

udf5 udf_field,

udf6 udf_field,

udf7 udf_field,

udf8 udf_field,

udf9 udf_field,

udf10 udf_field

);

Field Name

Field Type

Description

plan_class

VARCHAR2(32)

Switching plan type (planned, emergency, ….).

plan_number

NUMBER

Switching plan number.

start_date

DATE

Switching plan start date.

end_date

DATE

Switching plan end date.

State

VARCHAR2(32)

Switching plan state.

work_district

VARCHAR2(500)

work_location

VARCHAR2(500)

work_description

VARCHAR2(500)

serv_point_id

VARCHAR2(64)

Service point id.

serv_point_addr

VARCHAR2(200)

Service point address

pk_ccb.trouble_code_config

Stored procedure PK_CCB.TROUBLE_CODE_CONFIG allows caller to retrieve list of trouble codes configured in the Oracle Utilities Network Management System.

PROCEDURE trouble_code_config (

p_trouble_codes OUT nms_cursor,

p_err_no OUT NUMBER,

p_err_msg OUT VARCHAR2

);

Field Name

Field Type

Description

p_trouble_codes

nms_cursor

Returned trouble code information.

p_err_no

NUMBER

Error code

In case of successful execution 0 is returned.

p_err_msg

VARCHAR2(200)

Error message

For each returned trouble code following information is included:

-- trouble code configuration record

TYPE trouble_code_rec IS RECORD (

group_name srs_trouble_codes.group_name%TYPE,

group_order srs_trouble_codes.group_order%TYPE,

code_name srs_trouble_codes.code_name%TYPE,

code_num srs_trouble_codes.code_num%TYPE,

short_desc srs_trouble_codes.short_desc%TYPE,

description srs_trouble_codes.description%TYPE

);

Field Name

Field Type

Description

group_name

VARCHAR2(20)

Trouble code group name

group_order

NUMBER

Trouble code group order

code_name

VARCHAR2(40)

Trouble code name

code_num

NUMBER

Trouble code number within its group

short_desc

VARCHAR2(25)

Short description of the trouble code

description

VARCHAR2(70)

Long description of the trouble code

pr_trouble_calls

The Generic IVR Adapter provides the pr_trouble_calls procedure to be used by the external application to insert trouble calls in the TROUBLE_CALLS table. Refer to Trouble Calls for Data Flow details.

Below is a high level description of what is done inside the stored procedure

•

Upon invoking the stored procedure, the p_premise_id parameter is used to query the CES_CUSTOMERS table (via the SERV_LOC_ID field) to retrieve the ACCOUNT_NUMBER, H_CLS and H_IDX fields of the said table. The value of these fields is placed in the corresponding columns of the TROUBLE_CALLS table.

•

Other parameter values are inserted to corresponding fields on the TROUBLE_CALL table.

•

Several TROUBLE_CALLS columns will have default value when no parameter value is supplied.

•

Should there be an error in the record insert, an Oracle error is returned.

Note : If the given premise id has multiple accounts associated with it, only one account (i.e., the first account) is used.

Below are details about each parameter of the pr_trouble_calls stored procedure. Note that the field name column indicates the corresponding column that is populated in the TROUBLE_CALLS table.

Parameters

Parameter

Direction

Data Type

Field Name

Comment

p_premise_id

In

VARCHAR2

PREMISE_ID

The value is inserted as is.

p_trouble_code

In

VARCHAR2

TROUBLE_CODE

Defaults to ‘1’ followed by a certain number of ‘0’. If no value was supplied. The total length of the string is the total number of distinct groups in the SRS_TROUBLE_CODES table.

p_callback_ind

In

VARCHAR2

CALLBACK_INDICATOR

The possible values are as follows:

‘0’ - callback not requested

‘1’ - callback requested

Defaults to ‘1’ if no value is supplied.

‘Y’ is translated to ‘1’.

‘N’ is translated to ‘0’.

p_call_time

In

DATE

CALL_TIME

Defaults to the database system date if no value is supplied

p_call_taker_id

In

VARCHAR2

CALL_TAKER_ID

The value is inserted as is.

p_alternate_phone

In

VARCHAR2

ALTERNATE_PHONE

The value is inserted as is.

p_customer_comment

In

VARCHAR2

CUSTOMER_COMMENT

The value is inserted as is.

p_customer_phone

In

VARCHAR2

CUSTOMER_PHONE

The value is inserted as is.

p_customer_name

In

VARCHAR2

CUSTOMER_NAME

The value is inserted as is.

p_customer_address

In

VARCHAR2

CUSTOMER_ADDRESS

The value is inserted as is.

p_customer_city_state

In

VARCHAR2

CUSTOMER_CITY_STATE

The value is inserted as is.

p_customer_priority

In

VARCHAR2

CUSTOMER_PRIORITY

The value is inserted as is.

p_external_id

In

VARCHAR2

EXTERNAL_ID

The value is inserted as is.

p_device_alias

In

VARCHAR2

DEVICE_ALIAS

The value is inserted as is.

p_check_cutoff_ind

In

VARCHAR2

CHECK_CUTOFF_IND

The possible values are as follows:

‘Y’ - check if the customer is disconnected

‘N’ - do not perform checking.

Defaults to ‘N’ if no value is supplied

p_callback_late_ind

In

VARCHAR2

CALLBACK_LATE_IND

The possible values are as follows:

‘Y’ - It is OK to call back even when it is already late.

‘N’ - It is not OK to call back when it is already late.

Defaults to ‘N’ if no value is supplied

p_callback_before_time

In

DATE

CALLBACK_BEFORE_TIME

The value is inserted as is.

p_trouble_queue

In

VARCHAR2

TROUBLE_QUEUE

The value is inserted as is.

p_meter_id

In

VARCHAR2

METER_ID

The value is inserted as is.

p_supply_id

In

NUMBER

SUPPLY_ID

The value is inserted as is.

p_cust_phone_area

In

VARCHAR2

CUST_PHONE_AREA

The value is inserted as is.

p_cust_last_name

In

VARCHAR2

CUST_LAST_NAME

The value is inserted as is.

p_general_area

In

VARCHAR2

GENERAL_AREA

The value is inserted as is.

p_cust_order_num

In

VARCHAR2

CUST_ORDER_NUM

The value is inserted as is.

p_drv_inst

In

VARCHAR2

DRV_INST

The value is inserted as is.

p_cust_life_support

In

VARCHAR2

CUST_LIFE_SUPPORT

The value is inserted as is.

p_cust_call_cancel

In

VARCHAR2

CUST_CALL_CANCEL

The value is inserted as is.

p_short_desc

In

VARCHAR2

SHORT_DESC

The value is inserted as is.

p_addr_building

In

VARCHAR2

ADDR_BUILDING

The value is inserted as is.

p_meet_time

In

DATE

MEET_TIME

The value is inserted as is.

p_meet_type

In

NUMBER

MEET_TYPE

The value is inserted as is.

p_groupable

In

NUMBER

GROUPABLE

The value is inserted as is.

p_clue

In

NUMBER

CLUE

The value is inserted as is.

p_combine_pri

In

NUMBER

COMBINE_PRI

The value is inserted as is.

p_cust_status

In

NUMBER

CUST_STATUS

The value is inserted as is.

p_cust_intr_x

In

NUMBER

CUST_INTR_X

The value is inserted as is.

p_cust_intr_y

In

NUMBER

CUST_INTR_Y

The value is inserted as is.

p_cust_intersect_cls

In

NUMBER

CUST_INTERSECT_CLS

The value is inserted as is.

p_cust_intersect_idx

In

NUMBER

CUST_INTERSECT_IDX

The value is inserted as is.

p_cust_intersect_ncg

In

NUMBER

CUST_INTERSECT_NCG

The value is inserted as is.

p_update_existing_inc

In

NUMBER

UPDATE_EXISTING_INC

The value is inserted as is.

p_fuzzy_ncg_cls

In

NUMBER

FUZZY_NCG_CLS

The value is inserted as is.

p_fuzzy_ncg_idx

In

NUMBER

FUZZY_NCG_IDX

The value is inserted as is.

p_group_by_name

In

VARCHAR2

GROUP_BY_NAME

The value is inserted as is.

p_cust_critical

In

VARCHAR2

CUST_CRITICAL

The value is inserted as is.

p_related_evt_cls

In

NUMBER

RELATED_EVT_CLS

The value is inserted as is.

p_related_evt_idx

In

NUMBER

RELATED_EVT_IDX

The value is inserted as is.

p_related_evt_app

In

NUMBER

RELATED_EVT_APP

The value is inserted as is.

p_x_ref

In

NUMBER

X_REF

The value is inserted as is.

p_y_ref

In

NUMBER

Y_REF

The value is inserted as is.

p_call_type

In

VARCHAR2

CALL_TYPE

The value is inserted as is.

p_cust_phone_update

In

VARCHAR2

CUST_PHONE_UPDATE

The value is inserted as is.

p_trouble_loc

In

VARCHAR2

TROUBLE_LOC

The value is inserted as is.

p_appt_type

In

VARCHAR2

APPT_TYPE

The value is inserted as is.

p_appt_time

In

DATE

APPT_TIME

The value is inserted as is.

p_appt_range

In

NUMBER

APPT_RANGE

The value is inserted as is.

p_cust_device_ncg

In

NUMBER

CUST_DEVICE_NCG

The value is inserted as is.

p_cust_device_partition

In

NUMBER

CUST_DEVICE_PARTITION

The value is inserted as is.

p_err_premise_id

Out

VARCHAR2

VARCHAR2(80)

The erroneous premise ID input parameter

p_err_oracle_error

Out

VARCHAR2

VARCHAR2(80)

Oracle’s error message.

Note: The pr_trouble_calls stored procedure does not require a call status parameter from the user to insert in the TROUBLE_CALLS stored procedure. Each time the stored procedure inserts trouble calls in the TROUBLE_CALLS table, the CALL_STATUS field is always ‘N’, signifying that it is a new trouble call.

pr_trouble_callback_requests

Below is a high level description of what is done inside the stored procedure

•

From the TROUBLE_CALLBACKS table, a list of new callback requests is created. These are the TROUBLE_CALLBACKS records whose PROCESS_STATUS field is ‘N’ (New) and CALLBACK_DONE field is ‘N’ (No).

•

The list is captured within the stored procedure as a database cursor and returned to the calling application.

•

The PROCESS_STATUS field of the records in the list is updated from ‘N’ (New) to ‘I’ (In Progress).

Note: Refer to the Data Flow Steps of the Callback Requests Data Flow on how the TROUBLE_CALLBACKS table is populated.

Parameter

Parameter

Direction

Cursor

p_callback_requests

In/Out

CALLBACK_CURSOR

Cursor Definition

Below are the fields of the CALLBACK_CURSOR. Take note that the CALLBACK_CURSOR is defined as a weakly typed cursor.

Field Name from the Cursor

Data Type

Field Name from TROUBLE_CALLBACKS

Comments

EVENT_CLS

NUMBER(38)

TCB.EVENT_CLS

Event class

EVENT_IDX

NUMBER(38)

TCB.EVENT_IDX

Event index

INCIDENT_NUMB

NUMBER(38)

TCB.INCIDENT_NUMB

Incident number

PREMISE_ID

VARCHAR2(50)

TCB.PREMISE_ID

Premise id

CUSTOMER_NAME

VARCHAR2(75)

TCB.CUSTOMER_NAME

Customer name

CUSTOMER_PHONE

VARCHAR2(38)

TCB.CUSTOMER_PHONE

Customer phone

CUSTOMER_ADDRESS

VARCHAR2(255)

TCB.CUSTOMER_ADDRESS

Customer address

ALTERNATE_PHONE

VARCHAR2(38)

TCB.ALTERNATE_PHONE

Customer alternate phone number

TROUBLE_CODE

VARCHAR2(32)

TCB.TROUBLE_CODE

This is the trouble code (e.g., ‘10000000’) of the incident rather than the clue (e.g., 'Out'). 'Out' is short for 'All Power Out'.

SHORT_DESCRIPTION

VARCHAR2(128)

TCB.SHORT_DESCRIPTION

This is the clue (e.g., 'Out') of the incident rather than the trouble code (e.g., ‘10000000’). 'Out' is short for 'All Power Out'.

CUSTOMER_COMMENT

VARCHAR2(255)

TCB.CUSTOMER_COMMENT

Call-taker Comments. Comments provided by the customer or call-taker about the incident.

INCIDENT_TIME

DATE

TCB.INCIDENT_TIME

Input time of call. The input time of the incident.

EXTERNAL_ID

VARCHAR2(16)

TCB.EXTERNAL_ID

Unique call identifier. The unique identifier for the incident.

CALL_TAKER_ID

VARCHAR2(32)

TCB.CALL_TAKER_ID

Call-taker user name. The name of the call-taker or interface that created the call.

CALLBACK_LATE

VARCHAR2(1)

TCB.CALLBACK_LATE

The possible values are as follows:

‘Y’ - It is OK to call back even when it is already late.

‘N’ - It is not OK to call back when it is already late.

CALLBACK_LATE_TIME

DATE

TCB.CALLBACK_LATE_TIME

CALLBACK_REASON

VARCHAR2(100)

TCB.CALLBACK_REASON

This will default to 'OMS'.

CAUSE_CODE

VARCHAR2(32)

TCB.CAUSE_CODE

Cause code of the event related to the callback.

pr_trouble_callback_responses

Below is a high level description of what is done inside the stored procedure

•

Upon receiving the input parameter values, the stored procedure verifies if either the p_incident_numb input parameter or the p_external_id input parameter was supplied. If both were supplied, the p_incident_numb parameter takes precedence.

•

The stored procedure validates if the p_callback_status input parameter has a valid value. The valid values are ‘F’ (not restored), ‘R’ (restored) and ‘N’ (cancel callback).

•

The stored procedure verifies that there is a unique combination of p_incident_numb and p_premise_id OR a unique combination of p_external_id and p_premise_id on the TROUBLE_CALLBACKS table, whichever among p_incident_numb or p_external_id was supplied.

•

The TROUBLE_CALLBACKS table is updated for the p_incident_numb and p_premise_id combination OR the p_external_id and p_premise_id combination. The following fields are updated:

•

The callback's CALLBACK_DONE field to 'Y' signifying that the callback was already done.

•

The callback's CALLBACK_TIME field with provided p_callback_time stored procedure parameter. CALLBACK_TIME field defaults to the system date if no value was provided.

•

The callback's CALLBACK_STATUS field with the appropriate callback response code.

•

Should any of these steps fail, the stored procedure exits and returns the appropriate error.

Note: Refer to the Data Flow Steps of the Callback Response Data Flow on how the TROUBLE_CALLBACKS table is populated.

Parameters

Parameter

Direction

Data Type

Field Name

Comments

p_incident_numb

In

NUMBER

INCIDENT_NUMB

Incident Number. Either this or the p_external_id parameter has to be supplied

p_external_id

In

VARCHAR2

EXTERNAL_ID

External Id. Either this or the p_incident_numb parameter has to be supplied

p_premise_id

In

VARCHAR2

PREMISE_ID

Premise Id.

p_callback_status

In

VARCHAR2

CALLBACK_STATUS

The valid values are as follows:

'F' - Not Restored Callback

'R' - Restored Callback

'N' - Cancel Callback, unable to get a response

p_callback_time

In

DATE

CALLBACK_TIME

Defaulted to the system date if no value was supplied

p_err_incident_numb

Out

NUMBER

The erroneous incident number input parameter

p_err_external_id

Out

VARCHAR2

The erroneous external ID input parameter

p_err_premise_id

Out

VARCHAR2

The erroneous premise ID input parameter

p_err_oracle_error

Out

VARCHAR2

Oracle’s error message

pr_customer_event_details

The Generic IVR Gateway provides the pr_customer_event_details stored procedure that gives the event details of an outage given the customer premise. Refer to the data flow detail for Callback Requests .

Below is a high level description of what is done inside the stored procedure.

•

The stored procedure tries to get the latest event for the given premise ID (p_in_premise_id input parameter).

Parameters

Below are details about each parameter of the pr_customer_event_details stored procedure.

Parameter

Direction

Data Type

Comments

p_in_premise_id

In

VARCHAR2

Premise ID input parameter with a corresponding entry in CES_CUSTOMERS.SERV_LOC_ID

p_out_event_class

Out

NUMBER

Event class output parameter

p_out_event_index

Out

NUMBER

Event index output parameter

p_out_outage_status

Out

VARCHAR2

This is an abbreviation of the current state of the event, for instance, 'NEW', 'ASN', 'CMP', etc.

p_ out_outage_start_time

Out

DATE

The time of the lead call of the job.

p_ out_first_dispatch_time

Out

DATE

The time the first crew was dispatched

p_ out_est_restore_time

Out

DATE

The last estimate of restoration time.

p_ out_est_restore_time_src

Out

VARCHAR2

The source of the ERT of the event.

Possible values are as follows:

'N' - none (no ERT)

'S' - Storm Management

'P' - Storm Management "non-published global ERT"

'O' - Storm Management "onsite ERT"

'G' - Storm Management "published global ERT"

D' - Storm Management "published global ERT delay"

'C' - User-entered (assumed to have been provided by the crew)

'I' - Initial default ERT

'M' - Storm Management ERT is further in the future then allowed

p_ out_crew_arrival_time

Out

DATE

The time when the crew arrived on location

p_ out_completion_time

Out

DATE

The time the event has been completed. This implies power restoration, the crew(s) are gone, and the event is completed in the Event Details window.

p_ out_restoration_time

Out

DATE

The time that power has been restored.

p_ out_case_note

Out

VARCHAR2

Comment

p_ out_status

Out

NUMBER

Condition status

p_ out_active

Out

VARCHAR2

Possible values are as follows:

'Y' - Outage Is Active

'N' - Outage Is Not Active

p_out_alias

Out

VARCHAR2

The device alias.

P_out_event_type

Out

VARCHAR2

Possible values are as follows:

OUT

NON

MEET

PLAN

SWP

P_out_feeder_name

Out

VARCHAR2

The name of the feeder.

P_out_cause

Out

VARCHAR2

The cause of the outage if the SRS Rule useExternalCause is on.

P_out_num_calls

Out

NUMBER

The number of calls.

P_out_num_cust_out

Out

NUMBER

The number of customers out.

P_err_premise_id

Out

VARCHAR2

P_err_oracle_error

Out

VARCHAR2

SRSInput Testing Utility Command Line Options

SRSInput adds raw file incidents into SRSService.

Usage

SRSinput [-max number] [-ivr] [-time] [-blanksok] [-package number]

[-interval seconds] [-divide number] [-tilde] [-debug]

-input filename

Options/Arguments:

Option

Description

-max number

Maximum number of calls to enter.

-ivr

Write calls to trouble_calls table for IVR adapter.

-time

Add input_time with current time.

-blanksok

Blank lines in call record are acceptable.

-package number

Number of calls to send to JMS at a time. Default: 10.

-interval seconds

Seconds to delay between calls.Defaults to 5. Also, it can take floating point values such as 2.5 to sleep 2 and a half seconds between call batches.

-divide number

Number to divide <WAIT> times by.

-tilde

Use the tilde in column 0 as a call separator.

-debug

Enable runtime debugging.

-input filename

Filename containing trouble call data. Required.

Note: If the -ivr option is not used, SRSinput sends calls to JMService via the C++ API.

Terminology

The following terms and acronyms are relevant to this specification

OMS

Outage Management System

NMS

Network Management System

CIS

Customer Information System

IVR

Interactive Voice Response

Generic IVR Adapter

A Unix application that generally executes on the OMS server machine. It supports the Trouble Call, Callback Request, and Callback Response Data Flows.

SMService

System Monitor Service. SMService monitors the core processes in the system, essentially the services and interfaces.

JMService

Job Management Service. The Oracle Utilities Network Management System call processing and outage prediction engine.

ODService

Object Directory Service. ODService improves performance of the Oracle Utilities Network Management System by caching large amounts of device information that is likely to be requested by applications. This caching allows the requests to be handled very quickly without directly accessing the database.

Isis

Clients access services and tools through a central concurrency management and messaging system called Isis. Isis is a real-time implementation of message oriented middleware and comprises the backbone of the system, providing access to the server for each client and the communication required between tools and services. Isis delivers the organized information to the client applications.

SmallWorld GIS Adapter

This chapter describes the Oracle developed Smallworld data adapter. Since both the Oracle Utilities Network Management System and the Smallworld are highly configurable, there are many configuration options for the model build interface, but this document focuses only on the Smallworld Data Adapter. A related document, "Oracle Utilities Network Management System Model Build Interface" exists to provide details of Smallworld - Oracle Utilities Network Management System interface.

Model Build Process Overview

GIS to Oracle Utilities Network Management System integration is a multi-step process that generates an operational topological representation of the existing GIS database for use by the Oracle Utilities Network Management System. This process is referred to as the model build interface. During the model build interface, a single spatial grouping of GIS objects (known as a partition) is processed by the Oracle Utilities Network Management System model build engine before incorporating the partition data into the OMS data model. An electrical circuit (feeder) or polygon feature, such as a service territory boundary, can be used to define a partition. The Oracle Utilities Network Management System model build engine processes partitions in three stages before committing it to the OMS operational data model: 1) GIS data extraction, 2) model pre-processing and 3) data import into Oracle Utilities Network Management System.

The Smallworld Data Adapter extracts geospatial data in Oracle's vendor-neutral model preprocessing file format (MP file). Geospatial data in Smallworld is stored in a number of geographic data and attribute data tables. The GIS stores and renders the geospatial data as a contiguous map. For performance and architectural reasons, Oracle Utilities Network Management System requires GIS data to be brought into the system as smaller chunks referred as partitions.

An electrical circuit (feeder) or polygon feature, such as a service territory boundary could be used to define a partition. Landbase features should be separated from electrical features because this data is inherently different, and because landbase data is typically more static.

Oracle's Smallworld Data Adapter is able to:

•

Extract the data by predefined partitions.

•

Extract the electric facility data by the feeder; i.e. when a feeder is extracted, all the devices that take part in forming the feeder (i.e. electrically connected) will be extracted in a single MP file.

•

Extracts Landbase features by predefined polygon boundary in a single MP file.

In order to minimize the data extraction and model build data volume, the extract is capable of identify the changed partitions since the last data extract operation.

Adapter Documentation

Oracle Utilities Network Management System SmallWorld adapter documentation is included in the SmallWorld adapter release package as a Microsoft Office Word document.

ESRI ArcGIS 9.x Adapter

Adapter Overview

Oracle Utilities Network Management System model interface and the ArcGIS 9.x are highly configurable, there are many configuration options. This document includes a discussion of the choices and alternatives. A related document exists to provide project-specific configuration information.

The Oracle Utilities Network Management System receives data from the ESRI ArcGIS 9.x to populate its topology model and provide graphic views of the electrical network and landbase. This is done as required using the ArcGIS:Oracle Utilities Network Management System interface to keep the Oracle Utilities Network Management System current with the network and landbase being maintained in the GIS.

The interface is one-way: updates from the GIS flow to Oracle Utilities Network Management System for processing. The feedback to the GIS system is typically done using red lining on a map.

Adapter Documentation

Oracle Utilities Network Management System ArcGIS 9.x adapter documentation is included in the ArcGIS 9.x adapter release package as a Microsoft Office Word document.

Intergraph G/Electric Adapter

This chapter includes the following topics:

•

Introduction

•

Adapter Capabilities

•

Programs and Files

•

Installing the G/Electric Data Adapter

•

Adapter Configuration

•

Third Party Products

•

Executing the Adapter

•

GIS Data Requirements

•

Uninstalling the G/Electric Data Adapter

Introduction

GIS to Oracle Utilities Network Management System integration is a multi-step process that generates an operational topological representation of the existing GIS database for use by and display in the Oracle Utilities Network Management System. This process is referred to as the model build. A single spatial grouping of GIS objects (known as a partition) is processed by the Oracle Utilities Network Management System model build engine before incorporating the partition data into the Oracle Utilities Network Management System electrical model. An electrical circuit (feeder) or polygon feature, such as a service territory boundary, can be used to define a partition. The Oracle Utilities Network Management System model build engine processes partitions in three stages before committing it to the Oracle Utilities Network Management System operational electrical model: 1) GIS data extraction, 2) model pre-processing and 3) data import into Oracle Utilities Network Management System.

The G/Electric Adapter extracts geospatial data in Oracle’s vendor-neutral model preprocessing file format (MP file). Geospatial data in G/Electric is stored in a number of geographic data and attribute data tables. The GIS stores and renders the geospatial data as a contiguous map. For performance and architectural reasons, Oracle Utilities Network Management System requires GIS data to be brought into the system as smaller chunks referred as partitions.

An electrical circuit (feeder) or polygon feature, such as a service territory boundary can be used to define a partition. Land base features must be separated from electrical features because this data is inherently different, and because land base data is typically more static.

Oracle’s G/Electric Adapter is able to:

•

Extract the data by predefined partitions.

•

Extract the electric facility data by feeder; i.e. when a feeder is extracted, all the devices that take part in forming the feeder (i.e., are electrically connected) will be extracted into a single MP file.

•

Extracts land base features by predefined polygon boundary in a single MP file.

In order to minimize the data extraction and model build data volume, the extract is capable of identifying the changed partitions since the last data extract operation.

Adapter Overview

The Adapter makes use of G/Electric GIS metadata to access the G/Electric GIS features. The Adapter utilizes default values as set in an accompanying Microsoft Access database, which has the same name as the executable (GElec2Oracle) and resides in the same subdirectory. This required database is referred to as the "application configuration" database.

The Adapter can be installed and run on any personal computer with Windows XP or Windows 2000 as the supported platforms.

There are two methods of invoking the Adapter:

•

Non-interactively by a command line with parameters

•

Interactively with a Graphical User Interface (GUI)

The program can be launched in non-GUI mode from an operating system command prompt with command line parameters. The user can either use the defaults as set in the application configuration database or override them with passed parameters. As such, the program can be scheduled for "silent" launch as a Windows scheduled task. Note that because this type of launch is "silent" and does not make use of a GUI, feedback is usually not provided to the workstation screen unless an error occurs.

The program can be launched from the workstation desktop or pull down menu. Using the GUI, the user can interactively control what data is extracted, what extract method is to be used, the type of data to extract, and the name of the output directory. The user is also shown a status area, which includes progress bars and messages for monitoring the progress of the overall work order and the specific partition currently being extracted.

The remainder of this document describes the capabilities of the Adapter, how to install and configure it, and how to run it.

Adapter Capabilities

The Adapter is a partition-based tool that extracts objects and features as selected by their geographic location (i.e., based on the feeder name or partition to which they belong).

Optionally, the Adapter can be used to detect changes in a GIS database, thereby automatically flagging partitions for extraction. Automated change detection by the Adapter is based on the G/Electric modification log table where the Adapter attempts to identify changed feeders or partition polygons since the last successful extract (based on creation and modification dates). The change detect functionality is an optional automated mechanism for queuing partitions that contain objects and features that have been either changed, added, or deleted since the last extract.

On extraction, the Adapter retrieves:

•

Partition details.

•

Features. For each feature, the following are extracted:

•

Feature object class and identifier

•

Connectivity

•

Geometric (graphic) components including a feature annotation (text) component

•

Rows and attributes for all the non-graphic components of the feature, including annotation.

The Adapter produces output in a work order folder containing files in Oracle Utilities Network Management System Model Preprocessor (".mp") format and a log file of informational, warning, and error messages.

The details of these topics are discussed below.

Partition Details

The Adapter generates a "partition section" based on the geometry of the selection or tile. It uses the specified feature class as the class name for the partition and an attribute (e.g., "TileID") for the partition’s name.

Feature Extraction

The Adapter generates Add records for each feature. The Add feature records list the feature, its topology, diagram records, and attribute records

Object Identifier

The Adapter uses the feature class name and feature ID to identify an object. For example, "Switch 24". Note the feature ID is unique within the feature class.

Connectivity

The Adapter determines the connected (or networked) objects by analyzing the G/Electric connectivity component. The connectivity (topology) is established using the Node1 and Node2 ID attribute, a unique index number in the connectivity component.

The Oracle Utilities Network Management System AttTopoBuild program uses the GIS provided Port (Node) information to generate topology.

Geometric Information

The Adapter determines the geometry of the object and uses it to extract the coordinates scale, height, angle, and justification of the object.

Coded Value Look Up

In G/Electric there are no coded values, instead it provides the Value List for feature attributes for which user input should be limited to the system provided values. Because there are no coded values in the GIS database, the Adapter does not need to perform any coded value look up.

Names Containing Space Characters

It is possible for GIS feeder names or class user names to contain spaces (e.g., "Overhead Line). However, the Oracle Utilities Network Management System model build process does not recognize or accept class names with spaces, so a conversion must be made.

The accepted convention is that all spaces be substituted with underscores (e.g., "_"). Therefore, if source data class names have spaces in them, the final output model preprocessor (.MP) files will have underscores substituting the spaces. An example would be a class named "Overhead Line". The ADD statement in the extract output file will show the name "Overhead_Line" instead.

Node Reduction

The interface program does not use a node reduction algorithm to reduce the number of nodes.

Partitions with Index Maps

The G/Electric GIS database is a continuous map. For performance reasons, Oracle Utilities Network Management System requires maps to be tiled, each tile corresponding to an Oracle Utilities Network Management System partition.

The electrical features are extracted by using the feeder names associated with a source device or listed in the Connectivity table. All the electric devices taking part in forming a feeder are extracted in single MP file. The Adapter also extracts electrical device owner features such as structure and poles in the same MP file. The feeder name is used to name the extracted MP file.

The spatial data extract requires a GIS polygon feature to extract the data. These polygon partitions can be any size and are not required to be uniform. The optimal sized partition polygon contains less than 5,000 objects (devices, background text, and background graphics). For example, in dense urban areas of the electrical network, smaller size partition polygons can be used. The Adapter can use one of the existing polygon boundary classes or users can define a new Oracle Utilities Network Management System specific polygon boundary class to define the partition polygon.

A unique text attribute (e.g., "GridID") of the polygon partition feature class will be used to name the extracted MP Files that will become the name of the Oracle Utilities Network Management System partition.

Programs and Files

The Oracle Utilities Network Management System G/Electric Data Adapter program, configuration database, help file, and other associated files, are supplied in a standard self-extracting Oracle Utilities Network Management System G/Electric Data Adapter Installer. The following files will be installed in the user-selected installation directory. Default installation directory is "C:\Program Files\OracleTUGBU\Oracle GElectric data Extractor".

•

Oracle Utilities Network Management System G/Electric Data Adapter Program (GElec2Oracle.exe)

•

Oracle Utilities Network Management System G/Electric read me file. (readme.rtf)

•

Oracle_NMS_GElectric_Extractor_User_Guide.pdf

•

Oracle_NMS_GElectric Extractor Installation Guide.pdf

The following reference files will be copied to the Reference subdirectory under the user-selected installation directory:

•

Oracle Utilities Network Management System G/Electric Data Adapter On-line Help document (gelec2spl.chm)

•

Oracle Utilities Network Management System G/Electric Data Adapter Configuration Database (GElec2Oracle.mdb)

•

Oracle Utilities Network Management System G/Electric Data Adapter custom scrip to create the v_spl_fidfno View object (create_spl_view.sql)

G/Electric Data Adapter Installation Phases

There are four phases to installing the Adapter: application installation, Adapter configuration, Oracle client configuration, and testing:

•

Install the G/Electric Data Adapter

•

Populate the Adapter configuration database

•

Configure the Oracle SQL*Net Client

•

Test the Adapter

Minimum System Requirements

The PC is required to meet these minimum system requirements to install the G/Electric Data Adapter.

Processor

Pentium® III 800 MHz minimum

Operating system

Microsoft Windows 2000 or Microsoft XP

Internet Explorer

Obtain and install the appropriate language version of Internet Explorer 6.0 or higher prior to installing the G/Electric Adapter. See Note below.

RAM

256 MB minimum

Note: .NET Support Feature: The G/Electric Data Adapter is a .NET application that requires .NET Framework 1.1. If.NET Framework 1.1 is not installed on the personal computer; the Installer program will display the following warning message: "You can download the .NET Framework from Microsoft download site."

Disk Space Requirements

Installation Drive

5 MB

System Drive

Up to 1 MB

Typically C:, where windows\system32 is located

Installing the G/Electric Data Adapter

The Oracle Utilities Network Management System G/Electric Data Adapter Installer automates the tasks that must be performed in order to properly configure and install the Oracle Utilities Network Management System G/Electric Data Adapter.

Obtaining the Software

The adapter setup files are included in the Oracle Utilities Network Management Optional Windows Applications download zip file that can be obtained from the Oracle e*Delivery site. After downloading the zip file, find the appropriate Adapter zip file within the NMS_GIS_Adapters directory and unzip to a location on your Windows server. Application Installation

Application Installation

If a previous version of the Adapter exists on the workstation, remove all the previous versions first. However, be sure to keep a backup copy of the application’s configuration database file for use with the new software. Notices of schema changes for this database can be found in the readme.rtf file in the installation directory.

If this is the first installation, then an empty application configuration database file can be obtained from the installation package. Refer to the section labeled "Adapter Configuration Database" in this document for details on this required file.

Be certain to install the software while logged on to the workstation as a Windows Administrator.

Executing the Adapter Installer

Follow these steps to install the adapter:

1.

After verifying that the Adapter installation personal computer meets the system requirements, copy the Oracle Utilities Network Management System G/Electric Data Adapter Installer supplied to you by Oracle to the desktop of the personal computer you will be running the installation on. It can be found in the NMS_V1.1#.#_Intergraph_GIS_Adapter subdirectory.

2.

Double-click the setup.exe file to start the installation. After a short time, the initial splash screen will display.

3.

Follow the on-screen instructions and prompts as required to advance to the next screen. Accept the default values unless they conflict with your system’s configuration (e.g., installation directory). The installation screens are listed below in the order they appear:

•

Welcome Screen. This screen describes the installation process.

•

Customer Information Screen. This screen prompts you for your name and your organization’s name.

•

License Information Screen. This screen displays the license agreement. You must click the I Agree button in order to proceed.

•

G/Electric Data Adapter Information Screen. This screen displays version information for the adapter.

•

Select Installation Folder Screen. This screen allows you to specify the installation directory. You can also specify whether the adapter should be available to anyone who uses this computer or only to you.

•

Confirm Installation Screen. This screen allows you to confirm the information you’ve entered before installation begins. If you need to change anything, use the Back button. Otherwise, click Next to proceed.

•

Installation Complete Screen. This screen indicates that the installation was successfully completed.

System Changes

The Adapter does not add, modify or remove any of the Windows system DLL in the <windows>\system32 directory.

The Adapter installation program installs SmoothProgressBar.dll in the installation directory of the Adapter.

Following registry keys are created by the Adapter installation program:

HKEY_LOCAL_MACHINE/Software/OracleTUGBU/Oracle Gelectric data Extractor

String Value: VersionData: <Adapter version number>

Adapter Configuration

The Adapter is configured using tables in a Microsoft Access database, commonly referred to as the "application configuration database". The specific configuration tables, their contents, several examples, and content requirements are in the following Entity Relationship diagram.

The following diagram show the G/Electric Metadata Entity Relationship:

Defaults Table

The "Defaults" table is used to indicate the default settings for the Adapter. These settings should reflect the most common parameters used for an extract. The Adapter will read only the first row in this table to apply the default settings.

Column Name

Description

Type

Unique

Required?

ExtractDirectory

Directory for extracted data output

Text(100)

Yes

Yes

UserID

G/Electric database user id

Text(50)

Yes

Yes

Password

G/Electric database user password.(Masked in **** format)

Text(50)

Yes

Yes

Server

G/Electric database connection configuration string

Text(50)

Yes

Yes

ServerDescription

GIS Server information

Text(100)

No

AreaReportUtilityPath

Directory of the AreaReportUtility.exe If the path is not provided or application is not found in the provide path then Adapter will disable the Spatial (landbase) extract.

Text(200)

No

ModificationLogTable

Name of the G/Electric table where the modifications log is replicated. This value is required only if a table other than the modification log must be queried to check the changed features.

Text(50)

No

AreaReportConfig

G/Technology configuration name from connection configuration map If the config path is not provided then AreaReportUtility will not execute. The Spatial (landbase) extraction will be disabled.

Text(50)

No

ChangeDetect_NonElectric_FNO

Non Electrical Features, that need to be identified & extracted during Change Detect Extraction process.

Text(200)

No

GetAnnotationCNO_AsAttributes

GIS annotation feature component number list (separated by comma), where annotations also need to be extracted as attributes.

Text(200)

No

No

IgnoreComponentGeometry_CNO

Allows grouping of all component geometries as one diagram. This can be helpful for linear features like conductors and bus bars. (LIST G3E_CNOs separated by comma).

Text(50)

No

No

Example

Column Name

Value

ExtractDirectory

C:\temp

UserID

Gear

Password

****

Server

GearGIS

ServerDescription

GEAR GIS Database

AreaReportUtilityPath

c:\program files\ips\gtechnology\program

ModificationLogTable

ModLog

AreaReportConfig

GEAR

ChangeDetect_NonElectric_FNO

208, 209

GetAnnotationCNO_AsAttributes

45

IgnoreComponentGeometry_CNO

301

Partition_Reference Table

The "PARTITION_REFERENCE" table is used to identify the partitions (electrical feeders or geographical tiles) to be used for extraction and their appropriate configurations. For example, an electrical feeder is a partition because all the devices that take part in forming a feeder are electrically connected. Similarly all land base features located within a certain polygon can form a land base partition due to their spatial relationship with the polygon (all the features are located WITHIN the polygon which shows a location-based spatial relationship). In essence, a group of features that are related to each other because of spatial or connectivity-based relationships form a partition.

The Adapter uses the PARTITION_REFERENCE data table to identify names of the available partitions in the G/Electric database.

Column Name

Description

Type

Unique

Required?

ExtractMethod

Data extract method to indicate whether the Adapter performs a spatial data extract (using polygon area) or a connectivity based circuit data extract (using electric circuit data) or a Detail window based data extract (using Detail window data)

Text(10)

No

Yes

PartitionGroupName

Unique Name of the partitions grouped together (e.g., electric feeder partitions or land base partitions). This is the primary key.

Text(50)

Yes

Yes

GIS_TableName

G/Electric Start Feature’s attribute table name in the database; e.g., BREAKER_N or CONNECTIVITY_N or DETAIL_IND_LB

Text(50)

No

Yes

GIS_StartFeatureColumnName

Column name from the table specified in the above GIS_TableName parameter. The value from this column will be used to identify each unique partition and output MP files will be named using this value (if values are not unique then use the Where clause to filter out undesired rows) e.g., FEEDER_NO

Text(50)

No

Yes

GIS_StartFeature

G/Electric feature name that determines the partitions in a partition group (e.g., land base grid class name or head of the circuit for electric feeder data; e.g., breaker) This is not a required attribute if Non-Spatial (Electrical feeders) is provided from another table e.g., CONNECTIVITY. This is also not required for extracting Detail features.

Text(50)

No

No

GIS_StartFeatureFNO

G/Electric Feature Number of the GIS Start Feature (Only required when GIS_StartFeature is provided)

Number(5)

No

No

GIS_StartFeatureColumnANO

Unique name column G3E_ANO from G3E_ATTRIBUTES table

Text(50)

No

No

GIS_WhereClause

Standard SQL Where clause to filter the number of partitions in the provided class, e.g., G3E_FID<10000

Text(100)

No

No

MPFileSuffix

MP file suffix to distinguish between different partition group MP files

Text(3)

No

No

LastExtractDate

The last successful data extraction date of the partition (populated by the Adapter). The user can provide From and To date to identify changed partitions. If the user does not populate "From Date" to determine changes, then this date is used as a "From Date" to define the time duration.

Date

No

No

Populate Feeder List Using a Source Feature

When an electric feeder in the G/Electric GIS originates at a particular GIS feature then this feature is considered as a "Source" feature. If all the feeder are associated with a particular "Source" feature (e.g., Breaker) then use following example to populate the Electrical Feeders list in the Adapter

Column Name

Value

ExtractMethod

NonSpatial

PartitionGroupName

Electric Feeder

GIS_TableName

BREAKER_N

GIS_StartFeatureColumnName

BREAKER_NUMBER

GIS_StartFeature

Breaker

GIS_StartFeatureFNO

300

GIS_StartFeatureColumnName

3000001

GIS_WhereClause

MPFileSuffix

LastExtractDate

Populate Feeder List Using a Database Table

If all of your electrical feeders do not originate at a particular GIS feature (e.g., Breaker) OR source feature’s attribute value does not populate the CIRCUIT1 and CIRCUIT2 attribute in the CONNECTIVITY table then feeder names should be retrieved using a database table where all feeder names are listed. For example you could use CONNECTIVITY table to identify all the available feeders in the system. In this case you do not need to populate GIS_StartFeature, GIS_StartFeatureFNO and GIS_StartFeatureColumnANO attribute values.

Column Name

Value

ExtractMethod

NonSpatial

PartitionGroupName

Electric_Feeder

GIS_TableName

CONNECTIVITY_N

GIS_StartFeatureColumnName

CIRCUIT_1

GIS_StartFeature

GIS_StartFeatureFNO

GIS_StartFeatureColumnANO

GIS_WhereClause

SYSTEM_VOLTAGE=’13.8’

MPFileSuffix

LastExtractDate

15 Jun 2005

Populate Detail Window Name Using a database Table

All features within a Detail Window is extracted using the DETAIL_USERNAME attribute within the DETAIL_IND_LB table

Column Name

Value

ExtractMethod

Detail

PartitionGroupName

Detail

GIS_TableName

DETAIL_IND_LB

GIS_StartFeatureColumnName

DETAIL_USERNAME

GIS_StartFeature

GIS_StartFeatureFNO

GIS_StartFeatureColumnANO

GIS_WhereClause

MPFileSuffix

_dt

LastExtractDate

Populate Spatial (Landbase) Partition List

The Adapter extracts all the landbase and non-electrical data spatially, i.e. using a polygon grid (or tile). You need to provide the Polygon grid feature information in the PartitionReference table to extract the non-electrical data.

Column Name

Value

ExtractMethod

Spatial

PartitionGroupName

Landbase

GIS_TableName

OMSGRID_N

GIS_StartFeatureColumnName

GRID_NUMBER

GIS_StartFeature

OMS_GRID

GIS_StartFeatureFNO

204

GIS_StartFeatureColumnANO

2040001

GIS_WhereClause

GRID_NUMBER<150

MPFileSuffix

_lb

LastExtractDate

ExcludeFeature Table

The ExcludeFeature" table is used to indicate the G/Electric GIS features that should NOT be extracted by the Adapter.

Column Name

Description

Type

Unique

Required?

G3E_FNO

Unique and valid G/Electric G3E_FNO from the G3E_FEATURE table. This is the primary key.

Integer

Yes

Yes

FeatureName

Feature User Name (Not used by the Adapter. This is for the administrator’s reference.)

Text(80)

Example:

Column Name

Value

G3E_FNO

229

FeatureName

Region

ExcludeComponent Table

The ExcludeComponent" table is used to indicate the G/Electric GIS components that should NOT be extracted by the Adapter. If a feature is listed in the ExcludeFeature table, then listing individual feature components in the ExcludeComponent Table is not required because all the components of the features will be excluded anyway. If a global component (such as Leader Line) needs to be excluded from the data extract, then it should be listed here only once.

Column Name

Description

Type

Unique

Required?

G3E_CNO

Unique and valid G/Electric G3E_CNO from the G3E_COMPONENT table. This is the primary key.

Integer

Yes

Yes

ComponentName

Component User Name (Not used by the Adapter. This is for administrator’s reference)

Text(80)

Example:

Column Name

Description

G3E_CNO

33

ComponentName

Hyperlink Attributes

PartitionGroupFeature Table

The "PartitionGroupFeature" table is used to specify the spatial "Partition Group Name" to G3E feature relationship. The user can define the spatial PartitionGroupName in the Partition_Reference table and specify which G/Electric features belong to the partition group.

The user can extract grouped GIS features in separate MP files based on the PartitionGroupName. For example, the spatial PartitionGroup named "Street" will be extracted in a separate MP file where features listed in the PartitionGroupFeature table will be extracted.

Column Name

Description

Type

Unique

Required?

PartitionGroupName

Unique Name of the partitions grouped together (e.g., electric feeder partitions or land base partitions) Populated from PartitionReference table

Integer

Yes

Yes

G3E_FNO

GIS Feature Number of a feature which should be extracted as a part of the PartitionGroup. This is the primary key.

Text(80)

Example:

Column Name

Description

PartitionGroupName

Street

G3E_FNO

182

V_SPL_FIDFNO View

The G/Electric Adapter requires an Oracle view called V_SPL_FIDFNO in the G/Electric Oracle Database. The system administrator must create the view V_SPL_FIDFNO on the G/Electrical Oracle database server.

The V_SPL_FIDFNO view provides the G3E_FNO (feature number) for every G3E_FID in the G/Electric database. When the Adapter executes the G/Electric’s spatial query application AreaReportUtility to find the features within the specified spatial area, the application returns only the G3E_FID of the features. The V_SPL_FIDFNO view provides the feature number (G3E_FNO) of every G3E_FID (unique feature identifier) in the system, which reduces the overhead of querying each G3E_FID to find the corresponding G3E_FNO.

The system administrator should execute the create_spl_view.sql file on the G/Electric GIS server using the SQL PLUS utility. The create_spl_view.sql file is located in the Reference subdirectory of the Adapter installation directory.

The system administrator should edit the create_spl_view.sql file to make sure that the GIS COMMON component number is correct in the file. The create_spl_view.sql file lists "G3E_CNO=31". If the COMMON component number (G3E_CNO) in your G/Electric GIS database is different, then the G3E_CNO must be replaced with the correct G3E_CNO of the COMMON component

The query result returned by the database should be captured in a text file by using the SQL Plus spool command.

The spooled file should be edited to complete the Create view definition by:

•

In the beginning of a spooled file add a statement:

•

Create or Replace View V_SPL_FID_FNO as

•

After the last union all statement in the spooled file add a statement:

•

Select G3E_FID, G3E_FNO from COMMON_N;

•

Execute the spooled file using the Oracle SQL Plus application to create the V_SPL_FIDFNO view.

If the V_SPL_FIDFNO view is not available, then the Adapter will disable the spatial (land base) data extract functionality and only non-spatial extraction (electric feeders) can be carried out.

Third Party Products

The G/Electric Data Adapter requires three third party products. Those products are:

•

G/Electric GIS Database Server

•

Microsoft Access to configure the Adapter configuration database

•

Oracle SQL*NET Client

Oracle Client Configuration

The Adapter requires the Oracle client installed on the machine where the Adapter is installed. The Adapter administrator must configure the Oracle server name using the Oracle Net Configuration Assistant utility. The Oracle server name must be populated in the "Server" column of the Adapter configuration database’s "Default" table.

Executing the Adapter

The Adapter can be run either in the background with command line parameters or interactively with a GUI. In any event, ensure the Adapter configuration database file GElec2Oracle.mdb has been customized prior to running the Adapter for the first time.

When the Adapter is launched interactively or in command line mode, it creates the "initialize.log" file in the Adapter installation directory. The log file reports initialization status of the Adapter. Once the Adapter is launched successfully and extraction has started, the "extracting.log" file is created in the Extract Work Order directory.

Launching the Adapter Interactively

The G/Electric Data Adapter can be launched from the Windows Start button, Programs, Oracle’s G/Electric Data Adapter. After a few moments, the G/Electric Data Extractor configuration window is displayed.

This window contains four main framed panels:

•

Change Detection

•

Data Extraction Parameters

•

Status panel - Where information on the extraction process is reported to the user.

•

Work Order Details and the Launch Extract and Cancel buttons.

Debug Mode

The Adapter could be launched with debug mode on to report more detailed reporting of the Adapter activity in initialize.log and extracting.log files. In the debug mode the Adapter writes every detail in the log file, so it is very time consuming. The Adapter should be launched in the debug mode only during the test phase or to identify cause of the Adapter error.

To run the Adapter in debug mode:

•

Create a new shortcut icon on the desktop of the computer for launching the Adapter software (GElec2Oracle.exe)

•

In ‘Create Shortcut’ dialog, browse to the Adapter installation directory and select GElec2Oracle.exe. Click Next button to display the ‘Select a Title for the Program’ dialog.

•

After providing the name for the short cut click Finish button to create the short cut.

•

Right mouse click on the newly created shortcut on the desktop and select Properties from the displayed menu. The system will display Properties dialog with Shortcut tab selected

•

In the Target Section for the shortcut, specify the flag -DEBUG at the end of the existing value. For example

•

Before: C:\Program Files\OracleTUGBU\Oracle GElectric Data Extractor \GElec2Oracle.exe

•

After: "C:\Program Files\OracleTUGBU\Oracle GElectric Data Extractor \GElec2Oracle.exe" -DEBUG (You need to provide double quotes enclosing the Adapter application path but make sure -DEBUG is not typed within the closing double quotes.

•

Click Apply button to dismiss the Properties dialog.

•

Launch the Adapter using newly created shortcut. The log files will provide a lot more information.

Data Extraction Parameters Panel

This panel contains the data parameters required for conducting the extraction. In order to extract data partitions, the user needs to select a partition group name and partitions that are part of the desired partition group.

The partition group names are populated using the PartitionGroupName column of the PARTITION_REFERENCE table of the Adapter configuration database. The Adapter finds all the partitions belonging to the defined group by querying the G/Electric database.

Depending on the partition group name chosen by the user, the items (partition names) listed in the "Partitions" list box on the right hand side of the panel will change to reflect the unique partition names associated with the specified partition group.

The user can manually choose which partitions to extract from the partitions list on the right hand side of the GUI. Note that clicking or highlighting a partition on the partitions list will queue it for extraction. Standard Windows Shift-click or Alt-click functionality is employed for multiple selects.

Other tools include the Select All and Unselect All buttons, which will select all the partitions in the queue, or none of them respectively.

Extract Launch Controls

The Adapter displays the extracted data directory path where work order sub-directories will be created. The extract directory path is read from the ExtractDirectory field of the "Defaults" table in the Adapter configuration database.

The extracted data will be extracted in a work order directory created under the default extract directory. The default name for an extract directory is a combination of the system’s current date and time (e.g., 2001Aug30-1256); however this can be overridden by simply changing the contents of the Work Order Name field.

Pressing the Launch Extract button begins the extraction of the selected partitions. Once the extract begins, the Exit button in this panel is replaced with a Cancel button, which - if clicked - will allow the user to interrupt the extract process.

Change Detection Panel

This panel contains information for the change detection functionality of the Adapter. It also displays the G/Electric GIS server information and date of the last data extract for the selected partition group name.

The change detect mechanism identifies the changed partitions over a period of time. The user needs to provide a time range using the "From Date" and "To Date" fields. By default, the Adapter enters the Last_Extract date in the "From Date" and the current Adapter launch date and time in the "To Date" field, but the user can override these default values. If no data extraction has taken place, then the From and To date fields will be populated with the current Adapter launch date and time.

If the user has selected a "Non Spatial" partition group (i.e., electric), then the system will detect the changed feeders between the defined time duration. Similarly, if a user has selects a "Spatial" partition type (e.g., land base), the system will then detect changed land base polygons (partitions) between the defined time duration.

G/Technology provides GIS work order management through the concept of a long-term transaction (LTT), commonly referred to as a Job. It allows GIS users to perform Long Term Transaction (LTT) changes (unapproved) in the database while keeping these changes isolated from other LTTs (users working on the approved, master records and those working on their own, as of yet unapproved, LTTs). These changes can be deletions of and modifications to existing records as well as adding additional records. In this way GIS users can initiate an LTT and perform inserts, updates, and deletes in that LTT.

When changes are complete, the GIS user posts them to the master database by running the "Post Job" command. This ends their isolation from the master and from other GIS users. When this happens, the GIS user's changes become part of the master record, replacing the current master record. The GIS user must be editing the job in order to post it. Once the job is posted, the feature’s LTT_STATUS is set to null.

The Adapter will extract only master database records with the LTT_STATUS of NULL or ‘COPIED" and the change detect routine will use only master database records to identify the changes. The Adapter will not extract any of the LTT data or consider the changes made by the LTT in order to identify the changed partitions.

The Adapter uses the G/Electric facility model’s ModificationLog table to identify the changed or deleted features. The Adapter will use the user-provided time range to identify changed or deleted features, but considers only those features that are specified in PartitionGroupFeature table for the selected partition group name. Based on the changed feature’s location or connectivity, the Adapter will determine the changed partitions. For example, if the partition group is a spatial partition group then a changed polygon will be reported OR if the partition group is a non-spatial (electric) partition, then a changed feeder will be reported.

Executing the "Perform Change Detect" command will automatically queue partitions that contain changed features between the user provided "From" and "To" dates. The change detection process requires intensive database searches and comparisons to identify changed partitions.

To perform Change Detect of Deleted Features, GElectric Adapter, creates a master reference table CONNECTIVITY_SPL, to store all the G3E_FID, CIRCUIT1 & CIRCUIT2, LTT_DATE of all electrical features, in GIS database. The Adaptor uses the CONNECTIVITY_SPL & the modification log table, to identify any deleted features.

Modification Log

If departmental policy or business processes require the GIS administrator to purge the ModificationLog table frequently, quick and easy access to the G/Electric feature modification information is lost. The G/Electric database provides alternate ways to find the added and modified features but deleted feature information will be lost.

If the extract frequency is going to be longer than the ModificationLog table purge frequency, then it is advisable to copy the ModificationLog table in an intermediate table for the Adapter. The Adapter will use the modification log data from this new Adapter-specific table to identify the changed partitions. The table name must be specified in the ModificationLogtable column of the Default table in the Adapter configuration database.

Status Panel

Because the extraction process will take time to complete, its status and progress can be monitored from the panel at the bottom of the GUI. The Overall Progress field displays an estimated extraction progress of all the queued partitions, while the Detail Progress field indicates more detailed extraction progress information, such as the specific partition and feature class currently being extracted.

Launching the Adapter in Batch Mode

The Adapter can be launched in a non-GUI mode from the Windows command line with parameters. However, because this launch method is "silent," no visual feedback will be provided to the workstation screen except for error reports. The user will have to view the output directory in order to determine progress.

The Windows service scheduler can be used to schedule an automatic extract process.

When launching the Adapter in non-GUI mode, only the non-GUI launch flag is required, while all other command line parameters are optional. If a parameter is omitted, the default is assumed. In default mode, the Adapter extracts the electric feeder data.

The command line usage is:

"[install directory]\ GElec2Oracle.exe" -NONGUI [-DEBUG] [-?] [-d dataset] [-r reference] [-p partition] [-w workorder] [-o] [-q queue]

Where:

-NONGUI

(required) Indicates to launch Adapter in non-GUI mode.

-DEBUG

Launches the Adapter with Debug mode on.

-?

Command Line Help

-r reference

Path of application reference database file if other than the default GElec2Oracle.mdb in the extract install directory (e.g., -r c:\myrefdb.mdb)

-p partition

Partition type to use; as in PartitionReference table (e.g., -p Electric_Tile)

-w workorder

Workorder directory to create (e.g., -w Nov20-01)

-o

Force an Overwrite of existing workorder and version (if existing ones are found)

-q queue

Method to queue partitions:

ALL - queues all partitions (e.g., -q ALL)

CD - uses change detection to queue (e.g., -q CD) (default)

LIST - user provides a list of partition names to be extracted which are separated by a comma. (If multiple partition types are in provided using -p option where Adapter cannot determine the PartitionGroup of listed partition queue then Adapter will report the warning and terminates.

Output of Adapter

The model preprocessor import files (.MP), the log file, and the work order time stamp file are all placed in a folder with the work order name. This folder will appear in the output directory as designated in the "Defaults" table. If change detection was run, a log file of the process will be placed in the root of the output directory.

Note that if the extract is still in progress or does not complete, the work order time stamp file will not appear in the output directory. The work order time stamp file will only appear if the complete extract finishes successfully. As such, external processes can use its presence as an indicator of a completed extract.

Performance

The non-spatial data extract (i.e., of electric feeders) does not depend upon the GIS’ AreaReportUtility application to find the features located within a polygon partition so these extracts are faster compared with a spatial data extract. The spatial data extract uses G/Electric’s AreaReportUtility application to identify features located within a polygon area.

The number of class components being extracted will dramatically affect the Adapter performance. Therefore, if any of the features components are not required for the Oracle Utilities Network Management System then they should be listed in the ExcludeComponent table. The ExcludeComponent table ensures that feature information will be extracted but components listed in the ExcludeComponent table will not get extracted. For example detailed document, raster, or hyperlink document components are not required for the Oracle Utilities Network Management System. These components should be listed in the ExcludeComponent table.

The time required to perform change detection will vary and is dependent on the number of features that have changed since the last extract. The list of changed features does not provide the partition information, so the Adapter depends upon G/Electric’s AreaReportUtility to identify the spatial polygon (partition) of the changed feature.

Application Process Flows

The following figure shows the G/Electric Adapter user process flow:

The following figure shows the G/Electric Adapter module process flow:

The following figure shows the G/Electric Adapter process flow:

GIS Data Requirements

Required Data for All Adapter Features

Oracle Utilities Network Management System Requirement

GIS Source

Comments

Object type

G3E_FNO and G3E_USERNAME, Feature Class and attributes

Object Unique ID

G3E_FID

Object geometry (point, line, text)

Feature Geometry

Adapter produces diagram object of type point, line, or text.

Points:

(x, y) location

angle,

justification

Point Feature Geometry

Adapter produces diagram object characteristics of: location, angle, and scale.

Lines:

List of coordinates

Linear Feature Geometry

Adapter produces diagram object characteristics of: location, angle, scale

Text:

(x,y) location

angle or endpoint

string

justification

Feature Text Component

Adapter produces diagram object characteristics of: location, angle, string, and justification.

Optional Data for All Adapter Features

Oracle Utilities Network Management System Requirement

GIS Source

Comments

Diagram declutter ranking value

N/A

Not retrieved

(x,y) offset for graphical attributes

N/A

Not retrieved

Diagram groupings for multi-object hide/display

N/A

Not retrieved

Symbology class

N/A

Not retrieved

Scale factor

Attribute

E.g., urban or rural attribute prescribes a certain scale factor

Object location ID

Based on Partition

Required Attributes for Electrical Objects

Oracle Utilities Network Management System Requirement

GIS Source

Comments

Connectivity information

NODE1 and NODE2 from CONNECTIVITY component

Normal status of device

NORMAL STATUS from CONNECTIVITY component

Orientation of the feature - OH or UG

ORIENTATION from the CONNECTIVITY component

Phases for the device (PHASES)

PHASE from CONNECTIVITY component

Voltage level (VOLTS)

Voltage from CONNECTIVITY component

Optional Attributes for Electrical Objects

Oracle Utilities Network Management System Requirement

GIS Source

Comments

Network protection direction

N/A

Operations control authority zone (NCG)

N/A

Sample Model Preprocessor File

The main products of the Adapter are the model preprocessor (".mp") files. There is one preprocessor file for each partition.

A sample of a model preprocessor file that contains a partition identifier (feeder 1) and Switch feature (with switch unit and text annotation) is shown below:

ADD Feeder1 {

NAME = Elec1;

COORD_SYSTEM = NAD_1927_StatePlane_Pennsylvania_South_FIPS_3702;

SCALE_FACTOR = 1.0;

Diagram[Feeder] = {

GEOMETRY ={

(-2147000000.00000,-2147000000.00000),

(2147000000.00000,-2147000000.00000),

(2147000000.00000,2147000000.00000),

(-2147000000.00000,2147000000.00000),

(-2147000000.00000,-2147000000.00000);

};

};

ADD Primary_Switch 815425 {

PORT_PORT_A=129493717;

PORT_PORT_B=129493718;

DIAGRAM[31303] = {

HEIGHT = 0;

ANGLE = 0.3130386;

SCALE = 0;

TEXT = "445SWITCH_NUMBER";

GEOMETRY = {

(-553069.9375,-20248.82421875)};

};

DIAGRAM[31302] = {

HEIGHT = 0;

ANGLE = 1.747896;

SCALE = 0;

GEOMETRY = {

(-553076.625,-20250.107421875)};

};

ATTRIBUTE[G3E_FID]="815425";

ATTRIBUTE[G3E_FNO]="313";

ATTRIBUTE[FEATURENAME]="Primary Switch";

ATTRIBUTE[SWITCH_NUMBER]="445";

ATTRIBUTE[RATING]="600.00";

ATTRIBUTE[SWITCH_OPERATOR]="MANUAL";

ATTRIBUTE[SWITCH_TYPE]="AIR BREAK";

ATTRIBUTE[SWITCH_SUB_TYPE]="Load Break";

ATTRIBUTE[LTT_ID]="0";

ATTRIBUTE[MIRROR]="NO";

ATTRIBUTE[JOB_PLACE_NAME]="MetadataEdit";

ATTRIBUTE[JOB_PLACE_DATE]="05/14/2004 1:34:57 PM";

ATTRIBUTE[JOB_MODIFY_NAME]="JC_May20";

ATTRIBUTE[JOB_MODIFY_DATE]="06/01/2004 2:30:12 PM";

ATTRIBUTE[STATE]="In Service";

ATTRIBUTE[ASSET_OWNER]="THESL";

ATTRIBUTE[IPID]="35503";

ATTRIBUTE[DISTRICT]="YK";

ATTRIBUTE[LTT_ID]="0";

ATTRIBUTE[LTT_DATE]="06/01/2004 2:30:12 PM";

ATTRIBUTE[LTT_TID]="392702";

ATTRIBUTE[REGION_NAME]="York";

ATTRIBUTE[NORMAL_STATUS]="CLOSED";

ATTRIBUTE[CIRCUIT1]="11-M1";

ATTRIBUTE[CIRCUIT2]="11-M1";

ATTRIBUTE[PHASE]="RWB";

ATTRIBUTE[ORIENTATION]="OH";

ATTRIBUTE[ACTUAL_STATUS]="CLOSED";

ATTRIBUTE[STATE]="In Service";

ATTRIBUTE[SYSTEM_VOLTAGE]="27.6";

ATTRIBUTE[OPERATING_VOLTAGE]="27.6/16 kV";

ATTRIBUTE[COLOUR_NO]="1";

ATTRIBUTE[LTT_ID]="0";

ATTRIBUTE[FEEDER_FLAG]="NO";

};

Uninstalling the G/Electric Data Adapter

Microsoft Windows 2000

From the Start button, click Settings, then Control Panel. Double-click the Add/Remove Programs Icon. Select the G/Electric Data Adapter application from the program list, and click the Change/Remove button.

Microsoft Windows XP

From the Start button, click Control Panel. Double-click the Add/Remove Programs Icon. Select the G/Electric Data Adapter application from the program list, and click the Remove button.

Generic WebSphere MQ Adapter

This chapter includes the following topics:

•

Introduction

•

Hardware and Software Requirements

•

Functional Description

•

Adapter Installation

•

High Availability

•

Performance

•

Data Flows

•

Information Model

•

Configure Queues for Required Data Flows

Introduction

The purpose of this document is to provide an administration guide of the Oracle Utilities Network Management System Generic WebSphere MQ Adapter. This document will discuss the required process for installing and configuring the adapter to run with the appropriate Oracle Utilities Network Management System software.

The Oracle Utilities Network Management System Generic WebSphere MQ Adapter can serve as a data adapter between the Network Management System and a number of external systems, such as a Customer Information System (CIS) or an Interactive Voice Response (IVR) system. Additionally, this adapter could be used with external systems that need to input trouble calls into Network Management System but do not require other sophisticated data flows, such as High Volume Call Applications (HVCA), Automated Meter Reading (AMR), or Work Management Systems (WMS).

This interface depends upon IBM’s WebSphere MQ software as the intermediary repository for information passed between the Network Management System and the external system. This adapter is used only for the communication between IBM’s WebSphere MQ software and the Oracle Utilities Network Management System software suite. With the use of XML as the payload for data transmission, the adapter exchanges data between Oracle Utilities Network Management System and external systems as defined in the Oracle Utilities Network Management System WebSphere MQ XML schema documents. The required configuration of the adapter is described in the sections that follow.

Terminology

The following terms and acronyms are relevant to this specification

OMS

Outage Management System

Network Management System

Network Management System

SMService

System Monitor Service. SMService monitors the core processes in the system, essentially the services and interfaces.

JMService

Job Management Service. The Oracle Utilities Network Management System call processing and outage prediction engine.

MQSeries

A queue-based messaging system developed by IBM. This system has been renamed to WebSphere MQ.

DTD

Document type definition, used to define XML documents

XML

Extensible Markup Language

XSL

XML Style Sheet, used to reformat XML documents

XML Schema

An XML standard for defining XML documents

CIS

Customer Information System

IVR

Interactive Voice Response system

SCADA

Supervisory Control and Data Acquisition system

HA

High availability, where Oracle Utilities Network Management System is configured with a pair of redundant servers. This is usually in the form of a hardware cluster and a shared drive that contains the database.

Hardware and Software Requirements

Oracle Utilities Network Management System Environment

The Oracle Utilities Network Management System environment consists of a number of servers that are interconnected using the InterSys messaging system.

Adapter Server

The Generic WebSphere MQ Adapter environment may be resident on the same servers as the Oracle Utilities Network Management System services, or it may be implemented on a separate server. Specifications for a stand-alone adapter server:

•

All Oracle Utilities Network Management System Unix and Linux operating systems are supported.

•

IBM WebSphere MQ messaging product must be installed. Note, however, that the queues may reside on a remote machine.

•

A LAN connection to the Oracle Utilities Network Management System server must be available.

•

Isis must be installed and configured

Depending upon the high availability scheme selected, it would be possible to configure more than one adapter server for redundancy.

Oracle Utilities Network Management System Server

The Oracle Utilities Network Management System server environment is typically deployed on one or more Unix or Linux servers configured with the following:

•

Unix/Linux operating system

•

Oracle RDBMS with Oracle Utilities Network Management System model

•

Oracle Utilities Network Management System service processes

•

LAN connection to adapter server

•

Message queues to be used by the MQ/XML Adapter appropriately declared in the defined database configuration table.

•

Isis

External System Environment

The external system is any system that can exchange information with Oracle Utilities Network Management System through an adapter. The environment of the external system has the following capabilities:

•

Any operating system which supports IBM WebSphere MQ messaging

•

IBM WebSphere MQ messaging product

•

Applications that can request or publish information in a manner which is either directly or indirectly (through a translator) compliant with the XML specifications contained within this document via queues

•

Queues must be pre-configured

•

IBM WebSphere MQ Integrator can be used as needed for routing and translation.

Required Installed Software:

The following lists the required software that needs to be installed prior to any configuration of the Oracle Utilities Network Management System Generic WebSphere MQ Adapter.

•

IBM’s WebSphere MQ

•

Isis (installed as part of the base Oracle Utilities Network Management System installation)

Note : Isis is the messaging backbone for Oracle Utilities Network Management System and will already be present on any Network Management System servers. If the Generic WebSphere MQ Adapter is to be executed on a separate server than the Network Management System, then that server must also have Isis installed and running. Every server installation must be running the same version of Isis. The CMM_CELL environment variable must be set the same on any servers which are to communicate through Isis.

Functional Description

Context Diagram

Below is a diagram of the interaction between Oracle Utilities Network Management System and various external applications via the Generic WebSphere MQ Adapter.

In this document, it is assumed that the Generic WebSphere MQ Adapter’s tables reside in the database used by Oracle Utilities Network Management System.

Adapter Installation

Overview

This section guides the user in the installation of the Oracle Utilities Network Management System Generic WebSphere MQ Adapter. The following are assumed to be true before the adapter is installed:

1.

Oracle Utilities Network Management System is installed and functional. This means that database access has been confirmed, as well as Isis message bus communication.

2.

WebSphere MQ is installed on a machine that is accessible to the Oracle Utilities Network Management System.

Generic WebSphere MQ Adapter Installation Verification

Verify that the following files are found in their respective folders

•

$CES_HOME/bin/mqseriesgateway

•

$CES_HOME/bin/ces_mq_gateway.ces

Configure Adapter to Run as NMS System Service

Configure the Generic WebSphere MQ Adapter to run as an Oracle Utilities Network Management System service by updating the $NMS_HOME/etc/system.dat file to include the Generic WebSphere MQ Adapter as a system service. There are 3 main sections where this service needs to be defined: the service, program and instance sections.

See the $CES_HOME/templates/system.dat.template file for examples of how to configure the Generic WebSphere MQ Adapter. Search for "mqseriesgateway" in the file and copy those lines to the $NMS_HOME/etc/system.dat file. Make sure all lines are uncommented so that they are active. See the command line options section below for more details on available options. You must restart the system services in order to the Generic WebSphere MQ Adapter to properly be monitored by SMService.

Note: In setting up $NMS_HOME/etc/system.dat, it is important to note that the examples above were presented only for illustration purposes. Parameters may differ on an actual project setting. Coordinate with your Project Engineer in setting up your system configuration file. Also, take note that in the example above, it is assumed that the Generic WebSphere MQ Adapter will reside on the same machine where the Oracle Utilities Network Management System environment resides.

Generic WebSphere MQ Adapter Command Line Options

Command Line Option

Arguments

Required(Y/N)

Description

-areasummary

N

Enables the adapter to process area summary requests. The specified control zone level will be used to filter the outage list in the area summary. The default control zone level of 3 will be used when none is specified.

-complete

Minutes

N

Specifies how often the interface will save a timestamp which is used for synchronization on restart. The timestamp is used to go back to that timestamp to know how far back to get events on restart.

-condition

N

Enables the adapter to process condition data.

-connect

N

Enables the adapter to process customer disconnect / reconnect information.

-createincident

N

Enables the adapter to process trouble calls.

-crewoutagestatus

Enables the adapter to process crew outage status changes.

-crewupdate

N

Enables crew assignments & dispatches to be sent.

-custdbsname

DBService name

N

Indicates mqseriesgateway to use separate DBService.

-custhistory

N

Enables the adapter to process customer outage history information.

-custstatus

N

Enables the adapter to process customer outage status information.

-customer

N

Enables the adapter to modify the customer model.

-custparseonly

N

Indicates that mqseriesgateway will only parse the customer update xml messages without modifying in the database. This is for performance testing purposes.

-custsqlbundle

N

Enables the adapter to bundle all sql statements for DELETECREATE/CUSTOMER requests to improve speed.

-debug

N

Enables the adapter to write to standard output the debug information.

-defaultaccounttype

Account Type

N

Sets the default account type for customer model.

-getqueue

Queue name

N

Changes the default get queue name.

-help

N

Writes to standard output, the usage of the adapter.

-includeincident

N

Places incidents information in <PostSrsOutput_001> message. This option is not recommended, because it will greatly degrade the performance of the adapter.

-includepicklistinfo

N

Includes picklist info in the SRS output message if it exists.

-nocompleteevent

N

This option should be used with the -synchronize option. It will exclude all complete event from the synchronization messages

-nosndlist

N

Removes the supply node list from the <PostSrsOutput_001> and <PostSrsOutputStatus_001> messages to improve performance.

-nosndrecache

N

This command line will disable the JMService supply node recache.

-outageupdate

N

Enables outage updates to be sent.

-putqueue

Queue name

N

Changes the default put queue name.

-query

N

Enables the adapter to process query statements to the Operations Database.

-queuemanager

<string queue manager name>

N

Enables the adapter to use the defined queue manager name instead of NMS_MGR.

-recache

<int hours>

N

Enables the adapter to recache SRSService for the customer model.

-recachehour

<hours>

N

This specifies when JMService will re-cache customer info in hours. This will override the -recache option.

-recacheminute

<minutes>

N

This specifies when JMService will re-cache customer info in minutes. This will override the -recache option.

-requestedcblist

N

Enables the adapter to send restore messages containing a list of customers who requested a callback of a restored device.

-sql

N

Enables the adapter to process sql statements to the Operations Database.

-srsoutput

N

Enables the adapter to process outage status (Restored, complete, cancelled).

-subsetcblist

<percent affected> <minimum affected> <maximum affected>

N

This specifies that the Generic WebSphere MQ Adapter will send an SRSOutput message that contains a callback list of relatively random sampling of customers downstream of the restored device. Default values: percent affected=30%, minimum affected=10, maximum affected=300. Setting the percent affected alone is valid but setting the maximum affected needs all three parameters to be present.

-synchronize

N

Sends synchronization messages when the adapter starts. This is only required to capture outage event update messages for events that were completed while the interface was down.

-usedeviceid

N

Enables the adapter to process device names instead of supply nodes index or premise identifiers.

-usepremiseid

N

Enables the adapter to process premise identifiers instead of supply nodes.

-xslpath

<string path>

N

Indicates that Style Sheet Processing is used, and the literal path the directory that contains the .xsl files for the adapter.

The following table lists and describes command line options to support the bulk load for the customer model createSql process.

Command Line Option

Arguments

Required (Y/N)

Description

-xmlfile

<string path>

N

Indicates the name of the XML file to be used to create the SQL file to produce the customer model.

-writetodb

<>

N

Enables the adapter to write the SQL statements directly to the database when generating the SQL file. (Note when this option is used only a small portion of customers should be used because the entire SQL statement is run.

-outputfile

<string path>

N

Indicates the name of the SQL file to be produced, containing the SQL to create the customer model.

Optionally, Configure the Adapter to Run with Another Instance of DBService

In $NMS_HOME/etc/system.dat, include the MQDBService as one of the services. Use the TCDBService entries as examples of how to set this up.

Note : If using a separate DBService, you must start the Generic WebSphere MQ Adapter with the "-custdbsname" command line parameter and use the MQDBService name as the argument.

Configure the WebSphere MQ Server

•

References to "Console Root" throughout this chapter refer to the highest level in the tree displayed by the WebSphere MQ Explorer GUI.

Create New Queue Manager

1.

From WebSphere MQ Explorer tree, select: Console Root ==> WebSphere MQ ==> Queue Managers ==> New ==> Queue Manager

•

Queue Manager (name) = NMS_MGR.A

•

Check "Make this the default Queue Manager" (indicating yes)

2.

Click Next - use default settings (circular logging)

3.

Click Next - use default settings (start queue manager)

4.

Click Next - uncheck "create listener configured for TCP/IP"

Create New Queues (2)

1.

From WebSphere MQ Explorer tree, select:

Console Root ==> WebSphere MQ ==> Queue Managers ==> NMS_MGR.A ==>Queues ==> New ==> Local Queue

•

Queue Name = NMS.A.FROMNMS

2.

Click OK - use all default settings

3.

Click Console Root ==> WebSphere MQ ==> Queue Managers ==> NMS_MGR.A ==> Queues ==> New ==> Local Queue

•

Queue Name = NMS.A.TONMS

4.

Click OK - use all default settings

Note: At this point, the two new queues should be created. Check the status of each queue or put a test message into each queue by doing the following:

5.

Select Console Root ==> WebSphere MQ ==> Queue Managers ==> NMS_MGR.A ==> Queues

This should display a list of queues.

6.

Right click on the desired queue to bring up a menu containing selections for "Status" and "Put test message".

Create Server Connection Channel

1.

From WebSphere MQ Explorer tree, select:

Console Root ==> WebSphere MQ ==> Queue Managers ==> NMS_MGR.A ==> Advanced ==> Channels ==> New ==> Server Connection Channel

A dialog will display containing tabs for General, Extended, MCA, Exits, and SSL

•

In the General tab, the Channel Name is SCH1

•

In the MCA tab, the MCA User ID is the local login userid

2.

Click OK - use all default settings

Note: At this point, the new server connection channel should be created. Check the status of the new server connection channel by doing the following:

3.

Select Console Root ==> WebSphere MQ ==> Queue Managers ==> NMS_MGR.A ==> Advanced ==> Channels.

This should display a list of connection channels.

4.

Right-click on the SCH1 channel to bring up a menu containing selections for "Status" and "Start" and "Stop".

5.

Select Start. The new server connection channel should display the message "The request to start the channel was accepted (amq4008)".

Create New Queue Manager Listener Service

The default TCP/IP port for the default Queue Manager listener is 1414. Multiple listeners can be configured, but for simplicity, in this case, the original installation default listener for the default queue manager has been stopped. This frees up port 1414 for use by a new listener.

Stopping the Original Default Queue Manager Listener

1.

Select Console Root ==> WebSphere MQ Services (local) ==> ( the original default queue manager name).

This will cause a list of services to be displayed, one of which is the "listener" service.

2.

Right-click on "listener ==> properties" and stop the listener.

3.

Change the startup from Automatic to Manual.

This listener should no longer start-up at reboot.

Create New Queue Manager Listener for New Queue Manager

1.

Select Console Root ==> WebSphere MQ Services (local) ==> NMS_MGR.A ==> New ==> Listener.

This will invoke a dialog to create a new "listener" service. This dialog will have three tabs, General, Recovery, and Parameters.

•

The Parameters tab port number must be 1414.

•

The General tab startup type should be "Automatic".

2.

Click the Start button on the General tab.

3.

To check the status of the listener, select Console Root ==> WebSphere MQ Services (local) ==> NMS_MGR.A ==> Listener ==> Properties

Configure the MQ Client

Set Environment Variables

The environment configuration file (nms.rc), which is a data file listing Oracle Utilities Network Management System environment settings, should have the following:

export MQSERVER=SCH1/TCP/10.115.3.85

The environment configuration file must also have two variables set to locate the .TAB file for WebSphere MQ. The .TAB must be copied to the MQ client from the MQ server host as specified by these variables.

Examples:

export MQCHLLIB=/users/proj/MQ

export MQCHLTAB=AMQCLCHL.TAB

View this environment variable (to ensure that it’s correct) by typing in the following command: echo $MQSERVER

Test the Connection Between MQ Client and MQ Server

Test the Server Connection Channel (amqscnxc)

On the Unix command line, type in the following command:

/usr/mqm/samp/bin/amqscnxc -x 10.115.3.85 -c SCH1 NMS_MGR.A

where:

•

-x is the IP address of the MQ Server host

•

-c is the Server Connection Channel Name

•

the third parameter is the desired Queue Manager Name

Test ‘Putting’ a message from Server to Client (amqsputc)

On the Unix command line, type in the following command:

/usr/mqm/samp/bin/amqsputc NMS.A.FROMNMS Sample AMQSPUT0 starttarget queue is NMS.A.FROMNMS

<MSG-FROM-SVR>VOILA</MSG-FROM-SVR> Sample AMQSPUT0 end

The message should appear in the queue named NMS.A.FROMNMS which can be viewed on the client using the MQ Explorer GUI at:

Console Root ==> WebSphere MQ ==> Queue Managers ==> NMS_MGR.A ==>Queues ==> NMS.A.FROMNMS ==> Browse Messages

Test ‘Getting’ a Message on Client from Server (amqsgetc)

First "get" the message just written

/usr/mqm/samp/bin/amqsgetc NMS.A.FROMNMS Sample AMQSGET0 start message <<MSG-FROM-SVR>VOILA</MSG-FROM-SVR>> no more messages Sample AMQSGET0 end

Test ‘Putting’ a Message from Client to Server using WebSphere MQ GUI

1.

Select Console Root ==> WebSphere MQ ==> Queue Managers ==> NMS_MGR.A ==> Queues ==> NMS.A.TONMS ==> Put Test Message

2.

Paste the following into "Message Data":

<MSG-FROM-CLNT>VOILA</MSG-FROM-CLNT>

3.

Click OK.

The following message should be displayed: "The test message was put successfully (amq4016)".

Test ‘Getting’ a Message on Server from Client (amqsgetc)

On the Unix command line:

/usr/mqm/samp/bin/amqsgetc NMS.A.TONMS Sample AMQSGET0 start message <<MSG-FROM-CLNT>VOILA</MSG-FROM-CLNT>> no more messages Sample AMQSGET0 end

High Availability

The goal of the Oracle Utilities Network Management System MQ XML adapter redundancy is to provide assured message receipt and delivery between the Oracle Utilities Network Management System services and the WebSphere MQ queues. There are a number of availability approaches that could be utilized, with potentially different approaches being used for each system to be interfaced. The purpose of this section is to describe different availability approaches that can be used with the adapter.

Clustering

One approach for high availability is to utilize WebSphere MQ clustering on Windows where persistent queues would be used. The adapter is then responsible for maintaining connection to InterSys. All messages would be persisted to one physical disk location, where either redundant Oracle Utilities Network Management System Generic WebSphere MQ Adapter would have access to the same message.

Non-Redundant Queue Approach

This would be a classical implementation using WebSphere MQ. A single copy of the Oracle Utilities Network Management System Generic WebSphere MQ Adapter would be used to retrieve information from a single (non-redundant) set of message queues.

This approach is the simplest and most common way to implement WebSphere MQ queues for an application. However, a hard failure of the adapter or its server could result in message losses.

Synchronization Process

In the case in which both adapter servers are down, the Generic WebSphere MQ Adapter provides a synchronization process on startup by specifying -synchronize command line option. This will retrieve all events information from OPS and put them on the queue with topic_type = ‘TRBL_UPDATE’ in <PostSrsOutput_001> message with <srsOutputMsgType>1</srsOutputMsgType> and <description>SYNCHRONIZE</description>. This synchronization can also be triggered again by issuing the following command from the Unix server command prompt:

Action any.mq* synchronize

The synchronized messages will include the latest status of all active events and completed/cancelled events in the past N days, where N is the number of days since the adapter was last running.

Troubleshooting

High-level messages are typically used within Oracle Utilities Network Management System to permit one process to control another process. There are no special high-level messages that would be required for this adapter.

Note that doing an Action any.any stop will stop the adapter, which needs to be taken into consideration for administering the adapter when starting and stopping it.

Supported high level messages include the following:

•

report

•

debug <debug level>

•

stop

Example usage: Action any.mqseriesgateway report

Performance

This interface is intended to provide for high performance as needed to process frequent message exchange such as in the case of trouble calls during a storm. In order to provide optimum performance, there are aspects of both implementation and usage. Aspects of usage include:

1.

Sending multiple trouble calls together in a single message when possible will improve the call volume.

2.

Providing a valid device identifier (supply node) on each trouble call.

3.

Avoiding unnecessary queries within Oracle Utilities Network Management System, which might otherwise degrade overall system performance either due to locking, CPU utilization and/or disk access.

4.

Using a customer account (service account), or premiseId as apposed to the custDeviceIdx with a supply node, will slow down the overall performance of trouble call processing and potentially outage prediction.

The following aspects of implementation can optimize performance:

It is assumed that incoming XML messages are well formed, bypassing the validation step. It is assumed that the sender provided well-formed XML, which was transmitted using reliable communication mechanisms. The actual validation test is whether or not the code that internally parses a message can extract a sufficient set of parameters to make an InterSys request. XML that is not well formed will typically generate an error. It should also be noted that XML validation does not necessarily guarantee valid information provided by an external system. If this generates an error in the adapter, it will be generate an error.

Use of multiple threads within the adapter, permitting parallel processing. This makes it possible to process multiple requests concurrently, providing the potential to increase performance.

Functional Requirements

The purpose of this section is to describe the desired functionality. Key requirements include the following:

•

Get customer(s) query using fuzzy keys (as through call entry application).

•

Get customer outage status information, which would indicate whether or not a customer is part of an existing outage.

•

Get customer outage history, which would provide the available outage history for a customer who may have been part of an old outage event.

•

Create incident, to send trouble calls to Oracle Utilities Network Management System for outage analysis.

•

Add, remove, and update condition. One example of possible usage would be to get tags from SCADA for display within Oracle Utilities Network Management System.

•

Get conditions for a specified device as maintained within Oracle Utilities Network Management System.

•

Create, Delete, and Update customer information, as might typically be used by a Customer Information System (CIS) to maintain customer information within Oracle Utilities Network Management System. Support a mechanism that will provide a means of generating a large number of customer transactions to initially load the customer model.

•

Check interface/InterSys status, permitting an external system to see whether or not the adapter is currently active and whether or not Oracle Utilities Network Management System is active.

•

Report Current outage status to indicate current state of an outage.

•

Report Crew outage states to indicate crew events that may change the state of an outage in Oracle Utilities Network Management System.

•

Receive customer disconnect and reconnect indications to identify if the utility has purposely disconnect power or restored power for a customer.

•

Network trace including planned outage and current feeder request.

•

SQL Queries and Database transactions to get reports or manipulate specific customer specific tables.

•

Support for style sheet translation on incoming and outgoing XML messages.

•

Support for external notification when the status of a device changes such as open or close.

•

Synchronize outage status between Oracle Utilities Network Management System and external system.

•

Create area summary list

•

Create callback list

Design Overview

The general approach is to build an adapter process that passes messaging between the Isis and WebSphere MQ messaging systems. Messages sent and received using WebSphere MQ will be formatted in XML. The types of messaging that will be supported include the following:

•

Asynchronous publish from Oracle Utilities Network Management System to WebSphere MQ (using ‘fire and forget’ pattern)

•

Asynchronous publish from WebSphere MQ to Oracle Utilities Network Management System (using ‘fire and forget’ pattern)

•

Request/reply from WebSphere MQ to Oracle Utilities Network Management System (the requestor can process this either synchronously or asynchronously)

As the Oracle Utilities Network Management System currently supports a large number of messages internally, the principle of this interface is to externalize support for a key subset of those messages through the WebSphere MQ adapter.

Data Flows

Overview

The purpose of this section is to describe the information flows that are relevant to this interface. The details of each of these flows and associated XML formats are provided in the appendices.

All flows are formatted using XML, with specific XML definitions defined as to be consistent with Oracle Utilities Network Management System product direction. XML messages will provide well-formed XML, without a requirement for validation, as validity will be the responsibility of the sender. Consequentially, there is also no requirement for the specification of DTDs or XML Schema definitions. Specific XML requirements are defined in the appendixes of this document.

Create Incident

This is an asynchronous input to the adapter to report trouble calls. Internally the JMS::sendJMSinput method is used to send the trouble call to Oracle Utilities Network Management System. This interface supports a variety data that might be input on a trouble call.

This will be sent using an asynchronous fire and forget.

Adapter can also process fuzzy call with street intersection data. This requires att_street_segment and att_street_intersect tables to be populated.

Note: Performance is optimized when the customer supply node is identified.

Get Customer Outage Status

This is a request/reply interface that is used to obtain the current status of a customer. The information returned includes:

•

Whether or not the customer is part of an existing outage

•

Estimated restoration time

•

Whether or not customer is part of a planned outage

This will be processed using an asynchronous inquiry. It should be noted that several queries are required to collect this information, it will degrade overall performance in storm situation.

Get Customer Outage History

This is a request/reply interface that is used to obtain customer call and outage history.

•

Call history

•

Outage history

This message will be processed using an asynchronous inquiry. It should be noted that several queries are required to collect this information, it will degrade the overall performance in storm situation. This history is supply based on the current Ops database, and will not get history from any historical database.

Create, Delete, Update, Get Condition

This interface would be used to report tags and other types of conditions. Conditions are objects that describe and manage important information associated with objects that are defined within the Oracle Utilities Network Management System model. Subclasses of the "condition" class include "tag" and "note", or any other configured condition in Oracle Utilities Network Management System.

This message is an asynchronous input to the adapter.

Outage Status

This interface is an asynchronous output from the adapter used to publish SRS output messages. SRS output messages describe creation, update, and closure of information related to outages. If TRBL_ERT_UPDATE message type is configured in the mq_adapter_config table, then global ERT changes from Stormman will trigger <postSrsOutput_001> message with type = 20 to be published for each event. For performance considerations, type = 20 message only has limited information.

Create, Delete, Update, Get Customer

This is an asynchronous input interface used to report updates to the customer data model. These updates may be the addition, modification or deletion of a customer. To get information for an existing customer, the get verb is supported in order to retrieve this information. In the event of an update, only the modified information needs to be supplied. Internally this will use the DBS::sql method to perform updates to the appropriate tables that define the customer data model. It is assumed that CES_CUSTOMER and CUSTOMER_SUM are implemented as views, and the Oracle Utilities Network Management System MultiSpeak-based customer model is utilized.

This interface is implemented in a manner to provide extensions over the capabilities of MultiSpeak, including multiple meters and/or transformers for a service location. The interface uses the internal service point entity to manage these relationships.

Customer update can be configured to use separate DBService by using command line option -custdbsname < DBSNAME > to improve overall performance. This requires the server side to have an instance of DBService reserved for this purpose.

There is a new command line option available -custsqlbundle which will greatly improve the performance for DELETECREATE/CUSTOMER request.

Note: It will be necessary to have JMService update its internal cache periodically. This will be triggered by the adapter nightly by the defined recache period that is supplied to the adapter. The default value is 24 hours and can be changed through -recache < HOURS >. Re-cache can also be configured to run at specific hour and minute by specifying -recachehour < HOUR > and -recacheminute < MINUTE >. These two command line options will override -recache < HOURS > option. The recache function can be disabled by using -nosndrecache option.

SQL Transactions

This is an asynchronous input interface is used to send SQL transactions to Oracle Utilities Network Management System. This internally uses the DBS::sql method. This interface is activated by the - sql command line option.

WARNING: This interface, if activated, is a potential security issue in non-trusted environments, as it would be possible to execute destructive transactions against the Oracle Utilities Network Management System database.

WARNING: This interface, if activated and used inappropriately, can be a source of system performance degradation or denial of service. This would be the case if long duration transactions were run against the Oracle Utilities Network Management System database, especially if done against key Oracle Utilities Network Management System tables.

SQL Query

This is a request/reply interface that is used to perform an SQL query on Oracle Utilities Network Management System and return the resulting selection set. The DBS::query method is used internally. The returned XML is formatted using appropriate tags, using column names, and row delimiters.

WARNING: This interface, if activated and used inappropriately, can be a source of system performance degradation or denial of service. This would be the case if long duration queries were run against the Oracle Utilities Network Management System database, especially if done against key Oracle Utilities Network Management System tables.

Status Check

This is a request/reply interface that is used to check the status of the Generic WebSphere MQ Adapter.

Errors

Errors detected will be asynchronously reported on the defined error queue. An error queue will be as define per the reply queue for any out going message. If there is no reply queue, the default queue will be used to supply the error messages to.

Customer Disconnect / Reconnect.

This information flow is implemented as an asynchronous request for disconnecting or reconnecting customers, indicating which customers have had power disconnected or reconnected by the utility. The customers who have been disconnected will not be seen by Oracle Utilities Network Management System call taking applications, as these customers have purposely been disconnected by the utility for payment reasons. In order for these customers to be ignored from call taking applications that will be using the CreateIncident flow defined in this document, the checkCutoff flag for customers that call in should be used for JMService to be notified to check for the disconnected customers. If these systems know that the customers are disconnected, calls for these customers only need to use the checkCutoff flag.

Crew Outage Status Changes

The purpose of this section is to provide crew states that may or may not transition an outage state change in Oracle Utilities Network Management System. Oracle Utilities Network Management System currently provides crew state changes for an outage via a CrewMessage. The CrewMessage contains the following message types for crew messages. Each message type identified below also provides whether or no the message could change the status of the outage.

Crew Message Type

Classes APIs available in

Potentially generates outage state change

Description.

INVALID

None

NO

Invalid message was sent. Unsupported message for all crew APIs

SET_CONST

None

NO

Sets static constant(s) for the Crew class, which will make non-standard functionality of the crew classes be supported.

CLEAR_CONST

None

NO

Remove a static constant that has been set. This may make some supported functionality of the crew classes’ disabled.

AVAIL_FOR_OP

Crew

NO

UNAVAIL_FOR_OP

Crew

NO

CREATED

Crew

NO

DELETED

Crew

NO

EDITED

Crew

NO

ACTIVATED

Crew

NO

DEACTIVATED

Crew

NO

ASSIGNED

CrewAssignment

YES

UNASSIGNED

CrewAssignment

YES

DISPATCHED

CrewDispatch

YES

UNDISPATCHED

CrewDispatch

YES

RELOCATE

CrewDispatch

YES

AVAILABLE

Crew

NO

UNAVAILABLE

Crew

NO

ASSIGNMENT_CHANGED

CrewAssignment

YES

DISPATCH_CHANGED

CrewAssignment

YES

ARRIVED

CrewDispatch

YES

UNARRIVED

CrewDispatch

YES

TEMP_ZONE_CHANGE

Crew

NO

UPDATE_SCHEDULE

Crew

NO

SUSPENDED

CrewAssignment

YES

CASE_NOTES_INFO_CHANGED

Crew

NO

CREW_REQUEST_ADD

CrewRequest

NO

CREW_REQUEST_EDIT

CrewRequest

NO

CREW_REQUEST_DELETE

CrewRequest

NO

These changes may affect the status of the outage, or just the status of a crew. Via configuration of the mq_adapter_config table, any crew state change may trigger the creation of a PostSrsOutputStatus_001 XML message. This message will be identical in format to the PostSrsOutput_001 XML message, except that it will be triggered by the configure crew message type as previously defined. If the configuration for the crew message type is made, any queue can be used to put the PostSrsOutputStatus_001 message in.

Note: The crew message may not affect the current state transition of the outage, and may provide redundant data. In order to avoid un-necessary overhead of providing SRSOutput status information for non-required crew states, it is highly recommended that only the minimal crew states that are needed for the outage state changes are used in order to get the PostSrsOutputStatus_001 XML message. This flow will have to go to JMService to regenerate the outage information.

An example for configuring the receipt of a PostSrsOutputStatus_001 is provided below.

INSERT INTO mq_adapter_config VALUES ('OMS_OUTAGE_STATUS', 2,

'PostSrsOutputStatus_001',

'DISPATCHED',

'', '', 1);

In this example, if a message type of "DISPATCHED" is received by the adapter, JMService will (via JMS::getEventInfo()) be requested for the current event status of the outage. The outage status can be retrieved via the Crew with the current outage data; a PostSrsOutputStatus_001 XML message will be generated to send to the OMS_OUTAGE_STATUS queue. Note that any queue can be defined to publish the Outage Status to. This will be configurable based on the number of configuration parameters for the PostSrsOutputStatus_001 XML message. Whichever crew message types should trigger the creation of the XML message, each one (message type and put queue) will need to be identified and defined in the mq_adapter_config table. Please refer to PostSrsOutput_001 XML message for the data content of the PostSrsOutputStatus_001 message.

The purpose of this information flow is to provide crew outage status messages when ever a crew is Dispatched, Un-Dispatched, Assigned, or Un-Assigned from an event. In order to provide the crew outage status change for the events, this flow is required. This will be an asynchronous event that will provide the crew outage status changes to any interface that may require this information.

Sending Crew Updates / Getting Crew (Request / Reply) Information

When an external system needs to get crew details for one Crew, or all Crews, or the Crew needs to be indicated assigned, un-assigned, dispatched, un-dispatched, arrived, available, unavailable, active, in-active, or suspended from an event in or independent from an event in Oracle Utilities Network Management System; the external system will send a crew update message with the event id to Oracle Utilities Network Management System. The VERB of the CrewUpdate_001 XML message will indicate the state or action to be triggered by the message. Creating, deleting and editing crews is also supported by this flow.

Published Crew Information Updates to an External System

When a crew is assigned, un-assigned, dispatched, un-dispatched, arrived, suspended, created, deleted, or edited in Oracle Utilities Network Management System; the system will broadcast this information to any external system that would be interested in receiving this information about the crew.

Network Trace Includes Planned Outage Request and Current Feeder Request

Oracle Utilities Network Management System has the ability to send all supply nodes back for a specific device (planned outage request). Oracle Utilities Network Management System can also send back feeder, substation and control zone information back for a specific supply node (current feeder request). To enable this function, one line needs to be added to MQ_ADAPTER_CONFIG table and specify ‘-connectivitytrace’ command line option:

insert into mq_adapter_config values ('REQUEST_TRACE',3, 'TraceNetwork_001','TraceNetwork_001',null,'REPLY_TRACE',1);

Area Summary

The MQ Adapter will respond to a request for an area summary. The reply message will contain information that is available in the Performance Mart database. A synonym will be created to make this data available in the Ops database. The MQ Series Adapter will query this table and send back the information.

This will be a request/reply data flow. The external system must request an outage summary for the MQ Adapter to send a response. The areas that are to be summarized will exactly match some level(s) as defined in the Performance Mart database. The areas that are returned will be the Area Control Zones with recognized active outages. The control zone level of the included areas can be configured through the command line.

Callback List

The callback list message will use the same body as the Post SRSoutput message. It will have a different noun and verb.

There are two types of callback list. One contains in the incident list all of the callers who have requested a callback. This message will have a verb of REQUESTED and a noun of CALLBACKLIST. The second type of callback list is a relatively random sampling of customers downstream of the restored device. This message will have a verb of SUBSET and a noun of CALLBACKLIST.

There are configurable parameters that will set the maximum and minimum percentage of affected customers who will be included in the SUBSET callback list. The maximumCallbackSample and minimumCallbackSample for the subset callback can be set through the srs_rules table. These parameters will default to 50 and 4 percent respectively if not configured explicitly. Both types of callback lists use the same format found in PostSrsOutput_001.xsd.

Information Model

This section provides an overview of the logical information model supported by this interface. The key objects supported by this interface include:

•

Customers, which are defined using accounts, service locations and meters. This model is based upon the MultiSpeak model. Typically, as a practical note, the custId identifier may in fact be the same as the account number. Some extensions to the MultiSpeak model are used as required to address issues that are otherwise not addressed by MultiSpeak. The support of a bulk load process that reads an XML file, with defined customers to create the model. This process (createSql) can be run to generate the SQL to be run on the production servers, or can directly create the customers.

•

Trouble calls are also referred to as incidents with in Oracle Utilities Network Management System. An incident is typically related to a customer, who in turn is related to a device. In the absence of a correlation to a device, a trouble call is classified as a ‘fuzzy’ call, which differentiates it from a call that can be directly correlated to the electrical distribution network.

•

Outages, which are a consequence of the correlation of incidents. Outages are one form of an event that is managed by JMService. Some events are non-outage events, such as power quality. The type of call that is provided can identify such non-outage and outage events. Each call needs to be identified with a trouble code, which will determine the type of call that JMService will generate with in Oracle Utilities Network Management System.

•

Devices, which are part of the electrical distribution network. Customers, outages and conditions may have relationships to devices. Typically customers are related to transformer devices. Outages are typically related to switch, fuse or transformer devices.

•

Conditions (which can be specialized within Oracle Utilities Network Management System for the management of information such as tags, notes, etc.)

•

SQL queries, result sets and transactions.

•

Customer disconnections and reconnections for indicating customers who have been purposely removed from Service by the utility.

•

Crew Outage States that will identify outage states that change as a result of a crew action. For example a crew that has been dispatched, assigned, or suspended from outage work would correlate to an action that may trigger an outage state change in Oracle Utilities Network Management System.

The information described by these models is formatted using XML for the purposes of exchange through this interface. The following table describes tags that are used in the XML definitions, and how they relate to the information model within Oracle Utilities Network Management System. The corresponding types used in these models are I = Integer, S = String, T = TimeStamp, C = Single Character, and F = floating point.

SRS Output and SRS Output Status Message Tags

Tag

Parent entity

Description

Type

PostSrsOutput

PostSrsOutput_001

The start of the SRS Output message

S

PostSrsOutputStatus

PostSrsOutputStatus_001

The start of the crew outage status message.

S

srsOutputMsgType

PostSrsOutput, PostSrsOutputStatus, outage

Type of SRS output message:

1=Create outage condition and alarm

2=Remove outage condition and alarm

3=Change outage condition or alarm

4=Send a fuzzy alarm

5=Create incident

6=Clear incident

7=Priority Call groups to existing DO

8=A Pending Cancel

9=Reschedule Meet or Outage

11=Send an unassigned alarm

12=Remove all "incident" alarms for an event

13=crew has been removed AND the update trouble button on the picklist has been selected

14=update trouble button on the picklist has been selected

15=this message tells the viewer not to display the outage any more

17=the secondary SRS is now up and running

18=clear case note message

20=Estimated assessment/restore time values updated

21=damage report updated or created

22=update callback information

23=Callback is requested for an event

24=AMR interface message

25=AMR interface message

99=Trouble Clear

I

district

PostSrsOutput, PostSrsOutputStatus, outage

District name of the outage device

S

office

PostSrsOutput, PostSrsOutputStatus, outage

Office name of the outage device

S

circuit

PostSrsOutput, PostSrsOutputStatus, outage

Circuit name of the outage device

S

feeder

PostSrsOutput, PostSrsOutputStatus, outage

Feeder name of the outage device

S

Ncg

PostSrsOutput, PostSrsOutputStatus, outage

ID of the control zone of the outage device

I

partition

PostSrsOutput, PostSrsOutputStatus, outage

Partition ID typically identifies the map sheet on which a device is associated

I

appliedRule

PostSrsOutput, PostSrsOutputStatus, outage

Rule number used by SRS to determine outage device

I

numb

PostSrsOutput, PostSrsOutputStatus, outage

Internal identifier for each outage record

I

ruleSet

PostSrsOutput, PostSrsOutputStatus, outage

Name of active rule set used by SRS to process outage

S

eventCls

PostSrsOutput, PostSrsOutputStatus, outage

Event class. Class 800 indicates an outage event. Part of the event handle.

I

eventIdx

PostSrsOutput, PostSrsOutputStatus, outage

Event index, part of the event handle that uniquely identifies event in conjunction with the eventCls.

I

eventApp

PostSrsOutput, PostSrsOutputStatus, outage

Event app, part of the event handle that uniquely identifies event in conjunction with the eventCls and eventIdx.

I

alarmCls

PostSrsOutput, PostSrsOutputStatus, outage

Alarm class, part of alarm handle. Used to uniquely identify rows on work agenda

I

alarmIdx

PostSrsOutput, PostSrsOutputStatus, outage

Alarm index, part of alarm handle. Used to uniquely identify rows on work agenda

I

deviceCls

PostSrsOutput, PostSrsOutputStatus, outage

Class or outage device. Identifies the type of device that failed.

I

deviceIdx

PostSrsOutput, PostSrsOutputStatus, outage

Used in conjunction with the deviceCls to form the device handle, which uniquely identifies a device.

I

deviceAlias

PostSrsOutput, PostSrsOutputStatus, outage

Name of outage device, as defined in the ALIAS_MAPPING table.

S

deviceApp

PostSrsOutput, PostSrsOutputStatus, outage

Used in conjunction with the deviceCls and deviceIdx to form the device handle, which uniquely identifies a device.

deviceApp

cause

PostSrsOutput, PostSrsOutputStatus, outage

Outage cause (TROUBLE_CALL, FAULT_INDICATOR or blank)

S

description

PostSrsOutput, PostSrsOutputStatus, outage

Short description based on status

S

troubleCode

PostSrsOutput, PostSrsOutputStatus, outage

Entered trouble code or combination from all calls

S

troubleQueue

PostSrsOutput, PostSrsOutputStatus, outage

Dispatcher queue for outage

S

status

PostSrsOutput, PostSrsOutputStatus, outage

Alarm state name

S

operatorComment

PostSrsOutput, PostSrsOutputStatus, outage

Operator entered comment

S

tags

PostSrsOutput, PostSrsOutputStatus, outage

Y if tags exist

N if no tags exist

X if tags are not checked

C

estSource

PostSrsOutput, PostSrsOutputStatus, outage

Source of estimated restoration time:

C=crew (manually entered)

S=Storm Management (regular)

G=Storm Management globally applied ERT

D=Storm Management globally applied ERT delay

P=Storm Management non-published ERT

O=Storm Management (crew dispatched/onsite)

M=Storm Management calculated ERT exceeded allowed maximum

I=Initial ERT

N=none

C

externalId

PostSrsOutput, PostSrsOutputStatus

Identifier for event supplied by an external system.

I

crewId

PostSrsOutput, PostSrsOutputStatus, outage

Crew(s) assigned to outage

I

firstIncTime

PostSrsOutput, PostSrsOutputStatus, outage

Time of first reported incident.

T

firstCrewTime

PostSrsOutput, PostSrsOutputStatus, outage

Time of first dispatched crew.

T

crewOnSiteTime

PostSrsOutputStatus

Time of crew arrival

T

estRestTime

PostSrsOutput, PostSrsOutputStatus, outage

Estimated restoration time.

T

outageTime

PostSrsOutput, PostSrsOutputStatus, outage

Time the outage began.

T

jobCompletionTime

PostSrsOutput, PostSrsOutputStatus, outage

Time outage was completed.

T

restoreTime

PostSrsOutput, PostSrsOutputStatus, outage

Time the outage was restored.

T

srsCondStatus

PostSrsOutput, PostSrsOutputStatus, outage

Outage status codes:

0=no outage

1=probable service outage

2=probable device outage

3=real service outage

4=real device outage

7=non outage

8=critical meet

9=future meet

10=confirmed service outage

11=confirmed secondary outage

12=additional alarm

13=probable momentary outage

14=real momentary outage

15=planned outage

I

condPhases

PostSrsOutput, PostSrsOutputStatus, outage

Bitmask to identify affected phases

I

customersOut

PostSrsOutput,

PostSrsOutputStatus,

outage

Number of customers affected by an outage.

I

srsPriority

PostSrsOutput, PostSrsOutputStatus, outage

Number of priority calls, may be redefined by configuration

I

custCall

PostSrsOutput, PostSrsOutputStatus, outage

Number of customers affected by an outage that have called.

I

priW

PostSrsOutput, PostSrsOutputStatus, outage

Number of wire related calls, may be redefined by configuration

I

priSW

PostSrsOutput, PostSrsOutputStatus, outage

Number of service wire related calls, may be redefined by configuration

I

priP

PostSrsOutput, PostSrsOutputStatus, outage

Number of pole problem calls, may be redefined by configuration

I

priE

PostSrsOutput, PostSrsOutputStatus, outage

Number of emergency calls, may be redefined by configuration

I

custCrit

PostSrsOutput, PostSrsOutputStatus, outage

Number of affected critical customers

I

crit1

PostSrsOutput, PostSrsOutputStatus, outage

Number of category 1 customers that called, as determined by configuration

I

crit2

PostSrsOutput, PostSrsOutputStatus, outage

Number of category 2 customers that called, as determined by configuration

I

crit3

PostSrsOutput, PostSrsOutputStatus, outage

Number of category 3 customers that called, determined by configuration

I

critK

PostSrsOutput, PostSrsOutputStatus, outage

Affected category K (KEY) customer, may be redefined by configuration

I

critC

PostSrsOutput, PostSrsOutputStatus, outage

Affected category C (CRITICAL) customer, may be redefined by configuration

I

critD

PostSrsOutput, PostSrsOutputStatus, outage

Affected category D customer, may be redefined by configuration

I

critTot

PostSrsOutput, PostSrsOutputStatus, outage

Total number of critical customers, recognizing that a customer is counted only once even though it may belong to more than one category

I

revenue

PostSrsOutput, PostSrsOutputStatus, outage

Revenue of the total customers from customer_sum

revenue

customerName

PostSrsOutput, PostSrsOutputStatus, outage

Used for fuzzy calls

S

addrBuilding

PostSrsOutput, PostSrsOutputStatus, outage

Used for fuzzy calls

S

addrStreet

PostSrsOutput, PostSrsOutputStatus, outage

Used for fuzzy calls

S

addrCity

PostSrsOutput, PostSrsOutputStatus, outage

Used for fuzzy calls

S

customerPhone

PostSrsOutput, PostSrsOutputStatus, outage

Used for fuzzy calls

S

xRef

PostSrsOutput, PostSrsOutputStatus, utage

X reference coordinate

F

yRef

PostSrsOutput, PostSrsOutputStatus, outage

Y reference coordinate

F

sheetNum

PostSrsOutput, PostSrsOutputStatus, outage

Number of switching sheet associated with a planned outage.

I

dispAddress

PostSrsOutput, PostSrsOutputStatus, outage

Dispatch address, first incident if probable service outage, feeder name if no incidents or probable device outage

S

groupType

PostSrsOutput, PostSrsOutputStatus, outage

GRP is manually grouped, REL if related

S

hasClue

PostSrsOutput, PostSrsOutputStatus, outage

Y if one or more incidents for this outage has a clue

C

ctrlZoneName1

PostSrsOutput, PostSrsOutputStatus, outage

Control zone name, level 1

S

ctrlZoneName2

PostSrsOutput, PostSrsOutputStatus, outage

Control zone name, level 2

S

ctrlZoneName3

PostSrsOutput, PostSrsOutputStatus, outage

Control zone name, level 3

S

ctrlZoneName4

PostSrsOutput, PostSrsOutputStatus, outage

Control zone name, level 4

S

ctrlZoneName5

PostSrsOutput, PostSrsOutputStatus, outage

Control zone name, level 5

S

ctrlZoneName6

PostSrsOutput, PostSrsOutputStatus, outage

Control zone name, level 6

S

devClsName

PostSrsOutput, PostSrsOutputStatus, utage

Name of class of outage device

S

AffectedSupplyNodeList

PostSrsOutput, PostSrsOutputStatus, outage

The affected list of supply nodes

S

snd

AffectedSupplyNodeList

The affected supply node.

I

AffectedDeviceIdList

PostSrsOutput, PostSrsOutputStatus

The indicator for the device ids for the affected transformers.

S

devId

AffectedDeviceIdList

The affected device id for the transformer.

S

whoCompleted

PostSrsOutput, PostSrsOutputStatus, outage

The name of the user who completed the outage.

S

whoResponsible

PostSrsOutput, PostSrsOutputStatus, outage

The name of the user who is currently responsible for the event.

S

whoAcknowledged

PostSrsOutput, PostSrsOutputStatus, outage

The user who acknowledged the event.

S

AffectedPremiseIdList

PostSrsOutput, PostSrsOutputStatus, outage

This list is used as an option for systems that cannot have a transformer relationship to a customer. This is a last resort and is highly recommended not to be used because of performance impacts when using this option

S

premiseId

PostSrsOutput, PostSrsOutputStatus, outage

The customer’s premise id, or serv_loc_id in the customer model

S

AffectedDeviceIdList

PostSrsOutput, PostSrsOutputStatus

S

devId

PostSrsOutput, PostSrsOutputStatus

S

CaseNote

PostSrsOutput, PostSrsOutputStatus, Outage

S

caseNoteText

CaseNote

Text for the case note.

s

Note: The following tags appear in <PostSrsOutput_001> message only if the ‘-includeincident’ command line option is used. Oracle recommends against using this option.

IncidentList

PostSrsOutput, PostSrsOutputStatus, outage

Incident

IncidentList

incTroubleCode

Incident

S

incDevice

Incident

S

incAccount

Incident

S

incCustDeviceCls

Incident

I

incCustDeviceIdx

Incident

I

incCustName

Incident

S

incAddress

Incident

S

incStreet

Incident

S

incCity

Incident

S

incPhone

Incident

S

incIncidentTime

Incident

S

incComment

Incident

S

incCallbackLate

Incident

S

incExternaId

Incident

S

incCallCancel

Incident

S

incLifeSupport

Incident

S

incCustPriority

Incident

S

incMeterId

Incident

S

incGeneralArea

Incident

S

incCustOrderNum

Incident

S

incDrvInst

Incident

S

incCallbackRequest

Incident

S

incCustCritical

Incident

S

incAlternatePhone

Incident

S

incCserName

Incident

S

incXRef

Incident

F

incYRef

Incident

F

incEventCls

Incident

I

incEventIdx

Incident

I

Note: Many values, names and usages are configurable and vary between implementations. The details and description of configuration options are outside the scope of this document.

Note: For performance reasons the type 20(TRBL_ERT_UPDATE) message contains limited information. The available fields are: <srsOutputMsgType>, <eventIdx>, <estRestTime> and <estSource>. Other fields are either NULL or 0.

Customer Message Tags

Refer to the Oracle Utilities Network Management System Customer Data Model specification.

Note: The bulk load of customers can be accomplished by running the createSql.exe file that will create .sql file to be run through ISQL.ces, which will populate the customer model. The createSql file should be provided the following command line options to create the sql. (IE. CreateSql -xmlfile create_customers.sql -outputfile product_customer_data.sql.) The -writetodb command can be provided to write the customers directly through to the database with out having to run ISQL.ces < product_customer_data.sql.

Trouble Call Message Tags

Tag

Parent

Description

Incident

troubleCode

Incident

device

Incident

account

Incident

custDeviceCls

Incident

custDeviceIdx

Incident

name

Incident

address

Incident

city

Incident

phone

Incident

incidentTime

Incident

comment

Incident

callbackLate

Incident

externalId

Incident

callCancel

Incident

Deprecated and project specific

lifeSupport

Incident

custNone

Incident

custPriority

Incident

custPhoneArea

Incident

callId

Incident

meterId

Incident

custLastName

Incident

generalArea

Incident

custOrderNum

Incident

drvInst

Incident

addrBuilding

Incident

addrStreet

Incident

addrCity

Incident

This is also used in fuzzy calls to get a better indication of which intersection point should be used.

meetTime

Incident

meetType

Incident

cidAlias

Incident

powerUp

Incident

cancelCall

Incident

Deprecated and project specific

callbackRequest

Incident

callbackTime

Incident

custIntrX

Incident

custIntrY

Incident

updateExistingInc

Incident

custCritical

Incident

alternatePhone

Incident

userName

Incident

checkCutoff

Incident

xRef

Incident

yRef

Incident

custPhoneUpdate

Incident

streetNameA

Incident

Used to indicate a street name for a fuzzy call

streetNameB

Incident

Used to indicate a street name for a fuzzy call.

addressNumber

Incident

Used for the street number, to find in an address range for it in the range of an intersection point. The street number is <> the range.

addrState

Incident

This is also used in fuzzy calls to get a better indication of which intersection point should be used.

addrPostCode

Incident

This is also used in fuzzy calls to get a better indication of which intersection point should be used.

premiseId

Incident

This is the premiseId (serv_loc_id) for the customer. This XML tag should only be used as a last option if supply node or customer account number cannot be used with a call. This field incurs additional performance issues if used, and is highly recommended not to use it as an option for processing trouble calls.

controlZoneName

Incident

If the control zone name is passed with the call, it will be used to append control zone information with the call to be placed at this control zone within JMService. This would be useful in cases where customers are not yet modeled in Oracle Utilities Network Management System, and calls would want to be placed as close to the lowest control zone as possible.

eventCls

Incident

Related event class. Used for canceling or updating outages.

eventIdx

Incident

Related event index. Used for canceling or updating outages.

Crew Message Tags

Tag

Parent

Description

CrewList

DATAAREA

Crew

CrewList

crewId

Crew

crewContact

Crew

crewType

Crew

crewPagerNumber

Crew

crewMobileNumber

Crew

crewMdt

Crew

crewSupervisor

Crew

crewCenter

Crew

controlZone

Crew

crewStatus

Crew

crewVehicleList

Crew

crewVehicle

crewVehicleList

crewVehicleId

crewVehicle

crewVehicleType

crewVehicle

crewActive

Crew

crewAvailable

Crew

crewNcgCls

Crew

crewNcgIdx

Crew

userName

Crew

eventCls

Crew

eventIdx

Crew

crewMemberList

Crew

CrewMember

crewMemberList

crewMemberName

CrewMember

crewMemberTechId

CrewMember

crewMemberType

CrewMember

Crew Outage Status Changes

Refer to the SRS Output Message tags, as the DATA Content tags will be the same for this flow.

Configure Queues for Required Data Flows

Any data flows to be used require WebSphere queues to be created and configured. The default queues for the supported data flows are listed below. While these queues would need to be created, the base product configuration already supports these data flows.

•

Create Incident

OMS_TROUBLE_CALL

•

Get Customer Outage Status

OMS_CUST_STATUS

OMS_CUST_STATUS_REPLY

•

Get Customer Outage History

OMS_CUST_HISTORY

OMS_CUST_HISTORY_REPLY

•

Condition Updates and Queries

OMS_CONDITION_DATA

•

Outage Status

OMS_TROUBLE_CALL_STATUS

•

Customer Updates and Queries

OMS_CUSTOMER_DATA

OMS_CUSTOMER_DATA_REPLY

•

SQL Transactions

OMS_SQL

OMS_SQL_REPLY

•

Adapter Status Check

OMS_GATEWAY_STATUS

•

SQL Query

OMS_EXECUTE_QUERY

OMS_EXECUTE_QUERY_REPLY

•

Customer Disconnect / Reconnect

OMS_CUSTOMER_DISCONNECT

OMS_CUSTOMER_DISCONNECT_REPLY

•

Crew Outage Status Changes

OMS_TROUBLE_CALL_STATUS

•

Crew Updates / Crew Requests

OMS_UPDATE_CREW

OMS_UPDATE_CREW_REPLY

•

Published Crew Updates

OMS_TROUBLE_CALL_STATUS

•

Network Trace

OMS_TRACE_NETWORK

OMS_TRACE_NETWORK_REPLY

•

Area Summary

OMS_AREA_SUMMARY

OMS_AREA_SUMMARY_REPLY

•

Callback List

OMS_TROUBLE_CALL_STATUS

MQ_ADAPTER_CONFIG Table Definition

The following is the table definition for the MQ_ADAPTER_CONFIG table that defines the queues that will be used by the adapter. This is a configuration table that is loaded at startup.

Column

Type

Description

name

VARCHAR2(32)

Name of queue put queue for the reply queue, and for async output queues.

Q_type

INTEGER

Queue type: 1=async input, 2=async output, 3=request/reply

topic

VARCHAR2(32)

Subject matter for queue, specified in terms of document types

topic_type

VARCHAR2(32)

Message types for filtering specific document types.

translation

VARCHAR2(128)

Name of XSL translation to be applied, default=NULL

reply

VARCHAR2(32)

Name of reply queue (needed when qtype=3), but will be overridden if reply queue is specified on a request message

total_threads

INTEGER

Number of threads processing messages. Note: for async output queues the total_number is always set to 1.

The specific information topics to be supported include the following:

•

PostError_001

•

PostSrsOutput_001

•

GetCustomerHistory_001

•

GetCustomerStatus_001

•

CreateIncident_001

•

ExecuteQuery_001

•

ExecuteTransaction_001

XSL Transformation Files

If XSL transformations are to be used by the interface, these files must be placed in a file directory on the adapter server. The directory path must be supplied on the adapter command line.

Default CES_GET and CES_PUT Queues

CES_PUT and CES_GET queues are the default queues for sending and receiving each kind of Generic WebSphere MQ Adapter message. Both queues needed to be created, but they can be renamed through command line options defined above.

Trigger of Broadcasting Messages

Among information flows discussed in section 4, outage status flow <PostSrsOutput_001> and crew outage status change flow <PostSrsOutputStatus_001> are two broadcasting flows triggered by some actions happened in the Oracle Utilities Network Management System. Generally speaking, <PostSrsOutput_001> message will be generated every time when an internal srsoutput message is broadcasted. <PostSrsOutputStatus_001> message will be generated every time when an internal crew message is broadcasted. But the adapter configuration can selectively broadcast those messages based on the value in the mq_gateway_config.topic_type column which are internal srsoutput message and crew message type values.

Because Oracle Utilities Network Management System is highly configurable, it is pretty hard to define what kind operation to trigger internal srsoutput and crew messages and it is out of the scope of this document. Please reference corresponding SRS document for details of internal srsoutput and crew message.

SCADA Measurements

This chapter includes the following topics:

•

Introduction to scadapop

•

Configuration

•

Recaching Measurements

•

Information Model

Introduction to scadapop

The Oracle Utilities Network Management System (NMS) can accept updates from a variety of external (outside) Supervisory Control And Data Acquisition (SCADA) systems. Multiple external SCADA systems can be connected to a single NMS instance. If necessary a different adapter can be used for each external SCADA a utility wishes to connect to. For example one SCADA system might use the ICCPAdapter, one the generic NMS SCADA adapter (RTAdapter) another might use a project specific or custom SCADA adapter. In all cases the NMS objects and attributes that can be updated from each external SCADA adapter must be defined before NMS can accept input from these SCADA systems. This section describes one mechanism for populating the necessary configuration tables with objects and attribute information so the SCADA adapter can pass information into NMS.

Configuration

RDBMS Configuration

Tables involved:

•

scada_measurements_st : standard SCADA measurements configuration table. This is a staging table used by DDService for populating the production SCADA measurement tables.

•

digital_measurements: production SCADA measurements table for digital measurements. Only DDService should write to this table.

•

analog_measurements : production SCADA measurements table for analog measurements. Only DDService should write to this table.

•

scada_ids : RTAdapter SCADA definition table.

•

scada_points : optional model build attribute table that is used by the scadapop executable - to help populate the scada_measurements_st staging table. If you want to use scadapop - you need to populate the scada_points table.

Note: The scada_points table only needs to be populated if using scadapop. It is normally populated via device class driven attribute population during the model build process.

To configure the standard SCADA input RDBMS staging table (scada_measurements_st) using scadapop follow the following steps:

Specify which model devices have SCADA (via scada_points table. The scada_points table is generally populated via attribute population during model build construction/update but can be populated after the fact by a custom (project specific) process. A generalization is made that each defined "SCADA" provides a consistent set of attributes for a given NMS object. For example SCADA_A might be defined to always provide a digital "status" and 3 analog values - A_Phase_Amps, B_Phase_Amps and C_Phase_Amps. SCADA_B might be defined to always provide digital "status" and 6 analog values. This generalization is made to simplify configuration. It is generally acceptable if the external SCADA system does not actually provide all SCADA measurements for all configured points - within reason - to simplify configuration.

There are generally two options for populating the scada_points table:

1.

Populate scada_points RDBMS table via model build device attribute configuration.

This option involves populating two attributes in the scada_points table:

•

scada_name : the name of the SCADA, as defined in scada_ids.scada_name (for example, RTAdapter).

•

rtu_alias : SCADA unique identifier for reporting field device.

The rtu_alias must only be unique within a particular SCADA (scada_name). An individual rtu_alias may well report multiple analog values (AMP, VOLT, KVAR, etc.) as well as digital and/or status values.

To set up the scada_points table as a standard Network Management System attribute table generally involves the following RDBMS tables:

•

device_attributes : generic model build attribute configuration table.

•

scada_points : SCADA project specific attribute table.

2.

Populate the scada_points RDBMS table via a project specific (post model build) process. This might involve selecting all the devices of a specific class from the alias_mapping table - for example.

Once the scada_points table is populated, the scadapop program can be used to expand the information in the scada_points table to fully populate the more generic scada_measurements_st staging table (see notes below for how to use scadapop).

Note: A given "field device" corresponds to a given scada_points.rtu_alias and would typically be a breaker of some kind (often reporting both device status and multiple analog values). It could also be a transformer reporting analog values with or without status or some other class of device with SCADA data.

Below are two example device_attributes table entries to support population of the scada_points table via standard model build attribute population (option 1 above). For more information on this process, please consult the Network Management System Model Build process documentation. These are examples only.

INSERT INTO device_attributes (

DEVICE_CLS,

ATTR_NAME,

TABLE_NAME,

COLUMN_NAME,

ATTR_TYPE,

LENGTH,

REQUIRED,

MAINTENANCE

) VALUES (

143, 'Rtu_Id', 'scada_points', 'rtu_alias', 3,

32, 'N', 'Y');

COMMIT WORK;

INSERT INTO device_attributes (

DEVICE_CLS,

ATTR_NAME,

TABLE_NAME,

COLUMN_NAME,

ATTR_TYPE,

LENGTH,

REQUIRED,

MAINTENANCE

) VALUES (

143, 'Rtu_Desc', 'scada_points', 'scada_name', 3,

32, 'N', 'Y');

COMMIT WORK;

Example data field explanation:

143Class of device which may report SCADA data. + project specific

scada_pointsAttribute table to populate.

Rtu_IdAttribute id as appears in *.mb file for device.

+ project specific - SCADA device id (rtu_alias).

rtu_alias scada_points column to populate with Rtu_Id value.

Rtu_DescAttribute id as appears in *.mb file for device.

+ project specific - SCADA system name (scada_name).

scada_namescada_points column to populate with Rtu_Desc value.

3 Data type of string (ASCII field); always set to 3 for a string

32Maximum length of this attribute string (bytes)

+ project specific per scada_id len for SCADA.

'N' Required attribute

+ project specific - generally (N)o.

'Y'Set to Y for model builder maintenance. Set this to "Y" if you want the Model Builder to maintain this table via the incremental model build process.

Once the scada_points table is populated the scadapop program can be used to expand this information to fully populate the more generic (required) scada_measurements_st staging table.

Run scadapop -h to get command line options. In general:

•

scadapop [-debug [n]] -partition <n> -initFile <file>

•

debug <n> - Turns debug on <to level n>

•

partition n - Populate partition n (0 = all partitions)

•

initFile - file - rti.dat initialization file (see below)

The rti.dat file is the configuration file used by the scadapop program. Based on data in this file, and entries in the scada_points table, scadapop populates the standard SCADA configuration (RDBMS) staging table:

•

scada_measurements_st

The scada_points table contains a record (row) for each device in the Network Management System model that has SCADA information associated with it. Each record has a "scada_name" column which, in order to populate one of the measurements tables, must match a "SCADA_Name" keyword in this configuration file. Where there is a match a row is populated in the scada_measurements_st staging table for each defined attribute.

•

Each defined Digital attribute for a given SCADA_Name has a measurement_type of "D" in the scada_measurements_st table.

•

Each defined Analog attribute for a given SCADA_Name has a measurement_type of "A" in the scada_measurements_st table.

The syntax rules for the rti.dat file are:

•

Lines with a leading # are treated as comments (ignored).

•

Leading blank space is ignored.

•

Only the first two non-blank tokens on a line are recognized.

•

The remaining tokens are treated as comments (ignored).

•

Blank lines ok. (ignored)

•

Attributes are associated to last defined SCADA_Name.

The following keywords exist - they must match EXACTLY:

•

SCADA_Name:

•

Analog:

•

Digital:

Note: The colon ":" character is a keyword delimiter. The colon must appear as the first character after the keyword in order for the keyword to be recognized.

Example rti.dat file:

SCADA_Name: USA

Digital: status (Switch Position or "Status")

Analog: Amps_A

Analog: Amps_B

Analog: Amps_C

Analog: Volts_A

Analog: Volts_B

Analog: Volts_C

Example scadapop commands:

scadapop -partition 0 -initFile ${CES_DATA_FILES}/OPAL_rti.dat

scadapop -partition 3111 -initFile rti.dat -debug

Recaching Measurements

To load the SCADA measurements staging table into the production (run-time) SCADA measurements tables, the following command must be run:

UpdateDDS -recacheMeasurements

When this command is invoked, DDService will merge the scada_measurements_st table into the analog_measurements and digital_measurements tables (adding and removing rows as necessary) and load the updated analog_measurements and digital_measurements tables into memory.

When new measurements are added, all fields in the production measurements table are populated from the staging table.

When existing measurements are updated, all fields are copied from the staging table except the following columns because these columns can contain operator entered data (operator override values for example) - and should not be overwritten. Indeed this is the primary reason for using the staging table - to avoid overwriting these run-time columns:

•

QUALITY

•

VALUE

•

ACTIVE

Information Model

Database Schema

SCADA_IDS Database Table

The schema for this table is defined in ces_schema_scada.sql file.

The script, OPAL_scada_ids.sql, populates generic SCADA sources for the OPAL model. A source is any SCADA system that can provide information to the adapter. There could be one SCADA source defined for each of multiple SCADA vendors, or a utility may choose to divide their territory into multiple regions, with each region acting as a separate SCADA source. Each SCADA source must have a name as well as a unique integer ID.

SCADA_IDS

Column

Data Type

Description

ID

NUMBER

Numeric identifier for each "SCADA source" that we want RTI to process.

SCADA_NAME

VARCHAR2(32)

Name for the SCADA source

ADAPTER_TYPE

VARCHAR2(32)

Adapter type for this SCADA source.

ACTIVE

VARCHAR2(1)

Is the adapter active (Y/N)

SCADA_POINTS Database Table

The SCADA_POINTS table contains a row for each device in the Oracle Utilities Network Management System operations database that has SCADA information associated with it. Each record has a "scada_name" column which, in order to populate one of the measurements tables, must match a "SCADA_Name:" keyword in the rti.dat configuration file (see notes above for example rti.dat population). Where there is a match, a row is populated in the appropriate (digital or analog) measurements table for each defined attribute.

The SCADA_POINTS table is normally populated via device driven attribute population during the model build process. It is a staging table for the RTI population process. It is not accessed during adapter execution.

The schema for this table can be found in the file ces_retain_scada.sql

SCADA_POINTS

Column

Data Type

Description

H_CLS

SMALLINT

Object handle class

H_IDX

INTEGER

Object handle index

SCADA_NAME

VARCHAR2(32)

SCADA system name (Rtu_Desc)

RTU_ALIAS

VARCHAR2(32)

SCADA point name (Rtu_Id)

PARTITION

INTEGER

Partition of this object

BIRTH

DATE

Date object activated into the model

BIRTH_PATCH

INTEGER

Patch which activated this object

DEATH

DATE

Date object de-activated into the model

DEATH_PATCH

INTEGER

Patch which de-activated this object

ACTIVE

VARCHAR2(1)

Active flag (Y/N)

SCADA_MEASUREMENTS_ST Database Table

The scada_measurements_st table is a staging table used to help populate the analog_measurements and digital_measurements (production) tables. The schema for this table can be found in the file ces_retain_scada.sql.

SCADA_MEASUREMENTS_ST

Column

Data Type

Description

H_CLS

SMALLINT

Object handle class

H_IDX

INTEGER

Object handle index

PARTITION

INTEGER

Object partition

ATTRIBUTE

SMALLINT

Data attribute index (from ATTRIBUTES table)

TTL

SMALLINT

Time-To-Live Value

LIMIT_GROUP_ID

INTEGER

Object limit group

RTI_ALIAS

VARCHAR2(128)

RTI device measurement name

RTI_ALIAS_A

VARCHAR2(128)

RTI device measurement name for phase A. Only applies for digital measurements and only used by the MultiSpeak SCADA adapter.

RTI_ALIAS_B

VARCHAR2(128)

RTI device measurement name for phase B. Only applies for digital measurements and only used by the MultiSpeak SCADA adapter.

RTI_ALIAS_C

VARCHAR2(128)

RTI device measurement name for phase C. Only applies for digital measurements and only used by the MultiSpeak SCADA adapter.

SCADA_ID

INTEGER

SCADA source identifier - matches scada_ids.id

RTU_ID

VARCHAR2(32)

RTU ID - unique name within SCADA system.

QUALITY

INTEGER

Quality code

VALUE

FLOAT

Manual Replace Value

UPDATE_FLAG

INTEGER

Manual Replace Flag

ICCP_OBJECT

VARCHAR2(32)

ICCP mms object name

DISPLAY_ID

VARCHAR2(64)

ID for display call up

CONTROLLABLE

VARCHAR2(1)

Is this row controllable

ACTIVE

VARCHAR2(1)

Is this row active

SOURCE

VARCHAR2(33)

Source of measurements

COMMENTS

VARCHAR2(512)

Comment associated with

OFF_NOMINAL_TIME

DATE

Time quality went off-nominal

NORMAL_STATE

INTEGER

Normal state for measure. Only used for digital measurements.

MEASUREMENT_TYPE

VARCHAR2(1)

Measurement Type:

A -- Analog measurement

D -- Digital measurement

Generic SCADA Adapter

This chapter includes the following topics:

•

Introduction

•

Generic SCADA Adapter Configuration

•

Software Configuration

•

Information Model

Introduction

The Generic SCADA Adapter (executable name: RTAdapter) is an Oracle Utilities Network Management System interfacing adapter that can be used to interface to external SCADA systems. Generally one RTAdapter process is configured to communicate with each external SCADA system. Each external SCADA system must write some form of "scan file" to a defined (dedicated) directory (or RDBMS table) that RTAdapter can access in read/write mode. The "scan files" are read out of the named directory (or RDBMS table) by RTAdapter on a first-in-first-out basis (to support queuing of updates). The form of the scan files can be configured (to some degree) for each SCADA interface.

Generic SCADA Adapter Configuration

Overview

This section is used to guide the user in the configuration of the Oracle Utilities Network Management System Generic SCADA Adapter. The following are assumed to be true before the adapter is installed:

•

Oracle database access has been confirmed.

•

ISIS messaging bus has been installed and verified.

•

Oracle Utilities Network Management System is installed and functional.

Configure Adapter to Run as an NMS System Service

Configure the Generic SCADA Adapter to run as an Oracle Utilities Network Management System service by updating the $NMS_HOME/etc/system.dat file to include the Generic SCADA 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 $CES_HOME/templates/system.dat.template file for examples of how to configure the Generic SCADA Adapter. Search for RTAdapter 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 SCADA Adapter to properly be monitored by SMService.

Notes:

•

The adapter process is generally given a configuration name adapted from the SCADA system from which it is receiving data. Reference the RTDBAdapter configuration option in the $CES_HOME/templates/system.dat.template for an example of this type of configuration. The first parameter after the keyword program must match the -process_name parameter. The -scada option specifies the name of the SCADA for this instance of the RTAdapter (from the SCADA_IDS table) and often matches the -process_name option (although this is not required).

•

If the generic SCADA adapter is configured to use the "-dir RDBMS" option (where RTAdapter periodically scans the scada_digital_in and scada_analog_in tables for updates), it is recommended that a dedicated DBService instance be configured to support the RTAdapter. To do this you must configure RTAdapter with the -rtdbs option and you MUST configure an additional DBService process in your system.dat with the following program entry. You will also need appropriate corresponding service and instance records in your system.dat file.

program RTDBService DBService -nodaemon

-service rt -process_name RTDBService

Command Line Options for Generic SCADA Adapter

The command line for the Generic SCADA Adapter provides the following options:

Command Line Option

What it does

-volbuffer <VOLTS>

Threshold for analog VOLT attributes, report if changed by more than <VOLTS>.

-ampbuffer <AMPS>

Threshold for analog AMP attributes, report if changed by more than <AMPS>.

-no_analogs

Do not scan the scada_analog_in table or process analogs.

-idle <cycles>

Number of processing cycles to wait without processing any data before sending an alarm.

-lock

Use file locking to prevent file overwrite during file read (if scan file names are not unique).

-error

Show processing errors.

-watch

Show files being processed, minimal info.

-debug

Enable debugging.

-operate

Operate (change status of) model devices, otherwise generates pseudo alarms only.

-process_name

ISIS process name for this process. If the first parameter after the keyword program in the first column of the system.dat file is something other than the second parameter - then you must set the -process_name option to the same string as the first parameter. This is only generally necessary if you need to run more than one instance of RTAdapter or you want RTAdapter to be known as some other name within the ISIS messaging bus. ISIS process names must be unique.

-controls

Call the project/SCADA specific rti_project.ces script when an outbound control request (open/close) is made. This script can be customized to help trigger an action (some type of control request) on external system. Generally for testing.

-offline

For testing purposes - when a control request is received - simulate the external SCADA system and operate the device.

-dir <directory>

Value either directing RTAdapter to the directory containing scada data scan files or if set to 'RDBMS' enabling the scada_digital_in/scada_analog_in database polling functionality. (Required)

-interval <interval>

Seconds between file processing cycles. (Required)

-scada <scada>

SCADA source name. (Required)

-delimiter <char>

Allows a project to override the default (|) input file delimiter character with the specified character.

-rtdbs

Instructs RTAdapter to use a dedicated DBService instance. This is recommended if you are using the -dir RDBMS option to periodically scan scada_digital_in and scada_analog_in tables. To use this option you must have a DBService instance configured with a process name of rtdbs - see note above on RTDBService.

-retain

Retain data in scada_digital_in table after it is processed. Generally for validation/debug - not general purpose production use.

Software Configuration

Overview

The interface comes with a configuration support tool (scadapop) that can be used to help populate the standard SCADA configuration tables for incoming SCADA data (analog_measurements and digital_measurements). The scadapop process can be used to provide initial population of these tables.

Adapter Configuration

RDBMS configuration:

Tables involved:

•

digital_measurements : standard SCADA runtime configuration table for digital measurements. Persistent storage for digital measurement specific quality codes and/or manually entered values.

•

analog_measurements : standard SCADA runtime table for analog_measurements. Persistent storage for analog measurement specific quality codes and/or manually entered values.

•

scada_measurements_st: SCADA configuration staging table.

Note: The scada_measurements_st staging table can be populated via the scadapop process or by a project specific population mechanism. This table can be truncated and repopulated at will while DDService is active (running). The UpdateDDS -recacheMeasures command will send a message to DDService to merge updates from the scada_measurements_st staging table into the analog_measurements and/or digital_measurements runtime SCADA tables - preserving any existing quality codes and/or stored data values.

•

scada_ids : RTAdapter/scadapop SCADA definition table - required for both.

•

scada_states : RTAdapter string state to integer mapping - required.

•

scada_synonyms : RTAdapter scada data attribute value mapping - required.

•

scada_analog_in: RTAdapter polling table can be used to queue incoming analog SCADA updates - optional.

Note: The RTAdapter process does not require any population into the scada_analog_in table. The use of scada_digital_in is entirely optional but is generally used in conjunction with scada_analog_in.

•

scada_digital_in: RTAdapter polling table can be used to queue incoming digital SCADA updates - optional.

Note: The RTAdapter process does not require any population into the scada_digital_in table. The use of scada_digital_in is entirely optional but is generally used in conjunction with scada_analog_in.

•

scada_points : optional scadapop staging table - to help populate scada_measurements_st.

Note: The RTAdapter process does not require any population into the scada_points table. The use of scada_points as a staging table is merely one solution for the ultimate problem of configuring the required SCADA measurements staging table (scada_measurements_st). The use of scadapop is entirely optional.

•

srs_rules: RTAdapter has the ability to convert one incoming analog measurement into "another."

Note: This is for optional functionality that was initially done to support the NMS Fault Location Isolation and Restore (FLISR) functionality. In effect there is only one transform currently available and it transforms one analog measurement to another as long as the absolute value of the incoming measurement exceeds a rule defined threshold. This allows RTAdapter to - in effect - capturing "pre-trip" analog measurements as post trip analog values generally tend to 0. The threshold is provided to allow for some noise level from field transducers reporting analog values. These rules are generally configured and documented in the Configuration Assistant and are not discussed in further detail here.

To configure the standard SCADA measurement staging table (scada_measurements_st) using scada_pop, you might follow steps similar to the following:

Specify which devices have SCADA (via scada_points table and using the scadapop executable):

1.The scada_points table can be populated via standard attribute population during model build construction/update or it can be populated after the model is built/updated by a custom (project specific) process.

2.Populate scada_points RDBMS table via model build device attribute configuration.

To set up the scada_points table as a standard Network Management System attribute table generally involves the following RDBMS tables:

•

device_attributes : generic model build attribute configuration.

•

scada_points : SCADA project specific attribute table.

This option involves populating two attributes in the scada_points attribute table:

scada_name: the name of the SCADA, as defined in scada_ids.scada_name (for example, RTAdapter)

rtu_alias: SCADA unique identifier for reporting field device.

The rtu_alias must only be unique within a particular SCADA (scada_name). An individual rtu_alias may well report multiple analog values (AMP, VOLT, KVAR, etc.) as well as digital and/or status values.

Once the scada_points table is populated, the scadapop program can be used to expand the information in the scada_points attribute table to fully populate the more generic scada_measurements_st staging table (see notes below for how to use scadapop).

Note: a given field device corresponds to a given scada_points.rtu_alias and would typically be a breaker of some kind often reporting both digital status, for example, and multiple analog values. It could also be a transformer reporting analog values with or without status.

Below are two example device_attributes table SQL statements support population of the scada_points table via standard model build attribute population. For more information on this process, please consult the Network Management System Model Build process documentation. These are examples only.

INSERT INTO device_attributes (

DEVICE_CLS,

ATTR_NAME,

TABLE_NAME,

COLUMN_NAME,

ATTR_TYPE,

LENGTH,

REQUIRED,

MAINTENANCE

) VALUES (

143, 'Rtu_Id', 'scada_points', 'rtu_alias', 3, 32, 'N', 'Y');

COMMIT WORK;

INSERT INTO device_attributes

DEVICE_CLS,

ATTR_NAME,

TABLE_NAME,

COLUMN_NAME,

ATTR_TYPE,

LENGTH,

REQUIRED,

MAINTENANCE

) VALUES (

143, 'Rtu_Desc', 'scada_points', 'scada_name', 3, 32, 'N', 'Y');

COMMIT WORK;

Example device_attribute model attribute table - data field explanation:

143 Class of device which may report SCADA data. + project specific

scada_pointsModel attribute table to populate.

Rtu_IdAttribute id as appears in *.mb file for device - project specific.

rtu_alias Table scada_points column to populate with Rtu_Id value.

Rtu_DescAttribute id as appears in *.mb file for device.

scada_namescada_points column to populate with Rtu_Desc value.

3 Data type of string (ASCII field) always a 3 for a string.

32Maximum length of this attribute string (bytes).

'N' Required attribute - project specific generally ‘N’ (no).

'Y'Set to Y for model builder maintenance. Set this to ‘Y’ if you want the Model Builder to maintain this table via the incremental model build process.

Once the scada_points table is populated the scadapop program can be used to expand this information to fully populate the scada_measurements_st staging tables.

Run scadapop -h to get command line options. In general:

•

scadapop [-debug [n]] -partition <n> -initFile <file>

•

debug <n> - Turns debug on <to level n>

•

partition n - Populate partition n (0 = all partitions)

•

initFile <configuration - file> - rti.dat configuration file (see below)

The rti.dat file is the configuration file used by the scadapop program. Based on data in this file, and entries in the scada_points table, scadapop populates the scada_measurements_st staging table.

The scada_points table contains a single record (row) for each device in the Network Management System model that has SCADA information associated with it. Each record has a "scada_name" column which, in order to populate the scada_measurements_st staging table, must match a "SCADA_Name" keyword in the configuration file specified via the scadapop -initFile<configuration file> option.

The syntax rules for the rti.dat file are:

•

Lines with a leading # are treated as comments (ignored).

•

Leading blank space is ignored.

•

Only the first two non-blank tokens on a line are recognized.The remaining tokens are treated as comments (ignored).

•

Blank lines are okay.

•

Attributes are associated to last defined SCADA_Name.

Keywords (they must match EXACTLY):

•

SCADA_Name:

•

Analog:

•

Digital:

Note: The colon ":" character is a keyword delimiter. The colon must appear as the first character after the keyword in order for the keyword to be recognized.

Example rti.dat file:

SCADA_Name: RTAdapter

Digital: status (Switch Position or "Status")

Analog: Amps_A

Analog: Amps_B

Analog: Amps_C

Analog: Volts_A

Analog: Volts_B

Analog: Volts_C

Example scadapop command line execution:

scadapop -partition 0 -initFile ${CES_DATA_FILES}/OPAL_rti.dat

To populate the scada_measurements_st for all partitions.

scadapop -partition 3111 -initFile rti.dat -debug

To populate the scada_measurements_st for partitions 3111 plus debug.

Other RTAdapter-specific RDBMS Population

The tables below are configuration tables that generally need to be populated via project specific sql scripts. Example configuration for these tables is provided for the Oracle (OPAL) model in $NMS_HOME/sql/OPAL_scada.sql.

scada_ids : RTAdapter name to unique integer value mapping.

•

Generally used to map SCADA name to a unique integer id.

scada_states : RTAdapter string to integer mapping.

•

Generally used to map topology state and/or quality code information

scada_synonyms : RTAdapter scada data attribute/synonym value mapping.

•

Generally used to map SCADA reported attributes to Network Management System attributes.

Sample RTAdapter Configuration/Execution Sequence - File Based

To get RTAdapter up and running, the following general steps should suffice.

Start from the home directory for RTAdapter:

1.

Login to Network Management System admin account with standard OPAL model configured and running.

2.

Create RTAdapter specific RDBMS tables:

ISQL.ces product_schema_scada.sql

•

creates scada_ids table

•

creates scada_states table

•

creates scada_synonyms table

ISQL.ces ces_retain_scada.sql

•

creates scada_points table

•

creates scada_analog_in table (only used with "-dir RDBMS" option)

•

creates scada_digital_in table (only used with "-dir RDBMS" option)

3.

The OPAL_scada.sql file contains sample population data for the scada_ids, scada_points, scada_synonyms and controls table for the OPAL model. You must modify and rename this file for your project.

ISQL.ces OPAL_scada.sql

4.

Run "scadapop -partition 0 -initFile $CES_DATA_FILES/OPAL_rti.dat"

•

This should populate scada_measurements_st staging table - confirm that you have entries in this table before moving to the next step.

5.

Validate the RTAdapter is in the $NMS_HOME/etc/system.dat file (see directions above).

•

Recommend using -watch and possibly the -debug option to start; helps to identify configuration issues.

6.

If the system.dat file is using the $NMS_SCADA_SCAN_FILE_DIR environment variable to specify the SCADA scan file directory, make sure this environment variable points to a directory that the RTAdapter process can both read and write. Generally, this means a directory owned by the id that is executing RTAdapter. For example, mkdir ~/scada. At the same time, suggest creating a test data holding directory (for example, mkdir ~/scada/tst).

7.

Stop and restart Oracle Utilities Network Management System services (sms_start.ces).

•

Make sure RTAdapter is running.

8.

The $NMS_HOME/templates/rtiadapter.dat.template file contains sample RTAdapter incoming data blocks. You can use the example data blocks in this file to validate basic RTAdapter functionality.

Example:

Copy example data blocks from the rtiadapter.dat.template to individual test files under ~/scada/tst (using the example configuration above); cut the following out of rtiadapter.dat.template SCADA data file to "live" RTAdapter scan file directory to test. Note by convention the scadapop program will place the numeric value for the scada measurement attribute as a dash separated suffix for the name of the measurement. For example, attribute 0 is topological status (opened/closed) and thus the status attribute for BR2414 would be populated (by scadapop) as BR2414-0. This is generally desirable as it allows scada attribute names to be unique and thus it is not necessary to specify attributes on input - mostly used with the "-dir RDBMS" option.

1.Copy the following lines into a file - say BR2413_open

DATA

OBJECT|BR2414

BREAKER_POS|OPEN

END_DATA

2.Copy the following lines into a file - say BR2413_close

DATA

OBJECT|BR2414

BREAKER_POS|CLOSED

END_DATA

3.Copy BR2413_open and BR2413_close to ~/scada/tst (following example above).

4.cd ~/scada/tst

5.cp BR2413_open ..

This should cause the BR2413 file to be read and processed by RTAdapter - you should see the BR2413 device open in the standard OPAL model.

6.cp BR2413_close ..

This should cause the BR2413 file to be read and processed by RTAdapter - you should see the BR2413 device close in the standard OPAP model.

7.Follow other examples for conditions and quality codes.

Turn debug on RTAdapter to see what is going on. You should be able to send RTAdapter debug messages on the fly:

Action any.RTAdapter debug on

8.Validate that devices are changing state in the Network Management System viewer as you execute steps 5 and 6 above ("cp BR2413_open .." followed by "cp BR2413_close ..") sequence over and over.

Sample RTAdapter Configuration/Execution Sequence - RDBMS Table Polling Based

To get RTAdapter to use the RDBMS queue table mechanism (rather than the earlier file based polling), the following general steps should suffice.

Start from the home directory for RTAdapter:

1.

Follow steps (1-5) as noted above for the file based polling example above.

2.

In the ~/etc/system.dat configuration file verify the RTAdapter option -dir RDBMS. If the -dir option is set to a directory (rather than the keyword RDBMS),. RDBMS polling will NOT be enabled

3.

Recommend using -watch and, possibly, the -debug option to help identify configuration issues.

4.

Stop and restart Oracle Utilities Network Management System services (sms_start.ces).

5.

Make sure RTAdapter is running.

6.

Insert row into SCADA_DIGITAL_IN table either using alias or h_cls and h_idx with status = ‘N’. The primary key on the scada_digital_in table is the id column - which is generally populated by a trigger on the scada_digital_in table that fires on insert and populates the id column with the next value in a sequence.

Example sql statement:

INSERT into scada_digital_in (

alias,

phases

operation,

operation_date,

quality

source,

status

) VALUES (

‘ BR2414-0', /* Unique attribute measurement name from scada_measurements_st */

'7', /* Phase bitmask - 7=ABC, 1=A, 2=B, 4=C, etc */

'0', / * Defined in scada_synonyms - 0=open, 1=close */

SYSDATE,

'0', /* Quality bitmask - value >2047 and <2^32 - others ignored */

'SCADA',

'N'

);

COMMIT WORK

Data Flows

SCADA Entry

When RTAdapter is configured to poll and process files, the SCADA system sends fixed format files. The following format rules generally apply:

1.

Actual SCADA data appears between ^DATA (the string DATA at the start of a line) and ^END_DATA.

2.

Records between DATA and END_DATA are identified by OBJECT which must match a unique analog_measurements.rti_alias or digital_measurements.rti_alias entry.

3.

SYNCHRONIZE|TRUE is a special case used to synchronize conditions and is outside the standard DATA/END_DATA block. If set the line following SYNCHRONIZE|TRUE should be something like TYPE|note - to indicate the data that follows is to be used to synchronize "note" class conditions. For SYNCHRONIZE scan files the condition action code should be "syn" - not "add" or "rem".

4.

All other fields are generally ignored.

5.

For digital_measurements: device status: open or closed, battery low, etc. Example:

DATA

OBJECT|BR2414

BREAKER_POS|OPEN

END_DATA

6.

For analog measurements: In this example, Amps_A=attribute 1501, Amps_B=attribute 1502, Amps_C=attribute 1503:

DATA

OBJECT|BR2414-1501

AMPS_A|2.1|4096

OBJECT|BR2414-1502

AMPS_B|2.2

OBJECT|BR2414-1503

AMPS_C|2.3|SUSPECT

END_DATA

Both digital and analog measurements can include quality codes for each attribute. Quality codes are part of the standard Oracle Utilities Network Management System attribute definition and are contained within a 32-bit integer field. Bits 0->10 are reserved for Oracle Utilities Network Management System purposes. Bits 11->31 are available for project specific configuration. Quality codes are generally defined in the quality_codes configuration table. In the analog example above (AMPS_C|2.3|SUSPECT) the SUSPECT string must be defined in the scada_states table and map to a valid quality code integer. Integers can also be used directly to provide quality codes (AMPS_A|2.1|4096).

7.

Generic SCADA conditions (generally notes or tags - could be any condition) are also supported. To send a condition something like the following would be required:

DATA

OBJECT|BR2414-0

NOTE_0|add|WHO=system|TIM=2009-02-27T16:22:17|TXT=NOTE_0 txt|EXT=BR2414-note_0

END_DATA

The above text would "add" a note condition to the model on the device mapped to BR2414-0. The following keyword phrases can be used to specify common condition fields:

WHO= (who should be recorded as the creator of the condition - must be a valid NMS user name).

TIM= ISO timestamp for when the condition was added. Timestamp format must be defined in your $DATEMSK file.

TXT= Text string for the condition.text field (notes.text. tags.text, etc). Condition text string cannot contain newlines or the separator character - whatever it is configured to be. Text will truncate at the first newline or separator character.

EXT= SCADA unique identifier for the created condition. This field is necessary to allow the external system to later remove the condition.

8.

To remote the SCADA condition above:

DATA

OBJECT|BR2414

NOTE_0|rem|WHO=system|TIM=2009-10-27T16:22:17|EXT=BR2414-note_0

END_DATA

For potential use with the NMS MultiSpeak (other Java based) SCADA adapters.

If desired the generic SCADA adapter can be used in conjunction with the NMS MultiSpeak adapter. The intent is use the RTAdapter to provide a buffering mechanism for "noisy" SCADA systems that could potentially generate many periodic analog (or digital) updates. Using RTAdapter to capture and bundle incoming changes reduces the impact on the NMS CORBA Gateway and NMS CORBA publisher - when compared to contacting an internal service directly. Using RTAdapter with the "-dir RDBMS" option allows changes to be captured and sent in bulk to internal NMS Services.

If configured to do so the NMS Web Gateway APIs used by the MultiSpeak SCADA interface will write to the scada_digital_in and scada_analog_in tables when processing updates from an external SCADA. SCADA measurements submitted using Web Gateway APIs 'updateDigitalStatuses' and 'updateMeasurements' can be written into staging tables SCADA_DIGITAL_IN and SCADA_ANALOG_IN instead of being submitted directly to DDService. This behavior is controlled by three configuration properties, which can be added to the CentricityServer.properties file.

1.

intersys.use_db_for_scada_statuses

If set to 'true' than device status updates received from SCADA system will be written to the SCADA_DIGITAL_IN database table.

2.

intersys.use_db_for_scada_digitals

If set to 'true' than updates to digital values received from SCADA system will be written to the SCADA_DIGITAL_IN database table.

3.

intersys.use_db_for_scada_analogs

If set to 'true' than updates to analog values received from SCADA system will be written to the SCADA_ANALOG_IN database table

By default all the above properties are set to 'false', which means that SCADA measurements will be sent directly to the internal DDService process.

Information Model

Database Schema

SCADA_POINTS Database Table

The SCADA_POINTS table is an optional table that can either be populated via the model build process or via a project specific mechanism. It can be used to populate the scada_measurements_st staging table via the scadapop executable.

Column

Data Type

Description

H_CLS

NUMBER

Handle instance class.

H_IDX

INTEGER

Handle instance index

SCADA_NAME

VARCHAR(32)

SCADA system name

RTU_ALIAS

VARCHAR(32)

SCADA point name

PARTITION

INTEGER

Model partition for this object

BIRTH

DATE

Date object activated into the model.

BIRTH_PATCH

INTEGER

Model patch which activated with this object.

DEATH

DATE

Date object de-activated from the model.

DEATH_PATCH

INTEGER

Model patch which de-activated this object

ACTIVE

VARCHAR2(1)

Active flag (Y/N)

The schema for this table is defined in the file ces_retain_scada.sql.

SCADA_IDS Database Table

The SCADA_IDS table identifies a specific SCADA name with a numeric ID that is used for RTAdapter (and other) SCADA adapter configuration.

Column

Data Type

Description

ID

NUMBER

Numeric identifier for each "scada source" that we want RTI to process.

SCADA_NAME

VARCHAR(32)

Name for the scada source

ADAPTER_TYPE

VARCHAR(32)

Adapter type associated with this SCADA. Valid values are ICCP, MULTISPEAK, and RTADAPTER.

ACTIVE

VARCHAR(1)

‘Y’/‘N’ - adapter is active or not.

The script, OPAL_scada.sql, populates generic SCADA sources for the OPAL model. A source is any SCADA system that can provide information to the adapter. There could be one SCADA source defined for each of multiple SCADA vendors, or a utility may choose to divide their territory into multiple regions, with each region acting as a separate SCADA source. Each SCADA source must have a name as well as a unique integer ID.

SCADA_SYNONYMS Database Table

The SCADA_SYNONYMS table contains all the synonyms for attribute name or values (e.g., KV_3, AMP_A, and CLOSE) used by RTAdapter in processing flat files of SCADA data input.

Column

Data Type

Description

id

INTEGER

Unique integer - primary key.

scada_id

INTEGER

NOT NULL

Matches scada_ids.id

keyword

VARCHAR2(32)

NOT NULL

SCADA unique attribute keyword string from SCADA system. Generally maps to an NMS attribute name but this is not required unless the scada_synonyms.attribute_alias field is left blank.

If the scada_synonyms.attribute_alias field is left blank than the scada_synonyms.keyword field must map to a valid attribute name - from attributes.name (table.column).

For conditions this is unique name used by external SCADA to identify the condition class (NOTE, TAG, etc). NMS condition class must be defined in scada_synonyms.attribute_alias.

value

VARCHAR2(32)

For digitals: Customer value associated with keyword that indicates digital state (OPEN, CLOSED).

For analogs: This field can be null.

For conditions: Must be "add", "rem" or "syn". The "syn" value is used for synchronization requests.

process_type

VARCHAR2(5)

For Digitals - 'D'

For Analog - 'A'

For Analog VOLT threshold (volbuffer<n>) processing this value must contain the string "VOL" - for example, ‘A_VOL.’

For Analog AMP threshold (-ampbuffer<n>) processing this value must contain the string "AMP" - for example, ‘A_AMP.’

For Conditions - ‘C.’

attribute_alias

VARCHAR2(20)

Attribute name from attributes table.

For digitals: The only way to get a model object to change status is to set this value to 'Status'. All other values are for digital attributes.

For analogs: This field is optional and can be set to ‘’ (empty string). If this value is ‘’ (blank), the scada_synonyms.keyword is used as the attribute name.

For conditions: This field is the condition class name (tag, note, etc).

status_value

VARCHAR2(20)

Numeric or string from scada_states.alias table.

For digital status: This field is generally set to DEVICE_CLOSE, DEVICE_OPEN (defined in scada_states table), 0 (open), 1 (close).

For analogs: This field is NULL.

For conditions: This field is either a numeric condition status or a string that maps to a numeric condition status via the scada_states table. If it is a string it MUST start with an alpha (non-numeric) character.

For each implementation, define the customer specific <project>_scada.sql file to specify the required synonyms.

SCADA_STATES Database Table

This table exists to allow for entering a character string in place of a more obscure integer. For example 'DEVICE_CLOSE' instead of 2, ABC instead of 7 for phases, etc.

Column

Data Type

Description

SCADA_NAME

VARCHAR2(32)

Name of scada from scada_ids.scada_name

ALIAS

VARCHAR2(32)

Alias to map to integer

VALUE

INTEGER

Integer value to map to

OPAL_scada.sql defines commonly used entries .

SCADA_DIGITAL_IN Database Table

The scada_digital_in table can be used by RTAdapter to queue incoming digital SCADA updates. RTAdapter, if configured to do so, will periodically poll this table and check for unprocessed rows (status='N'). If unprocessed rows are found, RTAdapter will attempt to update the model according to data provided. Note that the database sequence scada_digital_in_sequence must be set up properly to create the primary key (scada_digital_in.id) value on insert.

If the -retain option is not used, records are always deleted after they are processed and the only record of any failure is in the RTAdapter log itself. It is generally recommended that production systems run this way (i.e., without the -retain option).

If the -retain option is used all rows are retained in the SCADA_DIGITAL_IN table. Processed records have scada_digital_in.status column set to "S" after they are processed. If an error occurs the scada_digital_in.status column will be set to 'E', and the scada_digital_in.error_code and scada_digital_in.error_description columns should be populated with some indication of the problem.

Note that use of the -retain option is not generally intended as a production option; rather it is a temporary mechanism to help validate/test the interface. With the -retain option, a busy (noisy) SCADA system can cause the scada_digital_in table to grow without bound. This (size of the scada_digital_in table) must in turn be managed by the customer, which creates a maintenance issue.

If scada_digital_in.attribute is a numeric, it must match a valid NMS attribute number (for example, 0 is topology status). If non-numeric, both the scada_digital_in.attribute and scada_digital_in.operation values must be properly defined in the scada_synonyms and scada_states tables.

One of three methods can be used to identify a specific NMS attribute measurement.

1.

If the rti_alias values in the digital_measurements table uniquely identify each measurement you do not need to specify an attribute on input. This is the preferred way to operate. If the project can support operating in this manner suggest adding a unique index on digital_measurements.rti_alias to enforce this.

2.

If the digital_measurements.rti_alias column is NOT unique a unique combination of digital_measurements.rti_alias and digital_measurements.attribute must provided for each record in the scada_analog_in table (the combination must be unique). If a valid rti_alias is provided but no valid handle is available you must set h_cls=0 and h_idx=0. This tells RTAdapter which scheme to use to find the appropriate digital to update. Since this scheme requires the external SCADA system to identify which NMS attribute each measurement is for it is generally deemed less desirable than option 1 above.

3.

A valid NMS handle AND attribute number - in this case the alias can be left blank. This is not often used as it requires the external system to know NMS handles and attribute numbers.

Column

Data Type

Description

ID

VARCHAR2(32)

scada_digital_in sequence generated pk

H_CLS

NUMBER(38,0)

NMS class of device - can be null if alias is not null.

H_IDX

NUMBER(38,0)

NMS index of device - can be null if alias is not null.

ALIAS

VARCHAR2(128)

SCADA point alias - can be null if h_cls and h_idx are NOT null. If not null it is suggested this value (alone) uniquely identify a measurement.

ATTRIBUTE

VARCHAR(32)

SCADA attribute. If numeric, it must match a valid NMS attribute number. If it is a string, it must map to a valid NMS attribute number via the scada_synonyms table. If the ALIAS above is unique it is NOT necessary to include an attribute value on input.

PHASES

VARCHAR(4)

Intended phases for operation. If numeric must be between 1 and 7 - where 1 is A and 7 is ABC. If a string must map to a valid numeric via the scada_states table.

OPERATION

VARCHAR(32)

Operation. If numeric and used for attribute 0 (topology status) it must be 1(open) or 1(close) and the phase attribute must be set to indicate which phases are intended to operate. If a string it must map to a valid code for the attribute involved via a combination of the scada_synonyms table and/or the scada_states table.

OPERATION_DATE

DATE

Time the operation occurred in the field. If left blank will default to SYSDATE.

OPERATION_COUNT

NUMBER(10)

How many operations have occurred since the last scan - for momentaries (not presently supported).

CAPTURE_DATE

DATE

When operation captured by NMS - generally set to SYSDATE.

QUALITY

VARCHAR2(32)

Quality code for attribute - can be numeric or a string. Either way it must be properly configured in NMS and must ultimately translate to be greater than 0x7FF (2047) and less than or equal to 0xFFFF. All quality codes below 0x7FF are reserved for NMS.

SOURCE

VARCHAR(32)

Data source/user name

STATUS

VARCHAR2(1)

Status of request:

N = New

E = Error

ERROR_CODE

NUMBER(38,0)

Error code

ERROR_DESCRIPTION

VARCHAR(256)

Error code description.

SCADA_ANALOG_IN Database Table

The scada_analog_in table can be used by RTAdapter to queue incoming analog SCADA updates. RTAdapter, if configured to do so, should periodically poll this table and check for data that has changed since the last update of the scada_analog_in.capture_date column. If potential updates are found RTAdapter will attempt to update the model according to the data provided. If an error occurs an error is written to the RTAdapter log file. If the update is successful no changes are made to the scada_analog_in table. This is to support the idea of continuous update of the scada_analog_in table from an external entity. The scada_analog_in table can be updated many times between RTAdapter scans. RTAdapter will "harvest" whatever appears to have changed since the last scan. It is expected that some form of merge statement would be used to update the scada_analog_in table - inserting if a record does not exist and updating otherwise - which triggers an update on the capture_date column.

One of three methods can be used to identify a specific NMS attribute measurement.

1.

Either a valid NMS handle If the rti_alias values in the analog_measurements table uniquely identify each measurement you do not need to specific an attribute on input. This is the preferred way to operate. If the project can support operating in this manner suggest adding a unique index on analog_measurements.rti_alias column to enforce this.

2.

If the analog_measurements.rti_alias column is NOT unique, a unique combination of analog_measurements.rti_alias and analog_measurements.attribute must provided for each record in the scada_analog_in table (the combination must be unique). If a valid rti_alias is provided but no valid handle is available you must set h_cls=0 and h_idx=0. This supports the scada_analog_in primary key and is a way of telling RTAdapter which scheme to use to find the appropriate analog to update. Since this scheme requires the external SCADA system to identify which NMS attribute each measurement is for it is generally deemed less desirable than option 1 above.

3.

A valid NMS handle AND attribute number - in this case the alias can be left blank. This is not often used as it requires the external system to know NMS handles and attributes.

Column

Data Type

Description

H_CLS

NUMBER(38,0)

NMS class of device

H_IDX

NUMBER(38,0)

NMS index of device

ALIAS

VARCHAR2(128)

SCADA point alias - can be null if h_cls and h_idx are NOT 0.

ATTRIBUTE

VARCHAR(16)

SCADA attribute. If it is numeric it must match a valid NMS attribute. If it is a string it must be defined in scada_synonyms and map to a valid NMS attribute. If it is NOT provided the provided ALIAS must be provided and MUST uniquely identify a measurement.

MEASUREMENT

NUMBER

Analog update value.

MEASUREMENT_DATE

DATE

When operation occurred in field - not presently used.

CAPTURE_DATE

DATE

When measurement captured - could be updated by trigger on table update. This is the how RTAdapter determines what to examine during periodic polls.

QUALITY

VARCHAR2(32)

Quality code for attribute - can be numeric or a string. Either way it must be properly configured in NMS and must ultimately translate to be greater than 0x7FF (2047) and less than or equal to 0xFFFF. All quality codes below 0x7FF are reserved for NMS.

SOURCE

VARCHAR(32)

source/user name

SCADA_MEASUREMENTS_ST Database Table

SCADA_MEASUREMENTS_ST is a staging table used to capture relevant information for each measurement attribute. It can be populated via the scadapop executable (discussed previously in this document) or via project specific means. It can be completely rebuilt at will as it is NOT a run-time table. The "updateDDS -recacheMeasures" utility sends a message to DDService to merge measurements defined in this table with the run-time analog_measurements and digital_measurements tables.

Column

Data Type

Description

H_CLS

NUMBER

Object handle

H_IDX

NUMBER

Object index

PARTITION

NUMBER

Object partition handle

ATTRIBUTE

NUMBER

Data attribute index (from ATTRIBUTES table)

TTL

NUMBER

Time-To-Live Value. If set to 0 value will NOT be broadcast dynamically.

LIMIT_GROUP_ID

INTEGER

Object limit group

RTI_ALIAS

VARCHAR2(128)

RTI device measurement name

RTI_ALIAS_A

VARCHAR2(128)

RTI device measurement name for phase A - MultiSpeak status updates.

RTI_ALIAS_B

VARCHAR2(128)

RTI device measurement name for phase B - MultiSpeak status updates.

RTI_ALIAS_B

VARCHAR2(128)

RTI device measurement name for phase C - MultiSpeak status updates.

SCADA_ID

INTEGER

SCADA source identifier - matches scada_ids.id

RTU_ID

VARCHAR2(32)

RTU ID - unique name within SCADA system. Not generally used.

QUALITY

INTEGER

Quality code

VALUE

FLOAT

Current value - from Manual Replace or from SCADA if configured for persistence.

UPDATE_FLAG

INTEGER

Update flag

ICCP_OBJECT

VARCHAR2(32)

ICCP mms object name

DISPLAY_ID

VARCHAR2(64)

ID for display call up - if different than rti_alias.

CONTROLLABLE

VARCHAR2(1)

Is this row controllable

ACTIVE

VARCHAR2(1)

Is this row active

SOURCE

VARCHAR2(33)

Source of measurements

COMMENTS

VARCHAR2(512)

Comment

NORMAL_STATE

INTEGER

Nominal state - only used for Digital measurements.

OFF_NOMINAL_TIME

DATE

Time quality went off-nominal

MEASUREMENT_TYPE

VARCHAR2(1)

‘A’ for Analog or ‘D’ for Digital.

ANALOG_MEASUREMENTS Database Table

The ANALOG_MEASUREMENTS table is a run-time table generally maintained by DDService.

Column

Data Type

Description

H_CLS

SMALLINT

Object handle

H_IDX

INTEGER

Object index

PARTITION

INTEGER

Object partition handle

ATTRIBUTE

SMALLINT

Data attribute index (from ATTRIBUTES table)

TTL

SMALLINT

Time-To-Live Value

LIMIT_GROUP_ID

INTEGER

Object limit group

RTI_ALIAS

VARCHAR2(128)

RTI device measurement name

SCADA_ID

INTEGER

SCADA source identifier - matches scada_ids.id

RTU_ID

VARCHAR2(32)

RTU IDID - unique name within SCADA system.

QUALITY

INTEGER

Quality code

VALUE

FLOAT

Manual Replace Value

UPDATE_FLAG

INTEGER

Manual Replace Flag

ICCP_OBJECT

VARCHAR2(32)

ICCP mms object name

DISPLAY_ID

VARCHAR2(64)

ID for display call up

CONTROLLABLE

VARCHAR2(1)

Is this row controllable

ACTIVE

VARCHAR2(1)

Is this row active

SOURCE

VARCHAR2(33)

Source of measurements

COMMENTS

VARCHAR2(512)

Comment associated with

OFF_NOMINAL_TIME

DATE

Time quality went off-nominal

DIGITAL_MEASUREMENTS Database Table

The DIGITAL_MEASUREMENTS table is a run-time table generally maintained by DDService.

Column

Data Type

Description

H_CLS

SMALLINT

Object handle

H_IDX

INTEGER

Object index

PARTITION

INTEGER

Object partition handle

ATTRIBUTE

SMALLINT

Data attribute index (from ATTRIBUTES table)

TTL

SMALLINT

Time-To-Live Value

LIMIT_GROUP_ID

INTEGER

Object limit group

RTI_ALIAS

VARCHAR2(128)

RTI device measurement name

SCADA_ID

INTEGER

SCADA source identifier

RTU_ID

VARCHAR2(32)

RTU ID

QUALITY

INTEGER

Quality code

VALUE

FLOAT

Manual Replace Value

UPDATE_FLAG

INTEGER

Manual Replace Flag

ICCP_OBJECT

VARCHAR2(32)

ICCP mms object name

DISPLAY_ID

VARCHAR2(64)

ID for display call up

NORMAL_STATE

INTEGER

Normal state for measure

CONTROLLABLE

VARCHAR2(1)

Is this row controllable

ACTIVE

VARCHAR2(1)

Is this row active

SOURCE

VARCHAR2(33)

Source of measurements

COMMENTS

VARCHAR2(512)

Comment associated with

OFF_NOMINAL_TIME

DATE

Time quality went off-nominal

This section provides an overview of the logical information model supported by this interface. The key objects supported by this interface include:

•

Customers, which are defined using accounts, service locations and meters. This model is based upon the MultiSpeak model. Typically, as a practical note, the custId identifier may in fact be the same as the account number. Some extensions to the MultiSpeak model are used as required to address issues that are otherwise not addressed by MultiSpeak. The support of a bulk load process that reads a XML file, with defined customers to create the model. This process (createSql) can be ran to generate the SQL to be run on the production servers, or can directly create the customers.

•

Trouble calls are also referred to as incidents within Oracle Utilities Network Management System. An incident is typically related to a customer, who in turn is related to a device. In the absence of a correlation to a device, a trouble call is classified as a ‘fuzzy’ call, which differentiates it from a call that can be directly correlated to the electrical distribution network.

•

Outages, which are a consequence of the correlation of incidents. Outages are one form of an event that is managed by JMService. Some events are non-outage events, such as power quality. The type of call that is provided can identify such non-outage and outage events. Each call needs to be identified with a trouble code, which will determine the type of call that JMService will generate with in Oracle Utilities Network Management System.

•

Devices, which are part of the electrical distribution network. Customers, outages and conditions may have relationships to devices. Typically customers are related to transformer devices. Outages are typically related to switch, fuse or transformer devices.

•

Conditions (which can be specialized within Oracle Utilities Network Management System for the management of information such as tags, notes, etc.)

•

SQL queries, result sets and transactions.

•

Customer disconnections and reconnections for indicating customers who have been purposely removed from Service by the utility.

•

Crew Outage States that will identify outage states that change as a result of a crew action. For example a crew that has been dispatched, assigned, or suspended from outage work would correlate to an action that may trigger an outage state change in Oracle Utilities Network Management System.

The information described by these models is formatted using XML for the purposes of exchange through this interface. The following table describes tags that are used in the XML definitions, and how they relate to the information model within Oracle Utilities Network Management System. The corresponding types used in these models are I = Integer, S = String, T = TimeStamp, C = Single Character, and F = floating point.

ICCP Adapter

This chapter includes the following topics:

•

ICCP Adapter Overview

•

LiveData ICCP Adapter Configuration

•

TMW ICCP Adapter Configuration

ICCP Adapter Overview

The Oracle Utilities Network Management System ICCP Adapter integrates the Oracle Utilities Network Management System with a remote SCADA system through the Inter-control Center Communications Protocol (ICCP). Oracle offers two versions of an ICCP adapter. One Oracle ICCP adapter (TMW ICCP Adapter) uses ICCP libraries from Triangle MicroWorks (TMW) and can interface directly to a 3rd-party SCADA system that supports the ICCP protocol. The other Oracle ICCP adapter (LiveData ICCP Adapter) does not directly speak ICCP, but instead interfaces to a LiveData 3rd-party ICCP server using LiveData proprietary APIs, which then interfaces to the SCADA system that supports the ICCP protocol.

Note: TMW ICCP Adapter includes the TWM libraries bundled in. The LiveData ICCP Adapter requires the use of a LiveData Server that must be separately licensed from LiveData, Inc. For additional details on the LiveData Server, please refer to LiveData documentation.

ICCP is a standard interface protocol that can be used with Oracle Utilities Network Management System to provide data exchange with remote and local SCADA systems. ICCP is also an international standard: International Electrotechnical Commission (IEC) Telecontrol Application Service Element 2 (TASE.2).

ICCP allows the exchange of real-time and historical power system monitoring and control data, including measured values, scheduling data, energy accounting data, and operator messages. Data exchange can occur between:

•

Multiple control center Energy Management System (EMS) systems

•

EMS and power plant DCS systems

•

EMS and distribution SCADA systems

•

EMS and other utility systems

•

EMS/SCADA and substations

The ICCP standard consists of the following blocks:

Block

Description

Notes

Block 1

Basic Services

Available via both the Oracle TMW ICCP Adapter and the Oracle LiveData ICCP Adapter.

Block 2

Extended Data Set Condition Monitoring

Available via both the Oracle TMW ICCP Adapter and the Oracle LiveData ICCP Adapter.

Block 3

Blocked Transfers

Block 4

Operator Stations

Block 5

Device Control

Currently only available via the Oracle LiveData ICCP Adapter.

Block 6

Programs

Block 7

Events

Block 8

Accounts

Block 9

Time Series

LiveData ICCP Adapter Configuration

This section guides the user through configuration of the Oracle Utilities Network Management System LiveData ICCP Adapter. The following are assumed to be true before the adapter is installed:

•

Oracle database access has been confirmed.

•

Isis messaging bus has been installed and verified.

•

Oracle Utilities Network Management System is installed and functional.

•

LiveData Server is installed, functional, and licensed.

Configuring the ICCP Adapter requires:

•

Configuring the Adapter to Run as a System Service

•

Populating the NMS Measurements Tables

Configuring the Adapter to Run as a System Service

Configure the ICCP Adapter by updating the $NMS_HOME/etc/system.dat file to include the ICCP 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 $CES_HOME/templates/system.dat.template file for examples of how to configure the ICCP Adapter. Search for IccpAdapter and make sure those lines are uncommented. You must restart the system services in order for the ICCP Adapter to be properly monitored by SMService.

Below is an example of the program section in the system.dat file:

program IccpAdapter IccpAdapter -prm_path /users/nms1/etc/

Note : It is assumed that the ICCP Adapter will reside on the same Unix or Linux server where the Oracle Utilities Network Management System services environment resides.

Command Line Options for ICCP Adapter

The command line for the ICCP Adapter provides the following options:

Command Line Option

What it does

-debug <level>

Sets the level of debug messages generated by the adapter. <level> is a positive number, or zero. The higher the number, the more information is displayed. If <level> is omitted, it defaults to a value of 0. Debug facilities can also be specified on the command line; for example:

-debug IA_RTP 3

could be used to specifiy level 3 debug for the IA_RTP debug facility.

-prm_path <IccpAdapter.prm path>

Sets the path of the IccpAdapter.prm parameter file location. This file is used to configure the operation of the ICCP adapter.

-help

Returns the available IccpAdapter startup parameters and definitions, then terminates.

-nodaemon

Runs in the foreground, used when running by hand.

IccpAdapter.prm

The IccpAdapter.prm file is used to configure the operation of the Oracle Utilities Network Management System ICCP Adapter. The default location for this file is the same as where the IccpAdapter binary is located ( i.e., $CES_HOME/bin) but it is generally configured to be in a different location by using the -prm_path <IccpAdapter.prm path> command line option. Lines in this file beginning with a ";" (semi-colon) are comments. Lines beginning with a "[" (left bracket) are block identifiers (markers). Fields marked as <Required> must be configured for proper operation and are generally site specific. See the IccpAdapter.prm.template file in the standard $CES_HOME/templates directory for an example IccpAdapter configuration file.

Fields in the IccpAdapter.prm File

Field name

Type

Default

Valid Values

Description

[IccpAdapter]

Marker

Used for generic configuration of program.

ServerHostname

IP address

List - blank

separated

<Required>

128.168.148.43 etc

The IP address(es) of the LiveData Server hostname(s) to connect to. It could be a blank separated list of IP address of several LiveData Servers. In case a failure of connection was detected by the ICCP Adapter with the current LiveData Server, it will traverse the ServerHostname list for the next LiveData Server to connect to.

Port

Integer

<Required>

[1..MAX_INT]

Blank separated list of TCP/IP port numbers that the ICCP Adapter will use for a connection attempt to a LiveData Server. Parallel to the ServerHostname, it could be a list of port numbers to use to connect to the corresponding LiveData server in ServerHostname. In case there was a failure of connection with the current LiveData Server, it would proceed to the next entry - in parallel with the next ServerHostname entry. 5002 is typical.

Period

Integer

10

[1..MAX_INT]

Time in seconds between periodic transfers of non-time critical data.

StatusUpdates

Integer

25

[1..MAX_INT]

The maximum number of status updates to be sent to DDService at one time.

ScadaId

Integer

1

[1..MAX_INT]

Identification number assigned to the SCADA in Oracle Utilities Network Management System with which the ICCP Adapter is communicating.

AnalogTolerance

Double

0.0F

[0.01..0.99]

Dead band for analog value updates. It is the required percent change from the last reported value to trigger an update.

Analogs

Boolean

F

[T, F]

Boolean value indicating use of the ANALOG_MEASUREMENTS table.

Digitals

Boolean

T

[T, F]

Boolean value indicating use of the DIGITAL_MEASUREMENTS table.

ReconnectPeriod

Integer

60

[0..MAX_INT]

Configurable duration of delay to wait after the LiveData Server instances failed in succession.

Controls

Boolean

F

[T, F]

Boolean value indicating use of the controls table for Block 5 functionality.

QualityCodeUseOnAssociationTimeOut

Integer

0

[0..MAX_INT]

Quality code that will be sent to DDService when the communication with LD server is lost. A valid QualityCode must be specified if this option is used.

DisableStop

Boolean

F

[T, F]

Normally the adapter will accept and process a stop high level message. This option disables this feature. When this feature is enabled, the adapter will disregard a stop high level message.

DisableCOV

Boolean

F

[T, F]

Normally the adapter will process a COV update (one or more open and close sequences within a scan cycle - normally indicating one or more momentaries) and send it to DDService. This option disables this feature.

Vccs

Integer

<Required>

[1..MAX_INT]

The number of VCCs (Virtual Control Centers) that are configured in the LiveData Server.

IgnoreCritInterSysServFail

Boolean

F

[T, F]

Normally the adapter will stop if SMSserivce reports a critical service failure and not restart until services are recovered. This option disables this feature.

NoSwitchOpQualityMask

Integer

No Mask

[0..MAX_INT]

This parameter sets the quality codes that prevent switches from being operated. There is no effect on non-switch statuses.

PhaseEncodeSwitch

Boolean

F

[T, F]

If set to true, this will enable Iccp Adapter to interpret data discrete values as three-bit phase encoded statuses. [e.g., A = ‘001’, B = ‘010’, C = ‘100’, etc.]

PseudoAlarms

Boolean

F

[T, F]

If set to 1, then this will set the pseudo flag for the switch entry to be sent to DDService. Generates pseudo (advisory) alarms for ICCP reported device ops rather than actually operating the switches in the Oracle Utilities Network Management System model.

SendTimeout

Integer

10

[0..MAX_INT]

Number of seconds to wait when attempting to connect ICCP Adapter to the LiveData server. If no connection is received, it will move to the next available LiveData server (if configured). Generally leave as the default.

DetachRead

Boolean

T

[T,F]

Detach the IccpAdapter internal thread that is reading the incoming RTP data stream from Isis. Generally leave as the default.

DetachWrite

Boolean

F

[T,F]

Detach the IccpAdapter internal thread that is writing the outgoing RTP data stream from Isis. Generally leave as the default

DetachHeartbeat

Boolean

F

[T,F]

Detach the IccpAdapter internal thread that is sending outgoing RTP data stream heartbeat requests from Isis. Generally leave as the default

[VCC#]

Marker

E.g., [VCC1]. Provides additional information for each VCC (Virtual Control Center).

AssociationAddress

Integer

<Required>

[1..MAX_INT]

RTP address in LiveData Server for watching and controlling this VCCs association status

TransferSetAddress

Integer

<Required>

[1..MAX_INT]

RTP address in LiveData Server for controlling the use of configured ICCP transfer sets

NumTransferSets

Integer

<Required>

[1..MAX_INT]

The total number of transfer sets that are available for use in the VCC. Number must be a multiple of 16.

AssociationName

String

Vcc Label

[a..z, A..Z, 0..9]

The name of the ICCP Association.

AssociationRestartTime

Integer

30

[1..MAX_INT]

Seconds allowed for restart before the association is considered failed.

TransferSetRestartPeriod

Integer

30

[1..MAX_INT]

Seconds allowed to restart transferset before the restart is considered failed and no additional restart attempts will be made.

TransferSetFailCountReset

Integer

60

[1..MAX_INT]

The number of fail count to be exhausted before marking the transfer set as not alive.

MaxTransferSetRestarts

Integer

10

[1..MAX_INT]

Maximum number of restart for transfer set.

TransferSetControlMask

String

<Required>

[T, F]

Transfer set control mask for the transfer set to be sent to LiveData Server. One T/F flag for each TransferSet. String length must be a multiple of 16.

Example with one TransferSet enabled: "FTTTTTTTTTTTTTTT"

[ValidityQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Validity Quality values

Valid

Integer

0

2**n (n=11->31)

The value is valid. This is the default (normal) value should virtually always be 0.

Held

Integer

0

2**n (n=11->31)

Previous data value has been held over. Interpretation is local.

Suspect

Integer

0

2**n (n=11->31)

Data value is questionable. Interpretation is local.

Notvalid

Integer

0

2**n (n=11->31)

The value is not valid.

[CurrentSourceQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Current Source Quality values.

Telemetered

Integer

0

2**n (n=11->31)

Value was received from a telemetered site. This is the default (normal) value should virtually always be 0.

Calculated

Integer

0

2**n (n=11->31)

Value was calculated based on other data.

Entered

Integer

0

2**n (n=11->31)

Value was entered manually.

Estimated

Integer

0

2**n (n=11->31)

Value was estimated (State Estimator, etc.).

[NormalValueQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Normal Value Quality values.

Normal

Integer

0

2**n (n=11->31)

The point value is that which has been configured as normal for the point. This is the default (normal) value should virtually always be 0.

Abnormal

Integer

0

2**n (n=11->31)

The point value is not that which has been configured as normal for the point.

[TimeStampQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Timestamp Quality values

Valid

Integer

0

2**n (n=11->31)

Current value of the TimeStamp attribute contains the time stamp of when the value was last changed. This is the default (normal) value should virtually always be 0.

Invalid

Integer

0

2**n (n=1->31)

Current value of the TimeStamp attribute contains the time stamp other than when the value was last changed.

[SwitchStatusQuality]

Marker

Assign an Oracle Utilties Network Management System quality to the non-open/close statuses that can be returned in the two-bit ICCP status field. ICCP "open" is generally (1) and "closed" is (2).

Between

Integer

262144

2**n (n=11->31)

Quality code to set if the two bit ICCP switch status is reported as "between" (0).

Invalid

Integer

524288

2**n (n=11->31)

Quality code to set if the two bit ICCP switch status is reported as "invalid" (3).

Sample IccpAdapter.prm Configuration File

[IccpAdapter]

Period=5

ScadaId=1

Analogs=0

AnalogTolerance=.0001

Digitals=1

Controls=0

Port=5002

QualityCodeUseOnAssociationTimeOut=16384

Vccs=1

DisableCOV=0

[VCC1]

AssociationAddress=10

TransferSetAddress=20

NumTransferSets=16

[ValidityQuality]

Valid=

Held=

Suspect=

Notvalid=1048576

[CurrentSourceQuality]

Telemetered=

Calculated=

Entered=

Estimated=2097152

[NormalValueQuality]

Normal=

Abnormal=

[TimeStampQuality]

Valid=

Invalid=

Quality Codes

The IccpAdapter.prm file enables ICCP quality codes to be translated into Oracle Utilities Network Management System quality codes. In the simplest (and default) configuration, all of the ICCP quality codes (except the Between and Invalid SwitchStatusQuality codes, which need to be defined to ensure proper operation) are assigned to the 'normal' Oracle Utilities Network Management System quality code (0).

Note : Oracle Utilities Network Management System quality codes are always single bit values. Therefore, the only valid value for configuration is 0 or a proper value of 2^nth power where n=0->31. The Quality Rules Table table lists all the valid user-defined quality codes in Oracle Utilities Network Management System.

If none of the predefined quality codes are applicable, then a new code must be created. The following steps accomplish this:

•

Choose an ICCP quality listed in the IccpAdapter.prm.

•

Check the Quality Rules Table to see which values have already been assigned to qualities.

•

Assign one of the values listed below to the ICCP quality and enter it in the Quality Rules Table .

•

Locate the quality in the IccpAdapter.prm file and enter the assigned value for it.

The assigned value must be the decimal representation of 32 bits, where no more than one bit has a value of 1. For example, if the bit position is 11, use the number 2048. The following list contains the decimal values that may be assigned to new qualities: 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288, 1048576, 2097152, 4194304, 8388608, 16777216, 33554432, 67108864, 134217728, 268435456, 536870912, 1073741824, 2147483648.

Values of 0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 may not be assigned as codes for new qualities because they are already defined and used within Oracle Utilities Network Management System. The ‘normal’ Oracle Utilities Network Management System quality code is 0.

The adapter reads the IccpAdapter.prm file only during startup. If the quality code is added when the adapter is running, you must restart the adapter in order for it to recognize the new quality code.

High Level Messages

The ICCP Adapter can be dynamically controlled from Oracle Utilities Network Management System by using high-level messages. They can be used any time while running the Oracle Utilities Network Management System ICCP Adapter. The following high-level messages can be used:

•

stop

Disconnect from the LiveData Server and stop the Oracle Utilities Network Management System ICCP Adapter.

•

report

Empty message to determine how many Oracle Utilities Network Management System ICCP Adapters are running.

•

debug [on | off | #]

Turn on/off debug, or set it to a specific level. On is equivalent to 1, off is 0. Level can be any integer value no less than 0.

•

debug <facility> #

Turn facility specific debug on/off. For example, to turn IA_RTP debug on to level 3:

Action any.IccpAdapter debug IA_RTP 3

To turn off:

Action any.IccpAdapter debug IA_RTP 0

Check ICCP Adapter specific log file for other facilities specific to this adapter process.

•

demote

Causes the Oracle Utilities Network Management System ICCP Adapter currently in control to relinquish control.

Use IccpAdapterService with high-level messages for the Oracle Utilities Network Management System ICCP Adapter. For example:

Action any.IccpAdapter report

Populating the NMS Measurements Tables

ICCP points must first be mapped to devices in the Oracle Utilities Network Management System model before sending SCADA updates to Oracle Utilities Network Management System. These ICCP points are placed in SCADA Measurements table of the Oracle Utilities Network Management System database. A process needs to be formalized to create and maintain this data. This process often depends on customer specific mechanisms used to maintain the SCADA side of the ICCP interface. As a result this process generally needs to be formalized by LiveData and the customer - potentially with help from NMS consulting.

Required NMS Data from LiveData

The following data items are required to be populated in the NMS measurements tables:

•

ICCP Name

•

ICCP Type

•

Attribute

•

NMSDeviceID

ICCP Name

•

ICCP Name has to be unique.

•

It is recommended for the name to be composed of alpha-numeric characters and underscore

•

It is recommended for the first character of the ICCP Name to be a letter

•

There should be no space, no periods and no dashes in the ICCP name.

ICCP Type

Below is a list of supported ICCP Types. Please take note of the underscore.

•

Data_State

•

Data_StateQ

•

Data_StateQTimeTag

•

Data_StateExtended

•

Data_Real

•

Data_RealQ

•

Data_RealQTimeTag

•

Data_RealExtended

•

Data_Discrete

•

Data_DiscreteQTimeTag

•

Data_DiscreteExtended

Attribute

•

The attribute should have a corresponding entry in the ATTRIBUTES table, specifically, in the NAME field in the Oracle Utilities Network Management System database. Take note that entries under the attributes column of the flat file needs to exactly match the entries in the NAME field of the ATTRIBUTES table, taking into consideration case sensitivity, underscores, etc.

NMSDeviceID

•

This is the ID of the SCADA device. This ID should match a unique attribute or device name in NMS that will allow the measurement table population process to grab the appropriate NMS device handle (h_cls and h_idx) of the SCADA device. Tables that could be used in NMS to reference SCADA devices handles could be SCADAMAP, ALIAS_MAPPING, or a model managed device attribute table such as ATT_SWITCH. Take note that matching should put into consideration several aspects like case sensitivity, special characters such as hyphens, underscores, etc.

Information Model - Database Schema

Quality Rules Table

This database table will define the quality codes that may be used for analog and digital values. This table defines the meaning of each bit in the quality codes for SCADA measurements.

Column Name

Data Type

Size

Description

Values

PRIORITY

NUMBER

Ranking priority of the quality code

Priority code, specifies relative importance of this quality bit over other quality bits

VALUE

NUMBER

Bit value used for the quality code change.

For Phase 1:

2048=No Data

4096=Old Data

STRING

VARCHAR2

3

Description of the quality code, which is displayed next to the value of the measurement when a quality exists for a measurement change.

The actual character string displayed next to the device when viewed via the Viewer

DESCRIPTION

VARCHAR2

128

Descriptive string

Any text string-usually the action taken from the SCADA Summary

COLOR

NUMBER

Designates which color is used in the Viewer to display the measurement when a particular quality bit is set.

Integer value for the color associated to the quality code change to be displayed

The integers are mapped to the pre-allocated colors documented in separate application file.

LOCATION

NUMBER

Location of symbol in relation to the device associated with the value.

only used if a symbol is defined for the quality code as opposed to just a color for a quality change

1-9; 5 overrides the device symbol

SYMBOL

NUMBER

The symbol used to display the value. only used if a symbol is defined for the quality code as opposed to just a color for a quality change

Valid Symbol Identification Number defined in <project>_SYMBOLS.sym. 0 if defining a text symbol.

OFF_NOMINAL

VARCHAR2

1

Whether or not the value is off-nominal

Y or N

Note: If multiple bits in the quality code are set, then the color of the measurement text in the Viewer is determined by the color of the lowest order bit that is set in the quality code.

SCADA Measurements Table

The SCADA_MEASUREMENTS_ST table defines digital and analog measurements as used by Oracle Utilities Network Management System. It is a staging table used by DDService for populating the production SCADA measurements tables (ANALOG_MEASUREMENTS and DIGITAL_MEASUREMENTS).

The Oracle Utilities Network Management System ICCP Adapter communicates dynamic information to the Oracle Utilities Network Management System services. The services will cache measurements defined by this table. Population is dependent upon customer-supplied information.

Column Name

Data Type

Size

Description

Values

MEASUREMENT_TYPE

VARCHAR2

1

Measurement type code.

A (analog)

D (digital)

H_CLS

NUMBER

Class component of handle

Valid object class

H_IDX

NUMBER

Index component of handle

>0

PARTITION

NUMBER

Partition number, index component of partition handle

Valid partition or 0 for multi-partition objects

ATTRIBUTE

NUMBER

Attribute number which identifies measurement type

Valid attribute number

TTL

NUMBER

Setting for displaying measurement value in the Viewer or not.

1 or 0. 1=yes

LIMIT_GROUP_ID

NUMBER

Limit group ID

Customer defined

RTI_ALIAS

VARCHAR2

128

Alias to be used in communications between the Oracle Utilities Network Management System ICCP Adapter and LiveData Server

Alphanumeric

SCADA_ID

NUMBER

SCADA host ID

0 (not a SCADA device), 1 (SCADA 1), 2 (SCADA 2)...

RTU_ID

VARCHAR2

32

SCADA RTU ID

String (optional)

QUALITY

NUMBER

Measurement quality code

Bit mask of quality codes

VALUE

NUMBER

Measurement/entered value

Entered value

UPDATE_FLAG

NUMBER

Manual replace flag

1=true, 0=false

ICCP_OBJECT

VARCHAR2

32

ICCP Object type of the telemetered value

Alphanumeric

DISPLAY_ID

VARCHAR2

64

NORMAL_STATE

NUMBER

CONTROLLABLE

VARCHAR2

1

ACTIVE

VARCHAR2

1

Active flag for patch management, indicates whether the row is active within the model

Y(yes=active), N(no=inactive), A(local add=active), D(local delete=inactive), R(locally removed, dependent=inactive)

SOURCE

VARCHAR2

33

Source of the measurement.

any character string.

OFF_NOMINAL_TIME

DATE

Controls Table

This table defines control actions as used by Oracle Utilities Network Management System. Population is dependent upon customer-supplied information. The information to be contained in this table is generated by the Auto Configuration Program.

Column Name

Data Type

Size

Description

Values

DEVICE_CLASS

NUMBER

Class component of device handle.

Valid object class

DEVICE_ID

NUMBER

Index component of device handle.

>0

CTLTYPE_ID

NUMBER

The Control Action ID number associated to the action.

Valid control action ID.1 (OPEN),2 (CLOSE)…

CONTROL_ID

NUMBER

Part of unique key to identify each control action for a single device.

0..N, based on the number of control actions defined for the device.

EXP_STATE

NUMBER

Expected return value.

Numeric

ATTRIBUTE

NUMBER

If non-zero, attribute number which identifies measurement type.

0 (Ignore) orValid attribute number

RTI_ALIAS

VARCHAR2

128

Alias to be used in communications between the Oracle Utilities Network Management System ICCP Adapter and LiveData Server.

Alphanumeric

TIMEOUT

NUMBER

SCADA timeout for this device.

0 = No Timeout, >0 = timeout is seconds.

NOT_IN_SERVICE

VARCHAR2

1

Not in service flag.

N (In Service),Y (Not in Service)

SCADA_ID

NUMBER

SCADA server ID.

0 (not a SCADA device), 1 (SCADA 1), 2 (SCADA 2)...

RTU_ID

VARCHAR2

32

SCADA RTU ID.

String (optional)

ACTIVE

VARCHAR2

1

Active flag for patch management; indicates whether the row is active within the model.

Y (yes=active), N (no=inactive), A (local add=active), D (local delete=inactive),R (locally removed, dependent=inactive)

TMW ICCP Adapter Configuration

This section guides the user through configuration of the Oracle Utilities Network Management System TMW ICCP Adapter. The following are assumed to be true before the adapter is installed:

•

Oracle database access has been confirmed.

•

Isis messaging bus has been installed and verified.

•

Oracle Utilities Network Management System is installed and functional.

Configuring the TMW ICCP Adapter requires:

•

Configuring the Adapter to Run as a System Service

•

Populating the NMS Measurements Tables

Configuring the Adapter to Run as a System Service

Configure the TMW ICCP Adapter by updating the $NMS_HOME/etc/system.dat file to include the TMW ICCP 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 $CES_HOME/templates/system.dat.template file for examples of how to configure the TMW ICCP Adapter. Search for Tase2Adapter and make sure those lines are uncommented. You must restart the system services in order for the TMW ICCP Adapter to be properly monitored by SMService.

Below is an example of the program section in the system.dat file:

program Tase2Adapter Tase2Adapter -prm_file /users/nms1/etc/Tase2Adapter.prm

Note : It is assumed that the ICCP Adapter will reside on the same Unix or Linux server where the Oracle Utilities Network Management System services environment resides.

Command Line Options for TMW ICCP Adapter

The command line for the TMW ICCP Adapter provides the following options:

Command Line Option

What it does

-debug <level>

Sets the level of debug messages generated by the adapter. <level> is a positive number, or zero. The higher the number, the more information is displayed. If <level> is omitted, it defaults to a value of 0. Debug facilities can also be specified on the command line; for example:

-debug IA_ICCP 3

could be used to specify level 3 debug for the IA_ICCP debug facility.

-prm_file <full path to configuration file>

Sets the path to the file used to configure the operation of the TMW ICCP Adapter.

Tase2Adapter.prm

The Tase2Adapter.prm file is used to configure the operation of the Oracle Utilities Network Management System TMW ICCP Adapter. The default location for this file is the same as where the Tase2Adapter binary is located ( i.e., $CES_HOME/bin) but it is generally configured to be in a different location by using the -prm_file <Tase2Adapter.prm path> command line option.

Lines in this file beginning with a ";" (semi-colon) are comments. Lines beginning with a "[" (left bracket) are block identifiers (markers). Fields marked as <Required> must be configured for proper operation and are generally site specific. See the Tase2Adapter.prm.template file in the standard $CES_HOME/templates directory for an example Tase2Adapter configuration file.

Fields in the Tase2Adapter.prm File

Field name

Type

Default

Valid Values

Description

[Tase2Adapter]

Marker

Used for generic configuration of program.

ServerHostname

IP address

List - blank

separated

<Required>

128.168.148.43 etc

The IP address(es) of the TMW ICCP server to connect to. It could be a blank separated list of IP address of several ICCP servers. In case a failure of connection was detected by the TMW ICCP Adapter with the current ICCP server, it will traverse the ServerHostname list for the next ICCP server to connect to.

Period

Integer

10

[1..MAX_INT]

Time in seconds between periodic transfers of non-time critical data.

StatusUpdates

Integer

25

[1..MAX_INT]

The maximum number of status updates to be sent to DDService at one time.

ScadaId

Integer

1

[1..MAX_INT]

Identification number assigned to the SCADA in Oracle Utilities Network Management System with which the TMW ICCP Adapter is communicating. It should match an existing record in SCADA_IDS database table.

AnalogTolerance

Double

0.0F

[0.01..0.99]

Dead band for analog value updates. It is the required percent change from the last reported value to trigger an update.

Analogs

Boolean

F

[T, F]

Boolean value indicating use of the ANALOG_MEASUREMENTS table.

Digitals

Boolean

T

[T, F]

Boolean value indicating use of the DIGITAL_MEASUREMENTS table.

ReconnectPeriod

Integer

60

[0..MAX_INT]

Configurable duration of delay to wait after the ICCP server instances failed in succession.

Controls

Boolean

F

[T, F]

Boolean value indicating use of the controls table for Block 5 functionality.

QualityCodeUseOnAssociationTimeOut

Integer

0

[0..MAX_INT]

Quality code that will be sent to DDService when the communication with ICCP server is lost. A valid QualityCode must be specified if this option is used.

DisableStop

Boolean

F

[T, F]

Normally the adapter will accept and process a stop high level message. This option disables this feature. When this feature is enabled, the adapter will disregard a stop high level message.

DisableCOV

Boolean

F

[T, F]

Normally the adapter will process a COV update (one or more open and close sequences within a scan cycle - normally indicating one or more momentaries) and send it to DDService. This option disables this feature.

IgnoreCritInterSysServFail

Boolean

F

[T, F]

Normally the adapter will stop if SMSserivce reports a critical service failure and not restart until services are recovered. This option disables this feature.

NoSwitchOpQualityMask

Integer

No Mask

[0..MAX_INT]

This parameter sets the quality codes that prevent switches from being operated. There is no effect on non-switch statuses.

PhaseEncodeSwitch

Boolean

F

[T, F]

If set to true, this will enable Iccp Adapter to interpret data discrete values as three-bit phase encoded statuses. [e.g., A = ‘001’, B = ‘010’, C = ‘100’, etc.]

PseudoAlarms

Boolean

F

[T, F]

If set to 1, then this will set the pseudo flag for the switch entry to be sent to DDService. Generates pseudo (advisory) alarms for ICCP reported device ops rather than actually operating the switches in the Oracle Utilities Network Management System model.

SendTimeout

Integer

10

[0..MAX_INT]

Timeout setting for the connection to the ICCP server.

[VCC]

Marker

ICCP Domain (VCC) Configuration.

Server TSEL

String

<Required>

OSI Transport Service Access Point (TSAP) Selector of the ICCP server.

ServerSSEL

String

<Required>

OSI Session Service Access Point (SSAP) Selector of the ICCP server.

ServerPSEL

String

<Required>

OSI Presentation Service Access Point (PSAP) Selector of the ICCP server.

ServerAP Title

String

<Required>

Application Process Title of the ICCP server.

DomainName

String

<Required>

ICCP Domain Name

TransferSets

String

<Required>

Comma-separated list of ICCP Data Transfer Sets.

ClientTSEL

String

<Required>

OSI Transport Service Access Point (TSAP) Selector of the TMW ICCP Adapter.

ClientSSEL

String

<Required>

OSI Session Service Access Point (SSAP) Selector of the TMW ICCP Adapter.

ClientPSEL

String

<Required>

OSI Presentation Service Access Point (PSAP) Selector of the TMW ICCP Adapter.

ClientAPTitle

String

<Required>

Application Process Title of the TMW ICCP Adapter.

[ValidityQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Validity Quality values

Valid

Integer

0

2**n (n=11->31)

The value is valid. This is the default (normal) value should virtually always be 0.

Held

Integer

0

2**n (n=11->31)

Previous data value has been held over. Interpretation is local.

Suspect

Integer

0

2**n (n=11->31)

Data value is questionable. Interpretation is local.

Notvalid

Integer

0

2**n (n=11->31)

The value is not valid.

[CurrentSourceQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Current Source Quality values.

Telemetered

Integer

0

2**n (n=11->31)

Value was received from a telemetered site. This is the default (normal) value should virtually always be 0.

Calculated

Integer

0

2**n (n=11->31)

Value was calculated based on other data.

Entered

Integer

0

2**n (n=11->31)

Value was entered manually.

Estimated

Integer

0

2**n (n=11->31)

Value was estimated (State Estimator, etc.).

[NormalValueQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Normal Value Quality values.

Normal

Integer

0

2**n (n=11->31)

The point value is that which has been configured as normal for the point. This is the default (normal) value should virtually always be 0.

Abnormal

Integer

0

2**n (n=11->31)

The point value is not that which has been configured as normal for the point.

[TimeStampQuality]

Marker

Assign an Oracle Utilities Network Management System quality to ICCP Timestamp Quality values

Valid

Integer

0

2**n (n=11->31)

Current value of the TimeStamp attribute contains the time stamp of when the value was last changed. This is the default (normal) value should virtually always be 0.

Invalid

Integer

0

2**n (n=1->31)

Current value of the TimeStamp attribute contains the time stamp other than when the value was last changed.

[SwitchStatusQuality]

Marker

Assign an Oracle Utilities Network Management System quality to the non-open/close statuses that can be returned in the two-bit ICCP status field. ICCP "open" is generally (1) and "closed" is (2).

Between

Integer

262144

2**n (n=11->31)

Quality code to set if the two bit ICCP switch status is reported as "between" (0).

Invalid

Integer

524288

2**n (n=11->31)

Quality code to set if the two bit ICCP switch status is reported as "invalid" (3).

Sample Tase2Adapter.prm Configuration File

[Tase2Adapter]

ServerHostname=128.168.148.43

Period=10

ScadaId=300

StatusUpdates=25

Analogs=T

AnalogTolerance=.001

Digitals=T

ReconnectPeriod=60

QualityCodeUseOnAssociationTimeOut=16384

DisableCOV=F

PhaseEncodeSwitch=T

SendTimeout=30

[VCC]

ServerTSEL=00 23

ServerSSEL=00 23

ServerPSET=00 23

ServerAPTitle=1,1,999,1

DomainName=NMS

TransferSets=DSTrans1,DSTrans2

ServerTSEL=00 24

ServerSSEL=00 24

ServerPSET=00 24

ServerAPTitle=1,1,999,2

[ValidityQuality]

Valid=

Held=

Suspect=

Notvalid=1048576

[CurrentSourceQuality]

Telemetered=

Calculated=

Entered=

Estimated=2097152

[NormalValueQuality]

Normal=

Abnormal=

[TimeStampQuality]

Valid=

Invalid=

Quality Codes

The Tase2Adapter.prm file enables ICCP quality codes to be translated into Oracle Utilities Network Management System quality codes. In the simplest (and default) configuration, all of the ICCP quality codes (except the Between and Invalid SwitchStatusQuality codes, which need to be defined to ensure proper operation) are assigned to the 'normal' Oracle Utilities Network Management System quality code (0).

Note : Oracle Utilities Network Management System quality codes are always single bit values. Therefore, the only valid value for configuration is 0 or a proper value of 2^nth power where n=0->31. The Quality Rules Table table lists all the valid user-defined quality codes in Oracle Utilities Network Management System.

If none of the predefined quality codes are applicable, then a new code must be created. The following steps accomplish this:

•

Choose an ICCP quality listed in the Tase2Adapter.prm.

•

Check the Quality Rules Table to see which values have already been assigned to qualities.

•

Assign one of the values listed below to the ICCP quality and enter it in the Quality Rules Table .

•

Locate the quality in the Tase2Adapter.prm file and enter the assigned value for it.

The assigned value must be the decimal representation of 32 bits, where no more than one bit has a value of 1. For example, if the bit position is 11, use the number 2048. The following list contains the decimal values that may be assigned to new qualities: 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288, 1048576, 2097152, 4194304, 8388608, 16777216, 33554432, 67108864, 134217728, 268435456, 536870912, 1073741824, 2147483648.

Values of 0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 may not be assigned as codes for new qualities because they are already defined and used within Oracle Utilities Network Management System. The ‘normal’ Oracle Utilities Network Management System quality code is 0.

The adapter reads the Tase2Adapter.prm file only during startup. If the quality code is added when the adapter is running, you must restart the adapter in order for it to recognize the new quality code.

High Level Messages

The TMW ICCP Adapter can be dynamically controlled from Oracle Utilities Network Management System by using high-level messages. They can be used any time while running the Oracle Utilities Network Management System TMW ICCP Adapter. The following high-level messages can be used:

•

stop

Disconnect from the ICCP server and stop the Oracle Utilities Network Management System TMW ICCP Adapter.

•

report

Empty message to determine how many Oracle Utilities Network Management System TMW ICCP Adapters are running.

•

debug [on | off | #]

Turn on/off debug, or set it to a specific level. On is equivalent to 1, off is 0. Level can be any integer value no less than 0.

•

debug <facility> #

Turn facility specific debug on/off. For example, to turn IA_ICCP debug on to level 3:

Action any.Tase2Adapter debug IA_ICCP 3

To turn off:

Action any.Tase2Adapter debug IA_ICCP 0

Check TMW ICCP Adapter specific log file for other facilities specific to this adapter process.

Populating the NMS Measurements Tables

ICCP points must first be mapped to devices in the Oracle Utilities Network Management System model before sending SCADA updates to Oracle Utilities Network Management System. These ICCP points are placed in SCADA_MEASUREMENTS_ST table of the Oracle Utilities Network Management System database. A process needs to be formalized to create and maintain this data. This process often depends on customer specific mechanisms used to maintain the SCADA side of the ICCP interface.

Required NMS Data

The following data items are required to be populated in the NMS measurements tables:

•

ICCP Point Name

•

Attribute

•

SCADA ID

•

NMS Device Handle

•

Measurement Type

ICCP Point Name

•

ICCP Point Name has to be unique.

•

It is recommended for the name to be composed of alpha-numeric characters and underscore

•

It is recommended for the first character of the ICCP Name to be a letter

•

There should be no space, no periods and no dashes in the ICCP name.

Attribute

•

The attribute value connects a SCADA measurement to a specific device attribute in NMS. The attribute should have a corresponding entry in the ATTRIBUTES table.

SCADA ID

•

SCADA system identifier. There should be a corresponding entry in the SCADA_IDS table.

NMS Device Handle

•

The NMS Device Handle is the handle of the device in the NMS model associated with a particular ICCP Point. A single NMS device can have multiple ICCP points associated with it for different measurements that the SCADA system provides for the given device.

Measurement Type

•

Each ICCP point represents either digital (including device status) or analog measurement.

Information Model - Database Schema

Quality Rules Table

This database table will define the quality codes that may be used for analog and digital values. This table defines the meaning of each bit in the quality codes for SCADA measurements.

Column Name

Data Type

Size

Description

Values

PRIORITY

NUMBER

Ranking priority of the quality code

Priority code, specifies relative importance of this quality bit over other quality bits

VALUE

NUMBER

Bit value used for the quality code change.

For Phase 1:

2048=No Data

4096=Old Data

STRING

VARCHAR2

3

Description of the quality code, which is displayed next to the value of the measurement when a quality exists for a measurement change.

The actual character string displayed next to the device when viewed via the Viewer

DESCRIPTION

VARCHAR2

128

Descriptive string

Any text string-usually the action taken from the SCADA Summary

COLOR

NUMBER

Designates which color is used in the Viewer to display the measurement when a particular quality bit is set.

Integer value for the color associated to the quality code change to be displayed

The integers are mapped to the pre-allocated colors documented in separate application file.

LOCATION

NUMBER

Location of symbol in relation to the device associated with the value.

only used if a symbol is defined for the quality code as opposed to just a color for a quality change

1-9; 5 overrides the device symbol

SYMBOL

NUMBER

The symbol used to display the value. only used if a symbol is defined for the quality code as opposed to just a color for a quality change

Valid Symbol Identification Number defined in <project>_SYMBOLS.sym. 0 if defining a text symbol.

OFF_NOMINAL

VARCHAR2

1

Whether or not the value is off-nominal

Y or N

Note: If multiple bits in the quality code are set, then the color of the measurement text in the Viewer is determined by the color of the lowest order bit that is set in the quality code.

SCADA Measurements Table

The SCADA_MEASUREMENTS_ST table defines digital and analog measurements as used by Oracle Utilities Network Management System. It is a staging table used by DDService for populating the production SCADA measurements tables (ANALOG_MEASUREMENTS and DIGITAL_MEASUREMENTS).

The Oracle Utilities Network Management System ICCP Adapter communicates dynamic information to the Oracle Utilities Network Management System services. The services will cache measurements defined by this table. Population is dependent upon customer-supplied information.

Column Name

Data Type

Size

Description

Values

MEASUREMENT_TYPE

VARCHAR2

1

Measurement type code.

A (analog)

D (digital)

H_CLS

NUMBER

Class component of handle

Valid object class

H_IDX

NUMBER

Index component of handle

>0

PARTITION

NUMBER

Partition number, index component of partition handle

Valid partition or 0 for multi-partition objects

ATTRIBUTE

NUMBER

Attribute number which identifies measurement type

Valid attribute number

TTL

NUMBER

Setting for displaying measurement value in the Viewer or not.

1 or 0. 1=yes

LIMIT_GROUP_ID

NUMBER

Limit group ID

Customer defined

RTI_ALIAS

VARCHAR2

128

ICCP Point Name

Alphanumeric

SCADA_ID

NUMBER

SCADA host ID

Foreign key into SCADA_IDS database table.

RTU_ID

VARCHAR2

32

SCADA RTU ID

String (optional)

QUALITY

NUMBER

Measurement quality code

Bit mask of quality codes

VALUE

NUMBER

Measurement/entered value

Entered value

UPDATE_FLAG

NUMBER

Manual replace flag

1=true, 0=false

ICCP_OBJECT

VARCHAR2

32

DISPLAY_ID

VARCHAR2

64

NORMAL_STATE

NUMBER

CONTROLLABLE

VARCHAR2

1

ACTIVE

VARCHAR2

1

Active flag for patch management, indicates whether the row is active within the model

Y(yes=active), N(no=inactive), A(local add=active), D(local delete=inactive), R(locally removed, dependent=inactive)

SOURCE

VARCHAR2

33

Source of the measurement.

any character string.

OFF_NOMINAL_TIME

DATE

SCADA_IDS

SCADA_IDS contains information about known SCADA systems that NMS is connected to. The TMW ICCP Adapter needs to have an entry in this table.

Column Name

Data Type

Size

Description

Values

ID

NUMBER

SCADA system id

SCADA_NAME

VARCHAR2

32

SCADA system name

ADAPTER_TYPE

VARCHAR2

32

Adapter used to communicate with the SCADA system

MULTISPEAK - MultiSpeak SCADA Adapter

RTADAPTER - Generic SCADA Adapter

ICCP - ICCP Adapter

ACTIVE

VARCHAR2

1

Active flag

Y - active

N - inactive

MultiSpeak Adapter

This chapter includes the following topics:

•

Introduction

•

Installation

•

Software Configuration

•

Adapter Interface Communication Overview

•

Adapter Design

•

Database Schema

•

SCADA Component

•

Supported Data Flows

•

Software Configuration

•

Plugin Support

•

High-Level Messages

Introduction

The Oracle Utilities Network Management System MultiSpeak Adapter provides the ability to request and receive meter status information from an Automated Meter Reading (AMR) system, to receive crew location information from an Automated Vehicle Location (AVL) system, and to communicate with SCADA systems. The interface uses communication protocols as defined in MultiSpeak Version 4.1 Web Services specification. (SOAP protocol version 1.1 is used unless otherwise noted.) HTTPS protocol is used as transport mechanism (plain HTTP is not supported). It allows Oracle Utilities Network Management System to communicate securely with any MultiSpeak-compliant AMR, AVL, or SCADA system. In addition to HTTPS, communication with SCADA systems can be done over JMS.

The Oracle Utilities Network Management System MultiSpeak Adapter is implemented as a Java application, running on the Oracle WebLogic Server platform.

Please read through this chapter thoroughly before beginning your product installation.

Installation

This chapter describes how you install the Oracle Utilities Network Management System MultiSpeak Adapter, including:

•

Manual Installation Instructions for Oracle WebLogic Server

Note : It is assumed that the Oracle Utilities Network Management System Web Gateway component has already been installed. Refer to the Oracle Utilities Network Management System Installation Guide for complete instructions on how to install and configure the Oracle Utilities Network Management System Web Gateway.

Installation Overview

The Oracle Utilities Network Management System MultiSpeak Adapter is delivered as five files:

•

$CES_HOME/dist/install/nms-multispeak.ear.base : NMS Multispeak adapter application.

•

$CES_HOME/sdk/java/lib/multispeak-4.1.0.jar : Java classes generated from MultiSpeak 4.1.0 WSDLs.

•

$CES_HOME/sdk/java/lib/nms-multispeak-sdk-1.11.0.4.jar : Java classes needed to build custom plugins.

•

$CES_HOME/sdk/java/docs/nms-multispeak-docs.zip : Documentation (javadoc) for classes included into multispeak-4.1.0.jar and nms-multispeak-sdk-1.11.0.4.jar archives.

•

$CES_HOME/sdk/java/samples/nms-multispeak-plugins.zip : Java project, which can be used as a starting point for building custom plugins for SCADA components of the NMS MultiSpeak adapter.

The nms-install-config script has to be used in order to apply adapter configuration changes and create the nms-multispeak.ear file, which can be deployed to the Oracle WebLogic Server (see Software Configuration on page 10-3 for configuration instructions).

Note that the nms-multispeak.ear cannot be installed on the same managed server where the cesejb.ear is deployed since the cesejb.ear must be deployed to its own server.

Adapter Installation Instructions for Oracle WebLogic Server

The installation has two main steps: creating a Foreign JNDI Provider and deploying the adapter.

Create Foreign JNDI Provider

In order for the Oracle Utilities Network Management System MultiSpeak Adapter to communicate with the Oracle Utilities Network Management System (cesejb.ear), a foreign JNDI provider must be configured.

Note: This makes the cesejb.ear EJBs appear local to the Oracle Utilities Network Management System MultiSpeak adapter.

Creating the Foreign JNDI Provider can be done through the WebLogic Server Administration Console.

1.

Access the WebLogic Server Administration Console by entering the following URL:

http:// hostname:port/console

Here hostname represents the DNS name or IP address of the Administration Server, and port represents the number of the port on which the Administration Server is listening for requests (port 7001 by default).

2.

If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.

3.

In the Domain Structure tree, expand Services, then select Foreign JNDI Providers to open the Summary of Foreign JNDI Providers page.

4.

Click New.

5.

Enter a name for the new Foreign JNDI Provider.

6.

Click Finish.

7.

Click the link to the new Foreign JNDI Provider in the table to open the Settings.

8.

Populate following fields:

Initial Context Factory: weblogic.jndi.WLInitialContextFactory

Provider URL: JNDI provider URL for the NMS (cesejb.ear)

User: valid NMS user

Password: password for the NMS user

Confirm: Password: same as Password

9.

Click Save.

10.

Click the Links tab.

11.

Create links to both the Local JNDI Name and the Remote JNDI Name fields set to 'cesejb/Session/remote'.

12.

Click Targets tab.

13.

Check the checkbox for the managed server where NMS MultiSpeak adapter will be deployed and click Save.

Deploy the Adapter

1.

In the left pane of the Administration Console, select Deployments.

2.

In the right pane, click Install.

3.

In the Install Application Assistant, locate the nms-multispeak.ear file.

4.

Click Next.

5.

Specify that you want to target the installation as an application.

6.

Click Next.

7.

Select the servers and/or clusters to which you want to deploy the application.

Note: If you have not created additional Managed Servers or clusters, you will not see this assistant page.

8.

Click Next.

9.

Set the deployed name of the application to: nms-multispeak.

10.

Click Next.

11.

Review the configuration settings you have specified, and click Finish to complete the installation.

Software Configuration

Configuration for the AMR and AVL components of the Oracle Utilities Network Management System MultiSpeak Adapter comes from the following sources:

•

CES_PARAMETERS database table

•

Oracle Utilities Network Management System Configuration Rules

Support for Encrypted Configuration Parameters

Some configuration parameters that are stored in the CES_PARAMETERS database table contain sensitive information, such as authentication credentials, which should be protected. To protect this data, the VALUES column can be encrypted using Oracle WebLogic Server encrypt utility. This utility encrypts cleartext strings for use with Oracle WebLogic Server. Its output can then be used to populate values in CES_PARAMETERS database table.

For detailed information see "encrypt" in the Oracle WebLogic Server Command Reference.

AMR Configuration Parameters

Entries in the CES_PARAMETERS database table for the AMR component of the Oracle Utilities Network Management System MultiSpeak Adapter should have value 'AMRInterface' in the APP column. Column ATTRIB should contain name of the configuration parameter and column VALUE its value.

The following table describes the general configuration parameters.

Parameter

Description

config.credentials

Absolute path to the file containing user credentials the adapter will use to communicate with Oracle Utilities Network Management System.

This parameter is required.

config.amr_vendor

AMR vendor.

Supported AMR vendors:

•

multispeak - MultiSpeak-compliant AMR system

This parameter is required.

Default: multispeak

config.ping_request_interval

Time interval in seconds between subsequent meter ping requests to the AMR system.

Default:60 seconds

config.enabled

Enables AMR processing.

Default: true

config.unsolicited_message_deadband

Deadband value in seconds for unsolicited messages reporting same status for a meter. If several unsolicited messages of the same type are received within the deadband then only one of them will be processed.

Default: 60 seconds

config.max_meter_status_age

Period of time in seconds after which meter status information received from AMR system is considered stale and has to be obtained from the AMR system again.

Default: 300 seconds

config.max_ping_request_age

If difference between the current time and ping request time is greater than value of this parameter then the request is too old to be sent to the AMR system. Such requests are marked as completed in the AMR_RESPONSES table. The value is defined in seconds.

Default: 3600 seconds

The following table describes configuration parameters specific to a particular AMR vendor. This could be any MultiSpeak-compliant AMR system.

Parameter

Description

multispeak.meter_status.< external status>

This parameter configures mapping between external (MultiSpeak) and internal meter status values. Valid values are:

ON - meter is energizedOFF - meter is deenergized UNKNOWN - external meter status has no configured mapping,

Examples:multispeak.meter_status.Outage=OFF multispeak.meter_status.PowerOff=OFF multispeak.meter_status.PowerOn=ON multispeak.meter_status.Restoration=ON multispeak.meter_status.Instantaneous=UNKNOWN multispeak.meter_status.NoResponse=UNKNOWN multispeak.meter_status.Inferred=UNKNOWN

multispeak.od_oa.url

This parameter configures the URL of the AMR system web service.

Default: https://localhost/multispeak

multispeak.od_oa.username

Username to use when connecting to the AMR system web service.

Default: empty string

multispeak.od_oa.password

Password to use when connecting to the AMR system web service.

Default: empty string

multispeak.od_oa.header.<attribute>

Used to set the values for MultiSpeak header attributes. For example, the following would set the MultiSpeak header attribute "Company" to the value "Oracle":

multispeak.od_oa.header.Company=Oracle

multispeak.od_oa.soap12

Indicates the SOAP protocol version to use for communicating with the AMR/AMI system. If true, version 1.2 will be used. Otherwise, version 1.1 will be used.

Default: false (SOAP version 1.1 is used)

multispeak.max_ping_attempts

Maximum number of attempts to ping a meter.

Default: 3

multispeak.ping_attempt_interval

Amount of time in seconds to wait for reply from the AMR system before resending meter ping request.

Default: 60 seconds

multispeak.send_meter_number_field

This parameter designates which field in the InitiateOutageDetectionEventRequest message should be used to submit meter numbers to the AMR system.

Valid values:

•

meterID - meterID element should be used

•

objectID - objected attribute should be used

•

meterNo - meterNo attribute should be used

Default: meterID

multispeak.unsolicited_meter_statuses

Comma-separated list of meter statuses for unsolicited "power up" and "last gasp" messages.

Example:

multispeak.unsolicited_meter_statuses=Outage,Restoration

AVL Configuration Parameters

Entries in the CES_PARAMETERS database table for the AVL component of the Oracle Utilities Network Management System MultiSpeak Adapter should have value 'AVLInterface' in the APP column. Column ATTRIB should contain the name of the configuration parameter and the column VALUE should contain its value.

The AVL component requires configuration for converting crew location information received from the AVL system into the Oracle Utilities Network Management System coordinate system. Coordinate conversion is done using reference point coordinates that are known for both systems. At least two reference points are required for coordinate conversion to work.

The AVL configuration parameters are described in the following table:

Parameter

Description

config.credentials

Absolute path to the file containing user credentials the adapter will use to communicate with Oracle Utilities Network Management System during initialization process. This parameter is required.

avl.num_reference_points

Number of configured reference points

avl.reference_point<N>.x

X coordinate of the reference point N in the Oracle Utilities Network Management System coordinate system

avl.reference_point<N>.y

Y coordinate of the reference point N in the Oracle Utilities Network Management System coordinate system

avl.reference_point<N>.longitude

Geographic longitude of the reference point N

avl.reference_point<N>.latitude

Geographic latitude of the reference point N

avl.xy_scale

Number of decimal points to use when rounding X/Y coordinates

avl.lat_long_scale

Number of decimal points for rounding longitude/latitude coordinates

config.enabled

Enables AVL processing

Default: true

Credentials Files

Credentials files are used to configure usernames and passwords to be used by the parts of the adapter that communicate with the Oracle Utilities Network Management System.

Credentials files should only be readably by the operating system account under which application server is running.

The format of a credentials file is described in the following table:

Property

Description

nms.username

Valid NMS username.

nms.password

NMS user password

The following illustration shows a sample credentials file.

#

nms.username=amr

nms.password=amr-user-password

Oracle Utilities Network Management System Configuration Rules

Below is the list of configuration rules in the Oracle Utilities Network Management System, which control AMR-related functionality. These rules are not directly used by the Oracle Utilities Network Management System MultiSpeak Adapter.

amrInterfacesEnabled

This rule enables AMR processing in JMService. Its value indicates the AMR processing types that are available. AMR processing is disabled if this rule is set to 0 (default value).

Available types of AMR processing:

•

1 - Outage detection

•

2 - PSO verification

•

4 - PDO verification

•

8 - Restoration verification

•

16 - Manual AMR processing

The rule value is a bitmask, which allows any combination of AMR processing types to be enabled. For example, if the rule is set to 9 then Outage Detection and Restoration Verification will be enabled.

meterOffThreshold

Maximum probability of meter having power when meter is still assumed to be "off". Default value is 0.

meterOffTroubleCode

Trouble code to be used when a call should be created because of information received from AMR system.

meterOnThreshold

Minimum probability of meter having power when meter is still assumed to be "on". Default value is 100.

meterQueryThreshold

This parameter is used to determine if a meter can be queried when an active request exists. When a new request is made, existing requests will be evaluated to see if any contain meter(s) from the new request. If a match is found, and the difference between the time the request was received and current time is less than value of this rule in seconds, that meter will be rejected from the new request. If set to -1 (default value), this rule will not be enforced.

meterPingPercentage

This parameter governs the percentage of meters to ping for an AMR action. When set to 100, it will ping all AMR meters downstream from the outage device. When set to -1, it will ping one AMR meter on each SND. When set to any other number between 1 and 99, JMService will attempt to ping the specified percentage of meters for each transformer affected by the outage (the resulting number of meters is rounded up so that at least one meter per transformer is pinged). It is possible to configure this rule differently for different device classes. Default value of this rule is 100.

useMeterTimeForDetection

This configuration rule determines if meter read time reported by AMR system should be used as call time for incidents created by outage detection functionality.

Valid values:

•

0 - Meter read time will not be used, instead current system time will be used (this is the default behavior)

•

1 - Meter read time will be used

useMeterTimeForRestoration

This configuration rule determines if meter read time reported by AMR system should be used to adjust outage restoration time as part of outage restoration verification functionality.

Valid values:

•

0 - outage restoration time will not be modified

•

1 - outage restoration time will be updated with the latest meter read time amongst the meters which reported power on for the restored outage (this is the default behavior)

meterRequestSendDelay

This configuration rule is used to control how long the outage prediction engine should wait before sending a meter ping request to the MultiSpeak adapter. This rule is only applicable for PSO Verification, PDO Verification, and Restoration Verification requests.

meterRequestTTL

This configuration rule is used to control the "time-to-live" (TTL) for meter ping requests. This is the period of time NMS will wait for a responses from AMR system.

TTL is configurable per request type. It can either be a fixed value (for example, the PSO Verification request can remain active for 15 minutes) or it can be calculated based on the number of meters in the request combined with minimum and maximum values. If TTL is set to 0, then the meter ping request remains active until the first response is received.

meterPingSuppress

This configuration rule can be used to suppress sending meter ping requests to the AMR system based on the request type.

Adapter Interface Communication Overview

The Oracle Utilities Network Management System MultiSpeak Adapter provides a reliable and configurable way of connecting MultiSpeak-compliant AMR, AVL, and SCADA systems to the Oracle Utilities Network Management System. The interface connects to the AMR systems by use of MultiSpeak-compliant SOAP/XML calls over the HTTPS protocol. For SCADA integration, JMS queues can also be used as the transport mechanism. The interface connects to the Oracle Utilities Network Management System through direct database access using JDBC and by use of a CORBA connection through the Oracle Utilities Network Management System Web Gateway.

Adapter Design

Supported Data Flows

Oracle Utilities Network Management System MultiSpeak Adapter supports following data flows described in the MultiSpeak Web Services Version 4.1 specification.

Oracle Utilities Network Management System to an AMR system:

•

InitiateOutageDetectionEventRequest

Oracle Utilities Network Management System requests meter status information from the AMR system.

An AMR system to Oracle Utilities Network Management System:

•

ODEventNotification

AMR system reports meter status information to the Oracle Utilities Network Management System.

An AVL system to Oracle Utilities Network Management System:

•

AVLChangedNotification

AVL system reports crew location information to the Oracle Utilities Network Management System.

Incoming requests (ODEventNotification and AVLChangedNotification) are authenticated against list of valid Oracle Utilities Network Management System users. Username and password has to be provided in the header of each incoming MultiSpeak message.

AMR Business Processes

This section describes the utility business processes related to AMR that can be supported through the Oracle Utilities Network Management System MultiSpeak Adapter.

Outage Detection

The vendor AMR system detects no power for a meter, either because of a "last gasp" meter message or from scheduled meter polling. A "power out" call is submitted to Oracle Utilities Network Management System, which generates a probable outage event.

PSO Verification

One customer call is received, generating a probable service outage in Oracle Utilities Network Management System. The Oracle Utilities Network Management System MultiSpeak Adapter is notified of the new probable outage, and the customer meter is pinged to verify power status.

If the meter reports that the power is still on, then we have conflicting information from the customer and the meter, so the outage predication engine will set the status of this event to Verify. At this point, we believe that there is no outage, but that the customer has a problem, such as a blown fuse, within his home. This event must be resolved by a customer service representative contacting the caller to explain the situation to them.

PDO Verification

Several customer calls are received, which are submitted into the Oracle Utilities Network Management System. The resulting probably outage rolls up to a device. The list of affected AMR customers is provided to the Oracle Utilities Network Management System MultiSpeak Adapter by the Oracle Utilities Network Management System outage prediction engine. The interface submits meter status requests to the AMR for any of the affected meters from which it has not already received a last gasp message. The received meter statuses are sent back to the prediction engine and the predicted outage device may change by moving downstream.

Restoration Verification

An outage event is restored in Oracle Utilities Network Management System, and a list of affected meters is provided by the outage prediction engine to the Oracle Utilities Network Management System MultiSpeak Adapter. The interface submits meter status requests to the AMR for any of the affected meters from which it has not received a "power up" message. The results are passed back to the Oracle Utilities Network Management System and the periodic cycle for getting outage events continues. The received meter statuses are sent back to the prediction engine. A power out status will result in another outage call and a nested outage that still needs restoration.

Unsolicited Power Ups

The AMR system can send unsolicited power up message when it detects that meter power has been restored. The adapter delivers such messages to the outage prediction engine, which uses them as part of Restoration Verification processing.

Manual Ping

In the diagram below, please note that the number indicates the sequence of actions:

1.

The operator or system has chosen a device to "Ping".

2.

Information about the new ping request is stored in the database.

3.

The AMR application notes the new ping request and verifies the device.

4.

A response is received from the meter.

5.

The database is updated with some information about the request response. Oracle Utilities Network Management System is aware of the response data in the database and displays relevant information.

Database Schema

Oracle Utilities Network Management System MultiSpeak Adapter uses several databases tables to store meter status information received from the AMR system and pending meter ping requests.

AMR_REQUESTS

AMR_REQUESTS is populated by the outage prediction engine when a request for meter information is submitted. There is one row per request, and each request can involve multiple meters.

Field

DataType

Nullable

Comments

REQUEST_IDX

NUMBER

No

AMR request id.

PRIMARY KEY

EVENT_CLS

NUMBER

No

The class part of the handle of the event for which the AMR request was made.

EVENT_IDX

NUMBER

No

The index part of the handle of the event for which the AMR request was made.

REQUEST_TIME

DATE

No

The timestamp when the AMR request was created.

WHO_REQUESTED

VARCHAR2(32)

Yes

User name of the operator who created the AMR request.

AMR_COMPLETE_TIME

DATE

Yes

The timestamp when the AMR request was completed or cancelled.

WHO_COMPLETED

VARCHAR2(32)

Yes

User name of the operator who completed or cancelled the AMR request.

REQUEST_TYPE

NUMBER

Yes

Request type.

Possible values:

•

1 - PSO Verification

•

2 - PDO Verification

•

3 - Restoration Verification

•

4 - Manual

QUERY_TYPE

NUMBER

Yes

Query type.

Possible values:

•

0 - simple meter status query

•

1 - complex meter information query

STATUS

NUMBER

Yes

Status of the AMR request.

Possible values:

1- active

2 - explicitly completed

3 -cancelled

DEVICE_CLS

NUMBER

Yes

The class part of the handle of the device for which the AMR request was made.

DEVICE_IDX

NUMBER

Yes

The index part of the handle of the device for which the AMR request was made.

NCG

NUMBER

Yes

NCG of the device for which the AMR request was made.

TTL

NUMBER(9)

Yes

The Time-To-Live of the request in seconds.

AMR_RESPONSES

The AMR_RESPONSES table is used to transfer meter status information between the outage prediction engine and the MultiSpeak adapter. The outage prediction engine inserts rows into this table when a request for meter information is submitted. Every request in AMR_RESPONSES is represented by one row for each meter requested. The MultiSpeak adapter updates this table as requested meter status information becomes available.

Field

DataType

Nullable

Comments

ID

Number

No

Unique record identifier. PRIMARY KEY

REQUEST_IDX

NUMBER

Yes

AMR request id.

REQUEST_TIME

DATE

Yes

Request timestamp.

METER_NO

VARCHAR2(256)

Yes

Meter number as known to the AMR system

METER_ID

NUMBER

No

NMS meter identifier.

REQUEST_STATUS

VARCHAR2(1)

Yes

Request status.

Possible values:

•

N - new request (not yet sent to AMR)

•

P - pending request (waiting for AMR response)

•

S - suppressed request

•

R - AMR response received

•

C - completed request

STATUS

VARCHAR2(256)

Yes

Meter status received from AMR.

Possible values:

•

ON - meter has power

•

OFF - meter does not have power

AMR_ERROR

VARCHAR2(256)

Yes

Error message received from the AMR system.

RECEIVED_TIME

DATE

Yes

Timestamp when the response was received from the AMR system.

RESULT_TIME

DATE

Yes

Timestamp returned by the AMR system for the meter status.

PROBABILITY

NUMBER

Yes

The probability of the meter having power (0 - no power; 100 - meter has power.)

STATUS

NUMBER(3)

Yes

Response status string

AMR_CU_METERS

Table AMR_CU_METERS contains information about all meters known to the Oracle Utilities Network Management System. This table is also used to cache the latest known meter status information to reduce the number of requests to the AMR system.

Field

DataType

Nullable

Comments

METER_ID

VARCHAR2(14)

No

Meter identifier in Oracle Utilities Network Management System.

METER_NO

VARCHAR2(20)

Yes

Meter identifier used by the AMR system.

RESULT_TIME

DATE

Yes

Timestamp of the latest meter status update.

POWER_UP_TIME

DATE

Yes

Timestamp of the latest power-up message.

LAST_GASP_TIME

DATE

Yes

Timestamp of the latest "last gasp" message.

ALT_METER_NO

VARCHAR2(256)

Yes

Alternative meter number.

AMR_ENABLED

VARCHAR2(1)

Yes

Indicator that meter is AMR-enabled.

STATUS

VARCHAR2(256)

Yes

Latest known meter status.

Possible values:

•

ON - meter has power

•

OFF - meter does not have power

REQUEST_IDX

NUMBER

Yes

AMR request id for the latest received meter status.

PROBABILITY

NUMBER

Yes

Latest known probability of the meter having power (0 - no power; 100 - meter has power).

AMR_CU_METERS_HISTORY

The AMR_CU_METERS_HISTORY table is used to store all meter status updates received from the AMR system. This table has the same columns as the AMR_CU_METERS table.

SCADA Component

The Oracle Utilities Network Management System MultiSpeak Adapter’s SCADA component has the capability of interacting with SCADA systems having a MultiSpeak-compatible interface.

The following functionality is available:

•

Receiving device status updates from SCADA system

•

Receiving analog and digital measurement updates from SCADA system

•

Mapping of SCADA quality codes (applies to status and measurement updates)

•

Receiving tag information from SCADA system

•

Receiving alarm information from SCADA system

•

Sending control request to SCADA system to operate devices and place/remove tags

•

Sending status information for non-SCADA devices to SCADA system

•

Dynamic configuration of the mapping between SCADA points and NMS device/attribute pairs

•

Display integration between NMS and SCADA system

A single instance of the adapter is capable of communicating with multiple SCADA systems. Several communication links can be configured for each SCADA system. If the currently active link fails, the adapter will automatically switch to the next link.

JMS Transport Mechanism

•

The JMS transport mechanism is based on the SOAP over JMS specification.

•

Two JMS queues are used per communication channel (one for requests and another for responses) to simulate synchronous communication.

•

Each individual request is synchronous. The system places the message on the request queue and waits for a reply to arrive on the response queue.

•

TextMessage or BytesMessage JMS message classes can be used. In both cases message must be a valid MultiSpeak message.

•

Requests and responses are connected through JMSCorrelationID JMS header.

•

In the request message, the JMS header JMSReplyTo must contain the queue where response message should be sent.

•

SOAP protocol versions 1.1 and 1.2 are supported.

•

There is no support for accessing a WSDL over JMS.

The following table describes how JMS message properties, specific to SOAP over JMS, are being used:

JMS Message Property

Value

SOAPJMS_bindingVersion

"1.0"

SOAPJMS_targetServer

"SCADA_Server" or "OA_Server" depending on the target system

SOAPJMS_soapAction

SOAP action

SOAPJMS_contentType

"text/xml; charset="utf-8""

SOAPJMS_isFault

"true" for SOAP fault messages

Configuring JMS Support

Incoming Data Flows

Support for accepting incoming requests over JMS in NMS MultiSpeak adapter is controlled by changing value of the config.multispeak_jms property in $NMS_CONFIG/jconfig/build.properties file.

Possible values:

•

none : JMS support is disabled

•

single : single JMS queue for all incoming data flows

•

multiple : separate JMS queue for each incoming data flow

By default JMS support is disabled.

After modifying the $NMS_CONFIG/jconfig/build.properties file, regenerate the nms-multispeak.ear with the new configuration by executing:

nms-install-config --java

JNDI names of JMS connection factory and queue(s) used for incoming data flows are fixed.

Connection Factory

nms-amr/ConnectionFactory

Queues

Single Queue Mode -

In single queue mode, all incoming requests are sent to the same JMS queue: nms-amr/queue/OA.

Multiple Queues Mode

When multiple incoming queues are used each incoming MultiSpeak data flow uses its own JMS queue.

List of JMS queues and associated MultiSpeak operations:

•

nms-amr/queue/OAPingURLPingURL

•

nms-amr/queue/OAGetMethodsGetMethods

•

nms-amr/queue/OAStatusChangedNotificationByPointIDSCADAStatusChangedNotificationSCADAStatusChangedNotificationByPointID

•

nms-amr/queue/OAStatusChangedNotificationByPointIDSyncStatusChangedNotificationByPointID

•

nms-amr/queue/OAAnalogChangedNotificationByPointIDSCADAAnalogChangedNotificationSCADAAnalogChangedNotificationByPointID

•

nms-amr/queue/OAAnalogChangedNotificationByPointIDSync AnalogChangedNotificationByPointID

•

nms-amr/queue/OATagChangedNotificationByPointIDSCADATagChangedNotificationSCADATagChangedNotificationByPointID

•

nms-amr/queue/OATagChangedNotificationByPointIDSync TagChangedNotificationByPointID

•

nms-amr/queue/OAInitiateStatusReadByPointID InitiateStatusReadByPointID

•

nms-amr/queue/OAHighlightObjectInDisplay HighlightObjectInDisplay

Outgoing Data Flows

The JMS connection factory for outgoing data flows is in defined in the CES_PARAMETERS database table.

The JMS queues used for outgoing messages are configured via SCADA_LINKS and SCADA_LINK_OPS database tables.

Supported Data Flows

NMS to SCADA

Heartbeat

PingURL

The adapter periodically sends PingURL message to the each configured SCADA system. Failure to send the message or error response from SCADA system (reply contains errorObject element) triggers switch to alternate link (if available). Upon restoration of communication with the SCADA system (PingURL has been sent successfully) synchronization sequence is executed.

PingURL request example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header>

<ns4:MultiSpeakMsgHeader xmlns:ns4="http://www.multispeak.org/

Version_4.1_Release" xmlns:ns3="http://www.w3.org/1999/xlink"

xmlns:ns2="gml" xmlns="cpsm" />

</S:Header>

<S:Body>

<ns4:PingURL xmlns:ns4="http://www.multispeak.org/Version_4.1_Release"

xmlns:ns3="http://www.w3.org/1999/xlink" xmlns:ns2="gml" xmlns="cpsm" />

</S:Body>

</S:Envelope>

Synchronization/Integrity check

The purpose of the synchronization sequence is to bring the state of devices in the NMS model up-to-date with the SCADA system. NMS supports two synchronization methods for device statuses, digital and analog measurements. At the beginning of the synchronization sequence, NMS will make GetMethods call to determine the list of operations supported by the SCADA system. Synchronization method selection is based on configured preferred method and available SCADA operations.

The synchronization sequence is executed automatically after the connection to a SCADA system is established. It also can be triggered manually using following command

Action -add_soap multispeak.SCADA resync

GetMethods

GetMethods retrieves lists of operations the SCADA system implements. It is used to determine available modes of syn-chronization. It is also used to determine if control requests can be send to SCADA.

GetMethods request and response example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header>

<ns4:MultiSpeakMsgHeader xmlns:ns4="http://www.multispeak.org/ Version_4.1_Release" xmlns:ns3="http://www.w3.org/1999/xlink" xmlns:ns2="gml" xmlns="cpsm" />

</S:Header>

<S:Body>

<ns4:GetMethods xmlns:ns4="http://www.multispeak.org/Version_4.1_Release"

xmlns:ns3="http://www.w3.org/1999/xlink" xmlns:ns2="gml" xmlns="cpsm" />

</S:Body>

</S:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release">

<soapenv:Header>

<ver:MultiSpeakMsgHeader/>

</soapenv:Header>

<soapenv:Body>

<ver:GetMethodsResponse>

<ver:GetMethodsResult>

<ver:string>PingURL</ver:string>

<ver:string>GetMethods</ver:string>

<ver:string>InitiateStatusReadByPointID</ver:string>

<ver:string>InitiateAnalogReadByPointID</ver:string>

<ver:string>InitiateControl</ver:string>

<ver:string>GetAllSCADAStatus</ver:string>

<ver:string>GetAllSCADAAnalogs</ver:string>

<ver:string>GetAllSCADATags</ver:string>

</ver:GetMethodsResult>

</ver:GetMethodsResponse>

</soapenv:Body>

</soapenv:Envelope>

GetAllSCADAStatus, GetAllSCADAAnalogs

The first synchronization method involves NMS invoking GetAllSCADAStatus and GetAllSCADAAnalogs operations to request the latest device statuses, digital and analog measurements from the SCADA. SCADA provides the requested information synchronously in the response message.

The MultiSpeak specification allows data to be returned in chunks by the SCADA system. In this case, NMS would have to make multiple GetAllSCADAXXX calls. The element lastReceived is included so that large sets of data can be returned in manageable blocks. lastReceived will carry an empty string the first time in a session that this method is invoked. When multiple calls to this method are required to obtain all of the data, the lastReceived should carry the objectID of the last data instance received in subsequent calls. If the ObjectsRemaining field is present in the MultiSpeak reply message’s message header, it will be used to determine when all of the data has been received. If the ObjectsRemaining field is not present, the empty result set will signal the end of the data.

GetAllSCADAStatus request and response example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header>

<ns4:MultiSpeakMsgHeader xmlns:ns4="http://www.multispeak.org/ Version_4.1_Release"

xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml"

Pwd="test" UserID="nms" />

</S:Header>

<S:Body>

<ns4:GetAllSCADAStatus xmlns:ns4="http://www.multispeak.org/ Version_4.1_Release"

xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml">

<ns4:lastReceived></ns4:lastReceived>

</ns4:GetAllSCADAStatus>

</S:Body>

</S:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release"

xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="scada" Pwd="test" AppName="Scada1"

ObjectsRemaining="0"/>

</soapenv:Header>

<soapenv:Body>

<ver:GetAllSCADAStatusResponse>

<ver:GetAllSCADAStatusResult>

<ver:scadaStatus>

<ver:objectName>BR_R-2241</ver:objectName>

<ver:quality>Initial</ver:quality>

<ver:status>Open</ver:status>

<ver:changeCounter>0</ver:changeCounter>

<ver:timeStamp>2011-03-01T11:11:11</ver:timeStamp>

</ver:scadaStatus>

</ver:GetAllSCADAStatusResult>

</ver:GetAllSCADAStatusResponse>

</soapenv:Body>

</soapenv:Envelope>

GetAllSCADAAnalogs request and response example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header>

<ns4:MultiSpeakMsgHeader xmlns:ns4="http://www.multispeak.org/ Version_4.1_Release"

xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml"

Pwd="test" UserID="nms" />

</S:Header>

<S:Body>

<ns4:GetAllSCADAAnalogs xmlns:ns4="http://www.multispeak.org/ Version_4.1_Release"

xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml">

<ns4:lastReceived></ns4:lastReceived>

</ns4:GetAllSCADAAnalogs>

</S:Body>

</S:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release"

xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="scada" Pwd="test" AppName="Scada1"

ObjectsRemaining="0" />

</soapenv:Header>

<soapenv:Body>

<ver:GetAllSCADAAnalogsResponse>

<ver:GetAllSCADAAnalogsResult>

<ver:scadaAnalog>

<ver:objectName>BR_R-2241</ver:objectName>

<ver:value units="Amps">260.78</ver:value>

<ver:quality>Measured</ver:quality>

<ver:timeStamp>2010-06-27T14:41:15-05:00</ver:timeStamp>

<ver:measurementTypeID>Amps</ver:measurementTypeID>

</ver:scadaAnalog>

<ver:scadaAnalog>

<ver:objectName>BR_R-2241</ver:objectName>

<ver:value>0</ver:value>

<ver:quality>Default</ver:quality>

<ver:timeStamp>2010-06-27T14:41:15-05:00</ver:timeStamp>

<ver:measurementTypeID>faultIndicator</ver:measurementTypeID>

</ver:scadaAnalog>

</ver:GetAllSCADAAnalogsResult>

</ver:GetAllSCADAAnalogsResponse>

</soapenv:Body>

</soapenv:Envelope>

GetAllSCADAAnalogs is used for both digital and analog measurements.

InitiateStatusReadByPointID, InitiateAnalogReadByPointID, InitiateTagReadyByPointID

The second synchronization method uses InitiateXXXReadByPointID operations to request latest device statuses, tags, digital and analog measurements from the SCADA. SCADA provides requested information asynchronously by sending XXXChangedNotificationByPointID messages to NMS. To avoid having to send all SCADA points known to NMS an empty list of SCADA points can be used to indicate desire to initiate read for all SCADA points. Operation InitiateTagReadByPointID is not part of MultiSpeak 4.1 specification.

InitiateStatusReadByPointID and InitiateAnalogReadByPointID request examples

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header>

<ns4:MultiSpeakMsgHeader xmlns:ns4="http://www.multispeak.org/Version_4.1_Release"

xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml"

Pwd="test" UserID="nms" />

</S:Header>

<S:Body>

<ns4:InitiateStatusReadByPointID

xmlns:ns4="http://www.multispeak.org/Version_4.1_Release"

xmlns:ns3="cpsm" xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml">

<ns4:pointIDs />

<ns4:responseURL>https://nms-server:7002/nms-amr/oa</ns4:responseURL>

<ns4:transactionID>1300163600187</ns4:transactionID>

<ns4:expTime units="Hours">1.0</ns4:expTime>

</ns4:InitiateStatusReadByPointID>

</S:Body>

</S:Envelope>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header>

<ns4:MultiSpeakMsgHeader xmlns:ns4="http://www.multispeak.org/Version_4.1_Release"

xmlns:ns3="cpsm" xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml"

Pwd="test" UserID="nms" />

</S:Header>

<S:Body>

<ns4:InitiateAnalogReadByPointID

xmlns:ns4="http://www.multispeak.org/Version_4.1_Release" xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns1="gml">

<ns4:pointIDs />

<ns4:responseURL>https://nms-server:7002/nms-amr/oa</ns4:responseURL>

<ns4:transactionID>1300163600203</ns4:transactionID>

<ns4:expTime units="Hours">1.0</ns4:expTime>

</ns4:InitiateAnalogReadByPointID>

</S:Body>

</S:Envelope>

GetAllSCADATags

Synchronization of tag information is done using GetAllSCADATags operation (not part of MultiSpeak 4.1). The expectation is that SCADA systems would return information about all currently applied tags. NMS compares information received from SCADA against tags currently present in the model and make necessary adjustments (adding or removing tags).

GetAllSCADATags request and response example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header>

<ns4:MultiSpeakMsgHeader xmlns:ns4="http://www.multispeak.org/Version_4.1_Release"

xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml"

Pwd="test" UserID="nms" />

</S:Header>

<S:Body>

<ns4:GetAllSCADATags xmlns:ns4="http://www.multispeak.org/Version_4.1_Release"

xmlns:ns3="cpsm"

xmlns:ns2="http://www.w3.org/1999/xlink"

xmlns:ns1="gml">

<ns4:lastReceived></ns4:lastReceived>

</ns4:GetAllSCADATags>

</S:Body>

</S:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release"

xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="scada" Pwd="test" AppName="Scada1"

ObjectsRemaining="0"/>

</soapenv:Header>

<soapenv:Body>

<ver:GetAllSCADATagsResponse>

<ver:GetAllSCADATagsResult>

<ver:scadaTag objectID="scada-tag-1" verb="Change">

<ver:tagType>Hold</ver:tagType>

<ver:scadaPointID>BR2422</ver:scadaPointID>

<ver:username>scada</ver:username>

<ver:comment>test tag</ver:comment>

<ver:timeStamp>2011-07-19T14:12:31.859-05:00</ver:timeStamp>

</ver:scadaTag>

</ver:GetAllSCADATagsResult>

</ver:GetAllSCADATagsResponse>

</soapenv:Body>

</soapenv:Envelope>

Controls

NMS can use the same operation ( InitiateControl) to request device operation and to request placement or removal of a tag. The InitiateControl message consists of a single controlAction object.

The following InitiateControl fields are used:

•

scadaPointID - SCADA point ID;

•

controlKey - SCADA-specific value indicating requested operation (open/close device, place/remove tag);

•

transactionID - unique value associated with the control request;

•

responseURL - URL of NMS web service , which should be used to report outcome of the requested control action.

Notes:

•

Field function is required, but NMS will not use it. Field function will always contain the following value: Direct operate.

•

NMS will not issue separate select and operate commands.

InitiateControl request example

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/

xmlns:ver="http://www.multispeak.org/Version_4.1_Release">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms" Pwd="test" TimeStamp="2011-03-19T20:04:37"/>

</soapenv:Header>

<soapenv:Body>

<ver:InitiateControl>

<ver:controlAction>

<ver:scadaPointID>BR_R-2241</ver:scadaPointID>

<ver:controlKey>open</ver:controlKey>

<ver:function>Direct operate</ver:function>

<ver:relayType>Normal</ver:relayType>

</ver:controlAction>

<ver:responseURL>https://nms-server:7002/nms-amr/oa</ver:responseURL>

<ver:transactionID>12345</ver:transactionID>

</ver:InitiateControl>

</soapenv:Body>

</soapenv:Envelope>

Operating a SCADA-controlled device

1.

NMS user instructs open of a SCADA-controlled device.

2.

Instructed flag is placed on the device in NMS. The device remains closed in NMS model.

3.

NMS sends InitiateControl message to the SCADA system.

4.

If requested control action has been successfully executed then:

a.

SCADA sends SCADAStatusChangedNotification with the new status of the operated device

b.

NMS updates device status in the model and removes Instructed flag

3.

Regardless of the outcome of the requested control action

a.

SCADA sends ControlActionCompleted message to indicate whether requested control action was successful or not

b.

In case of negative outcome NMS removes Instructed flag. Device status remains unchanged.

Note: When SCADA sends ControlActionCompleted message to NMS in case of success NMS will not update device status in its model until SCADAStatusChangedNotification message has been received.

Placing or removing a tag on a SCADA-controlled device

1.

NMS user instructs placement of a HOLD tag on a SCADA-controlled device.

2.

Instructed flag is placed on the device in NMS. The device remains closed in the NMS model.

3.

NMS sends InitiateControl message to the SCADA system.

4.

If requested control action has been successfully executed then:

a.

SCADA sends SCADATagChangedNotification with the new status of the operated device.

b.

NMS updates device status in the model and removes Instructed flag.

3.

If requested control action has NOT been successfully executed then:

a.

SCADA sends ControlActionCompleted message to indicate that requested control action has not been executed.

b.

NMS removes Instructed flag, device status remains unchanged.

Note: SCADA can send ControlActionCompleted message to NMS in case of success, but NMS will not update tag information in its model until SCADATagChangedNotification message has been received.

Outgoing Device Statuses

If SCADA system has knowledge of the NMS electrical model, then the adapter can be configured to send device status information for non-SCADA devices in the NMS model to the SCADA system.

The SCADA system plugin method buildScadaPointId is used to construct SCADA point id for non-SCADA devices.

SCADAStatusChangedNotification

Sends NMS device status changes to SCADA system.

StatusChangedNotificationByPointID

Sends NMS device status information to SCADA system in response to InitiateStatusReadByPointID request. NMS only returns information for devices which are not in the nominal state to reduce volume of data.

Display Integration

HighlightObjectInDisplay

This message causes SCADA system to focus display on a particular SCADA point.

SCADA to NMS

Supported Operations

PingURL

SCADA system can use PingURL operation to verify that NMS is operational.

GetMethods

SCADA system can use GetMethods operation to determine operations supported by NMS.

SCADAAnalogChangedNotification

SCADA system can use this operation to report that analog or digital measurement(s) has changed. The message consists of an array of scadaAnalog objects.

The following scadaAnalog fields should be used (XPath notation is used):

•

@objectID or objectName - SCADA point ID;

•

measurementTypeID - measurement type (used to determine NMS attribute);

•

value - measurement value and units;

•

quality - quality code associated with the measurement;

•

timeStamp - measurement timestamp.

Note: If SCADA point ID uniquely identifies the measurement then the measurementTypeID field can be omitted.

Possible error conditions:

•

Unknown SCADA system;

•

Unknown SCADA point id;

•

Unable to map measurement to NMS attribute;

•

Empty measurement value.

SCADAAnalogChangedNotification Example

•

Sets Amps attribute to 260.78 and turns off faultIndicator for device BR_R-2241.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release" xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms" Pwd="test" AppName="Scada1"/>

</soapenv:Header>

<soapenv:Body>

<ver:SCADAAnalogChangedNotification>

<ver:scadaAnalogs>

<ver:scadaAnalog>

<ver:objectName>BR_R-2241</ver:objectName>

<ver:value units="Amps">260.78</ver:value>

<ver:quality>Measured</ver:quality>

<ver:timeStamp>2010-06-27T14:41:15-05:00</ver:timeStamp>

<ver:measurementTypeID>Amps</ver:measurementTypeID>

</ver:scadaAnalog>

<ver:scadaAnalog>

<ver:objectName>BR_R-2241</ver:objectName>

<ver:value>0</ver:value>

<ver:quality>Measured</ver:quality>

<ver:timeStamp>2010-06-27T14:41:15-05:00</ver:timeStamp>

<ver:measurementTypeID>faultIndicator</ver:measurementTypeID>

</ver:scadaAnalog>

</ver:scadaAnalogs>

</ver:SCADAAnalogChangedNotification>

</soapenv:Body>

</soapenv:Envelope>

SCADAAnalogChangedNotificationByPointID

The SCADA system can use this operation to report that an analog or digital measurement has changed. The message consists of a single scadaAnalog object.

The following scadaAnalog fields should be used:

•

@objectID or objectName - SCADA point ID;

•

measurementTypeID - measurement type (used to determine NMS attribute);

•

value - measurement value and units;

•

quality - quality code associated with the measurement;

•

timeStamp - measurement timestamp.

Possible error conditions:

•

Unknown SCADA system;

•

Unknown SCADA point id;

•

Unable to map measurement to NMS attribute;

•

Empty measurement value.

AnalogChangedNotificationByPointID

This operation is used by SCADA system to respond to the InitiateAnalogReadByPointID request made by NMS.

•

The message format is the same as SCADAAnalogChangedNotification with one additional field 'transactionID'.

•

Its value has to match the value of the ' transactionID' field in the InitiateAnalogReadByPointID message the SCADA system is responding to.

SCADAStatusChangedNotification

The SCADA system will use this operation to report that one or more devices have changed status. The message consists of an array of scadaStatus objects.

The following scadaStatus fields should be used:

•

@objectID or objectName - SCADA point ID;

•

status - SCADA device status (Open/Closed);

•

quality - quality code associated with the status update;

•

changeCounter - number of device status changes since the last report;

•

timeStamp - device operation timestamp.

Possible error conditions:

•

Unknown SCADA system;

•

Unknown SCADA point id;

•

Invalid status value.

SCADAStatusChangedNotification examples

1.

Opens device BR_R-2241

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release" xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms" Pwd="test" AppName="Scada1"/>

</soapenv:Header>

<soapenv:Body>

<ver:SCADAStatusChangedNotification>

<ver:scadaStatuses>

<ver:scadaStatus>

<ver:objectName>BR_R-2241</ver:objectName>

<ver:quality>Measured</ver:quality>

<ver:status>Open</ver:status>

<ver:changeCounter>1</ver:changeCounter>

<ver:timeStamp>2011-03-04T11:44:10</ver:timeStamp>

</ver:scadaStatus>

</ver:scadaStatuses>

</ver:SCADAStatusChangedNotification>

</soapenv:Body>

</soapenv:Envelope>

2.

Closes device BR_R-2241

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release" xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms" Pwd="test" AppName="Scada1"/>

</soapenv:Header>

<soapenv:Body>

<ver:SCADAStatusChangedNotification>

<ver:scadaStatuses>

<ver:scadaStatus>

<ver:objectName>BR_R-2241</ver:objectName>

<ver:quality>Measured</ver:quality>

<ver:status>Closed</ver:status>

<ver:changeCounter>1</ver:changeCounter>

<ver:timeStamp>2011-03-04T11:44:10</ver:timeStamp>

</ver:scadaStatus>

</ver:scadaStatuses>

</ver:SCADAStatusChangedNotification>

</soapenv:Body>

</soapenv:Envelope>

SCADAStatusChangedNotificationByPointID

The SCADA system can use this operation to report that the status of a device has changed. The message consists of a single scadaStatus object.

The following scadaStatus fields should be used:

•

@objectID or objectName - SCADA point ID;

•

status - SCADA device status (Open/Closed);

•

quality - quality code associated with the status update;

•

changeCounter - number of device status changes since the last report;

•

timeStamp - device operation timestamp.

Possible error conditions:

•

Unknown SCADA system;

•

Unknown SCADA point id;

•

Invalid status value.

StatusChangedNotificationByPointID

This operation is used by the SCADA system to respond to the InitiateStatusReadByPointID request made by NMS.

•

Message format is the same as SCADAStatusChangedNotification with one additional field 'transactionID'.

•

Its value has to match value of the ' transactionID' field in the InitiateStatusReadByPointID message the SCADA system is responding to.

SCADATagChangedNotification

The SCADA system can use this operation to report that there has been a change in tag(s) placed on devices in the SCADA system. The message consists of an array of scadaTag objects.

The following scadaTag fields should be used:

•

@objectID - SCADA tag identifier;

•

scadaPointID - SCADA point id;

•

@verb - action (New/Change/Delete);

•

tagType - SCADA tag type;

•

username - SCADA operator's user name;

•

comment - tag comments, notes;

•

timeStamp - tag operation timestamp.

Possible error conditions:

•

Unknown SCADA system;

•

Unknown SCADA point id;

•

Invalid tag type;

•

Unsupported action.

This operation does not exist in MultiSpeak 4.1 specification.

SCADATagChangedNotification examples

1.

Place HOLD tag on device BR2422

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release" xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms" Pwd="test" AppName="Scada1"/>

</soapenv:Header>

<soapenv:Body>

<ver:SCADATagChangedNotification>

<ver:scadaTags>

<ver:scadaTag objectID="scada-tag-1" verb="New">

<ver:tagType>Hold</ver:tagType>

<ver:scadaPointID>BR2422</ver:scadaPointID>

<ver:username>scada</ver:username>

<ver:comment>test tag</ver:comment>

<ver:timeStamp>2011-07-19T14:12:31.859-05:00</ver:timeStamp>

</ver:scadaTag>

</ver:scadaTags>

</ver:SCADATagChangedNotification>

</soapenv:Body>

</soapenv:Envelope>

2.

Update HOLD tag on device BR2422

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release" xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms" Pwd="test" AppName="Scada1"/>

</soapenv:Header>

<soapenv:Body>

<ver:SCADATagChangedNotification>

<ver:scadaTags>

<ver:scadaTag objectID="scada-tag-1" verb="Change">

<ver:tagType>Hold</ver:tagType>

<ver:scadaPointID>BR2422</ver:scadaPointID>

<ver:username>scada2</ver:username>

<ver:comment>updated test tag</ver:comment>

<ver:timeStamp>2011-07-19T14:13:31.859-05:00</ver:timeStamp>

</ver:scadaTag>

</ver:scadaTags>

</ver:SCADATagChangedNotification>

</soapenv:Body>

</soapenv:Envelope>

3.

Remove HOLD tag from device BR2422

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ver="http://www.multispeak.org/Version_4.1_Release" xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms" Pwd="test" AppName="Scada1"/>

</soapenv:Header>

<soapenv:Body>

<ver:SCADATagChangedNotification>

<ver:scadaTags>

<ver:scadaTag objectID="scada-tag-1" verb="Delete">

<ver:tagType>Hold</ver:tagType>

<ver:scadaPointID>BR2422</ver:scadaPointID>

<ver:username>scada</ver:username>

<ver:comment>updated test tag</ver:comment>

<ver:timeStamp>2011-07-19T14:14:31.859-05:00</ver:timeStamp>

</ver:scadaTag>

</ver:scadaTags>

</ver:SCADATagChangedNotification>

</soapenv:Body>

</soapenv:Envelope>

TagChangedNotificationByPointID

This operation is used by the SCADA system to respond to the InitiateTagReadByPointID request made by NMS.

•

The message format is the same as SCADATagChangedNotification with one additional field 'transactionID'.

•

Its value has to match value of the ' transactionID' field in the InitiateTagReadByPointID message SCADA system is responding to.

•

This operation does not exist in MultiSpeak 4.1 specification.

ControlActionCompleted

The SCADA system can use this operation to report to NMS the outcome of a control action requested by the InitiateControl operation. The message consists of a single of scadaControl object. In case of successful control action field, the controlStatus should contain value "Control accepted." Any other value is interpreted as control failure.

ControlActionCompleted example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://www.multispeak.org/Version_4.1_Release">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="scada" Pwd="test" AppName="Scada1"/>

</soapenv:Header>

<soapenv:Body>

<ver:ControlActionCompleted>

<ver:controlAction>

<ver:scadaPointID>BR2422</ver:scadaPointID>

<ver:function>Direct operate</ver:function>

<ver:relayType>Normal</ver:relayType>

<ver:controlStatus>Control accepted</ver:controlStatus>

</ver:controlAction>

<ver:transactionID>12345</ver:transactionID>

</ver:ControlActionCompleted>

</soapenv:Body>

</soapenv:Envelope>

VoltageAlarmNotification

The SCADA system can use this operation to report alarms to NMS. The message consists of an array of voltageA-larm objects.

The following voltageAlarm fields should be used:

•

@objectID - SCADA alarm identifier;

•

sourceIdentifier - SCADA point id;

•

sourceIdentifier/@name - attribute name;

•

@verb - action (only New is allowed);

•

@errorString - alarm description;

•

comments - alarm description;

•

eventTime - SCADA alarm timestamp;

•

voltageAlarmList/voltageAlarmItem[1]/voltageValue - SCADA measurement value, which caused the alarm;

•

voltageAlarmList/voltageAlarmItem[1]/quality - SCADA quality code;

•

voltageAlarmList/voltageAlarmItem[1]/analogCondition - SCADA limit violation;

•

voltageAlarmList/voltageAlarmItem[1]/phaseCode - SCADA alarm phases.

For alarms SCADA quality code is passed "as-is." Configured quality code mapping rules are not applied in this case.

Possible error conditions:

•

Unknown SCADA system;

•

Unknown SCADA point id;

•

Unsupported action.

VoltageAlarmNotification example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://www.multispeak.org/Version_4.1_Release" xmlns:cpsm="cpsm">

<soapenv:Header>

<ver:MultiSpeakMsgHeader UserID="nms1" Pwd="systems" AppName="SoapUI"/>

</soapenv:Header>

<soapenv:Body>

<ver:VoltageAlarmNotification>

<ver:alarms>

<ver:voltageAlarm objectID="alarm-1" verb="New" errorString="alarm test">

<ver:comments>comment</ver:comments>

<ver:sourceIdentifier name="Volts">BR2422</ver:sourceIdentifier>

<ver:eventTime>2011-05-11T10:05:25.484-05:00</ver:eventTime>

<ver:voltageAlarmList>

<ver:voltageAlarmItem>

<ver:voltageValue units="V">100</ver:voltageValue>

<ver:quality>Measured</ver:quality>

<ver:analogCondition>H1</ver:analogCondition>

<ver:phaseCode>BC</ver:phaseCode>

</ver:voltageAlarmItem>

</ver:voltageAlarmList>

</ver:voltageAlarm>

</ver:alarms>

</ver:VoltageAlarmNotification>

</soapenv:Body>

</soapenv:Envelope>

InitiateStatusReadByPointID

Initiates process of sending device status information for non-SCADA devices from NMS to SCADA as series of StatusChangedNotificationByPointID messages.

HighlightObjectInDisplay

Causes NMS viewer to focus on given SCADA point. Viewer window has to be open (this message does not open viewer window).

MultiSpeak Message Header

The attributes UserID and Pwd in the MultiSpeak message header are used for authentication. These attributes should be populated with valid NMS credentials for all messages coming to NMS with exception of PingURL and GetMethods.

The attribute AppName in the MultiSpeak message header must be populated with the name of the SCADA system the message originated from. It is checked against the SCADA systems defined in the SCADA_IDS database table.

Software Configuration

Configuration for the Oracle Utilities Network Management System MultiSpeak Adapter comes from the following sources:

•

CES_PARAMETERS database table;

•

SCADA_IDS database table;

•

SCADA_LINKS database table;

•

SCADA_LINK_OPS database table;

•

SCADA_SYNONYMS database table.

CES_PARAMETERS

Entries in the CES_PARAMETERS database table for the SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter should have the value SCADAInterface in the APP column. Column ATTRIB should contain the name of the configuration parameter and column VALUE its value.

Common Configuration Parameters

The following table describes the common configuration parameters.

Parameter

Description

config.credentials

Absolute path to the file containing user credentials the adapter will use to communicate with Oracle Utilities Network Management System.

This parameter is required.

config.enabled

Enables SCADA processing.

Default: true

config.message_credentials_required

If this parameter is set to false then credentials for authenticating with NMS are taken from the MultiSpeak header of the incoming message.

If this parameter is set to false and credentials are not present in the MultiSpeak header of the incoming message then username and password configured in the adapter is used to authenticate with NMS.

Valid values: true/false. Default value: true

Per SCADA System Configuration Parameters

The following configuration parameters are configured individually for each SCADA system the adapter is communicating with. Names of such parameters are prefixed with the name of the SCADA system they apply to (value from the SCADA_NAME column in the SCADA_IDS table).

Authentication with the SCADA System

The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter passes credentials to the SCADA system in the UserID and Pwd fields of the MultiSpeak message header.

Parameter

Description

<scada name>.headers.UserID

Username to be passed to the SCADA system.

<scada name>.headers.Pwd

Password to be passed to the SCADA system.

Note: Other MultiSpeak message header fields can be set by using desired field name in the parameter name.

JNDI Name for JMS Connection Factory

When JMS transport is used this parameter defines JNDI name of the JMS connection factory used for NMS to SCADA data flows.

Parameter

Description

<scada name>.jms_cf_name

JNDI name of the JMS connection factory which should be used for NMS to SCADA data flows.

Default value: ConnectionFactory

JMS Connection Credentials

These parameters are used if credentials are required to establish connection to JMS server. They are passed to the createConnection method of JMS connection factory.

Parameter

Description

<scada name>.jms_user

JMS connection username.

<scada name>.jms_password

JMS connection password.

SCADA System Plugin Class

Plugin class is a Java class, which encapsulates functionality of the adapter, which is specific to a particular SCADA system.

Parameter

Description

<scada name>.plugin_class

Full name of the Java class implementing ScadaSystemPlugin interface for the SCADA system the adapter is connected to.

Default value: com.splwg.oms.interfaces.scada.plugins.GenericScada

Support for Tags

This parameter allows enable/disable tag-related data flows.

Parameter

Description

<scada name>.support_tags

Enable/disable support for tags.

Default value: false (tags are not supported)

Synchronization Sequence Timeout

This parameter limits how long synchronization sequence can last. If this value is exceeded then link failure is declared.

Parameter

Description

<scada name>.sync_timeout

Maximum allowed duration (in seconds) of synchronization sequence.

Default value: 3600

Automatic Synchronization of Measurements Values

SCADA systems can have large number of analog measurements and synchronizing those can be a lengthy task. This configuration parameter allows analog measurements to be excluded from automated synchronization sequence, which is executed when connection to SCADA system is established.

It is always possible to manually trigger synchronization of analog measurements regardless of the value of this parameter.

Parameter

Description

<scada name>.sync_analogs

Include measurement values into automated synchronization sequence

Default value: true

Adapter Status Alarm Messages

NMS MultiSpeak adapter can generate system alarms to alert NMS operator about following conditions:

•

Adapter has been started

•

Adapter has been stopped

•

Connection to SCADA system has been established

•

Connection to SCADA system has failed

•

Synchronization sequence has finished

Parameter

Description

<scada name>.msg.started

Text of the alarm generated when adapter has been started.

<scada name>.msg.stopped

Text of the alarm generated when adapter has been stopped.

<scada name>.msg.established

Text of the alarm generated when connection to SCADA system has been established.

<scada name>.msg.failed

Text of the alarm generated when connection to SCADA system has failed.

<scada name>.msg.synchronized

Text of the alarm generated when synchronization sequence has finished.

If alarm text is not configured then corresponding alarm will not be generated.

Dynamic SCADA Point Configuration

When SCADA system has knowledge of NMS device aliases or device handles it is possible to have process of SCADA point configuration to be performed by the adapter as part of integrity check. New SCADA points are added to the database tables ANALOG_MEASUREMENTS, DIGITAL_MEASUREMENTS and SCADA_MEASUREMENTS_ST. Orphaned SCADA points can be removed from the SCADA_MEASUREMENTS_ST database table.

No additional actions are required for new SCADA points to take effect (users may have to refresh SCADA Summary to see new points). Command 'UpdateDDS -recacheMeasures' need to be executed to propagate record deletions to runtime tables (ANALOG_MEASUREMENTS and DIGITAL_MEASUREMENTS).

In order for dynamic SCADA point configuration to be possible SCADA system plugin must implement buildScadaPointId and parseScadaPointId methods.

Parameter

Description

<scada name>.dynamic_point_config

Dynamic SCADA point configuration support.

Valid values:

•

full - dynamic addition and removal of SCADA points is supported

•

add - only dynamic addition of SCADA points is supported

•

none - not supported

Default: none.

Sending Device Status Information from NMS to SCADA

The adapter can be configured to send NMS device status information to SCADA system for non-SCADA devices. List of NMS devices classes has to be configured to enable this functionality (<scada name>.outgoing_status.class.<idx> parameter).

Class inheritance is taken into account so if a device class is configured to have status changes to be sent to SCADA system then status changes for all the child classes would also be sent out.

For conductors quality value in the outgoing message is set to Other. In all other cases quality value is not set.

Status information for inline jumpers is reported as status on the underlying conductor.

Point-to-point jumpers are not supported.

Parameter

Description

<scada name>.outgoing_status.class.<idx>

Device classes for which status information should be sent to SCADA system.

<scada name>.outgoing_status.block_size

Block size for outgoing device status messages.

Default: 10

<scada name>.conductor.class.<idx>

NMS conductor device classes.

<scada name>.jumper.class.<idx>

NMS jumper device classes.

<idx> - suffix used to make parameter name unique; any value can be used as long as resulting configuration parameter name is unique.

Synchronization Method

The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter supports two methods of synchronizing device statuses and measurements with the SCADA system: synchronous and asynchronous.

Parameter

Description

<scada name>.preferred_sync_method

Preferred method of synchronization with the SCADA system.

Valid values:

•

sync - synchronous

•

async - asynchronous

Default: async.

<scada name>.need_sync_points

Whether full list of SCADA points known to NMS should be sent to SCADA during synchronization process. Only applicable when preferred_sync_method is async.

Valid values: true/false

Default: false

SOAP Protocol Version

Oracle Utilities Network Management System MultiSpeak Adapter can use SOAP protocol versions 1.1 or 1.2.

Parameter

Description

<scada name>.soap12

Whether SOAP 1.2 should be used.

Valid values: true/false

Default: false (use SOAP 1.1)

Outbound Controls

The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter supports sending control requests to the SCADA system.

Parameter

Description

<scada name>.allow_controls

Whether control requests should be sent to SCADA.

Valid values: true/false

Default: false (controls are not allowed)

Heartbeat Interval

The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter periodically sends PingURL message to the SCADA system to check status of the link. Heartbeat failure causes adapter to switch to alternate link (if available).

Parameter

Description

<scada name>.heartbeat_interval

Interval in seconds between heartbeat messages.

Default: 60 seconds

Support for operating non-SCADA devices in NMS model

If set to 'true' this configuration parameter allows SCADA system to operate devices, which are not SCADA-telemetered, in NMS model. For this to be possible the adapter must be able to derive NMS device handle from SCADA point id. In addition if dynamic point configuration is enabled, then SCADA plugin must implement 'isScadaPoint' method to allow adapter to distinguish between status updates for SCADA and non-SCADA devices.

Parameter

Description

<scada name>.allow_non_scada_ops

Allow SCADA to operate non-SCADA devices in NMS model. Default: false (do not allow SCADA to operate non-SCADA devices)

Own Web Service URL

There are cases when the SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter needs to send an URL of its own web service to the SCADA system. For example, when sending asynchronous request to the SCADA system, it needs to provide a URL where the response should be sent when the results become available.

Parameter

Description

<scada name>.OA.url

URL where the incoming web service of the Oracle Utilities Network Management System MultiSpeak Adapter is deployed.

SCADA_IDS

This database table is used to configure the list of SCADA systems that the adapter will be communicating with. For SCADA systems compatible with this adapter, the column ADAPTER_TYPE should have value MULTISPEAK.

Example

INSERT INTO scada_ids (id, scada_name, adapter_type, active)

VALUES (200, 'SCADA1', 'MULTISPEAK', 'Y');

INSERT INTO scada_ids (id, scada_name, adapter_type, active)

VALUES (201, 'SCADA2', 'MULTISPEAK', 'Y');

SCADA_LINKS

This database table is used to configure communication links to the SCADA systems. It is allowed to configure multiple links to a single SCADA system. If one link fails the adapter will switch to another one in the order determined by the PRIORITY field (only one link is active at any given time). HTTPS and JMS links are supported.

•

For HTTP links, the WS_URL column is used to specify the URL of the SCADA system web service.

•

For JMS links, the columns REQUEST_QUEUE and RESPONSE_QUEUE are used to specify the JNDI names of the JMS queues used to send requests to and receive responses from the SCADA system.

•

The value in the TIMEOUT column controls how long the adapter should wait for a response from the SCADA system (in seconds). This is only applicable to JMS links. The maximum allowed value is 3600 (1 hour).

•

The value in the PERSISTENT column defines the delivery mode for JMS messages. If set to 'Y' then JMS messages are persistent, otherwise they are not persistent. By default messages are not persistent. This is only applicable to JMS links.

Example

INSERT INTO scada_links (id, scada_id, ws_url, timeout, priority, active)

VALUES (1, 200, 'http://scada-server1:8088/SCADA', 30, 1, 'Y');

INSERT INTO scada_links (id, scada_id, ws_url, timeout, priority, active)

VALUES (2, 200, 'http://scada-server2:8088/SCADA', 30, 2, 'Y');

INSERT INTO scada_links (id, scada_id, request_queue, response_queue,

timeout, persistent, priority, active)

VALUES (3, 200, 'queue/ScadaRequest', 'queue/ScadaResponse', 30, 'N', 3, 'Y');

SCADA_LINK_OPS

This table can be used to configure JMS transport differently for individual outgoing web service operations. If an operation does not have a record in the SCADA_LINK_OPS table then values from the parent SCADA_LINKS record are used.

Column LINK_ID is the foreign key into the SCADA_LINKS table.

Column OPERATION is used to specify web service operation name. Supported operation names:

•

PingURL

•

GetMethods

•

InitiateAnalogReadByPointID

•

InitiateStatusReadByPointID

•

InitiateTagReadByPointID

•

InitiateControl

•

GetAllSCADAAnalogs

•

GetAllSCADAStatus

•

GetAllSCADATags

•

SCADAStatusChangedNotification

•

SCADAStatusChangedNotificationByPointID

•

StatusChangedNotificationByPointID

•

HighlightObjectInDisplay

Columns REQUEST_QUEUE and RESPONSE_QUEUE are used to specify JNDI names of JMS queues used to send requests to and receive responses from SCADA system.

Value in the TIMEOUT column controls how long the adapter should wait for response from SCADA system (in seconds). Maximum allowed value is 3600 (1 hour).

Value in the PERSISTENT column defines delivery mode for JMS messages. If set to 'Y' then JMS messages are persistent, otherwise they are not persistent. By default messages are not persistent.

Example

INSERT INTO scada_link_ops (id, link_id, operation, request_queue,

response_queue, timeout, persistent)

VALUES (31, 3, 'PingURL', 'queue/ScadaRequest_PingURL',

'queue/ScadaResponse_PingURL', 30, 'N');

SCADA_SYNONYMS

This database table is used configure mapping of different data elements between SCADA and NMS systems. The SCADA_ID column should always be populated with the id of the SCADA system (value of the ID column in the SCADA_IDS table) the mapping applies to.

Device Status Mapping

By default the adapter maps MultiSpeak device status values 'Open' and 'Closed' to the corresponding device statuses in NMS and ignores all other device status values defined by MultiSpeak 4.1 specification. SCADA_SYNONYMS table allows customization of device status mapping by associating MultiSpeak device status value to a combination of NMS device status and quality code.

The MultiSpeak device status value should be entered into the KEYWORD column. The NMS device status value should be entered into the STATUS_VALUE column. Valid values are 'Open', 'Closed' or NULL.

If this column is NULL, the device status in NMS will not be affected.

The NMS quality code should be entered in the INT_VALUE column. It will be combined with the quality code received in the MultiSpeak message. The PROCESS_TYPE should be 'S'.

The following example maps the 'Travel' device status received from SCADA to quality code 8192 and keeps device status in NMS unchanged.

INSERT INTO scada_synonyms (id, scada_id, keyword, status_value, int_value, process_type)

VALUES (tmp_seq.nextval, 200, 'Travel', null, 262144, 'S');

Attribute Mapping

Attribute mapping is used when SCADA point ID does not uniquely identify both NMS device and attribute. SCADA attribute name/key should be entered into the KEYWORD column. NMS attribute key should be entered into the INT_VALUE column. PROCESS_TYPE should be 'D' for digital measurements and 'A' for analogs.

Example

INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type)

VALUES (1, 200, 'faultIndicator', 23, 'D');

INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type)

VALUES (2, 200, 'Amps', 1012, 'A');

An additional method for configuring mapping for digital measurements is available. It applies specifically to the case when digital measurement is submitted to NMS via SCADAStatusChangedNotification, SCADAStatusChangedNotificationByPointID or StatusChangedNotificationByPointID operation. This is only possible when SCADA point id uniquely identifies digital measurement in NMS.

SCADA attribute name/key should be entered into the KEYWORD column.

NMS attribute name should be entered into ATTRIBUTE_ALIAS column.

Status value received from SCADA should be entered into STATUS_VALUE column.

Corresponding NMS attribute value should be entered into INT_VALUE column.

PROCESS_TYPE should be 'D'.

Column VALUE is not used.

Example configuration for AutoReclose digital attribute. Receiving status 'Open' from SCADA would set AutoReclose attribute for a device to 1. Receiving status 'Closed' from SCADA would set AutoReclose attribute for a device to 0.

INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type,

attribute_alias, status_value, value)

VALUES (247, 200, 'AutoReclose', 1, 'D', 'AutoReclose', 'Open', 'On');

INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type,

attribute_alias, status_value, value)

VALUES (248, 200, 'AutoReclose', 0, 'D', 'AutoReclose', 'Closed', 'Off');

Quality Code Mapping

The SCADA quality value should be entered into the KEYWORD column. The MultiSpeak 4.1 specification defines the following quality values: Measured, Default, Estimated, Calculated, Initial, Last, and Failed.

The NMS quality code should be entered into the INT_VALUE column (lower 11 bits are reserved for NMS-specific quality codes).

The PROCESS_TYPE should be 'Q'.

Example

INSERT INTO scada_synonyms (id, scada_id, keyword, int_value, process_type)

VALUES (3, 200, 'Measured', 4096, 'Q');

Tag Type Mapping

The SCADA tag type should be entered into the KEYWORD column.

The NMS condition class name should be entered into VALUE column.

The PROCESS_TYPE should be 'C'.

Example

INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)

VALUES (11, 200, 'Hold', 'hold', 'C');

INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)

VALUES (12, 200, 'Tag', 'tag', 'C');

INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)

VALUES (13, 200, 'Clear', 'clear', 'C');

DDService Configuration for Outbound Controls

The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter periodically polls the database table EXPECTED_ACTIONS for pending SCADA controls.

DDService only write records into this table when it is running with the ' -sendAsyncSCADA' command-line option.

SCADA Point Configuration

The SCADA component of the Oracle Utilities Network Management System MultiSpeak Adapter loads SCADA point configuration from the ANALOG_MEASUREMENTS and DIGITAL_MEASUREMENTS database tables. It normally happens during initialization. The adapter can be forced to reload the SCADA point configuration during runtime using the following command:

Action -add_soap multispeak.SCADA reload

The synchronization sequence will be automatically started after the SCADA point configuration is reloaded.

Plugin Support

SCADA vendors may interpret MultiSpeak specification differently or use extensions, which are unique to each vendor. To address the issue of possible differences between various SCADA components, the NMS MultiSpeak adapter has a plugin interface.

Plugin is a Java class, which encapsulates functionality specific to a particular SCADA system. Plugin class must implement the interface com.splwg.oms.interfaces.scada.ScadaSystemPlugin.

Default implementation of the SCADA system plugin is provided by the com.splwg.oms.interfaces.scada.plugins.GenericScada class.

Methods

The available plugin methods, including description of how the default plugin class implements each method, are:

getScadaPointId

java.lang.String getScadaPointId(MspObject obj)

This method is used to extract SCADA Point ID from the incoming MultiSpeak message.

Parameters:

obj - MultiSpeak object

Returns:

SCADA Point ID

Default implementation:

Returns value of the objectID attribute if not empty, otherwise value of the objectName element

getScadaPointId

java.lang.String getScadaPointId(ScadaTag tag)

This method is used to extract SCADA Point ID from the incoming tag-related MultiSpeak message.

Parameters:

tag - ScadaTag object

Returns:

SCADA Point ID

Default implementation:

Returns value of the scadaPointID element

getStatus

StatusIdentifiers getStatus(final ScadaStatus status);

This method is used to extract device status value from the MultiSpeak device status update message.

Parameters:

status - ScadaStatus object

Returns:

MultiSpeak device status value

Default implementation:

Returns value of the status element.

getQualityCodes

java.util.List<java.lang.String> getQualityCodes(ScadaStatus status)

This method is used to extract quality values from MultiSpeak status update message.

Parameters:

status - ScadaStatus object

Returns:

list of MultiSpeak quality values

Default implementation:

Returns value of the quality element

getQualityCodes

java.util.List<java.lang.String> getQualityCodes(ScadaAnalog analog)

This method is used to extract quality values from MultiSpeak analog update message.

Parameters:

analog - ScadaAnalog object

Returns:

list of MultiSpeak quality values

Default implementation:

Returns value of the quality element

processChangeCounter

int processChangeCounter(StatusPoint point, int changeCounter)

This method is used to process SCADA change counter value.

Parameters:

point - SCADA status point

changeCounter - new change counter value for the SCADA status point

Returns:

Number of device operations, which occurred since the last processed update

Default implementation:

Assumes that change counter value received from SCADA is cumulative (total number of times device has changed state since some point in the past). Number of device operations is calculated as the difference between previous and current SCADA change counter values

getTagId

java.lang.String getTagId(ScadaTag tag)

This method is used to extract value from the tag update message, which is then used to populate external id of the corresponding condition in NMS. This value has to uniquely identify the tag in NMS.

Parameters:

tag - ScadaTag object

Returns:

SCADA tag id

Default implementation:

Returns value of the objectID attribute

setTagId

void setTagId(ScadaTag tag, java.lang.String tagId)

This method is used during synchronization process to set tag id value in the tag update message, which is later extracted by the getTagId method.

Parameters:

tag - ScadaTag object to be updated

tagId - SCADA tag id

Default implementation:

Sets value of objectID attribute

getTagType

java.lang.String getTagType(ScadaTag tag)

This method is used to extract SCADA tag type from tag update message. This value is then used to determine corresponding NMS condition class.

Parameters :

tag - ScadaTag object

Returns:

SCADA tag type

Default implementation:

Returns value of the tagType element

getTagData

java.util.Map<java.lang.String,java.lang.Object> getTagData(ScadaTag tag)

This method is used to extract additional tag data fields from tag message.

Parameters:

tag - ScadaTag object

Returns:

Map <tag field name -> tag field value>

Default implementation:

Returns map with a single entry ('text', value of the tagReason element)

getUserName

java.lang.String getUserName(ScadaTag tag)

Extracts operator username from tag update message.

Parameters:

tag - ScadaTag object

Returns:

SCADA operator username

Default implementation:

Returns value of the userName element

getAction

Action getAction(ScadaTag tag)

This method is used to extract action from tag update message. Action determines if the request is to place a new tag, update an existing tag or remove an existing tag.

Parameters:

tag - ScadaTag object

Returns:

action

•

NEW - add new tag

•

CHANGE - update an existing tag

•

DELETE - delete an existing tag

Default implementation:

Returns value of the verb attribute

setAction

void setAction(ScadaTag tag, Action action)

This method is used during synchronization process to set action value in the tag update message, which is later extracted by the getAction method.

Parameters:

tag - ScadaTag object to be updated

action - action

•

NEW - add new tag

•

CHANGE - update an existing tag

•

DELETE - delete an existing tag

Default implementation:

Sets value of the verb attribute

buildScadaPointId

java.lang.String buildScadaPointId(com.splwg.oms.common.intersys.Handle nmsDeviceHandle, java.lang.String nmsDeviceAlias, int phase)

throws java.lang.IllegalArgumentException

This method is used to construct SCADA point id for status of an NMS device.

Parameters:

nmsDeviceHandle - NMS device handle

nmsDeviceAlias - NMS device alias

phase - phase

Returns:

SCADA point id or null if not supported

Throws:

java.lang.IllegalArgumentException - SCADA point id cannot be constructed for the given arguments

Default implementation:

Returns null

parseScadaPointId

ParsedSCADAPointId parseScadaPointId(java.lang.String scadaPointId)

throws java.lang.IllegalArgumentException

Parse SCADA point id.

Parameters:

scadaPointId - SCADA point id

Returns:

ParsedSCADAPountId object

Throws:

java.lang.IllegalArgumentException - if scadaPointId cannot be parsed

Default implementation:

Populates NMS device id in ParsedSCADAPointId with scadaPointId argument.

generateControl

ScadaControl generateControl(ExpectedAction action)

This method is used to create ScadaControl object based on information from the EXPECTED_ACTIONS table.

Parameters:

action - row from EXPECTED_ACTIONS table

Returns:

ScadaControl object or null is controls are not supported

Default implementation:

Returns null

isScadaPoint

boolean isScadaPoint(final MspObject obj)

This method is used to determine if obj is a SCADA-telemetered point. Currently this method gets invoked only for status points.

Parameters:

obj - MultiSpeak object

Returns:

true if obj is a SCADA-telemetered point, otherwise false

Default implementation:

Returns true

Building Custom SCADA Plugins

Prerequisites

•

NMS is installed.

•

nms-install-config --java script has been executed and nms-multispeak.ear file exists in the $NMS_HOME/java/deploy directory.

Steps

1.

Unpack $CES_HOME/sdk/java/samples/nms-multispeak-plugins.zip archive into desired location (this location will be referred as PLUGIN_HOME). It includes Java project directory structure including example of plugin class and Ant build files.

2.

Create Java class implementing com.splwg.oms.interfaces.scada.ScadaSystemPlugin interface and place it into desired location under PLUGIN_HOME/NmsScadaPlugin/src directory.

3.

Execute following command to compile plugin class(s), build jar file and incorporate the jar file into the nms-multispeak.ear file.

ant -Dplatforms.JDK_1.6.home=<JDK home> clean update-ear

where

<JDK home> is the location where Java Development Kit 1.6 is installed

4.

Update configuration for the Oracle Utilities NMS MultiSpeak Adapter to use new plugin class (configuration property '<scada name>.plugin_class').

5.

Updated nms-multispeak.ear file can now be deployed into WebLogic server.

High-Level Messages

SCADA component of the NMS MultiSpeak adapter responds to several high-level messages. High-level message can be sent using Action command-line utility.

Action -add_soap multispeak.SCADA <message>

Following messages are supported:

•

RELOADForces adapter to reload configuration for the SCADA component.

•

RESYNC [statuses|analogs|tags] [<scada id>|<scada name>]Initiates synchronization sequence.If 'statuses', 'analogs' or 'tags' qualifier is present in the message then synchronization sequence is executed only for that particular data flow. Otherwise full synchronization sequence is executed.

If <scada id> or <scada name> is specified then synchronization sequence is executed only for the designated SCADA system. Otherwise synchronization sequence is executed for all SCADA systems the adapter is connected to.

•

FOCUS <user> <device> [<display>] [<action>]Causes HighlightObjectInDisplay message to be sent to the SCADA system(s). This message is used for display integration between NMS and SCADA system. For example, NMS operator can select a SCADA device in NMS viewer and trigger action, which would cause the same device to be selected/highlighted on SCADA system's display.Parameters:

•

<user> - username of SCADA operator

•

<device> - NMS device handle

•

<display> - SCADA display

•

<action> - action to perform

Symbols

AVLInterface.properties 10-7

callbackFeederTimeout 1-27

defaultCallbackAgent 1-27

IccpAdapter.prm 9-4

MDS_ RELATION_FIELD 6-46

SRS Rules Configuration 1-24

A

Aggregation 6-13

Alternate Names 6-25

amqscnxc 5-11

amqsgetc 5-11 , 5-12

amqsputc 5-11

AMR Business Processes 10-11

AMR_CU_METERS 10-17

AMR_REQUEST_RESP 10-18

AMR_REQUESTS 10-15

AMR_RESPONSES 10-16

AMRInterface.properties 10-4

ANALOG_MEASUREMENTS 8-21

B

Base Path 6-36

Batch Mode 4-20

C

Callback Requests 1-5

Callback Responses 1-6

callbackInterfaceEnabled 1-25

Callbacks application data flows 1-2

CES_GET 5-34

CES_PUT 5-34

Change Detection 6-26

Code Mapping Tables 6-81

Code Mapping Tables 6-46

Configuration Documents 6-37

Controls Table 9-13

Crew Message Tags 5-31

Crew Outage Status Changes 5-17

crewActive 6-78

Customer Message Tags 5-28

Customer Outage History 5-15

customerPhoneParentheses 1-26

D

Data Flows 5-14

data flows 1-2

Database Table Schema 1-30

Defaults Table 4-9

DIGITAL_MEASUREMENTS 8-22

DML Examples 6-50

DML Files 6-16

DML Function Calls 6-70

DML Reference 6-56

E

ESRI ArcGIS 9.x Adapter 3-1

Event Object Fields 6-129

ExcludeComponent Table 4-15

ExcludeFeature Table 4-14

External Objects 6-28

F

Flags 6-24

Functions 6-71

clearIncidents 6-95

completeEvent 6-98

confirmDeviceOutage 6-101

confirmServiceOutage 6-102

createPseudoRelation 6-106

createPseudoRelationFromConfirmServiceOutage 6-107

Crew Functions 6-71

crew functions

activateCrew 6-77

arriveCrew 6-75

assignCrew 6-76

availableCrew 6-77

createCrew 6-71

crewActive 6-78

crewOnShift 6-79

dispatchCrew 6-74

findCrewByExternalKey 6-72

findCrewByExtKeySubStr 6-73

findCrewById 6-72

findCrewByIdSubStr 6-73

releaseCrews 6-78

setCrewOnShift 6-79

setVehicleId 6-80

unassignCrew 6-76

updateCrew 6-73

damageSetAddress 6-85

damageSetComment1 6-91

damageSetCrewId 6-84

damageSetFeederName 6-85

damageSetGrid 6-88

damageSetLoadAffected 6-90

damageSetLocation 6-89

damageSetNcg 6-85

damageSetOption1 6-91

damageSetPhase 6-89

damageSetReportTime 6-84

damageSetSection 6-88

damageSetText1 6-90

damageSetText2 6-92

damageSetTransformer 6-87

damageSetType 6-92

damageSetZoneName 6-87

ert 6-99

Event Manipulation 6-95

eventIsActive 6-101

findOrCreateDamage 6-83

findRelation 6-105

getCaseNotesForEvent 6-97

lockForEventCreation 6-103

logDebug 6-94

logFatalError 6-94

Logging Functions 6-93

logLocalError 6-93

picklistCompLog 6-104

picklistInfoUpdTr 6-105

readGenericField 6-99

readIncidents 6-95

Relation Functions 6-105

requestRowAction 6-100

requestRowActionAll 6-100

restoreOutage 6-103

saveDamageDetails 6-93

setCaseNoteInfo 6-96

setEventInfo 6-97

setGenericField 6-98

G

G/Electric Adapte 4-1

Generic IVR Adapter 1-1

Generic SCADA Adapter 8-1

Generic WebSphere MQ Adapter 5-1

Generic WebSphere MQ Mobile Adapter 6-1

Geometric Information 4-4

GIS Data Requirements 4-24

H

High Level Messages 9-9 , 9-21

High Priority Category Table 6-48

I

ICCP Adapter 9-1

Incident Object Fields 6-133

Incidents table 1-23

Information Model 5-20

Input Documents 6-13

Input Element Arrays 6-29

Intergraph G/Electric Adapter 4-1

IVR Adapter 1-1

IVR Adapter Installation 1-7

IVR data flows 1-2

IVRAdapter command line options 1-9

L

Listener 6-9

listener 5-10

loadMapConfigTable 6-81

loadMapTable 6-82

M

mapTableCode 6-83

mapTableStr 6-82

MDS_ORDER 6-41

MDS_ORDER_FIELD 6-42

MDS_RELATION 6-45

MDS_RELATION_EVENT 6-46

Message Tags 5-28

MQ Client 5-10

MultiSpeak Adapter 10-1

N

NMSDeviceID 9-11 , 9-22

O

Oracle WebLogic Server 10-2

Order Tables 6-41

Outage Detection 10-11

Outage Status 5-15

Output Documents 6-12

Output Documents 6-12

P

Partition_Reference Table 4-11

PartitionGroupFeature Table 4-15

PDO Verification 10-12

Permanent Order Object Fields 6-135

Permanent Relationship Object Fields 6-135

pk_ccb.trouble_code_config 1-53

pr_customer_event_details 1-60

pr_trouble_callback_requests 1-57

pr_trouble_callback_responses 1-58

pr_trouble_calls 1-54

Pseudo Relationships 6-41

PSO Verification 10-11

Q

Q manager listener 5-10

Quality Codes 9-8 , 9-20

Quality Rules Table 9-11 , 9-23

Queue Manager Listener Service 6-9

Queue Manager 6-8

Queue Specification 6-31

Queues 5-32

R

RDBMS configuration 8-4

Restoration Verification 10-13

Root Element 6-35

RS Message Type Table 6-47

RTI_STATUS 8-15

RTI_SYN Database 8-14

Run Time Errors 6-49

S

SCADA Adapter 8-1

SCADA Adapter Data Flows 8-10

SCADA Measurement Entry 8-11

SCADA_ID Database 8-14

Server Connection Channel 6-9

SmallWorld GIS Adapter 2-1

Spatial (Landbase) Partition List 4-14

SQL Query 5-16

SQL Transactions 5-16

SRS Output 5-21

Stop Statement 6-37

Stored Procedure Parameters 1-42

streetXsectionOffset 1-28

Synchronization Process 5-12

T

Triggers 6-32

Trouble Call Mapping Configuration 1-16

Trouble Call Message Tags 5-28

Trouble Call Performance 1-29

Trouble Calls 1-3

TROUBLE_CALLBACKS 1-37

TROUBLE_CALLS Table Schema 1-30

troubleCallCreate 1-13

U

useExternalCause 1-26

V

V_SPL_FIDFNO View 4-16

W

WebSphere MQ Adapter 5-1

WebSphere MQ Mobile Adapter 6-1

WebSphere MQ Server 5-9

Index