Documente Academic
Documente Profesional
Documente Cultură
1 Technical Specification
RS09F004-034 23/05/2011 1
Copies of this document are uncontrolled. Check the project file for the current issue before using this document. Copyright Itron Metering Solutions, unpublished work, created 2011. Contains CONFIDENTIAL and TRADE SECRET information
Itron Metering Solutions UK Ltd. Registered Office: Langer Road, Felixstowe, Suffolk, IP11 2ER Registered in England - No. 4274515
23/05/2011
CONTENTS 1 Introduction .............................................................................................................................. 3 1.1 1.2 2 2.1 Objectives and Scope ..................................................................................................... 3 References ..................................................................................................................... 3 Common Types .............................................................................................................. 4 Message .................................................................................................................. 4 RequestMessage ..................................................................................................... 5 ResponseMessage .................................................................................................. 5 ResponseMultiMessage........................................................................................... 6 MeterReading .......................................................................................................... 7 InstallMeter .............................................................................................................. 7 UninstallMeter .........................................................................................................12 ReplaceMeter .........................................................................................................15 CreateServicePoint .................................................................................................19 UpdateServicePoint ................................................................................................22 InstallDevice ...........................................................................................................24 InstallDeviceBatchAsync.........................................................................................27 ReplaceDevice .......................................................................................................29 ControlMeterAsync .................................................................................................32 GetMeterReadingsAsync ........................................................................................36 ChangeMeterGroupAsync ......................................................................................43 ConfigureMeterAsync .............................................................................................46
Metering System API ............................................................................................................... 4 2.1.1 2.1.2 2.1.3 2.1.4 2.1.5 2.2 2.2.1 2.2.2 2.2.3 2.2.4 2.2.5 2.2.6 2.2.7 2.2.8 2.3 2.4 2.5 2.3.1 2.4.1 2.5.1 2.5.2
Meter Control .................................................................................................................32 Meter Data Collection ....................................................................................................36 Meter Configuration .......................................................................................................43
3 4 5
RS09F004-034
Version: 1
Page 2 of 55
23/05/2011
1 Introduction
1.1 Objectives and Scope
The objective of the document is to detail the implementation of the Metering System API in Saturne. Metering System API (MS API) is a generic CIM-based metering system interface defined in [1] and [2]. Saturne implements semantically subset of MS API, i.e. some fields are not supported, for ControlMeter only connection and disconnection is supported etc. The scope of the document is a technical description of MS API as implemented in Saturne. The installation and configuration of Saturne MS API in the customers environment is out of scope and it is typically part of Saturne deployment provided by Itron Deployment Team.
1.2 References
No. 1 2 3 4 Document Metering System API V2.1 Metering System API Model V2.1 IEE Readings Import/Export XML API Guide IEC 61968-9 Interface Standard for Meter Reading and Control Version 1 1 7.0 1.0 Author Itron Itron Itron IEC
RS09F004-034
Version: 1
Page 3 of 55
23/05/2011
2.1.1 Message
Message is a base type for passing request and response messages. Field MessageId
Occurrence
Description xsd:string Unique identifier of the message. Auto-generated (GUID) for responses. xsd:string It is the requests MessageId in the response to correlate the response with the request. Not used for requests.
CorrelationId
0..1
RS09F004-034
Version: 1
Page 4 of 55
23/05/2011
Field Timestamp
Occurrence
Description xsd:dateTime UTC-based date and time when the message was created. xsd:string Required for asynchronous requests it defines the URL for the clients call-back endpoint where the response is sent. Not used for synchronous requests or for responses. xsd:string It defines a URL where bulk data response will be sent. The server replies to the client with a normal response containing no bulk data (e.g. without meter readings) and the server sends the bulk data to this URL. URL defines also format of the data, i.e. ari: means ARI XML format. Currently supported for GetMeterReadingsAsync only. MessageSource Not used/supported.
ReplyAddress
0..1
DataReplyAddress 0..1
MessageSource
0..1
2.1.2 RequestMessage
RequestMessage extends Message and is a base type for all requests. Field LogProcessing
Occurrence
0..1
2.1.3 ResponseMessage
ResponseMessage extends Message and is a base type for all responses. Field ResultCode
Occurrence
Description xsd:string CIM response code. 0.0 means success other values are errors. xsd:dateTime UTC-based date and time when the command if applicable has been executed. Only applies to specific requests. ProcessingInfo Not supported.
ExecutionTimestamp
0..1
ProcessingInfo
0..1
RS09F004-034
Version: 1
Page 5 of 55
23/05/2011
Field ResultMessages
Occurrence
Description ArrayOfResultMessage Only present if processing was not successful. ResultMessage It contains an error message for each error, e.g. if the request was for more meters and processing for some of them failed there is a message for each failed meter processing. xsd:string Always empty, not used. xsd:string Id of an error message, please see Error Messages xsd:string An error message, please see Error Messages ServiceMessageSeverityKind Always Error xsd:string Always SATURNE xsd:dateTime UTC-based date and time when the message was created. xsd:string Not supported, always xsd:nil. xsd:string Not supported, always xsd:nil. ArrayOfstring Not supported, always xsd:nil. ArrayOfResultMessage Only present if available, e.g. error message from a data concentrator. ArrayOfServiceLogMessage Not supported.
0..1
ResultMessage
0..*
Category
Id
Message
Severity
Source
0..1
Timestamp
EntityId
EntityType
TaskIds
InnerMessages
0..1
LogMessages
0..1
2.1.4 ResponseMultiMessage
ResponseMultiMessage is a response that is passed in multiple messages. It is not currently supported by Saturne.
RS09F004-034
Version: 1
Page 6 of 55
23/05/2011
Field LastMessage
Occurrence
MessageNumber
2.1.5 MeterReading
MeterReading is a complex type used in response messages returning meter readings. Field MeterId
Occurrence
Description xsd:string Id of the meter which readings are contained in Intervals and/or Readings xsd:string Not supported, not present. TimeInterval Not supported, not present. ReadingTypeSchemaKind Only CIM and IEEServicePointChannel ReadingTypeId schemas are supported. The schema defines what type of id ReadingTypeId is inside Intervals and Readings. ArrayOfReadingTypeReading It contains meter readings. ArrayOfIntervalBlockReading Not supported.
ServicePointId
0..1
Interval
0..1
ReadingTypeSchema
Readings
0..1
Intervals
0..1
2.2.1 InstallMeter
The InstallMeter operation sets up a meter in Saturne it creates the meter and, optionally, creates the service point (SP) and attaches (links) the meter to the service point. Saturne keeps a history of SP and meter relationships.
RS09F004-034
Version: 1
Page 7 of 55
23/05/2011
InstallMeter does not allow the meter to be attached to a SP if the meter is already attached to another SP, i.e. it checks if it is a new or uninstalled meter. Meter Auto-discovery If the meter is automatically discovered by the AMI network Saturne automatically creates the meter and a dummy SP for the meter, attaching the meter to that dummy SP at the same time. All meter data are collected against the dummy SP from that time on. Meter auto-discovery is configurable in Saturne. When InstallMeter is requested for the meter with a new SP, the dummy SP is just updated with the new Id, Name and CustomData and all meter data is retained with the SP. No meter data are sent to an upstream system when the dummy SP is updated. Request Field EffectiveDate
Occurrence
Description xsd:dateTime UTC-based date and time when installation of the meter to the service point took place. Saturne checks if EffectiveDate is newer than the last link of the meter to an SP if a link exists.
Options
InstallMeterOptions This is a list of following enumerations: None Meter and ServicePoint must exist prior to InstallMeter operation. CreateMeterIfNotExist creates Meter if the meter does not exist yet. CreateServicePointIfNotExist creates ServicePoint if the SP does not exist yet.
Meter
Meter Details of the meter to be installed in Saturne. Only Name is updated if the meter already exists and the operation succeeds. xsd:string Serial number of the meter in Saturne must be unique. Saturne uses Id as a key to find existing meter. xsd:string Name of the meter in Saturne. If not present Id is used as meters name. xsd:string Not used/supported.
Id
Name
0..1
SerialNumber
0..1
RS09F004-034
Version: 1
Page 8 of 55
23/05/2011
Field Model
Occurrence
Description xsd:string Model determines meter type in Saturne. Saturne MS API has a mapping of Model to Saturne meter type (configurable). Saturne checks if the mapping exists. Model cant be updated once the meter is created in Saturne. ServicePoint If present the meter is attached to the SP. Otherwise the meter is created/updated only. If SP exists and the operation succeeds it is updated only Name and CustomData are updated.
ServicePoint
0..1
Id
xsd:string Id of the SP in Saturne must be unique. Saturne uses Id as a key to find existing SP. xsd:string Name of the SP in Saturne. If not present Id is used as SPs name. CommodityKind Not supported. Saturne allows SP to service more commodities and therefore SPs commodities are determined by meter types (Model) of meters attached to the SP. ArrayOfNameValue CustomData is stored as SP custom attributes in Saturne. NameValue Name and value pair stored as SP custom attribute in Saturne. Only first matching NameValue is supported, please see below. xsd:string Name determines SP custom attribute where Value is stored. Saturne MS API has a mapping of Name to Saturnes SP custom attribute. Only one custom attribute per SP is supported via API. xsd:string Value of SPs custom attribute.
Name
0..1
Commodity
CustomData
0..1
NameValue
0..*
Name
Value
1 nil
Response Field
Occurrence
Description
RS09F004-034
Version: 1
Page 9 of 55
23/05/2011
Field ExecutionTimestamp
Occurrence
Description xsd:dateTime Not used, not present. Meter An exact copy of Meter from the request. ServicePoint An exact copy of ServicePoint from the request if present in the request.
0..1
Meter
ServicePoint
0..1
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11"> <soap:Header/> <soap:Body> <ns:InstallMeter> <ns:request> <ns1:MessageId>INSTALL001</ns1:MessageId> <ns1:ReplyAddress>http://metering-system-client/IMeteringSystemReceive</ns1:ReplyAddress> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:EffectiveDate>2011-01-01T00:00:00Z</ns:EffectiveDate> <ns:Meter> <ns1:Id>LGZDUMMY19003</ns1:Id> <ns1:Name>LGZDUMMY19003</ns1:Name> <ns:Model>CN</ns:Model> <ns:SerialNumber>LGZDUMMY19003</ns:SerialNumber> </ns:Meter> <ns:Options>CreateMeterIfNotExist CreateServicePointIfNotExist</ns:Options> <ns:ServicePoint> <ns1:CustomData> <ns1:NameValue> <ns1:Name>FuseBoxCode</ns1:Name> <ns1:Value>123</ns1:Value> </ns1:NameValue> </ns1:CustomData> <ns1:Id>SP-LGZDUMMY19003</ns1:Id> <ns:Commodity>Electricity</ns:Commodity> </ns:ServicePoint> </ns:request> </ns:InstallMeter> </soap:Body> </soap:Envelope>
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/InstallMeterRespo nse</a:Action> </s:Header> <s:Body> <InstallMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <InstallMeterResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">INSTALL001</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">e145c8d7-a38d-4343-9e728ed07c391d29</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11">http://metering-systemclient/IMeteringSystemReceive</ReplyAddress> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T08:55:49.922375Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Meter> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/>
RS09F004-034
Version: 1
Page 10 of 55
23/05/2011
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/InstallMeterRespo nse</a:Action> </s:Header> <s:Body> <InstallMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <InstallMeterResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">INSTALL001</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">47e097fe-fee6-434e-980c1545a6d50064</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11">http://metering-systemclient/IMeteringSystemReceive</ReplyAddress> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T08:48:51.40675Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.P20</Id> <Message>Meter matching model cannot be found in mapping file</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T08:48:51.96925Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Meter> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">LGZDUMMY19003</Id> <Name xmlns="http://www.smartgridservicebus.org/common/2010/11">LGZDUMMY19003</Name> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model>CN2</Model> <SerialNumber>LGZDUMMY19003</SerialNumber> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Meter> <ServicePoint>
RS09F004-034
Version: 1
Page 11 of 55
23/05/2011
2.2.2 UninstallMeter
The UninstallMeter operation detaches a meter from a service point (SP). Saturne keeps history of SP and meter relationships. UninstallMeter checks if the meter is attached to the SP, i.e. it is not a new or already uninstalled meter. Request Field EffectiveDate
Occurrence
Description xsd:dateTime UTC-based date and time when uninstallation of the meter from the service point took place. Saturne checks if EffectiveDate is newer than the creation time of the meter-SP link.
Meter
Meter Details of the meter to be uninstalled in Saturne. Only Id is used. The meter must already exist and must be attached to an SP. xsd:string Serial number of existing meter in Saturne. xsd:string Not used. xsd:string Not used. xsd:string Not used. ServicePoint If present the meter must already be attached to this SP. Only Id is used.
Id
Name
0..1
SerialNumber
0..1
Model
ServicePoint
0..1
RS09F004-034
Version: 1
Page 12 of 55
23/05/2011
Field Id
Occurrence
Description xsd:string Id of existing SP in Saturne. xsd:string Not used. CommodityKind Not used. ArrayOfNameValue Not used.
Name
0..1
Commodity
CustomData
0..1
Description xsd:dateTime Not used, not present. Meter An exact copy of Meter from the request. ServicePoint An exact copy of ServicePoint from the request if present in the request.
0..1
Meter
ServicePoint
0..1
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11"> <soap:Header/> <soap:Body> <ns:UninstallMeter> <ns:request> <ns1:MessageId>UNINSTALLMETER</ns1:MessageId> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:EffectiveDate>2011-01-07T00:00:00Z</ns:EffectiveDate> <ns:Meter> <ns1:Id>LGZDUMMY19006</ns1:Id> </ns:Meter> <ns:ServicePoint> <ns1:Id>SP-LGZDUMMY19005</ns1:Id> <ns:Commodity>Electricity</ns:Commodity> </ns:ServicePoint> </ns:request> </ns:UninstallMeter> </soap:Body> </soap:Envelope>
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/UninstallMeterRes ponse</a:Action> </s:Header> <s:Body>
RS09F004-034
Version: 1
Page 13 of 55
23/05/2011
<UninstallMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <UninstallMeterResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">UNINSTALLMETER</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">9192f7b0-a8f7-48a1-b24d3c0f5c8283d7</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T10:24:17.422375Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Meter> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">LGZDUMMY19006</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model i:nil="true"/> <SerialNumber i:nil="true"/> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Meter> <ServicePoint> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">SP-LGZDUMMY19005</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Commodity>Electricity</Commodity> <NominalServiceVoltage i:nil="true"/> <PhaseConfig i:nil="true"/> <RatedCurrent i:nil="true"/> <RatedPower i:nil="true"/> </ServicePoint> </UninstallMeterResult> </UninstallMeterResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/UninstallMeterRes ponse</a:Action> </s:Header> <s:Body> <UninstallMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <UninstallMeterResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">UNINSTALLMETER</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">42649b65-dac0-473f-90c49ba049d6bca8</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T10:22:26.938Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.P16</Id> <Message>Meter LGZDUMMY19006 is attached to a service point, the service point must be specified.</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T10:22:26.953625Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Meter> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">LGZDUMMY19006</Id>
RS09F004-034
Version: 1
Page 14 of 55
23/05/2011
2.2.3 ReplaceMeter
The ReplaceMeter operation is a sequence of UninstallMeter and InstallMeter operations in one transaction where one meter is replaced by another. It creates the meter (optionally) and attaches (links) the meter to the service point (SP) after uninstalling the previous meter from the SP. Saturne keeps a history of SP and meter relationships. ReplaceMeter does not allow the meter to be attached to a SP if the meter is already attached to another SP, i.e. it checks if it is a new or uninstalled meter. ReplaceMeter does not allow replacing the meter which is not attached to the particular SP the previous meter is not attached to the SP or is a new or uninstalled meter. Request Field EffectiveDate
Occurrence
Description xsd:dateTime UTC-based date and time when the replacement of the meter on the service point took place. Saturne checks if EffectiveDate is newer than last link of Meter to an SP if the link exists. Saturne also checks if EffectiveDate is newer than creation time of the MeterToReplace-SP link.
Options
ReplaceMeterOptions This is a list of following enumerations: None Meter must exist prior to ReplaceMeter operation. CreateMeterIfNotExist creates Meter if the meter does not exist yet.
Meter
Meter Details of the meter to be installed in Saturne as replacement for MeterToReplace. Only Name is updated if the meter already exists and the operation succeeds.
RS09F004-034
Version: 1
Page 15 of 55
23/05/2011
Field Id
Occurrence
Description xsd:string Serial number of the meter in Saturne must be unique. Saturne uses Id as a key to find existing meter. xsd:string Name of the meter in Saturne. If not present Id is used as meters name. xsd:string Not used/supported. xsd:string Model determines meter type in Saturne. Saturne MS API has a mapping of Model to Saturne meter type (configurable). Saturne checks if the mapping exists. Model cant be updated once the meter is created in Saturne. Meter Details of the meter to be replaced in Saturne. The meter must exist and must be attached to ServicePoint.
Name
0..1
SerialNumber
0..1
Model
MeterToReplace
Id
xsd:string Serial number of the meter in Saturne. xsd:string Not used. xsd:string Not used/supported. xsd:string Saturne checks if Model matches the model when the meter was created. Saturne MS API has a mapping of Model to Saturne meter type (configurable). Saturne checks if the mapping exists. ServicePoint SP must exist and MeterToReplace must be attached to the SP. Only Name and CustomData are updated.
Name
0..1
SerialNumber
0..1
Model
0..1
ServicePoint
Id
xsd:string Id of the SP in Saturne must be unique. Saturne uses Id as a key to find SP.
RS09F004-034
Version: 1
Page 16 of 55
23/05/2011
Field Name
Occurrence
Description xsd:string Name of the SP in Saturne. CommodityKind Not supported. ArrayOfNameValue CustomData is stored as SP custom attributes in Saturne. NameValue Name and value pair stored as SP custom attribute in Saturne. Only first matching NameValue is supported, please see below. xsd:string Name determines SP custom attribute where Value is stored. Saturne MS API has a mapping of Name to Saturnes SP custom attribute. Only one attribute is supported via API. xsd:string Value of SPs custom attribute.
0..1
Commodity
CustomData
0..1
NameValue
0..*
Name
Value
1 nil
Description xsd:dateTime Not used, not present. Meter An exact copy of Meter from the request. ServicePoint An exact copy of ServicePoint from the request if present in the request.
0..1
Meter
ServicePoint
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11"> <soap:Header/> <soap:Body> <ns:ReplaceMeter> <ns:request> <ns1:MessageId>REPLACEMETER</ns1:MessageId> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:EffectiveDate>2011-01-05T00:00:00Z</ns:EffectiveDate> <ns:Meter> <ns1:Id>LGZDUMMY19006</ns1:Id>
RS09F004-034
Version: 1
Page 17 of 55
23/05/2011
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/ReplaceMeterRespo nse</a:Action> </s:Header> <s:Body> <ReplaceMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <ReplaceMeterResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">REPLACEMETER</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">69b30b03-a9d9-45ee-839e606bd18f2325</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11">http://metering-systemclient/IMeteringSystemReceive</ReplyAddress> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T10:19:15.563Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Meter> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">LGZDUMMY19006</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model>CN</Model> <SerialNumber i:nil="true"/> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Meter> <ServicePoint> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">SP-LGZDUMMY19005</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Commodity>Electricity</Commodity> <NominalServiceVoltage i:nil="true"/> <PhaseConfig i:nil="true"/> <RatedCurrent i:nil="true"/> <RatedPower i:nil="true"/> </ServicePoint> </ReplaceMeterResult> </ReplaceMeterResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/ReplaceMeterRespo nse</a:Action> </s:Header> <s:Body> <ReplaceMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <ReplaceMeterResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">REPLACEMETER</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/>
RS09F004-034
Version: 1
Page 18 of 55
23/05/2011
<MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">dec9a541-87ec-4e09-af66797c8cf7804e</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T10:17:26.047375Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.P13</Id> <Message>Meter LGZDUMMY19006 does not exist.</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T10:17:26.734875Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Meter> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">LGZDUMMY19006</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model>CN</Model> <SerialNumber i:nil="true"/> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Meter> <ServicePoint> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">SP-LGZDUMMY19004</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Commodity>Electricity</Commodity> <NominalServiceVoltage i:nil="true"/> <PhaseConfig i:nil="true"/> <RatedCurrent i:nil="true"/> <RatedPower i:nil="true"/> </ServicePoint> </ReplaceMeterResult> </ReplaceMeterResponse> </s:Body> </s:Envelope>
2.2.4 CreateServicePoint
The CreateServicePoint operation creates a service point (SP) in Saturne. CreateServicePoint checks if the SP does not already exist. Request Field EffectiveDate
Occurrence
Description xsd:dateTime UTC-based date and time when creation of the SP is effective from. If not present the current date and time is used. ServicePoint Details of the service point. The SP must not exist in Saturne.
0..1
ServicePoint
RS09F004-034
Version: 1
Page 19 of 55
23/05/2011
Field Id
Occurrence
Description xsd:string Id of the SP in Saturne must be unique. Saturne uses Id as a key to find existing SP. xsd:string Name of the SP in Saturne. If not present Id is used as SPs name. CommodityKind Not supported. Saturne allows SP to service more commodities and therefore SPs commodities are determined by meter types (Model) of meters attached to the SP. ArrayOfNameValue CustomData is stored as SP custom attributes in Saturne. NameValue Name and value pair stored as SP custom attribute in Saturne. Only first matching NameValue is supported, please see below. xsd:string Name determines SP custom attribute where Value is stored. Saturne MS API has a mapping of Name to Saturnes SP custom attribute. Only one attribute is supported via API. xsd:string Value of SPs custom attribute.
Name
0..1
Commodity
CustomData
0..1
NameValue
0..*
Name
Value
1 nil
Description xsd:dateTime Not used, not present. ServicePoint An exact copy of ServicePoint from the request.
0..1
ServicePoint
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11"> <soap:Header/>
RS09F004-034
Version: 1
Page 20 of 55
23/05/2011
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/CreateServicePoin tResponse</a:Action> </s:Header> <s:Body> <CreateServicePointResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <CreateServicePointResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">CREATESP</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">3d22c393-ec9e-49c6-9f0a39961ab9ad0d</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T09:23:13.859875Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ServicePoint> <CustomData xmlns="http://www.smartgridservicebus.org/common/2010/11"> <NameValue> <Name>FuseBoxCode</Name> <Value>123</Value> </NameValue> </CustomData> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">SP-LGZDUMMY19010</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Commodity>Electricity</Commodity> <NominalServiceVoltage i:nil="true"/> <PhaseConfig i:nil="true"/> <RatedCurrent i:nil="true"/> <RatedPower i:nil="true"/> </ServicePoint> </CreateServicePointResult> </CreateServicePointResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/CreateServicePointResponse</a:A ction> </s:Header> <s:Body> <CreateServicePointResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <CreateServicePointResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">CREATESP</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">9adae964-354d-4b6c-81f7694453d3279b</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-05-04T10:36:09.6735076Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/>
RS09F004-034
Version: 1
Page 21 of 55
23/05/2011
2.2.5 UpdateServicePoint
The UpdateServicePoint operation updates a service point (SP) in Saturne. UpdateServicePoint checks that the SP exists. Request Field EffectiveDate
Occurrence
Description xsd:dateTime UTC-based date and time when creation of the SP is effective from. If not present EffectiveDate is not updated. ServicePoint Details of the service point. The SP must exist in Saturne. xsd:string Id of the SP in Saturne. xsd:string Name of the SP in Saturne. If not present Name is not updated. CommodityKind Not supported.
ServicePoint
Id
Name
0..1
Commodity
RS09F004-034
Version: 1
Page 22 of 55
23/05/2011
Field CustomData
Occurrence
Description ArrayOfNameValue CustomData is stored as SP custom attributes in Saturne. If not present it is not updated. NameValue Name and value pair stored as SP custom attribute in Saturne. Only first matching NameValue is updated, please see below. xsd:string Name determines SP custom attribute where Value is stored. Saturne MS API has a mapping of Name to Saturnes SP custom attribute. Only one attribute is supported via API. xsd:string Value of SPs custom attribute.
0..1
NameValue
0..*
Name
Value
1 nil
Description xsd:dateTime Not used, not present. ServicePoint An exact copy of ServicePoint from the request.
0..1
ServicePoint
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11"> <soap:Header/> <soap:Body> <ns:UpdateServicePoint> <ns:request> <ns1:MessageId>UPDATESERVICEPOINT</ns1:MessageId> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:EffectiveDate>2011-04-01T00:00:00Z</ns:EffectiveDate> <ns:ServicePoint> <ns1:CustomData> <ns1:NameValue> <ns1:Name>FuseBoxCode</ns1:Name> <ns1:Value>12345</ns1:Value> </ns1:NameValue> </ns1:CustomData> <ns1:Id>SP-LGZDUMMY19010</ns1:Id> <ns:Commodity>Electricity</ns:Commodity> </ns:ServicePoint> </ns:request> </ns:UpdateServicePoint> </soap:Body> </soap:Envelope>
RS09F004-034
Version: 1
Page 23 of 55
23/05/2011
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/UpdateServicePoin tResponse</a:Action> </s:Header> <s:Body> <UpdateServicePointResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <UpdateServicePointResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">UPDATESERVICEPOINT</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">2385bf62-1ed9-4175-926ff0e6a8b619ce</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T09:55:32.922375Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ServicePoint> <CustomData xmlns="http://www.smartgridservicebus.org/common/2010/11"> <NameValue> <Name>FuseBoxCode</Name> <Value>12345</Value> </NameValue> </CustomData> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">SP-LGZDUMMY19010</Id> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Commodity>Electricity</Commodity> <NominalServiceVoltage i:nil="true"/> <PhaseConfig i:nil="true"/> <RatedCurrent i:nil="true"/> <RatedPower i:nil="true"/> </ServicePoint> </UpdateServicePointResult> </UpdateServicePointResponse> </s:Body> </s:Envelope>
2.2.6 InstallDevice
The InstallDevice operation sets up a device in Saturne it creates the device. Installation of a concentrator is supported only. Request Field EffectiveDate
Occurrence
Description xsd:dateTime UTC-based date and time when installation of the device took place. If not present the current date and time is used. Saturne checks if EffectiveDate is newer than uninstallation date of the device if the device exists.
0..1
Device
Device Details of the device to be installed in Saturne. Only Name is updated if the device already exists and the operation succeeds. Only Concentrator type is supported.
@xsi:type
RS09F004-034
Version: 1
Page 24 of 55
23/05/2011
Field Id
Occurrence
Description xsd:string Serial number of the device in Saturne must be unique. Saturne uses Id as a key to find existing device. xsd:string Name of the device in Saturne. If not present Id is used as devices name. xsd:string Model determines device type in Saturne. Saturne MS API has a mapping of Model to Saturne device type (configurable). Saturne checks if the mapping exists. Model cant be updated once the device is created in Saturne.
Name
0..1
Model
Description xsd:dateTime Not used, not present. Device An exact copy of Device from the request.
0..1
Device
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11"> <soap:Header/> <soap:Body> <ns:InstallDevice> <ns:request xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <ns1:MessageId>InstallDevice001</ns1:MessageId> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:Device i:type="ns:Concentrator"> <ns1:Id>TESTIBDDC001</ns1:Id> <ns1:Name>TESTIBDDC001_NAME</ns1:Name> <ns:Model>IBDDC</ns:Model> </ns:Device> <ns:EffectiveDate>2011-02-12T15:30:30Z</ns:EffectiveDate> </ns:request> </ns:InstallDevice> </soap:Body> </soap:Envelope>
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/InstallDeviceResp onse</a:Action> </s:Header> <s:Body> <InstallDeviceResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <InstallDeviceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
RS09F004-034
Version: 1
Page 25 of 55
23/05/2011
<CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">InstallDevice001</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">3f45ac70-51fc-4c8a-9543aa8c16113aff</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T10:28:51.34425Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Device i:type="Concentrator"> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC001</Id> <Name xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC001_NAME</Name> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model>IBDDC</Model> <SerialNumber i:nil="true"/> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Device> </InstallDeviceResult> </InstallDeviceResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/InstallDeviceResp onse</a:Action> </s:Header> <s:Body> <InstallDeviceResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <InstallDeviceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">Install123</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">0cef1c85-c117-4f84-be53241b5087c9f6</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T10:26:33.297375Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.P31</Id> <Message>Invalid device type - only Concentrator is supported as a device</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T10:26:33.7505Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Device i:type="Meter"> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC</Id> <Name xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC_NAME</Name> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model>IBDDC</Model> <SerialNumber i:nil="true"/> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Device> </InstallDeviceResult> </InstallDeviceResponse> </s:Body>
RS09F004-034
Version: 1
Page 26 of 55
23/05/2011
2.2.7 InstallDeviceBatchAsync
InstallDeviceBatchAsync is an asynchronous batch operation to install multiple devices via one request. If one of the individual installations fails the whole request fails and ResultMessages contains error details. In Saturne, only the installation of a concentrator is supported. Request Field ReplyAddress
Occurrence
Description xsd:string URL of clients call-back endpoint where the response is sent. ArrayOfInstallDeviceData List of items to be installed. InstallDeviceData Parameters for device installation. xsd:dateTime UTC-based date and time when installation of the device took place. If not present the current date and time is used. Saturne checks that EffectiveDate is newer than uninstallation date of the device if the device exists.
Items
InstallDeviceData
1..*
EffectiveDate
0..1
Device
Device Details of the device to be installed in Saturne. Only Name is updated if the device already exists and the operation succeeds. Only Concentrator type is supported. xsd:string Serial number of the device in Saturne must be unique. Saturne uses Id as a key to find existing device. xsd:string Name of the device in Saturne. If not present Id is used as devices name. xsd:string Model determines device type in Saturne. Saturne MS API has a mapping of Model to Saturne device type (configurable). Saturne checks if the mapping exists. Model cant be updated once the device is created in Saturne.
@xsi:type Id
1 1
Name
0..1
Model
RS09F004-034
Version: 1
Page 27 of 55
23/05/2011
0..1
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/common/2010/11"> <soap:Header/> <soap:Body> <ns:InstallDeviceBatchAsync> <ns:request xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <ns1:MessageId>InstSeveralDev123</ns1:MessageId> <ns1:ReplyAddress>http://metering-system-client/IMeteringSystemReceive</ns1:ReplyAddress> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:Items> <ns:InstallDeviceData> <ns:Device i:type="ns:Concentrator"> <ns1:Id>BATCHIBDDC1</ns1:Id> <ns1:Name>BATCHIBDDC1_NAME</ns1:Name> <ns:Model>IBDDC</ns:Model> </ns:Device> <ns:EffectiveDate>2011-02-19T12:00:00Z</ns:EffectiveDate> </ns:InstallDeviceData> <ns:InstallDeviceData> <ns:Device i:type="ns:Concentrator"> <ns1:Id>BATCHIBDDC2</ns1:Id> <ns1:Name>BATCHIBDDC2_NAME</ns1:Name> <ns:Model>IBDDC</ns:Model> </ns:Device> <ns:EffectiveDate>2011-02-19T12:00:00Z</ns:EffectiveDate> </ns:InstallDeviceData> <ns:InstallDeviceData> <ns:Device i:type="ns:Concentrator"> <ns1:Id>BATCHIBDDC3</ns1:Id> <ns1:Name>BATCHIBDDC3_NAME</ns1:Name> <ns:Model>IBDDC</ns:Model> </ns:Device> </ns:InstallDeviceData> </ns:Items> </ns:request> </ns:InstallDeviceBatchAsync> </soap:Body> </soap:Envelope>
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioningReceive/ReceiveCreateAssetBatchR esponse</a:Action> <a:MessageID>urn:uuid:594e0535-c4c9-442b-b97b-f036b54001fc</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveCreateAssetBatchResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">InstSeveralDev123</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">1dd1f4e0-248f-46c2-94251ccf66b0074c</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-05-04T09:34:54.5476894Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/>
RS09F004-034
Version: 1
Page 28 of 55
23/05/2011
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioningReceive/ReceiveCreateAssetBatchR esponse</a:Action> <a:MessageID>urn:uuid:ca4ca909-96a2-4e2d-9baa-690757c7749e</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveCreateAssetBatchResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">InstSeveralDev123</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">84b25e44-b3e3-4cfa-8ebf196ddc27555f</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-05-04T09:37:05.7471359Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.P31</Id> <Message>Invalid device type - only Concentrator is supported as a device</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-05-04T09:37:08.5439214Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> </response> </ReceiveCreateAssetBatchResponse> </s:Body> </s:Envelope>
2.2.8 ReplaceDevice
The ReplaceDevice operation uninstalls the current device and installs a new device in one transaction where one device is replaced by another. Replacement of a concentrator is supported only. All current (DeviceToReplace) concentrators meters are moved to the new (Device) concentrator. Request Field EffectiveDate
Occurrence
Description xsd:dateTime UTC-based date and time when replacement of the device took place. If not present the current date and time is used. Saturne checks that EffectiveDate is newer than uninstallation date of Device if Device already exists.
0..1
RS09F004-034
Version: 1
Page 29 of 55
23/05/2011
Field Device
Occurrence
Description Device Details of the device to be installed in Saturne as a replacement for DeviceToReplace. Only Name is updated if the device already exists and the operation succeeds. Only Concentrator type is supported. xsd:string Serial number of the device in Saturne must be unique. Saturne uses Id as a key to find existing device. xsd:string Name of the device in Saturne. If not present Id is used as devices name. xsd:string Model determines device type in Saturne. Saturne MS API has a mapping of Model to Saturne device type (configurable). Saturne checks if the mapping exists. Model cant be updated once the device is created in Saturne. Device Details of the device to be replaced in Saturne. The device must exist. Only Name is updated. Must be the same type as for Device. Only Concentrator type is supported. xsd:string Serial number of the device. xsd:string If present it is updated. xsd:string Saturne checks if Model matches the model when the device was created. Saturne MS API has a mapping of Model to Saturne device type (configurable). Saturne checks if the mapping exists.
@xsi:type Id
1 1
Name
0..1
Model
DeviceToReplace
@xsi:type
Id
Name
0..1
Model
Response Field
Occurrence
Description
RS09F004-034
Version: 1
Page 30 of 55
23/05/2011
Field ExecutionTimestamp
Occurrence
Description xsd:dateTime Not used, not present. Device An exact copy of Device from the request.
0..1
Device
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11"> <soap:Header/> <soap:Body> <ns:ReplaceDevice> <ns:request xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <ns1:MessageId>ReplaceDevice001</ns1:MessageId> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:Device i:type="ns:Concentrator"> <ns1:Id>TESTIBDDC001_REPLACE</ns1:Id> <ns1:Name>TESTIBDDC001_REPLACE_NAME</ns1:Name> <ns:Model>IBDDC</ns:Model> </ns:Device> <ns:DeviceToReplace i:type="ns:Concentrator"> <ns1:Id>TESTIBDDC001</ns1:Id> <ns1:Name>TESTIBDDC001_NAME</ns1:Name> <ns:Model>IBDDC</ns:Model> </ns:DeviceToReplace> <ns:EffectiveDate>2011-02-24T12:00:00Z</ns:EffectiveDate> </ns:request> </ns:ReplaceDevice> </soap:Body> </soap:Envelope>
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/ReplaceDeviceResp onse</a:Action> </s:Header> <s:Body> <ReplaceDeviceResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <ReplaceDeviceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">ReplaceDevice001</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">9f86c07a-636a-41c6-88facc0568a80a7e</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T12:55:29.40675Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Device i:type="Concentrator"> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC001_REPLACE</Id> <Name xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC001_REPLACE_NAME</Name> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model>IBDDC</Model> <SerialNumber i:nil="true"/> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Device> </ReplaceDeviceResult> </ReplaceDeviceResponse> </s:Body>
RS09F004-034
Version: 1
Page 31 of 55
23/05/2011
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterProvisioning/ReplaceDeviceResp onse</a:Action> </s:Header> <s:Body> <ReplaceDeviceResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <ReplaceDeviceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">ReplaceDevice001</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">1d992892-f524-4324-ac5f79583fef9de2</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T10:30:12.7505Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.P24</Id> <Message>Changing device type is not supported, device type IBDDC does not match device type T5PLC</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T10:30:13.234875Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Device i:type="Concentrator"> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC001_REPLACE</Id> <Name xmlns="http://www.smartgridservicebus.org/common/2010/11">TESTIBDDC001_REPLACE_NAME</Name> <InstallationDate i:nil="true"/> <Manufacturer i:nil="true"/> <Model>IBDDC</Model> <SerialNumber i:nil="true"/> <Status i:nil="true"/> <AmrSystem i:nil="true"/> <Capabilities i:nil="true"/> <TimeZoneOffset i:nil="true"/> </Device> </ReplaceDeviceResult> </ReplaceDeviceResponse> </s:Body> </s:Envelope>
Description
RS09F004-034
Version: 1
Page 32 of 55
23/05/2011
Field ReplyAddress
Occurrence
Description xsd:string URL of clients call-back endpoint where the response is sent. TimeInterval Schedule interval specifying when the meter control should happen. xsd:dateTime UTC-based date and time when is the meter control scheduled and should start. xsd:dateTime UTC-based date and time when the meter control should be finished. If there is no response from the meter after this point in time the request times out. ArrayOfstring List of meter ids (Meter/Id) which receive ControlSequence
ScheduleInterval
Start
End
MeterIds
string
1..*
xsd:string Meter id. The meter must exist and must be present just once in the list.
ServicePointIds
0..1
ControlSequence
ArrayOfDeviceControl List of control commands. Only one item is supported. DeviceControl Device control command details. xsd:string Type of control CIM EndDeviceEvent request code. Currently only following types are supported: 3.31.6.42 connect the electricity meter (RCD switch connected) 3.31.6.68 disconnect the electricity meter (RCD switch disconnected)
DeviceControl
Type
Parameters
0..1
RS09F004-034
Version: 1
Page 33 of 55
23/05/2011
Description xsd:dateTime UTC-based date and time when the meter(s) executed the control command. If the request is for more meters the first meter acknowledgement received is used to populate this field. ArrayOfMeterReading Readings of meter(s) associated with the meter control command. Which reading types are returned in ControlMeterAsync response is configurable in Saturne. MeterReading Meter readings for a particular meter. Only IEEServicePointChannel reading type schema is supported. See MeterReading.
0..1
Readings
0..1
MeterReading
0..*
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <soap:Header/> <soap:Body> <ns:ControlMeterAsync> <ns:request> <ns1:MessageId>CONTROLMETER</ns1:MessageId> <ns1:ReplyAddress>http://metering-system-client/IMeteringSystemReceive</ns1:ReplyAddress> <ns1:Timestamp>2011-02-07T15:00:00Z</ns1:Timestamp> <ns:ControlSequence> <ns:DeviceControl> <ns:Type>3.31.6.42</ns:Type> </ns:DeviceControl> </ns:ControlSequence> <ns:MeterIds> <arr:string>LGZDUMMY19003</arr:string> </ns:MeterIds> <ns:ScheduleInterval> <ns1:End>2011-04-15T16:00:00Z</ns1:End> <ns1:Start>2011-04-15T10:00:00Z</ns1:Start> </ns:ScheduleInterval> </ns:request> </ns:ControlMeterAsync> </soap:Body> </soap:Envelope>
Response (shortened)
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterControlReceive/ReceiveControlM eterResponse</a:Action> <a:MessageID>urn:uuid:700f335c-03dc-4f37-b808-8f2029049361</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveControlMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">CONTROLMETER</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/>
RS09F004-034
Version: 1
Page 34 of 55
23/05/2011
<MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">5b23e1b9-c1db-41e9-82ccb61fa44a1597</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:13:32.641125Z</Timestamp> <ExecutionTimestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-0415T13:13:27.281Z</ExecutionTimestamp> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Readings> <MeterReading> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Interval i:nil="true" xmlns:b="http://www.smartgridservicebus.org/common/2010/11"/> <Intervals i:nil="true"/> <MeterId>LGZDUMMY19003</MeterId> <ReadingTypeSchema>IEEServicePointChannel</ReadingTypeSchema> <Readings> <ReadingTypeReading> <ReadingTypeId>10101</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>1500</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10102</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10103</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10104</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <!-- other readings --> </Readings> <ServicePointId i:nil="true"/> </MeterReading> </Readings> </response> </ReceiveControlMeterResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterControlReceive/ReceiveControlM eterResponse</a:Action> <a:MessageID>urn:uuid:35b033bd-97f3-4560-b94e-1d8f34ac4b8d</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header>
RS09F004-034
Version: 1
Page 35 of 55
23/05/2011
<s:Body> <ReceiveControlMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">CONTROLMETER</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">502af9b6-02ad-42a8-87babc433e596b9e</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:01:37.922375Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.CF13</Id> <Message>Configuration schedule end date is in the past</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T13:01:37.922375Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Readings i:nil="true"/> </response> </ReceiveControlMeterResponse> </s:Body> </s:Envelope>
2.4.1 GetMeterReadingsAsync
GetMeterReadingsAsync operation retrieves meter readings for meters. GetMeterReadingsAsync can be used for AMI on-demand reading of the meter when ReadMeter is true. Otherwise the meter readings are retrieved from Saturnes database. Also historic data can be retrieved using the Interval field. When it is expected that a large volume of data will be retrieved DataReplyAddress should be specified to deliver the meter readings to an ftp or Windows shared folder. Request Field ReplyAddress
Occurrence
Description xsd:string URL of clients call-back endpoint where the response is sent.
RS09F004-034
Version: 1
Page 36 of 55
23/05/2011
Field DataReplyAddress
Occurrence
Description xsd:string It defines a URL where a bulk meter readings data response will be sent. Saturne replies to the client with a normal response containing no meter readings and sends the bulk meter readings data to this URL. Only IEE ARI format of data is currently supported, please see [3]. 2 transfer protocols are supported: ftp when the URL starts with ari:// (please note the forward slash) Windows shared folder when URL starts with ari:\\ (please note the backward slash)
0..1
Interval
0..1
TimeInterval It defines the time interval of the meter reading to be retrieved. If not present instantaneous/current meter readings are retrieved.
Start
xsd:dateTime UTC-based date and time of the start of the interval. xsd:dateTime UTC-based date and time the end of the interval. ArrayOfstring List of meter ids (Meter/Id) for which meter readings are required.
End
MeterIds
string
1..*
xsd:string Meter id. The meter must exist and must be present just once in the list.
ReadingTypeSchema
0..1
ReadingTypeSchemaKind Only CIM and IEEServicePointChannel ReadingTypeId schemas are supported. The schema defines what type of id ReadingTypeIds are. If not present CIM is used.
RS09F004-034
Version: 1
Page 37 of 55
23/05/2011
Field ReadingTypeIds
Occurrence
Description ArrayOfstring List of reading type ids determining which type of meter readings are retrieved. If not present the default readings set is retrieved (configurable).
0..1
string
1..*
xsd:string Reading type id. Saturne maps reading type id to its internal meter data type (configurable). Saturne checks if the mapping exists for the particular reading type id. xsd:boolean It determines if the meter will be communicated with for data retrieval. If true the readings will be retrieved from the meter otherwise from the database. If not present false is used.
ReadMeter
0..1
ServicePointIds
0..1
Description xsd:dateTime UTC-based date and time when the meter readings were retrieved. ArrayOfMeterReading Readings of meter(s). MeterReading Meter readings for a particular meter for which reading of the meter succeeded. It can be present even if the response returns failure. See MeterReading.
0..1
Readings
0..1
MeterReading
0..*
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <soap:Header/> <soap:Body> <ns:GetMeterReadingsAsync> <ns:request> <ns1:MessageId>MTR0102030405</ns1:MessageId> <ns1:ReplyAddress>http://metering-system-client/IMeteringSystemReceive</ns1:ReplyAddress>
RS09F004-034
Version: 1
Page 38 of 55
23/05/2011
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterDataCollectionReceive/ReceiveG etMeterReadingsResponse</a:Action> <a:MessageID>urn:uuid:0d8a0376-8cae-40d8-a80e-ea690dd3bc70</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveGetMeterReadingsResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">MTR0102030405</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">b72f018a-8f04-425f-a85323e606d0a077</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:23:01.28175Z</Timestamp> <ExecutionTimestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-0415T13:23:01.28175Z</ExecutionTimestamp> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LastMessage xmlns="http://www.smartgridservicebus.org/common/2010/11">true</LastMessage> <MessageNumber xmlns="http://www.smartgridservicebus.org/common/2010/11">1</MessageNumber> <Readings> <MeterReading> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Interval i:nil="true" xmlns:b="http://www.smartgridservicebus.org/common/2010/11"/> <Intervals i:nil="true"/> <MeterId>LGZDUMMY19003</MeterId> <ReadingTypeSchema>IEEServicePointChannel</ReadingTypeSchema> <Readings> <ReadingTypeReading> <ReadingTypeId>10101</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>1500</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10102</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading>
RS09F004-034
Version: 1
Page 39 of 55
23/05/2011
<ReadingTypeId>10103</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10104</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10105</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10106</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> </Readings> <ServicePointId i:nil="true"/> </MeterReading> <MeterReading> <CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Interval i:nil="true" xmlns:b="http://www.smartgridservicebus.org/common/2010/11"/> <Intervals i:nil="true"/> <MeterId>LGZDUMMY19004</MeterId> <ReadingTypeSchema>IEEServicePointChannel</ReadingTypeSchema> <Readings> <ReadingTypeReading> <ReadingTypeId>10101</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>1500</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10102</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10103</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10104</ReadingTypeId> <Readings>
RS09F004-034
Version: 1
Page 40 of 55
23/05/2011
<Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10105</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10106</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> </Readings> <ServicePointId i:nil="true"/> </MeterReading> </Readings> </response> </ReceiveGetMeterReadingsResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterDataCollectionReceive/Receiv eGetMeterReadingsResponse</a:Action> <a:MessageID>urn:uuid:0944e937-4c5b-4059-8243-5b6f0c2a4f90</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveGetMeterReadingsResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">MTR0102030405</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">b9a1274b-452c-402f-8744bf0a01ed8f55</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:19:54.7505Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">2.9</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.A3</Id> <Message>Meter LGZDUMMY19999 doesn't exist</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T13:19:54.7505Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <LastMessage xmlns="http://www.smartgridservicebus.org/common/2010/11">true</LastMessage> <MessageNumber xmlns="http://www.smartgridservicebus.org/common/2010/11">1</MessageNumber> <Readings/> </response> </ReceiveGetMeterReadingsResponse> </s:Body> </s:Envelope>
RS09F004-034
Version: 1
Page 41 of 55
23/05/2011
RS09F004-034
Version: 1
Page 42 of 55
23/05/2011
Description
RS09F004-034
Version: 1
Page 43 of 55
23/05/2011
Field ReplyAddress
Occurrence
Description xsd:string URL of clients call-back endpoint where the response is sent. TimeInterval Schedule interval specifying when the meter configuration should happen. If not present Start is the current time and End is the current time plus 10 minutes (configurable in Saturne).
ConfigurationSchedule
0..1
Start
xsd:dateTime UTC-based date and time when is the meter configuration scheduled and should start. xsd:dateTime UTC-based date and time when the meter configuration should be finished. If there is no response from the meter after this point in time the request times out. ArrayOfstring List of meter ids (Meter/Id) which will be reconfigured.
End
MeterIds
string
1..*
xsd:string Meter id. The meter must exist and must be present just once in the list.
GroupIds
ArrayOfstring List of group ids meter(s) will be configured with. xsd:string Configuration group id Saturnes meter configuration id. Configuration groups have to be preconfigured in Saturne with corresponding meter configurations. ArrayOfstring Not supported.
string
1..*
ServicePointIds
0..1
Description xsd:dateTime UTC-based date and time when all meters where configured.
0..1
RS09F004-034
Version: 1
Page 44 of 55
23/05/2011
Field Readings
Occurrence
0..1
Example
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <soap:Header/> <soap:Body> <ns:ChangeMeterGroupAsync> <ns:request> <ns1:MessageId>CHANGEGROUP</ns1:MessageId> <ns1:ReplyAddress>http://metering-system-client/IMeteringSystemReceive</ns1:ReplyAddress> <ns1:Timestamp>2011-02-07T15:00:00Z</ns1:Timestamp> <ns:GroupIds> <arr:string>GROUP1</arr:string> </ns:GroupIds> <ns:MeterIds> <arr:string>LGZDUMMY19003</arr:string> </ns:MeterIds> <ns:ServicePointIds> </ns:ServicePointIds> </ns:request> </ns:ChangeMeterGroupAsync> </soap:Body> </soap:Envelope>
Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterConfigurationReceive/ReceiveChangeMeterGroup Response</a:Action> <a:MessageID>urn:uuid:1b233793-0423-4481-a45f-96d9ae5204c0</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveChangeMeterGroupResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">CHANGEGROUP</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">db5d157b-c925-450c-a0e32548a43c8f89</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:25:29.6255Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <Readings i:nil="true"/> </response> </ReceiveChangeMeterGroupResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterConfigurationReceive/ReceiveCh angeMeterGroupResponse</a:Action> <a:MessageID>urn:uuid:1b233793-0423-4481-a45f-96d9ae5204c0</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body>
RS09F004-034
Version: 1
Page 45 of 55
23/05/2011
<ReceiveChangeMeterGroupResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">CHANGEGROUP</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">db5d157b-c925-450c-a0e32548a43c8f89</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:25:29.6255Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.G2</Id> <Message>Group GROUP1 is unknown</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T13:25:29.641125Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Readings i:nil="true"/> </response> </ReceiveChangeMeterGroupResponse> </s:Body> </s:Envelope>
2.5.2 ConfigureMeterAsync
The ConfigureMeterAsync operation configures meter(s) with specific parameterised meter configuration. Saturne keeps history of all configurations applied to the meter. Switching tariff and power limitation configurations are supported only. Request Field ReplyAddress
Occurren ce
Description xsd:string URL of clients call-back endpoint where the response is sent. TimeInterval Schedule interval specifying when the meter configuration should happen. If not present Start is the current time and End is the current time plus 10 minutes (configurable in Saturne).
ConfigurationSchedule
0..1
Start
xsd:dateTime UTC-based date and time when is the meter configuration scheduled and should start.
RS09F004-034
Version: 1
Page 46 of 55
23/05/2011
Field End
Occurren ce
Description xsd:dateTime UTC-based date and time when the meter configuration should be finished. If there is no response from the meter after this point in time the request times out. ArrayOfstring List of meter ids (Meter/Id) which will be configured.
MeterIds
string
1..*
xsd:string Meter id. The meter must exist and must be present just once in the list.
ServicePointIds
0..1
Configurations
ArrayOfMeterConfigurationSet Meter configurations which are applied to meter(s). MeterConfigurationSet Meter configurations which meter(s) are configured with. Only one set is supported.
MeterConfigurationSet
EffectiveDate
0..1
xsd:dateTime UTC-based date and time when configuration is effective in the meter, e.g. tariff effective date. Applicable only for certain configuration types and can depend on the meter type.
Configurations
ArrayOfMeterConfigurationData List of meter configurations. MeterConfigurationData Details of the meter configuration. Only 1 item is supported.
ConfigurationData
@xsi:type
RS09F004-034
Version: 1
Page 47 of 55
23/05/2011
Field ContractId
Occurren ce
Description xsd:string Identifier of contract which is this configuration related to, e.g. consumption, generation, distribution contract. This value is send directly to a concentrator/meter and its application depends on the meter type. It is supported only for TariffMeterConfiguration.
for TariffMeterConfiguration
TariffId
xsd:string Identifier of tariff definition which is applied to meter(s). The meters are switched to this tariff on EffectiveDate. The tariff definition needs to be pre-configured in Saturne. Saturne checks if the tariff exists.
SpecialDaysCalendarId
0..1
xsd:string Identifier of special days calendar which is applied with the tariff definition to meter(s). The special days calendar needs to be preconfigured in Saturne. Saturne checks if the calendar exists.
for PowerLimitMeterConfiguration
RatePowerLimit
ArrayOffloat List of power limits for each rate starting with rate 1. xsd:float Power limitation in W.
float
1..*
Description xsd:dateTime UTC-based date and time when the meter(s) were configured. ArrayOfMeterReading Readings of meter(s) associated with the meter configuration. Which reading types are returned in ConfigureMeterAsync response is configurable in Saturne.
0..1
Readings
0..1
RS09F004-034
Version: 1
Page 48 of 55
23/05/2011
Field MeterReading
Occurrence
Description MeterReading Meter readings for a particular meter. Only IEEServicePointChannel reading type schema is supported. See MeterReading.
0..*
Example
Request
<soap:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:soap="http://www.w3.org/2003/05/soapenvelope" xmlns:ns="http://www.smartgridservicebus.org/metering/2010/11" xmlns:ns1="http://www.smartgridservicebus.org/comm on/2010/11" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" > <soap:Header/> <soap:Body> <ns:ConfigureMeterAsync> <ns:request> <ns1:MessageId>cfg123456</ns1:MessageId> <ns1:ReplyAddress>http://metering-system-client/IMeteringSystemReceive</ns1:ReplyAddress> <ns1:Timestamp>2011-02-07T15:30:30Z</ns1:Timestamp> <ns:Configurations> <ns:MeterConfigurationSet> <ns:Configurations> <ns:MeterConfigurationData i:type="ns:PowerLimitMeterConfiguration"> <ns:ContractId i:nil="true"/> <ns:RatePowerLimit xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <b:float>1</b:float> <b:float>2</b:float> <b:float>3</b:float> <b:float>4.56</b:float> </ns:RatePowerLimit> </ns:MeterConfigurationData> </ns:Configurations> <ns:EffectiveDate>2011-02-15T17:00:00Z</ns:EffectiveDate> </ns:MeterConfigurationSet> </ns:Configurations> <ns:MeterIds> <arr:string>LGZDUMMY19003</arr:string> </ns:MeterIds> <ns:ServicePointIds> </ns:ServicePointIds> </ns:request> </ns:ConfigureMeterAsync> </soap:Body> </soap:Envelope>
Response (shortened)
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterConfigurationReceive/ReceiveCo nfigureMeterResponse</a:Action> <a:MessageID>urn:uuid:392eb010-b422-4010-81c0-40e8e5faf522</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveConfigureMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">cfg123456</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">511d3ab3-2bef-43b7-8690cd37aaf81e33</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:17:56.813Z</Timestamp> <ExecutionTimestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-0415T13:17:56.859875Z</ExecutionTimestamp> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">0.0</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Readings> <MeterReading>
RS09F004-034
Version: 1
Page 49 of 55
23/05/2011
<CustomData i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Description i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Id i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Name i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Interval i:nil="true" xmlns:b="http://www.smartgridservicebus.org/common/2010/11"/> <Intervals i:nil="true"/> <MeterId>LGZDUMMY19003</MeterId> <ReadingTypeSchema>IEEServicePointChannel</ReadingTypeSchema> <Readings> <ReadingTypeReading> <ReadingTypeId>10101</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>1500</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>10102</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-14T22:00:00Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> <!-- other readings --> <ReadingTypeReading> <ReadingTypeId>431</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-15T13:17:48.375Z</Timestamp> <Value>NA</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>432</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-15T13:17:48.375Z</Timestamp> <Value>1</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>441</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-15T13:17:48.375Z</Timestamp> <Value>1</Value> </Reading> </Readings> </ReadingTypeReading> <ReadingTypeReading> <ReadingTypeId>442</ReadingTypeId> <Readings> <Reading> <ReadingQualities i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <Timestamp>2011-04-15T13:17:48.375Z</Timestamp> <Value>0</Value> </Reading> </Readings> </ReadingTypeReading> </Readings> <ServicePointId i:nil="true"/> </MeterReading> </Readings> </response> </ReceiveConfigureMeterResponse> </s:Body> </s:Envelope>
Error Response
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header>
RS09F004-034
Version: 1
Page 50 of 55
23/05/2011
<a:Action s:mustUnderstand="1">http://www.smartgridservicebus.org/metering/2010/11/IMeterConfigurationReceive/ReceiveCo nfigureMeterResponse</a:Action> <a:MessageID>urn:uuid:a6c94daa-a39a-440b-97e6-4cc554936710</a:MessageID> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">http://metering-system-client/IMeteringSystemReceive</a:To> </s:Header> <s:Body> <ReceiveConfigureMeterResponse xmlns="http://www.smartgridservicebus.org/metering/2010/11"> <response xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <CorrelationId xmlns="http://www.smartgridservicebus.org/common/2010/11">cfg123456</CorrelationId> <DataReplyAddress i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <MessageId xmlns="http://www.smartgridservicebus.org/common/2010/11">37517535-35e1-4f69-a28070232279dca0</MessageId> <MessageSource i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ReplyAddress xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <Timestamp xmlns="http://www.smartgridservicebus.org/common/2010/11">2011-04-15T13:15:46.8755Z</Timestamp> <ExecutionTimestamp i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <LogMessages i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ProcessingInfo i:nil="true" xmlns="http://www.smartgridservicebus.org/common/2010/11"/> <ResultCode xmlns="http://www.smartgridservicebus.org/common/2010/11">5.2</ResultCode> <ResultMessages xmlns="http://www.smartgridservicebus.org/common/2010/11"> <ResultMessage> <Category/> <Id>MSAPI.CF10</Id> <Message>Invalid configuration request : number of power configurations > 1</Message> <Severity>Error</Severity> <Source>SATURNE</Source> <Timestamp>2011-04-15T13:15:46.8755Z</Timestamp> <EntityId i:nil="true"/> <EntityType i:nil="true"/> <InnerMessages i:nil="true"/> <TaskIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> </ResultMessage> </ResultMessages> <Readings i:nil="true"/> </response> </ReceiveConfigureMeterResponse> </s:Body> </s:Envelope>
RS09F004-034
Version: 1
Page 51 of 55
23/05/2011
3 Error Messages
Following table contains Id of ResultMessage and its corresponding Message which is returned in a response in ResultMessages in case of error.
ResultMessage/Id
MSAPI.A0 MSAPI.A1 MSAPI.A2 MSAPI.A3 MSAPI.A4 MSAPI.A5 MSAPI.A6 MSAPI.A7 MSAPI.C1 MSAPI.C2 MSAPI.C3 MSAPI.CF1 MSAPI.CF2 MSAPI.CF3 MSAPI.CF4 MSAPI.CF5 MSAPI.CF6 MSAPI.CF7 MSAPI.CF8 MSAPI.CF9 MSAPI.CF10 MSAPI.CF11 MSAPI.CF12 MSAPI.CF13 MSAPI.CF14 MSAPI.CF15 MSAPI.CF16 MSAPI.CF17 MSAPI.CF18 MSAPI.D1 MSAPI.DP1 MSAPI.G1 MSAPI.G2 MSAPI.G3
ResultMessage/Message
Error : {0} Multiple definition of meter {0} Access to database is denied Meter {0} doesn't exist File server is unavailable No request service to apply No request service for meter {0} Unable to store request in database Control sequence is empty Invalid control sequence type {0} Control schedule end date is in the past Invalid configuration request : no load profile configuration allowed Configuration request is empty One of the configuration request is empty Invalid configuration request : power and tariff configuration are not allowed in the same request Invalid configuration request : number of tariff configurations > 3 Unable to store request in database Unable to store configuration in database Unable to get configuration identifiers from database Cannot find the tariff/calendar in Saturne Invalid configuration request : number of power configurations > 1 Invalid configuration request : number of powers in power configuration = 0 Configuration already exists in Saturne for service point {0} Configuration schedule end date is in the past Invalid configuration request : invalid tariff contract id Meter {0} is not active Invalid power configuration in translation file for meter type {0} Invalid tariff configuration in translation file for meter type {0} Invalid contactor state for meter {0} Unable to configure meter {0} An error occurred pending request execution. No group defined Group {0} is unknown Unable to change group meter {0}
RS09F004-034
Version: 1
Page 52 of 55
23/05/2011
ResultMessage/Id
MSAPI.M1 MSAPI.M2 MSAPI.M3 MSAPI.M4 MSAPI.M5 MSAPI.P1 MSAPI.P2 MSAPI.P3 MSAPI.P4 MSAPI.P5 MSAPI.P6 MSAPI.P9 MSAPI.P10 MSAPI.P11 MSAPI.P13 MSAPI.P14 MSAPI.P15 MSAPI.P16 MSAPI.P17 MSAPI.P18 MSAPI.P19 MSAPI.P20 MSAPI.P21 MSAPI.P22 MSAPI.P23 MSAPI.P24 MSAPI.P25 MSAPI.P26 MSAPI.P27 MSAPI.P28 MSAPI.P29 MSAPI.P30 MSAPI.P31 MSAPI.T1
ResultMessage/Message
Mapping file unavailable No reading group in SC02 service file {0} Meter type unknown in mapping file Invalid reading type {0} mRIDs not found Meter cannot be null Service point cannot be null Serial number cannot be null Meter model cannot be null Meter {0} already exists Meter type {0} does not exist Unable to found configuration for meter type {0} Database configuration error. Missing external code {0}. Service point {0} already exists. Meter {0} does not exist. Service point {0} does not exist. Changing meter model is not supported, meter model {0} does not match meter model {1} Meter {0} is attached to a service point, the service point must be specified Meter {0} is not attached to Service point {1} at {2} Service point {0} is already attached to a meter. Meter {0} is already attached to a service point. Meter matching model cannot be found in mapping file Device request is null Device model cannot be null Device type {0} does not exist in Saturne Changing device type is not supported, device type {0} does not match device type {1} Unable to find configuration for device type {0} Device matching model cannot be found in mapping file Unable to find device to replace {0} Unable to deactivate device Devices request is null One device request is null Invalid device type - only Concentrator is supported as a device The timeout has been reached.
RS09F004-034
Version: 1
Page 53 of 55
23/05/2011
4 Document Control
Version 1 Date 23/05/2011 Description First release including all examples and updates. It reflects changes in Asais.Addins.MeteringSystem.ISB v3.0.9 of Saturne. Author TS
RS09F004-034
Version: 1
Page 54 of 55
23/05/2011
5 Glossary
Term AMI API CIM IEC MS WCF SOAP WS WSDL XML XSD Definition Advanced Metering Infrastructure Application Programming Interface Common Information Model International Electrotechnical Commission Metering System Windows Communication Foundation Simple Object Access Protocol Web Services Web Services Definition Language eXtensible Markup Language XML Schema
RS09F004-034
Version: 1
Page 55 of 55