Skip to main content

Let Users Edit Business Documents with Context-Bound References

· 3 min read
TeaQL Team
TeaQL Team
Core Team

An order-editing page may show an order and several lines. The user changes a quantity, removes one line, and clicks Save. The server must distinguish that intent from a missing row that was never loaded, an old version of the order, or a row reference copied from another user's page.

TeaQL's optional Secure Document Reference module makes that round trip explicit. Here, a document is an editable view of a business object graph; it does not mean a PDF or Word file. The application opens a document for a particular actor and purpose, sends its editable body and opaque credentials to the client, and accepts a returned edit only within that document's scope.

Why use it​

A normal JSON form is easy to display, but it does not explain which rows were issued, which fields were editable, or which version the user saw. A secure document carries a protected snapshot alongside the body. On submission, the application can validate the actor, purpose, allowed rows and fields, current authorization, and versions before applying an audited business mutation.

This suits order editors, approval screens, case-management forms, and other workflows where a client edits part of a larger graph. The module can be used without Blob Reference when there are no file fields.

The user journey​

  1. Open the editor. The server authenticates the user, loads the authorized business graph, and opens a document for a named purpose such as edit-order. The response contains display fields, writable fields, opaque row references, and document credentials with a limited lifetime.
  2. Edit the body. The client changes the fields the view offered. It keeps the document credentials with that edit. A row reference is only meaningful inside this document; the client does not need database IDs.
  3. Submit once. The client sends the edited body, credentials, and a command ID. The server checks the protected snapshot and current permissions, verifies versions, and saves the accepted changes in a business transaction. A stale or out-of-scope edit is rejected instead of being guessed into a mutation.
  4. Show the result. The server prepares the accepted document for display and can issue fresh credentials for the next edit.

For an order, the client-facing edit can stay small:

{
  "orderNumber": "ORDER-1042",
  "items": [
    {"ref": "opaque-row-reference", "sku": "CUP-1", "quantity": 5}
  ]
}

The protected document credentials accompany this body; the ref is not a database ID or a reusable authorization token. The application decides what an omitted or removed row means based on the issued snapshot. A field that was never loaded is not silently treated as a request to clear it.

The Secure Document Reference guide shows how to define the editable scope, open a document, accept an edit, and prepare the result. If the editor also has attachment fields, add Blob Reference so file selections are validated and saved through the normal Blob binding path.

This describes the source implementation being prepared for release. Check Latest Versions before selecting an installable package.