Skip to main content

Attach Files to Business Records with Blob References

· 3 min read
TeaQL Team
TeaQL Team
Core Team

A support agent attaches a PDF to a case. The case may stay open for months, while a download link should last only minutes. If the case stores that link, the attachment appears broken when it expires. If the case stores a raw storage key and treats it as permission, anyone who obtains the key may get more access than intended.

TeaQL's optional Blob Reference module gives the case a stable BlobRef. The file lives in object storage; the business record keeps only its reference. When someone is allowed to view the case, TeaQL prepares a complete temporary URL for that reader. The next view can receive a fresh URL without changing the case or uploading the file again.

Where it fits​

Use Blob References for attachments on cases, invoices, product images, or other business records whose files outlive a single download link. The module also handles replacing and clearing a file field, so the attachment follows the business transaction. A failed case save does not leave a new binding on the case; a file still referenced elsewhere is protected from cleanup.

The module is independent of Secure Document Reference. A simple application that lets authorized users upload and download files can use Blob Reference on its own.

The user journey​

Suppose a case has a document field that accepts PDFs:

  1. Choose a file. The application starts an upload for the document field. The module checks the configured field policy and upload permission, then accepts and verifies the file through the chosen storage provider.
  2. Save the case. The application receives a pending file selection and saves its stable BlobRef with the case. TeaQL binds the reference as part of the business save. The case does not persist a URL or file bytes.
  3. Open the case. The application loads the case and prepares its view for the current user. TeaQL checks read permission and asks storage for a complete signed URL with an expiry. The UI uses that URL for the download button; it does not write the URL back to document.
  4. Replace or remove it. Upload a replacement and save the new reference, or clear the field through a normal authorized mutation. Retention and cleanup can then deal with unbound files without deleting those still in use.

For example, a case API can return the stable business fields and a prepared download link together:

{
  "caseNumber": "CASE-1042",
  "document": {
    "url": "https://storage.example.test/temporary-download?...",
    "expiresAt": "2026-10-31T10:15:00Z",
    "fileName": "case.pdf",
    "contentType": "application/pdf",
    "sizeBytes": 12480
  }
}

The URL above illustrates a prepared response, not the value saved in the case. The response can be configured to return a URL alone or file metadata with that URL; signing and expiry come from the storage provider. A signed URL is a bearer credential until it expires; if every individual download must recheck identity, choose a provider or gateway with that policy.

The Blob Reference guide walks through model configuration, module setup, upload, save, view preparation, and replacement.

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