energy management information system web service for remote readings and bills … · 2 data...

ENERGY MANAGEMENT

INFORMATION SYSTEM

EMIS Web Service for Remote Readings and Bills

Issue 2020-05-08


1

CONTENTS 1 Overview ............................................................................................................................................................... 3

2 Data Structure ...................................................................................................................................................... 4

2.1 Remote bills .................................................................................................................................................. 4

2.2 Basic Remote readings.................................................................................................................................. 5

2.3 Advanced remote readings ........................................................................................................................... 6

3 Web Service Data Exchange ................................................................................................................................. 7

3.1 Overview ....................................................................................................................................................... 7

3.2 Connecting to the REST Web Service ........................................................................................................... 7

3.3 Authentication .............................................................................................................................................. 7

3.3.1 Authentication Example ....................................................................................................................... 8

3.3.2 Debugging MAC calculation .................................................................................................................. 8

3.4 XML Namespace ........................................................................................................................................... 9

3.5 Echo Method ................................................................................................................................................ 9

3.5.1 Echo Request ........................................................................................................................................ 9

3.5.2 Echo Response ...................................................................................................................................... 9

3.5.3 Examples ............................................................................................................................................... 9

3.6 Batch Sending Method ............................................................................................................................... 10

3.6.1 Batch Request Structure ..................................................................................................................... 10

3.6.2 Batch Response Structure................................................................................................................... 11

3.6.3 Batch-Contained Objects Structure .................................................................................................... 11

3.7 Query Methods ........................................................................................................................................... 25

3.7.1 Basic Remote Readings – Meters and Readings ................................................................................. 25

3.7.2 List of OIB-s (OIB – Personal identification number/Osobni identifikacijski broj) .............................. 29

3.8 Service Response Codes ............................................................................................................................. 30

4 Command-Line Client ......................................................................................................................................... 32

4.1 Installing the Client ..................................................................................................................................... 32

4.2 Configuring the Client ................................................................................................................................. 32

4.2.1 Quick Start .......................................................................................................................................... 32

4.2.2 Configuration Parameters .................................................................................................................. 33

4.2.3 Passing Parameters in Command Line................................................................................................ 34

4.2.4 Getting a Help Cheat-Sheet ................................................................................................................ 34

4.2.5 Encrypting a Password ........................................................................................................................ 34

4.2.6 Default Configuration File Locations .................................................................................................. 34


2

4.2.7 Using the Client behind a Web Proxy ................................................................................................. 34

4.3 Return Codes .............................................................................................................................................. 35

4.4 Scheduling Batches ..................................................................................................................................... 35

5 Simple Client Example in Java ............................................................................................................................. 36

6 DataSupplier Web Interface ............................................................................................................................... 38


3

1 OVERVIEW Required personnel qualifications for implementing a connection to the service:

Persons implementing a connection to web service need to be familiar with the following concepts:

• Web services (even for using the provided EMIS web services client)

• XML and/or JSON data structure

• Text encodings

Besides this, for implementing your own web service client, of course, you need a developer proficient in your

technology of choice.

This document explains web services for sending:

• Basic remote meter readings

• Advanced remote bills

• Advanced remote meter readings (in development)

What do I have to send? Which chapters do I need to read?

If you are… and you… then you will… See chapters

… a company which supplies energy or water, … need to send bills, … send advanced bills. 2.1 and 3.6.3.1

… a company which supplies energy or water, … need to send readings, … send advanced readings. 2.3 and 3.6.3.2

… a smart metering company, … need to send readings, … send basic readings. 2.2 and 3.6.3.3.

… a smart metering company, … need to send readings, … in some cases you will send advanced readings.

2.3 and 3.6.3.2

Besides that, you also need to read the chapters on connecting, authentication (3.1, 3.2, 3.3)

What is the difference between meanings of words “basic” and “advanced”?

Basic readings Advanced readings

EMIS administrators will provide you with … … a list of meters with their EMIS IDs and descriptions.

It is likely that EMIS administrators will be periodically sending you updates for the list of new meters with their EMIS IDs. (EMIS ID never changes, but a list of meters for which you will send readings might).

*Subject to signed contract

… a list of institutions. You will determine from your business data which meters belong to these institutions. You will first send to EMIS a list of meters (with IDs from your database) that belong to these institutions, following which you will start send readings.

(For sending a list of meters, we use the term “registering meters”).

You will periodically update a list of registered meters that belong to these institutions as they might change.

Readings that you will send are referring to… … meter IDs from EMIS database …meter ID-s from your own database.

Note: you will actually refer them to as “meter device counter ID” (see later in document)

Before you can start sending readings… …you don’t have to do anything special. … you must register meters (with IDs from your database + description) + some other registries (see details further in documentation)

Meter from EMIS database and meter from your database need to be linked (1-on-1, using their description, serial number, etc.). That linking will be performed…

… by data supplier (you).

You will receive a list of meters in EMIS with their IDs from EMIS database, you will find

… by EMIS administrators.

When you register meters in EMIS, EMIS administrators will link a list of “your” meters with a list of EMIS meters.


4

corresponding meter in your database (corresponding ID).

If one meter has more counters (e.g. electricity has daily active consumption, nightly active consumption, daily reactive consumption, nightly reactive consumption)…

… values of all counters taken at same time (for the same meter) are sent in the same data record (XML or JSON).

Record refers to EMIS meter ID.

... values of each counter taken at same time (for the same meter) is send in the separate data record (XML or JSON).

Record refers to Meter device counter ID (from your database)

(This is a simplified explanation. For further details please refer to the following chapters.)

Note: Bills are always sent using the concept described in advanced readings, so you always have to register a list

of energy carriers, tariff models, bill fields, vendors and meters.

2 DATA STRUCTURE

2.1 Remote bills

In order to use the Web Service, the data model structure will be explained first.

This is data model for sending of remote bills. This model is independent from structure and primary/foreign keys

of EMIS model. Records IDs in this model are defined by data supplier, and only after the data is sent to EMIS, it

will be processed and mapped to EMIS IDs.

Bills

Bill DataBILL_ID

Metering Points

METER_ID

Vendors

Tariffs

TARIFF_ID

ENERGENT_ID

VENDOR_ID

Energy Carrier Fields

BILLITEM_ID

ENERGENT_IDENERGENT_IDENERGENT_ID

Energy Carriers

VENDOR_ID

1. Vendors – Vendors provide one or more energy products. A vendor can issue one more types of bills for

one energy products. These usually make a fixed registry that seldom changes.

2. Energy Carriers – Also referred to as “energy products”, such as electrical energy, natural gas and so on.

Energy carriers also make a fixed registry.

3. Energy Carrier Fields – Each energy product can have several fields that are specified on a bill (amount,

fee, lump sum, interest etc.). Energy Carrier Fields make a registry that does not change often.

4. Tariff – Tariffs usually appear in case of electrical energy, but they can also be found in cases of other

energy products. They are internally used in EMIS group bill field entries, specify different billing rates etc.

There must be at least one tariff per energy carrier registered. Tariffs are also seldom changed.


5

5. Metering Points – Metering point (for which the bill is sent) is a location for which the bill is issued. It is

not necessarily identical to metering point that reads the consumption. For instance, in cases of electrical

energy, water or gas, the bill is issued to the metering point even when e.g. water consumption is

calculated per number of occupants in a flat (the bill is issued on the flat so there is a virtual billing and

metering point.)

In cases such as central heating where radiators have heat meters, each meter is a metering point (as far

as reading is concerned) but the bill is issued for a flat. Although such situation can be discussed with Data

Supplier, the flat is a fictitious billing and metering point (receives the bill, does not need readings as

well). The flat ID is an identifier of the metering point to which the bill is issued. The metering point ID is

NOT a customer’s ID because the customer can change and the flat/geographical location does not

change.

Other synonyms for metering point are also: “meter” and “metering location”.

Each of the above objects must have an identifier that is unique throughout a data supplier domain.

2.2 Basic Remote readings This is data model for basic remote readings. Metering points are assigned to your DataSupplier account by EMIS

administrators, so you can send only readings for assigned meters.

Metering Points(defined in EMIS, and assigned to you, not

editable by web service, use this ID’s when sending readings)

Readings

METER_ID

1. Readings – For each metering point, data suppliers can periodically or continuously send remote

readings. Unlike other objects previously described, readings are referring to EMIS Metering Point IDs

(available through end-user GUI), rather than using data-supplier assigned IDs.

Please note that a “metering point” is not the same as a “metering device”! When sending readings you

are referring to metering points. If a metering device is changed, and counter values are reset, new

metering device must be created through EMIS user interface – it is not possible to create new metering

device through web service.


6

2.3 Advanced remote readings

Metering Points(PK: METER_ID)

ENERGENT_ID

Energy Carriers(PK: ENERGENT_ID)

Metering Devices (PK: MTR_DEVICE_ID)

METER ID

Energy Carrier Counters (PK: ENG_COUNTER_ID)

ENERGENT_ID

Metering Device Counters (PK: MTR_DEVICE_ID, ENG_COUNTER_ID)

DEVICE_ID

ENG_COUNTER_ID

Reading

DVC_COUNTER_ID

Note: Energy carriers and Metering points are the same entity as in sending of Remote bills, so you don’t have to

register them twice.

1. Energy Carriers – Also referred to as “energy products”, such as electrical energy, natural gas and so on.

2. Energy Carrier Counter – Each energy carrier has one or more measurable properties. While

“consumption” is the only property for most of them, the electricity has “daily active”, “nightly active”,

“daily reactive”, “nightly reactive”, “max power consumed in last 15 minutes” and others. Each one of

these values is represented by a different counter.

3. Metering Points (Meters) – Metering point is a location for which readings are sent. The metering point

ID is NOT a customer’s ID because a customer can change, but a flat/geographical location always stays

the same.

Other synonyms for metering point are also “meter” and “metering location”.

4. Metering Device - represents a physical device installed on a metering location. The devices on a location

can occasionally be replaced (so a metering device has an installation date and a removal date), while the

location remains the same.

Please keep in mind that a “metering device” is not the same as a “meter / metering point”)!

Only one metering device can be installed on a metering point at a time.

5. Metering Device Counters – represents energy counter on metering device. Different metering devices,

even those that were installed on the same metering location (at different times), can have different

counters that initially have to be registered with each meter. Each counter has a correction coefficient

that a company maintaining the meters determines by a calibration process.

6. Reading – One reading has a metering device ID, energy counter ID, and a date/time. You will be sending

a separate reading for each device counter. Note that readings do not refer to meter ID, but metering

device ID!


7

3 WEB SERVICE DATA EXCHANGE

3.1 Overview

Data from the external applications can be delivered to the EMIS by a REST Web Service. Messages can be in

either XML or JSON format, sent by HTTP protocol to the URL of the web service method. The HTTP message

header must contain a sender’s username and a security MAC (Message Authentication Code) value, calculated as

a hash of the sent data and a secret pre-shared key.

The following data can be exchanged this way:

A1) For billing companies that send remote bills:

1. Energy Carrier Vendors

2. Energy Carriers

3. Tariffs

4. Metering Points

5. Bills

A2) For billing companies that send advanced remote readings:

1. Energy Carriers

2. Metering points

3. Energy Carrier Counters

4. Metering Devices

5. Metering Device Counters

6. Advanced Remote Readings

B) For companies that manage energy and water metering devices, their SCADA systems, and are responsible

for sending of hourly remote readings:

• Basic Remote Readings

C) For companies that send sensor readings (temperature, humidity, pressure, CO₂, noise …) please refer to

the document “EMIS Web Service for Sensor Readings”!

A single batch-message contains lists of data that should be deleted or inserted. After a successful execution a list

of processed objects will be returned (only ID fields will be kept, while others will be omitted), together with

corresponding timestamps. In case of an error the service returns an object with the original fields, together with

the corresponding error codes and error descriptions.

3.2 Connecting to the REST Web Service HTTP traffic between a client and the URI of the web service must be allowed through firewalls. In further text

“{SERVICE_URI}” specifies the base URI of the web service.

The messages can be in either XML or JSON format. Base URI for JSON communication will be specified as

“{SERVICE_URI}/json”, and URI for XML communication will be specified as “{SERVICE_URI}/xml”.

All the messages should be UTF-8 encoded.

3.3 Authentication The HTTP-Header section of each request must contain the following:

Parameter Description

X-Ekonerg-Login Data-Supplier username


8

X-Ekonerg-MAC MAC (Message Authentication Code) of the HTTP-Body. Calculated as a SHA-256 digest of the message body combined with a secret pre-shared key, username and method URI (described below)

The MAC must be calculated as follows:

1. Instantiate an SHA-256 digest object and initialize with the following bytes:

(httpMethod + "\n" + methodUri + "\n" + username + "\n" + password).getBytes(Utils.UTF8)

2. Calculate digest of the HTTP body using UTF-8 encoding.

3. Encode the digest result as Base64 and set it as a HTTP-Header parameter named “X-Ekonerg-MAC “

• httpMethod = GET, POST, DELETE, …

• methodUri = part of the URI after application base path and without request parameters

o Example: if URI is http://localhost:8080/em-remote-service/sensors/json/readings/sensor/1564564?fromDate=2018-02-06T13:00:00&toDate=2018-02-

06T13:30:00 methodUri would be /sensors/json/readings/sensor/1564564

• “\n” is chr(10) only (no chr(13) here)

3.3.1 Authentication Example

• Method URL: https://www.isge.hr/em-remote-service/batch/json/echo

• HTTP method: POST

• Username: TEST_USER

• Password: superSecRet

• Message payload: {"value" : "Äteritsiputeritsipuolilautatsijänkä"}

Create an SHA-256 digest object and feed the following string (UTF-8 encoded bytes):

POST\n/em-remote-service/batch/json/echo\nTEST_USER\nsuperSecRet{"value" :

"Äteritsiputeritsipuolilautatsijänkä"}

NOTES:

• \n is LineFeed (decimal code 10);

• There is no \n between the password and the message payload.

Now take the digest result and encode it as Base64. The result should be:

eKr7YQPvj8sb0uACfirKKFUaGROA4kyYAmDJOER+tNo=

That is the value you should set as your X-Ekonerg-MAC header value, together with the X-Ekonerg-Login set to

TEST_USER.

3.3.2 Debugging MAC calculation

• You can use it for ANY web service method

• Instead of using your own login, use X-Ekonerg-Login:“AUTHTUTORIAL” (leave X-Ekonerg-MAC empty, it is

ignored)

• Server will return “401 Unauthorized error”, but in errDesc field (in JSON body response) will also return

an example how to calculate MAC for the specific demo user AUTHTUTORIAL, and its demo key.

• You cannot perform any actual operation using this login because it always fails with “Unauthorized

exception”, but it is useful if you want a detailed breakdown of MAC calculation for a specific request,

with the expected value.

http://localhost:8080/em-remote-service/sensors/json/readings/sensor/1564564?fromDate=2018-02-06T13:00:00&toDate=2018-02-06T13:30:00



http://localhost:8080/em-remote-service/sensors/json/readings/sensor/1564564


9

3.4 XML Namespace If you are sending XML structure its top object (usually <batch>) must have namespace

http://www.ekonerg.hr/em/bills, i.e. <batch xmlns="http://www.ekonerg.hr/em/bills">

Note that the namespace is the same whether you are sending bills or readings.

JSON structure does not have a namespace.

3.5 Echo Method The echo method is used for integration/authentication testing.

3.5.1 Echo Request

Echo Request Properties

Name Type Info Description

value Text Any string The contents of this string will be returned by the service

3.5.2 Echo Response

Echo Response Properties


status Number HTTP response code Standard HTTP response code

statusDesc Text HTTP response description

Standard HTTP response description

ts Timestamp YYYY-MM-DD’T’HH:mm:ss.SSS

Response timestamp

value Text Any text The same value from the echo request

serviceURL Text HTTP/S link URL of the service (copied from request)

dataSupplierId Text userID User ID

dataSupplierLogin Text userLogin User Login

3.5.3 Examples

Echo Example – Successful0F

1

JSON Request JSON Response POST http://<EMIS-service-url>/batch/json/echo Request Headers: Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Content-Length: 27 Host: <EMIS-service-url> {"value" : "Hello, World!"}

{"status":200,"statusDesc":"OK","ts":"2016-09-30T15:15:31.215","value":"Hello, World!"}

XML Request XML Response POST http://<EMIS-service-url>/batch/xml/echo Request Headers: Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: FZ8NABKpId04g8p07lX3v/edG3+YIXiyvsxMYVSSeoY= Content-Length: 109 Host: <EMIS-service-url> <?xml version='1.0' encoding='utf-8'?>

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2016-09-30T15:13:22.609" value="Hello, World!"/>

1 HTTP request headers are written in italic.

http://www.ekonerg.hr/em/bills


10

<echo xmlns="http://www.ekonerg.hr/em/bills" value="Hello, World!" />

Echo Example – Failed Authentication

JSON Request JSON Response POST http://<EMIS-service-url>/batch/json/echo Request Headers: Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: abcd Content-Length: 27 Host: <EMIS-service-url> {"value" : "Hello, World!"}

{"status":401,"statusDesc":"Unauthorized","ts":"2016-09-30T15:26:29.926","err":"AuthorizationException","errDesc":"Invalid MAC"}

XML Request XML Response POST http://<EMIS-service-url>/batch/xml/echo Request Headers: Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: abcd Content-Length: 109 Host: <EMIS-service-url> <?xml version='1.0' encoding='utf-8'?> <echo xmlns="http://www.ekonerg.hr/em/bills" value="Hello, World!" />

<response xmlns="http://www.ekonerg.hr/em/bills" status="401" statusDesc="Unauthorized" ts="2016-09-30T15:29:23.664" err="AuthorizationException" errDesc="Invalid MAC"/>

3.6 Batch Sending Method This method is used for sending both remote bills and remote readings. It depends of your contract with

customer which set of data will you be sending.

A request contains information about objects that will be added or removed from the system. In order to

minimize overhead, one request can (and should) contain as many objects as possible. I.e., using two consecutive

web-method calls for adding two objects, or adding one and removing another, is strongly discouraged. Since one

request usually contains more objects, in further text we will refer to it as a “Request Batch”.

Each request contains in the HTTP Header section the appropriate Data Supplier ID and a MAC signature used to

verify the authenticity of the message.

A response contains list of processed objects (just their type and IDs) and a list of failed objects, together with

error codes and descriptions.

3.6.1 Batch Request Structure

A batch contains the following entries:

1. List of objects for deletion (“delete” for JSON or <delete> for XML)

2. List of Metering Points to unregister (“unregister” for JSON or <unregister> for XML)

3. List of objects for insertion (“insert” for JSON or <insert> for XML)

Each of the lists contains a list of objects (described above), except the “unregister” list that can contain only

objects of type (“meter”).

The entries in the request will always be processed in the order listed above – deletion first, meters unregistering

second, and finally insertion.

Optionally, a batch can also contain the following fields:

• “id” - identifier


11

• “ts” – Timestamp in YYYY-MM-DD’T’HH:mm:ss.SSS format

Return batches may also include the following fields:

• “err” – Error name (exception class name)

• “errDesc” – Error description (detailed description)

The following are the types of available objects contained in the “delete” and/or “insert” list:

• “vendor” – Energy carrier vendor

• “energyCarrier” – Energy carrier

• “energyCarrierField” – Bill field for an energy carrier

• “tariff” – Energy carrier tariff

• “meter” – Metering point

• “bill” – Bill with the corresponding entries contained within

• “reading” – Metering point readings

Processing order for deletion will be bottom-up, and the order of inserts will always be top-down.

Structure of the listed objects will be specified in the following chapters.

3.6.1.1 Inserting vs. Deleting (or Unregistering)

Objects listed for insertion must contain all the required fields, while objects listed for deletion or unregistering

should contain only the bare minimum of fields required for identification (i.e. only the fields that make part of a

primary key).

3.6.2 Batch Response Structure

A response contains two sections, containing a batch with the processed, and a batch with the failed objects:

• “succeeded” – with a batch containing operations and objects that were successfully processed (deleted,

unregistered or inserted). Each succeeded object will be referenced just by its ID and a “ts” containing the

processing timestamp.

• “failed” – with a batch containing objects that failed. Objects in this batch will contain all the original

fields, together with the corresponding error description, plus a “ts” containing the processing

timestamp.

After receiving a response, a caller should always check the “failed” section for entries that might have failed,

correct the errors (if any), and retry sending of those entries once the errors are resolved. Exception to this rule is

sending Bills, where you have to rectify and recreate the whole bill, since in case of an error in single BillData

entry, the whole bill will be rejected, but only the field that caused the error will be returned.

The response also contains serviceURL, dataSupplierId and dataSupplierLogin fields, as described in 2.4.1.2 Echo

Response.

3.6.3 Batch-Contained Objects Structure

The following chapters describe objects contained in a batch.

a) After a successful processing, the service will return a collection of objects, reduced just to their Primary

Key fields, while the others will be omitted

b) In case of a failure, the entire object will be returned, together with the corresponding error description.

In both cases an additional “ts” field will be added, containing the processing timestamp.

NOTE:


12

• When inserting an object, all the mandatory fields must be present.

• When deleting an object, or unregistering a Meter, only the Primary Key field(s) must be present.

3.6.3.1 Sending of remote bills

3.6.3.1.1 Object “vendor”

Vendor Properties


id Text Primary Key, Mandatory

Data Supplier’s Vendor ID

name Text Mandatory Vendor name

ignoreExisting Boolean Optional (“true” or “false”, omitted -> “false”)

If true, no exception will be thrown when inserting an entry with the same ID, so the new entry will be ignored, and the existing entry WILL NOT BE UPDATED! An existing entry can not be changed in any way.

Vendor Example (Fragment)

JSON XML { "id" : "AP", "name" : "Austin Powers Ltd." }

<vendor id="AP" name="Austin Powers Ltd."/>

3.6.3.1.2 Object “energyCarrier”

Energy Carrier Properties



Data Supplier’s Energy Carrier ID

name Text Mandatory Energy Carrier name



Energy Carrier Example (Fragment)

JSON XML { "id" : "MOJO", "name" : "Mojo Energy" }

<energyCarrier id="MOJO" name="Mojo Energy"/>


13

3.6.3.1.3 Object “energyCarrierField”

Energy Carrier Field Properties



Data Supplier’s Bill Field ID

energyCarrierId Text Primary Key, Mandatory

Data Supplier’s Energy Carrier ID

name Text Mandatory Bill item name with unit of measure

consumption Boolean Optional (omitted -> false)

Allowed values are “true” (for bill items representing consumption) and “false”.



Energy Carrier Field Example (Fragment)

JSON XML { "id" : "HOT", "energyCarrierId" : "MOJO", "name" : "Hot Mojo" }

<energyCarrierField id="HOT" energyCarrierId="MOJO" name="Hot Mojo"/>

3.6.3.1.4 Object “tariff”

Tariff Properties



Data Supplier’s Tariff ID

energyCarrierId Text Mandatory Data Supplier’s Energy Carrier ID

vendorId Text Mandatory Data Supplier’s Vendor ID

name Text Mandatory Tariff name



Tariff Example (Fragment)

JSON XML { "id":"MOJO_MAIN", "energyCarrierId":"MOJO", "vendorId":"AP", "name":"Main Mojo Tariffa" }

<tariff id="MOJO_MAIN" energyCarrierId="MOJO" vendorId="AP" name="Main Mojo Tariff"/>


14

3.6.3.1.5 Object “meter”

Meter Properties


id Text Primary Key, Mandatory Data Supplier’s Metering point ID

serialNumber Text Mandatory, Updateable Meter serial number

description Text Optional, Updateable Meter description

address Complex Optional, Updateable Meter address

buildingName Text Optional, Updateable Facility name

ownerName Text Optional, Updateable Owner name

ownerExternalId Text Optional, Updateable Owner’s Tax ID (OIB)


unregisterDate Date YYYY-MM-DD Only for unregistering

Date since DataSupplier is no longer obliged to send bills for a metering point because the contract with the user of this metering point expired.

unregisterComment Text Only for unregistering Comment (e.g. number of contract, or name of new vendor)

When registering a meter with ID that is already registered, the system will update data and will NOT raise a

primary key exception. It will update the following fields: serialNumber, description, address (address, city, zip),

buildingName, ownerName, and ownerExternalId. Field energyCarrierId is not updateable. Fields unregisterDate

and unregisterComment are ignored when registering a meter!

Unregistering a meter serves to mark that a DataSupplier is no longer obliged to send bills for a metering point,

because a contract with a user of that metering point expired.

Note: This does not prevent DataSupplier from sending further bills for any reason, but it serves as an information

to users of EMIS system that a vendor has changed.

To unregister a meter see chapter 3.6.1 (Batch Request Structure), and send only fields id, unregisterDate and

unregisterComment.

Address Properties


address Text Optional Street name with house number

city Text Optional City name

zip Text Optional Zip code

Meter Example (Fragment)

JSON XML { "id" : "METER1", "serialNumber" : "M-1-SER", "description" : "Mojo Meter One ", "address" : { "address" : "Elm Street 1", "city" : "London", "zip" : "WC2N" }, "buildingName" : "Headquarters", "ownerName" : "Dr. Evil", "energyCarrierId" : "MOJO" }

<meter id="METER1" serialNumber="M-1-SER" description="Mojo Meter One" buildingName="Headquarters" ownerName="Dr. Evil" energyCarrierId="MOJO> <address address="Elm Street 1" city="London" zip="WC2N"/> </meter>


15

3.6.3.1.6 Object “bill”

Bill with its contained BillData entries are processed in a single transaction, meaning that if a single BillData entry

is invalid, the entire Bill will be rejected, and all the previous BillData entries (if any) contained in that Bill will be

ignored. In that case, the service response will contain in its “failed” section the corresponding “bill” object with

all its original attributes, containing only the first BillData element that failed, together with the error description.

Bill Properties



Data Supplier’s Bill ID

serialNumber Text Mandatory Serial number printed on the bill

total Decimal Optional Total amount of bill with VAT. Used for accuracy check of all entered items.

month Number Optional Month for which the bill is issued

year Number Optional Year for which the bill is issued

billData List of Complex “BillData”

Optional Bill entries

BillData Properties


energyCarrierId Text UK* Data Supplier’s Energy Carrier ID

meterId Text UK* Meter ID

vendorId Text UK* Vendor ID

tariffID Text UK* Tariff/group of bills ID

dateFrom Date UK*, Mandatory Date from

dateTo Date UK*, Mandatory Date until

energyCarrierFieldId Text UK*, Mandatory Energy Carrier Field ID

quantity Decimal Mandatory Amount

unitCost Decimal Mandatory Unit price

taxPercentage Decimal Mandatory Tax rate (%)

* Fields marked with UK must be unique. It means that on the same bill one item can appear only once on a metering point from the same

vendor in a specific from-to period, for a specific tariff. Null (empty) fields are also included in uniqueness check. This limitations has been

added due to the fact to prevent double sending of the same item of the bill and the aim is to make it flexible enough to function in

different scenarios. If meterId is not null, then also vendorId, tariffId and energyCarrierId must be not null.

If bill has fields which do not have quantity (like discount, interest, various fees) you must have quantity set to 1.

It is possible that you need to send bills which contain consumption of more than one meter and have fields

which belong to the whole bill and not to specific meter (like discount, interest, etc.). In that case you send this

billItems without attributes energyCarrierId, meterId, vendorId, tariffId. See example document “Sending of

remote bills – example.pdf”.

Bill Example (Fragment)

JSON XML { "id" : "INT-0002", "serialNumber" : "AP-2016-0002", "total" : 1234.56, "month" : 1, "year" : 2016, "billData" : [{

<bill id="INT-0002" serialNumber="AP-2016-0002" total="1234.56" month="1" year="2016" > <billData energyCarrierId="MOJO" meterId="METER1" vendorId="AP" tariffId="MOJO_MAIN" dateFrom="2016-01-01" dateTo="2016-02-01" vendorId="AP" energyCarrierFieldId="HOT" quantity="10.0" unitCost="123.0" taxPercentage="25.0"/>


16

"energyCarrierId" : "MOJO", "meterId" : "METER1", "vendorId" : "AP", "tariffId" : "MOJO_MAIN", "dateFrom" : "2016-01-01", "dateTo" : "2016-02-01", "energyCarrierFieldId" : "HOT", "quantity" : 10.0, "unitCost" : 123.0, "taxPercentage" : 25.0, }, { "energyCarrierId" : "MOJO", "meterId" : "METER2", "vendorId" : "AP", "tariffId" : "MOJO_MAIN", "dateFrom" : "2016-01-01", "dateTo" : "2016-01-02", "energyCarrierFieldId" : "COOL", "quantity" : 100.0, "unitCost" : 95.0, "taxPercentage" : 25.0, } ] }

<billData energyCarrierId="MOJO" meterId="METER2" vendorId="AP" tariffId="MOJO_MAIN" dateFrom="2016-01-01" dateTo="2016-02-01" vendorId="AP" energyCarrierFieldId="COOL" quantity="100.0" unitCost="95.0" taxPercentage="25.0"/> </bill>

Bill Example – Successful (complete)

JSON Request JSON Response POST http://<EMIS-service-url>/batch/json/send Request Headers: Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: yoHi5qZsqfPM0pkmKiudSIIsXTVFaYT/cdsZ/ZK0S2I= Content-Length: 886 Host: <EMIS-service-url> { "insert" : { "bills" : [{ "id" : "INT-0001", "serialNumber" : "AP-2015-0001", "total" : 1234.56, "month" : 1, "year" : 2015, "billData" : [{ "energyCarrierId" : "MOJO", "meterId" : "METER1", "vendorId" : "AP", "tariffId" : "MOJO_MAIN", "dateFrom" : "2015-01-01", "dateTo" : "2015-02-01", "energyCarrierFieldId" : "HOT", "quantity" : 10.0, "unitCost" : 123.0, "taxPercentage" : 25.0 }, { "energyCarrierId" : "MOJO", "meterId" : "METER2", "vendorId" : "AP", "tariffId" : "MOJO_MAIN", "dateFrom" : "2015-01-01", "dateTo" : "2015-01-01", "energyCarrierFieldId" : "COOL", "quantity" : 100.0, "unitCost" : 95.0, "taxPercentage" : 25.0 } ] } ] } }

{ "status" : 200, "statusDesc" : "OK", "ts" : "2016-09-14T10:34:13.296", "serviceURL" : "http://<EMIS-service-url>/batch/json/send ", "succeeded" : { "ts" : "2016-09-14T10:34:13.308", "insert" : { "bills" : [{ "id" : "INT-0001", "ts" : "2016-09-14T10:34:13.308" } ] } } "dataSupplierId" : "test" "dataSupplierLogin" : "test" }

XML Request XML Response POST http://<EMIS-service-url>/batch/xml/send Request Headers: Content-Type: application/xml

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2016-09-14T12:18:10.358" serviceURL="http://<EMIS-service-url>/batch/xml/send " dataSupplierId="test" dataSupplierLogin="test"> <succeeded ts="2016-09-14T12:18:10.373">


17

X-Ekonerg-Login: test X-Ekonerg-MAC: yoHi5qZsqfPM0pkmKiudSIIsXTVFaYT/cdsZ/ZK0S2I= Content-Length: 736 Host: <EMIS-service-url> <?xml version='1.0' encoding='UTF-8'?> <batch xmlns="http://www.ekonerg.hr/em/bills" ts="2016-09-14T12:15:20.224"> <insert> <bill id="INT-0001" serialNumber="AP-2015-0001" year="2015" month="1" total="1234.56"> <billData energyCarrierId="MOJO" meterId="METER1" vendorId="AP" tariffId="MOJO_MAIN" dateFrom="2015-01-01" dateTo="2015-02-01" energyCarrierFieldId="HOT" quantity="10.0" unitCost="123.0" taxPercentage="25.0"/> <billData energyCarrierId="MOJO" meterId="METER2" vendorId="AP" tariffId="MOJO_MAIN" dateFrom="2015-01-01" dateTo="2015-02-01" energyCarrierFieldId="COOL" quantity="100.0" unitCost="95.0" taxPercentage="25.0"/> </bill> </insert> </batch>

<insert> <bill id="INT-0001" ts="2016-09-14T12:18:10.373"/> </insert> </succeeded> </response>


18

In the following example, the second entry of the BillData list contains an unknown meterId. The service returns a

“failed” list containing a partial copy of the original batch only one BillData entry – the one that was invalid. The

“err” and “errDesc” fields contain details about the error, and are contained in both BillData entry and the Bill

object. As a result of the operation, the entire Bill is rejected.

Bill Example – Failed (complete)

JSON Request JSON Response POST http://<EMIS-service-url>/batch/json/send Request Headers: Connection: keep-alive Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: yoHi5qZsqfPM0pkmKiudSIIsXTVFaYT/cdsZ/ZK0S2I= Content-Length: 887 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) { "insert" : { "bills" : [{ "id" : "INT-0001", "serialNumber" : "AP-2015-0001", "total" : 1234.56, "month" : 1, "year" : 2015, "billData" : [{ "energyCarrierId" : "MOJO", "meterId" : "METER1", "vendorId" : "AP", "tariffId" : "MOJO_MAIN", "dateFrom" : "2015-01-01", "dateTo" : "2015-02-01", "energyCarrierFieldId" : "HOT", "quantity" : 10.0, "unitCost" : 123.0, "taxPercentage" : 25.0 }, { "energyCarrierId" : "MOJO", "meterId" : "METER2x", "vendorId" : "AP", "tariffId" : "MOJO_MAIN", "dateFrom" : "2015-01-01", "dateTo" : "2015-02-01", "energyCarrierFieldId" : "COOL", "quantity" : 100.0, "unitCost" : 95.0, "taxPercentage" : 25.0 } ] } ] } }

{ "status" : 200, "statusDesc" : "OK", "ts" : "2016-09-14T12:21:08.403", "failed" : { "ts" : "2016-09-14T12:21:08.420", "serviceURL" : "http://<EMIS-service-url>/batch/json/send ", "insert" : { "bills" : [{ "id" : "INT-0001", "serialNumber" : "AP-2015-0001", "year" : 2015, "month" : 1, "billData" : [{ "ts" : "2016-09-14T12:21:08.419", "err" : "ForeignKeyException", "errDesc" : "PreparedStatementCallback; SQL [call REMOTEBILLS_BACK.BILL_SEND_FIELD(?,?,?,?,?,?,?,?,?,?,?,?,?)]; ORA-02291: integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found\nORA-06512: at \"EMIS.REMOTEBILLS_BACK\", line 298\n; nested exception is java.sql.SQLIntegrityConstraintViolationException: ORA-02291: integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found\nORA-06512: at \"EMIS.REMOTEBILLS_BACK\", line 298\n", "energyCarrierId" : "MOJO", "meterId" : "METER2x", "vendorId" : "AP", "tariffId" : "MOJO_MAIN", "dateFrom" : "2015-01-01", "dateTo" : "2015-02-01", "energyCarrierFieldId" : "COOL", "quantity" : 100.0, "unitCost" : 95.0, "taxPercentage" : 25.0 } ], "err" : "ForeignKeyException", "errDesc" : "PreparedStatementCallback; SQL [call REMOTEBILLS_BACK.BILL_SEND_FIELD(?,?,?,?,?,?,?,?,?,?,?,?,?)]; ORA-02291: integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found\nORA-06512: at \"EMIS.REMOTEBILLS_BACK\", line 298\n; nested exception is java.sql.SQLIntegrityConstraintViolationException: ORA-02291: integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found\nORA-06512: at \"EMIS.REMOTEBILLS_BACK\", line 298\n", "total" : 1234.56, "ts" : "2016-09-14T12:21:08.420" } ] } } "dataSupplierId" : "test" "dataSupplierLogin" : "test" }

XML Request XML Response POST http://<EMIS-service-url>/batch/xml/send Request Headers: Connection: keep-alive Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: yoHi5qZsqfPM0pkmKiudSIIsXTVFaYT/cdsZ/ZK0S2I= Content-Length: 737 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) <?xml version='1.0' encoding='UTF-8'?> <batch xmlns="http://www.ekonerg.hr/em/bills" ts="2016-09-14T12:15:20.224"> <insert> <bill id="INT-0001" serialNumber="AP-2015-0001" year="2015" month="1" total="1234.56">

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2016-09-14T12:28:55.396" serviceURL="http://<EMIS-service-url>/batch/xml/send " dataSupplierId="test" dataSupplierLogin="test"> <failed ts="2016-09-14T12:28:55.403"> <insert> <bill id="INT-0001" serialNumber="AP-2015-0001" year="2015" month="1" err="ForeignKeyException" errDesc="PreparedStatementCallback; SQL [call REMOTEBILLS_BACK.BILL_SEND_FIELD(?,?,?,?,?,?,?,?,?,?,?,?,?)]; ORA-02291: integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found
ORA-06512: at "EMIS.REMOTEBILLS_BACK", line 298
; nested exception is java.sql.SQLIntegrityConstraintViolationException: ORA-02291: integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found
" total="1234.56" ts="2016-09-14T12:28:55.403"> <billData ts="2016-09-14T12:28:55.402" err="ForeignKeyException" errDesc="PreparedStatementCallback; SQL [call REMOTEBILLS_BACK.BILL_SEND_FIELD(?,?,?,?,?,?,?,?,?,?,?,?,?)]; ORA-02291: integrity


19

<billData energyCarrierId="MOJO" meterId="METER1" vendorId="AP" tariffId="MOJO_MAIN" dateFrom="2015-01-01" dateTo="2015-02-01" energyCarrierFieldId="HOT" quantity="10.0" unitCost="123.0" taxPercentage="25.0"/> <billData energyCarrierId="MOJO" meterId="METER2x" vendorId="AP" tariffId="MOJO_MAIN" dateFrom="2015-01-01" dateTo="2015-02-01" energyCarrierFieldId="COOL" quantity="100.0" unitCost="95.0" taxPercentage="25.0"/> </bill> </insert> </batch>

constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found
; nested exception is java.sql.SQLIntegrityConstraintViolationException: ORA-02291: integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found
" energyCarrierId="MOJO" meterId="METER2x" vendorId="AP" tariffId="MOJO_MAIN" dateFrom="2015-01-01" dateTo="2015-02-01" energyCarrierFieldId="COOL" quantity="100.0" unitCost="95.0" taxPercentage="25.0"/> </bill> </insert> </failed> </response>

3.6.3.2 Sending of Advanced Remote Readings

3.6.3.2.1 Object “energyCarrier”

See chapter 3.6.3.1.2!

If you are already sending remote bills, you do not have to register these again, this is the same data.

3.6.3.2.2 Object “meter”

See chapter 3.6.3.1.5!

If you are already sending remote bills, you do not have to register these again, this is the same data.

3.6.3.2.3 Object “energyCarrierCounter”

Each energy carrier has one or more values that can be measured by a meter. Meters do not need to measure all

of them, but all possible counters need to be registered for an energy carrier.

Energy Carrier Counter Properties


id Text Primary Key, Mandatory, Strictrly alphanumeric (A-Z,a-z,0-9)

Data Supplier’s Energy Counter ID (If you have more then one energy carrier note that ID must be unique across all energy carriers you have) It is suggested to make this field as short as possible because you will refer to it in each reading.


name Text Name of energy carrer counter

uom Text Unit of measure



Energy Carrier Counter Example (Fragment)

JSON XML { "id": "E1", "energyCarrierId" = "EE", "name": "Electricity - active daily consumption", "uom" = "kWh" }

<energyCarrierCounter id="E1" energyCarrierId="EE" name="Electricity - active daily consumption" uom="kWh" />


20

3.6.3.2.4 Objects “meterDevice” and “meterDeviceCounter”

Metering device is a physical device installed on metering point. Metering device counter is a counter on a

metering device. They can be registered either separately, or together – where counters are specified as sub-

objects of meter device (that is why they are documented in the same chapter).

Type of counter on metering device must first be registered in a list of energy carrier counters.

Besides insert and delete operations you can also unregister a meter device, which should be done when a device

is removed from a metering point, and replaced with another one. If you are sending historical data you can send

dateRemoved field in insert operation, and you do not have to call unregister operation later. There is no

prevention of sending historical readings for unregistered devices either.

Meter Device Properties


id Text Primary Key, Mandatory,

Data Supplier’s Meter Device ID (must be unique across all meter devices)

meterId Text Mandatory Data Supplier’s meter ID

serialNumber Text Serial number of metering device

dateInstalled DateTime Date when this device was installed on metering location

dateRemoved DateTime When inserting and unregistering

Date when this device was removed from metering location

meterDeviceCounter meterDeviceCounter Array, Optional Optionally a list of metering devices if you want to include them in meterDevice object



Meter Device Counter Properties


meterDeviceId Text Primary Key, Mandatory (can be omitted if specified under meterDevice object)

Data Supplier’s Meter Device ID

energyCounterId Text Primary Key, Mandatory Data Supplier’s Energy Counter ID

correctionFactor Number Defaults to 1 Correction factor of counter on installed device. All readings are multiplied by this factor in further calculations.



A Meter Device and a Meter Device Counter can be registered either separately, or a Meter Device Counter can

be registered within a Meter Device object. Both concepts are equally valid, and you can even combine them at

your convenience. It is only important not to register a Meter Device Counter before its Meter Device.

Meter Device and Meter Device Counter Examples (Fragment)

(Both examples give the same result)

JSON XML { <meterDevice


21

"meterDevice": [{ "id": "EE790", "meterId": "2", "serialNumber": "782364", "dateInstalled": "2012-05-09T17:45:00", "dateRemoved": "2018-05-17T18:05:00" } ], "meterDeviceCounter": [{ "meterDeviceId": "EE790", "energyCounterId": "E1", "correctionFactor": "1.004" }, { "meterDeviceId": "EE790", "energyCounterId": "E2", "correctionFactor": "1.004" } ] }

id="EE790" meterId="2" serialNumber="782364" dateInstalled="2012-05-09T17:45:00" dateRemoved="2018-05-17T18:05:00" /> <meterDeviceCounter meterDeviceId="EE790" energyCounterId="E1" correctionFactor="1.004" /> <meterDeviceCounter meterDeviceId="EE790" energyCounterId="E2" correctionFactor="1.004" />

JSON XML

{ "meterDevice": [{ "id": "EE790", "meterId": "2", "serialNumber": "782364", "dateInstalled": "2012-05-09T17:45:00", "dateRemoved": "2018-05-17T18:05:00", "meterDeviceCounter": [{ "energyCounterId": "E1", "correctionFactor": "1.004" }, { "energyCounterId": "E2", "correctionFactor": "1.004" } ] } ] }

<meterDevice id="EE790" meterId="2" serialNumber="782364" dateInstalled="2012-05-09T17:45:00" dateRemoved="2018-05-17T18:05:00"> <meterDeviceCounter energyCounterId="E1" correctionFactor="1.004" /> <meterDeviceCounter energyCounterId="E2" correctionFactor="1.004" /> </meterDevice>

3.6.3.2.5 Object “ar” (Advanced Reading)

Generally, there will be many advanced reading entries, so the tag and the attribute names have been shortened

in order to cut down the traffic. For the same reason you should also consider sending non-indented files and

remove excessive tabs and spaces.

Note that readings are linked to Data Supplier’s metering device ID (not metering point ID).

Advanced Reading “ar” Properties


md Text Primary Key, Mandatory,

Data Supplier’s Meter Device ID

ec Text Primary Key, Mandatory Data Supplier’s Energy Counter ID

t DateTime Primary Key, Mandatory Date and time of reading

v Number Value

Advanced Reading Example (Fragment)

JSON XML { "md": " D342397", "ec" = "1", "t": "2019-04-07T13:25:00", "v" = 154 }

<ar md="D342397" ec="1" t="2019-04-07T13:25:00" v="154"/>


22

3.6.3.3 Sending of Basic Remote Readings

Readings are referenced to internal EMIS identifier of a related meter – not the data supplier meter identifier.

These identifier values will be specified in a contract with each data supplier, but assigned meter IDs can also be

retrieved as described in chapter 5. DataSupplier Web Interface, and chapter 3.7. Query Methods

Various methods that you can use to query data from server.

Basic Remote Readings.

When sending readings all monitored counter values have to be sent.

Important: When sending an already existing reading, the system will throw an exception. It is expected from

data supplier to track which data has already been sent. To change the previously sent readings, you must first

delete the existing readings and then send the new ones.

3.6.3.3.1 Object “reading”

The following sections describes format of remote readings.

Reading Properties


meterId Text UK, Mandatory, Foreign key

EMIS Meter ID

date DateTime UK, Mandatory Reading date

dateTo DateTime Optional Used only to delete a time-range of readings. You can delete all readings of a given meterId by specifying start and end date (date and dateTo fields). In that case, you must specify only:

• meterId – meter whose readings are to be deleted

• date – readings start date-time

• dateTo – readings end date-time (inclusive!)

c1 Decimal Optional Counter 1 value





tempIn Decimal Optional Inside temperature in °C (Please contact administrators)

tempOut Decimal Optional Outside temperature in °C (Please contact administrators)

people Number Optional Number of occupants (Please contact administrators)

internalId Text UK, Optional Internal Data Supplier’s reading ID

id Text Return value Record ID in EMIS database

Striked attributes are no longer supported, and will be abandoned. You will use sensors to send this data. Please

contact administrators.

NOTE: If a request contains the “internalId” value, then “meterId” and “date” will be removed from the response

after a successful operation. If the “internalId” is omitted, then these two values will be kept in the confirmation

response.

Reading Example (successful)

JSON Request JSON Response POST http://<EMIS-service-url>/batch/json/send Request Headers: Connection: keep-alive Content-Type: application/json X-Ekonerg-Login: ARSEN X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8=

{ "status" : 200, "statusDesc" : "OK", "ts" : "2016-09-14T14:42:00.601", "serviceURL" : "http://<EMIS-service-url>/batch/json/send ", "succeeded" : { "ts" : "2016-09-14T14:42:00.675",


23

Content-Length: 260 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) { "insert" : { "readings" : [{ "meterId" : "2186653", "date" : "2016-01-15T02:02:00", "c1" : "209002", "internalId" : "19625" }, { "meterId" : "2186653", "date" : "2016-01-15T02:03:00", "c1" : "209003" } ] } }

"insert" : { "readings" : [{ "ts" : "2016-09-14T14:42:00.649", "id" : "200271268", "internalId" : "19625" }, { "ts" : "2016-09-14T14:42:00.674", "id" : "200271269", "meterId" : "2186653", "date" : "2016-01-15T02:03:00" } ] } } "dataSupplierId" : "test" "dataSupplierLogin" : "test" }

XML Request XML Response POST http://<EMIS-service-url>/batch/xml/send Request Headers: Connection: keep-alive Content-Type: application/xml X-Ekonerg-Login: ARSEN X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= Content-Length: 315 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) <?xml version='1.0' encoding='UTF-8'?> <batch xmlns="http://www.ekonerg.hr/em/bills" ts="2016-09-14T14:42:00.558"> <insert> <reading meterId="2186653" date="2016-01-15T02:02:00" c1="209002.0" internalId="19625"/> <reading meterId="2186653" date="2016-01-15T02:03:00" c1="209003.0"/> </insert> </batch>

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2016-09-14T14:42:00.601" serviceURL="http://<EMIS-service-url>/batch/xml/send " dataSupplierId="test" dataSupplierLogin="test"> <succeeded ts="2016-09-14T14:42:00.675"> <insert> <reading ts="2016-09-14T14:42:00.649" id="200271268" internalId="19625"/> <reading ts="2016-09-14T14:42:00.674" id="200271269" meterId="2186653" date="2016-01-15T02:03:00"/> </insert> </succeeded> </response>

Reading Example (partially successful)

JSON Request JSON Response POST http://<EMIS-service-url>/batch/json/send Request Headers: Connection: keep-alive Content-Type: application/json X-Ekonerg-Login: ARSEN X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= Content-Length: 260 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) { "insert" : { "readings" : [{ "meterId" : "2186653", "date" : "2016-01-15T02:04:00", "c1" : "209004", "internalId" : "19631" }, { "meterId" : "2186653", "date" : "2016-01-15T02:03:00", "c1" : "209005" } ] } }

{ "status" : 200, "statusDesc" : "OK", "ts" : "2016-09-14T14:54:23.123", "serviceURL" : "http://<EMIS-service-url>/batch/json/send ", "succeeded" : { "ts" : "2016-09-14T14:54:23.285", "insert" : { "readings" : [{ "ts" : "2016-09-14T14:54:23.165", "id" : "200271270", "internalId" : "19631" } ] } }, "failed" : { "ts" : "2016-09-14T14:54:23.285", "insert" : { "readings" : [{ "ts" : "2016-09-14T14:54:23.283", "err" : "BusinessException", "errDesc" : "ERR-20243:ORA-20243: READING_LARGER_THAN_NEXT - Reading on one of the counters is larger then one next reading. This is not allowed for cummulative meters. Next counters: c1:209004/c2:/c3:/c4:/c5: Param1:2186653\nORA-06512: at \"EMIS.REMOTE\", line 60\nORA-06512: at \"EMIS.REMOTE\", line 392\nORA-06512: at line 1\n", "meterId" : "2186653", "date" : "2016-01-15T02:03:00", "c1" : 209005.0 } ] }


24

} "dataSupplierId" : "test" "dataSupplierLogin" : "test" }

XML Request XML Response POST http://<EMIS-service-url>/batch/xml/send Request Headers: Connection: keep-alive Content-Type: application/xml X-Ekonerg-Login: ARSEN X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= Content-Length: 315 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) <?xml version='1.0' encoding='UTF-8'?> <batch xmlns="http://www.ekonerg.hr/em/bills" ts="2016-09-14T14:54:23.113"> <insert> <reading meterId="2186653" date="2016-01-15T02:04:00" c1="209004.0" internalId="19631"/> <reading meterId="2186653" date="2016-01-15T02:03:00" c1="209005.0"/> </insert> </batch>

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2016-09-14T14:54:23.123" serviceURL="http://<EMIS-service-url>/batch/xml/send " dataSupplierId="test" dataSupplierLogin="test"> <succeeded ts="2016-09-14T14:54:23.285"> <insert> <reading ts="2016-09-14T14:54:23.165" id="200271270" internalId="19631"/> </insert> </succeeded> <failed ts="2016-09-14T14:54:23.285"> <insert> <reading ts="2016-09-14T14:54:23.283" err="BusinessException" errDesc="ERR-20243:ORA-20243: READING_LARGER_THAN_NEXT - Reading on one of the counters is larger then one next reading. This is not allowed for cummulative meters. Next counters: c1:209004/c2:/c3:/c4:/c5: Param1:2186653
ORA-06512: at "EMIS.REMOTE", line 60
ORA-06512: at "EMIS.REMOTE", line 392
ORA-06512: at line 1
" meterId="2186653" date="2016-01-15T02:03:00" c1="209005.0"/> </insert> </failed> </response>

3.6.3.3.2 Mass deleting of readings

All the readings of a specified meterId in a given period can be deleted by sending a batch with one or more

“reading” objects in a “delete” section.

Each “reading” entry must contain the following properties:

Reading Properties (for deleting)


meterId Text UK, Mandatory, Foreign key

EMIS Meter ID

date DateTime UK, Mandatory Reading date

dateTo DateTime Optional Used only to delete a time-range of readings. You can delete all readings of a given meterId by specifying start and end date (date and dateTo fields). In that case, you must specify only:

• meterId – meter whose readings are to be deleted

• date – readings start date-time

• dateTo – readings end date-time (inclusive!)

For each reading “range” entry, the service returns a number of successfully deleted readings.

Reading Interval Delete Example (successful)

JSON Request JSON Response POST http://<EMIS-service-url>/batch/json/send Request Headers: Connection: keep-alive Content-Type: application/json X-Ekonerg-Login: ARSEN X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= Content-Length: 260 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) { "delete" : { "readings" : [{ "meterId" : "2186653", "date" : "2016-01-15T02:02:00", "dateTo" : "2016-01-29T23:59:59",

{ "status" : 200, "statusDesc" : "OK", "ts" : "2016-09-14T14:42:00.601", "serviceURL" : "http://<EMIS-service-url>/batch/json/send ", "succeeded": { "ts": "2016-09-14T14:42:00.655", "delete": { "readings": [{ "ts": "2016-09-14T14:42:00.652", "processedEntries": 6, "meterId": "2186653", "date": "2016-01-15T02:02:00", "dateTo": "2016-01-29T23:59:59" } ], "count": 1


25

} ] } }

} }, "dataSupplierId" : "test" "dataSupplierLogin" : "test" }

XML Request XML Response POST http://<EMIS-service-url>/batch/xml/send Request Headers: Connection: keep-alive Content-Type: application/xml X-Ekonerg-Login: ARSEN X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= Content-Length: 315 Host: <EMIS-service-url> User-Agent: Apache-HttpClient/4.2.6 (java 1.5) <?xml version='1.0' encoding='UTF-8'?> <batch xmlns="http://www.ekonerg.hr/em/bills" ts="2016-09-14T14:42:00.558"> <delete> <reading meterId="2186653" date="2016-01-15T02:02:00" dateTo="2016-01-29T23:59:59"/> </delete> </batch>

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2016-09-14T14:42:00.601" serviceURL="http://<EMIS-service-url>/batch/xml/send " dataSupplierId="test" dataSupplierLogin="test"> <succeeded ts="2016-09-14T14:42:00.655"> <delete> <reading ts="2016-09-14T14:42:00.652" processedEntries="6" meterId="2186653" date="2016-01-15T00:00:00" dateTo="2016-01-15T23:59:59"/> </delete> </succeeded> </response>

3.7 Query Methods Various methods that you can use to query data from server.

3.7.1 Basic Remote Readings – Meters and Readings

The following methods are used for querying granted Meters and Readings that a data supplier has sent.

They work only for basic remote readings.

3.7.1.1 Meters Query

This method is used for getting a list of all the meters that a data supplier is granted to send readings to. All

meters include “Counters” object, which contains a list of counters that are enabled on a meter.

It is a REST GET method with no parameters. It comes in JSON and XML flavors.

3.7.1.1.1 Meters Query Request

Meters Request Properties <EMIS-service-url>/query/[xml|json]/meters


- - - No parameters are required, except for the MAC authorization in HTTP header.

3.7.1.1.2 Meters Query Response

Meters Response Properties






Response timestamp





26

meters List List of objects List of Meter objects

meter (zero or more entries)

meterId Long Primary key EMIS meter ID

meterSerialNumber Text Meter serial number

meterShortDescription Text Short description of the meter

meterDescription Text Additonal comment

objectName Text Object name

emisCode Text EMIS code of the object

energent Text Energy carrier name

energentId Text Foreign key – Energent Energy carrier ID

counters Array See “Counters” object List of counters on meter

Counters Object


counter Number Counter number

name Text Counter name and UOM

3.7.1.1.3 Examples

Meters Request Example

JSON Request JSON Response GET http://localhost:8080/em-remote-service/query/json/meters Request Headers: Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Host: localhost:8080

{ "status": 200, "statusDesc": "OK", "ts": "2017-11-23T14:29:55.687", "meters": [{ "meterId": 1122976, "meterSerialNumber": "NN1122334455", "meterShortDescription": null, "meterDescription": null, "objectName": "Gradski kotar Sirobuja", "isgeCode": "HR-21000-0122-1", "energent": "Električna energija", "energentId": "Electricity", "counters": [{ "counter": 1, "name": "RVT [kWh]" } ] }, { "meterId": 1122982, "meterSerialNumber": "NNxxxxxx", "meterShortDescription": null, "meterDescription": null, "objectName": "Osnovna Škola Miroslava krleže Čepin", "isgeCode": "HR-31431-0007-1", "energent": "Električna energija", "energentId": "Electricity", "counters": [{ "counter": 1, "name": "RVT [kWh]" }, { "counter": 2, "name": "RNT [kWh]" }, ] } ], "serviceURL": "http://localhost:8080/em-remote-service/query/json/meters", "dataSupplierId": "TEST", "dataSupplierLogin": "test" }


27

XML Request XML Response GET http://localhost:8080/em-remote-service/query/xml/meters Request Headers: Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: FZ8NABKpId04g8p07lX3v/edG3+YIXiyvsxMYVSSeoY= Host: <EMIS-service-url>

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2017-11-23T13:25:03.012" serviceURL="http://localhost:8080/em-remote-service/query/xml/meters" dataSupplierId="TEST" dataSupplierLogin="test"> <meters> <meter> <meterId>1122976</meterId> <meterSerialNumber>NN1122334455</meterSerialNumber> <meterShortDescription/> <meterDescription/> <objectName>Gradski kotar Sirobuja</objectName> <isgeCode>HR-21000-0122-1</isgeCode> <energent>Električna energija</energent> <energentId>Electricity</energentId> <counters> <counter> <counter>1</counter> <name>RVT [kWh]</name> </counter> </counters> </meter> <meter> <meterId>1122982</meterId> <meterSerialNumber>NNxxxxxx</meterSerialNumber> <meterShortDescription/> <meterDescription/> <objectName>Osnovna Škola Miroslava krleže Čepin</objectName> <isgeCode>HR-31431-0007-1</isgeCode> <energent>Električna energija</energent> <energentId>Electricity</energentId> <counters> <counter> <counter>1</counter> <name>RVT [kWh]</name> </counter> <counter> <counter>2</counter> <name>RNT [kWh]</name> </counter> </counters> </meter> </meters> </response>

3.7.1.2 Readings Query

This method is used for getting a list of all the readings that a data supplier previously sent for a specific meter

and a given year/month.

It is a REST GET method with no parameters. It comes in JSON and XML flavors.

3.7.1.2.1 Readings Query Request

Readings Request Properties <EMIS-service-url>/query/[xml|json]/readings/<meterId>/<year>/<month>


meterId Number - Meter ID

year Number - Year

month Number - Month

3.7.1.2.2 Readings Query Response

Readings Response Properties






Response timestamp



28



readings List List of Objects List of Reading objects

reading (zero or more entries) – as described in chapter 3.6.3.3.1 Object “reading”

3.7.1.2.3 Examples

Readings Request Example

JSON Request JSON Response GET http://localhost:8080/em-remote-service/query/json/readings/1123580/2015/1 Request Headers: Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Host: localhost:8080

{ "status": 200, "statusDesc": "OK", "ts": "2017-11-23T15:47:55.906", "readings": [{ "serviceURL": null, "id": "23", "meterId": "1123580", "date": "2015-01-18T00:00:00", "c1": 511.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalId": "17" }, { "serviceURL": null, "id": "19", "meterId": "1123580", "date": "2015-01-17T00:00:00", "c1": 510.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalId": "17" }, { "serviceURL": null, "id": "22", "meterId": "1123580", "date": "2015-01-16T00:00:00", "c1": 509.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalId": "17" }, { "serviceURL": null, "id": "20", "meterId": "1123580", "date": "2015-01-15T00:00:00", "c1": 508.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalId": "17" }, { "serviceURL": null, "id": "21", "meterId": "1123580", "date": "2015-01-14T00:00:00", "c1": 500.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalId": "17" } ], "serviceURL": "http://localhost:8080/em-remote-service/query/json/readings/1123580/2015/1", "dataSupplierId": "TEST", "dataSupplierLogin": "test" }

XML Request XML Response GET http://localhost:8080/em-remote-service/query/xml/readings/1123580/2015/1 Request Headers: Content-Type: application/xml X-Ekonerg-Login: test

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2017-11-23T15:47:56.009" serviceURL="http://localhost:8080/em-remote-service/query/xml/readings/1123580/2015/1" dataSupplierId="TEST" dataSupplierLogin="test"> <readings>


29

X-Ekonerg-MAC: FZ8NABKpId04g8p07lX3v/edG3+YIXiyvsxMYVSSeoY= Host: <EMIS-service-url>

<reading id="23" meterId="1123580" date="2015-01-18T00:00:00" c1="511.0" c2="500.0" c3="500.0" c4="500.0" internalId="17"/> <reading id="19" meterId="1123580" date="2015-01-17T00:00:00" c1="510.0" c2="500.0" c3="500.0" c4="500.0" internalId="17"/> <reading id="22" meterId="1123580" date="2015-01-16T00:00:00" c1="509.0" c2="500.0" c3="500.0" c4="500.0" internalId="17"/> <reading id="20" meterId="1123580" date="2015-01-15T00:00:00" c1="508.0" c2="500.0" c3="500.0" c4="500.0" internalId="17"/> <reading id="21" meterId="1123580" date="2015-01-14T00:00:00" c1="500.0" c2="500.0" c3="500.0" c4="500.0" internalId="17"/> </readings> </response>

3.7.2 List of OIB-s (OIB – Personal identification number/Osobni identifikacijski broj)

Returns a list of OIBs of institutions for which data suppliers must send bills/advanced readings. If you are a data

supplier sending bills to EMIS application, you can fetch a list of OIBs using this query.

3.7.2.1.1 OIB Query Request

OIB Request GET <EMIS-service-url>/query/[xml|json]/institutions/oib

3.7.2.1.2 OIB Query Response

Readings Response Properties






Response timestamp




oibs List List of Strings List of OIB strings


30

3.7.2.1.3 Examples

OIB Request Example

JSON Request JSON Response GET http://localhost:8080/em-remote-service/query/json/institutions/oib Request Headers: Content-Type: application/json X-Ekonerg-Timestamp: 2019-07-25T11:13:03.085Z X-Ekonerg-MAC: axMfZeb3ESq9gwfdHAEBBowswHIEe9ZpO6GZq2tFPo8= X-Ekonerg-Login: test Host: localhost:8080

{ "status": 200, "statusDesc": "OK", "ts": "2019-07-25T13:13:03.127", "serviceMethod": "GET", "serviceURL": "http://localhost:8080/em-remote-service/query/json/institutions/oib", "dataSupplierId": "TEST", "dataSupplierLogin": "test", "oibs": [ "22339633428","75534548941","57318345822","72370493845",… ] }

XML Request XML Response GET /em-remote-service/query/xml/institutions/oib X-Ekonerg-Timestamp: 2019-07-25T11:15:33.420Z X-Ekonerg-MAC: Bym4+GeIIAPGI6TLczMzbMbi8/wbbWHz3usQ0du6U1Q= X-Ekonerg-Login: test Content-Type: application/xml Host: localhost:8080

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2019-07-25T13:15:33.479" serviceMethod="GET" serviceURL="http://localhost:8080/em-remote-service/query/xml/institutions/oib" dataSupplierId="TEST" dataSupplierLogin="test"> <oibs> <oib>22339633428</oib> <oib>75534548941</oib> <oib>57318345822</oib> <oib>72370493845</oib> <oib>02717359814</oib> <oib>26353705868</oib> <oib>52399386537</oib> … </oibs> </response>

3.8 Service Response Codes These are standard HTTP response codes that the service returns through its “status” and “statusDesc” fields:

Service Response Codes

Code Text Description

200 OK Request was successfully processed

207 Multi-Status Some or all items could not have been processed due to some business reasons

400 Bad Request Malformed request

401 Unauthorized The MAC or username were invalid

500 Internal Server Error An error on the server side occurred

In case of a service error, the service returns a HTTP response code as specified above, and the body of the HTTP

response contains a service response object. When an error occurs in a layer other than the service (e.g. firewalls

or connection timeouts), then instead of the described error response object, a standard http error response will

be returned.

Error Response Example1F

2

JSON Response XML Response HTTP/1.1 401 Unauthorized Server: nginx Date: Mon, 30 Sep 2016 15:26:29 CEST Content-Type: text/html; charset=UTF-8 Cache-Control: no-cache

HTTP/1.1 401 Unauthorized Server: nginx Date: Mon, 30 Sep 2016 15:26:29 CEST Content-Type: text/html; charset=UTF-8 Cache-Control: no-cache

2 HTTP response header is marked italic.


31

Pragma: no-cache {"status":401,"statusDesc":"Unauthorized","ts":"2016-09-30T15:26:29.926","err":"AuthorizationException","errDesc":"Invalid MAC", "serviceURL ":"http://<EMIS-service-url>/batch/xml/send" dataSupplierId="test" dataSupplierLogin="test"}

Pragma: no-cache <response xmlns="http://www.ekonerg.hr/em/bills" status="401" statusDesc="Unauthorized" ts="2016-09-30T15:29:23.664" err="AuthorizationException" errDesc="Invalid MAC" serviceURL="http://<EMIS-service-url>/batch/xml/send " dataSupplierId="test" dataSupplierLogin="test"/>


32

4 COMMAND-LINE CLIENT A simple Java command-line client application called “em-remote-client” allows data-suppliers to easily send XML

and/or JSON batches to the service. The application runs on any platform capable of running Java 5 or later. It can

be triggered either manually, or automatically by a task scheduler. It sends all XML and JSON batch files found in a

specific directory, returning a response code “0” for successful, or specific non-zero values for various failures in

the process. The files will be moved to two different directories for successful and failed attempts, together with

a matching response from the service.

4.1 Installing the Client In order to use the application, a Java 5 or later Runtime Environment, or a Java Development Kit should be

installed on a machine running the application.

1. Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and download the latest

Java JRE. Using a JDK is an overkill in this case and not required to run the application.

2. Install the Java following the on-screen instructions.

This completes the Java installation part. Now install the Client application:

3. Go to https://www.isge.hr/upute/ and download the latest “EMIS WS Client for Remote Readings and

Bills”.

4. Copy the downloaded em-remote-client-X.X.X.jar application to a directory of choice. Let’s call it

{CLIENT_HOME}.

5. Set the permissions so the system would be able to read it.

4.2 Configuring the Client The client has several parameters that can be configured. They can be set through a configuration file or

overridden as command line parameters.

4.2.1 Quick Start

The following steps apply to Windows environments, but they can be also applied to Linux if you use appropriate

directory separators “/” and directory/drive mapping names.

1. Be sure that your EMIS administrators provided you with your username, password and EMIS web service

URL.

2. Let’s say that the working directory is “C:\EmisWS\”

3. Download the “em-remote-client.jar” and place it in the working directory (see chapter 3.1).

4. You need to create a configuration file “em-remote-client.properties” in that directory using Notepad or

another plain text editor of your choice.

5. Put the following content in the em-remote-client.properties file:

usr=<your username (without the “DS!“ prefix, if one existed)>

pwd=<your password in clear text (no space before or after>

url=<EMIS web service URL, as received from EMIS administrators>

charset=utf-8

NOTE: When entering actual values into the fields described above, you should omit the < and >

characters!

This ends the client configuration. Now let’s send some data:

6. Create a directory “input” inside the “C:\EmisWS\”.

7. Create “my-echo.xml” file in your input folder (file names are irrelevant, but the extension is important):

https://www.isge.hr/upute/


33

<?xml version='1.0' encoding='utf-8'?>

<echo xmlns="http://www.ekonerg.hr/em/bills" value="Hello, World!" />

8. Alternatively, you can create an echo.json file:

{"value" : "Hello, World!"}

9. Open console and place it in the working directory “C:\EmisWS\”

10. Run the client with the “-action ECHO” argument:

java -jar em-remote-client.jar -action ECHO

11. The console should say:

1 file found in directory: C:\EmisWS\input

Sending: my-echo.xml >>> https://...../batch/xml/echo [OK]

Successfuly sent files: 1

You should now have a new directory called “C:\EmisWS\processed” with a response file called “my-echo-

res.xml” (and/or “my-echo-res.json”) with the successful response:

<response xmlns="http://www.ekonerg.hr/em/bills" status="200" statusDesc="OK" ts="2016-11-

10T15:15:21.059" value="Hello, World!"/>

Also, the original my-echo.xml file will also be moved from the input directory, to the processed directory.

In case of an error, the two files should be placed in another directory called “failed”. Open the “my-echo-

res.xml” to see what caused the error.

4.2.2 Configuration Parameters

The following are the available configuration parameters, with their default values. Please note that the default

values can be overridden using a configuration file, as described in chapter 3.2.6.

Configuration Parameters

Name Default Description

data

“input” XML or JSON file to be sent, or directory containing the files. When specifying a directory, the application will look only for JSON or XML files (case-insensitive).

base Current directory Default base directory for data, processed, or failed files. If “data”, “proc” or “failed” parameters are specified as a non-absolute path, this value will be used as a base directory.

proc “processed” Directory for saving successfully processed files. It can be either an absolute or a relative path (see “base” parameter). After successful processing a file will be moved to this directory, keeping the same file name. The service response will be saved as a file with the same name and type, with the “-res” appended at the end.

failed “failed” Directory for saving failed files. It can be either an absolute or a relative path (see “base” parameter). After a failure in processing a file will be moved to this directory, keeping the same file name. The service response will be saved as a file with the same name and type, with the “-res” appended at the end.

url “http://localhost:8080” Service base URL. Usually something like “http://server.domain:8080” (the exact URL will be sent to each Data-Supplier together with its username and password). DO NOT USE DEFAULT VALUE, SERVER IS NOT ON YOUR LOCALHOST! THIS IS JUST DEFAULT, USE THE URL WHICH YOU HAVE RECEIVED IN DOCUMENT/EMAIL WITH YOUR LOGIN AND PASSWORD.

action BATCH Web Service action (BATCH, ECHO). BATCH is used for sending batches, and ECHO is used just for connection testing purposes.

usr null Data Supplier user-name.


34

pwd null Data Supplier password in clear or encrypted format. Encrypted passwords start with “{aes}”. See “3.2.5 Encrypting a Password” for details about encrypting a password.

charset System default Local file encoding. This is encoding used locally for storing batches and service responses. It will generally be a system default, but you can specify any other encoding such as UTF-8, UTF-16, CP1250 and so on.

config As described in chapter 3.2.6 Configuration file. If omitted, a configuration file will be searched on default locations as described in chapter “3.2.6 Default Configuration File Locations”.

debug false Turns on some debugging output, like MAC calculation source and result

4.2.3 Passing Parameters in Command Line

The application can be executed from a command line as follows:

java -jar em-remote-client.jar [data] [-base <base>] [-processed <proc>] [-failed <failed>]

[-url <url>] [-usr <name>] [-pwd <password>] [-charset <charset>]

4.2.4 Getting a Help Cheat-Sheet

The following will display help for all the options, with the default values for each parameter:

java -jar em-remote-client.jar [-h | -help]

4.2.5 Encrypting a Password

The following will encrypt and output a given password for safer storing in a configuration file:

java -jar em-remote-client.jar [-encrypt <password>]

Encrypted passwords have an “{aes}” prefix. Copy the output and use it in a configuration file or command line

rather than a plain text.

NOTE: The password is encrypted with and internal AES-128 key that is hard, but not impossible to get.

4.2.6 Default Configuration File Locations

The application tries to find configuration parameters in the following order:

1. Command Line

2. “em-remote-client.properties” in current directory

3. “.em-remote-client” in current directory

4. “em-remote-client.properties” in user home directory

5. “.em-remote-client” in user home directory

4.2.7 Using the Client behind a Web Proxy

If your system uses a web proxy, then you must add the following parameters to all java calls of the em-remote-

client.jar:

a) If the service URL is https, then use


35

java –Dhttps.proxyHost=<proxyHostURL> –Dhttps.proxyPort=<proxyPort> -jar em-remote-

client.jar …

b) If the service URL is http, then use java –Dhttp.proxyHost=<proxyHostURL> –Dhttp.proxyPort=<proxyPort> -jar em-remote-

client.jar …

<proxyHostURL> and <proxyPort> should be replaced with actual Proxy URL and Port values, without the “<” and

“>” characters.

For example:

java –Dhttps.proxyHost=proxy.mycompany.com –Dhttps.proxyPort=8080 -jar em-remote-client.jar …

…or:

java –Dhttp.proxyHost=proxy.mycompany.com –Dhttp.proxyPort=8080 -jar em-remote-client.jar …

4.3 Return Codes The application returns the following codes

Shell Return Codes

Code Description

0 All the batches were successfully processed. A batch is considered successfully processed only if there was not a single failure in the batch, i.e. all the entries were successfully processed.

1 Partial success – there were both successful and unsuccessful files.

2 Total failiure – all the files failed

100 Failure due to invalid parameters.

4.4 Scheduling Batches Sending a batch using the client can be either triggered manually when required, or scheduled using a crontab (on

*nix) or Task Scheduler (on Windows) machines.

A good practice is to put all the files in a single directory and then call the client application to send all the files.

If calling the client application is scheduled, you must ensure that all the XML and JSON files in the outgoing

directory are completed and ready for sending. The easiest way to ensure that is to use a “.tmp” extension for

files that are currently being created or copied, and then change the extension to XML or JSON when completed.


36

5 SIMPLE CLIENT EXAMPLE IN JAVA The following is a simple client application in Java:

package hr.ekonerg.emis.remote.client;

import java.io.Closeable;

import java.io.IOException;

import java.io.InputStream;

import java.io.InputStreamReader;

import java.io.OutputStream;

import java.io.OutputStreamWriter;

import java.net.HttpURLConnection;

import java.net.URL;

import java.security.MessageDigest;

import java.security.NoSuchAlgorithmException;

import java.util.Base64;

import java.util.Date;

public class TestClient {

public static final Charset UTF8 = Charset.forName("UTF-8");

public static void main(String[] args) throws Exception {

String username = "TEST";

String password = "Secret123";

String payload = "{\"value\":\"It is now " + new Date() + "\"}";

String response = echo(username, password, payload);

System.out.println(response);

}

/**

* Calls echo method and returns service response.

*

* @param username

* assigned web service user name

* @param password

* assigned web service password

* @param payload

* request message body

* @return response message body

* @throws IOException

* in case of an I/O exception in communication with the service

*/

public static String echo(String username, String password, String payload) throws IOException {

return wsMethod("POST", "/batch/json/echo", username, password, payload);

}

/**

* Generic call to a REST Web Service method. Internally calculates MAC and sets all required

* HTTP headers.

*

* @param httpMethod

* HTTP method (POST, GET, UPDATE, DELETE...)

* @param methodSubUri

* Web Service method URI. This is the part of the URL behind the server name, port,

* and application context (it should start with a "/").

*

* @param username


* @param password


* @param payload

* request message body

* @return response message body

* @throws IOException


37

* in case of an I/O exception in communication with the service

*/

protected static String wsMethod(String httpMethod, String methodSubUri, String username,

String password, String payload) throws IOException {

URL url = new URL("http://<EMIS-service-url>" + methodSubUri); // replace with proper URL

OutputStream os = null;

InputStream is = null;

try {

HttpURLConnection conn = (HttpURLConnection) url.openConnection();

conn.setRequestMethod(httpMethod);

conn.setRequestProperty("Content-Type", "application/json");

conn.setRequestProperty("X-Ekonerg-Login", username);

conn.setRequestProperty("X-Ekonerg-MAC", getMac(httpMethod, url,

username, password, payload));

conn.setDoOutput(true);

os = conn.getOutputStream();

OutputStreamWriter osw = new OutputStreamWriter(os, UTF8);

osw.write(payload);

osw.flush();

osw.close();

try {

is = conn.getInputStream();

} catch (Exception e) {

closeSilently(is);

is = conn.getErrorStream();

}

InputStreamReader isr = new InputStreamReader(is, UTF8);

char[] cbuf = new char[1024];

StringBuilder sb = new StringBuilder();

int len = 0;

while ((len = isr.read(cbuf)) > 0) {

sb.append(cbuf, 0, len);

}

isr.close();

return sb.toString();

} finally {

closeSilently(is);

closeSilently(os);

}

}

/**

* Calculates message digest salt from the given parameters.

*

* @param httpMethod


* @param methodUri

* Web Service method URI. This is the part of the URI behind the server name and port.

* @param username


* @param password


* @return byte array used to initialize the SHA-256 digester

*/

protected static byte[] getSalt(String httpMethod, String methodUri, String username,

String password) {

String str = httpMethod + "\n" + methodUri + "\n" + username + "\n" + password;

return str.getBytes(UTF8);


38

}

/**

* Calculates message MAC.

*

* @param httpMethod


* @param methodUrl

* Full method URL

* @param username


* @param password


* @param payload

* message body

* @return Base64 encoded message MAC

*/

public static String getMac(String httpMethod, URL methodUrl, String username, String password,

String payload) {

try {

MessageDigest md = MessageDigest.getInstance("SHA-256");

byte[] salt = getSalt(httpMethod, methodUrl.getPath(), username, password);

md.update(salt);

if (payload != null)

md.update(payload.getBytes());

return Base64.getEncoder().encodeToString(md.digest());

} catch (NoSuchAlgorithmException e) {

throw new RuntimeException(e);

}

}

protected static void closeSilently(Closeable c) {

try {

if (c != null)

c.close();

} catch (Exception e) {

}

}

}

6 DATASUPPLIER WEB INTERFACE In order to review sent data, and to check setup of remote meters, a data supplier can access the EMIS web

application using his login and key.

1. Go to EMIS web application login page.

2. Login is: DS!<datasupplier login>

3. Password is: <datasupplier key>

E.g. if a data supplier login is TEST, and data supplier key is test123, then web page login is “DS!TEST” and

password is “test123”.

You can review your logins, for remote readings:

• List of energy carriers,

• Energy carrier counters

• Meters (a list of meters for which you can send readings)

• Counters on meters (which you must send with each reading)


39

• Metering devices (for information only, to be able to map device serial number with metering location

serial number if needed)

• Log of sent readings

• List of accepted readings

• Errors in last 24h

• Errors in last 24h – detailed

For remote bills:

• Sent energy carriers

• Sent energy bill field names

• Sent vendors

• Sent tariffs

• Sent meters

• Sent bills

• Sent bill items

All these tables can also be exported to Excel.


40

Change Log

2017-05-05 - Bugfix in source code in “Simple Client Example in Java”.

2017-05-10 - Added Change log;

- Doc fix: type of “tempOut” field in object “Reading” changed to “Decimal” (was “Text”);

- Doc fix: field “billDataList” in “Bill Properties” table changed to “billData”.

2017-09-14 - serviceURL, dataSupplierId and dataSupplierLogin to service responses

- added note to energyCarrierField name

- added instructions for using the Client behind a proxy

2017-11-23 - added meters and readings query methods

2018-01-23 - changed mandatory / optional fields in BillData

2018-03-16 - minor changes in chapter names

2018-04-26 - added Authentication Example

- added “debug” parameter into the Command-Line Client application

2018-10-09 - Fixed error in example XML for bills in chapter 3.6.3.1.6 Object “bill”.

- Fixed several typos in the text

2019-04-19 - added authentication debugging in chapter 3.3

2019-04-25 - added better explanation of unregistering meter in chapter 3.6.3.1.5

2019-04-30 - Added more details about response on Meters query in chapter 3.7.1.1 (response contains a list

of counters)

2019-07-22 - chapter 4.2.2 added red text to not use default URL

2019-07-25 - added chapter 3.7.2

2019-12-19 - added advanced remote readings

- reorganized chapter Query Methods

2020-01-03 -minor changes

2020-02-21 -added chapter 3.4 XML Namespace

2020-02-26 -added info about bill items which are not related to meters in chapter 3.6.3.1.6 Object “bill”

2020-03-09 -added required personnel qualifications for implementing for implementing a connection to the

service

2020-05-08 -added igoreExisting attibute for energyCarrierCounter, meterDevice and meterDeviceCounter

energy management information system web service for remote readings and bills … · 2 data...

Documents