Oracle Utilities Smart Grid Gateway Adapter for Networked Energy Services

Administrative User Guide

Release 2.2.0.1

E80268-02

April 2017

Documentation build: 4.10.2017 11:41:36 [D4_1491849696000]

Copyright © 2011, 2017, Oracle and/or its affiliates. All rights reserved.

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

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

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

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

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

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

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

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Oracle Utilities Smart Grid Gateway Adapter for Networked Energy Services

This section documents the administrative functions for the Oracle Utilities Smart Grid Gateway Adapter for Networked Energy Services.

Next in This Section

- Networked Energy Services Adapter Overview

- Networked Energy Services Adapter Processing

- Configuring a Networked Energy Services Head-End System

- Configuring Networked Energy Services Extendable Lookups

- Configuring NES Usage and Event Extract Processing

- Extending the Networked Energy Services Adapter

Networked Energy Services Adapter Overview

The Oracle Utilities Smart Grid Gateway Adapter for Networked Energy Services (NES) supports two-way communication with the NES server. Communications include measurement data and device event loading, and command messaging in support of commissioning, connect, disconnect, decommissioning, and on-demand read.

The adapter uses Oracle Service Bus (OSB) and Oracle Business Process Execution Language Process Manager (BPEL PM) to facilitate communication between Oracle Utilities Smart Grid Gateway and NES.

Please refer to the release notes for product version information, a summary of the release functionality, and any known issues.

The following table describes the attributes of the adapter:

Attribute

Details

Currently Supported Version

Networked Energy Services 5.3

Protocol

Proprietary (NES specific)

Market(s)

Worldwide

Architecture

ANSI and IEC, PLC

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 NES system.

The following functionality is included:

Measurement Data and Device Event Loading - data parsing and transformation via Oracle Service Bus from NES 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 NES 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 NES application to initiate smart meter commands from Oracle Utilities Smart Grid Gateway. The NES 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.

Networked Energy Services Adapter Processing

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

Next in This Section

- Initial Measurement Data and Device Event Loading

- Device Communication

Initial Measurement Data and Device Event Loading

The initial measurement data load and subsequent device event processing use OSB to poll for, parse, and transform the head-end payloads into the Oracle Utilities Smart Grid Gateway service format. Payloads contain measurements and meter events in the format specific to the NES system. 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 NES processing as needed. A second service creates device events with data in a common format.

Next in This Section

- Initial Measurements

- Device Events

- Base Package Business Objects

Initial Measurements

Usage data is exported from the head-end system as a file in NES format and 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-D4-USAGE-BASE contains components responsible for the actual processing of incoming data. This should not be modified during configuration.

2. SGG-D4-USAGE-CM allows you to segment your customizations so that future upgrades of base functionality implemented in SGG-D4-USAGE-BASE do not affecting the customization and environment settings.

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

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

Element

Description

Valid Values

populateRaw

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

true

false

callPreProcessing

Determines if the preprocessing proxy service is called.

true

false

callPostProcessing

Determines if the postprocessing proxy service is called.

true

false

destinationRootElementInterval

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

destinationRootElementScalar

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

publishServices/service

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

filterUsage

Determines if usage should be filtered.

true

false

Publishing Initial Measurement Data

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

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

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

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

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

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

Filtering Initial Measurement Data

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

<filterUsage>true</filterUsage>

When filtering is enabled, only measurements whose <externalUOM> matches one of the values defined in the NES UOMCode Mapping Extendable Lookup extendable lookup (D4-HeadendUOMLookup) are passed into the system for processing.

Processing Large Input Files

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

Prioritized Initial Measurement Processing

The NES adapter prioritizes processing of initial measurements created from smart meter commands and/or completion events by setting the Execution Method flag in these types of initial measurements to “Real Time” (D1RT). In addition, initial measurements received with the Execution Method flag set to “Real Time” will be processed in real time rather than via batch processing.

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

Device Events

The device event data exported from the head-end system as a file in NES 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-D4-EVENT-BASE contains components responsible for the actual processing of incoming data. This should not be modified during configuration.

2. SGG-D4-EVENT-CM allows you to segment your customizations so that future upgrades of base functionality implemented in SGG-D4-EVENT-BASE do not affecting the customization and environment settings.

The runtime configuration settings for the SGG-D4-EVENT-CM project are stored in the EnvironmentSettings.xq XQuery file. You can use this file to adjust device event data processing. For example, if you want to load raw data you would specify “true” for the content of the populateRaw element.

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

Element

Description

Valid Values

populateRaw

Determines if the device event data is populated as raw data.

true

false

callPreProcessing

Determines if the preprocessing proxy service is called.

true

false

callPostProcessing

Determines if the postprocessing proxy service is called.

true

false

destinationRootElement

Holds the name of inbound web service for the device event seeder.

serviceProviderExternalId

The External ID of the NES service provider.

publishServices/service

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

filterEvents

Determines if events should be filtered.

true

false

Publishing Events

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

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

Publishing device events to Oracle DataRaker is supported by the following components provided with the SGG-D4-EVENT-CM OSB project:

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

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

Device event data is published in the “native” device event data format (the format of the device event seeder business object).

Filtering Events

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

<filterEvents>true</filterEvents>

When filtering is enabled, only device events whose <externalEventName> matches one of the values defined in the NES Device Event Mapping extendable lookup (D4-DeviceEventMappingLookup) are passed into the system for processing.

Prioritized Device Event Processing

The NES adapter prioritizes processing of device events created from smart meter commands and/or completion events by setting the Execution Method flag in these types of device events to “Real Time” (D1RT). In addition, device events received with the Execution Method flag set to “Real Time” will be processed in real time rather than via batch processing.

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

Base Package Business Objects

The NES adapter base package includes the following device, initial measurement, and device event business objects:

Business Object Name

Description

D4-InitialLoadIMDInterval

NES Initial Load IMD Interval

D4-InitialLoadIMDScalar

NES Initial Load MD Scalar

D4-SmartMeter

Smart Meter - NES

D4-EventExtractScheduler

NES Event Extract Scheduler

D4-PayloadExtractScheduler

Payload Extract Scheduler

D4-UsageExtractScheduler

NES Usage Extract Scheduler

Device Communication

The basic communication for all business processing is essentially the same. A communication request is sent from the Oracle Utilities application to NES. This request would be for a connect/disconnect, commission/decommission, measurement data or an on-demand read. The designated BPEL process transforms the request from Oracle Utilities format to NES format and invokes the related NES web service. NES then returns a reply, the BPEL process transforms the reply message back to the appropriate format so that Oracle Utilities can receive the response.

Next in This Section

- Communication Flows

- Device Communication Base Package Business Objects

- External System

- Outbound Message Types

- Inbound / Outbound Service Configuration

- BPEL Processes and Web Services

Communication Flows

The table below lists the communications created for each NES command:

Command

Outbound Communication

Inbound Communication

Completion Event

Remote Connect

Retrieve Meter Information

Read Load Status

Read Billing Data On-Demand

Connect Load

Read Load Status Notification

Read Billing Data On-Demand Notification

Connect Load Notification

Create IMD

Connect Device

Remote Disconnect

Disconnect Load

Read Billing Data On-Demand

Disconnect Load Notification

Read Billing Data On-Demand Notification

Create IMD

Disconnect Device

Device Commissioning

Add Meter Request

Set ATM Configuration

Set ATM Configuration Notification

Device Commissioning

Device Decommissioning

Decommission Meter Request

Decommission Meter Notification

Device Decommissioning

On-Demand Read

(Scalar)

Read Billing Data On-Demand

Read Billing Data On-Demand Notification

Create IMD

On-Demand Read

(Interval)

Read Load Profile On Demand

Read Load Profile On-Demand Notification

Create IMD

Commissioning and Decommissioning Communications

Commissioning a previously decommissioned NES device requires a different process than commissioning a new device.

When you commission a device for the first time, a commissioning command is sent to BPEL to create the meter in NES using the DeviceManager.CreateMeter command. If Automatic Topology Management is selected then the DeviceManager.SetATMConfiguration command is also sent.

When you decommission a device, BPEL sends the DeviceManager.Move command to NES for the device. In NES you need to confirm that the device has been moved to a non-DC tree. You then need to manually delete the device from the non-DC tree. To permanently decommission the device you must delete it by using the DeviceManager.Delete command from the NES interface.

To recommission a device that has been previously decommissioned, you need to log into NES and manually move the meter from the non-DC tree to the DC tree that it belonged to previously. This will not be possible if the device has been deleted from within NES.

Device Communication Base Package Business Objects

The NES base package includes the following communication business objects:

Meter Commissioning

Business Object

Description

D4-AddMeterRequest

Add Meter Request

D4-GenericAMIDeviceIdentifier

Generic AMI Device Identifier

D4-RetrieveMeterIdentifier

Retrieve Meter Identifier

D4-RetrieveMeterInfo

Retrieve Meter Information

D4-SetATMConfigNotification

Set ATM Configuration Notification

D4-SetATMConfiguration

Set ATM Configuration

Meter Decommissioning

Business Object

Description

D4-DecommMeterNotification

Decommission Meter Notification

D4-DecommMeterRequest

Decommission Meter Request

On-Demand Read

Business Object

Description

D4-ReadBillingData

Read Billing Data On-Demand

D4-ReadBillingDataNtf

Read Billing Data On-Demand Notification

D4-ReadLoadProfile

Read Load Profile On Demand

D4-ReadLoadProfileNtf

Read Load Profile On-Demand Notification

D4-ReadLoadStatus

Read Load Status

D4-ReadLoadStatusNtf

Read Load Status Notification

Remote Connect

Business Object

Description

D4-ConnectLoad

Connect Load

D4-ConnectLoadNtf

Connect Load Notification

Remove Disconnect

Business Object

Description

D4-DisconnectLoad

Disconnect Load

D4-DisconnectLoadNtf

Disconnect Load Notification

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 or Real-time)

- The corresponding message senders

- Batch Control (if Processing Method is set to Batch)

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

Outbound Message Types

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

Outbound Message Type

Description

D4-ADDMETREQ

Add Meter Request

D4-CONLOAD

Connect Load

D4-DECMETREQ

Decommission Meter Request

D4-DISCONLD

Disconnect Load

D4-HNLBATEVT

NES - Handle Batch Event

D4-HNLBATUSG

NES - Handle Batch Usage

D4-RDLOADST

Read Load Status

D4-READLP

Read Load Profile

D4-READOUT

Read Billing Data

D4-RETMETID

Retrieve Meter Identifier

D4-RETRIEVE

Retrieve Meter Information

D4-SETATMCFG

Set ATM Configuration

Inbound / Outbound Service Configuration

The inbound/outbound message utility allows you to configure your system to receive information from and to send information to external applications using XML. The Smart Grid Gateway Adapter for NES uses one inbound web service to map device events. This is the same inbound web service used by the D1 application.

Inbound Web Services

Inbound web services 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 inbound web 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 NES uses the following inbound web services to import usage and device events:

Inbound Web Service

Description

D1-DeviceEventSeeder

Used for upload of device events.

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-InitialLoadIMD

Used for initial measurement upload.

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.

The Oracle Utilities Smart Grid Gateway Adapter for NES includes the following inbound web services for receiving communications from the NES:

Inbound Web Service Name

Description

D4-ConnectLoadNotification

Connect Load Notification

D4-DecommMeterNotificationXAI

Meter Decommission Notification

D4-DisconnectLoadNotification

Disconnect Load Notification

D4-ReadBDNotificationXAI

Read Billing Data On-Demand Notification

D4-ReadingATMConfigNotification

Get Response Initiate Read By Meter Number

D4-ReadLoadStatusNotification

Read Load Status Notification

D4-ReadLPNotificationXAI

Read Load Profile On-Demand Notification

Message Senders

Message 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 message senders you need to create is based on the types of messages the system is designed to accept.

The Oracle Utilities Smart Grid Gateway Adapter for NES includes the following message senders:

Message Sender

Description

D4-ADDMETREQ

Add Meter Request

D4-CONLOAD

Connect Load

D4-DECOMMIS

Device Decommissioning

D4-DISCONLD

Disconnect Load

D4-HNLBATEVT

NES Handle Batch Event

D4-HNLBATUSG

NES Handle Batch Usage

D4-RDLOADST

Read Load status

D4-READBILLD

NES On-Demand Read (Scalar)(2)

D4-READLP

Read Load Profile

D4-RETMETID

Retrieve Meter Identifier

D4-RETRIEVE

Retrieve Meter Information

D4-ReadBill

Read Billing Data

D4-SETATMCFG

Set ATM Configuration

BPEL Processes and Web Services

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

All web services receive XML from an incoming service then transform the call to a format which is recognized by the NES system.

CreateMeter: Receives the incoming XML from the message sender service, transforms it to the NES API parameters node, passes it to the DeviceManager.Create NES API web service method then collects XML from CreateMeter to be returned to Oracle Utilities Smart Grid Gateway.

Messages

CreateMeter RequestMessage: Contains the parameters which are formatted from Oracle Utilities Smart Grid Gateway to match the incoming XML for the NES API DeviceManager.Create method.

CreateMeter ResponseMessage: Contains the Device ID that is used when the DeviceManager.Create method validates the security key and the XML parameters successfully.

Related Processes

Meter Commissioning
ConnectLoadRemoteConnect
Receives the incoming XML from the D4-CONLOAD (Connect Load) message sender in Oracle Utilities Smart Grid Gateway and transforms to NES format.
GrabBatchEvents
Retrieves the un-processed events from the event repository; transforms each batch to replace GUID identifiers with a readable form, and finally prepares a new file for OSB before deleting the batch of events. The scheduled call to this service can contain the preferred dates to query for or can accept the default which is the previous day usage.

Messages

GrabBatchEventsSoapIn

GrabBatchEventsSoapOut
GrabBatchUsage
Retrieves the un-processed usage from the usage repository; transforms each batch to replace GUID identifiers with a readable form, and finally prepares a new file for OSB before deleting the batch of usage. The scheduled call to this service can contain the preferred dates to query for or can accept the default which is the previous day usage.

Messages

GrabBatchUsageSoapIn

GrabBatchUsageSoapOut

Related Processes

Connection

Event Management

Usage Processing
MeterDecommissioning
Receives the incoming XML from the message senderOutbound service and transforms to NES API parameters node to be passed to the DeviceManager.Move NES API web service method. The process then collects the return XML to be returned to Oracle Utilities Smart Grid Gateway.

Messages

MeterDecommissioningRequestMessage: This message is the input for the Move method. The method contains the parameters conveniently formatted from Oracle Utilities Smart Grid Gateway to match the incoming XML for the NES API DeviceManager.Move method.

MeterDecommissioningResponseMessage: This message contains status stating that the DeviceManager.Create method validated the security key and the XML parameters are accepted successfully. If the status is SUCCEEDED, it also contains Tracking ID for the call, Device ID and StatusType ID.

Related Processes

Meter Decommissioning
PerformCommand
This web service facilitates most of the communication between Oracle Utilities Smart Grid Gateway and the NES system. If your implementation requires functionality that was not delivered as part of the base package this web service will play an integral part in managing those customizations.

PerformCommand executes a command which generates the events that advance the Oracle Utilities Smart Grid Gateway lifecycle then returns the output string to the caller. The output might be a tracking ID or information about a device.

Messages

PerformCommandSoapIn: The sXmlParameters input is prepared from within Oracle Utilities Smart Grid Gateway to execute primarily a group of five commands, these are Read Load Status, On-Demand Read, Connect Load, Disconnect Load and Set ATM Configuration.

PerformCommandSoapOut:

The return from PerformCommand is the xml from the DeviceManager.PerformCommand for Read Load Status, On-Demand Read, Connect Load, Disconnect Load and Set ATM Configuration.
ReceivePanoramixEvents
This web service is actually never called by the implementation, but rather it is called by NES and is needed when configuring the NES server.

ReceivePanoramixEvents obtains the APIKey from the NES authentication service, then, with the event definition ID from the parameter list for this service, switches to the branch for the event definition to begin any specific processing. For example, an on-demand read completion event means that the BPEL PM process needs to retrieve the usage using the RESULTID found in the event xml. All events and usage to be passed on to Oracle Utilities Smart Grid Gateway must first be transformed to replace the GUID with a readable form items. This involves using the BPEL PM DVM lookup functionality.

Messages

ReceivePanoramixEventsSoapIn

ReceivePanoramixEventsSoapOut

Related Processes

Event Management
PrePerformCommandCallout / PostPerformCommandCallout
These web services are hooks designed to allow customization of messages just prior and just after sending them to the NES server. Your implementation may wish to modify the data for special purposes. This is the one of the only places where modification of BPEL PM code is allowed.
ReceivedPanoramixEventsCallout
This web service is a hook designed to allow customization of messages just prior and just after sending them to the NES server. Your implementation may wish to modify the data for special purposes. This is one of the only places where modification of BPEL PM code is allowed.
ReadBillingDataOnDemand
This web service method, initiate a call to NES system with formatted inbound xml parameter. First it transforms the Parameters received from the calling system in to NES system recognizable format. Then it invokes a call to the NES system's Device Manager Service. When the call is invoked the system receives the return XML from DeviceManager stating the status of the command execution and, if succeeded, the tracking ID of this call.

Messages

ReadBillingDataOnDemandRequestMessage: Contains the input parameter for DeviceManager Perform Command to read billing data OnDemand. It formats parameters from the calling system to match incoming XML for the NES DeviceManager.PerfomCommand method.

ReadBillingDataOnDemandResponseMessage: Transforms the response xml from NES system format to Oracle Utilities Smart Grid Gateway format.

Related Processes

On Demand Reads
ReadLoadProfileOnDemand
This web service method, initiate a call to NES system's Device Manager Service with formatted inbound xml parameter. First it transforms the Parameters received from the calling system in to NES system recognizable format. Then it invokes a call to the NES system thru Device Manager Service. After invoking the call, the system receives the response message from DeviceManager stating the status of the command execution and, if succeeded, the tracking ID of this call.

Messages

ReadLoadProfileOnDemandRequestMessage: This message is for interval on demand read request to the NES system. Transforms the incoming XML from Oracle Utilities Smart Grid Gateway to NES recognizable format.

ReadLoadProfileOnDemandResponseMessage: Transforms the response xml for ReadLoadProfileOnDemandRequest from NES system format to Oracle Utilities Smart Grid Gateway format.

Related Processes

On Demand Reads
ReadLoadStatusRemoteConnect
Receives the incoming XML from the D4-RDLOADST ( Read Load Status) message sender in Oracle Utilities Smart Grid Gateway and transforms to NES format.
RemoteDisconnect
Receives the incoming XML from the D4-DISCONLD (Disconnect Load) message sender in Oracle Utilities Smart Grid Gateway and transforms to NES format.
RetrieveMeterInfo
Initiates a call to the Request Management Service with formatted inbound xml parameters. First it transforms the Parameters received from the calling system in to NES system recognizable format. Then it invokes a call to the NES system thru Request Management Service and retrieves a response with Meter Information.

Messages

RetrieveMeterInformationRequestMessage: Contains the input parameter for DeviceManager Perform Command to retrieve meter information. It also formats parameters from the calling system to match incoming XML for the NES DeviceManager.PerfomCommand method.

RetrieveMeterInformationResponseMessage: Transforms the response xml from NES system format to Oracle Utilities Smart Grid Gateway format.

Related Processes

Remote Disconnect

Remote Connect
RetrieveMeterIdentifier
Receives a call from Oracle Utilities Smart Grid Gateway for RetrieveMeterIdentifier process and invokes the RetrieveByParameter method in the NES system's DeviceManager service.

Converts incoming Oracle Utilities Smart Grid Gateway formatted input to sXmlParameters in NES format then invokes RetrieveMeterIdentifier.

Messages

RetrieveMeterIdentifierRequestMessage: Transforms the xml received from the calling system to match incoming XML for the NES API DeviceManager.RetrieveByParameter method. This method requires the Type of ID and the associated ID as input.

RetrieveMeterIdentifierResponseMessage: When the XML is synchronously returned from the head-end system for the RetrieveByParameter call, the DEVICEID node is only included in the APIPAYLOAD if the status of the call is Succeeded.

Related Processes

Meter Commissioning
SetATMConfiguration
This web service method is specific to set Automated Topology Management (ATM) configuration command which assigns the Meter to the Data Concentrator.

Converts incoming Oracle Utilities Smart Grid Gateway formatted input to sXmlParameters in NES format then invokes the DeviceManager PerformCommand. A connection should establish to begin the NES command processing.

Messages

SetATMConfigurationRequestMessage: This message is the input for the SetATMConfiguration method. The method contains the parameters conveniently formatted from Oracle Utilities Smart Grid Gateway to match the incoming XML for the NES API DeviceManager.PerformCommand method where the COMMANID is Constants.DeviceCommands.SET_ATM_CONFIGURATION

SetATMConfigurationResponseMessage: when the XML is synchronously returned from the head-end system for the PerformCommand call, the COMMAND node is only included in the APIPAYLOAD if the status of the call is Succeeded.

Related Processes

Meter Commissioning

NES Web Services

The following table describes NES web services and operations used for the Oracle Utilities Smart Grid Gateway command messaging:

Smart Grid Gateway Commands

AMI Adapter Business Objects

NES Web Services

NES Operations

Device Commissioning

D4-AddMeterRequest

D4-RetrieveMeterIdentifier

D4-SetATMConfiguration

DeviceManager

Create

RetrieveByParameter

PerformCommand:

SET_ATM_CONFIGURATION

Device Decommissioning

D4-DecommMeterRequest

DeviceManager

PerformCommand:

MOVE_DEVICE_ADD

Remote Connect

D4-ConnectLoad

D4-ReadLoadStatus

D4-RetrieveMeterInfo

DeviceManager

Retrieve

PerformCommand:

CONNECT_LOAD

READ_LOAD_STATUS

Remote Disconnect

D4-DisconnectLoad

DeviceManager

PerformCommand:

DISCONNECT_LOAD

On-Demand Read

D4-ReadBillingData

DeviceManager

PerformCommand

Command ID:

READ_BILLING_DATA_ON_DEMAND (Scalar)

READ_LOAD_PROFILE_ON_DEMAND (Interval)

Configuring a Networked Energy Services Head-End System

This section outlines the configuration required for the Oracle Utilities Smart Grid Gateway NES Adapter to communicate with the NES software.

Next in This Section

- Inbound Web Services

- Message Senders

- Outbound Message Types

- External System

- Service Provider

- Processing Methods

- Configuring Endpoint URIs

Inbound Web Services

Inbound web 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 NES in response to a command request.

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

Inbound Web Service Name

Description

D1-BulkRequestHeader

Bulk Request Header

D1-BulkRequestUpdate

Bulk Request Update

D1-BulkResponse

Bulk Response

D1-DeviceEventSeeder

Device Event Seeder

D1-InitialLoadIMD

IMD Seeder

D1-PayloadErrorNotif

Payload Error Notification

D1-PayloadStatistics

Payload Statistics

D1-PayloadSummary

Payload Summary

D4-ConnectLoadNotification

Connect Load Notification

D4-DecommMeterNotificationXAI

Meter Decommission Notification

D4-DisconnectLoadNotification

Disconnect Load Notification

D4-ReadBDNotificationXAI

Read Billing Data On-Demand Notification

D4-ReadingATMConfigNotification

Get Response Initiate Meter Read By Meter Number

D4-ReadLoadStatusNotification

Read Load Status Notification

D4-ReadLPNotificationXAI

Read Load Profile On-Demand Notification

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

Message Options

- Trace: No

- Debug: No

- Active: Yes

Operations

- Operation Name: Same as web service name

- Schema Type: Business Object

- Schema Name: Applicable business object code

- Transaction Type: Add

Message Senders

Message senders define the details of how messages are sent to an external system, such as messages containing device command requests.

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

Message Sender

Description

D4-ADDMETREQ

Add Meter Request

D4-CONLOAD

Connect Load

D4-DECOMMIS

Device Decommissioning

D4-DISCONLD

Disconnect Load

D4-HNLBATEVT

NES Handle Batch Event

D4-HNLBATUSG

NES Handle Batch Usage

D4-RDLOADST

Read Load status

D4-READBILLD

NES On-Demand Read (Scalar)(2)

D4-READLP

Read Load Profile

D4-RETMETID

Retrieve Meter Identifier

D4-RETRIEVE

Retrieve Meter Information

D4-ReadBill

Read Billing Data

D4-SETATMCFG

Set ATM Configuration

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

Main Tab:

- Invocation Type: Real-time

- Message 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/echelon/<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/D4/<SERVICE>/<SERVICE>

where:

- <OPERATION>: the operation performed by the message 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>: 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 message 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

D4-ADDMETREQ

Add Meter Request

D4-CONLOAD

Connect Load

D4-DECMETREQ

Decommission Meter Request

D4-DISCONLD

Disconnect Load

D4-HNLBATEVT

NES - Handle Batch Event

D4-HNLBATUSG

NES - Handle Batch Usage

D4-RDLOADST

Read Load Status

D4-READLP

Read Load Profile

D4-READOUT

Read Billing Data

D4-RETMETID

Retrieve Meter Identifier

D4-RETRIEVE

Retrieve Meter Information

D4-SETATMCFG

Set ATM Configuration

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

- External System: NES

- Description: NES

- Outbound Message Types::

Outbound Message Type

Message Sender

D4-ADDMETREQ

D4-ADDMETREQ

D4-CONLOAD

D4-CONLOAD

D4-DECMETREQ

D4-DECOMMIS

D4-DISCONLD

D4-DISCONLD

D4-HNLBATEVT

D4-HNLBATEVT

D4-HNLBATUSG

D4-HNLBATUSG

D4-RDLOADST

D4-RDLOADST

D4-READLP

D4-READBILLD

D4-READOUT

D4-READLP

D4-RETMETID

D4-RETMETID

D4-RETRIEVE

D4-RETRIEVE

D4-SETATMCFG

D4-SETATMCFG

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

- Processing Method: Real-time

- Message XSL: D4-Request xsl

- Response XSL: D4-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 NES 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 - NES

- Service Provider: NES

- Description: NES

- External Reference ID: NES

- External System: D4-NES

- Out Name/ID in Their System:

- AMI Device ID Type: Internal Meter Number

- AMI Measuring Component ID Type: Channel ID

Processing Methods

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

The following types of processing methods must be configured for the NES 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 inbound web service uses this processing method to determine which type of initial measurement business object to instantiate when receiving usage from the NES.

Device Event Mapping

Device event mapping processing methods define how head-end-specific device events are mapped to standard device event names. The Device Event Seeder inbound web service uses this processing method to determine which type of device event business object to instantiate when receiving device events from the NES.

UOM Translation

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

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 NES service provider, based on the requirements of each implementation using the “How to Create OB COMM/Send OB Message” processing method business object (D1–HowToCreateActivityOBComm).

Command

Processing Role

Default Business Object

Default Outbound Message Type

Device Commission

Device Registration

D4-SetATMConfiguration

Set ATM Configuration

Device Decommission

Device Removal

D4-DecommMeterRequest

Decommission Meter Request

On-Demand Read (Scalar)

On-Demand Read (Scalar)

D4-ReadBillingData

Read Billing Data

On-Demand Read (Interval)

On-Demand Read (Interval)

D4-ReadLoadProfile

Read Load Profile

Device Status Check

Device Status Check

D4-ReadLoadStatus

Read Load Status

Remote Connect

Remote Connect

D4-ConnectLoad

Connect Load

Remote Disconnect

Remote Disconnect

D4-DisconnectLoad

Disconnect Load

Other Processing Methods

This section outlines details for other processing methods used by the NES adapter.

Processing Role

Default Business Object

Default Outbound Message Type

NES Add Meter Request

D4-AddMeterRequest

Commission

NES Retrieve Meter Identifier

D4-RetrieveMeterIdentifier

Commission Retrieve Meter Identifier

NES Retrieve Meter Information

D4-RetrieveMeterInfo

Retrieve Meter Info

Configuring Endpoint URIs

Part of configuring your NES adapter is configuring your BPEL composites to work with your head-end system by defining the appropriate Endpoint URIs for each of the commands.

The default approach to defining Endpoints URIs is redeployment or reinstallation or the BPEL composites. For example, by default, changing an adapter from using the test harness to a production environment using the actual head end system requires editing the appropriate installation menu options and redeploying the BPEL composites. The Endpoints URIs defined during installation and deployment for each adapter are listed in the Smart Grid Gateway Installation and Configuration Worksheets section of the Oracle Utilities Smart Grid Gateway Installation Guide.

You can also use an “Endpoint Override” Domain Value Map (DVM) to override Endpoints URIs defined during deployment and installation. This DVM allows defining specific keys that provide an alternate URL that will override the original installed value. Endpoint Override DVMs can be edited using the Oracle SOA Composer.

The NES endpoint override DVM (D4–EndpointOverrides.dvm) uses a specific set of keys, each used for one or more commands. The table below lists the DVM keys available for the NES adapter and the command used with each:

DVM Key

Commands

DeviceManager

Remote Connect

Remote Disconnect

Device Commissioning

Device Decommissioning

On-Demand Read (Scalar)

On-Demand Read (Interval)

EventManager

On-Demand Read (Scalar)

On-Demand Read (Interval)

GatewayManager

Remote Connect

Remote Disconnect

Device Commissioning

Device Decommissioning

On-Demand Read (Scalar)

On-Demand Read (Interval)

SettingManager

Remote Connect

Remote Disconnect

Device Commissioning

Device Decommissioning

On-Demand Read (Scalar)

On-Demand Read (Interval)

UserManager

Remote Connect

Remote Disconnect

Device Commissioning

Device Decommissioning

On-Demand Read (Scalar)

On-Demand Read (Interval)

ProcessCallout

User Exit Functions

To define an override Endpoint URI for the NES adapter, use the following procedure:

1. Open the SOA Composer for your BPEL configuration.

The URL for the SOA Composer is http://server:port/soa/composer.

2. Select the D4–EndpointOverrides.dvm in the left panel.

- In Fusion Middleware v12.2.1, this is located under Shared in the Deployment View, or under Domain Value Maps in the Types View.

- In Fusion Middleware v12.2.2, this is located under Metadata in the Deployment View.

The DVM will open in the right panel. The Description field lists the available keys for the DVM (only the first key is shown, but you can scroll through the contents to view the list. The panel also displays a list of previously defined keys.

3. Click the Create Session button (above the left panel) to begin an editing session.

4. Click the Add Domain Values icon (“+”) to add a new key.

The Add Domain Values dialog opens.

5. Enter the appropriate values in the Add Domain Values dialog as follows:

- key: The DVM key for the Endpoint URI you wish to define (see the table above).

- EndpointURI: The override Endpoint URI.

6. Click OK.

The new DVM value will appear in the list of keys.

7. Click the Save icon to save the DVM values.

8. Click the Publish button to activate all the changes in the editing session.

Enter an optional note for the session in the Publish Session dialog.

Changes take effect immediately upon publishing the session.

Click Discard to discard your changes.

Click Exit to exit your current session. Note that your session will still be open if you exit. Use Discard to end your session without making changes.

Configuring Networked Energy Services Extendable Lookups

This section outlines some of the extendable lookups that must be configured for use with the NES adapter. Refer to the Oracle Utilities Application Framework documentation for more information about working with extendable lookups.

NES Device Event Mapping

The NES Device Event Mapping extendable lookup is used to determine which type of device event business object to instantiate when receiving device events from NES.

Each value defined for the NES Device Event Mapping extendable lookup should include the following:

- Head-End System Event Name: The event name used by the NES

- Description: A description of the device event

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

NES UOM Code to Standard UOM Mapping

Usage received from NES may use utility-specific unit of measures (UOMs). These custom UOMs must be mapped to standard UOM codes. The NES UOM Code Mapping Extendable Lookup is used to determine how to map NES UOM codes to standard UOM codes when receiving usage from the NES.

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

- Head-end UOM: The unit of measure code used by the NES

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

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

NES Interval Status Code to Condition Mapping

Interval usage received from the NES can include NES 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 NES Interval Status Code to Condition Mapping extendable lookup is used to determine how to map NES interval status codes to standard status codes when receiving usage from the NES.

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

- Interval Status: The NES interval status code

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

- Description: A description of the interval status code.

- Priority: The priority of the interval status code, represented as a numeric value where larger numbers correlate to higher priorities.

Other Extendable Lookups

Business Object

Description

D4-EntityTypeLookup

Entity Type

D4-ExtServiceReturnCodeLookup

External Service Return Code

D4-GatewayTypeLookup

Gateway Type

D4-IDTypeLookup

ID Type

D4-InformationReturnTypeLookup

Information Return Type

D4-LoadVoltageStatusTypeLookup

Load Voltage Status Type

D4-TaskPriorityLookup

Task Priority

D4-TimeZoneManagerLookup

Time Zone Manager

Configuring NES Usage and Event Extract Processing

Usage and events received from the NES server must be requested from Oracle Utilities Smart Grid Gateway. Extract requests for usage and events are triggered by a batch process, and sent to the NES via middleware. The NES compiles a batch of usage or events and sends it to BPEL services to create a file to be processed by Oracle Service Bus (OSB) services, it is then loaded as SGG events and/or usage.

This section describes the processing performed by the extract request process, and the configuration steps involved.

Next in This Section

- Extract Request Processing

- Extract Request Configuration Steps

- Executing Extract Requests

Extract Request Processing

This section provides a detailed description of the extract request process.

- The “Usage / Event Extract Scheduler Monitor” batch process (D1-EXTSC) checks for “NES Usage Extract Scheduler” or “NES Event Extract Scheduler” activities that are in the “Active” state, and transitions these to the “Send Request” state. It also updates the “Latest Request Start Date/Time” and “Latest Request End Date/Time” fields on the activity based on the date and time of the request.

- When the activity enters the “Send Request” state, an Enter algorithm (either “Usage Extract Scheduler Send Request” (D4-USGSNDREQ) or “Event Extract Scheduler Send Request” (D4-EVTSNDREQ)) sends a request via an message sender to the middleware (via the GrabBatchUsage or GrabBatchEvent BPEL services), which in turn send the request to the NES server.

- After the request is sent, the “NES Usage Extract Scheduler” or “NES Event Extract Scheduler” activity to set back to the “Active” state.

- The NES server calls the BPEL services “GrabBatchEvents” and “GrabBatchUsage.” BPEL then routes the incoming events or usage to a file system, which is used by OSB components to process the usage or events.

Extract Request Configuration Steps

This section outlines the objects that must be configured to support batch extracts of usage and events from an NES head-end system. To configure the NES Adapter to support sending extract requests for usage and events, you must do the following:

- Create message senders (one for usage, one for events) to send extract requests.

- Create Outbound Message Types (one for usage, one for events) for extract requests.

- Associate the message senders and Outbound Message Types to the External System used with the head-end system service provider

- Create “NES Usage Extract Scheduler Type” and “NES Event Extract Scheduler Type” activity types.

- Create “NES Usage Extract Scheduler” and “NES Event Extract Scheduler” activities.

The following sections provide details for configuring these object. Refer to the Oracle Utilities Application Framework documentation for more information about creating message senders, Outbound Message Types, and External Systems.

Note: Configuration of the OSB and BPEL services used by this process is done when installing and configuring the OSB and BPEL components of the NES Adapter.

Message Sender - NES Handle Batch Event

Create an message sender for event extracts as follows:

Main Tab:

- Message Sender: Enter a code for the batch event message sender (D4-HNLBATEVT)

- Description: NES Handle Batch Event

- Invocation Type: Real-time

- Message Class: RTHTTPSNDR (Sender routes messages via HTTP real-time)

- Active: True (checked)

- MSG Encoding: UTF-8 message encoding

Context Tab:

- HTTP Header: SOAPAction:http://xmlns.oracle.com/ouaf/NES/GrabBatchEvents

- HTTP Login User: <USER_ID>

- HTTP Login Password: <PASSWORD>

- HTTP Method: POST

- HTTP URL 1: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/NES/HandleBatchEvent/BatchEventHandler

where:

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

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

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

Message Sender - NES Handle Batch Usage

Create an message sender for usage extracts as follows:

Main Tab:

- Message Sender: Enter a code for the batch usage message sender (D4-HNLBATUSG)

- Description: NES Handle Batch Usage

- Invocation Type: Real-time

- Message Class: RTHTTPSNDR (Sender routes messages via HTTP real-time)

- Active: True (checked)

- MSG Encoding: UTF-8 message encoding

Context Tab:

- HTTP Header: SOAPAction:http://xmlns.oracle.com/ouaf/NES/GrabBatchUsage

- HTTP Login User: <USER_ID>

- HTTP Login Password: <PASSWORD>

- HTTP Method: POST

- HTTP URL 1: http://<EM_SERVER>:<EM_SERVER_PORT>/soa-infra/services/NES/HandleBatchUsage/BatchUsageHandler

where:

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

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

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

Outbound Message Type - NES Handle Batch Event

Create an Outbound Message Type for event extract requests as follows:

- Outbound Message Type: Enter a code for the batch event Outbound Message Type (D4-HNLBATEVT)

- Description: NES Handle Batch Event

- Business Object: D1-OutboundMessage

- Priority: - Priority 20 (or lower)

Outbound Message Type - NES Handle Batch Usage

Create an Outbound Message Type for usage extract requests as follows:

- Outbound Message Type: Select a code for batch usage Outbound Message Type (D4-HNLBATUSG)

- Description: NES Handle Batch Usage

- Business Object: D1-OutboundMessage

- Priority: Priority 20 (or lower)

External Systems

Add the event and usage extract Outbound Message Types and message senders to the external system used for the NES head-end system as follows:

- External System: NES

- Description: NES

- Outbound Message Types:

Outbound Message Type

Message Sender

D4-HNLBATEVT

D4-HNLBATEVT

D4-HNLBATUSG

D4-HNLBATUSG

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

- Processing Method: Real-time

- Message XSL: D4-Request xsl

- Response XSL: D4-Response.xsl

Activity Type - NES Event Extract Scheduler

Create an Activity Type for event extract requests as follows:

- Activity Type: Enter a code for the activity type (NES-EVENT-EXTRACT)

- Description: Enter a description for the activity type (NES Event Extract Scheduler Type)

- Related Transaction BO: NES Event Extract Scheduler

- Activity Type Status: Active

- Outbound Message Type: NES Handle Batch Event

- External System: The external system used for the NES head-end system

- Exception Handling:

- To Do Type: Activity To Do Type

- To Do Role: System Default Role

- Retry Frequency: Select retry frequency in case if Activity reaches an error state (00:03:00)

- Maximum Retries: Select max number of times the activity will be retried - since it reached the error state (1)

- Discard Reason: Select from the dropdown if available.

Activity Type - NES Usage Extract Scheduler

Create an Activity Type for usage extract requests as follows:

- Activity Type: Enter a code for the activity type (NES-USAGE-EXTRACT)

- Description: Enter a description for the activity type (NES Usage Extract Scheduler Type)

- Related Transaction BO: NES Usage Extract Scheduler

- Activity Type Status: Active

- Outbound Message Type: NES Handle Batch Usage

- External System: The external system used for the NES head-end system

- Exception Handling:

- To Do Type: Activity To Do Type

- To Do Role: System Default Role

- Retry Frequency: Select retry frequency in case if Activity reaches an error state (00:03:00)

- Maximum Retries: Select max number of times the activity will be retried - since it reached the error state (1)

- Discard Reason: Select from the dropdown if available.

Activity - NES Event Extract Scheduler

Initiate an Activity for event extract requests as follows:

1. Select Main->Communication->Activity+

2. Select "NES Event Extract Scheduler Type" from the Activity Type drop-down list.

3. Enter the number of hours for each extract request in the Number of Hours of Data Request field. The default is 24.

4. Optional: Enter start and end dates and times for the first extract request in the Current Request Start Date/Time and Current Request End Date/Time fields.

Note that these are optional fields. If not populated, the values are populated as follows:

- Current Request Start Date/Time: taken from the last request stop date/time (which is populated by the “Event Extract Scheduler Send Request” algorithm (D4-EVTSNDREQ)

- Current Request End Date/Time: the Current Request Start Date/Time plus the number of hours in the Number of Hours of Data Request field.

Activity - NES Usage Extract Scheduler

Initiate an Activity for usage extract requests as follows:

1. Select Main->Communication->Activity+

2. Select "NES Usage Extract Scheduler Type" from the Activity Type drop-down list.

3. Enter the number of hours for each extract request in the Number of Hours of Data Request field. The default is 24.

4. Optional: Enter start and end dates and times for the first extract request in the Current Request Start Date/Time and Current Request End Date/Time fields.

Note that these are optional fields. If not populated, the values are populated as follows:

- Current Request Start Date/Time: taken from the last request stop date/time (which is populated by the “Usage Extract Scheduler Send Request” algorithm (D4-USGSNDREQ)

- Current Request End Date/Time: the Current Request Start Date/Time plus the number of hours in the Number of Hours of Data Request field.

Executing Extract Requests

To schedule and execute usage and device event extract requests, set up the “Usage / Event Extract Scheduler Monitor” batch process (D1-EXTSC) to run at a frequency appropriate to when you wish to retrieve usage and device events from the NES. For example, to retrieve usage and device events on a daily basis, schedule the “Usage / Event Extract Scheduler Monitor” batch process (D1-EXTSC) to run once every 24 hours.

Extending the Networked Energy Services Adapter

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

- Commission Device

- Decommission Device

- Device Status Check

- On-Demand Read

- Remote Connect

- Remote Disconnect

The Adapter for NES can be extended to support additional commands provided by the NES.