Example: Itron On-Demand Read Process

This section provides an example of an asynchronous command, the On-Demand Read command supported by the Itron OpenWay adapter.

The Itron www.itron.com.ami.2008.10.data.wsdl definition contains a series of commands for an On-Demand Read process. The Smart Grid Gateway adapter for Itron OpenWay initiates the process by invoking the ContingencyReadByEndpoints method. The reply contains a “request token ID” that identifies the entire flow and will be shared by subsequent communications. On the Itron side, a job for collecting usage and events is configured. To inform the caller (SGG) that the job is starting, Itron sends a StatusChanged request (defined in www.itron.com.ami.2008.10.common.wsdl) containing “State = Initialized”. Itron sends another StatusChanged request to notify SGG that the process of gathering the usage is underway. As the usage is collected, Itron submits one or more DataArrived requests to SGG. When Itron has finished making internal requests for usage, it sends a final StatusChanged request to SGG. That completion notification informs SGG that it should submit GetContingencyReadByEndpointsResult, the reply to which contains information about errors encountered during the process.

The image below illustrates the process flow used by this command.

Below is a summary of the important features of the Smart Grid Gateway implementation of this command. Many of the concepts can be applied when creating a custom synchronous command.

Command Activity — On-Demand Read (Interval)

Business Object: D1-OnDemandReadInterval

Lifecycle and Algorithms

The table below outlines some of the important algorithms used by the On-Demand Read (Interval) command activity.

Lifecycle State Algorithms

Validate

The important features here are not the specific algorithms, but rather the ability to perform validation logic at a process level.

  • D1-VALDEVMC – Validate that Device has appropriate Measuring Component: This algorithm ensures the device has at least one measuring component whose Measuring Component Type is registered as interval type

  • D1-VALIDCMD – Validate Headend's capability to perform On Demand Read (Interval): This algorithm checks whether the head end system has the capability to support an on-demand read request. If the command is supported, an outbound communication business object is returned.

  • D1-CHKMST – Check for existing Measurements: This algorithm checks whether complete measurements for the specified time period exist in the database already.

Connection Ready

  • D1-CODRIOB – Create Outbound communication for OnDemandRead Interval: This algorithm creates an outbound communication business object based on the Processing Role and algorithm parameters. The algorithm will look up the outbound communication business object defined for the Processing Role parameter and create an instance of that business object. In the case of this business object, the parameter is D1IN and it should create an instance of the D8-ReadIntervalDR business object.

Once the Outbound Communication record is created, the Activity business object moves from the Connection Ready state to the Communication In Progress state. When the outbound communication is complete, it moves the Activity to next default state, which is Connection Ready (the activity moves from Communication In Progress back to Connection Ready). The outbound communication will also set the “isOnDemandReadComplete” flag value in the activity business object, in this case, indicating the outbound communication for a particular processing role was created. If the condition is true, the processing moves on to next algorithm.

  • D1-CODRSRTOB – Create On Demand Read Results Outbound based on Completion Flag: This algorithm is the second algorithm in this state responsible for sending outbound communications. If the completion flag passed as a parameter is true, it will create the second outbound communication. In this example, it should create an instance of D8-ReadOnDemandReadResultDR to send a second request to Itron for the results of the Contingency Read operation.

Waiting for Measurement

  • D1-RIINTM – Retrieve Interval Initial Measurements: This algorithm retrieves the most recent Initial Measurement Data for each interval measuring component for the period of the measurement requested.

Outbound Communication — Itron - Contingency Read (Interval)

Business Object: D8-ReadIntervalDR

Schema

The portions of the schema that contain the payload of the web service request and response communications are the sendDetail element (constructed using the D8-ContingencyReadRequestDR data area) and the responseDetail element (constructed using the D8-ContingencyReadResponDtlDA data area). The XSLs used to create or decipher XML conforming to the Itron structure use these elements as a basis.

Lifecycle and Algorithms

The table below outlines some of the important algorithms used by the Contingency Read outbound communication.

Lifecycle State Algorithms

Validate

  • D1-VALCOMTP – Validate Communication Type: This algorithm ensures the communication type is populated on the communication.

Awaiting Response

  • D8-PSDMRSCDR – Itron - Populate Send Detail for ContingencyReadByEndpoints Direct Route: This algorithm populates the sendDetail element with the needed items for the web service input.

  • D8-COUTMINDR – Itron - Create Outbound Message Contingency Read (Interval): This algorithm determines the correct outbound message to create based upon the input processing role. The reply from the head end system will be stored in the responseDetails element and log entries will be created for the creation of the outbound message and the result (whether it is a success or a failure).

Response Error

  • D8-RBORINTER – Itron - Retry Read Interval BO in Error: This algorithm provides a means to retry the communication in the event of an error.

Completed

  • D1-UCFLAGTPA – Update On-Demand Read Completion Flag And Transition Parent Activity: If requirements are met, this algorithm sets the completion flag on the parent activity to “true” and transitions it to the next state.

Inbound Communication — Itron - StatusChanged

Business Object: D8-StatusChanged

This business object handles the inbound StatusUpdate requests. It contains the request token ID created by the initial request. When it receives schema values of “State = Completed” and Result of either Canceled or Success, it triggers the next command in the Activity. For On-DemandRead, the next command is GetContingencyReadByEndpointsResult.

Schema

Unlike other communications containing sendDetail or responseDetail elements, this business object contains an input element with child elements that map to the those within the StatusChanged XSD definition.

Lifecycle and Algorithms

The table below outlines some of the important algorithms used by the Status Changed Read inbound communication.

Lifecycle State Algorithms

Validate

  • D8-IDNPOCAA – Find Parent Outbound Communication For Async Inbound: This algorithm finds the initial outbound communication associated with the current inbound communication using the request token id.

Evaluate Response

  • D8-EVALSTCHG – Itron - Evaluate Response for StatusChanged: This algorithm performs a task based on the values of the arriving StatusChanged request. If the Status is Completed and the Result is Success or Failure, the parent outbound communication is completed. This alerts the activity to initiate the next outbound communication.

Outbound Communication — Itron - On Demand Read Result

Business Object: D8-ReadOnDemandReadResultDR

This is the second of two outbound requests within the Itron Contingency Read API. The outbound request submits the request token ID. The response contains error information collected by the Itron server during the execution of the Contingency Read process.

Schema

The portions of the schema that contain the payload of the web service request and response communications are the sendDetail element (constructed using the D8-ReadODRResultRequestDR data area) and the responseDetail element (constructed using the D8-ReadODRResultResponseDR data area). The XSLs used to create or decipher XML conforming to the Itron structure use these elements as a basis.

Lifecycle and Algorithms

The table below outlines some of the important algorithms used by the On-Demand Read Result outbound communication.

Lifecycle State Algorithms

Awaiting Response

  • D8-PSDODRRDR – Itron - Populate OnDemand Read Result Send Details: This algorithm populate the sendDetail element for the outbound message. Primarily, this consists of the request token ID.

  • D8-CODRROBDR – Create Outbound Message for On Demand Read Result: This algorithm determines the correct outbound message to create based upon the input Processing Role. The reply from the head end system will be stored in the responseDetails element and log entries will be created for the creation of the outbound message and the result (whether it is a success or a failure).

Evaluate Response

  • D8-EVODRRSLT – Create Outbound Message for On Demand Read Result: This algorithm evaluates the response from Itron and determines whether the command was successful or was a failure.

  • D8-VDVCMCDR – Validate if Device has appropriate Measuring Component: This algorithm performs a check to ensure that the reading has a proper measuring component.

Service Script: Itron - DataArrived Request

This Groovy—based service script handles the incoming DataArrived requests. It saves the payload to file storage locations (including Cloud Object Storage buckets in the case of cloud implementations) based on configuration.

Schema

The schema maps closely to the Itron DataArrived message. It includes the D8-DataArrived data area.

Steps

Step 10 Edit Data – Invoke Main Groovy Method

This step shows how to trigger a Groovy script from other OUAF objects. It is similar to a main method in other programming languages. In this case, it is called by an Inbound Web Service method.

Step 20 – Groovy Imports

This step imports other classes needed by the script.

Step 30 – Groovy Members

  1. Look up the Master Configuration object

  2. Use the Master Configuration to find the File Storage details

    1. Find the File Adapter type

    2. Compute a filename using a configured generation script

    3. Compute a fill URL using the bucket, filename, and other details

  3. Use the FileStorageAdapter business service to save the file to the targeted location.

Message Sender XSLs

Outbound messages created by on-demand read outbound communications use the following XSL files:

ContingencyReadByEndpoints

  • Request XSL: D8-ContinegencyReadByEndpointsRequest.xsl
  • Response XSL: D8-ContingencyReadByEndpointsResponse.xsl

GetContingencyReadByEndpointsResult

  • Request XSL: D8-GetContingencyReadByEndpointsResultRequest.xsl
  • Response XSL: D8-GetContingencyReadByEndpointsResultResponse.xsl

Refer to Creating Message Senders for more information about creating message senders.

Inbound Web Services

The Itron on-demand read process uses the following inbound web services.

D8-RequestStatusChangedService

  • Operation Name: StatusChanged
  • Schema Name: Itron — Status Changed BO
  • Request XSL: D8-RequestStatusChangedServiceRequest.xsl
  • Response XSL: D8-RequestStatusChangedServiceResponse.xsl

D8-DataSubscriberService

  • Operation Name: DataArrived
  • Schema Name: Itron — DataArrived Request Script
  • Request XSL: D8-DataSubscriberServiceRequest.xsl
  • Response XSL: D8-DataSubscriberServiceResponse.xsl