Library Developer Home FD1 Client Protocol Home Concepts Reading Data Writing Data Protocol Defined Servers Connect & Authenticate Proxies & Tunnels
Webhooks & Firehoses Programming Support Logging Minor Facts State Facts Response Format How To Guides eCommerce Sites Custom Point of Sale Customer Access Bulk Downloads Major APIs / Endpoints All Endpoints Products Sales SalesBuilder Session Get Attribute Sale Capture General Purpose Data Capture Devices Barcode Scanners Eftpos IoT Sensors Power Outlets Printing Scales Security Cameras Purchasing / Supply Side Purchase Orders Invoices Invoice Payments Document Capture Rare APIs / Endpoints SSL Certificates API Key Management Diagnositics PosGreen Server to Client Messages Overview Resources / Objects Purchase Order Invoice Payable Invoice Payment Product Supplier Location Sale Lines Sale Delivery Details Sales Price Maps Employees Carriers Payments Product Kits Department 1 Customers

FD1 Write Concepts

A write, including create, update and delete, are all implmented by sending a JSON packet. As FD1 is primarily designed for websockets, the HTTP verbs are not used as there is no HTTP verb inside websockets.

The following are all broadly the same as far as Fieldpine servers are concerned. All update the comments field on a single purchase order. The difference is how the record to edit is identified.

POST /fd1/purchaseorders/edit_purchaseorder_header
{
  "a": "purchaseorders.edit_purchaseorder_header",
  "k": "KAJDID38THGD357RHGH3G586YFGGIF",
  "v": {
    "comments": "My first edit"
  }
}

This version uses the "k" (key) field to provide the direct internal record key. This is the most robust way of issuing a request and is multi server safe.

POST /fd1/purchaseorders/edit_purchaseorder_header
{
  "a": "purchaseorders.edit_purchaseorder_header",
  "q": {
    "cust_ponum": "X12345"
  },
  "v": {
     "comments": "My first edit"
  }
}

This version uses the "q" (query) field to select the record. In this case we are selecting the purchase order with the number "X12345". If using "q", you are responsible for ensuring the corret row is selected - in this case "cust_ponum" is human entered, so duplicates could potentially exist.

POST /fd1/purchaseorders/edit_purchaseorder_header
{
  "a": "purchaseorders.edit_purchaseorder_header",
  "k": 928344,
  "v": {
    "comments": "My first edit"
  }
}

This version also uses the "k" (key) field, but in this case is using the local key. This is not safe if you are using multiple servers, as, for purchase orders, integer keys are server specific.

All writes use the following top level field names

Field name	Description	Required
a	Address of the endpoint to run this request	Mandatory
k	The primary key of the record to alter. The exact value for "k" depends on the endpoint being used	Recommended
q	A query struture to select the record of interest. Details of "q" contents are outlined in Reading Data	Either k or q is required
v	The values you wish to write	Mandatory
rq	Your request identifier. If present will be returned in the response packet	Optional

"v" object definition

The v object contains each field and it's value to be written.

v: { fieldname: "string" }

If the value of a field is a string, this value is written to the field

v: { fieldname: number }

If the value of a field is a number, this value is written to the field

v: { fieldname: bool }

If the value of a field is a true/false boolean value, the field is set to 1 (true) or 0 (false)

v: { fieldname: null }

If the fieldname is an explicit null, the field will usually be set to 0 or empty string. Very few fields in Fieldpine can be explicitly set to null, and you should consider setting a field to null as an error.

v: { fieldname: { ... object ... } }

If the field definition is an object, then the object contains additional processing commands. This is used for conditional updates, delta values and other non scalar operations. These details are not yet documented.

If however you are trying to store an object into a field (ie the field contains a JSON object), then stringify the value before sending.

let myObj = {
  x: 12,
  name: "Bob"
}

Send to FD1  - row.jdata to object value
v: {
  key: 16,
  jdata: JSON.stringify(myObj),
}

The resulting database will contain

Key	jdata
16	{"x":12,"name":"Bob"}

Create, Edit, Delete

The selection of create, edit or delete is given by the "a" end-point name. REST developers may be used to POST, PUT, PATCH and DELETE verbs, but as this is a websocket protocol, verbs are not present.