Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks

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 agencyspecific 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.
Contents
Chapter 1
Overview............................................................................................................................................................. 1-1
What Is This Book?........................................................................................................................................................ 1-2
Other Documentation................................................................................................................................... 1-2
Oracle Utilities Application Framework Configuration Tools................................................................................ 1-4
Chapter 2
General Configuration ...................................................................................................................................... 2-1
Understanding the Adapter........................................................................................................................................... 2-2
Understanding the Adapter Processing....................................................................................................................... 2-3
Initial Measurement Data Load and Device Events................................................................................. 2-3
Device Communication ................................................................................................................................ 2-6
Configuring a Silver Spring Networks Head-End System ..................................................................................... 2-14
Master Configuration................................................................................................................................... 2-14
XAI Inbound Services................................................................................................................................. 2-14
XAI Senders.................................................................................................................................................. 2-16
Outbound Message Types .......................................................................................................................... 2-17
External System............................................................................................................................................ 2-17
Service Provider ........................................................................................................................................... 2-18
Processing Methods for Service Provider ................................................................................................ 2-18
Configuring Silver Spring Networks Extendable Lookups ................................................................................... 2-21
Silver Spring Networks Device Event Mapping ..................................................................................... 2-21
Silver Spring Networks UOM Code to Standard UOM Mapping....................................................... 2-21
Silver Spring Networks Interval Status Code to Condition Mapping.................................................. 2-22
Extending the Adapter for Silver Spring Networks................................................................................................ 2-23
The Test Harness.......................................................................................................................................................... 2-24
Test Harness Design.................................................................................................................................... 2-24
Locating the WSDL for the Test Harness ............................................................................................... 2-25
Web Services................................................................................................................................................. 2-27
Appendix
Glossary ............................................................................................................................................................. 3-1
Index
i
ii
Chapter 1
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
Overview 1-1
What Is This Book?
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
1-2 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
What Is This Book?
•
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)
Overview 1-3
Oracle Utilities Application Framework Configuration Tools
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.
1-4 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Chapter 2
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
General Configuration 2-1
Understanding the Adapter
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.
2-2 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Understanding the Adapter Processing
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-SSNXMLCM.
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
•
callPreProcessing
Determines if the preprocessing proxy service is called.
Valid values are:
• true
•
callPostProcessing
false
false
Determines if the postprocessing proxy service is called.
Valid values are:
• true
•
false
General Configuration 2-3
Understanding the Adapter Processing
Element
Description
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
2-4 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Understanding the Adapter Processing
Business Object Name
Description
D7-IntStsCodeToCondMapLookup
SSN - Interval Status Mapping
This is a child BO of Interval Status Code to Condition
Mapping
General Configuration 2-5
Understanding the Adapter Processing
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
Remote Connect
Outbound
Communication
Inbound
Communication
Completion
Event
SSN–Connect or
Disconnect
•
SSN – Connect or
Disconnect
Response
Connect Device
Completion Event
•
Remote
Provisioning Job
(Get Status)
Remote Disconnect
SSN–Connect or
Disconnect
SSN – Connect or
Disconnect Response
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
2-6 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Disconnect Device
Completion Event
Understanding the Adapter Processing
Command
Device Status
Check
Outbound
Communication
Inbound
Communication
SSN – Add Ping job
SSN – Ping Job
Response
Completion
Event
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
D7ReplaceDeviceAtLocForDecomm
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, D1DeviceEventMappingLookup:
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
General Configuration 2-7
Understanding the Adapter Processing
Silver Spring Flat File
Field
Device Event Seeder BO
Element
Device Type
External Device Type
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 freeform):
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.
Comments
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
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.
2-8 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Understanding the Adapter Processing
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 preprocessing 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.
General Configuration 2-9
Understanding the Adapter Processing
XAI Inbound Service
Description
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.
2-10 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Understanding the Adapter Processing
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.
General Configuration 2-11
Understanding the Adapter 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
2-12 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Understanding the Adapter Processing
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
Device
Commissioning
D7-ReplaceLocation
Device
Decommissioning
Remote Connect/
Remote Disconnect
Silver
Spring
Networks
Web
Services
Silver Spring Networks
Operations
Device
Manager
findDevice
D7ReplaceDeviceAtLocForDec
omm
Device
Manager
findDevice
D7-ConnectDisconnect
Device
Manager
findDevice
Job Manager
getJobStatusForDevice
DeviceResults
getRemoteProvisioningResults
ByJobID
D7-GetStatus
Replace Location
ReplaceDeviceAtLocation
addRemoteProvisioningJob
findJob
getJobStatus
getMeterReadResultsByJobID
Device Status Check
D7-AddPingJob
Device
Manager
findDevice
Job Manager
getPingResultsByJobID
addPingJob, getJobStatus
DeviceResults
On-Demand Read
D7AddMeterReadJobInterval
Device
Manager
findDevice
D7-AddMeterReadJobScalar
Job Manager
getJobStatus
DeviceResults
getMeterReadResultsByJobID
addMeterReadJob
General Configuration 2-13
Configuring a Silver Spring Networks Head-End System
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
2-14 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Configuring a Silver Spring Networks Head-End System
XAI Inbound Service Name
Description
Schema Type
Schema Name
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
D7MeterReadResponseInterval
D7-MeterReadResponseScalar
SSN - Meter Read
Response (Scalar)
Business Object
D7-MeterReadResponseScalar
D7-PingJobResponse
SSN - Ping Response
Business Object
D7-PingJobResponse
General Configuration 2-15
Configuring a Silver Spring Networks Head-End System
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
CommissionDecommissionS
ervice
D7-COMM
SSN Replace Location
- Commission
ReplaceLocation
CommissionDecommissionS
ervice
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)
2-16 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Configuring a Silver Spring Networks Head-End System
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
General Configuration 2-17
Configuring a Silver Spring Networks Head-End System
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:
2-18 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Configuring a Silver Spring Networks Head-End System
•
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))
General Configuration 2-19
Configuring a Silver Spring Networks Head-End System
•
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
2-20 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Configuring Silver Spring Networks Extendable Lookups
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.
General Configuration 2-21
Configuring Silver Spring Networks Extendable Lookups
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
2-22 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Extending the Adapter for Silver Spring Networks
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 926 of the Oracle Utilities Smart Grid Gateway Configuration Guide for more information about adding
commands to the Silver Spring Networks adapter.
General Configuration 2-23
The Test Harness
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 inmemory structure will be lost when the server is restarted or the Test Harness composite is
redeployed.
2-24 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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
General Configuration 2-25
The Test Harness
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
2-26 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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
General Configuration 2-27
The Test Harness
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 on page 2-27.
2-28 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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
General Configuration 2-29
The Test Harness
Element: FindMetersResult
Zero or more meter objects can be returned from the search
Fault - See UtilityFault on page 2-27. 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 on page 2-27. 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
2-30 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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 on page 2-27. 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
General Configuration 2-31
The Test Harness
Element: GetMeterResult
The meter object requested by the ID.
Fault - See UtilityFault on page 2-27. 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
2-32 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
Element: GetMeterByMACIDResult
The meter object requested by the MAC address.
Fault - See UtilityFault on page 2-27. 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
General Configuration 2-33
The Test Harness
Element: GetGroupMetersResult
The set of meters with the provided group name.
Fault - See UtilityFault on page 2-27. 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
2-34 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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.
General Configuration 2-35
The Test Harness
Parameter
Description
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 on page 2-27
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 on page 2-27. Thrown when meter id is not found.
AddMeterChannel
This web service adds a new channel to a single meter.
2-36 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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 on page 2-27. Thrown when meter id is not found.
RemoveMeterChannel
This web service removes a Channel from a meter.
Input - RemoveMeterChannelInput
Part: payload
General Configuration 2-37
The Test Harness
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 on page 2-27. 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
2-38 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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.
General Configuration 2-39
The Test Harness
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 on page 2-27. 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
2-40 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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 on page 2-27. 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
General Configuration 2-41
The Test Harness
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 on page 2-27. 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
2-42 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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 on page 2-27. 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 on page 2-27. 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.
General Configuration 2-43
The Test Harness
•
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 on page 2-27. 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
2-44 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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 on page 2-27. 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
General Configuration 2-45
The Test Harness
Element: SetConnectionStatusResult
The boolean response indicates the success or failure of the update (not the current field status).
Fault - See UtilityFault on page 2-27. 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 on page 2-27. 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
2-46 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
The Test Harness
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 on page 2-27. 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
General Configuration 2-47
The Test Harness
Element: GetExecutionStatusResult
The value of the ExecutionStatus attribute for the requested meter.
Fault - See UtilityFault on page 2-27. 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 on page 2-27. Thrown when meter id is not found.
2-48 Oracle Utilities Smart Grid Gateway Adapter for Silver Spring Networks Configuration Guide
Appendix
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
Glossary 3-1
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.
3-2 Oracle Utilities Smart Grid Gateway adapter for Sensus Configuration Guide
Index
A
I
Adapter 2-2
processing 2-3
Inbound Services 2-9
D1-BulkRequestHeader 2-9
D1-BulkRequestUpdate 2-9
D1-BulkResponse 2-9
D1-DeviceEvent 2-9
D1-DeviceStatusCheck 2-9
D1-InitialLoadIMD 2-9
D1-RemoteConnect 2-10
D1-RemoteDisconnect 2-10
D7-ConnectDisconnectResponse 2-10
D7-GetStatusResponse 2-10
D7-MeterReadResponseInterval 2-10
D7-MeterReadResponseScalar 2-10
D7-PingJobResponse 2-10
Initial Measurement 2-3
B
BPEL Processes 2-11
CommissionDecommission 2-11
ConnectDisconnect 2-11
OnDemandRead 2-11
ProcessCallout 2-11
Business Objects 2-4, 2-7
D7-AddMeterReadJobInterval 2-7
D7-AddMeterReadJobScalar 2-7
D7-AddPingJob 2-7
D7-ConnectDisconnect 2-7
D7-ConnectDisconnectResp 2-7
D7-DeviceEventMappingLookup 2-4
D7-GetStatus 2-7
D7-GetStatusResponse 2-7
D7-HeadendUOMLookup 2-4
D7-InitialLoadIMDInterval 2-4
D7-InitialLoadIMDScalar 2-4
D7-IntStsCodeToCondMapLookup 2-5
D7-MeterReadResponseInterval 2-7
D7-MeterReadResponseScalar 2-7
D7-PingJobResponse 2-7
D7-ReplaceDeviceAtLocForDecomm 2-7
D7-ReplaceLocation 2-7
C
Communication Processes 2-6
D
Device Event Mapping 2-6
Device Events 2-4
O
Oracle Service Bus 2-3
OUAF 2-6
Overview 1-1
W
Web Services 2-12
AddMeterReadJobService 2-12
CommissionDecommissionService 2-12
ConnectDisconnectService 2-12
DeviceStatusCheckService 2-12
OnDemandReadService 2-12
X
XAI
configuration 2-8
inbound services 2-9
senders 2-11
E
External System 2-8
G
General Configuration 2-1
Index-1
Index-2
Download PDF