FD1 Concepts

Resources

Fieldpine FD1 talks of "resources". A resource is a "thing" such as a product record. Depending on your background, you might also consider these to be "entities", "objects", "nodes" or rows in a spreadsheet.

A resource has attributes or fields. Some attributes are direct, such as product name. Other attributes may serve as a link (relationship / pointer / refercence / edge ) to another resource.

Product Name: Paper Price: 7.99 Id: 923 Last Supplier: 415

Last Supplier links to

Supplier Name: Ace Paper Supply Id: 415, Phone: ....

Endpoints

An endpoint is a piece of code that does something. Most often you call an endpoint to read or write resources. (ie fetch details of product #923). However endpoints can also trigger actions. (ie Email receipt for sale #12345 to anatasia@example.com )

Techncially speaking, an endpoint is the top level access. Endpoints can invoke handlers to perform the task for them

Tabs

When using a websocket, multiple different "tabs" (think browser tabs) can share one websocket. The "tab" field (technically, "rt" field) is sent in each message to identify which tab/channel this message relates too.

Log

A log message as used in Log means a message that is primarily a trace or support style message. Think "console.log" in Javascript. Clients send these messages to Fieldpine and we store them for a period of time. Log messages are NOT state changing, so can be freely discarded, however they are incredibly helpful for support purposes.

Log Messages are loosely defined and you are free to store whatever is relevant

Fact

A fact message is something that happened and may affect state in either client applications or Fieldpine itself. A "fact" is logically between a "log" and a high level function "edit product #9"

Facts are stored in areas and some areas affect Fieldpine state (much like a standard REST call)

Facts are reasonably defined, but are not totally rigid. In many cases you can extend what you send.

Handler

A Handler is the piece of code/logic within Fieldpine that actually does what you want. While a HTTP request invokes a (top level) endpoint/handler, that handler can call numerous other handlers too. Handlers can be either Fieldpine provided, or overriden by customer scripts (server side)

For example, you might call /fd1/customer/customer_details?city=lisboa.
On the server:

• A top level "customer details" handler is invoked. Top level handlers are always Fieldpine provided
• This handler fires the "event" - "customer details pre" to let sites filter every inbound request if they wish.
• A cursor is setup and all customers with city=lisboa are retrived
• In a loop, an "event" is fired for each candidte result row "customer details access check". This (site specific) handler may chose to hide certain results, or take other actions
• etc

Defer

You may see references to a "defer" in the documentation. This is a request that has been placed in a queue for processing, ie deferred until we can do it.

Many functions requested are required "now", but do not need to be done while you are waiting. For example, sending a customer an email with a receipt - your API call is "please send customer XYZ an email receipt for sale #123". Fieldpine will typically create a "defer" for this and return to you before the defer is completed. Using a defer is simply moving it to background async threads, it does not imply delay necessarily. Defer is largely an internal implementation detail.

Defers are also created when you request a function and the responding server cannot perform that action and must refer to an authoritive server. Fieldpine is a distributed system, so requests such as "please delete customer NNN" must be routed to HO systems, and not executed by branch servers.