Library
Usage Charging
Usage charging within Fieldpine allows you to receive automated feeds (either directly via API calls, or Excel spreadsheets containing usage information) and have Fieldpine record this and schedule sale creation/invoicing.
This is used whenever you have repeated charges arising from use of something or elapsed time.
For documentation purposes, this page will use a "water meter" as a device that generates automatic API calls, and a "photocopier" as a example where a monthly summary is received as an Excel spreadsheet. Fieldpine Charging is also implemented using Usage Charging.
Usage Data records "what" happened of interest for charging. A later process collects usage records and creates invoices
Receiving Use Data
The general expectation of usage charging is that a "device" generates "use data" at periodic or random intervals. This "use data" is then collected and processed as a second task (weekly, monthly, etc) to create the customer charging information.
Our water meter might send automatic records every hour containing the meter number and total litres.
Alternatives to Usage Charging
Usage charging is quite flexible and can appear to solve many retail situations, however it might not always be the best choice
| Type | Use For |
| Usage Charging |
Suited for
|
| Standing Order | A standing order is an instruction to automatically repeat a sale every so often. For example "2 dozen eggs and 6Kg of flour every friday" Standing orders are less rigid than usage charging in that you can pause/skip, as they are manually processed while usage charging is largely automatic. |
Use Data
The following fields are available in a usage record
| FieldName | Content | Notes |
| Data Record Classification | ||
| eGroup | Event group |
A broad classification of what general sort of data this record relates too.
Must start with a letter (A-Z) Values starting with a number are reserved to Fieldpine Our water meter might put "WM-ACME5" to indicate these records are from an "ACME-5" Water Meter. |
| eId | Event Id |
Exact record type being sent. Our water meter might send a "Type-1" record every 30 minutes with volume data, and might send a "Type-2" record occasionally to indicate min/max pressures. |
| Dtu | Date/time (UTC) | UTC Date/time the use was recorded. This value is automatically created by the server if not explicitly provided |
| Device and Instance Identifiers | ||
| DeviceId | Unique device identifier | A unique indentifier for the individual device. |
| Dt | Date/time (local) | Date/time of the use. This time is optionally supplied by the device if it can. |
| EventRef Ref |
Reference # | A unique value that identifies this specific usage event record. If provided, must be unque for a given (deviceid + gGroup + eId). Where eventref are sent, this means a sender can safely repeat sending the same record as only the first record received will be used. |
| Data being recorded | ||
| IntCounter Int |
integer (64bit) counter | Simple counter or integer value. For example kilometers, #pages, occurrences |
| Temperature | Temperature. Units are not defined (C, F, K) and are implied from the device. This value may be the actual value being recorded for charging or it may be a reference value - liquids are typically measured at specific temperatures to cater their volume change by temperature | |
| EventDataJ | Custom JSON data | Holds a JSON record with additional per device values. This permits storage of other attributes that do not cleanly fit into existing fields. |
Recording Usage Records (via API)
Quick Start
Browse to the URL
/OpenApi/UsageRecord/test/1/mydevice?ref=firsttry&intcounter=6789This will create the device "mydevice" and record the value "6789" for a with a reference of "firsttry". Once recorded subsequent uses of this url with the same reference (firsttry) will return success status but not save any additional values.
You can use GET, PUT, POST requests to store data. You can also configure different URLs and implement security - neither of which is documented here
Recording Usage Records (via Excel Spreadsheet load)
Usage data can be uploaded using Excel. Create a spreadsheet with the following structure. The order of the columns is not important. You can omit columns you are not using
| DeviceId | eGroup | eId | Dtu | DtDevice | SrcIp | EventRef | IntCounter | IntCounter2 | IntCounter3 | IntCounter4 | IntCounter5 | Temperature | EventDataJ |
| myDevice1 | 12-jun-2021 14:31 | tick-1718273 | 301 | ||||||||||
| myDevice1 | 12-jun-2021 15:01 | tick-1718274 | 305 | ||||||||||
| XY876 | 12-jun-2022 15:22 | 12-jun-2021 17:22 | 10.50.190.201 | BS-1792(Alpha) ICS.14 | 82885 | 9182727 | 2307 | 56 |
In this table, the cells are color coded to mean
- A field that is required.
- A field that can optionally contain data if provided by the source device. These are essentially the "data values" you are loading
- A field that can be loaded, but isn't typically loaded
- A field which would be rare to be loaded via Excel. It is valid to load them if needed.