ENERGY MANAGEMENT INFORMATION SYSTEM. EMIS Web Service for Remote Readings and Bills. Issue

Transcription

1 ENERGY MANAGEMENT INFORMATION SYSTEM EMIS Web Service for Remote Readings and Bills Issue

2 CONTENTS 1 Preface: Data Structure Remote bills Remote readings Web Service Data Exchange Overview Connecting to the REST Web Service Authentication Echo Method Echo Request Echo Response Examples Batch Sending Method Batch Request Structure Batch Response Structure Batch-Contained Objects Structure Query Methods for Remote Readings Meters Query Readings Query Service Response Codes Command-Line Client Installing the Client Configuring the Client Quick Start Configuration Parameters Passing Parameters in Command Line Getting a Help Cheat-Sheet Encrypting a Password Default Configuration File Locations Using the Client behind a Web Proxy Return Codes Scheduling Batches Simple Client Example in Java DataSupplier Web Interface

3 2

4 1 PREFACE: DATA STRUCTURE 1.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, IDs of records 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. Energy Carriers Vendors ENERGENT_ID ENERGENT_ID ENERGENT_ID V EN DOR_ID ENERGENT_ID Energy Carrier Fields Tariffs Bills V EN DOR_ID Metering Points TARIFF_ID BILLITEM_ID METER_ID Bill Data BILL_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. 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 which 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, doesn t 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 doesn t change. Other synonyms for metering point are also: meter and metering location. 3

5 Each of the above objects must have an identifier that is unique throughout a data supplier domain. 1.2 Remote readings This is data model for remote readings. Metering points are assigned to your DataSupplier account by EMIS administrator, so you can send only readings for assigned meters. 6. 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. 4

6 2 WEB SERVICE DATA EXCHANGE 2.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 should contain a sender s username and a security MAC (Message Authentication Code) value, calculated as a hash of the sent data and the secret pre-shared key. The following data can be exchanged this way: A) For billing companies which send remote bills: 1. Energy Carrier Vendors 2. Energy Carriers 3. Tariffs 4. Metering Points 5. Bills B) For companies that manage metering devices, their SCADA systems, and are responsible for sending of hourly remote readings: 1. 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 the timestamp. In case of an error, an object with the original fields, together with error code and error description will be returned. 2.2 Connecting to the REST Web Service HTTP traffic between a client and the URI of the web service must be allowed. 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. 2.3 Authentication The HTTP-Header section of each request must contain the following: Parameter X-Ekonerg-Login X-Ekonerg-MAC Description Data-Supplier username 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 5

7 2.4 Echo Method The echo method is used for integration/authentication testing Echo Request Echo Request Properties Name Type Info Description value Text Any string The contents of this string will be returned by the service Echo Response Echo Response Properties Name Type Info Description Examples Echo Example Successful 1 JSON Request POST Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Content-Length: 27 Host: <EMIS-service-url> JSON Response "status":200,"statusdesc":"ok","ts":" t15:15:31.215","value":"hello, World!" "value" : "Hello, World!" XML Request POST Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: FZ8NABKpId04g8p07lX3v/edG3+YIXiyvsxMYVSSeoY= Content-Length: 109 Host: <EMIS-service-url> XML Response <response xmlns=" status="200" statusdesc="ok" ts=" t15:13:22.609" value="hello, World!"/> <?xml version='1.0' encoding='utf-8'?> <echo xmlns=" value="hello, World!" /> Echo Example Failed Authentication JSON Request POST Content-Type: application/json JSON Response status Number HTTP response code Standard HTTP response code statusdesc Text HTTP response Standard HTTP response description description ts Timestamp YYYY-MM- Response timestamp DD T HH:mm:ss.SSS 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 "status":401,"statusdesc":"unauthorized","ts":" T15:26:29.926","err":"AuthorizationException","errDesc":"Invalid MAC" 1 HTTP request headers are written in italic. 6

8 X-Ekonerg-Login: test X-Ekonerg-MAC: abcd Content-Length: 27 Host: <EMIS-service-url> "value" : "Hello, World!" XML Request POST Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: abcd Content-Length: 109 Host: <EMIS-service-url> XML Response <response xmlns=" status="401" statusdesc="unauthorized" ts=" t15:29:23.664" err="authorizationexception" errdesc="invalid MAC"/> <?xml version='1.0' encoding='utf-8'?> <echo xmlns=" value="hello, World!" /> 2.5 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 should 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 many objects, we ll refer to it as Request Batch from now on. 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 the error description 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 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: 7

9 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 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) Batch Response Structure A response contains two sections, containing a batch with the processed and a batch with the failed objects: succeeded with the batch containing operations and objects that were successfully processed (deleted, unregistered or inserted). Each succeeded object will be minimized just to its ID, plus a ts containing the processing timestamp. failed with the 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. 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 Echo Response 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: 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. 8

10 Sending of remote bills Object vendor Vendor Properties Name Type Info Description id Text Primary Key, Data Supplier s Vendor ID Mandatory 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 chaned in any way. Vendor Example (Fragment) JSON "id" : "AP", "name" : "Austin Powers Ltd." XML <vendor id="ap" name="austin Powers Ltd."/> Object energycarrier Energy Carrier Properties Name Type Info Description id Text Primary Key, Data Supplier s Energy Carrier ID Mandatory name Text Mandatory Energy Carrier 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 chaned in any way. Energy Carrier Example (Fragment) JSON "id" : "MOJO", "name" : "Mojo Energy" XML <energycarrier id="mojo" name="mojo Energy"/> Object energycarrierfield Energy Carrier Field Properties Name Type Info Description id Text Primary Key, Data Supplier s Bill Field ID Mandatory energycarrierid Text Primary Key, Data Supplier s Energy Carrier ID Mandatory 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. 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 9

11 not be chaned in any way. Energy Carrier Field Example (Fragment) JSON "id" : "HOT", "energycarrierid" : "MOJO", "name" : "Hot Mojo" XML <energycarrierfield id="hot" energycarrierid="mojo" name="hot Mojo"/> Object tariff Tariff Properties Name Type Info Description id Text Primary Key, Data Supplier s Tariff ID Mandatory energycarrierid Text Mandatory Data Supplier s Energy Carrier ID vendorid Text Mandatory Data Supplier s Vendor ID name Text Mandatory Tariff 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 chaned in any way. Tariff Example (Fragment) JSON "id":"mojo_main", "energycarrierid":"mojo", "vendorid":"ap", "name":"main Mojo Tariffa" XML <tariff id="mojo_main" energycarrierid="mojo" vendorid="ap" name="main Mojo Tariff"/> Object meter Meter Properties Name Type Info Description id Text Primary Key, Data Supplier s Metering point ID Mandatory serialnumber Text Mandatory Meter serial number description Text Optional Meter description address Complex Optional Meter address buildingname Text Optional Facility name ownername Text Optional Owner name ownerexternalid Text Optional Owner s Tax ID (OIB) energycarrierid Text Mandatory Data Supplier s Energy Carrier ID unregisterdate Date YYYY-MM-DD Date since no bills will have been sent Only for unregistering unregistercomment Text Only for unregistering Comment (e.g. number of contract) When registering a meter with ID that is already registered, the system will update data and will NOT raise a primary key exception, and it will update the following fields: serialnumber, description, address, buildingname, ownername, and ownerexternalid. 10

12 Address Properties Name Type Info Description address Text Optional Street name with house number city Text Optional City name zip Text Optional Zip code Meter Example (Fragment) JSON "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" XML <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> Object bill Bill with its contained BillData entries are processed in a 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 Name Type Info Description id Text Primary Key, Data Supplier s Bill ID Mandatory 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 Name Type Info Description 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 11

13 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. Bill Example (Fragment) JSON "id" : "INT-0002", "serialnumber" : "AP ", "total" : , "month" : 1, "year" : 2016, "billdata" : [ "energycarrierid" : "MOJO", "meterid" : "METER1", "vendorid" : "AP", "tariffid" : "MOJO_MAIN", "datefrom" : " ", "dateto" : " ", "energycarrierfieldid" : "HOT", "quantity" : 10.0, "unitcost" : 123.0, "taxpercentage" : 25.0,, "energycarrierid" : "MOJO", "meterid" : "METER2", "vendorid" : "AP", "tariffid" : "MOJO_MAIN", "datefrom" : " ", "dateto" : " ", "energycarrierfieldid" : "COOL", "quantity" : 100.0, "unitcost" : 95.0, "taxpercentage" : 25.0, ] XML <bill id="int-0002" serialnumber="ap " total=" " month="1" year="2016" > <billdata energycarrierid="mojo" meterid="meter1" vendorid="ap" tariffid="mojo_main" datefrom=" " dateto=" " vendorid="ap" energycarrierfieldid="hot" quantity="10.0" unitcost="123.0" taxpercentage="25.0"/> <billdata energycarrierid="mojo" meterid="meter2" vendorid="ap" tariffid="mojo_main" datefrom=" " dateto=" " vendorid="ap" energycarrierfieldid="cool" quantity="100.0" unitcost="95.0" taxpercentage="25.0"/> </meter> Bill Example Successful (complete) JSON Request POST 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 ", "total" : , "month" : 1, "year" : 2015, "billdata" : [ "energycarrierid" : "MOJO", "meterid" : "METER1", "vendorid" : "AP", "tariffid" : "MOJO_MAIN", "datefrom" : " ", "dateto" : " ", "energycarrierfieldid" : "HOT", "quantity" : 10.0, "unitcost" : 123.0, "taxpercentage" : 25.0, JSON Response "status" : 200, "statusdesc" : "OK", "ts" : " T10:34:13.296", "serviceurl" : " ", "succeeded" : "ts" : " T10:34:13.308", "insert" : "bills" : [ "id" : "INT-0001", "ts" : " T10:34:13.308" ] "datasupplierid" : "test" "datasupplierlogin" : "test" 12

14 "energycarrierid" : "MOJO", "meterid" : "METER2", "vendorid" : "AP", "tariffid" : "MOJO_MAIN", "datefrom" : " ", "dateto" : " ", "energycarrierfieldid" : "COOL", "quantity" : 100.0, "unitcost" : 95.0, "taxpercentage" : 25.0 ] ] XML Request POST Content-Type: application/xml 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=" ts=" t12:15:20.224"> <insert> <bill id="int-0001" serialnumber="ap " year="2015" month="1" total=" "> <billdata energycarrierid="mojo" meterid="meter1" vendorid="ap" tariffid="mojo_main" datefrom=" " dateto=" " energycarrierfieldid="hot" quantity="10.0" unitcost="123.0" taxpercentage="25.0"/> <billdata energycarrierid="mojo" meterid="meter2" vendorid="ap" tariffid="mojo_main" datefrom=" " dateto=" " energycarrierfieldid="cool" quantity="100.0" unitcost="95.0" taxpercentage="25.0"/> </bill> </insert> </batch> XML Response <response xmlns=" status="200" statusdesc="ok" ts=" t12:18:10.358" serviceurl=" " datasupplierid="test" datasupplierlogin="test"> <succeeded ts=" t12:18:10.373"> <insert> <bill id="int-0001" ts=" t12:18:10.373"/> </insert> </succeeded> </response> 13

15 In the following example, an unknown meterid is being delivered in the second entry of the BillData list. 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 POST 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 ", "total" : , "month" : 1, "year" : 2015, "billdata" : [ "energycarrierid" : "MOJO", "meterid" : "METER1", "vendorid" : "AP", "tariffid" : "MOJO_MAIN", "datefrom" : " ", "dateto" : " ", "energycarrierfieldid" : "HOT", "quantity" : 10.0, "unitcost" : 123.0, "taxpercentage" : 25.0, "energycarrierid" : "MOJO", "meterid" : "METER2x", "vendorid" : "AP", "tariffid" : "MOJO_MAIN", "datefrom" : " ", "dateto" : " ", "energycarrierfieldid" : "COOL", "quantity" : 100.0, "unitcost" : 95.0, "taxpercentage" : 25.0 ] ] XML Request POST 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=" ts=" t12:15:20.224"> <insert> <bill id="int-0001" serialnumber="ap " year="2015" month="1" total=" "> <billdata energycarrierid="mojo" meterid="meter1" vendorid="ap" JSON Response "status" : 200, "statusdesc" : "OK", "ts" : " T12:21:08.403", "failed" : "ts" : " T12:21:08.420", "serviceurl" : " ", "insert" : "bills" : [ "id" : "INT-0001", "serialnumber" : "AP ", "year" : 2015, "month" : 1, "billdata" : [ "ts" : " T12: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 : at \"EMIS.REMOTEBILLS_BACK\", line 298\n", "energycarrierid" : "MOJO", "meterid" : "METER2x", "vendorid" : "AP", "tariffid" : "MOJO_MAIN", "datefrom" : " ", "dateto" : " ", "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 : at \"EMIS.REMOTEBILLS_BACK\", line 298\n", "total" : , "ts" : " T12:21:08.420" ] "datasupplierid" : "test" "datasupplierlogin" : "test" XML Response <response xmlns=" status="200" statusdesc="ok" ts=" t12:28:55.396" serviceurl=" " datasupplierid="test" datasupplierlogin="test"> <failed ts=" t12:28:55.403"> <insert> <bill id="int-0001" serialnumber="ap " 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 ORA-06512: at "EMIS.REMOTEBILLS_BACK", line 298 " total=" " ts=" t12:28:55.403"> <billdata ts=" t12:28:55.402" err="foreignkeyexception" errdesc="preparedstatementcallback; SQL [call REMOTEBILLS_BACK.BILL_SEND_FIELD(?,?,?,?,?,?,?,?,?,?,?,?,?)]; ORA-02291: integrity 14

16 tariffid="mojo_main" datefrom=" " dateto=" " energycarrierfieldid="hot" quantity="10.0" unitcost="123.0" taxpercentage="25.0"/> <billdata energycarrierid="mojo" meterid="meter2x" vendorid="ap" tariffid="mojo_main" datefrom=" " dateto=" " 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 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 ORA-06512: at "EMIS.REMOTEBILLS_BACK", line 298 " energycarrierid="mojo" meterid="meter2x" vendorid="ap" tariffid="mojo_main" datefrom=" " dateto=" " energycarrierfieldid="cool" quantity="100.0" unitcost="95.0" taxpercentage="25.0"/> </bill> </insert> </failed> </response> Sending of 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 2.6. Query Methods for 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. In case of sending changes to readings, you must first delete the existing readings and then send new ones Object reading The following sections describes format of remote readings. Reading Properties Name Type Info Description meterid Text UK, Mandatory, EMIS Meter ID Foreign key 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 c2 Decimal Optional Counter 2 value c3 Decimal Optional Counter 3 value c4 Decimal Optional Counter 4 value c5 Decimal Optional Counter 5 value tempin Decimal Optional Inside temperature in C tempout Decimal Optional Outside temperature in C people Number Optional Number of occupants internalid Text UK, Optional Internal Data Supplier s reading ID id Text Return value Record ID in EMIS database 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. 15

17 Reading Example (successful) JSON Request POST 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" : " ", "date" : " T02:02:00", "c1" : "209002", "internalid" : "19625", "meterid" : " ", "date" : " T02:03:00", "c1" : "209003" ] XML Request POST 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=" ts=" t14:42:00.558"> <insert> <reading meterid=" " date=" t02:02:00" c1=" " internalid="19625"/> <reading meterid=" " date=" t02:03:00" c1=" "/> </insert> </batch> JSON Response "status" : 200, "statusdesc" : "OK", "ts" : " T14:42:00.601", "serviceurl" : " ", "succeeded" : "ts" : " T14:42:00.675", "insert" : "readings" : [ "ts" : " T14:42:00.649", "id" : " ", "internalid" : "19625", "ts" : " T14:42:00.674", "id" : " ", "meterid" : " ", "date" : " T02:03:00" ] "datasupplierid" : "test" "datasupplierlogin" : "test" XML Response <response xmlns=" status="200" statusdesc="ok" ts=" t14:42:00.601" serviceurl=" " datasupplierid="test" datasupplierlogin="test"> <succeeded ts=" t14:42:00.675"> <insert> <reading ts=" t14:42:00.649" id=" " internalid="19625"/> <reading ts=" t14:42:00.674" id=" " meterid=" " date=" t02:03:00"/> </insert> </succeeded> </response> Reading Example (partially successful) JSON Request POST 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" : " ", "date" : " T02:04:00", "c1" : "209004", "internalid" : "19631", "meterid" : " ", JSON Response "status" : 200, "statusdesc" : "OK", "ts" : " T14:54:23.123", "serviceurl" : " ", "succeeded" : "ts" : " T14:54:23.285", "insert" : "readings" : [ "ts" : " T14:54:23.165", "id" : " ", "internalid" : "19631" ], "failed" : "ts" : " T14:54:23.285", "insert" : "readings" : [ "ts" : " T14:54:23.283", 16

18 "date" : " T02:03:00", "c1" : "209005" ] XML Request POST 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=" ts=" t14:54:23.113"> <insert> <reading meterid=" " date=" t02:04:00" c1=" " internalid="19631"/> <reading meterid=" " date=" t02:03:00" c1=" "/> </insert> </batch> "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: \nORA-06512: at \"EMIS.REMOTE\", line 60\nORA-06512: at \"EMIS.REMOTE\", line 392\nORA-06512: at line 1\n", "meterid" : " ", "date" : " T02:03:00", "c1" : ] "datasupplierid" : "test" "datasupplierlogin" : "test" XML Response <response xmlns=" status="200" statusdesc="ok" ts=" t14:54:23.123" serviceurl=" " datasupplierid="test" datasupplierlogin="test"> <succeeded ts=" t14:54:23.285"> <insert> <reading ts=" t14:54:23.165" id=" " internalid="19631"/> </insert> </succeeded> <failed ts=" t14:54:23.285"> <insert> <reading ts=" t14: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: ORA-06512: at "EMIS.REMOTE", line 60 ORA-06512: at "EMIS.REMOTE", line 392 ORA-06512: at line 1 " meterid=" " date=" t02:03:00" c1=" "/> </insert> </failed> </response> 2.6 Query Methods for Remote Readings The following methods are used for querying Meters and Readings that a data supplier has sent Meters Query This method is used for getting a list of all the meters that a data supplier previously sent. It is a REST GET method with no parameters. It comes in JSON and XML flavors Meters Query Request Meters Request Properties <EMIS-service-url>/query/[xml json]/meters Name Type Info Description No parameters are required, except for the MAC authorization in HTTP header Meters Query Response Meters Response Properties Name Type Info Description status Number HTTP response code Standard HTTP response code statusdesc Text HTTP response Standard HTTP response description description ts Timestamp YYYY-MM- Response timestamp DD T HH:mm:ss.SSS serviceurl Text HTTP/S link URL of the service (copied from request) datasupplierid Text userid User ID 17

19 datasupplierlogin Text userlogin User Login 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 Examples Meters Request Example JSON Request GET Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Host: localhost:8080 XML Request GET Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: FZ8NABKpId04g8p07lX3v/edG3+YIXiyvsxMYVSSeoY= Host: <EMIS-service-url> JSON Response "status": 200, "statusdesc": "OK", "ts": " T14:29:55.687", "meters": [ "meterid": , "meterserialnumber": "NN ", "metershortdescription": null, "meterdescription": null, "objectname": "Gradski kotar Sirobuja", "isgecode": "HR ", "energent": "Električna energija", "energentid": "Electricity", "meterid": , "meterserialnumber": "NNxxxxxx", "metershortdescription": null, "meterdescription": null, "objectname": "Osnovna Škola Miroslava krleže Čepin", "isgecode": "HR ", "energent": "Električna energija", "energentid": "Electricity" ], "serviceurl": " "datasupplierid": "TEST", "datasupplierlogin": "test" XML Response <response xmlns=" status="200" statusdesc="ok" ts=" t13:25:03.012" serviceurl=" datasupplierid="test" datasupplierlogin="test"> <meters> <meter> <meterid> </meterid> <meterserialnumber>nn </meterserialnumber> <metershortdescription/> <meterdescription/> <objectname>gradski kotar Sirobuja</objectName> <isgecode>hr </isgecode> <energent>električna energija</energent> <energentid>electricity</energentid> </meter> <meter> <meterid> </meterid> <meterserialnumber>nnxxxxxx</meterserialnumber> <metershortdescription/> <meterdescription/> <objectname>osnovna Škola Miroslava krleže Čepin</objectName> <isgecode>hr </isgecode> <energent>električna energija</energent> <energentid>electricity</energentid> </meter> </meters> </response> 18

20 2.6.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 Readings Query Request Readings Request Properties <EMIS-service-url>/query/[xml json]/readings/<meterid>/<year>/<month> Name Type Info Description meterid Number - Meter ID year Number - Year month Number - Month Readings Query Response Readings Response Properties Name Type Info Description status Number HTTP response code Standard HTTP response code statusdesc Text HTTP response Standard HTTP response description description ts Timestamp YYYY-MM- Response timestamp DD T HH:mm:ss.SSS serviceurl Text HTTP/S link URL of the service (copied from request) datasupplierid Text userid User ID datasupplierlogin Text userlogin User Login readings List List of Objects List of Reading objects reading (zero or more entries) as described in chapter Object reading Examples Readings Request Example JSON Request GET Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Host: localhost:8080 JSON Response "status": 200, "statusdesc": "OK", "ts": " T15:47:55.906", "readings": [ "serviceurl": null, "id": "23", "meterid": " ", "date": " T00:00:00", "c1": 511.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalid": "17", "serviceurl": null, "id": "19", "meterid": " ", "date": " T00:00:00", "c1": 510.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalid": "17", "serviceurl": null, "id": "22", "meterid": " ", "date": " T00:00:00", "c1": 509.0, "c2": 500.0, "c3": 500.0, 19

21 XML Request GET Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: FZ8NABKpId04g8p07lX3v/edG3+YIXiyvsxMYVSSeoY= Host: <EMIS-service-url> "c4": 500.0, "internalid": "17", "serviceurl": null, "id": "20", "meterid": " ", "date": " T00:00:00", "c1": 508.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalid": "17", "serviceurl": null, "id": "21", "meterid": " ", "date": " T00:00:00", "c1": 500.0, "c2": 500.0, "c3": 500.0, "c4": 500.0, "internalid": "17" ], "serviceurl": " "datasupplierid": "TEST", "datasupplierlogin": "test" XML Response <response xmlns=" status="200" statusdesc="ok" ts=" t15:47:56.009" serviceurl=" datasupplierid="test" datasupplierlogin="test"> <readings> <reading id="23" meterid=" " date=" T00:00:00" c1="511.0" c2="500.0" c3="500.0" c4="500.0" internalid="17"/> <reading id="19" meterid=" " date=" T00:00:00" c1="510.0" c2="500.0" c3="500.0" c4="500.0" internalid="17"/> <reading id="22" meterid=" " date=" T00:00:00" c1="509.0" c2="500.0" c3="500.0" c4="500.0" internalid="17"/> <reading id="20" meterid=" " date=" T00:00:00" c1="508.0" c2="500.0" c3="500.0" c4="500.0" internalid="17"/> <reading id="21" meterid=" " date=" T00:00:00" c1="500.0" c2="500.0" c3="500.0" c4="500.0" internalid="17"/> </readings> </response> 2.7 Service Response Codes These are standard HTTP responses that the service may return in its status and statusdesc : 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 an error, the service returns a HTTP response code as specified above, and the body of the HTTP response contains a service response object, with the exception of errors returned by layers other than the service (e.g. firewalls or connection timeouts), where the response object cannot be returned. 20

22 Error Response Example 2 JSON Response HTTP/ Unauthorized Server: nginx Date: Mon, 30 Sep :26:29 CEST Content-Type: text/html; charset=utf-8 Cache-Control: no-cache Pragma: no-cache "status":401,"statusdesc":"unauthorized","ts":" T15:26:29.926","err":"AuthorizationException","errDesc":"Invalid MAC", "serviceurl ":" datasupplierid="test" datasupplierlogin="test" XML Response HTTP/ Unauthorized Server: nginx Date: Mon, 30 Sep :26:29 CEST Content-Type: text/html; charset=utf-8 Cache-Control: no-cache Pragma: no-cache <response xmlns=" status="401" statusdesc="unauthorized" ts=" t15:29:23.664" err="authorizationexception" errdesc="invalid MAC" serviceurl=" " datasupplierid="test" datasupplierlogin="test"/> 2 HTTP response header is marked italic. 21

23 3 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. 3.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 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 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. 3.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 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\. 22

24 7. Create my-echo.xml file in your input folder (file names are irrelevant, but the extension is important): <?xml version='1.0' encoding='utf-8'?> <echo xmlns=" 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 >>> [OK] Successfuly sent files: 1 You should now have a new directory called C:\EmisWS\processed with a response file called my-echores.xml (and/or my-echo-res.json ) with the successful response: <response xmlns=" status="200" statusdesc="ok" ts=" t15: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-echores.xml to see what caused the error 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 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 Service base URL. Usually something like (the exact URL will be sent to each Data-Supplier together with its username 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. pwd null Data Supplier password in clear or encrypted format. Encrypted passwords start with aes. See Encrypting a Password for details about encrypting a password. 23