Meter Reading Exchange

create

Method	URL
POST	api/esh/meter_reading_exchange/create

The Meter Reading Exchange process is used by a supplier to exchange meter readings for small-scale connection. This is needed for event related meter readings and periodic meter readings.

Pre-requisite steps

1. The initiator sends a request to create a Global Task meter_reading_exchange

2. If the validation of the input parameters results in an error the ‘Global Task’ is not created and the errors are returned.

3. A Global Task is created and the GlobalTask.ID is returned.

Global Task steps

1. The ValueA adapter sends out the request to EDSN via an XML request: MeterReadingExchangeNotification.

EDSN rejection handling

1. EDSN validates the request (see EDSN validations). If there are inaccuracies, the message is rejected.

2. The ValueA adapter collects the rejection, if available, from EDSN: RejectionMeterReadingResponse.

3. When a rejection is received the status of the GlobalTask is set to rejected.

Dispute handling

1. A GlobalTask is started for the dispute handling (Meter Reading Dispute)

2. When the dispute handling is finished the status is set to Ready when deadline for dispute is expired or the dispute is not accepted. Otherwise the status is set to Rejected.

Grid Operator rejection handling

1. The Grid Operator validates the request (see Grid Operator validations). If there are inaccuracies, the message is rejected.

2. The ValueA adapter collects the rejections send by the Grid Operator, if available, from EDSN: MeterReadingRejectionResponse.

3. When a rejection is received the status of the GlobalTask is set to rejected.

Input parameters

meter_reading_exchange global_task input parameters
type	object
properties
ean_id	type	string
	pattern	^[0-9]{18}$
process_id	enum	MOVEIN, MOVEOUT, EOSUPPLY, SWITCHLV, PERMTR, ALLMTCHG, MONTHMTR
external_id	external dossier id, mandatory if process_id is MOVEIN, MOVEOUT, EOSUPPLY or SWITCHLV
	type	string
consumer	type	string
	pattern	^[0-9]{13}$
initiator	type	string
	pattern	^[0-9]{13}$
product_type	enum	ELK, GAS
meter_id	type	string
	maxLength	18
	minLength	1
nr_of_registers	type	integer
	maximum	9
	minimum	0
registers	type	array
	items	register
use_local_data_for_validation	If true then the latest available MeteringPoint data will be used to perform additional validations
	type	boolean
	default	False

register

type	object
properties
measure_unit	enum	KWH, M3N, MTQ
metering_direction	enum	LVR, TLV
nr_of_digits	type	integer
	maximum	9
	minimum	1
tariff_type	enum	L, N
readings	type	array
	items	reading
additionalProperties	False

reading

type	object
properties
reading	type	integer
reading_date	type	string
	format	date
reading_method	Calculated, Agreed on, Customer/P1-reading, Physical reading, P4-reading
	enum	005, 102, 22, 003, 004
additionalProperties	False

EDSN validations

validation	error message	error code
The request to consult, a connection is complete and syntactically correct	Message incomplete or syntactically incorrect	200
If a transaction dossier is provided: does the transaction dossier exist?	Transaction dossier unknown	215
In case of an event related reading: does the transaction dossier exist?	Transaction dossier unknown	215

Grid Operator validations

validation	error message	error code
Is the measurement data not too old?	Determined measurement data too old	231
Is it a dispute or non-event meter readings for GV?	Delivery of dispute or non-event meter readings not possible for a large-scale metering point	232
The connection belongs to the domain of the relevant network operator	EAN-code connection unknown	201
has the metering point a measuring device?	Metering point has no measuring device	234
Does the amount of meter readings equals the number of active registers?	Amount of meter readings unequals the number of active registers	235
Does the number of digits in the meter readings equals the number of digits of the register?	Number of digits in the meter readings unequals the number of digits of the register	236
Is the meter reading exchange for a small-scale metering point?	Meter reading exchange not possible for a large-scale metering point	254
In case of an periodic meter reading: is the supplier the current supplier?	Supplier is not the current supplier	237
In case of an periodic meter reading: is the meter reading not earlier then a already determined meter reading?	Meter reading is ahead of already determined meter reading	238
In case of an event: is the supplier the initiator of the event?	Supplier is not the initiator of the event	239
In case of an event: is an event known on the recording date?	No event known on recording date	240

Output parameters

meter_reading_exchange global_task return parameters
properties
global_task_id	GlobalTask.id
	type	string
	format	uuid
error	type	object
	properties
	messsageid	ValueA Broker message.id
		type	string
		format	uuid
	validations	type	array
		items	global_task_validation

global_task_validation

type	object
properties
message	type	string
ref	optional reference to parameter
	type	string / null
user_message	type	string / null

getStatus

Method	URL
GET	api/esh/meter_reading_exchange/get_status

Get status input parameters

global_task get_status input parameters
type	object
properties
id	GlobalTask.id
	type	string
	format	uuid

Get status return parameters

global_task get_status return parameters
type	object
properties
status	type	string
status_date	type	string
	format	date
status_description	type	string / null
status_details	type	array
	items	status_detail
error	type	object
	properties
	messsageid	ValueA Broker message.id
		type	string
		format	uuid
	validations	type	array
		items	get_status_validation

status_detail

type	object
properties
description	type	string
remark	type	string / null

get_status_validation

type	object
properties
message	type	string
ref	optional reference to parameter
	type	string / null
user_message	type	string / null

getData

Method	URL
GET	api/esh/meter_reading_exchange/get_data

Get data input parameters

meter_reading_exchange get_data input parameters
type	object
properties
id	GlobalTask.id
	type	string
	format	uuid

Get data return parameters

meter_reading_exchange get_data return parameters
type	object
properties
meter_reading_dispute	type	object
	properties
	consumer	type	string
		pattern	^[0-9]{13}$
	initiator	type	string
		pattern	^[0-9]{13}$
	comment	type	string
		maxLength	1000
		minLength	1
	product_type	enum	ELK, GAS
	meter_id	type	string
		maxLength	18
		minLength	1
	nr_of_registers	type	integer
		maximum	9
		minimum	0
	registers	type	array
		items	Dispute Register
meter_reading_dispute_result	type	object
	properties
	initiator	type	string
		pattern	^[0-9]{13}$
	consumer	type	string
		pattern	^[0-9]{13}$
	accepted	Yes, No
		enum	J, N
	comment_result	type	string
		maxLength	100
		minLength	1
	product_type	enum	ELK, GAS
meter_reading_rejection	type	object
	properties
	consumer	type	string
		pattern	^[0-9]{13}$
	initiator	type	string
		pattern	^[0-9]{13}$
	product_type	enum	ELK, GAS
	reasons	type	array
		items	Reason
rejection_meter_reading	type	object
	properties
	reasons	type	array
		items	Reason
error	type	object
	properties
	messsageid	ValueA Broker message.id
		type	string
		format	uuid
	validations	type	array
		items	get_data_validation

Dispute Register

type	object
properties
measure_unit	enum	KWH, M3N, MTQ
metering_direction	enum	LVR, TLV
nr_of_digits	type	integer
	maximum	9
	minimum	1
tariff_type	enum	L, N
readings	type	array
	items	Dispute Reading

Dispute Reading

type	object
properties
reading	type	integer
reading_date	type	string
	format	date
reading_method	Calculated, Agreed on, Customer/P1-reading, Physical reading, P4-reading
	enum	005, 102, 22, 003, 004

Reason

type	object
properties
code	type	string
text	type	string / null

get_data_validation

type	object
properties
message	type	string
ref	optional reference to parameter
	type	string / null
user_message	type	string / null

getMessages

Method	URL
POST	api/esh/meter_reading_exchange/get_messages

This Task wil get all available MeterReadingExchange messages from EDSN.

Get Input parameters

meter_reading_exchange get_messages input parameters
type	object
properties

Get return parameters

meter_reading_exchange get_messages return parameters
type	object
properties
message_type	type	string
records_received	type	integer
error	type	object
	properties
	messsageid	ValueA Broker message.id
		type	string
		format	uuid
	validations	type	array
		items	get_validation

get_validation

type	object
properties
message	type	string
ref	optional reference to parameter
	type	string / null
user_message	type	string / null

sendMessages

Method	URL
POST	api/esh/meter_reading_exchange/send_messages

This Task wil send all available MeterReadingExchange(Notifications) to EDSN.

Send Input parameters

meter_reading_exchange send_messages input parameters
type	object
properties

Send return parameters

meter_reading_exchange send_messages return parameters
type	object
properties
message_type	type	string
message_ids	type	array
	items	EDSN message.id
		type	string
		format	uuid
error	type	object
	properties
	messsageid	ValueA Broker message.id
		type	string
		format	uuid
	validations	type	array
		items	send_validation

send_validation

type	object
properties
message	type	string
ref	optional reference to parameter
	type	string / null
user_message	type	string / null

eventMessageCollector

Method	URL
POST	api/esh/meter_reading_exchange/event_message_collector

This Task wil get all event based MeterReadingExchange messages from EDSN.

Event Message Collector Input parameters

meter_reading_exchange event_message_collector input parameters
type	object
properties
from_date_time	Date-time format as defined in RFC 3339, section 5.6.
	type	string
	format	date-time
batch_size	Maximum number of messages to be fetched, because minimum timespan is 1 second it can return more records then requested
	type	integer
	default	1000

Event Message Collector Return parameters

meter_reading_exchange event_message_collector return parameters
type	object
properties
to_date_time	type	string
	format	date-time
records_received	type	integer
messages	type	array
	items	meter_reading_exchange_response
error	type	object
	properties
	messsageid	ValueA Broker message.id
		type	string
		format	uuid
	validations	type	array
		items	collector_validation

meter_reading_exchange_response

type	object
properties
consumer	type	string
	pattern	^[0-9]{13}$
initiator	type	string
	pattern	^[0-9]{13}$
valid_from_date	type	string
	format	date
valid_to_date	type	string
	format	date
product_type	enum	ELK, GAS
volumes	type	array
	items	mre_res_volume

mre_res_volume

type	object
properties
valid_from_date	type	string
	format	date
valid_to_date	type	string
	format	date
volume	type	string
	maxLength	15
	minLength	1
calorific_corrected_volume	type	string
	maxLength	15
	minLength	1
registers	type	array
	items	mre_res_register
	maxItems	1
	minItems	0
readings	type	array
	items	mre_res_reading
	maxItems	2
	minItems	0

mre_res_register

type	object
properties
metering_direction	enum	LVR, TLV
tariff_type	enum	L, N

mre_res_reading

properties
meter_id	type	string
register_id	type	string
tariff_type	type	string
mutation_date	type	string
	format	date
reading	type	integer
reading_method	type	string
determined_party	type	string

collector_validation

type	object
properties
message	type	string
ref	optional reference to parameter
	type	string / null
user_message	type	string / null