AMI – Callback Interface - HxGN InService - 9.4.2512 - Help

Parameters

The OMS Callback Parameters (oms_callback set) (see Other Documents) control how Callback connects to WebSphere MQ queues and to Microsoft Message Queue (MSMQ).

When using MSMQ, Callback removes messages from input queues non-transactionally, so an individual message might be lost if Callback fails over or recycles before the message is processed. This is an MSMQ limitation. If you require queue logic to be transactional, use IBM WebSphere MQ instead of MSMQ. MSMQ message queuing size limit is 4MB; AMI cannot transfer message over 4MB using MSMQ.

Add the registry string value CALLBACK_CONFIG as part of the Configuration key under Intergraph Public Safety/Configurations to indicate which overrides to apply when retrieving oms_callback parameters.

The oms_callback set contains the following lists and tables:

The AMI request generation filters in the following parameters apply only to automatic request generation through Trouble Analysis:

• AMI Request Processing List

• Request Gen FID Settings Table

• Request Gen Ag Dg Settings Table

Manual requests that come from Dispatcher workstations are forwarded to an AMI system regardless of filters that would apply for the same automatic requests.

You can customize the category field value in the request .xml using the following parameters in the oms_callback set—AMI Request Processing list:

• Category_MeterList

• Category_Unknown

• Category_VerifyOutage

• Category_VerifyRestoration

Processing

service processing of AMI requests and responses is determined largely by configuration settings in OMS Callback Parameters (oms_callback set) (see Other Documents).

The command-line argument /id:<#> (required) identifies the AMI instance ordinal to use for the instance of the service being run.

The processing workflow for AMI is as follows:

1. Startup processing

   1. Read the /id:<#> parameter to determine the AMI instance ordinal to use.

   2. Load processing parameters, including AMI queue details and queue handling parameters.

   3. Load WebSphere MQ functions, or load Microsoft Message Queue (MSMQ) functions.

   4. Create synchronization objects to communicate between the processing thread and the AMI read and write threads.

   5. Start AMI queue read and write threads in a suspended state:

      1. A write queue thread adds AMI request messages to the outbound WebSphere MQ queue or to the outbound MSMQ.

      2. A create call thread interacts with Call Interface and handles (based on configuration) create call requests on meter off notifications

      3. An AMI response timeout processing thread periodically checks for stale ami_data_requests records.

2. When going to primary (either at startup or from secondary):

   1. Load request IDs for AMI data requests for which calls should be created on meter off notifications.

   2. Check the ami_processing_status table to determine whether unsolicited AMI response messages should be processed or ignored. If there is no record with is_current = ‘T’, messages are processed.

   3. Resume threads created during startup processing.

   4. Check the ami_data_requests and ami_data_request_details tables for any open requests and process those requests.

   5. Start packet processing.

3. OMS_AMI_DATA_REQUEST packet processing (and processing of open requests):

   1. Retrieve the request ID from the packet.

   2. Retrieve request details from the ami_data_requests and ami_data_request_details tables. (For ‘Meter List’ and ‘Verify Outage’ requests, retrieve meter names directly from the ami_data_response_details table.)

   3. If the request timeout period configured in the (ServiceControlOptions Table (oms_callback set) and the CancelSubmitToAmiAfterXMin parameter (oms_callback set – AMI Request Processing List) has expired, close the request and do not write a request message to the output queue.

   4. Determine which meters for which to request AMI data for the request, and populate those meters into the ami_data_response_details table. For ‘Meter List’ and ‘Verify Outage’ requests, skip this step.

   5. Write meter information to the outgoing queue for the AMI system to retrieve and process.

4. OMS_AMI_SET_PROCESSING packet processing:

   Set the global indicator variable to either process or discard unsolicited AMI response messages, depending on whether the request indicates that processing should be suspended or resumed.

5. AMI response message processing:

   1. If the message does not specify a <CorrelationID> (request ID), or if <CorrelationID> is zero, and if unsolicited AMI response messages should be ignored, discard the message.

   2. Determine whether ami_data_response_details records should be updated or created, and perform any required database writes. See the UpdateBehavior_NoRequestId parameter (AMI Response Processing List - oms_callback) and the UpdateBehavior_WithRequestId parameter ((AMI Response Processing List - oms_callback set).

   3. If there are meter-off notifications for ami_data_response_details records associated with requests for which calls should be created on such notifications, add a create call request for processing by the create call thread.

6. AMI response timeout processing:

   1. Every number of minutes as set in the AmiResponseCheckIntervalInMin parameter AMI Response Processing List - oms_outcall set), check the ami_data_requests table for requests submitted to an AMI system and for which a response is not complete after the time set in the CloseIfNoAmiResponseAfterXMin parameter (AMI Response Processing list - oms_callback set ).

   2. For such records, set ami_data_requests.processing_status = ‘T’, and set ami_data_response_details.meter_response = ‘Response Timed Out’ for corresponding meters.

7. Processing on exit:

   1. Send a stop signal to AMI read and write queue processing threads.

   2. Each worker thread responds to the stop signal by finishing its current operation and exiting.

   3. The main thread waits for all worker threads to exit before exiting. If a worker thread takes more than the milliseconds to finish set in the TimeInMsToAllowForAmiShutdown parameter (ServiceControlOptions Table - oms_outcall set), the main thread may terminate it abnormally in order to exit. (For this reason, Callback recommends that you set this parameter larger than any other external wait parameter [for example, a wait for a response from Call Interface] that applies to individual thread processing.)

AMI Request and Response Messages

considers an AMI data request to be a set of meters for which data are requested as a group. Requests indicate which meters to query and may indicate the time of the request and the time by which a response is needed.

The following XML format definitions for AMI request and response messages contain fields that uses for AMI processing. Queued messages should be in ASCII or MBCS (as opposed to Unicode) format.

XML message formats are based on the following international standards documents:

• IEC 61970-301 (Edition 2.0, 2009-04), “Energy management system application program interface (EMS-API) – Part 301: Common information model (CIM) base”

• IEC 61968-9 (Edition 1.0, 2009-09), “Application integration at electric utilities – System interfaces for distribution management – Part 9: Interfaces for meter reading and control”

Although based on the CIM standard, InService handling of AMI messages is not currently CIM-compliant.

Request and response messages both use the following format. InService includes XML elements that are either required by the standard or that the software requires for processing.

AMI Request and Response messages

<?xml version=”1.0” encoding=”UTF-8”?>

<Message>

<Header>

<Verb>…</Verb>

<Noun>…</Noun>

<Timestamp>…</Timestamp>

[<RespondByTimestamp>…</RespondByTimestamp>]

[<CorrelationID>…</CorrelationID>]

</Header>

[<Reply>

<ReplyCode>…</ReplyCode>

</Reply>]

<Payload>

<EndDeviceEvents>

[<EndDeviceEvent>

<category>…</category>

<createdDateTime>…</createdDateTime>

[<description>…</description>]

<Assets>

[<mRID>…</mRID>

<mRID…/> …]

</Assets>

</EndDeviceEvent>

<EndDeviceEvent…/> …]

</EndDeviceEvents>

</Payload>

</Message>

The <Header> section indicates whether a <Message> is a meter data request (<Verb> = GET) or response (<Verb> = REPLY) message, indicates the request or response time, and may (must for requests) include a request ID (<CorrelationID>).

The <Payload> section lists the meters to query or for which status data are returned. For requests, there will be exactly one <EndDeviceEvent> element listing all meters to be queried in the <Assets> section; for responses, there may be one or more <EndDeviceEvent> elements, where each element describes a response profile (<category> plus <createdDateTime>) shared by one or more meters listed in the <Assets> section of that <EndDeviceEvent> element.

The following table describes requirements for these elements. String values should not contain reserved XML characters:

• AMI Ping Meter and AMI Ping Results are two separate workflows. Meter status doesn't immediately display as a result of AMI Ping Meter. Results are in the table for Dispatcher to manually retrieve later.

• A meter ping can be sent from TA.

• On the AMI Meter Results dialog box, there is a Create Call button. This functionality is disabled in InService 9.3. The create call functionality from AMI is currently not enabled in the product—in order to get to that processing path, set the field ami_data_requests.create_calls_for_meters_off to ‘T’ for a particular request. Configure the (oms_callback, AMI ICall Processing) parameter list. Even then, it may still be the case that only one connection to I/Call can exist, so you might only be able to run one of I/MQC, Callback, CCTest, and the Create Call functionality in Dispatcher at a time.