Oracle Utilities Network Management System

Adapters Guide

Release 1.12.0.2.0

E61791-01

April 2015

Oracle Utilities Network Management System Adapters Guide, Release 1.12.0.2.0

E61791-01

Copyright © 1991, 2015 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 is software or related documentation that 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 END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

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

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware 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 administrators and 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.

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

This chapter is an administration guide for the Oracle Utilities Network Management System Generic Interactive Voice Response (IVR) System Adapter. This chapter describes the processes required to install and configure the adapter to run with various IVR 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. 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 JMService.

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 Template

The Oracle Smallworld data adapter template is a Smallworld Magik code template for an extraction tool to produce .mp files from the Smallworld GIS. This unsupported template is provided as an example for projects to use to facilitate the extraction from the Smallworld GIS to the Oracle Utilities Network Management System (NMS). It is located on the installed Oracle Utilities Network Management System in the $CES_HOME/sdk/gis directory as file SW_EXTRACTOR_TEMPLATE.zip.

ESRI ArcGIS Adapter

Adapter Overview

Oracle Network Management System has adapters for various ESRI ArcGIS systems. Please refer to http://support.oracle.com and search the Oracle Support Knowledge Base for "NMS ESRI Extractor" for information on supported versions of the adapter and download links.

Adapter Documentation

Oracle Utilities Network Management System ArcGIS adapter documentation is included in the ArcGIS adapter release package.

Intergraph G/Electric Adapter

Adapter Overview

Oracle Utilities Network Management System has adapters for various Intergraph G/Electric systems. Please refer to http://support.oracle.com and search the Oracle Support Knowledge Base for "NMS Intergraph Extractor" for information on supported versions of the adapter and download links.

Adapter Documentation

Oracle Utilities Network Management System Intergraph G/Electric adapter documentation is included in the Intergraph G/Electric adapter release package.

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 JMService 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);

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

•

DataRaker Integration

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 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. It is assumed that the 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/or 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

-service rt -process_name RTDBService

SRS_RULES Configuration for Generic SCADA Adapter

The RT_PLANNED_OUTAGE_QUALITY rule controls which outages are planned. To trigger this rule the srs_rules.rule_value_2 must be set to non-zero positive integer less than 2^32. If properly set and if/when an external device change request comes in with a quality code that matches a bitwise mask with this value, then RTAdapter will attempt to create a planned outage (for an open request). If rule_value_2 is set to a value above 2^10 (1024) then it is possible to also set a project specific quality code for this action (at the same time). If rule_value_2 is below 2^11 (2048), the planned outage will still be created but no quality code will be set (because qualities of 2^10 and below are all internal NMS quality codes).

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 data 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, but can be used to send outbound controls (digital or analog) to an external SCADA as well.

-offline

For testing purposes - when a control request is received - simulate the external SCADA system and operate the device.

-offlineDelay <seconds>

Seconds between receiving a CONTROL request (in offline mode) and responding. Used to help simulate an actual SCADA system.

-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 processing cycles. (Required)

-scada <scada>

SCADA source name. (Required). Must match an active SCADA entry in the scada_ids table (scada_ids.scada_name).

-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/or 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 used for incoming SCADA data (analog_measurements and digital_measurements).

Adapter Configuration

RDBMS configuration:

Tables involved:

•

digital_measurements : standard SCADA runtime 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_analog_in is entirely optional but is generally used in conjunction with scada_digital_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 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 - capture "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 scadapop, 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 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).

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 supporting 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 - project specific.

scada_namescada_points column to populate with Rtu_Desc value.

3 Data type of string (ASCII field) always 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 and (optionally) the scada_controls table..

Run scadapop -h to get command line options. In general:

•

scadapop [-debug [n]] -partition <n> -initFile <file> -nonUniq -scada -attrName

•

debug <n> - Turns debug on <to level n>

•

partition <n> - Populate partition n (0 = all partitions)

•

initFile <file> - rti.dat configuration file (see below)

•

-nonUniq - Do not generate unique rti_alias values.

•

-scada <scada> - Specific SCADA to process (scada_ids.scada_name).

•

-attrName - Append NMS attribute name (rather than number) to make rti_alias unique.

•

-controls - Populate scada_controls table for common attribute=0 entries.

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 and (optionally) the scada_controls 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.

By default scadapop will append a dash "-" followed by the NMS attribute number to each rti_alias - other than for attribute=0 (status). The -attrName option will similarly append the dash and NMS attribute name to each rti_alias - except where attribute=0.

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

To populate the scada_measurements_st for all partitions for the SCADA named RTAdapter in scada_ids.scada_name.

scadapop -partition 3111 -initFile rti.dat -debug -scada mySCADA

To populate the scada_measurements_st for partitions 3111 plus debug for scada named mySCADA..

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 SCADA 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 ces_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)

•

creates scada_controls table

3.

The OPAL_scada.sql file contains sample population data for the scada_ids, scada_points, scada_synonyms and scada_controls table for the OPAL model. You must modify and rename this file for your project. The example below is for the OPAL model using file based updates (not RDBMS polling).

ISQL.ces OPAL_scada.sql

4.

Run "scadapop -partition 0 -initFile $CES_DATA_FILES/OPAL_rti.dat -scada RTAdapter"

•

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 1 is topological status (opened/closed) and thus the status attribute for BR2414 would be populated (by scadapop) as BR2414-1 - unless the -nonUniq option is used (or BR2414-Auto if -attrName option is used) - in which case the combination of rti_alias and attribute must be unique. It is generally desirable to make the rti_alias values unique (by appending the attribute number - which happens by default) or by using the -attrName option which appends the NMS attribute name to each rti_alias. By using unique rti_alias values it eliminates the necessity of the external SCADA system understanding (and supplying) NMS attribute names/numbers for input. 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', /* 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;

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->11 are reserved for Oracle Utilities Network Management System purposes. Bits 12->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

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. 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, the "system" (NMS Admin user name), or the name of the SCADA system that sent the update.

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 remove 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 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 and condition status (NOTE, TAG_RED, TAG_BLUE, 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, 0, 1).

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 be provided for each record in the scada_digital_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 0(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.

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

S = Success

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.

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

DataRaker Integration

The NMS RTAdapter can be configured to support integration with the Oracle DataRaker application. DataRaker captures large quantities of periodic Automated Meter Information (AMI) data - typically once a day. AMI data typically includes usage information like meter load (kwH) and voltage for each interval - where intervals are typically hourly or every 15 minutes. By analyzing months (or more) of AMI usage data, DataRaker can detect a broad range of usage anomalies. A few examples include transformer overloads (by aggregating loads from all meters below the load transformer), voltage sags, voltage swells, and abnormal usage patterns.

If DataRaker analysis is routinely executed (for example, daily to pick up yesterday’s AMI data), it can be beneficial to make at least a subset of the DataRaker discovered anomalies clearly visible to NMS operators. RTAdapter can be configured to "import" a set of DataRaker discovered anomalies as NMS conditions (symbols that show in the NMS Viewer or simply records in the NMS Condition Summary tool). These DataRaker anomalies are captured as NMS conditions in the data_raker RDBMS table via the RTAdapter. Once captured, these NMS conditions allow navigation back into DataRaker from NMS.

DataRaker provides raw data files (in DataRaker export file format) that must be mapped/translated to the RTAdapter formats noted below. Typically DataRaker would generate raw DataRaker export files containing the desired data on a relatively routine (daily or weekly) basis. The raw DataRaker files must be transformed (via project specific adapters) into the specified RTAdapter format files for subsequent consumption. A project specific adapter (likely a perl or python script) must be used to translate the DataRaker export format file into the RTAdapter import format data file. This allows a project to determine what DataRaker data they want to include/exclude and how they want to categorize the input data for their NMS operators.

The following three use cases describe how the DataRaker to NMS data integration can be managed by a project using the RTAdapter. The first use case is expected to be the most common - the others are options for NMS administrators to consider as necessary.

Use Cases

Use Case 1 - DataRaker Master (Minimal NMS Involvement)

For this use case, DataRaker is the master of all DataRaker discovered anomalies. This means the anomalies generated by a new DataRaker analysis execution completely replace whatever DataRaker anomalies (NMS conditions) that were previously reported to (or captured by) NMS. This has the advantage of not requiring any periodic updates from NMS operators. NMS operators can view the DataRaker conditions if they choose, act on them if they have time, etc., but they can also ignore the DataRaker conditions and be confident they will not accumulate in NMS over time.

To accomplish this, RTAdapter must be configured to scan files (not the RDBMS) for this instance of the adapter. Below is an example RTAdapter record from the system.dat file that could be applicable for this case:

program DataRaker RTAdapter -scada dataraker -interval 60 -dir ~/dataraker

This means this RTAdapter instance will be known as DataRaker internal to NMS (on the message bus) and will look for configuration records that match scada_ids.id where scada_ids.scada_name=‘dataraker’ in the scada_ids RDBMS table. This id will then need to be matched by appropriate configuration in the scada_synonyms and scada_states tables for this DataRaker instance of the RTAdapter. Note there is no required scada_states table configuration so it will not be further discussed in this section.

Example configuration for the RTAdapter configuration tables is shown below:

•

Records in the RTAdapter SCADA_SYNONYMS configuration table for DataRaker configuration are for where scada_ids.id=100 where scada_ids.scada_name=’dataraker’ (to match example system.dat configuration noted above).

•

The scada_synonyms table configuration records noted below will allow the RTAdapter to process add, rem(ove) and syn(chronize) directive records from an RTAdapter input file for a single type of DataRaker condition (where NMS data_raker condition status=10). See the example OPAL_scada.sql file for more examples of DataRaker conditions. By default the NMS OPAL model is configured to handle 3 different DataRaker condition class statuses (Info=10, Warn=20, Alarm=30). To utilize OPAL type configuration the DataRaker Info, Warn and Alarm conditions must have the specified condition status values of 10, 20 and 30 respectively. These values are somewhat arbitrary and can be changed if necessary - but will require more project specific configuration. Entries for "DR_E2" are similar - just change status_value=‘20’. Entries for "DR_E3" are also similar - just change status_value=‘30’.

INSERT into scada_synonyms (id, scada_id, keyword, value, process_type, attribute_alias, status_value)

VALUES (tmp_seq.nextval, 100, 'DR_E1', 'add', 'C',

'data_raker', '10');

INSERT into scada_synonyms (id, scada_id, keyword, value, process_type, attribute_alias, status_value)

VALUES (tmp_seq.nextval, 100, 'DR_E1', 'rem', 'C',

'data_raker', '10');

INSERT into scada_synonyms (id, scada_id, keyword, value, process_type, attribute_alias, status_value)

VALUES (tmp_seq.nextval, 100, 'DR_E1', 'syn', 'C',

'data_raker', '10');

Technically only the "syn" entry above is required for the first use case option (use RTAdapter to periodically synchronize DataRaker conditions). The "add" and "rem" options are configured just in case a project wants RTAdapter to also process individual add/rem directives in the RTAdapter input file. They are not required, but are used for Use Case 2 and Use Case 3.

Below is an example (translated) DataRaker export file suitable for RTAdapter consumption. You can give the file any valid file name, but it must ultimately be placed in the directory specified via "RTAdapter -dir <directory>" before it will be processed. The RTAdapter data files in the specified directory are processed in a first in, first out basis. The "OBJECT" keyword specifies an NMS object that must match an RTAdapter configured rti_alias (from scada_measurements_st.rti_alias) or an alias entry in the alias_mapping table where db_type=‘OPS’ (default alias).

Any data_raker records in NMS that are NOT found in a RTAdapter synchronization input file will be deleted (based on the value of the external id provided by the EXT= keyword). NMS should only be left with conditions that are specified in the RTAdapter synchronization file when processing is completed. The pipe symbol "|" is a delimiter and can be changed via the "RTAdapter -delimter <n>" command line option. Replace "|" with your project specified delimiter in the examples below, if necessary:

SYNCHRONIZE|TRUE

TYPE|data_raker

DATA

OBJECT|xfmr_1

DR_E1|syn|WHO=dataraker|TIM=2009-02-27T16:22:17|TXT=Over voltage detected|EXT=DR_E1-1

DR_E1|syn|WHO=dataraker|TIM=2009-02-27T17:22:17|TXT=Xfmr within 50% of capacity|EXT=DR_E1-2

DR_E2|syn|WHO=dataraker|TIM=2009-02-27T18:22:17|TXT=Xfmr within 75% of capacity |EXT=DR_E2-1

OBJECT|xmfr_2

DR_E3|syn|WHO=dataraker|TIM=2009-02-27T16:22:17|TXT=Xfmr within 100% of capacity|EXT=DR_E3-1

DR_E3|syn|WHO=dataraker|TIM=2009-02-27T19:22:17|TXT=Xfmr 120% of capacity|EXT=DR_E3-2

END_DATA

Detailed field descriptions of RTAdapter keywords:

•

SYNCHRONIZE|TRUE is a keyword sequence that says this entire file is a synchronization file. Always specify exactly as noted for a synchronization file request. Must start in column 1.

•

TYPE is a keyword that specifies what condition class the synchronization will focus on for all subsequent entries (data_raker in the above example). All entries in a given RTAdapter synchronization file must be of the same class. Must start in column 1.

•

OBJECT is a keyword that precedes the common object id between NMS and DataRaker - as this is the link between the two systems. Normally this is a transformer alias.

•

Project configured keywords - defined in scada_synonyms table ( SCADA_SYNONYMS Database Table ):

•

DR_E1 indicates we are dealing with a DataRaker "Info condition".

•

DR_E2 indicates we are dealing with a DataRaker "Warn condition".

•

DR_E3 indicates we are dealing with a DataRaker "Alarm condition".

•

syn is a directive keyword that indicates we want to make sure this condition exists in NMS. It will update an existing condition or (if there is no current matching condition based on the EXT id) it will insert a new one.

•

WHO= is a keyword that indicates what external system to indicate as the source of the condition directive. Normally this would be "dataraker" (or similar) for DataRaker integration.

•

TIM= is a keyword that specifies a timestamp to go with the directive. Generally from the external system and must be specified in ISO format (the format you see above YYYY-MM-DDTHH:MM:SS - where hours are 00->24 and local time zone is assumed).

•

TXT= is a keyword that specifies a brief summation of the condition detected. Can be up to 512 characters, but less is generally more. Suggest this be just enough to convey the type of issue detected - at least on first 30 characters of the text or so.

•

EXT= is a keyword that specifies the unique external id for this condition. This should be the primary key for this condition. It could be generated by DataRaker or it could be generated by the NMS translation process. Ultimately it should be unique for at least every transformer and data_raker condition status combination in play (project specific).

Notes on the NMS unique key (EXT=) field. If DataRaker reports an anomaly for NMS transformer "xfmr_1" that maps to an NMS data_raker alarm (status=10) today - we could set the EXT= value to "xfmr_1-10" - indicating there is a data_raker alarm (status=10) on xfmr_1. This way if tomorrow DataRaker reports the same (or essentially the same) condition we would again translate to "xfmr_1-10" - and nothing would change on the NMS side for this condition. This scheme minimizes processing in NMS and allows "old" NMS data_raker conditions to "age" within NMS. This should provide some indication of how long DataRaker has been reporting similar issues for this transformer, which may be useful to NMS operators. Otherwise the conditions will be reported as new every day.

Use Case 2 - DataRaker Only Inputs New Conditions - NMS Deletes

Use Case 2 can use the same configuration as Use Case 1 other than the format of the input file to RTAdapter. Here DataRaker only inputs new conditions into NMS and NMS operators have the option to view/add/delete DataRaker conditions as necessary. If/when subsequent DataRaker input is processed, it will be captured "in addition to" whatever DataRaker conditions were already present within NMS. Ideally, for this use case, NMS operators would delete all (old) DataRaker conditions before processing a new batch of DataRaker conditions. If the operators do not delete the old DataRaker conditions they will tend to accumulate.

This option may be useful if it becomes necessary to leave some DataRaker conditions on the system for a substantial period of time before they are acted on and you do not want to automatically remove previously imported DataRaker conditions during every import (like the "SYNCHRONIZE" option does in Use Case 1). Maybe one execution of DataRaker finds conditions of one type and the next iteration finds conditions of another and you do not want to delete the records from the first pass before applying the second (or similar). The format for the input file would be similar to what follows. The primary differences are that there is no SYNCHRONIZE or TYPE keywords and (instead of the directive "syn") we use the "add" action directive.

DATA OBJECT|xfmr_1

DR_E1|add|WHO=dataraker|TIM=2009-02-27T16:22:17|TXT=Over voltage detected|EXT=DR_E1-1

DR_E1|add|WHO=dataraker|TIM=2009-02-27T17:22:17|TXT=Xfmr within 50% of capacity|EXT=DR_E1-2

DR_E2|add|WHO=dataraker|TIM=2009-02-27T18:22:17|TXT=Xfmr within 75% of capacity |EXT=DR_E2-1

OBJECT|xmfr_2

DR_E3|add|WHO=dataraker|TIM=2009-02-27T16:22:17|TXT=Xfmr within 100% of capacity|EXT=DR_E3-1

DR_E3|add|WHO=dataraker|TIM=2009-02-27T19:22:17|TXT=Xfmr 120% of capacity|EXT=DR_E3-2

END_DATA

Use Case 3 - Bulk Delete for NMS Conditions

Use Case 3 can use the same configuration as Use Case 1 other than the format of the input file processed by RTAdapter. In this use case, the RTAdapter input file specifies what conditions to delete from NMS. The creation of this form of input file would need to be done by the NMS project implementers. This option may be useful if an NMS administrator wants to automatically delete some subset of previously applied DataRaker conditions (for whatever reason). The format of the input file is similar to Use Case 2 except that no "TXT=" data is processed. All other fields are processed and can be captured in the NMS data_raker condition table. Note that "add" and "rem" records can also be combined in the same file, but must be specified in proper order ("del" must follow an "add" for same condition, for example).

DATA OBJECT|xfmr_1

DR_E1|rem|WHO=dataraker|TIM=2009-02-27T16:22:17|EXT=DR_E1-1

DR_E1|rem|WHO=dataraker|TIM=2009-02-27T17:22:17|EXT=DR_E1-2

DR_E2|rem|WHO=dataraker|TIM=2009-02-27T18:22:17|EXT=DR_E2-1

OBJECT|xmfr_2

DR_E3|rem|WHO=dataraker|TIM=2009-02-27T16:22:17|EXT=DR_E3-1

DR_E3|rem|WHO=dataraker|TIM=2009-02-27T19:22:17|EXT=DR_E3-2

END_DATA

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 SCADA_POINTS, ALIAS_MAPPING, or a model managed device attribute table such as ATT_SWITCH.

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

SCADA Controls Table

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

H_CLS

NUMBER

Class component of device handle.

Valid object class

H_IDX

NUMBER

Index component of device handle.

>0

NMS_ACTION

NUMBER

The Control Action ID number associated to the action.

Valid control action ID.1 (OPEN),2 (CLOSE)…

EXT_ACTION

NUMBER

Part of unique key to identify each external control action for a single device.

0..N, based on the number of control actions defined for the device.

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.

SCADA_ID

NUMBER

SCADA server ID.

0 (not a SCADA device), 1 (SCADA 1), 2 (SCADA 2)...

RTU_ID

VARCHAR2

64

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.) HTTP/HTTPS protocol is used as transport mechanism. It allows Oracle Utilities Network Management System to communicate securely with any MultiSpeak-compliant AMR, AVL, or SCADA system. In addition to HTTP/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

•

Installation Overview

•

Adapter Installation Instructions for Oracle WebLogic Server

Note : The installation instructions that follow assume that the Oracle Utilities Network Management System Web Gateway component has been installed. Refer to the Oracle Utilities Network Management System Installation Guide for complete instructions.

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.12.0.1.0.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.12.0.1.0.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 is used to apply adapter configuration changes and create the nms‑multispeak.ear file, which can be deployed to the Oracle WebLogic Server (see Software Configuration for configuration instructions).

To avoid performance impacts on the cesejb.ear, it is recommended that the nms-multispeak.ear not be deployed on the managed server where the cesejb.ear is deployed; however, both managed servers need to be in the same Oracle WebLogic Server domain.

Adapter Installation Instructions for Oracle WebLogic Server

Topics

•

Create a Managed Server (Optional)

•

Create a Foreign JNDI Provider

Note: Creating a foreign JNDI provider is required when the nms‑multispeak.ear is on a different managed server than the cesejb.ear; if they are deployed on the same server, skip this step.

•

Configure Data Source for the Adapters Managed Server

•

Deploy the Adapter

Create a Managed Server (Optional)

To simplify creation of a new managed server, you may clone an existing Oracle Utilities Network Management System managed server.

1.

Log in to the WebLogic Server Administration Console.

Note: The URL for WebLogic will be http://hostname:port/console where 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.

Click Lock & Edit.

3.

In the Domain Structure tree, expand Environment, then select Servers to open the Summary of Servers page.

4.

Select an Oracle Utilities Network Management System server in the Servers table and click Clone.

5.

Click the link to the cloned server and edit the settings:

a.

On the General tab, change the Listen Port and SSL Listen Port to unique values.

b.

On the Server Start tab, edit the Arguments field to remove the DRMI_URL parameter:

-DRMI_URL=t3://<hostname:port>

Create a Foreign JNDI Provider

In order for the Oracle Utilities Network Management System MultiSpeak Adapter, deployed on its own managed server, to communicate with the Oracle Utilities Network Management System (cesejb.ear), a foreign JNDI provider must be configured.

Note: Creating the foreign JNDI provider makes the cesejb.ear Enterprise JavaBeans (EJBs) appear local to the Oracle Utilities Network Management System MultiSpeak adapter.

1.

Log in to the WebLogic Server Administration Console.

2.

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.

On the Summary of Foreign JNDI Providers page, click New.

5.

Enter a name for the new Foreign JNDI Provider.

6.

Click Finish.

Configure Foreign JNDI Provider

1.

In the Foreign JNDI Provider table, click the new foreign JNDI provider name link.

2.

In the Settings for Foreign_JNDI_Provider_Name General tab, enter the following information:

Initial Context Factory: weblogic.jndi.WLInitialContextFactory

Provider URL: JNDI provider URL for the NMS (cesejb.ear)

User: valid NMS user who has the ‘NmsService’ role in WebLogic Server

Password: NMS user password

Confirm Password: enter the same NMS user password to confirm

3.

Click Save.

4.

Select the Links tab.

5.

Create the following foreign JNDI links

Link Name

Local JNDI Name

Remote JNDI Name

Session

cesejb/Session/remote

cesejb/Session/remote

MessageBean

cesejb/MessageBean/remote

cesejb/MessageBean/remote

PublisherBean

cesejb/PublisherBean/remote

cesejb/PublisherBean/remote

ViewerBean

cesejb/ViewerBean/remote

cesejb/ViewerBean/remote

ConnectionFactory

ConnectionFactory

ConnectionFactory

6.

Select the Targets tab.

7.

Select the managed server where the Oracle Utilities Network Management System MultiSpeak adapter will be deployed and click Save.

Configure Data Source for the Adapters Managed Server

You may configure a new JDBC data source or add the adapter managed server as a target to an existing Oracle Utilities Network Management System read/write data source.

Note: See "Configure Database Connectivity" in the Oracle Utilities Network Management System Installation Guide for information on creating JDBC data sources.

1.

In the Domain Structure tree, expand Services, then select Data Sources.

2.

In the Data Sources table, click the data source name (either a new data source or an existing read/write NMS data source) to open the Settings for JDBC_Data_Source_Name page.

3.

Select the Targets tab.

4.

Add the adapter managed server to the list of targets.

5.

Click Save.

Enabling Support for Plain HTTP

By default the adapter is configured to only accept incoming requests over HTTPS. To enable support for plain HTTP, add or uncomment the line in $NMS_CONFIG/jconfig/build.properties file:

option.no_multispeak_force_https

Then build new nms-multispeak.ear by running:

nms-install-config --java

Authentication Methods

By default the adapter is configured to use Basic HTTP Authentication for incoming web service requests. If credentials from the MultiSpeak message header should be used instead, add or uncomment the line in $NMS_CONFIG/jconfig/build.properties file:

option.no_multispeak_http_auth

Then build new nms-multispeak.ear by running:

nms-install-config --java

Note: This parameter has no effect on JMS transport mechanism available in the SCADA component of this adapter. It cannot use Basic HTTP Authentication mechanism.

The adapter authorizes incoming web service requests by checking that caller that has the ‘NmsWrite’ role in WebLogic Server..

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.

Select Install this deployment 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.

12.

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.

Either this parameter or both config.username and config.password parameters should be provided. If all are present, then the config.username/config.password pair is used.

config.username

Valid NMS username, which has the ‘NmsService’ role in WebLogic Server.

config.password

NMS user password. Value of this parameter should be encrypted.

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

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

config.ws_request_timeout

Timeout (in seconds) for web service requests to the AMR system. Request will fails if AMR system does not respond

before the timeout expires.

Default: 30 seconds

config.max_pings_per_cycle

Maximum number of meter ping requests to be processed in one cycle (cycle duration is defined by the config.ping_request_interval parameter).

Default: 10000

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

multispeak.max_update_attempts

Maximum number of retries for a request enable/disable meters (MeterChangedNotification request). This is only supported when Oracle Utilities Network Management System is integrated with Oracle Utilities Smart Grid Gateway.

Default: 3

multispeak.update_attempt_interval

Amount of time in seconds the adapter will wait after failure before retrying request to enable/disable meters (MeterChangedNotification request). This is only supported when Oracle Utilities Network Management System is integrated with Oracle Utilities Smart Grid Gateway.

Default: 60 seconds

multispeak.max_ping_batch_size

Maximum number of meter numbers to be included into a single ping request to the AMR/AMI system. If number of pending meter pings exceeds this value then multiple requests will be sent.

Default: 10000

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. Either this parameter or both config.username and config.password parameters should be provided. If all are present then config.username/config.password pair is used.

config.username

Valid NMS username, which has the ‘NmsService’ role in WebLogic Server.

config.password

NMS user password. Value of this parameter should be encrypted.

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

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 may be 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, which has the NmsService role in WebLogic Server.

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:

•

no - Meter read time will not be used, instead current system time will be used (this is the default behavior)

•

yes - 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. Outage restoration time is only updated if restoration time calculated from AMR data is earlier then the current restoration time.

Valid values:

no - outage restoration time will not be modified

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

earliest - outage restoration time will be updated with the earliest meter read time amongst the meters which reported power on for the restored outage

percentile - outage restoration time will be updated with the earliest meter read time which covers the desired percentile of meters which have reported power on. Percentile value is specified using rule_value_2 field. It should be in the range from 1 to 99 (inclusive).

Meter read times preceding outage start time or past current time are ignored.

Example of ‘percentile’ setting.

rule_value_1 = 'percentile'

rule_value_2 = 50

This configuration corresponding to using median value from the all meter read times for meters, which reported power on. Given following four meter read times

00:00:10

00:00:11

00:00:20

00:00:30

the median value would be 00:00:11 (second value out of four).

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. Automated meter ping requests (PSO Verification, PDO Verification, and Restoration Verification) are considered completed when TTL expires. Manual meter ping requests, which were not explicitly completed or cancelled by the user, are automatically cancelled when TTL expires.

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 automated meter ping requests remain active until the first response is received. Manual meter ping requests in this case remain active until explicitly completed or cancelled by the user.

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.

Urgent Ping

The adapter supports the ability to immediately ping a single meter. Such ping requests are initiated by sending PING high-level message containing single meter id to the adapter. Requests received via high-level message are processed right away without being subject to batching. They do not persist in database. Cache is not used to satisfy such requests so the AMR system is always contacted.

Business Scenario:

1.

The operator or system has chosen a device to "Ping."

2.

PING high-level message containing meter id is sent to the adapter.

3.

The adapter sends ping request to the AMR system.

4.

A response is received from the AMR system.

5.

The adapter sends PING_RESPONSE high-level message containing received meter status back to the client.

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 device status information to SCADA system

•

Sending NMS tags and other conditions 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/OAAnalogChangedNotificationByPointIDSyncAnalogChangedNotificationByPointID

•

nms-amr/queue/OATagChangedNotificationByPointIDSCADATagChangedNotificationSCADATagChangedNotificationByPointID

•

nms-amr/queue/OATagChangedNotificationByPointIDSyncTagChangedNotificationByPointID

•

nms-amr/queue/OAInitiateStatusReadByPointIDInitiateStatusReadByPointID

•

nms-amr/queue/OAHighlightObjectInDisplayHighlightObjectInDisplay

•

nms-amr/queue/OAInitiateTagReadByPointIDInitiateTagReadByPointID

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

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"

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"

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:

•

controlAction/scadaPointID - SCADA point ID;

•

controlAction/controlKey - SCADA-specific value indicating requested operation (open/close device, place/remove tag);

•

controlAction/desiredValue - the desired value of the SCADA point being controlled (for example, transformer tap setting);

•

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 does not use it. It is always populated with the value Direct operate.

•

Field relayType is required, but NMS does not use it. It is always populated with the value Normal.

•

NMS will not issue separate select and operate commands.

•

The desiredValue field is not part of the MultiSpeak 4.1 specification. The SCADA system needs to be aware of this Oracle-specific extension.

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 devices in the NMS model to the SCADA system.

The SCADA system plugin method buildScadaPointId is used to construct SCADA point id for NMS devices.

SCADAStatusChangedNotification

Sends NMS device status changes to SCADA system.

If support for pending construction devices is enabled then boolean extension item named 'PENDING_CONSTRUCTION' is used to indicate pending construction status of the NMS device.

Example of a message to SCADA system when a device in NMS has been commissioned (this means that the device is no longer pending construction therefore the value of the extension item is false).

<ns4:SCADAStatusChangedNotification xmlns:ns4="http://www.multispeak.org/Version_4.1_Release">

<ns4:scadaStatuses>

<ns4:scadaStatus objectID="148.1345#C">

<ns4:extensionsList>

<ns4:extensionsItem>

<ns4:extName>PENDING_CONSTRUCTION</ns4:extName>

<ns4:extValue>false</ns4:extValue>

<ns4:extType>boolean</ns4:extType>

</ns4:extensionsItem>

</ns4:extensionsList>

<ns4:status>Open</ns4:status>

<ns4:changeCounter>0</ns4:changeCounter>

</ns4:scadaStatus>

</ns4:scadaStatuses>

</ns4:SCADAStatusChangedNotification>

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.

Outgoing Tags and Other Conditions

If SCADA system has knowledge of the NMS electrical model, then the adapter can be configured to send information about tags and other conditions (for example, notes) in the NMS model to the SCADA system.

The SCADA system plugin method buildScadaPointId is used to construct SCADA point id associated with NMS tag/condition.

The SCADA system plugin methods setTagHandle, setTagId, setTagType, setUserName, setScadaPointId, setAction, and setTagData are used to populate the outgoing tag update messages.

SCADATagChangedNotification

Sends changes to NMS tags and other conditions to SCADA system.

This operation is vendor extension to the MultiSpeak 4.1 specification.

TagChangedNotificationByPointID

Sends information about NMS tags and other conditions to SCADA system in response to InitiateTagReadByPointID request.

This operation is vendor extension to the MultiSpeak 4.1 specification.

Both SCADATagChangedNotification and TagChangedNotificationByPointID messages contain sequence of ScadaTag objects. The following ScadaTag fields are used by the default SCADA system plugin implementation:

•

@objectID - NMS condition handle

•

tagID - NMS condition external id

•

scadaPointID - SCADA point id

•

@verb = action (New - condition placed; Change - condition update; Delete - condition removed)

•

tagType - SCADA tag type

•

username - NMS operator username

•

tagReason - condition text

•

tagInsertionTime - condition creation timestamp

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

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

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

</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 is vendor extension to the 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"/>

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

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

</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 is vendor extension to the 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"/>

</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 voltageAlarm 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"/>

</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 from NMS to SCADA as series of StatusChangedNotificationByPointID messages.

InitiateTagReadByPointID

Initiates process of sending tag/condition information from NMS to SCADA as series of TagChangedNotificationByPointID messages.

The following message fields should be used:

•

responseURL - web service URL where NMS should send TagChangedNotificationByPointID messages with response data (not used in case of JMS transport)

•

transactionID - request transaction ID (all TagChangedNotificationByPointID messages sent in response to this request will contain the specified transaction ID)

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 unless Basic HTTP Authentication is used. When used for authentication, these attributes should be populated with valid NMS credentials for all messages coming to NMS with exception of PingURL and GetMethods. When Basic HTTP Authentication is used, the attribute Pwd should be either empty or omitted.

The attribute UserID is also used to determine the SCADA system the message originated from. It is checked against the names of the known SCADA systems in the SCADA_IDS database table. If the adapter is configured to communicate with a single SCADA system and the configuration parameter config.strict_scada_name_check is set to false, then SCADA name check is skipped.

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.

Either this parameter or both config.username and config.password parameters should be provided. If all are present then config.username/config.password pair is used.

config.username

Valid NMS username, which has the 'NmsService' role in WebLogic Server.

config.password

NMS user password. Value of this parameter should be encrypted.

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

config.strict_scada_name_check

SCADA name validation. If set to 'false' and only one SCADA system is configured for the MultiSpeak Adapter in the SCADA_IDS database table then SCADA name check is skipped. Otherwise field UserID in the MultiSpeak message header or username of the web services caller (if UserID is empty) is matched against the values in the SCADA_NAME field in the SCADA_IDS database table. Request is rejected if matched value is not found.

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

These parameters control tag-related data flows.

Parameter

Description

<scada name>.support_tags

Enable/disable support for incoming tags.

Default value: false (incoming tags are not supported)

<scada name>.outgoing_tag.class.<idx>

Names of the NMS condition classes for which updates should be sent to the SCADA system. This applies to the children of the configured classes as well.

<scada name>.outgoing_tag.block_size

Block size for the outgoing condition messages.

Default: 10

<idx> - suffix used to make parameter name unique; any value can be used as long as resulting configuration parameter name is unique.

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. 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>.outgoing_status.allow_scada

Allow device status updates for SCADA devices to be sent to the SCADA system. This is disabled by default because SCADA system is the master for the information about SCADA devices.

Default: false

<scada name>.outgoing_status.allow_pending_construction

Allow device status updates for pending construction devices as well as changes in pending construction status of devices to be sent to the SCADA system.

Default: false

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

•

SCADATagChangedNotification

•

TagChangedNotificationByPointID

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.

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');

INSERT INTO scada_link_ops (id, link_id, operation, ws_url, timeout, persistent)

VALUES (32, 4, 'GetMethods', 'http://scada-server:8080/GetMethods', 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

For incoming SCADA tags:

The SCADA tag type should be entered into the KEYWORD column.

The NMS condition class name should be entered into VALUE column.

For outgoing NMS conditions:

NMS condition class name should be entered into the KEYWORD column.

SCADA tag type should be entered into the VALUE column.

The PROCESS_TYPE should be 'C'.

Examples

Incoming

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');

Outgoing

INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)

VALUES (21, 200, 'hold', 'Hold', 'C');

INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)

VALUES (22, 200, 'hot', 'Hot', 'C');

INSERT INTO scada_synonyms (id, scada_id, keyword, value, process_type)

VALUES (23, 200, 'note', 'Note', '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 -java 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

setScadaPointId

void setScadaPointId(ScadaTag tag, java.lang.String pointId)

This method is used to set SCADA Point ID in the outgoing tag update message.

Parameters:

tag - ScadaTag object to be updated

pointId - SCADA Point ID

Default implementation:

Sets 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 tagID element

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 the tagID element

getTagHandle

Handle getTagHandle(ScadaTag tag)

This method is used to extract NMS condition handle from tag update message.

Parameters:

tag - ScadaTag object

Returns:

NMS condition handle

Default implementation:

Attempts to parse the objectID attribute as NMS handle and returns parsed value or null if the objectID attribute cannot be parsed as NMS handle.

setTagHandle

void setTagHandle(ScadaTag tag, Handle condHdl)

This method is used to set NMS condition handle in the outgoing tag update message.

Parameters:

tag - ScadaTag object to be updated

condHdl - NMS condition handle

Default implementation:

Sets value of the 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

setTagType

void setTagType(ScadaTag tag, java.lang.String tagType)

This method is used to set SCADA tag type in the outgoing tag update message.

Parameters:

tag - ScadaTag object to be updated

tagType - SCADA tag type

Default implementation:

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

setTagData

void setTagData(ScadaTag tag, java.util.Map<java.lang.String, java.lang.Object> data)

This method is used to set additional tag data fields in the outgoing tag update message.

Parameters:

tag - ScadaTag object to be updated

data - Map <tag field name -> tag field value>

Default implementation:

Sets value of the tagReason element to the value of the 'text' entry in the data parameter.

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

setUserName

void setUserName(ScadaTag tag, java.lang.String username)

This method sets operator username in the outgoing tag update message.

Parameters:

tag - ScadaTag object to be updated

username - NMS operator username

Default implementation:

Sets 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

getPhaseName

java.lang.String getPhaseName(int phase)

This method is used to convert NMS phase code into phase name.

Parameters:

phases - NMS phase code (1 - A, 2 - B, 4 - C)

Returns:

phase name or empty string

Default implementation:

Returns 'A' if phase is 1, 'B' if phase is 2, and 'C' if phase is 4. Empty string is returned for any other input.

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

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 -java multispeak.SCADA <message>

Following messages are supported:

RELOAD

Forces 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

AMR

The AMR component of the NMS MultiSpeak adapter responds to several high-level messages. High-level message can be sent using Action command-line utility.

Action -java multispeak.AMR <message>

The following messages are supported:

PING <meter id>

Initiates "urgent" meter ping request for a single meter. <meter id> is the internal NMS meter identifier. When response to this ping request is received, the high-level message PING_RESPONSE is sent to the client, which initiated the ping.

PING_RESPONSE <meter id> <meter status> <raw meter status>

Response to the PING message. This is an outgoing message. It should not be sent to the adapter. The client, which sent the PING message, is expected to handle this message.

Parameters:

•

<meter id> - the same meter identifier, which was sent in the PING message being responded to.

•

<meter status> - meter status.

Possible values:

ON - meter has power

OFF - meter does not have power

UNKNOWN - undetermined meter status

ERROR - error occurred while trying to ping the meter

•

<raw meter status> - raw meter status value as received from the AMR/AMI system.

Troubleshooting

NMS MultiSpeak Adapter uses Apache log4j library to log error, warning and debug messages. To enable debug output following lines should be added to the log4j configuration file used by the WebLogic Server where the Adapter is deployed.

<logger name="com.splwg.oms.interfaces">

<level value="DEBUG"/>

</logger>

<logger name="com.splwg.oms.ws.multispeak">

<level value="DEBUG"/>

</logger>

<logger name="MultiSpeak">

<level value="DEBUG"/>

</logger>

For additional details about configuring log4j logging in WebLogic Server see Configure Log4j Logging Services section in the Oracle Utilities Network Management System Installation Guide.

At runtime debug output can be toggled by sending high-level message to the appropriate component of the Adapter.

Action -java multispeak.<component> DEBUG

where <component> is one of

•

AMR - AMR/AMI component

•

AVL - AVL component

•

SCADA - SCADA component

Introduction

The Oracle Utilities Network Management System Mobile Workforce Management Adapter provides services required by the Oracle Utilities Network Management System Integration to Oracle Utilities Mobile Workforce Management.

One of the main functions of the adapter is translating Oracle Utilities Network Management System trouble events into Oracle Utilities Mobile Workforce Management activities. A trouble event is some situation in the electrical network, which requires attention ( e.g., an outage causing some number of customers to be without electric power). An activity is a unit of work which a mobile crew needs to perform. Single event can be associated with multiple activities during its lifetime (for example, one crew may need to perform initial assessment before another crew or crews can start repair work). The responsibility of the adapter is to maintain relationships between the trouble events and activities and subsequently between trouble events and mobile crews.

Note: For more information see Oracle Utilities Network Management System Integration to Oracle Utilities Mobile Workforce Management Implementation Guide.

Installation

The Oracle Utilities Network Management System Mobile Workforce Management Adapter is delivered as a single file:

•

$CES_HOME/dist/install/nms-mwm.ear.base - NMS-MWM adapter application.

The nms-install-config script is used to apply adapter configuration changes and create the nms-mwm.ear file, which can be deployed to the Oracle WebLogic Server (see Software Configuration for configuration instructions).

To avoid performance impact on the main NMS application (cesejb.ear), it is recommended that the nms-mwm.ear not be deployed on the same managed server where the cesejb.ear is deployed; however, both managed servers need to be in the same Oracle WebLogic Server domain.

Adapter Installation Instructions for Oracle WebLogic Server

Topics

•

Create a Managed Server (Optional)

•

Create a Foreign JNDI Provider

Note: Creating a foreign JNDI provider is required when the nms-mwm.ear is on a different managed server than the cesejb.ear; if they are deployed on the same server, skip this step.

•

Configure Foreign JNDI Provider

•

Configure Data Source for the Adapters Managed Server

•

Deploy the Adapter

Create a Managed Server (Optional)

To simplify creation of a new managed server, you may clone an existing Oracle Utilities Network Management System managed server.

6.

Log in to the WebLogic Server Administration Console.Note: The URL for WebLogic will be http:// hostname:port/console where 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).

7.

Click Lock & Edit .

8.

In the Domain Structure tree, expand Environment, then select Servers to open the Summary of Servers page.

9.

Select an Oracle Utilities Network Management System server in the Servers table and click Clone .

10.

Click the link to the cloned server and edit the settings:

•

On the General tab, change the Listen Port and SSL Listen Port to unique values.

•

On the Server Start tab, edit the Arguments field to remove the DRMI_URL parameter:-DRMI_URL=t3://<hostname:port>

Create a Foreign JNDI Provider

In order for the Oracle Utilities Network Management System Mobile Workforce Management Adapter, deployed on its own managed server, to communicate with the Oracle Utilities Network Management System (cesejb.ear), a foreign JNDI provider must be configured.

Note: Creating the foreign JNDI provider makes the cesejb.ear Enterprise JavaBeans (EJBs) appear local to the Oracle Utilities Network Management System Mobile Workforce Management Adapter.

1.

Log in to the WebLogic Server Administration Console.

2.

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.

On the Summary of Foreign JNDI Providers page, click New .

5.

Enter a name for the new Foreign JNDI Provider.

6.

Click Finish .

Configure Foreign JNDI Provider

1.

In the Foreign JNDI Provider table, click the new foreign JNDI provider name link.

2.

In the Settings for Foreign_JNDI_Provider_Name General tab, enter the following information: Initial Context Factory: weblogic.jndi.WLInitialContextFactoryProvider URL: JNDI provider URL for the NMS (cesejb.ear)User: valid NMS user who has the ‘NmsService’ role in WebLogic ServerPassword: NMS user passwordConfirm Password: enter the same NMS user password to confirm

3.

Click Save .

4.

Select the Links tab.

5.

Create the following foreign JNDI links:

Link Name

Local JNDI Name

Remote JNDI Name

Session

cesejb/Session/remote

cesejb/Session/remote

PublisherBean

cesejb/PublisherBean/remote

cesejb/PublisherBean/remote

CrewOperations

cesejb/CrewOperations/remote

cesejb/CrewOperations/remote

6.

Select the Targets tab.

7.

Select the managed server where the Oracle Utilities Network Management System Mobile Workforce Management Adapter will be deployed and click Save.

Configure Data Source for the Adapters Managed Server

You may configure a new JDBC data source or add the adapter managed server as a target to an existing Oracle Utilities Network Management System read/write data source.

Note: See "Configure Database Connectivity" in the Oracle Utilities Network Management System Installation Guide for information on creating JDBC data sources.

1.

In the Domain Structure tree, expand Services, then select Data Sources .

2.

In the Data Sources table, click the data source name (either a new data source or an existing read/write NMS data source) to open the Settings for JDBC_Data_Source_Name page.

3.

Select the Targets tab.

4.

Add the adapter managed server to the list of targets.

5.

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-mwm.ear file.

4.

Click Next .

5.

Select Install this deployment 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-mwm .

10.

Click Next .

11.

Review the configuration settings you have specified.

12.

Click Finish to complete the installation.

Database Schema

The adapter uses several database tables where the information about trouble events, activities, and notifications is persisted.

OMS_MWM_EVENTS

This table stores the most recent information about the trouble events which have been sent to the Oracle Utilities Mobile Workforce Management system. This table is used to determine if trouble event update contains changes which should be sent out. This table is also used during synchronization sequence.

Field

Description

EVENT_IDX

Event index.

Primary key.

EXTERNAL_ID

Event’s external id.

DEVICE_CLS

Class part of the event’s device handle.

DEVICE_IDX

Index part of the event’s device handle.

PHASES

Affected device phases.

STATUS

Event’s condition status (PSO, PDO, etc.)

STATE_KEY

Event’s state key.

NUM_CUST_OUT

Number of affected customers.

NUM_CALLS

Number of customer calls.

TROUBLE_CODE

Event’s trouble code (combination of the unique trouble codes of the customer calls).

ERT

Estimated restoration time.

COMMENTS

Event comments.

LAST_UPDATE_TIME

Last update time.

OMS_MWM_ACTIVITIES

This table stores mobile activities known to the adapter.

Field

Description

ACTIVITY_ID

Activity identifier. Primary key. Generated by the adapter.

EXTERNAL_ID

External identifier of the activity. Presently unused.

EVENT_IDX

NMS event index. Foreign key into the OMS_MWM_EVENTS table.

CREW_ID

Crew id/name.

CREW_TYPE

Crew type. Only populated if in NMS a generic crew is assigned to the activity.

STATUS

Activity status.

Valid values:

•

INITIAL - initial state for activities created by NMS

•

NO_CREW - activity without a crew

•

DISPATCHED - activity has been given to a crew

•

DISPATCHED_ACK - crew has accepted the activity

•

EN_ROUTE - crew is en-route to work location

•

ARRIVED - create has arrived at the work location but haven't started the work

•

STARTED - crew has started the work

•

SUSPENDED - crew has temporarily suspended this activity

•

COMPLETE - activity is completed

•

CANCELLED - activity is cancelled

PENDING

'Pending flag (Y means that this activity should not be cancelled when crew is released). It is set when an activity is created from the MWM without a crew.

CREATED

Activity creation time.

COMPLETED

Activity completion/cancellation time.

LAST_UPDATE_TIME

Last update time.

OMS_MWM_ALARMS

This table stores notifications sent to the Oracle Utilities Mobile Workforce Management system. It is used to prevent sending of duplicate notifications.

Field

Description

ALARM_IDX

Alarm index.

Primay key.

ACTIVITY_ID

Activity identifier. Foreign key into the OMS_MWM_ACTIVITIES table.

SENT_TIME

Time when the alarm was sent to mobile system.

OMS_MWM_CREW_ACTIONS

This table is used to record actions performed by a mobile crew in the course of working on a trouble event.

Field

Description

ID

Primary key.

Generated by the sequence OMS_MWM_CREW_ACTIONS_SEQ.

EXTERNAL_ID

External identifier. Should be unique for the rows associated with the same trouble event.

EVENT_IDX

Event index.

Supported Data Flows

All data flows are implemented as SOAP web services. HTTPS transport is used (by default access over plain HTTP is disabled).

Outgoing Flows

Heartbeat

When connection to the Oracle Utilities Mobile Workforce Management system is not established the adapter periodically sends out PingURL message. Once such message is sent successfully, the connection is considered established, sending of the PingURL messages stops and the adapter executes synchronization sequence. The purpose of the synchronization sequence is to send out updates for the activities where corresponding trouble event information has changed with the connection was down.

Create/Update Mobile Activity

CreateUpdateMessage message is sent by the adapter whenever new mobile activity needs to be created or an existing activity needs to be updated. The message contains full details of the trouble event associated with the activity as well as details of the activity itself. If there are multiple activities associated with the same trouble event separate CreateUpdateMessage is sent for each activity.

Complete/Cancel Mobile Activity

CompleteOrder message is sent by the adapter when activity is needs to be completed or cancelled. When a trouble event is completed or cancelled all the activities associated with the trouble event are completed or cancelled. When a crew is released from a trouble event - only the activity associated with that crew is cancelled.

Notification

When a trouble event-related alarm is created in Oracle Utilities Network Management System a Notification message containing text of the alarm can be sent by the adapter. The alarm has to be of the supported type. Only one type of notifications is supported - ERT Expiration notification. Separate Notification message is sent for each activity associated with the trouble event.

Incoming Flows

Create Mobile Activity

Sending CreateActivity message to the adapter creates a new mobile activity for an existing trouble event. Either an index of an existing trouble event or activity id of an existing activity needs to be passed in the request. Activity id of the newly created mobile activity is returned.

Update Mobile Activity

Sending UpdateActivity message to the adapter allows to perform different crew-related actions depending on the state value passed in the request.

•

Dispatched - assigns the mobile crew associated with the activity to the trouble event.

•

EnRoute - places the mobile crew associated with the activity en-route to the trouble event.

•

Started - places the mobile crew associated with the activity onsite for the trouble event.

•

Suspended - suspends the mobile crew associated with the activity from working on the trouble event.

•

NoCrew - releases the mobile crew associated with the activity from working on the trouble event. The same effect can be achieved by sending crewId in the message. Releasing the crew will cause the activity to be cancelled.

•

Complete - completes the activity and releases the crew from the trouble event.

•

Cancelled - cancels the activity and releases the crew from the trouble event.

Update Trouble Event

Sending UpdateEvent message to the adapter allows trouble event in the Oracle Utilities Network Management System to be updated. In particular it allows to

•

Update Estimated Restoration Time

•

Update Event Case Note

•

Update Event Details information

•

Update Failed Equipment information

•

Update crew action steps

•

Confirm Outage Device

•

Move outage upstream or downstream

•

Restore outage

•

Cancel trouble event

Query

Query request allows retrieving information from Oracle Utilities Network Management System. The following query types are supported:

•

call - returns customer calls for specific trouble event

•

customer - returns customer information for specific account number

•

device_info - returns device information for specific device name (alias)

Asynchronous Message Acknowledgment

The outgoing requests other than PingURL can be processed asynchronously. In such case the receiving side would send back response message containing error code ‘DEFERRED’. This is an indication the request is being processed asynchronously. The adapter would wait up to the configured amount of time (mwm.ack_wait_timeout) for the incoming MessageAck message containing result of the earlier request. There are 3 possible outcomes: Success - request was processed successfully; Error - an error occurred while processing the request; Failure - request cannot be delivered to the Oracle Utilities Mobile Workforce Management system. Failure response is treated as loss of connection between the system and initiates heartbeat flow followed by synchronization sequence. If MessageAck message is not received during the configured period of time then the Failure outcome is assumed.

Correspondence between the original request message and the MessageAck message is established through the messageId attribute in the message header of the original request. The MessageAck message must contain the same message id.

Software Configuration

Configuration for the Oracle Utilities Network Management System Mobile Workforce Management Adapter comes from the following sources:

•

CES_PARAMETERS database table

•

Oracle Utilities Network Management System configuration rules

•

Data mapping configuration

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.

Note: For detailed information see "encrypt" in the Oracle WebLogic Server Command Reference.

Configuration Parameters

Entries in the CES_PARAMETERS database table for the Oracle Utilities Network Management System Mobile Workforce Management Adapter should have value 'MWMInterface' in the APP column. Column ATTRIB should contain name of the configuration parameter and column VALUE its value.

General Configuration Parameters

Parameter

Description

config.enabled

Enable/disable NMS-MWM interface.

Default: true

config.credentials

Absolute path to the file containing user credentials the adapter will use to communicate with Oracle Utilities Network Management System.

Either this parameter or both config.username and config.password parameters should be provided. If all are present, then the config.username/config.password pair is used.

config.username

Valid NMS username, which has the 'NmsService' role in WebLogic Server.

config.password

NMS user password. Value of this parameter should be encrypted.

config.activity_accepted_action

Key of the state transition action, which is executed when activity create/update message is accepted by the Oracle Utilities Mobile Workforce Management system.

config.activity_rejected_action

Key of the state transition action, which is executed when activity create/update message is rejected by the Oracle Utilities Mobile Workforce Management system.

config.default_crew_type

Default crew type.

The adapter uses this crew type when it needs to create a mobile crew which does not exist in NMS. This parameter should be set to the name of a valid NMS crew type. If not specified then the adapter will not be able to create crews.

config.allow_device_ops

Allow the adapter to operate device in NMS model.

Default: false

config.call_send_limit

Maximum number of customer calls (incidents) to be included into an activity create/update message sent by the adapter. Customer calls with higher priority are included ahead of the calls with lower priority. Note: including large number of calls greatly increases message size.

Default: 0

mwm.activity_id_prefix

Activity id prefix.

Default: NMS-

mwm.ws_request_timeout

Timeout (in seconds) for the outgoing web service requests. Requests would fail if response is not received before the timeout expires.

Default: 30

mwm.ack_wait_timeout

Timeout (in seconds) when waiting for acknowledgment of outgoing messages sent asynchronously. Link failure is declared if acknowledgment is not received before the timeout expires.

Default 60

mwm.url

Default URL of the web service where the adapter should send outgoing messages.

mwm.url.<operation name>

Operation-specific web service URLs. Allows for the outgoing messages to be send to the different URLs based on the message type (operation).

Valid operation names:

•

PingURL - hearbeat message

•

CreateUpdateOrder - creating or updating mobile activity

•

CompleteOrder - completing or canceling mobile activity

•

Notification - notification message

mwm.username

Username included in the outgoing messages as part of HTTP Basic authentication.

mwm.password

Password included in the outgoing messages as part of HTTP Basic authentication. Value of this parameter should be encrypted.

mwm.header.<attribute name>

The outgoing messages include standard header (XML element 'MessageHeader'). This configuration parameter is used to specify additional header attributes.

The following attributes are required when integrating with the Oracle Utilities Mobile Workforce Management system:

•

systemId - NMS instance identifier

•

country - country code

Description Text for the Alarm Messages Generated by the Adapter

Parameter

Description

msg.started

The adapter has been started.

msg.stopped

The adapter has been stopped.

msg.established

Connection to the Oracle Utilities Mobile Workforce Management system has been established.

msg.synchronized

Synchronization sequence has finished.

msg.failed

Connection to the Oracle Utilities Mobile Workforce Management system has failed.

msg.activity_rejected

Oracle Utilities Mobile Workforce Management returned error in response to a request to create an activity.

Note: this alarm is not current being generated.

msg.event_canceled

Event cancelation has been requested from the Oracle Utilities Mobile Workforce Management system but the event cannot be canceled in NMS.

msg.outage_restored

Outage restoration has been reported from the Oracle Utilities Mobile Workforce Management system but the outage cannot be restored in NMS (most likely because outage device cannot be closed).

msg.outage_confirmed

Outage has been confirmed by the Oracle Utilities Mobile Workforce Management system but the outage cannot be confirmed in NMS (outage device cannot be opened).

Query Configuration

Parameter

Description

query.type.<query type>

Query type.

Valid query types:

•

device_info - device information

•

customer - customer information

•

call - customer call information for an event

query.<query type>.table

Database table or view to query.

Not applicable to the "device_info" query type.

query.<query type>.where

Additional conditions to be included in the query's WHERE clause.

query.<query type>.order_by

Query's ORDER BY clause (sorting condition).

query.<query type>.max_results

Maximum number of rows allowed to be returned for this query type.

Default: 100

query.<query type>.param.<param_name>

Maps query parameter name to a database column name.

The following parameters are defined for different query types:

•

device_info

•

deviceAlias - device alias

•

customer

•

accountNumber -customer account number

•

call

•

eventIdx - NMS event index

query.<query type>.column.<column_name>

Label for the data retrieved for the specified database column

Oracle Utilities Network Management System Configuration Rules

Oracle Utilities Network Management System configuration rules control various aspects of the system. You can configure these rules using the Oracle Utilities Network Management System Configuration Assistant tool. This section only covers the rules which directly affect the integration between Oracle Utilities Network Management System and Oracle Utilities Workforce Management system.

Rule

Description

crewFollowOutageDevice

This rule indicates whether or not crews dispatched to an event are automatically relocated if the device location changes. If this rule is enabled, dispatched crews are automatically relocated to the new device when an event moves to a different device in Oracle Utilities Network Management System. Typically, this rule should be enabled when Oracle Utilities Network Management System is integrated with Mobile Workforce Management system.

Default: no (disabled)

mobilePreassignCrew

Allows Oracle Utilities Network Management System user to assign and release mobile crews.

Default: no (disabled)

repredictionCrewReassignment

This rule enables or disables automatic crew reassignment/redispatch when event reprediction occurs in Oracle Utilities Network Management System.

For example:

Events A, B, and C exist on laterals off of a feeder backbone. Crew 1 is dispatched to event A, crew 2 is dispatched to event B, and crew 3 is assigned to event C. More calls come in on the feeder, eventually causing the system to repredict and group events A, B, and C to an upstream device. The resulting grouped event is called event A.

•

If this rule is enabled, crew 1 remains dispatched to event A, crew 2 is undispatched from event B and redispatched to event A, and crew 3 is unassigned from event C and reassigned to event A.

•

If this rule is disabled, crew 1 remains dispatched to event A, crew 2 is only undispatched from event B, and crew 3 is only unassigned from event C.

Default: yes (enabled)

sendToMobileState

This rule specifies the state(s) at which an event is sent to Oracle Utilities Mobile Workforce Management. When an event transitions to one of the states defined in this rule, a "send to mobile" flag is set in the event. The Oracle Utilities Network Management System-Mobile Workforce Management Interface uses this flag to determine whether an event should be processed by the interface, triggering field order creation in Oracle Utilities Mobile Workforce Management.

Default: none

singleCrewPerEvent

This rule indicates whether or not multiple crews can be assigned or dispatched to an event in Oracle Utilities Network Management System. If this rule is enabled, only one crew can be assigned or dispatched to an event at any given time. The repreditionCrewReassignment rule is implicitly disabled if this rule is enabled.

Default: no (disabled)

useGenericAssign

Allows treating of crews with crew key less 1000 as "generic crews".

Default: no (disabled)

useMdt

This rule enables or disables MDT (Mobile Dispatch Terminal) crew flag functionality. This rule should be enabled when the Oracle Utilities Network Management System-Mobile Workforce Management Interface is being used.

Default: no (disabled)

Data Mapping

Data mapping converts data elements between a data source and a destination. Oracle Utilities Network Management System Mobile Workforce Management Adapter uses data mapping configuration to determine activity type and notification type for the outgoing messages.

Data Mapping Overview

The Oracle Utilities Network Management System Mobile Workforce Management Adapter provides a configurable data-mapping facility. This facility can be used to populate certain data elements in the outgoing messages.

Many-to-many data mapping: Most data flows from Oracle Utilities Network Management System to Oracle Utilities Mobile Workforce Management use many-to-many data mapping. This means that a source value can be mapped to many different target values, based on one or more conditions.

Data mapping is rules-based. Rule configuration is defined in the following database tables:

Mapping Table

Description

OMS_MWM_MAPPING_RULES

This table defines the field to be mapped and, for many-to-many mapping, the value to be written to the mapped field if all conditions are met.

OMS_MWM_MAPPING_CHECKS

This table defines conditions that may be applied to mapping rules.

OMS_MWM_MAPPING_RULE_CHECKS

This table associates a rule with a condition. Together, this table and the two previous tables are used to define many-to-many data mapping.

OMS_MWM_MAPPING_RULES Table

The OMS_MWM_MAPPING_RULES table contains rules for mapping data values between Oracle Utilities Network Management System and Oracle Utilities Mobile Workforce Management. The fields comprising each rule are described below:

Field

Description

rule_id

A unique identifier for this rule.

mapping

The name of the mapping rule set used to group related mapping rules. For example, the mapping rule set 'mwmOrder' defines rules for mapping Oracle Utilities Network Management System event data to the corresponding field order data in Oracle Utilities Mobile Workforce Management for outgoing orders.

mapped_field

The name of the field where the target value (the result of the mapping) should be written. For example, orderType, priority and alarmType are mapped fields.

mapped_value

This is the value to be written to the mapped field if all conditions defined for this rule are met. This is also referred to as the target value.

table_id

This field is not used.

rule_order

The order in which this rule should be applied when a series of rules is being used. The lowest value is used first.

Note: To define the default value for a field, configure a rule with no conditions and set that rule to be the last rule applied.

OMS_MWM_MAPPING_CHECKS Table

The OMS_MWM_MAPPING_CHECKS table contains conditions that can be used by the mapping rules defined in the OMS_MWM_MAPPING_RULES table.

Field

Description

check_id

A unique identifier for this condition.

field_name

The name of the field to which the condition applies.

cond_str

The condition to be applied. For a description of the condition format, see the next section.

negate

Indicates whether or not to negate the condition result. If this is set to Y, the result is negated. This field is optional.

Condition Format

Three different types of conditions are allowed in mapping rule checks. The format for each type of condition is shown in the table below.

Condition Type

Condition Format

Description

Exact string compare

<string to compare against>

The condition is true if the field value (converted to a string) exactly matches the comparison string.

Regular expression

@regex <regular expression>

The condition is the true if the field value (converted to a string) matches the given regular expression.

Class inheritance

@inheritFrom <class name>

The condition is true if the field contains the class name specified in the condition or the name of any child class.

Note: The angle brackets (<>) shown in the following table are not part of the format. The text inside the brackets should be replaced with the actual value as indicated.

OMS_MWM_MAPPING_RULE_CHECKS Table

This table is used to create many-to-many relationship between OMS_MWM_MAPPING_RULES and OMS_MWM_MAPPING_CHECKS tables. Each rule check associates a mapping rule with a condition (mapping check).

Field

Description

rule_id

The key to the mapping rule in the OMS_MWM_MAPPING_RULES table.

check_id

The key to the condition in the table OMS_MWM_MAPPING_CHECK table.

Mapping from Oracle Utilities Network Management System to Oracle Utilities Mobile Workforce Management

All data mapping rules for Oracle Utilities Network Management System to Oracle Utilities Mobile Workforce Management data flows belong to the "mwmOrder" rule set. This rule set supports mapping for the following data elements:

•

Activity Type ( "orderType")

•

Activity Priority ("externalPriority")

•

Notification Type ("alarmType")

These data elements are mapped using many-to-many data mapping, as described in the following example.

Field Order Type Mapping Configuration Example

This example shows how to define data mapping rules to set the Oracle Utilities Mobile Workforce Management activity type to ‘ROUTXFMWD’ for events meeting the following conditions:

•

The event is an RDO (real device outage);

•

The event is on a transformer;

•

The event has "Wire Down Pole-to-Pole" trouble code;

•

The event is created under normal (non storm) conditions.

To configure data mapping for this example, complete the following steps:

1.

Configure a mapping rule in the OMS_MWM_MAPPING_RULES table to set the Order Type to ROUTXFMWD. The rule set is ‘mwmOrder’; the mapped field is ‘orderType’; the mapped_value is ‘ROUTXFMWD':

INSERT INTO oms_mwm_mapping_rules(rule_id, mapping, mapped_field, mapped_value, rule_order)VALUES (15, 'mwmOrder', 'orderType', 'ROUTXFMWD', 70);

2.

Configure the required conditions in the OMS_MWM_MAPPING_CHECKS table:

/* RDO */INSERT INTO oms_mwm_mapping_checks (check_id, field_name, cond_str)VALUES (1, 'cond_status', '4');/* Wire Down Pole to Pole */INSERT INTO oms_mwm_mapping_checks (check_id, field_name, cond_str)VALUES (15, 'trouble_code', '@regex ^(.*[-,]|)P2P([-,].*|)$');/* Non storm */INSERT INTO oms_mwm_mapping_checks (check_id, field_name, cond_str, negate)VALUES (33, 'rule_set', '@regex storm', 'Y');/* Transformar */INSERT INTO oms_mwm_mapping_checks (check_id, field_name, cond_str)VALUES (35, 'dev_cls_name', '@inheritFrom transformer');

3.

Assign each of the four conditions (rules checks) to the mapping rule in the OMS_MWM_MAPPING_RULE_CHECKS table:

/* ROUTXFMWD */INSERT INTO oms_mwm_mapping_rule_checks (rule_id, check_id)VALUES (15, 1);INSERT INTO oms_mwm_mapping_rule_checks (rule_id, check_id)VALUES (15, 35);INSERT INTO oms_mwm_mapping_rule_checks (rule_id, check_id)VALUES (15, 15);INSERT INTO oms_mwm_mapping_rule_checks (rule_id, check_id)VALUES (15, 33);

Use the same process described above to configure data mapping for notification types (alarmType) and activity priority values (priority).

High-Level Messages

The Oracle Utilities Network Management System Mobile Workforce Management Adapter responds several commands sent as high-level messages.

High-level message can be sent using Action command-line utility.

Action any.publisher ejb client NMS-MWM command <message>

Following messages are supported:

•

RELOAD - Forces adapter to reload configuration and then initiates synchronization sequence.

•

RESYNC - Initiates synchronization sequence.

•

STOP - Temporarily stops the adapter.

•

START - Re-starts previously stopped adapter.

Troubleshooting

The Oracle Utilities Network Management System Mobile Workforce Management Adapter uses Apache log4j library to log error, warning and debug messages. To enable debug output following lines should be added to the log4j configuration file used by the WebLogic Server where the adapter is deployed.

<logger name="com.splwg.oms.interfaces.mwm"> <level value="DEBUG"/></logger><logger name="MOBILE"> <level value="DEBUG"/></logger><logger name="MOBILE_WS"> <level value="DEBUG"/></logger><logger name="MOBILE_DB"> <level value="DEBUG"/></logger><logger name="SOAP"> <level value="DEBUG"/></logger>

For additional details about configuring log4j logging in WebLogic Server, see the Configure Log4j Logging Services section in the Oracle Utilities Network Management System Installation Guide.

Authentication

In order to invoke Oracle Utilities Network Management System web services, the caller needs to be authenticated using valid Oracle Utilities Network Management System credentials. HTTP Basic Authentication protocol is used for authentication. Since HTTP Basic Authentication does not encrypt credentials, the HTTPS transport should be used.

Trouble Management Web Service

Trouble Management web service provide access to the subset of the trouble management functionality available in the Oracle Utilities Network Management System.

Port TroubleServiceSOAP

Location: https://<nms host>:<nms port>/nms/trouble

Protocol: SOAP

Default Style: document

Transport Protocol: SOAP over HTTP

Target Namespace: http://oms.splwg.com/ws/trouble/

Operations

CreateEvent

Creates new event in NMS.

Operation Type: Request-response. The endpoint receives Sa message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/trouble/CreateEvent

Input: CreateEventRequest (soap:body, use = literal)

parameters type CreateEvent

status type jobConditionStatus - type string with restriction - enum { 'NO_OUTAGE', 'PROBABLE_SERVICE_OUTAGE', 'PROBABLE_DEVICE_OUTAGE', 'REAL_SERVICE_OUTAGE', 'REAL_DEVICE_OUTAGE', 'RESERVED_5', 'RESERVED_6', 'NON_OUTAGE', 'CRITICAL_MEET', 'FUTURE_MEET', 'CONFIRMED_SERVICE_OUTAGE', 'CONFIRMED_SECONDARY_OUTAGE', 'ADDITIONAL_ALARM', 'PROBABLE_MOMENTARY_OUTAGE', 'REAL_MOMENTARY_OUTAGE', 'PLANNED_OUTAGE', 'NON_ELECTRIC_EVENT', 'SWITCHING_JOB', 'FAULT_CURRENT_EVENT', 'CVR_JOB' }

Condition status

device - optional; type handle

Device handle

deviceAlias - optional; type string

Device alias. If device handle is not provided device alias is used to determine it

phases - optional; type phaseCode

Affected device phases (default: all phases)

groupable - optional; type boolean

Groupable flag (default: non-groupable)

beginTime - optional; type dateTime

Event begin time (default: current time)

restoreTime - optional; type dateTime

Event restoration time (only applicable to momentary outages)

priority - optional; type int

Event priority

appliedRule - optional; type int

Initial applied rule value. When creating real momentary outage value 3 (SRS_SCADA) indicates that this is SCADA-reported event

accidental - optional; type int

0 - normal, 1 - accidental, 2 - planned

numMomentaries - optional; type int

Number of momentaries (only applicable to momentary outages)

description - optional; type string

Description text

dispatchGroup - optional; type string

Dispatch group

userCustOut - optional; type int

Number of customers affected by the created event. Populates USER_CUST_OUT field in the created event

ddsAlarm - optional; type handle

Handle of the DDS alarm (device operation) related to the event being created.

switchingPlan - optional; type handle

When creating SWITCHING_JOB event this element must be populated with the switching plan handle.

Output: CreateEventResponse (soap:body, use = literal)

parameters type CreateEventResponse

event type handle

Handle of the created event

Fault: TroubleServiceException (soap:fault, use = literal)

parameters type TroubleServiceFault

errors - unbounded; type Error

Trouble Service error

•

error type errorCode - type string with restriction - enum { 'ERROR' }

String representation of the error code

[a]

errorMessage type errorCode - type string with restriction - enum { 'ERROR' } [1]

Error code

[a]

eventIdx type int

Event index associated with the error

1

[a] bullets designate attributes.

Switching and Safety Web Service

Port SwmanServiceBeanPort

Location: https://<nms host>:<nms port>/ExternalSwmanServiceImpl/SwmanServiceBean

Protocol: SOAP

Default style: rpc

Transport protocol: SOAP over HTTP

Target Namespace: http://www.oracle.com/ugbu/nms

Operations

GetSafetyDocument

Retrieves safety document by handle.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

Input: GetSafetyDocument (soap:body, use = literal)

docHdl type handle

Safety document handle.

Output: GetSafetyDocumentResponse (soap:body, use = literal)

safetyDoc type SafetyDoc

Safety document

•

id - nillable; type long

Safety document identifier

•

externalId - optional; type normalizedString

Safety document external identifier

•

handle - nillable; type handle

Safety document handle

•

docType - nillable; type normalizedString

Safety document type

•

state - optional; type State

Real-time state

•

swSheet - optional; type handle

Switching sheet handle

•

deleted - optional; type boolean

Safety document deleted flag

•

version - optional; type long

Safety document version (used for optimistic locking)

•

extensions - optional; type ArrayOfExtensionField

Extension fields

•

steps - optional; type ArrayOfSwStep

Switching steps associated with this safety document

•

step - optional, unbounded; type SwStep

Switching step

•

cls - nillable; type long

Switching step class

•

id - nillable; type long

Switching step identifier

•

parentId - optional; type long

Parent step

•

groupNumber - optional; type long

Group number

•

device - optional; type handle

Handle of the main device associated with this switching step

•

deviceAlias - optional; type normalizedString

Alias of the main device associated with this switching step

•

controlZone - optional; type ControlZone

Switching step control zone

•

phases - optional; type phaseCode

Phases of the main device affected by this switching step

•

availablePhases - optional; type phaseCode

All phases of the main device associated with this switching step

•

secondaryDevice - optional; type handle

Handle of the secondary device associated with this switching step

•

groundNode - optional; type handle

Grounding node associated with this switching step

•

condition - optional; type handle

Condition associated with this switching step

•

state - optional; type State

Switching step real-time state

•

controlAction - optional; type ControlAction

Control Tool action

•

action - nillable; type normalizedString

•

switchingCode - optional; type normalizedString

•

attribute - optional; type long

[a]

cls - required; type normalizedString

[a]

idx - required; type normalizedString

[a]

key - required; type long

Switching step control action

•

revision - optional; type long

Switching step revision number

•

description - optional; type string

Description

•

comments - optional; type string

Comments

•

plannedOffset - optional; type duration

Planned offset

•

createTime - optional; type dateTime

Date/time when this step was created

•

createUser - optional; type normalizedString

User who created this step

•

updateTime - optional; type dateTime

Date/time when step was last updated

•

updateUser - optional; type normalizedString

User who made the latest update this step

•

instructTime - optional; type dateTime

Date/time when step was instructed

•

instructUser - optional; type normalizedString

User who instructed this step

•

executeTime - optional; type dateTime

Date/time when step was executed

•

executeUser - optional; type normalizedString

User who executed this step

•

executeOrder - optional; type long

Step execution order

•

operationOutcome - optional; type normalizedString

Operation outcome

•

undoOperationOutcome - optional; type normalizedString

Undo operation outcome

•

resultOfOperation - optional; type normalizedString

Result of operation

•

resultFeeders - optional; type normalizedString

Result feeders

•

lastResultOfOperation - optional; type normalizedString

Last result of operation

•

editedOperation - optional; type normalizedString

Edited operation

•

modelBuild - optional; type normalizedString

Step affected by model build

•

safetyDocId - optional; type long

Safety document id (for safety-related steps)

•

safetyDevStatus - optional; type normalizedString

Status of the device as it pertains to the associated safety document. This is used to keep track of a user's modifications to a safety document's device list. ADD - The device has been added as part of a viewer device selection. ADD_STEP - The device has been added as part of a switching sheet step association. COND_APPLIED - The condition has been applied and updated to the device in the device list. INCOMPLETE - The device is associated to a switching step where the condition has already been applied to the device. REMOVE - The device has been marked for removal and will be removed the next time the document transitions from the Unissued to Issued state. REMOVED - The device has been removed from the device list. These devices are filtered out of the device list.

•

safetyCondAdded - optional; type long

Safety document version number where this safety condition step was added

•

safetyCondRemoved - optional; type long

Safety document version number where this safety condition step was added

•

crews - optional; type ArrayOfCrewId

Crew ids

•

extensions - optional; type ArrayOfExtensionField

Extension fields

•

crews - optional; type ArrayOfSafetyCrew

Crew information associated with this safety document

•

crew - optional, unbounded; type SafetyCrew

Crew information associated with a safety document

•

crewId - optional; type normalizedString

Crew id

•

position - optional; type normalizedString

Position the crew is in with regards to the zone of protection

•

auditLog - optional; type ArrayOfAuditLogEntry

Audit log entries

•

log - optional, unbounded; type AuditLogEntry

Audit log entry

•

id - nillable; type long

Audit log entry identifier

•

entryType - optional; type normalizedString

Audit log entry type

•

userLog - optional; type string

User log

•

device - optional; type handle

Device handle

•

deviceAlias - optional; type normalizedString

Device alias

•

state - optional; type State

State

•

revision - optional; type long

Revision number

•

comment - optional; type string

Log comment

•

phases - optional; type phaseCode

Phases

•

crews - optional; type ArrayOfCrewId

Crew ids

Fault: OmsServiceException (soap:fault, use = literal)

fault type OmsServiceException

GetSafetyDocumentsForSheet

Retrieves all safety documents for a switching sheet.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

Input: GetSafetyDocumentsForSheet (soap:body, use = literal)

sheetHdl type handle

Switching sheet handle.

Output: GetSafetyDocumentsForSheetResponse (soap:body, use = literal)

safetyDocs type ArrayOfSafetyDoc

List of safety documents

•

safetyDoc - optional, unbounded; type SafetyDoc

Safety document (see GetSafetyDocument)

Fault: OmsServiceException (soap:fault, use = literal)

fault type OmsServiceException

GetSwitchingSheet

Retrieves switching sheet by handle.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

Input: GetSwitchingSheet (soap:body, use = literal)

sheetHdl type handle

Switching sheet handle

Output: GetSwitchingSheetResponse (soap:body, use = literal)

swSheet type SwSheet

Switching sheet

•

id - nillable; type long

Switching sheet identifier

•

handle - nillable; type handle

Switching sheet handle

•

externalId - optional; type normalizedString

Switching sheet external identifier

•

device - optional; type handle

Handle of the main device associated with this switching sheet

•

deviceAlias - optional; type normalizedString

Alias of the main device associated with this switching sheet

•

controlZone - optional; type ControlZone

Switching sheet control zone

•

owner - optional; type normalizedString

Switching sheet owner

•

revision - optional; type long

Switching sheet revision number

•

version - nillable; type long

Switching sheet version (used for optimistic locking)

•

checkedIn - optional; type normalizedString

Switching sheet is checked in

•

state - optional; type State

Real-time state

•

createTime - optional; type dateTime

Date/time when this sheet was created

•

createUser - optional; type normalizedString

User who created this sheet

•

updateTime - optional; type dateTime

Date/time when this sheet was last updated

•

updateUser - optional; type normalizedString

User who updated this sheet last

•

lockedTime - optional; type dateTime

Date/time when sheet was locked

•

lockedUser - optional; type normalizedString

User who locked this sheet

•

startTime - optional; type dateTime

Date/time when execution of this switching sheet is expected to start

•

finishTime - optional; type dateTime

Date/time when execution of this switching sheet is expected to finish

•

completedTime - optional; type dateTime

Completion date/time

•

reworkDescription - optional; type string

Rework description

•

reworkTime - optional; type dateTime

Rework date/time

•

defaultOffset - optional; type duration

Default offset

•

modelBuild - optional; type normalizedString

Switching sheet is affected by model build

•

extensions - optional; type ArrayOfExtensionField

Extension fields

•

steps - optional; type ArrayOfSwStep

Switching steps

•

step - optional, unbounded; type SwStep

Switching step

•

cls - nillable; type long

Switching step class

•

id - nillable; type long

Switching step identifier

•

parentId - optional; type long

Parent step

•

groupNumber - optional; type long

Group number

•

device - optional; type handle

Handle of the main device associated with this switching step

•

deviceAlias - optional; type normalizedString

Alias of the main device associated with this switching step

•

controlZone - optional; type ControlZone

Switching step control zone

•

phases - optional; type phaseCode

Phases of the main device affected by this switching step

•

availablePhases - optional; type phaseCode

All phases of the main device associated with this switching step

•

secondaryDevice - optional; type handle

Handle of the secondary device associated with this switching step

•

groundNode - optional; type handle

Grounding node associated with this switching step

•

condition - optional; type handle

Condition associated with this switching step

•

state - optional; type State

Switching step real-time state

•

controlAction - optional; type ControlAction

Control tool action

•

action - nillable; type normalizedString

•

switchingCode - optional; type normalizedString

•

attribute - optional; type long

[a]

cls - required; type normalizedString

[a]

idx - required; type normalizedString

[a]

key - required; type long

Switching step control action

•

revision - optional; type long

Switching step revision number

•

description - optional; type string

Description

•

comments - optional; type string

Comments

•

plannedOffset - optional; type duration

Planned offset

•

createTime - optional; type dateTime

Date/time when this step was created

•

createUser - optional; type normalizedString

User who created this step

•

updateTime - optional; type dateTime

Date/time when step was last updated

•

updateUser - optional; type normalizedString

User who made the latest update this step

•

instructTime - optional; type dateTime

Date/time when step was instructed

•

instructUser - optional; type normalizedString

User who instructed this step

•

executeTime - optional; type dateTime

Date/time when step was executed

•

executeUser - optional; type normalizedString

User who executed this step

•

executeOrder - optional; type long

Step execution order

•

operationOutcome - optional; type normalizedString

Operation outcome

•

undoOperationOutcome - optional; type normalizedString

Undo operation outcome

•

resultOfOperation - optional; type normalizedString

Result of operation

•

resultFeeders - optional; type normalizedString

Result feeders

•

lastResultOfOperation - optional; type normalizedString

Last result of operation

•

editedOperation - optional; type normalizedString

Edited operation

•

modelBuild - optional; type normalizedString

Step affected by model build

•

safetyDocId - optional; type long

Safety document id (for safety-related steps)

•

safetyDevStatus - optional; type normalizedString

Status of the device as it pertains to the associated safety document. This is used to keep track of a user's modifications to a safety document's device list. ADD - The device has been added as part of a viewer device selection. ADD_STEP - The device has been added as part of a switching sheet step association. COND_APPLIED - The condition has been applied and updated to the device in the device list. INCOMPLETE - The device is associated to a switching step where the condition has already been applied to the device. REMOVE - The device has been marked for removal and will be removed the next time the document transitions from the Unissued to Issued state. REMOVED - The device has been removed from the device list. These devices are filtered out of the device list.

•

safetyCondAdded - optional; type long

Safety document version number where this safety condition step was added

•

safetyCondRemoved - optional; type long

Safety document version number where this safety condition step was added

•

crews - optional; type ArrayOfCrewId

Crew ids

•

extensions - optional; type ArrayOfExtensionField

Extension fields

•

auditLog - optional; type ArrayOfAuditLogEntry

Audit log entries

•

log - optional, unbounded; type AuditLogEntry

Audit log entry

•

id - nillable; type long

Audit log entry identifier

•

entryType - optional; type normalizedString

Audit log entry type

•

userLog - optional; type string

User log

•

device - optional; type handle

Device handle

•

deviceAlias - optional; type normalizedString

Device alias

•

state - optional; type State

State

•

revision - optional; type long

Revision number

•

comment - optional; type string

Log comment

•

phases - optional; type phaseCode

Phases

•

crews - optional; type ArrayOfCrewId

Crew ids

•

standaloneSafetyDoc - optional; type SafetyDoc

Safety document (see GetSafetyDocument)

Fault: OmsServiceException (soap:fault, use = literal)

fault type OmsServiceException

createSwmanSheetFromExternalSystem

Creates new or updates an existing switching sheet.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

Input: createSwmanSheetFromExternalSystem (soap:body, use = literal)

dataString type string

XML representation of the switching sheet.

sheetHdl type handle

Switching sheet handle.

Output: createSwmanSheetFromExternalSystemResponse (soap:body, use = literal)

return type int

Return code.

sheetHdl type handle

Switching sheet handle.

Fault: OmsServiceException (soap:fault, use = literal)

fault type OmsServiceException

sheetStateTransition

Executes state transition on a switching sheet.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

Input: sheetStateTransition (soap:body, use = literal)

sheetHdl type handle

Switching sheet handle.

actionType type string

State transition action type.

actionName type string

State transition action name.

username type string

Username.

Output: sheetStateTransitionResponse (soap:body, use = literal)

Fault: OmsServiceException (soap:fault, use = literal)

fault type OmsServiceException

Damage Assessment Web Service

Oracle Utilities Network Management System Damage Assessment web service

Port DamageServiceSOAP

Location: https://<nms host>:<nms port>/nms/damage

Protocol: SOAP

Default style: document

Transport protocol: SOAP over HTTP

Target Namespace: http://oms.splwg.com/ws/damage/

Operations

CompleteDamageReport

Completes an existing damage report.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/CompleteDamageReport

Input: CompleteDamageReportRequest (soap:body, use = literal)

parameters type CompleteDamageReport

reportId type long

Damage report id

Output: CompleteDamageReportResponse (soap:body, use = literal)

parameters type CompleteDamageReportResponse

report type damageReport

Damage assessment report

•

id - optional; type long

Damage report unique identifier assigned by the server

•

externalId - optional; type string

External id of the damage assessment incident in NMS

•

eventIdx - optional; type int

Index of the event associated with this damage report

•

eventExternalId - optional; type string

External id of the event associated with this damage report

•

device - optional; type handle

[a]

cls - required; type short

[a]

index - required; type int

[a]

app - optional; type short

Handle of the affected device

•

deviceAlias - optional; type string

Alias of the affected device

•

feeder - optional; type string

Feeder name

•

gpsLocation - optional; type gpsLocation

GPS location

•

latitude type double

Latitude

•

longitude type double

Longitude

GPS location of the damage

•

zone - optional; type string

•

grid - optional; type string

•

location - optional; type string

•

section - optional; type string

•

city - optional; type string

•

address - optional; type string

Street address of the damage

•

phases - optional; type phaseCode - type string with restriction - enum { 'NONE', 'A', 'B', 'AB', 'C', 'AC', 'BC', 'ABC', 'N', 'AN', 'BN', 'ABN', 'CN', 'ACN', 'BCN', 'ABCN', 'Unknown' }

Affected phases

•

loadAffected - optional; type boolean

Is damage causing an outage

•

crew - optional; type crew

[a]

id - required; type string

NMS crew identifier (crew name)

[a]

mobileNumber - optional; type string

Crew's mobile (radio) number

Crew, who submitted this damage report

•

stateName - optional; type string

Damage report state (New, Assessed, etc.)

•

stateBitmask - optional; type int

Damage report state bitmask (New=0x1, Assessed=0x2, Complete=0x4, Obsolete=0x8)

•

active - optional; type boolean

•

reportTime - optional; type dateTime

•

lastModified - optional; type dateTime

•

version - optional; type long

Damage report version used for optimistic concurrency control

•

damageType - optional, unbounded; type reportDamageType

•

typeId type int

•

typeName - optional; type normalizedString

•

accessible - optional; type int

•

inaccessible - optional; type int

List of specific damage instances

•

damageComment - optional; type string

•

requiredPart - optional, unbounded; type reportDamagePart

•

quantity - optional; type int

•

partId type string

List of required parts/materials needed to address reported damage

•

requirePartsComment type string

•

crewType - optional, unbounded; type crewType

•

id type int

Crew type id

•

name type string

Crew type name

List of crew types needed to address reported damage

•

miscField1 - optional; type string

•

miscField2 - optional; type string

•

miscField3 - optional; type string

•

miscField4 - optional; type string

•

miscField5 - optional; type string

•

miscField6 - optional; type string

•

miscField7 - optional; type string

•

miscField8 - optional; type string

•

miscField9 - optional; type string

•

miscField10 - optional; type string

•

attachment - optional, unbounded; type attachment

List of damage report attachments. Actual attachment data is not included.

•

data - optional; type base64Binary

Attachment data

•

description - optional; type string

Description of the attachment

[a]

id - required; type string

Attachment id (file name)

[a]

reportId - required; type long

Damage report id

[a]

uri - optional; type anyURI

Link to the attachment. Can be used instead of passing attachment data in the message

[a]

contentType - optional; type string

MIME content type

[a]

lastModified - optional; type dateTime

Last modification timestamp

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

•

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

[a]

code type int

Error code

[a]

reportId type long

Damage report id associated with the error

DeleteAttachments

Deletes one or more damage report attachments.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/DeleteAttachments

Input: DeleteAttachmentsRequest (soap:body, use = literal)

parameters type DeleteAttachments

attachmentId - unbounded; type attachmentId

Identifier for damage report attachment

•

id type string

Attachment id (file name). If empty then all attachments for this damage report are included.

•

reportId type long

Damage report id

Output: DeleteAttachmentsResponse (soap:body, use = literal)

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

•

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

[a]

code type int

Error code

[a]

reportId type long

Damage report id associated with the error

GetAttachments

Retrieves damage report attachments.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/GetAttachments

Input: GetAttachmentsRequest (soap:body, use = literal)

parameters type GetAttachments

attachmentId - unbounded; type attachmentId

Identifier for damage report attachment

•

id type string

Attachment id (file name). If empty then all attachments for this damage report are included.

•

reportId type long

Damage report id

Output: GetAttachmentsResponse (soap:body, use = literal)

parameters type GetAttachmentsResponse

result - optional, unbounded; type attachment

[a]

data - optional; type base64Binary

Attachment data

[a]

description - optional; type string

Description of the attachment

•

id - required; type string

Attachment id (file name)

•

reportId - required; type long

Damage report id

•

uri - optional; type anyURI

Link to the attachment. Can be used instead of passing attachment data in the message

•

contentType - optional; type string

MIME content type

•

lastModified - optional; type dateTime

Last modification timestamp

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

•

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

GetCrewTypes

Returns all crew types configured in NMS.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/GetCrewTypes

Input: GetCrewTypesRequest (soap:body, use = literal)

parameters type GetCrewTypes

Output: GetCrewTypesResponse (soap:body, use = literal)

parameters type GetCrewTypesResponse

result - optional, unbounded; type crewType

•

id type int

Crew type id

•

name type string

Crew type name

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

GetDamageReportById

Returns damage report for given report id.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/GetDamageReportById

Input: GetDamageReportByIdRequest (soap:body, use = literal)

parameters type GetDamageReportById

reportId type long

Damage report id

Output: GetDamageReportByIdResponse (soap:body, use = literal)

parameters type GetDamageReportByIdResponse

report type damageReport

Damage assessment report (see CompleteDamageReport)

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

GetDamageReportsByHandle

Returns all damage reports for given event or device handle.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/GetDamageReportsByHandle

Input: GetDamageReportsByHandleRequest (soap:body, use = literal)

parameters type GetDamageReportsByHandle

handle type handle

•

cls - required; type short

•

index - required; type int

•

app - optional; type short

Event or device handle

Output: GetDamageReportsByHandleResponse (soap:body, use = literal)

parameters type GetDamageReportsByHandleResponse

report - optional, unbounded; type damageReport

Damage assessment report (see CompleteDamageReport)

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

GetDamageTypes

Returns all damage types configured in NMS.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/GetDamageTypes

Input: GetDamageTypesRequest (soap:body, use = literal)

parameters type GetDamageTypes

Output: GetDamageTypesResponse (soap:body, use = literal)

parameters type GetDamageTypesResponse

result - optional, unbounded; type damageType

•

id type int

•

name type string

•

source - optional; type string

•

repairMinutes type int

•

inaccessibleRepairMinutes type int

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

GetRequiredParts

Returns all required parts/materials configured in NMS.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/GetRequiredParts

Input: GetRequiredPartsRequest (soap:body, use = literal)

parameters type GetRequiredParts

Output: GetRequiredPartsResponse (soap:body, use = literal)

parameters type GetRequiredPartsResponse

result - optional, unbounded; type requiredPart

•

id type string

•

name type string

•

source - optional; type string

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

NewDamageReport

Returns populated damage report for given event or device. This operation does not create new damage report in NMS.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/NewDamageReport

Input: NewDamageReportRequest (soap:body, use = literal)

parameters type NewDamageReport

handle - optional; type handle

•

cls - required; type short

•

index - required; type int

•

app - optional; type short

Event or device handle

•

deviceAlias - optional; type string

Device alias (only used if handle is not provided)

•

externalId - optional; type string

Event's external id (only used if handle is not provided)

Output: NewDamageReportResponse (soap:body, use = literal)

parameters type NewDamageReportResponse

report type damageReport

Damage assessment report (see CompleteDamageReport)

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

SaveAttachments

Creates new or updates existing damage report attachments.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/SaveAttachments

Input: SaveAttachmentsRequest (soap:body, use = literal)

parameters type SaveAttachments

attachment - unbounded; type attachment

•

data - optional; type base64Binary

Attachment data

•

description - optional; type string

Description of the attachment

id - required; type string

Attachment id (file name)

reportId - required; type long

Damage report id

uri - optional; type anyURI

Link to the attachment. Can be used instead of passing attachment data in the message

contentType - optional; type string

MIME content type

lastModified - optional; type dateTime

Last modification timestamp

Output: SaveAttachmentsResponse (soap:body, use = literal)

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

SaveDamageReport

Creates new or updates existing damage report. This operation cannot be used to complete an existing damage report.

Operation Type: Request-response. The endpoint receives a message, and sends a correlated message.

SOAP Action: http://oms.splwg.com/ws/damage/SaveDamageReport

Input: SaveDamageReportRequest (soap:body, use = literal)

parameters type SaveDamageReport

report type damageReport

Damage assessment report (see CompleteDamageReport)

action - optional; type string

Action to trigger state transition

Output: SaveDamageReportResponse (soap:body, use = literal)

parameters type SaveDamageReportResponse

report type damageReport

Damage assessment report (see CompleteDamageReport)

Fault: DamageServiceException (soap:fault, use = literal)

parameters type DamageServiceFault

errors - unbounded; type Error

Damage Service error

[a]

error type errorCode - type string with restriction - enum { 'CreateFailed', 'CompletedEvent', 'UnknownEvent', 'BadEventType', 'LoadAffectedSetForNonOutage', 'DatabaseError', 'UnknownReportId', 'AlreadyCompleted', 'StaleData', 'IncidentCreateFailed', 'InvalidCrewType', 'InvalidDamageType', 'InvalidRequiredPart', 'NeedEventOrDevice', 'NeedAddress', 'NeedCrewId', 'MoveFailed', 'AttachmentTooBig', 'AttachmentSaveError', 'AttachmentNotFound', 'Other' }

String representation of the error code

•

code type int

Error code

•

reportId type long

Damage report id associated with the error

This chapter includes the following topics:

•

Introduction

•

Installation

•

Database Schema

•

Supported Data Flows

•

Software Configuration

•

High-Level Messages

•

Troubleshooting

This chapter includes the following topics:

•

Authentication

•

Trouble Management Web Service

•

Switching and Safety Web Service

•

Damage Assessment Web Service