Developers
 
Library Developer Home Web Appearance Customising Reports APIs Primitives OpenAPI eLink O3 DataRead Realtime SSE Levels Online Services xyz.online.fielpine.com Zone Stock Levels
Worked Examples Customer Signup Detailed Guides Login Pages Tips & Tricks Database Override POS UI Cheatsheet

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

TypeUse For
Usage Charging Suited for
  • Devices/Systems that generate charging records (meters, printers, photocopiers, entry sensors, software applications)
  • Long term automatic recurrent billing (rental payments, contract invoicing)
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

FieldNameContentNotes
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
DeviceIdUnique device identifierA 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=6789
This 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.

Recording Usage Records (via automated recurring instructions)