Fieldpine systems offer a number of interface techniques for interfacing alternative systems to
meet the differing requirements of interfaces
Command Line Interfaces
Mesh Utility
The Mesh command line utility provides a simple but powerful way to read, write and monitor your system.
Programatic Interfaces
For interfaces used by applications and external systems the following methods are most commonly used.
Generic eCommerce
This API provides a simple generic method to interface websites that need access to a limited set of information, such
as the ability to read products and upload sales.
RetailAPI
The RetailApi is a RESTful like API that permits controlled read and write access to logical components in the
retail system. This api is available on both internal network channels and public internet channels (if enabled). It supplies
a restricted set of information when operating on the internet. This API is primarily used by systems with small needs
such as phone apps and simple web pages.
eLink API
The recommended protocol for high functionality interfacing is called 'eLink' which allows full read and write access to all logical components in the
retail system. This interface is used by Fieldpine application itself and all web reports and management screens are using eLink.
As a protocol, eLink defines the message packets (read a product, change a customers phone number, etc) but you can transport these messages
however you wish. Web browsers typically use HTTP direct to the server, but you can also email them to the server (if configured and enabled)
or place them in flat files for bulk loading. When using eLink as a web api you can use either XML or JSON, with a few rare exceptions
eLink operates at the logical data level, meaning you get information about a "product" or "sale", but the exact details of where and how
this is stored is left to the Fieldpine application
WebAPI
The WebApi is a technical interface to instore trading lanes. It is not for external interfacing and provides a way to connect
instore devices and other programs to active trading lanes. For example, Customer Displays using browsers use this API to retrieve
active sale details to display to the customer.
Mesh Application
PRELIMINARY Subject to change
Mesh applications are programs or dlls you can create to interact with the Fieldpine system via supported APIs. The applications load a
Fieldpine interface DLL to gain read and write access to the servers. These applications are implicitly mesh aware and can run in both online and
offline mode.
Mesh applications work at logical business level the same as the eLink API above.
Direct Database
You can interface directly at the database layer, however for writing this is strongly discouraged as the Fieldpine application may not be
able to detect
changes to the physical data. Direct database is acceptable for introductory reporting however. The main issue with accessing the database
directly is that
the database schema is not fully publically documented and is subject to change without notice. The eLink API provides a constant definition
and does not change over time.
Direct database operates at the physical data level.
DLL
Advanced users can create DLLs to interact directly with the system at either the lane level or backoffice level. These DLLs use
the same technique as "Mesh Applications" and work by loading a DLL to communicate to Fieldpine. DLLs can also
take part in the actual sale process or provide additional device interfaces to the Point Of Sale.
Specific Interfaces
The Fieldpine system also includes a number of built in interfaces to different systems
This page outlines a number of typical interface examples and how they are best solved.
Interfacing an eCommerce Website
Use the "Generic eCommerce" interface. If you out grow this interface then changing to a full eLink interface is not difficult
as the generic ecommerce interface is a subset of eLink.
Extract to Accounting System
The major deciding factor for selecting this type of interface is what toolsets you are
most used to and what options the accounting system provides. The following table summarises
the differences
| Requirement | eLink API | Database |
| How to read sales |
Open the API and read from retailmax.elink.sales.XYZ bucket endpoints.
This can be done using common utilities such as wget or embedded in your own
program.
Works easily from different networked machines
API provides a feed clean from irrelevant sales |
Open the database directly and run a query over sales, salelines and payments tables.
Typically needs ODBC connection defined
Program needs to clean from raw data feed
|
| How do I mark sales as "extracted"? (See note 1 below) |
Use the API and send "edit" commands to mark individual records
or, Use one of the endpoints that both creates a file and updates the database in one operation
|
Extract program directly updates record in database with "extracted". This can either be one of the pre reserved fields
for this purpose or a custom field
|
| What if I want a real-time feed so sales are "posted" instantly? |
Both the eLink and database interfaces would require the use of polling to detect
new sales, and both would cause about the same amount of load on the system each time
it is polled. Please contact Fieldpine if you require a high performance non polled technique |
Notes:
- There are two major ways of extracting sales. One system uses a flag in the POS system to say
"extracted", and then queries only request records that aren't flagged extracted. The other technique
extracts all records over a wide time period and then checks each entry to see if it is already posted
to secondary systems.
The first technique reduces the load on the target system, but adds a slight timing issue where
data might be inserted in the target system but the flag doesnt get set.
The second technique is more reliable, but does require more support from the target system to support
either blocking or rapid checking.
Import From Accounting System
To load data into the system, it must be processed via Fieldpine to ensure logical integrity. There are a few options
- Load the complete CSV or XLSX file directly. Files must be in a layout or structure that can be understood, typically
one record per line, and column headings describing that is being loaded
- You can individually post records via the API calls to edit products, customers, acounts etc.
- For common concepts, such as products, you may directly write to a special loading table, and trigger the POS to read and
process each row.
Interfacing a Custom Device
Custom devices allow you to extend the POS by creating your own interfaces to devices and
talking to the Point of Sale as events happen.
You can create both event creating devices, (barcode scanner or door entry counter) or
driven devices (cameras that take photos on demand, payment interfaces)
There are two main options, the talk_to_fieldpine DLL technique if your interface is going to be running even when Fieldpine POS is not
and you want a low level interface. Alternatively, the WebApi for connecting to Windows PosGreen lanes
using HTTP.
Visit the
talk_to_fieldpine.htm homepage for:
- Full API details
- Programming guides
- SDK
Details about the Mesh Application Interface.
Mesh Application Interface
A Mesh application is a program or dll you write that is able to access Fieldpine as a full service client. As a mesh program
it is free to run standalone and be authenticated using non interactive means. Mesh programs are primarily used where:
- You want the ability to run offline, or when servers are unavailable.
- Your security environment is complex and opening network connections to servers is not always possible
- You require non interactive authentication
- You are providing functions to extend the Fieldpine system, and Fieldpine will be initiating the call to you.
- You are wanting to influence and control how sales are processed in real time. A common use would be to provide
support for highly complex pricing situations
Overview
- Your code starts and loads talk_to_fieldpine.dll. This dll provides all the APIs you need to communicate to Fieldpine.
- Your code identifies itself to the dll, providing name, purpose, version and details of which Retail System it is to communicate too.
- You can now freely call the APIs to read and write retail data.
- Your code can reside on different machines to the POS. A single program can receive requests
for different POS lanes and web browsers if it wishes.
| POS |
«-- | --»
Process Seperation |
| Talk_to_Fieldpine.dll |
«-- | --»
API Interface |
Your program logic |
|
The POS usually runs programs using this interface in a seperate process for security and reliability reasons
(The POS can autostart your programs,
no manual action is required). The talk_to_fieldpine.dll takes care of the communication between your program
and the POS, including handling POS restarting. Your program logic receives "packets" of information from the POS
which you can respond too. You can also generate "packets" for the POS to react too.
There are open source examples of how this interface can be used. These are provided in C++
and you can download a free C++ compiler from Microsoft. You do not need to use C++, you can
use any language that is capable of loading a DLL at runtime and calling functions inside it.
We are investigating using WebAssembly in the future too.
Types of Interfaces
- Device interfaces. Your program can provide device support, connecting scanners, scales, weigh bridges, cameras or
many other devices.
- Event Handlers. Your program can be called by the POS as part of sale processing to control how the sales are processed.
Details about the RetailAPI Interface.
RetailAPI Interface
The RetailAPI interface is designed with simplicity of use in mind. It is designed to be consumed by
web based apps (or programs using HTTP transport) using internet connected hosts. Retailers who are hosted
behind firewalls are able to configure the RetailAPI to use Fieldpine servers and delegate authority to them, rather than
opening firewalls and self managing everything.
- Data is controlled by API Key. You can configure some users to see more or less depending on who they are
- Security and velocity controls. Fieldpine servers manage access, allowing you to release even highly sensible
material if you wish.
- JSON default response format, but can also be XML, CSV or even XLSX in some cases
- RetailAPI is an additional option and charged based on volume of use.
Further reading:
Retail API Developer Information
When to use RetailAPI
RetailAPI is intended to be used when you need access to your retail data from the internet or other
web services, but do not want to open and manage your firewall
- Use a web page to capture sales at low volume remote stores or agencies, or while on the road.
- Allow an eCommerce website to perform realtime prepay and loyalty verification and charging. If you are using
stored value cards (aka, Gift cards or Prepay cards), you can allow shoppers to enter their card numbers online
without needing to publish the complete list of cards, balances and passwords. It is also updated into your trading system
rapidly, reducing fraud potential.
- Allow customers or suppliers to see the details you hold about them, enter changes and review their transaction history.
Examples
Return details on product with Id#4.
GET /RetailAPI,1,2,3,4/database/products/Pid/4
Return details on all active products.
GET /RetailAPI,1,2,3,4/database/products
Return details on products with 'maxi' present in any text field. Return a maximum of 82 rows.
GET /RetailAPI,1,2,3,4/database/products?limit=82&search=maxi
Return details on location/store with Id#21.
GET /RetailAPI,1,2,3,4/database/locations/Locid/21
Mesh Command Line Interface
The command line utility allows you to read and write from your mesh storage. It allows a simple interface for scripting languages that
cannot easily use TCP protocols. Many mesh command line options have equivalents in the eLink API but the mesh command line saves you
from having to know which IP address is the server.
To use the mesh utility, you need
- The mesh.exe utility
- An authorisation key to connect to the database. Some operations do not require a key
With these two items, you can run the mesh utility anywhere that has a suitable network connection, the utility will "find" the correct and latest
path to your data, whether this is on the local network, on a remote store or on a public cloud.
The mesh command line can also be invoked from node.js (on Windows)
Some examples of use
mesh fetch products to abc.xlsx
Read the current set of products and write them to abc.xlsx
This command will try and source the data from the closest machine capable of supplying it. You can override this behaviour
by specifying /cloud (fetch directly from public cloud) or /nas (read from NAS device) or options to specify the exact server
mesh write products from abc.xlsx
Update the current products from the records in abc.xlsx This command may require a username/password
mesh write products from sqldb /server=10.50.200.100
Update the current products Using the database on the server 10.50.200.100 This command might be used after you have externally
changed products directly in the database and wish to ensure these are reflected to all systems.
mesh transactions fetch product.edit [pid=55] to abc.txt
Request all recorded transactions, ie the complete history, for pid#55 to abc.txt
mesh postrace monitor /srcuid=1234
Connect to the licensed machine number 1234 and display all trace lines being generated
mesh clone sqldb to abc.mdb /srcuid=1234
Connect to the licensed machine number 1234 and clone the current database in use to a local database called abc.mdb
mesh clone sqldb to "ODBC;dsn=xyz" /srcuid=1234
Connect to the licensed machine number 1234 and clone the current database in use to a local dsn connection called "xyz"
mesh discover monitor
Listen to the network and report any discovery protocol messages seen. The discovery protocol is used to find nodes in the network.
This command can be useful to verify the network is operating correctly
