Oracle Utilities Smart Grid Gateway MV90 Adapter for Itron

Administrative User Guide

Release 2.2.0.1

E80273-02

April 2017

Documentation build: 4.10.2017 11:44:15 [D5_1491849855000]

Copyright © 2011, 2017, 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, then 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 about 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 unless otherwise set forth in an applicable agreement between you and Oracle. 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, except as set forth in an applicable agreement between you and Oracle.

Oracle Utilities Smart Grid Gateway Adapter for MV90 Adapter for Itron

This section documents the administrative functions for the Oracle Utilities Smart Grid Gateway Adapter for MV90 Adapter for Itron.

Next in This Section

- MV90 Adapter Overview

- MV90 Adapter Processing

- Configuring a MV90 Head-End System

- Configuring MV90 Extendable Lookups

MV90 Adapter Overview

The Oracle Utilities Smart Grid Gateway MV-90 Adapter for Itron the parsing, transformation, and loading of MV-90 binary format measurement data for use in Oracle Utilities applications. The following table describes the attributes of the adapter:

Attribute

Details

Currently Supported Version

SGG supports the .mv9 binary, mainframe data format.

Protocol

Binary file format.

Market(s)

Worldwide, but largely USA.

Architecture

AMR

The adapter uses Oracle Service Bus (OSB) to facilitate communication between Oracle Utilities Smart Grid Gateway and MV-90.

The following functionality is included:

Measurement Data Loading - data parsing and transformation from MV-90 binary format into the Oracle Utilities Service and Measurement Data Foundation unified format.

Measurement Data Processing - configurable mapping for MV-90 status codes to Oracle Utilities Service and Measurement Data Foundation standard values, along with configurable device event creation based on MV-90 status codes.

MV90 Adapter Processing

This section provides details concerning the OSB processing and OUAF objects supplied as part of the base package. This information illustrates how the base package objects were designed, and can serve as the basis for any customizations you create as part of your implementation.

Next in This Section

- Initial Measurement Data Loading

Initial Measurement Data Loading

The initial measurement data load and subsequent device event processing use OSB to poll for, parse, and transform the head-payloads into the Oracle Utilities Smart Grid Gateway service format. Payloads contain measurements in a head-end specific format OSB then places each service call into a JMS queue within the Oracle Utilities applications. The JMS client consumes the entries and invokes the respective services in parallel then a service creates initial measurements with data in a common format with head-end-specific processing as needed.

Next in This Section

- Initial Measurements

- Base Package Business Objects

Initial Measurements

The usage data exported from the AMI head-end system as a file in MV-90 format is loaded into Oracle Utilities as Initial measurement data. The following OSB projects, delivered in the base product, help manage the usage processing:

1. SGG-D5-USAGE-BASE contains components responsible for the actual processing of incoming data. It should not be modified during configuration. This project can be upgraded without affecting the customization and environment settings added to the SGG-D5-USAGE-CM project.

2. SGG-D5-USAGE-CM allows for customization and simplifies future upgrades.

The runtime configuration settings for the SGG-D5-USAGE-CM project are stored in the xquery file EnvironmentSettings.xq. You can use this file to adjust initial measurement data processing. For example, if you want to load raw data you would specify “true” for the content of the populateRawIMD element.

The following table describes the elements included in the EnvironmentSettings.xq file:

Element

Description

Valid Values

populateRawIMD

Determines if the initial measurement data is populated as raw data.

true

false

callPreProcessing

Determines if the preprocessing proxy service is called.

true

false

callPostProcessing

Determines if the postprocessing proxy service is called.

true

false

destinationRootElementInterval

Holds the name of inbound web service for the interval IMD seeder.

publishServices/service

Specifies the name of the business service within the OSB project used to publish data for external systems (such as Oracle DataRaker).

filterUsage

Determines if usage should be filtered.

true

false

usePhysicalChannel

Optional value. Determines whether the physical channel ID is passed to the IMD seeder to create the measuring component identifier number. If this is set to false, the MV90 LOGCHAN field is used.

true

false (default)

fieldForDvcIdN

Optional value. Specifies which field is used as the value for the device ID.

DC_RECID

DC_CUSTID

DC_METERID (default)

MV90ScalarChannelSuffix

Optional value. Holds a suffix value to be added to the measuring component identifier number when a scalar IMD is created for register reads. Default value is “_S”

processMV90ScalarData

Optional value. Determines if register reads are processed.

true

false (default)

Publishing Initial Measurement Data

The MV90 adapter can be configured to publish initial measurement data for use in Oracle DataRaker or other external systems. Publishing data is enabled by referencing a publisher business service in the publishServices/service element in the EnvironmentSettings.xq file as follows:

<publishServices>
<service>[publisherBusinessService]</service>
</publishServices>

Publishing measurement data to Oracle DataRaker is supported by the following components provided with the SGG-D5-USAGE-CM OSB project:

- The DataRakerBusinessService business service is used to publish data to a specified JMS queue (defined as an Endpoint URI), from which the external system can receive the data. This is the business service that should be specified in the EnvironmentSettings.xq file.

- The DataRakerServiceAccount service account is used to define and maintain the user name and password needed to access the JMS queue defined in the DataRakerBusinessService business service.

Initial measurement data is published in the “native” initial measurement data format (the format of the initial measurement seeder business object).

Filtering Usage

The MV90 adapter can be configured to filter initial measurement data passed into Oracle Utilities Smart Grid Gateway and Meter Data Management. Filtering data is enabled by setting the <filterUsage> element in the EnvironmentSettings.xq file to “true” as follows:

<filterUsage>true</filterUsage>

When filtering is enabled, only measurements whose <externalUOM> matches one of the values defined in the MV90 UOM Code to Standard UOM Mapping extendable lookup (D5-UOMtoStdUOMCodeMapLookup) are passed into the system for processing.

Processing Large Input Files

In some environments, the OSB project may begin processing a large input file before it has been completely copied to the input directory. To prevent this, configure the MinimumAge property in the “InboundProxyService” proxy service for the SGG-D5-USAGE-CM project. The MinimumAge property specifies the minimum age of files to be retrieved, based on the last modified time stamp. This enables large files to be completely copied to the input directory before they are retrieved for processing.

Prioritized Initial Measurement Processing

Processing of initial measurements can be prioritized by setting the Execution Method flag set to “Real Time” (D1RT), in which case the measurements are processed in real time rather than via batch processing.

See Initial Measurement Data Prioritization in the Oracle Utilities Meter Data Management / Smart Grid Gateway Business User Guide for more information.

Initial Measurement Data Load with Register Reads
In the MV90 format, measurement data can include interval data as well as register reads that can be used to create scalar measurements. For information on configuring the adapter for loading scalar data based on register reads, see Override Processing Methods for Scalar Initial Measurement Data.

Base Package Business Objects

The MV-90 Adapter for Itron base package includes the following initial measurement business objects:

Business Object Name

Description

D5-InitialLoadIMDInterval

MV-90 Initial Load IMD

D5-InitialLoadIMDScalar

MV90 - Initial Load IMD - Scalar

Configuring a MV90 Head-End System

This section outlines the configuration required for the Oracle Utilities Smart Grid Gateway MV-90 Adapter for Itron to receive usage from an MV-90 system.

Next in This Section

- Inbound Web Services

- External System

- Service Provider

- Processing Methods

Inbound Web Services

Inbound web services define the details of how messages are received from an external system, including incoming usage.

The following inbound web services must be configured in your system. If these are not present in your configuration, add them. Refer to the Oracle Utilities Application Framework documentation for more information about creating inbound web services.

Inbound Web Service Name

Description

D1-InitialLoadIMD

IMD Seeder

D1-PayloadErrorNotif

Payload Error Notification

D1-PayloadStatistics

Payload Statistics

D1-PayloadSummary

Payload Summary

Note: The following apply to all of the above inbound web services:

Message Options

- Trace: No

- Debug: No

- Active: Yes

Operations

- Operation Name: Same as web service name

- Schema Type: Business Object

- Schema Name: Applicable business object code

- Transaction Type: Add

External System

External systems represent external applications with which the Smart Grid Gateway will exchange messages or data. In the case of the Smart Grid Gateway adapters, external systems represent the head-end systems with which the adapters communicate.

An external system that represents the MV-90 system must be present in your system. If this is not present in your configuration, add it. Refer to the Oracle Utilities Application Framework documentation for more information about creating external systems.

External System - MV-90:

External System: MV90

Description: MV90 - Mainframe File Format

Service Provider

Service providers represent external entities that serve various roles relative to the application, including head-end systems, billing systems to which the application sends bill determinant data, market participants in a deregulated environment, outage management systems that receive meter event data from the application, or other parties that require or provide information to the system. The head-end systems that collect and send measurement data and meter events to the application are defined as service providers.

A service provider that represents the MV-90 system must be present in your system. If this is not present in your configuration, add it. Refer to the Oracle Utilities Meter Data Management / Smart Grid Gateway documentation for more information about creating service providers.

Service Provider - MV-90:

- Service Provider: MV90

- Description: Head-End System for MV90

- External Reference ID: MV90

- External System: MV90 - Mainframe File Format

- Out Name/ID in Their System: MV90

- AMI Device ID Type: Serial Number

- AMI Measuring Component ID Type:

Processing Methods

Processing methods define the format or means by which a service provider receives and/or sends data from and/or to the application, including as bill determinants, usage data, or device events. Processing methods are also used to define how to create information internal to the application such as initial measurement data and device events.

The following types of processing methods must be configured for the MV90 service provider. Refer to the Oracle Utilities Meter Data Management / Smart Grid Gateway documentation for more information about configuring processing methods.

Initial Measurement Creation
Initial measurement creation processing methods define the business objects used to create initial measurements. The IMD Seeder inbound web service uses this processing method to determine which type of initial measurement business object to instantiate when receiving usage from the MV-90 system.

Override Processing Methods for Scalar Initial Measurement Data

In the MV-90 format, meter read start and stop values can represent either a calculated read based on the interval data that is included in the MV90 data, or a register read that has been logged using a separate channel. When the values represent a register read the application can create a second file for the scalar initial measurements. The creation of a scalar initial measurement file is triggered by the Register Type flag, DC_REGTYPE, in the MV-90 data and the processMV90ScalarData variable in the EnvironmentSettings.xq file. The following register read values are valid for the DC_REGTYPE field:

Value

Description

V

Visual energy readings

D

Visual demand and energy readings

E

Encoder register readings (energy only).

B

Both encoder and visual energy readings.

C

Calculate stop meter readings from the encoder base reading

In order to configure your adapter to create scalar initial measurements based on register reads, first define new measuring component types and register measuring components. Then use the new measuring component types to specify override processing methods on the Initial Measurement Creation processing method for your service provider.

Measuring Component Types for Scalar Reads: To create initial measurement data for register reads, first create new measuring component types to represent the registers. These will be used to create measuring components for scalar reads.

Example Measuring Component Type

- Measuring Component Type: MV90_SCALAR_REG

- Description: MV90 Scalar Register

- Measuring Component Business Object: Register

- Measurement Business Object: Measurement

- Service Type: Electric Service

- Allow Negative Consumption: Allowed

- Consumptive/Subtractive: Subtractive

- Read Method: Automatic Read

Other attributes such as Value Identifiers, VEE Groups, and so on, should be defined based on requirements

Register Measuring Components for Scalar Reads: Use the new measuring component types to create measuring components for the scalar measurements created by the register read process. You must create a corresponding register measuring component for each interval channel for which you will receive scalar reads. The channel number for the registers must be based on the channel numbers of the corresponding interval channels, plus the suffix defined in the “MV90ScalarChannelSuffix” environment setting. The default value for this setting is “_S”. These registers must also be added to the device configuration used by the interval channels (in other words, both measuring components - interval and scalar - must be on the same device). The following table shows examples of these values for the measuring components:

Device Type/Serial Number

MV-90 Interval Channel Number

MV-90 Scalar Register Channel Number

MV90 Electric/00001

1

1_S

MV90 Electric/00002

1

1_S

MV90 Electric/00003

1

1_S

Override Processing Methods for MV-90 Service Provider: Add an override processing method to the Initial Measurement Creation processing method for the MV90 service provider for each register measuring component type. The business object for each override processing method should be “D5-InitialLoadIMDScalar”. The following tables shows examples of the override processing methods:

Measuring Component Type

Business Object

MV90 Scalar Register

D5-InitialLoadIMDScalar

Measuring Component Type 2

D5-InitialLoadIMDScalar

Measuring Component Type n

D5-InitialLoadIMDScalar

Device Event Mapping
Device event mapping processing methods define how head-end-specific device events are mapped to standard device event names. The Device Event Seeder inbound web service uses this processing method to determine which type of device event business object to instantiate when creating device events based on interval status codes received with usage from the MV-90 system.

UOM Translation
UOM translation processing methods define how head-end-specific unit of measure (UOM) codes are mapped to standard UOM codes. This processing method is used to determine how to map MV90 UOM codes to standard UOM codes when receiving usage from the MV-90 system.

Configuring MV90 Extendable Lookups

This section outlines some of the extendable lookups that must be configured for use with the MV-90 Adapter for Itron. Refer to the Oracle Utilities Application Framework documentation for more information about working with extendable lookups.

Interval Status Code to Event Mapping

The MV-90 adapter for does not accept device events from an MV-90 system, but can create device events based on specific interval status codes in an incoming usage reading. The MV-90 Interval Status Code to Event Mapping extendable lookup is used to determine which type of device event business object to instantiate when creating device events based on interval status codes received with usage from the MV-90 system.

Each value defined for the Interval Status Code to Event Mapping extendable lookup should include the following:

- MV90 Interval Status: The interval status code used by the MV-90 system

- Description: A description of the MV-90 interval status code

- Event Duration Mode: The duration type for the event. Can be either “Individual” or “Continuous” (used for events with a duration, such as an outage).

- Device Event Type: The Device Event Type for the device event created for this interval status code. For status codes with an Event Duration Mode or “Continuous” this is the start event, or the first of the paired events created for this status code.

- End Event Type: The Device Event Type for the “end” device event created for this interval status code. For status codes with an Event Duration Mode or “Continuous” this is the start event, or the last of the paired events created for this status code.

Example: The MV-90 “Low Voltage” status code could be configured to create a “Low Voltage” device event as follows:

- MV90 Interval Status: <MV-90 interval status code for low voltage>

- Description: Low Voltage detected for meter

- Event Duration Mode: Individual

- Device Event Type: Low Voltage

- End Event Type: N/A

Example: The MV-90 “Power Outage” status code could be configured to create a “Last Gasp” device event, and a “Power Restoration” event as follows:

- MV90 Interval Status: <MV-90 interval status code for outage>

- Description: Outage

- Event Duration Mode: Continuous

- Device Event Type: Last Gasp

- End Event Type: Power Restoration

MV90 UOM Code to Standard UOM Code Mapping

Usage received from the MV-90 system may use utility-specific unit of measures (UOMs). These custom UOMs must be mapped to standard UOM codes. The MV90 UOM Code to Standard UOM Code Mapping extendable lookup is used to determine how to map MV90 UOM codes to standard UOM codes when receiving usage from the MV-90 system.

Each value defined for the MV90 UOM Code to Standard UOM Code Mapping extendable lookup should include the following:

- Head-End Unit of Measure: The unit of measure code used by the MV-90 system

- Unit of Measure: The unit of measure defined in the system.

- Description: A description of the unit of measure code.

Other Extendable Lookups

Business Object Name

Description

D5 - ChanelStatusCodeLookup

MV-90 Channel Status Code Lookup

D5-IntStsCdToCndMapPrLookup

Condition Mapping with Priority