ENERGY MANAGEMENT INFORMATION SYSTEM - EMIS Web Service for Remote Readings and Bills Issue 2021-04-14 - ISGE
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
ENERGY MANAGEMENT INFORMATION SYSTEM EMIS Web Service for Remote Readings and Bills Issue 2021-04-14
EMIS Web Service for Remote Readings and Bills 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.2.1 Reponse types.......................................................................................................................................7 3.3 Authentication ..............................................................................................................................................8 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.6.4 Errors in batch processing ..................................................................................................................25 3.7 Query Methods ...........................................................................................................................................26 3.7.1 Basic Remote Readings – Meters and Readings .................................................................................26 3.7.2 List of OIB-s (OIB – Personal identification number/Osobni identifikacijski broj)..............................30 3.8 Service Response Codes .............................................................................................................................31 4 Command-Line Client .........................................................................................................................................33 4.1 Installing the Client .....................................................................................................................................33 4.2 Configuring the Client .................................................................................................................................33 4.2.1 Quick Start ..........................................................................................................................................33 4.2.2 Configuration Parameters ..................................................................................................................34 4.2.3 Passing Parameters in Command Line................................................................................................35 4.2.4 Getting a Help Cheat-Sheet ................................................................................................................35 1
EMIS Web Service for Remote Readings and Bills 4.2.5 Encrypting a Password ........................................................................................................................35 4.2.6 Default Configuration File Locations ..................................................................................................35 4.2.7 Using the Client behind a Web Proxy .................................................................................................36 4.3 Return Codes ..............................................................................................................................................36 4.4 Scheduling Batches .....................................................................................................................................36 5 Simple Client Example in Java.............................................................................................................................37 6 DataSupplier Web Interface ...............................................................................................................................39 2
EMIS Web Service for Remote Readings and Bills 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 Term "meter readings" in this document refers to energy and water consumption readings. If you need to send temperature, humidity, CO₂, or any other value which is not energy or water consumption then you need to send "sensor readings", please see document "EMIS Web Service for Sensor Readings". What do I have to send? Which chapters do I need to read? This table gives you just a general direction of what you need to specifically look at: 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. … in some cases you will send … a smart metering company, … need to send readings, 2.3 and 3.6.3.2 advanced readings. …need to send temperature, … need to look at the document … a smart metering company, humidity, CO₂, or any other "EMIS Web Service for Sensor non-energy-or-water readings, Readings" 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 … a list of institutions. You will determine from descriptions. your business data which meters belong to It is likely that EMIS administrators will be these institutions. You will first send to EMIS a periodically sending you updates for the list of list of meters (with IDs from your database) that new meters with their EMIS IDs. (EMIS ID of a belong to these institutions, following which you meter never changes, but a list of meters for will start send readings. which you will send readings might). (For sending a list of meters, we use the term *Subject to signed contract “registering meters”). You will periodically update a list of registered meters that belong to these institutions as they might change. 3
EMIS Web Service for Remote Readings and Bills 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 … by data supplier (you). … by EMIS administrators. database need to be linked (1-on-1, using their You will receive a list of meters in EMIS with When you register meters in EMIS, EMIS description, serial number, etc.). That linking will their IDs from EMIS database, you will find administrators will link a list of “your” meters be performed… corresponding meter in your database with a list of EMIS meters. (corresponding ID). If one meter has more counters (e.g. electricity … values of all counters taken at same time (for ... values of each counter taken at same time has daily active consumption, nightly active the same meter) are sent in the same data (for the same meter) is send in the separate data consumption, daily reactive consumption, record (XML or JSON). record (XML or JSON). nightly reactive consumption)… Record refers to EMIS meter ID. 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. Energy Carriers Vendors ENERGENT_ID ENERGENT_ID ENERGENT_ID VEN DOR_ID ENERGENT_ID Energy Carrier Fields Bills Tariffs VEN DOR_ID TARIFF_ID Metering Points BILLITEM_ID Bill Data BILL_ID METER_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. 4
EMIS Web Service for Remote Readings and Bills 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 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) METER_ID Readings 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. 5
EMIS Web Service for Remote Readings and Bills 2.3 Advanced remote readings Energy Carriers Energy Carrier Counters ENERGENT_ID (PK: ENERGENT_ID) (PK: ENG_COUNTER_ID) ENERGENT_ID Metering Points ENG_COUNTER_ID (PK: METER_ID) METER ID Metering Devices Metering Device Counters DEVICE_ID (PK: MTR_DEVICE_ID) (PK: MTR_DEVICE_ID, ENG_COUNTER_ID) DVC_COUNTER_ID Reading 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! 6
EMIS Web Service for Remote Readings and Bills 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.2.1 Reponse types Responses can be in XML or JSON, although media type is included in URI we recommend using "Accept" header in HTTP request: Accept:application/json or Accept:application/xml 7
EMIS Web Service for Remote Readings and Bills 3.3 Authentication The HTTP-Header section of each request must contain the following: Parameter Description X-Ekonerg-Login Data-Supplier username 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: AUTHTUTORIAL • Password: authtutorial_key • Message payload (body): {"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\nAUTHTUTORIAL\nauthtutorial_key{"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: 2f36UaFn5LyuvDvyKn5uyprMI6N1Hex2ma+wMcfQAtY= That is the value you should set as your X-Ekonerg-MAC header value, together with the X-Ekonerg-Login set to AUTHTUTORIAL. (Note, that AUTHTUTORIAL user always fails with error 401 Unauthorized, because it is used for MAC debugging only.) 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. 8
EMIS Web Service for Remote Readings and Bills • 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. 3.4 XML Namespace If you are sending XML structure its top object (usually ) must have namespace http://www.ekonerg.hr/em/bills, i.e. 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 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 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 – Successful 1 0F JSON Request JSON Response POST http:///batch/json/echo {"status":200,"statusDesc":"OK","ts":"2016-09-30T15:15:31.215","value":"Hello, World!"} Request Headers: Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Content-Length: 27 Host: {"value" : "Hello, World!"} 1 HTTP request headers are written in italic. 9
EMIS Web Service for Remote Readings and Bills XML Request XML Response POST http:///batch/xml/echo Request Headers: Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: FZ8NABKpId04g8p07lX3v/edG3+YIXiyvsxMYVSSeoY= Content-Length: 109 Host: Echo Example – Failed Authentication JSON Request JSON Response POST http:///batch/json/echo {"status":401,"statusDesc":"Unauthorized","ts":"2016-09- 30T15:26:29.926","err":"AuthorizationException","errDesc":"Invalid MAC"} Request Headers: Content-Type: application/json X-Ekonerg-Login: test X-Ekonerg-MAC: abcd Content-Length: 27 Host: {"value" : "Hello, World!"} XML Request XML Response POST http:///batch/xml/echo Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: abcd Content-Length: 109 Host: 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 for XML) 2. List of Metering Points to unregister (“unregister” for JSON or for XML) 3. List of objects for insertion (“insert” for JSON or for XML) 10
EMIS Web Service for Remote Readings and Bills 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: • “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. 11
EMIS Web Service for Remote Readings and Bills 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. 3.6.3.1 Sending of remote bills 3.6.3.1.1 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 If true, no exception will be thrown when inserting an entry “false”, omitted -> with the same ID, so the new entry will be ignored, and the “false”) 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." } 3.6.3.1.2 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 If true, no exception will be thrown when inserting an entry “false”, omitted -> with the same ID, so the new entry will be ignored, and the “false”) existing entry WILL NOT BE UPDATED! An existing entry can not be changed in any way. Energy Carrier Example (Fragment) JSON XML { "id" : "MOJO", "name" : "Mojo Energy" } 12
EMIS Web Service for Remote Readings and Bills 3.6.3.1.3 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 -> Allowed values are “true” (for bill items representing false) consumption) and “false”. ignoreExisting Boolean Optional (“true” or If true, no exception will be thrown when inserting an entry “false”, omitted -> with the same ID, so the new entry will be ignored, and the “false”) existing entry WILL NOT BE UPDATED! An existing entry can not be changed in any way. Energy Carrier Field Example (Fragment) JSON XML { "id" : "HOT", "energyCarrierId" : "MOJO", "name" : "Hot Mojo" } 3.6.3.1.4 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 If true, no exception will be thrown when inserting an entry “false”, omitted -> with the same ID, so the new entry will be ignored, and the “false”) existing entry WILL NOT BE UPDATED! An existing entry can not be changed in any way. Tariff Example (Fragment) JSON XML { "energyCarrierId":"MOJO", "vendorId":"AP", "name":"Main Mojo Tariffa" } 13
EMIS Web Service for Remote Readings and Bills 3.6.3.1.5 Object “meter” Meter Properties Name Type Info Description id Text Primary Key, Mandatory Data Supplier’s Metering point ID serialNumber Text Mandatory, Updateable Meter serial number description Text Mandatory, Updateable Meter description address Complex Mandatory, Updateable Meter address buildingName Text Mandatory, Updateable Facility name ownerName Text Mandatory, Updateable Owner name ownerExternalId Text Mandatory, Updateable Owner’s Tax ID (OIB) Important note for suppliers in Croatia: This field must contain OIB! energyCarrierId Text Mandatory Data Supplier’s Energy Carrier ID unregisterDate Date YYYY-MM-DD Date since DataSupplier is no longer obliged to send bills Only for unregistering 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 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 XML {
EMIS Web Service for Remote Readings and Bills "buildingName" : "Headquarters", "ownerName" : "Dr. Evil", "energyCarrierId" : "MOJO" } 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 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 Optional Bill entries Complex “BillData” 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 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”. 15
EMIS Web Service for Remote Readings and Bills Bill Example (Fragment) JSON XML { "serialNumber" : "AP-2016-0002", "billData" : [{ "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, } ] } Bill Example – Successful (complete) JSON Request JSON Response POST http:///batch/json/send { "status" : 200, Request Headers: "statusDesc" : "OK", Content-Type: application/json "ts" : "2016-09-14T10:34:13.296", X-Ekonerg-Login: test "serviceURL" : "http:///batch/json/send ", X-Ekonerg-MAC: yoHi5qZsqfPM0pkmKiudSIIsXTVFaYT/cdsZ/ZK0S2I= "succeeded" : { Content-Length: 886 "ts" : "2016-09-14T10:34:13.308", Host: "insert" : { "bills" : [{ { "id" : "INT-0001", "insert" : { "ts" : "2016-09-14T10:34:13.308" "bills" : [{ } "id" : "INT-0001", ] "serialNumber" : "AP-2015-0001", } "total" : 1234.56, } "month" : 1, "dataSupplierId" : "test" "year" : 2015, "dataSupplierLogin" : "test" "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 } 16
EMIS Web Service for Remote Readings and Bills ] } ] } } XML Request XML Response POST http:///batch/xml/send Content-Type: application/xml X-Ekonerg-Login: test X-Ekonerg-MAC: yoHi5qZsqfPM0pkmKiudSIIsXTVFaYT/cdsZ/ZK0S2I= Content-Length: 736 Host: 17
EMIS Web Service for Remote Readings and Bills 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:///batch/json/send { "status" : 200, Request Headers: "statusDesc" : "OK", Connection: keep-alive "ts" : "2016-09-14T12:21:08.403", Content-Type: application/json "failed" : { X-Ekonerg-Login: test "ts" : "2016-09-14T12:21:08.420", X-Ekonerg-MAC: yoHi5qZsqfPM0pkmKiudSIIsXTVFaYT/cdsZ/ZK0S2I= "serviceURL" : "http:///batch/json/send ", Content-Length: 887 "insert" : { Host: "bills" : [{ User-Agent: Apache-HttpClient/4.2.6 (java 1.5) "id" : "INT-0001", "serialNumber" : "AP-2015-0001", { "year" : 2015, "insert" : { "month" : 1, "bills" : [{ "billData" : [{ "id" : "INT-0001", "ts" : "2016-09-14T12:21:08.419", "serialNumber" : "AP-2015-0001", "err" : "ForeignKeyException", "total" : 1234.56, "errDesc" : "PreparedStatementCallback; SQL [call "month" : 1, REMOTEBILLS_BACK.BILL_SEND_FIELD(?,?,?,?,?,?,?,?,?,?,?,?,?)]; ORA-02291: integrity "year" : 2015, constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not "billData" : [{ found\nORA-06512: at \"EMIS.REMOTEBILLS_BACK\", line 298\n; nested exception is "energyCarrierId" : "MOJO", java.sql.SQLIntegrityConstraintViolationException: ORA-02291: integrity constraint "meterId" : "METER1", (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not found\nORA- "vendorId" : "AP", 06512: at \"EMIS.REMOTEBILLS_BACK\", line 298\n", "tariffId" : "MOJO_MAIN", "energyCarrierId" : "MOJO", "dateFrom" : "2015-01-01", "meterId" : "METER2x", "dateTo" : "2015-02-01", "vendorId" : "AP", "energyCarrierFieldId" : "HOT", "tariffId" : "MOJO_MAIN", "quantity" : 10.0, "dateFrom" : "2015-01-01", "unitCost" : 123.0, "dateTo" : "2015-02-01", "taxPercentage" : 25.0 "energyCarrierFieldId" : "COOL", }, { "quantity" : 100.0, "energyCarrierId" : "MOJO", "unitCost" : 95.0, "meterId" : "METER2x", "taxPercentage" : 25.0 "vendorId" : "AP", } "tariffId" : "MOJO_MAIN", ], "dateFrom" : "2015-01-01", "err" : "ForeignKeyException", "dateTo" : "2015-02-01", "errDesc" : "PreparedStatementCallback; SQL [call "energyCarrierFieldId" : "COOL", REMOTEBILLS_BACK.BILL_SEND_FIELD(?,?,?,?,?,?,?,?,?,?,?,?,?)]; ORA-02291: integrity "quantity" : 100.0, constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key not "unitCost" : 95.0, found\nORA-06512: at \"EMIS.REMOTEBILLS_BACK\", line 298\n; nested exception is "taxPercentage" : 25.0 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:///batch/xml/send Connection: keep-alive Content-Type: application/xml X-Ekonerg-Login: test
EMIS Web Service for Remote Readings and Bills integrity constraint (EMIS.TREMOTE_ADV_BILLDATA_MTR_FK) violated - parent key
EMIS Web Service for Remote Readings and Bills 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 Name Type Info Description 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 Date when this device was removed from unregistering metering location meterDeviceCounter meterDeviceCounter Array, Optional Optionally a list of metering devices if you want to include them in meterDevice object ignoreExisting Boolean Optional (“true” or If true, no exception will be thrown when “false”, omitted -> “false”) 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. Meter Device Counter Properties Name Type Info Description meterDeviceId Text Primary Key, Mandatory Data Supplier’s Meter Device ID (can be omitted if specified under meterDevice object) 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. ignoreExisting Boolean Optional (“true” or “false”, If true, no exception will be thrown when inserting an omitted -> “false”) 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. 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 {
EMIS Web Service for Remote Readings and Bills "meterDevice": [{ id="EE790" "id": "EE790", meterId="2" "meterId": "2", serialNumber="782364" "serialNumber": "782364", dateInstalled="2012-05-09T17:45:00" "dateInstalled": "2012-05-09T17:45:00", dateRemoved="2018-05-17T18:05:00" /> "dateRemoved": "2018-05-17T18:05:00" "meterDeviceId": "EE790", "meterDeviceId": "EE790", "energyCounterId": "E2", "correctionFactor": "1.004" } ] } JSON XML { "dateRemoved": "2018-05-17T18:05:00", "meterDeviceCounter": [{ "energyCounterId": "E1", "correctionFactor": "1.004" }, { "energyCounterId": "E2", "correctionFactor": "1.004" } ] } ] } 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 Name Type Info Description 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 } 21
EMIS Web Service for Remote Readings and Bills 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 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 (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:///batch/json/send { "status" : 200, Request Headers: "statusDesc" : "OK", Connection: keep-alive "ts" : "2016-09-14T14:42:00.601", Content-Type: application/json "serviceURL" : "http:///batch/json/send ", X-Ekonerg-Login: ARSEN "succeeded" : { X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= "ts" : "2016-09-14T14:42:00.675", 22
EMIS Web Service for Remote Readings and Bills Content-Length: 260 "insert" : { Host: "readings" : [{ User-Agent: Apache-HttpClient/4.2.6 (java 1.5) "ts" : "2016-09-14T14:42:00.649", "id" : "200271268", { "internalId" : "19625" "insert" : { }, { "readings" : [{ "ts" : "2016-09-14T14:42:00.674", "meterId" : "2186653", "id" : "200271269", "date" : "2016-01-15T02:02:00", "meterId" : "2186653", "c1" : "209002", "date" : "2016-01-15T02:03:00" "internalId" : "19625" } }, ] { } "meterId" : "2186653", } "date" : "2016-01-15T02:03:00", "dataSupplierId" : "test" "c1" : "209003" "dataSupplierLogin" : "test" } } ] } } XML Request XML Response POST http:///batch/xml/send Connection: keep-alive Content-Type: application/xml X-Ekonerg-Login: ARSEN X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= Host: User-Agent: Apache-HttpClient/4.2.6 (java 1.5) Reading Example (partially successful) JSON Request JSON Response POST http:///batch/json/send { "status" : 200, Request Headers: "statusDesc" : "OK", Connection: keep-alive "ts" : "2016-09-14T14:54:23.123", Content-Type: application/json "serviceURL" : "http:///batch/json/send ", X-Ekonerg-Login: ARSEN "succeeded" : { X-Ekonerg-MAC: SJdtDN3ZiY5AUl5ub74CR2GntrdJg1p7F1UKcQ2ktu8= "ts" : "2016-09-14T14:54:23.285", Content-Length: 260 "insert" : { Host: "readings" : [{ User-Agent: Apache-HttpClient/4.2.6 (java 1.5) "ts" : "2016-09-14T14:54:23.165", "id" : "200271270", { "internalId" : "19631" "insert" : { } "readings" : [{ ] "meterId" : "2186653", } "date" : "2016-01-15T02:04:00", }, "c1" : "209004", "failed" : { "internalId" : "19631" "ts" : "2016-09-14T14:54:23.285", }, "insert" : { { "readings" : [{ "meterId" : "2186653", "ts" : "2016-09-14T14:54:23.283", "date" : "2016-01-15T02:03:00", "err" : "BusinessException", "c1" : "209005" "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 } ] } 23
You can also read