Add a Contract and Cover Image to a TeaQL Asset
A supplier asset needs a PDF contract and a PNG cover. The user uploads both, saves the asset, and later opens either file. When the contract changes, replacing it should leave the cover alone. When the cover is removed, the contract should still download.
That is the example behind our new Blob attachment guide. It uses the Java source preview of the optional Blob module. You can download and run the complete example against PostgreSQL and local File storage, then follow its upload, save, read, replace, and clear operations in order.
Give each attachment a field
An object can have several Blob fields, each with its own allowed formats. The modeling declaration for this example is:
<asset title="string()"
contract="contract.pdf"
cover="cover.png"/>
Each field refers to one file. contract="contract.pdf|contract.docx" would allow
one PDF or one DOCX in that field. If a user can add an arbitrary number of
attachments, use a child collection with one Blob field per attachment row.
The downloadable example declares the corresponding runtime metadata explicitly, so you can try the file workflow without generating an application first. The guide distinguishes that executable example from the KSML modeling illustration.
Upload first, then save the asset
An application upload endpoint calls the Blob service's begin, write, and
complete operations. Completion verifies the actual file and returns a stable
BlobRef. The guide's helper closes its input stream and wraps those three calls:
BlobRef contract = upload(ctx, "contract", "contract.pdf", pdf, "contract-upload-1");
BlobRef cover = upload(ctx, "cover", "cover.png", png, "cover-upload-1");
upload is application code provided in the guide, not an extra SDK method.
The resulting references become ordinary business field values:
asset.updateProperty("contract", contract);
asset.updateProperty("cover", cover);
asset.setComment("Attach supplier contract and cover");
runtime.saveGraph(ctx, asset);
The database stores stable Keys. The Blob module checks the bindings inside the business transaction. An upload can finish before the user saves; if the user abandons the form, the unbound file follows the configured retention policy. Business code does not manually maintain a second binding table.
Prepare the response when the transaction finishes
After a successful commit:
PreparedView prepared = runtime.prepareView(
ctx, Map.of("data", asset), ViewOptions.afterCommit());
The response contains a temporary URL for each visible, loaded attachment field. The entity and database retain the stable Keys. Your response adapter serializes the prepared value and applies its private cache and expiry constraints; your business code does not assemble a storage hostname or signature.
For a later read, load the required fields and prepare with
ViewOptions.readOnly(). If a download URL expires, obtain a new authorized view.
The file does not need to be uploaded again.
Replace one file or clear one field
Upload a new contract, assign its reference to contract, and save. Leave
cover out of that change. To remove the nullable cover, assign null to
cover and save. The runnable example checks both cases and then downloads the
remaining contract again.
Unbinding and physical deletion have different timing: maintenance removes eligible files after retention and a reference check. A saved record can also outlive a temporary signing-service failure. If a save committed but preparing the response fails, retry the read rather than the business mutation.
Start with ordinary attachments
The Blob module covers this workflow on its own. The separate secure-document module protects an editable business snapshot and its submitted changes; “secure document” does not mean encrypting the PDF attachment. Applications can enable that editing protocol separately when they need it.
For downloads, a normal presigned URL remains usable until expiry by anyone who holds it. If each download must check the current user, choose a provider or gateway with that stronger read capability.
Follow the step-by-step attachment guide for one-time configuration, the complete upload helper, build commands, and expected output. The dated status page tracks runtime availability and release progress; this source-preview walkthrough does not announce a new public package version.
