Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks

Configuration Guide

Release 2.1.0 Service Pack 2

E48616-02

April 2014

Oracle Utilities Smart Grid Gateway adapter for Silver Spring Configuration Guide

E48616-02

Copyright © 2012, 2014 Oracle and/or its affiliates. All rights reserved.

Primary Author: TUGBU Documentation

Contributing Author: TUGBU Documentation

Contributor: TUGBU Documentation

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.

Overview

This chapter provides an overview of this configuration guide and an introduction to the Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks, including the following:

•

What Is This Book?

•

Other Documentation

•

Oracle Utilities Application Framework Configuration Tools

What Is This Book?

This guide describes how to configure the Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks. It is intended for implementers and system administrators responsible for configuration and initial setup of the application.

The Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks is based on the Oracle Utilities Application Framework (OUAF). For information about using and configuring basic Framework functions, see the Oracle Utilities Application Framework documentation. This guide only covers configuration of functions specific to the Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks.

The body of this guide presents conceptual information to help you understand how the system works as well as how the various configuration options affect system functionality. Once you have an understanding of the system's capabilities, you can plan your data setup and design any customizations you want to implement.

When you are ready to implement your design, use Chapter 2 : General Configuration to guide you through the setup process of admin data. This section lists each object that can be configured, defines any prerequisites for configuration.

This guide includes the following chapters:

•

Chapter 1 : Overview (this chapter) provides an overview of the Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks architecture and of the configuration tools and process used in implementing the product.

•

Chapter 2 : General Configuration provides an overview of some general configuration options used by the Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks.

Other Documentation

This section describes other documentation provided with the Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks.

Installation Documentation

Installation documentation describes the steps involved in the installation and initial set up of the system, and includes the following documents:

•

Oracle Utilities Smart Grid Gateway Quick Install Guide

•

Oracle Utilities Smart Grid Gateway DBA Guide

•

Oracle Utilities Smart Grid Gateway Installation Guide

User Documentation

User documentation provides conceptual information and procedures related to working with the various objects used in the system, and includes the following documents:

•

Oracle Utilities Application Framework Business Process Guide

•

Oracle Utilities Application Framework Administration Guide

•

Oracle Utilities Service and Measurement Data Foundation User’s Guide

•

Oracle Utilities Smart Grid Gateway User’s Guide

Supplemental Documentation

Supplemental documentation provides technical information related to system administration tasks and include the following documents:

•

Oracle Utilities Smart Grid Gateway Server Administration Guide

•

Oracle Utilities Smart Grid Gateway Batch Server Administration Guide

•

Oracle Utilities Smart Grid Gateway Configuration Guide

The Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks uses Oracle Service Bus (OSB) and Oracle Business Process Execution Language (BPEL) as middleware components. These tools are part of the Oracle SOA Suite. See the Oracle SOA Suite Documentation library (http://www.oracle.com/technetwork/middleware/soasuite/documentation/index.html) for more information about using these tools.

Embedded Help

Oracle Utilities Smart Grid Gateway, like all Oracle Utilities Application Framework applications, provides extensive internal documentation. For example, detailed descriptions of system objects are included in the objects' maintenance portals. The lifecycle of each business object is described on the Lifecycle tab and depicted in flow diagrams on the Summary tab. This information is extremely useful for implementers and system administrators.

Embedded help is provided for all non-obvious fields in most portals and zones. If a field has associated help text, a ? icon appears next to the field when the zone is displayed.

Online Help

Oracle Utilities Smart Grid Gateway also includes context-sensitive help for all the user interface screens users will typically work with as they use the system. Online help contains conceptual information and procedures related to working with the various objects used in the system.

The online help is divided into the following three sections:

•

Oracle Utilities Application Framework: Describes the features and functions of the application framework (F1)

•

Oracle Utilities Service and Measurement Data Foundation: Describes the features and functions provided in the Service and Measurement Data Foundation (D1)

•

Oracle Utilities Smart Grid Gateway: Describes the features and functions provided in the smart grid gateway application (D7)

Oracle Utilities Application Framework Configuration Tools

Please refer to the general configuration guide for information on the Oracle Utilities Application Framework (OUAF) configuration tools that can be used to create and customize system entities, such as business objects, portals, zones, and UI maps. Refer to the Oracle Utilities Application Framework configuration tools documentation for instructions on using tools such as:

•

Configuration Process Overview

•

Data Areas

•

Algorithms

•

Entity Naming Conventions

This configuration guide does not duplicate the concepts and procedures presented in the Oracle Utilities Application Framework configuration tools documentation; rather, it will identify the specific objects used by the Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks that can be configured and customized using the configuration tools, as well as application parameters and objects that can be managed within the application components themselves.

This guide assumes that all individuals responsible for system configuration and implementation will be familiar with the Oracle Utilities Application Framework and will have completed training on the Oracle Utilities Application Framework Configuration Tools.

General Configuration

This chapter provides details on the components and configurations required for the Smart Grid Gateway adapter for Silver Spring Networks including the following:

•

Understanding the Adapter

•

Understanding the Adapter Processing

•

Configuring a Silver Spring Networks Head-End System

•

Configuring Silver Spring Networks Extendable Lookups

•

Extending the Adapter for Silver Spring Networks

•

The Test Harness

Understanding the Adapter

The Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks supports communication with the Silver Spring Networks UtilityIQ application, including measurement data and device event loading, and command messaging in support of commissioning, connect, disconnect, decommissioning, status check, and on-demand read.The following table describes the attributes of the adapter:

Attribute

Details

Currently Supported Versions

UtilityIQ Versions 4.4 through 4.8

Protocol

Proprietary

Market(s)

Worldwide

Architecture

RF WAN (mesh) based on Access Points

The adapter uses Oracle Service Bus (OSB) and Oracle Business Process Execution Language (BPEL) to facilitate communication between Oracle Utilities Smart Grid Gateway and the Silver Spring Networks UtilityIQ application.

The following functionality is included:

Measurement Data and Device Event Loading - data parsing and transformation via Oracle Service Bus from Silver Spring Networks format into the Oracle Utilities Service and Measurement Data Foundation unified format for measurement data and device events.

Measurement Data and Device Event Processing - configurable mapping for Silver Spring Networks status codes and device event names to Oracle Utilities Service and Measurement Data Foundation standard values.

Smart Meter Command Processing - sending/receiving messages to/from the Silver Spring Networks application to initiate smart meter commands from Oracle Utilities Smart Grid Gateway. The Silver Spring Networks adapter supports the following types of commands and communications:

•

Meter Commissioning - business objects and BPEL processes to support issuing meter commissioning commands.

•

Remote Connect - business objects and BPEL processes to support issuing remote connect commands.

•

Remote Disconnect - business objects and BPEL processes to support issuing remote disconnect commands

•

Meter Decommissioning - business objects and BPEL processes to support issuing meter decommissioning commands.

•

On-Demand Read - business objects and BPEL processes to support issuing on-demand read commands.

Understanding the Adapter Processing

This section provides details concerning the OSB processing, BPEL Processes, 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.

This section includes:

•

Initial Measurement Data Load and Device Events

•

Device Communication

Initial Measurement Data Load and Device Events

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 and meter events in some 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. A second service creates device events with data in a common format.

Initial Measurement

The usage data exported from the AMI head-end system as a file in Silver Spring Networks XML 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-D7-SSNXML-BASE contains components responsible for "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 SGG-D7-SSNXML-CM.

2.

SGG-D7-SSNXML-CM allows for customization and simplifies future upgrades.

The runtime configuration settings for the SGG-D7-SSNXML-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

populateRaw

Determines if the initial measurement data is populated as raw data. Valid values are:

•

true

•

false

callPreProcessing

Determines if the preprocessing proxy service is called. Valid values are:

•

true

•

false

callPostProcessing

Determines if the postprocessing proxy service is called. Valid values are:

•

true

•

false

destinationRootElementInterval

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

destinationRootElementScalar

Holds the name of XAI inbound service for the scalar IMD seeder. In most cases it is the same as destinationRootElementInterval.

destinationRootElementEvent

Holds the name of XAI inbound service for the Device Event seeder.

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-D7-SSNXML-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.

See Working with Adapter OSB Projects in the Oracle Utilities Smart Grid Gateway Configuration Guide for more information about setting the MinimumAge property.

Device Events

The device event data exported from the head-end system as a file in Silver Spring Networks CSV format is loaded into Oracle Utilities as a Device Event. One of your configuration tasks is to customize the device events processing.

The required functionality is delivered in the base product as two OSB projects:

1.

SGG-D7-CSV-BASE contains components responsible for "actual" processing of incoming data. It can be upgraded in future without affecting the customization and environment settings that done in SGG-D7-CSV-CM project.

2.

SGG-D7-CSV-CM allows the customization and simplifies the future upgrades.

Base Package Business Objects

The Silver Spring Networks adapter base package includes the following initial measurement and device event business objects:

Business Object Name

Description

D7-InitialLoadIMDInterval

SSN - Initial Load IMD - Interval

Used when loading Silver Spring Network (SSN) interval measurements into the system for the first time.

D7-InitialLoadIMDScalar

SSN - Initial Load IMD - Scalar

Used when loading Silver Spring Network (SSN) scalar measurements into the system for the first time.

D7-DeviceEventMappingLookup

SSN - Device Event Mapping

D7-HeadendUOMLookup

SSN - UOM Code to Standard UOM Mapping

D7-IntStsCodeToCondMapLookup

SSN - Interval Status Mapping

This is a child BO of Interval Status Code to Condition Mapping

Silver Spring Networks Device Event Mapping BO

The Silver Spring Networks head-end system is capable of sending a large selection of device events. The adapter maps these events into standard Oracle Utilities Smart Grid Gateway event names and categories. To meet this end, a Silver Spring Networks-specific extendable lookup business object, D7-DeviceEventMappingLookup, holds device event names specific to Silver Spring Networks.

Device Communication

The basic communication for all business processing is essentially the same. A communication request is sent from the Oracle Utilities application to Silver Spring Networks. This request would be for a connect/disconnect, commission/decommission, measurement data, device status check, or an on-demand read. The designated BPEL process transforms the request from Oracle Utilities format to Silver Spring Networks format and invokes the related Silver Spring Networks web service. Silver Spring Networks then returns a reply, and the BPEL process transforms the reply message back to the appropriate format so that Oracle Utilities can receive the response. The following sections describe the key components in this processing, including:

•

Communication Flows

•

Base Package Business Objects

•

External System

•

Outbound Message Types

•

XAI Configuration

•

BPEL Processes

Communication Flows

The table below lists the communications created for each Silver Spring Networks command:

Command

Outbound Communication

Inbound Communication

Completion Event

Remote Connect

SSN-Connect or Disconnect

•

SSN - Connect or Disconnect Response

•

Remote Provisioning Job (Get Status)

Connect Device Completion Event

Remote Disconnect

SSN-Connect or Disconnect

SSN - Connect or Disconnect Response

Disconnect Device Completion Event

Device Commissioning

SSN- Replace Location

Device Commissioning Completion Event

Device Decommissioning

SSN- Replace Device At Location (Decomm)

Device Decommissioning Completion Event

On-Demand Read

(Scalar)

SSN - Add Meter Read Job (Scalar)

SSN - Meter Read Response (Scalar)

Create IMD Completion Event

On-Demand Read

(Interval)

SSN - Add Meter Read Job (Interval)

SSN - Meter Read Response (Interval)

Create IMD Completion Event

Device Status Check

SSN - Add Ping job

SSN - Ping Job Response

Base Package Business Objects

The Silver Spring Networks Adapter base package includes the following communication business objects:

Business Object Name

Description

D7-AddMeterReadJobInterval

SSN - Add Meter Read Job (Interval)

D7-AddMeterReadJobScalar

SSN - Add Meter Read Job (Scalar)

D7-AddPingJob

SSN - Add Ping Job

D7-ConnectDisconnect

SSN - Connect or Disconnect

D7-ConnectDisconnectResp

SSN - Connect or Disconnect Response

D7-GetStatus

SSN - Get Status

D7-GetStatusResponse

SSN - Get Status Response

D7-MeterReadResponseInterval

SSN - Meter Read Response (Interval)

D7-MeterReadResponseScalar

SSN - Meter Read Response (Scalar)

D7-PingJobResponse

SSN - Ping Job Response

D7-ReplaceDeviceAtLocForDecomm

SSN - Replace Device At Location (Decomm)

D7-ReplaceLocation

SSN - Replace Location

Silver Spring Event Data Mapping

The Silver Spring event file format maps as follows into the business object, D1-DeviceEventMappingLookup:

Silver Spring Flat File Field

Device Event Seeder BO Element

Comments

Transaction ID (from Header record)

External Source Identifier

This is the file name.

Device Identifier

External Device Identifier

Event Name

External Event Name

Event Creation Date/Time

Event Date/Time

Device Type

External Device Type

This element has no real bearing on the device type within MDM/SGG. Its valid values include (although the element itself is free-form):

Meter

Collector

Router

Service Location ID

External Service Location ID

Communication Module Serial Number

External Communication Module Identifier

Event Category ID

External Event Category

Event Severity

External Event Severity

Valid values include (although the element itself is free-form):

Alert

Information

Status Value

External Status Value

This represents additional information that relates to the event itself.

Status Date/Time

External Status Date/Time

The date & time at which the additional information referenced above had occurred.

External System

You must create an External System for each external system to which Oracle Utilities Smart Grid Gateway will send messages. Each external system defines a set of outbound message types that will be sent to that system. Each external system outbound message type also specifies the following:

•

The processing method used to send the message (Batch, XAI, or Real-time)

•

The corresponding XAI senders

•

Batch Control (if Processing Method is set to Batch)

•

Message XSL, W3C Schema, and Response XSL (as applicable)

Outbound Message Types

Acknowledgement and response messages are sent and received validating that commands have been transmitted.

XAI Configuration

The XML Application Integration (XAI) utility allows you to configure your system to receive information from and to send information to external applications using XML. The Silver Spring Networks adapter for Smart Grid Gateway uses one XAI inbound service to map device events. This is the same XAI inbound service used by the D1 application.

XAI Inbound Services

XAI inbound systems define the details of how messages are received from an external system, including the inbound communication business object (or business service or service script) to be invoked when the response message is received. As in the case of inbound communication business objects, the set of XAI inbound services you need to create is based on the types of messages the system is designed to send.

The Oracle Utilities Smart Grid Gateway adapter for Silver Spring Networks includes the following XAI inbound services:

XAI Inbound Service

Description

D1-BulkRequestHeader

Bulk Request Header

Schema Name: D1-BulkRequestHeader

D1-BulkRequestUpdate

Bulk Request Update

Schema Name: D1-BULKUPD

D1-BulkResponse

Bulk Response

Schema Name: D1-BulkResponse

D1-DeviceEventSeeder

Used for upload of device events.

Schema Name: D1-DeviceEventSeeder.

The Device Event Seeder business object serves as a means of adding device events both from outside the application and from online. Its pre-processing algorithms determine the device event type - which in turn defines the device event BO that should be used to create the device event.

If a device event type can't be determined, the device event is created using this BO. Such a device event can then be re-processed - and if successful, a new device event is created.

D1-DeviceStatusCheck

Device Status Check

Schema Name: D1-DeviceStatusCheck

This service is invoked by the integration layer to instantiate a Device Status Check command.

D1-InitialLoadIMD

Used by OSB to instantiate an IMD

Schema Name: D1-IMDSeeder.

The IMDSeeder business object is used to determine the type of initial measurement business object to instantiate when receiving usage readings from a head-end system.

D1-RemoteConnect

Remote Connect

Schema Name: D1-RemoteConnect

This service is invoked by the integration layer to instantiate a Remote Connect command.

D1-RemoteDisconnect

Remote Disconnect

Schema Name: D1-RemoteDisconnect

This service is invoked by the integration layer to instantiate a Remote Disconnect command.

D7-ConnectDisconnectResponse

Connect Disconnect Response

Schema Name: D7-ConnectDisconnectResp

Retrieves response for Remote provisioning Job Connect or Disconnect commands.

D7-GetStatusResponse

D7-GetStatusResponse

Schema Name: D7-GetStatusResponse

Retrieve response from the Get Status command.

D7-MeterReadResponseInterval

SSN - Meter Read Response (Interval)

Schema Name: D7-MeterReadResponseInterval

D7-MeterReadResponseScalar

SSN - Meter Read Response (Scalar)

Schema Name: D7-MeterReadResponseScalar

D7-PingJobResponse

SSN - Ping Response

Schema Name: D7-PingJobResponse

Retrieves response from the Ping Job Response command.

XAI Senders

XAI senders define the details of how messages are sent to an external system. As in the case of outbound communication business objects and outbound message types, the set of XAI senders you need to create is based on the types of messages the system is designed to accept.

BPEL Processes

These processes are responsible for performing the conversion from Oracle Utilities format to Silver Spring Networks format, invoking process callouts and invoking the remote endpoint to trigger the device events.

OnDemandRead Composite Process

Provides access points to edge application and handles data between edge application and head end system. It invokes sequence of web methods to head end system and retrieves meter read and send it back to Edge application.

ConnectDisconnect Composite Process

Performs the conversion from Oracle Utilities format to SSN format, invokes process callouts, and invokes the remote endpoint to trigger the connect event. A second, asynchronous reply will call back into the OUAF layer when the status change is completed at the head-end system. Another asynchronous reply will call back into the OUAF layer to send Meter Read Results.

CommissionDecommission Composite Process

Performs the conversion from Oracle Utilities format to SSN UIQ format, invokes process callouts, and invokes the remote endpoint to trigger the commission or decommission of meter.

DeviceStatusCheck Composite

Performs the conversion from Oracle Utilities format to SSN format, invokes process callouts, and makes a call via a proxy to the head-end system starting the Meter Ping operation. In an ideal scenario, the job status is returned as completed and the results are acquired and sent back to OUAF. If the job takes longer, OUAF will initiate a second request that will poll the head end system for the job status. When the job is completed, the results are returned to OUAF.

Common Composite

Contains two main classes of operations: Proxies and ProcessCallouts. Proxies are simple mediators that forward a web service call to a preset endpoint. No transformations are performed. They are convenient because they allow head end URLs and security to be set in a single composite. ProcessCallouts are points of customization which allow users to modify data and/or initiate some external business process.

BulkRequest Composite

Provides access points to requesting application. It decouples the bulk request into single commands for each meter/device in the request and sends it to edge application for processing.

Web Services

The following web services are all defined in the Silver Spring Networks head-end system.:

•

CommissionDecommissionService

•

BPEL Process: CommissionDecommission

•

Operation: ReplaceDeviceAtLocation

•

Enpoint URL: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/SSN/CommissionDecommission/CommissionDecommissionService

•

CommissionDecommissionService

•

BPEL Process: CommissionDecommission

•

Operation: ReplaceLocation

•

Enpoint URL: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/SSN/CommissionDecommission/CommissionDecommissionService

•

ConnectDisconnectService

•

BPEL Process: ConnectDisconnect

•

Operation: AddRemoteProvisioningJob

•

Enpoint URL: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/SSN/ConnectDisconnect/ConnectDisconnectService

•

DeviceStatusCheckService

•

BPEL Process: DeviceStatusCheck

•

Operation: AddPingJob

•

Enpoint URL: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/SSN/DeviceStatusCheck/DeviceStatusCheckService

•

AddMeterReadJobService

•

BPEL Process: AddMeterRead

•

Operation: AddMeterReadJob

•

Enpoint URL: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/SSN/OnDemandRead/AddMeterReadJobService

•

OnDemandReadService

•

BPEL Process: OnDemandRead

•

Operation: GetJobStatus

•

Enpoint URL: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/SSN/OnDemandRead/OnDemandReadService

Silver Spring Networks Utility IQ Web Services

The following table describes the Silver Spring Networks Utility IQ web services and operations used for the Oracle Utilities Smart Grid Gateway command messaging:

Smart Grid Gateway Command

AMI Adapter Business Objects

Silver Spring Networks Web Services

Silver Spring Networks Operations

Device Commissioning

D7-ReplaceLocation

Device Manager

findDevice

Replace Location

Device Decommissioning

D7-ReplaceDeviceAtLocForDecomm

Device Manager

findDevice

ReplaceDeviceAtLocation

Remote Connect/ Remote Disconnect

D7-ConnectDisconnect

D7-GetStatus

Device Manager

Job Manager

DeviceResults

findDevice

addRemoteProvisioningJob

getJobStatusForDevice

getRemoteProvisioningResultsByJobID

findJob

getJobStatus

getMeterReadResultsByJobID

Device Status Check

D7-AddPingJob

Device Manager

Job Manager

DeviceResults

findDevice

addPingJob, getJobStatus

getPingResultsByJobID

On-Demand Read

D7-AddMeterReadJobInterval

D7-AddMeterReadJobScalar

Device Manager

Job Manager

DeviceResults

findDevice

addMeterReadJob

getJobStatus

getMeterReadResultsByJobID

Configuring a Silver Spring Networks Head-End System

This section outlines the configuration required for the Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks to communicate with the Silver Spring Networks UtilityIQ. This includes:

•

Master Configuration

•

XAI Inbound Services

•

XAI Senders

•

Outbound Message Types

•

External System

•

Service Provider

•

Processing Methods for Service Provider

Master Configuration

Master Configurations are sources of global parameter records used by a system implementation. This section describes the master configuration that is specific to Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks. For more information about other master configurations used by Oracle Utilities Smart Grid Gateway, see the Oracle Utilities Smart Grid Gateway Configuration Guide.

SSN Version Master Configuration

This master configuration specifies the version of the Silver Spring Networks head-end system with which the system is communicating. The configuration options are SSN Version 4.4 and SSN Version 4.7. Only one version can be specified at a time. Because of SSN version compatibility, configuration option 4.4 can be used to communicate with SSN Version 4.4 or 4.5, and configuration option 4.7 can be used to communicate with SSN Versions 4.6, 4.7, or 4.8.

XAI Inbound Services

XAI inbound services define the details of how messages are received from an external system. This includes incoming usage and device events, as well as messages sent from the Silver Spring Networks UtilityIQ application in response to a command request.

The following XAI Inbound 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 XAI inbound services.

XAI Inbound Service Name

Description

Schema Type

Schema Name

D1-BulkRequestHeader

Bulk Request Header

Business Object

D1-BulkRequestHeader

D1-BulkRequestUpdate

Bulk Request Update

Business Object

D1-BULKUPD

D1-BulkResponse

Bulk Response

Business Object

D1-BulkResponse

D1-DeviceEventSeeder

Device Event Seeder

Business Object

D1-DeviceEventSeeder

D1-DeviceStatusCheck

Device Status Check

Business Object

D1-DeviceStatusCheck

D1-InitialLoadIMD

Used by OSB to instantiate an IMD

Business Object

D1-IMDSeeder

D1-PayloadErrorNotif

Payload Error Notification

Business Object

D1-PayloadErrorNotif

D1-PayloadStatistics

Payload Statistics

Business Object

D1-PayloadStatistics

D1-PayloadSummary

Payload Summary

Business Object

D1-PayloadSummary

D7-ConnectDisconnectResponse

Connect Disconnect Response

Business Object

D7-ConnectDisconnectResp

D7-GetStatusResponse

Get Status Response

Business Object

D7-GetStatusResponse

D7-MeterReadResponseInterval

SSN - Meter Read Response (Interval)

Business Object

D7-MeterReadResponseInterval

D7-MeterReadResponseScalar

SSN - Meter Read Response (Scalar)

Business Object

D7-MeterReadResponseScalar

D7-PingJobResponse

SSN - Ping Response

Business Object

D7-PingJobResponse

XAI Senders

XAI senders define the details of how messages are sent to an external system, such as messages containing device command requests. An XAI sender should be configured for each command.

The following XAI Senders 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 XAI senders.

XAI Sender

Description

Operation

Service

D7-DECOMM

SSN Replace Device at Location for Decommission

ReplaceDeviceAtLocation

CommissionDecommissionService

D7-COMM

SSN Replace Location - Commission

ReplaceLocation

CommissionDecommissionService

D7-ADDJOB

SSN Add Meter Read Job

AddMeterReadJob

AddMeterReadJobService

D7-ADDPING

SSN Add Ping Job

addPingJob

DeviceStatusCheckService

D7-CONNECT

SSN Connect Device

AddRemoteProvisioningJob

ConnectDisconnectService

D7-GTSTATUS

SSN Get Status

AddRemoteProvisioningJob

ConnectDisconnectService

Note: The following apply to all of the above XAI senders:

Main Tab:

•

Invocation Type : Real-time

•

XAI Class : RTHTTPSNDR (Sender routes message via HTTP real-time)

•

MSG Encoding : UTF-8 message encoding

Context Tab:

•

HTTP Header : SOAPAction:http://xmlns.oracle.com/ouaf/ssn/<OPERATION>

•

HTTP Login User : <USER_ID>

•

HTTP Login Password : <PASSWORD>

•

HTTP Method : POST

•

HTTP URL 1 : http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/SSN/<SERVICE>

where:

•

<OPERATION> : the operation performed by the XAI Sender (see Operation column in the table above)

•

<USER_ID> : the user ID used to log into WebLogic Enterprise Manager

•

<PASSWORD> : the password used to log into WebLogic Enterprise Manager

•

<EM_SERVER_IP> : the machine name or IP address of server where the WebLogic Enterprise Manager is installed

•

<EM_SERVER_PORT> : the port where the WebLogic Enterprise Manager is installed

•

<SERVICE> : the service invoked by the XAI Sender (see Service column in the table above)

Outbound Message Types

Outbound message types define specific types of messages sent to an external system, such as messages containing device command requests.

The following outbound message types 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 outbound message types.

Outbound Message Type

Description

D7-COMMS

Replace Device At Location

D7-OB MSG TY

Outbound Message Type SSN

Note: The following apply to all of the above outbound message types:

•

Business Object : D1-OutboundMessage (Outbound Message)

•

Priority : Priority 50

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 Silver Spring Networks UtilityIQ must be present in your system. If this is not present in your configuration, add it, along with the following Outbound Message Types. Refer to the Oracle Utilities Application Framework documentation for more information about creating external systems.

External System - Silver Spring Networks :

•

External System : Silver Spring Networks

•

Description : Silver Spring Networks

•

Outbound Message Types :

Outbound Message Type

XAI Sender

D7-OB MSG TY (Outbound Message Type SSN)

XAI sender associated with the Outbound Message Type

Note: The following apply to all of the above outbound message types:

•

Processing Method : Real-time

•

Message XSL : D7-Request xsl

•

Response XSL : D7-Response.xsl

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 Silver Spring Networks UtilityIQ must be present in your system. If this is not present in your configuration, add it. Refer to the Oracle Utilities Service and Measurement Data Foundation documentation for more information about creating service providers.

Service Provider - Silver Spring Networks :

•

Service Provider : Silver Spring Networks

•

Description : Silver Spring Networks

•

External Reference ID : Silver Spring Networks

•

External System : Silver Spring Networks

•

Our Name/ID in Their System :

•

AMI Device ID Type : Internal Meter Number

•

Pre-Commissioning Device ID Type:

•

AMI Measuring Component ID Type : Channel ID

Processing Methods for Service Provider

Processing methods define the format or means by which a service provider receives and/or sends data from and/or to the application, including 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. Processing methods can also be used to define how command requests are sent to the Silver Spring Networks UtilityIQ.

The following types of processing methods must be configured for the Silver Spring Networks service provider. Refer to the Oracle Utilities Service and Measurement Data Foundation 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 XAI Inbound Service uses this processing method to determine which type of initial measurement business object to instantiate when receiving usage from the Silver Spring Networks UtilityIQ.

Processing Method - Initial Measurement Creation

•

Service Provider : Silver Spring Networks

•

Processing Role : Initial Measurement Creation

•

Description : Silver Spring Networks Initial Measurement Creation

•

Status : Active

•

Default Processing Method :

•

Business Object : D7-InitialLoadIMDInterval (Silver Spring Networks Initial Load IMD - Interval)

•

Override Processing Method :

•

Measuring Component Type : Electric Residential kWh Scalar

•

Business Object : D7-InitialLoadIMDScalar (Silver Spring Networks Initial Load IMD - Scalar)

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 XAI Inbound Service uses this processing method to determine which type of device event business object to instantiate when receiving device events from the Silver Spring Networks UtilityIQ.

Processing Method - Device Event Mapping

•

Service Provider : Silver Spring Networks

•

Processing Role : Device Event Mapping

•

Description : Silver Spring Networks Device Event Mapping

•

Status : Active

•

Default Processing Method :

•

Business Object : D7-DeviceEventMappingLookup (Silver Spring Networks Device Event Mapping)

•

Override Processing Method : based on implementation-specific requirements

Commands

Command processing methods define how command requests are sent to a head-end system. More specifically, they define the type of outbound communication business object to create for each type of command, and the outbound message type to send to the head-end system.

The following types of command processing methods can be configured for the Silver Spring Networks service provider, based on the requirements of each implementation.

Device Commission

•

Service Provider : Silver Spring Networks

•

Processing Role : Device Commission

•

Description : Silver Spring Networks Device Commission / Replace Location

•

Status : Active

•

Processing Method :

•

Default Business Object : D7-ReplaceLocation (Silver Spring Networks Replace Location)

•

Default Outbound Message Type : Silver Spring Networks Commissioning Outbound Messsage Type

Device Decommission

•

Service Provider : Silver Spring Networks

•

Processing Role : Device Decommission

•

Description : Silver Spring Networks Replace Device at Location - Decommission

•

Status : Active

•

Processing Method :

•

Default Business Object : D7-ReplaceDeviceAtLocForDecomm (Silver Spring Networks - Replace Device At Location (Decomm))

•

Default Outbound Message Type : Outbound Message Type SSN

Device Status Check

•

Service Provider : Silver Spring Networks

•

Processing Role : Device Status Check

•

Description : Add Ping Job

•

Status : Active

•

Processing Method :

•

Default Business Object : D7-AddPingJob (Silver Spring Networks - Add Ping Job)

•

Default Outbound Message Type : Outbound Message Type SSN

Remote Connect

•

Service Provider : Silver Spring Networks

•

Processing Role : Remote Connect

•

Description : Remote Provisioning Job -Connect

•

Status : Active

•

Processing Method :

•

Default Business Object : D7-ConnectDisconnect (Silver Spring Networks - Connect or Disconnect)

•

Default Outbound Message Type : Connect Device

Remote Disconnect

•

Service Provider : Silver Spring Networks

•

Processing Role : Remote Disconnect

•

Description : Silver Spring Networks Disconnect

•

Status : Active

•

Processing Method :

•

Default Business Object : D7-ConnectDisconnect (Silver Spring Networks - Connect or Disconnect)

•

Default Outbound Message Type : Initiate Connect Disconnect

Verify Command

•

Service Provider : Silver Spring Networks

•

Processing Role : Verify Command

•

Description : Silver Spring Networks Get Status

•

Status : Active

•

Processing Method :

•

Default Business Object : D7-GetStatus (Silver Spring Networks - Get Status)

•

Default Outbound Message Type : Get Status

Configuring Silver Spring Networks Extendable Lookups

This section outlines some of the extendable lookups that must be configured for use with the Silver Spring Networks adapter. These include:

•

Silver Spring Networks Device Event Mapping

•

Silver Spring Networks UOM Code to Standard UOM Mapping

•

Silver Spring Networks Interval Status Code to Condition Mapping

Refer to the Oracle Utilities Application Framework documentation for more information about working with extendable lookups.

Silver Spring Networks Device Event Mapping

The Silver Spring Networks Device Event Mapping extendable lookup is used to determine which type of device event business object to instantiate when receiving device events from the Silver Spring Networks UtilityIQ.

Each value defined for the Silver Spring Networks Device Event Mapping extendable lookup should include the following:

•

Head-End System Event Name : The event name used by the Silver Spring Networks UtilityIQ

•

Description : A description of the device event

•

Status : The status of the lookup value (can be Active or Inactive)

•

Standard Event Name : The standard event name for device events of this type, from the "Standard Event Name" extendable lookup.

Example : The Silver Spring Networks "Tampering" device event name could be mapped to the "Device Tampering" standard device event name as follows:

•

Head-End System Event Name : Tampering

•

Description : Tampering Detected

•

Status : Active

•

Standard Event Name : Device Tampering

Silver Spring Networks UOM Code to Standard UOM Mapping

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

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

•

Head-End Unit of Measure : The unit of measure code used by the Silver Spring Networks UtilityIQ

•

Description : A description of the unit of measure code.

•

Status : The status of the lookup value (can be Active or Inactive)

•

Unit of Measure : The unit of measure defined in the system. See Defining Units of Measure in the Oracle Utilities Service and Measurement Data Foundation User’s Guide for more information about creating UOM codes for use with Oracle Utilities Smart Grid Gateway.

Example : The Silver Spring Networks "KWH" unit of measure code could be mapped to the "Kilowatt Hours" standard UOM code as follows:

•

Unit of Measure : Kilowatt Hours

•

Head-end UOM : kWh

•

Description : Silver Spring Networks Kilowatt Hours

Silver Spring Networks Interval Status Code to Condition Mapping

Interval usage received from the Silver Spring Networks UtilityIQ can include Silver Spring Networks interval status codes that indicate the status or condition of the interval value. These interval status codes must be mapped to standard condition codes in the system. The Silver Spring Networks Interval Status Code to Condition Mapping extendable lookup is used to determine how to map Silver Spring Networks interval status codes to standard status codes when receiving usage from the Silver Spring Networks UtilityIQ.

Each value defined for the Silver Spring Networks Interval Status Code to Condition Mapping extendable lookup should include the following:

•

Interval Status : The Silver Spring Networks interval status code

•

Description : A description of the interval status code.

•

Status : The status of the lookup value (can be Active or Inactive)

•

Condition : The condition code to which the interval status code is to be mapped, from the Measurement Condition extendable lookup.

Example : The Silver Spring Networks "Missing" interval status code could be mapped to the "Missing" condition code as follows:

•

Interval Status : Missing

•

Condition : Missing

•

Description : Silver Spring Networks Missing

Extending the Adapter for Silver Spring Networks

The Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks supports a number of commands, including:

•

Commission Device

•

Decommission Device

•

Device Status Check

•

On-Demand Read

•

Remote Connect

•

Remote Disconnect

The Adapter for Silver Spring Networks can be extended to support additional commands provided by the Silver Spring Networks UtilityIQ. See Creating Custom Commands on page 9-26 of the Oracle Utilities Smart Grid Gateway Configuration Guide for more information about adding commands to the Silver Spring Networks adapter.

The Test Harness

Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks (SSN) includes a test harness that can be configured to simulate the Silver Spring Networks UtilityIQ head-end system for testing the two-way commands. The test harness includes a BPEL composite, web services for standard meter functions, and an XML file that can be used to contain information for one or more meters. This chapter describes the test harness and it’s components, including:

•

Test Harness Design

•

Locating the WSDL for the Test Harness

•

Web Services

Test Harness Design

The SSN Harness is divided into two main layers. A "front end" set of services implements the SSN-specified interfaces in both the 4.4 version and in the 4.7 version. They receive requests corresponding to:

•

urn:com:ssn:schema:service:v1.4:DataAggregation and urn:com:ssn:schema:service:v1.6:DataAggregation

•

getMeterFieldStatus

•

urn:com:ssn:schema:service:v1.4:DeviceManager and urn:com:ssn:schema:service:v1.6:DeviceManager

•

FindDevice

•

ReplaceDeviceAtLocation

•

ReplaceLocation

•

urn:com:ssn:schema:service:v1.4:DeviceResults and urn:com:ssn:schema:service:v1.6:DeviceResults

•

getRemoteProvisioningResultsByJobID

•

getMeterReadResultsByJobID

•

getPingResultsByJobID

•

urn:com:ssn:schema:service:v1.4:JobManager and urn:com:ssn:schema:service:v1.6:JobManager

•

addRemoteProvisioningJob

•

getJobStatus

•

addMeterReadJob

•

addPingJob

•

findJob

•

getJobStatusForDevice

Each of these services calls into the "back end" layer which defines meters and sets their attributes. These meters are stored in a file within the test harness called meterdb.xml. This file can be modified pre-deployment. Post-deployment changes to the file are not supported. However, the Test Harness retains an in-memory "database" of the meters in the file. The in-memory representation can be modified using the Utility web services. Note that any changes to the in-memory structure will be lost when the server is restarted or the Test Harness composite is redeployed.

Locating the WSDL for the Test Harness

Follow these procedures to locate the test harness WSDL:

How to Use Enterprise Manager to Locate the WSDL

1.

Open Enterprise Manager and use the navigation pane to open the dashboard of the test harness composite:

2.

The top bar of the dashboard contains several buttons and icons. One of these is a "world" icon with a puzzle piece over it. Click this icon to display a list of the WSDLs and endpoint URIs for the composite:

3.

Click the UtilService WSDL URL link to see the WSDL in the browser, or right click and save it to your machine

Depending on your requirements, it may be necessary to download the associated schema found in the wsdl:types section. The URL can be pasted into a browser tab and downloaded in the same manner as the WSDL. The main schema has imported schemas that may also be required.

How to Use a Direct URL to locate the WSDL

The WSDL can be accessed without Enterprise Manager by understanding the paths used on the SOA server. In general, they have the following form:

http://{server name}:{port number}/soa-infra/services/{partition}/{Composite}/{Web Service}?WSDL

So by default, the test harness WSDL can be found at

http://{server name}:{port number}/soa-infra/services/SSN_Test/SSNTestHarness/UtilService?WSDL

Web Services

This section describes the web services included in the test harness BPEL composite, including:

•

General Services

•

Locate Meter Services

•

Meter Administration Services

•

Meter Attribute Administration Services

General Services

This section describes the general services of the test harness composite, including:

•

LoadMeterIndex

•

ViewAuditTrail

LoadMeterIndex

This web service loads the data store from the internal file. By default, if the store is already in memory, it will NOT reload. This behavior can be overridden with the forceReload parameter.

Input

LoadMeterIndexInput

Part: payload

Element: LoadMeterIndexRequest

Parameter

Description

forceReload

A switch telling the system whether to reload the meter index from the configuration file. Default is false.

Output

LoadMeterIndexOutput

Part: payload

Element: LoadMeterIndexResult

Parameter

Description

loaded

A boolean value for whether or not the index was reloaded from the configuration file

Fault

UtilityFault

Fault with similar mapping to SGG/OUAF faults:

Typically, the faultCode, faultString, faultActor, and detail/text elements will be populated.

ViewAuditTrail

This web service returns the audit log for the entire session.

Input

ViewAuditTrailInput

Part: payload

Element: ViewAuditTrailRequest

Output

ViewAuditTrailOutput

Part: payload

Element: ViewAuditTrailResult

An Entry consisting of a timestamp and an Operation. Each entry may have an associated meter object showing the latest update.

Fault

See UtilityFault .

Locate Meter Services

This section describes the locate meter web services of the test harness composite, including:

•

FindMeters

•

IsMeterDefined

•

IsMACIDDefined

•

GetMeter

•

GetMeterByMACID

•

GetGroupMeters

FindMeters

This web service queries the data store for one or more meters. The difference between GetMeter and FindMeters is GetMeter can return at most one meter and it must match the provided ID exactly. GetMeter will throw an error if the ID is not found. FindMeters can return more than one meter (when using the regex) and will not throw an error when the ID does not match any of the meters in the index.

Input

FindMetersInput

Part: payload

Element: FindMetersRequest

Parameter

Description

id

The meter ID for which to search

isRegex

The provided id can be a regex value when this parameter is true. Hint: to search for all meters in the system, use ".*" for the ID.

Output

FindMetersOutput

Part: payload

Element: FindMetersResult

Zero or more meter objects can be returned from the search

Fault

See UtilityFault . Unlike other methods, FindMeters does not throw an exception if the meter is not found. As such, it can be used to test for the existence of a Meter prior to querying for it.

IsMeterDefined

This web service queries whether a particular meter is defined in the data store.

Input

IsMeterDefinedInput

Part: payload

Element: IsMeterDefinedRequest

Parameter

Description

id

The meter ID for which to search

Output

IsMeterDefinedOutput

Part: payload

Element: IsMeterDefinedResult

Whether or not the provided ID is part of the index.

Fault

See UtilityFault . Thrown when meter id is not found.

IsMACIDDefined

This web service queries whether a particular MAC address is defined in the data store.

Input

IsMACIDDefinedInput

Part: payload

Element: IsMACIDDefinedRequest

Parameter

Description

id

The MAC address for which to search

Output

IsMACIDDefinedOutput

Part: payload

Element: IsMACIDDefinedResult

Whether or not the provided MAC address is part of the index.

Fault

See UtilityFault . Thrown when meter id is not found.

GetMeter

This web service returns all the attributes of a single meter from the in-memory data store. The difference between GetMeter and FindMeters is GetMeter can return at most one meter and it must match the provided ID exactly. GetMeter will throw an error if the ID is not found. FindMeters can return more than one meter (when using the regex) and will not throw an error when the ID does not match any of the meters in the index.

Input

GetMeterInput

Part: payload

Element: GetMeterRequest

Parameter

Description

id

The meter ID for which to search

Output

GetMeterOutput

Part: payload

Element: GetMeterResult

The meter object requested by the ID.

Fault

See UtilityFault . Thrown when meter id is not found.

GetMeterByMACID

This web service returns all the attributes of a single meter from the in-memory data store. The difference between GetMeter and GetMeterByMACID is this method looks for a MAC address rather than the identifier of the meter. GetMeterByMACID will throw an error if the MAC address is not found.

Input

GetMeterByMACID

Part: payload

Element: GetMeterByMACIDRequest

Parameter

Description

id

The MAC address for which to search

Output

GetMeterByMACIDOutput

Part: payload

Element: GetMeterByMACIDResult

The meter object requested by the MAC address.

Fault

See UtilityFault . Thrown when meter id is not found.

GetGroupMeters

This web service retrieves the set of meters with the specified group name

Input

GetGroupMetersInput

Part: payload

Element: GetGroupMetersRequest

Parameter

Description

id

The group name common to the meters to retrieved

Output

GetGroupMetersOutput

Part: payload

Element: GetGroupMetersResult

The set of meters with the provided group name.

Fault

See UtilityFault . Thrown only in unusual circumstances.

Meter Administration Services

This section describes the meter administration services of the test harness composite, including:

•

AddMeters

•

RemoveMeter

•

AddMeterChannel

•

RemoveMeterChannel

•

ReadScalarMeter

AddMeters

This web service adds a set of meters to the in-memory data store. This will not permanently add it to the control file.

Input

AddMetersInput

Part: payload

Element: AddMetersRequest

Parameter

Description

id

The identification code for the meter.

macID

A MAC address that must be unique within the system.

utility

An informational string.

serviceType

One of the valid ServiceType values (see schema). "Electric" is the only option at this time.

isCommissioned

Whether or not the meter is in a commissioned state.

loadActionCode

One of the possible LoadActionCode values used in Connect and Disconnect (see schema).

outageEventType

One of the possible OutageEventType values used in Device Status Check (see schema).

executionStatus

One of the possible ExecutionStates (see schema). These values control how the meter will respond to commands.

groupName

The name linking multiple meters together into a set.

jobExecutionStatus

One of the possible Job Execution Status values (see schema). This attribute determines how requested jobs perform.

updateIfExisting

Whether or not to update the meter with the provided values if it already exists in the index.

Comment

An informational string describing the purpose of the meter.

Channels

A listing of unit of measures supported by this meter.

uomCode

A code describing the unit of measure for the channel.

uomName

A short string containing the name of the unit of measure.

decimals

The number of digits to the right of the decimal that should be generated when reading the meter.

description

A longer description of the unit of measure.

Output

AddMetersOutput

Part: payload

Element: AddMetersResult

Whether or not each meter was added to the index.

Fault

See UtilityFault

RemoveMeter

This web service removes a meter from the in-memory data store. This will not permanently remove it from the control file.

Input

RemoveMeterInput

Part: payload

Element: RemoveMeterRequest

Parameter

Description

id

The ID for the meter to be removed

Output

RemoveMeterOutput

Part: payload

Element: RemoveMeterResult

Whether or not the meter was removed from the index.

Fault

See UtilityFault . Thrown when meter id is not found.

AddMeterChannel

This web service adds a new channel to a single meter.

Input

AddMeterChannelInput

Part: payload

Element: AddMeterChannelRequest

Parameter

Description

id

The identification code for the meter.

uomCode

A code describing the unit of measure for the channel.

uomName

A short string containing the name of the unit of measure.

decimals

The number of digits to the right of the decimal that should be generated when reading the meter.

description

A longer description of the unit of measure.

Output

AddMeterChannelOutput

Part: payload

Element: AddMeterChannelResult

Whether or not the channel was added to the index.

Fault

See UtilityFault . Thrown when meter id is not found.

RemoveMeterChannel

This web service removes a Channel from a meter.

Input

RemoveMeterChannelInput

Part: payload

Element: RemoveMeterChannelRequest

Parameter

Description

id

The ID for the meter to be removed.

uomCode

A code describing the unit of measure for the channel.

uomName

A short string containing the name of the unit of measure.

These three parameters are combined to locate a unique channel

Output

RemoveMeterChannelOutput

Part: payload

Element: RemoveMeterChannelResult

Whether or not the channel was removed from the meter.

Fault

See UtilityFault . Thrown when meter id is not found.

ReadScalarMeter

This web service generates a scalar reading for each channel of a given meter.

Input

ReadScalarMeterInput

Part: payload

Element: ReadScalarMeterRequest

Parameter

Description

id

The ID for the meter to be read

Output

ReadScalarMeterOutput

Part: payload

Element: ReadScalarMeterResult

Zero or more scalar readings for the given meter.

Parameter

Description

uomCode

A code describing the unit of measure for the channel.

uomName

A short string containing the name of the unit of measure.

decimals

The number of digits to the right of the decimal that should be generated when reading the meter.

description

A longer description of the unit of measure.

value

A random number representing the scalar reading.

Meter Attribute Administration Services

This section describes the meter administration services of the test harness composite, including:

•

GetMACID

•

SetMACID

•

GetJobExecutionStatus

•

SetJobExecutionStatus

•

GetDeviceStatus

•

SetDeviceStatus

•

GetConnectionStatus

•

SetConnectionStatus

•

IsCommissioned

•

SetCommissioned

•

GetExecutionStatus

•

SetExecutionStatus

GetMACID

This web service queries the MAC address of a meter. MAC addresses are used to identify meters within the SSN system. Therefore, they must be unique within the test harness. The structure of a MAC address is six sets of character pairs separated by colons. A "real" MAC address has further limitations on the range of the data, but for the purposes of the test harness, any digit or character from A-Z will be returned.

Input

GetMACIDInput

Part: payload

Element: GetMACIDRequest

Parameter

Description

id

The ID for the meter for which the MAC address should be retrieved

Output

GetMACIDOutput

Part: payload

Element: GetMACIDResult

The MAC address for the requested meter.

Fault

See UtilityFault . Thrown when meter id is not found.

SetMACID

This web service updates the MAC address for a given meter. MAC addresses are used to identify meters within the SSN system. Therefore, they must be unique within the test harness. The structure of a MAC address is six sets of character pairs separated by colons. A "real" MAC address has further limitations on the range of the data, but for the purposes of the test harness, any digit or character from A-Z will be returned.

Input

SetMACIDInput

Part: payload

Element: SetMACIDRequest

Parameter

Description

id

The ID for the meter for which the MAC address should be set

value

The new MAC address to set on the meter

Output

SetMACIDOutput

Part: payload

Element: SetMACIDResult

The boolean response indicates the success or failure of the update (not the current field status).

Fault

See UtilityFault . Thrown when meter id is not found.

GetJobExecutionStatus

This web service queries the job execution status of a meter. Many activities in SSN initiate jobs which can end in one of several statuses. The job execution status controls the ending status. The possible values of a jobExecutionStatus are:

•

JOB_EXEC_STATUS_NOT_STARTED - The job has not started. This is the initial state of submitted jobs.

•

JOB_EXEC_STATUS_RUNNING - The job is running.

•

JOB_EXEC_STATUS_COMPLETE - The job has completed.

•

JOB_EXEC_STATUS_FAILURE - The job failed.

•

JOB_EXEC_STATUS_UNKNOWN - The job's status is unknown.

•

Other - The job's status is not one of the other values.

The enumeration values come from the SSN schema type "ExecutionStatusEnumeration."

Input

GetJobExecutionStatusInput

Part: payload

Element: GetJobExecutionStatusRequest

Parameter

Description

id

The ID for the meter for which the job execution status should be retrieved

Output

GetJobExecutionStatusOutput

Part: payload

Element: GetJobExecutionStatusResult

The value of the job execution status for the requested meter.

Fault

See UtilityFault . Thrown when meter id is not found.

SetJobExecutionStatus

This web service update the job execution status for a given meter. Many activities in SSN initiate jobs which can end in one of several statuses. The job execution status controls the ending status. The possible values of a jobExecutionStatus are:

•

JOB_EXEC_STATUS_NOT_STARTED - The job has not started. This is the initial state of submitted jobs.

•

JOB_EXEC_STATUS_RUNNING - The job is running.

•

JOB_EXEC_STATUS_COMPLETE - The job has completed.

•

JOB_EXEC_STATUS_FAILURE - The job failed.

•

JOB_EXEC_STATUS_UNKNOWN - The job's status is unknown.

•

Other - The job's status is not one of the other values.

The enumeration values come from the SSN schema type "ExecutionStatusEnumeration."

Input

SetJobExecutionStatusInput

Part: payload

Element: SetJobExecutionStatusRequest

Parameter

Description

id

The ID for the meter for which the job execution status should be set

value

The new job execution status to set on the meter

Output

SetJobExecutionStatusOutput

Part: payload

Element: SetJobExecutionStatusResult

The boolean response indicates the success or failure of the update (not the current field status).

Fault

See UtilityFault . Thrown when meter id is not found.

GetDeviceStatus

This web service queries the device status of a meter. The OutageEventType is used by DeviceStatusCheck. The possible values of a deviceStatusType are:

•

Instantaneous - The meter responds immediately to the status check

•

SlowResponse - An EndpointFailure with a FailureReason of "ErrorResponse" will be returned from the Test Harness

•

NoResponse - An EndpointFailure with a FailureReason of "NoResponse" will be returned from the Test Harness

•

Unknown - An EndpointFailure with a FailureReason of "Unspecified" will be returned from the Test Harness

Input

GetDeviceStatusInput

Part: payload

Element: GetDeviceStatusRequest

Parameter

Description

id

The ID for the meter for which the status should be retrieved

Output

GetDeviceStatusOutput

Part: payload

Element: GetDeviceStatusResult

The value of the device status for the requested meter.

Fault

See UtilityFault . Thrown when meter id is not found.

SetDeviceStatus

This web service updates the device status for a given meter. The possible values of a deviceStatusType are:

•

Instantaneous - The meter responds immediately to the status check.

•

SlowResponse - An EndpointFailure with a FailureReason of "ErrorResponse" will be returned from the Test Harness.

•

NoResponse - An EndpointFailure with a FailureReason of "NoResponse" will be returned from the Test Harness.

•

Unknown - An EndpointFailure with a FailureReason of "Unspecified" will be returned from the Test Harness.

Input

SetDeviceStatusInput

Part: payload

Element: SetDeviceStatusRequest

Parameter

Description

id

The ID for the meter for which the device status should be set

value

the new device status to set on the meter

Output

SetDeviceStatusOutput

Part: payload

Element: SetDeviceStatusResult

The boolean response indicates the success or failure of the update (not the current field status).

Fault

See UtilityFault . Thrown when meter id is not found.

GetConnectionStatus

This web service queries whether the given meter is connected or disconnected. This method is used by the Connect/Disconnect service. The values for connectionStatusType are:

•

Connected

•

Disconnected

•

Unknown

Input

GetConnectionStatusInput

Part: payload

Element: GetConnectionStatusRequest

Parameter

Description

id

The ID for the meter for which the connection status should be retrieved

Output

GetConnectionStatusOutput

Part: payload

Element: GetConnectionStatusResult

The connection status of the requested meter.

Fault

See UtilityFault . Thrown when meter id is not found.

SetConnectionStatus

This web service updates the load action code for a given meter. This method is used by the Connect/Disconnect service. The values for connectionStatusType are:

•

Connected

•

Disconnected

•

Unknown

Input

SetConnectionStatusInput

Part: payload

Element: SetConnectionStatusRequest

Parameter

Description

id

The ID for the meter for which the connection status should be set.

value

The new value of LoadActionCode to set on the meter.

Output

SetConnectionStatusOutput

Part: payload

Element: SetConnectionStatusResult

The boolean response indicates the success or failure of the update (not the current field status).

Fault

See UtilityFault . Thrown when meter id is not found.

IsCommissioned

This web service queries the commissioning status for a given meter. This service is used by the Commission/Decommission process. The commissioning attribute can be true or false.

Input

IsCommissionedInput

Part: payload

Element: IsCommissionedRequest

Parameter

Description

id

The ID for the meter for which the Commissioned status should be retrieved

Output

IsCommissionedOutput

Part: payload

Element: IsCommissionedResult

The value of the Commissioned status attribute for the requested meter.

Fault

See UtilityFault . Thrown when meter id is not found.

SetCommissioned

This web service updates the commissioning status for a given meter. This service is used by the Commission/Decommission process. The commissioning attribute can be true or false.

Input

SetCommissionedInput

Part: payload

Element: SetCommissionedRequest

Parameter

Description

id

The ID for the meter for which the Commissioned status should be set

value

The new value of Commissioned status to set on the meter

Output

SetCommissionedOutput

Part: payload

Element: SetCommissionedResult

The boolean response indicates the success or failure of the update (not the current field status).

Fault

See UtilityFault . Thrown when meter id is not found.

GetExecutionStatus

This web service queries the status of the property controlling the overall execution of the command. The possible values of execution status are:

•

Success - The command should complete successfully

•

ResponseTimeout - The asynchronous response will never arrive

•

SyncOperationFail - A simulated fault will occur in the during the initial request

•

AsyncOperationFailure - A simulated fault will occur in the asynchronous response

Input

GetExecutionStatusInput

Part: payload

Element: GetExecutionStatusRequest

Parameter

Description

id

The ID for the meter for which the ExecutionStatus should be retrieved

Output

GetExecutionStatusOutput

Part: payload

Element: GetExecutionStatusResult

The value of the ExecutionStatus attribute for the requested meter.

Fault

See UtilityFault . Thrown when meter id is not found.

SetExecutionStatus

This web service updates the property controlling the overall completion of the command. The possible values of execution status are:

•

Success - The command should complete successfully

•

ResponseTimeout - The asynchronous response will never arrive

•

SyncOperationFail - A simulated fault will occur in the during the initial request

•

AsyncOperationFailure - A simulated fault will occur in the asynchronous response

Input

SetExecutionStatusInput

Part: payload

Element: SetExecutionStatusRequest

Parameter

Description

id

The ID for the meter for which the ExecutionStatus should be set

value

The new value of ExecutionStatus to set on the meter

Output

SetExecutionStatusOutput

Part: payload

Element: SetExecutionStatusResult

The boolean response indicates the success or failure of the update (not the current field status).

Fault

See UtilityFault . Thrown when meter id is not found.

Glossary

This glossary provides definitions of commonly used terms.

Command Effective Date/Time

The date and time when a device command becomes effective.

Command Expiration Date/Time

The date and time when a device command expires.

Commissioning

A command issued to establish communication between a device and the head-end system. The goal is to ensure connectivity has been established with the device, that any information needed to communicate with the meter has been defined in both Oracle Utilities Smart Grid Gateway and the head end system, and the meter will begin capturing usage and events.

Decommissioning

A command issued to inform the head-end system when a meter needs to be removed from a service point, so that no further reads or events will arrive from the meter. Decommissioning is invoked when a meter must be removed or deactivated. The goal is to stop any communication between the device and the head-end system.

Head-End System

A system that collects measurement data and meter events for eventual submission to the application. Many devices can communicate to the application through a single head-end system. A utility may have numerous head-end systems through which they communicate with devices.

On-Demand Read

A request for the most up-to-date reading from a particular meter. It is not guaranteed to return immediately; it could require a person to manually read the meter. The purposes are to check the meter’s operational status and/or obtain a more recent reading than is currently available.

Payload

An upload component which contains measurements and meter events in a format specific to the head-end. Payloads are part of the initial upload of measurement data.

Remote Connect

A command issued when a meter needs to be connected at a service point.