feat(intent): send a document by e-mail - the notify block + attach: print (#6356)

[delchev]

What

Closes #6356. An intent could already render any document to PDF and send plain-text mail from a schedule, but not do the single most common outbound action a business document has: send the document itself - the invoice to its customer, the payslip to its employee, an escalating reminder that carries the invoice.

to / subject / body (+ channel) becomes one reusable notify block, authored at every place an intent can act on a record:

Call site	Reads	Sends when	Generated as
notifications[]	the event record	create / update / delete	<Name>Notification.java
schedules[].notify	each matched row	every cron tick, per row	<Name>Job.java
transitions[].notify	the transitioned record	after the status flip commits	inside <Name>Transition.java
a serviceTask's args.notify	the process's trigger record	the flow reaches that step	<Process><Step>Send.java (new sends glue)

    notify:
      to: Customer.email                 # literal / field / one-hop relation.field (cross-model ok)
      subject: "Invoice {number}"        # {field} / {relation.field} interpolation
      body: "Dear {Customer.name}, please find invoice {number} attached."
      attach: print                      # render THIS record's .print to PDF and attach it
      language: bg                       # optional print-template language

attach: print reuses the generated <Entity>PrintFeeder + sdk.print.Print - the two steps the snapshot delegate already takes - so no module ever needs a hand-written listener around the print engine. The attachment is named after the document's number: field (INV0000042.pdf), else <Entity> <id>.pdf.

Failure semantics, per call site (deliberate)

• A recipient that resolves to nothing is a logged no-op - a record with nobody to mail must not stall a flow.
• A transitions[].notify can never fail its transition: the flip is the endpoint's contract and has already committed, so SMTP cannot turn a successful void into an error.
• A sending serviceTask does fail on a delivery error, so the process engine retries - the message is that step's whole work.

Guardrails

• Only a document (header + line-items child) can be attached; the parser rejects attach: print on anything else rather than mail a note claiming a document it cannot render. The check mirrors the print generator's own document-master resolution, so the parser can never allow what generation would silently drop.
• A sending serviceTask stands alone: notify cannot share a step with setField / setRelationField / call / delegate.
• ServiceTaskHandlerGenerator no longer scaffolds a custom/<Step>.java stub for a notify step (it would never be invoked).

Platform side

MailClient accepts a part's data as a raw byte[] in addition to the historical JSON int-array string, so a rendered PDF does not have to travel through a JSON array of numbers. Backward compatible; both shapes are unit-tested.

Test

• GlueSendDocumentTest - the pre-rendered glue at all four call sites, the empty-key contract for a generate schedule, and both parser rejections (non-document attach, notify combined with setField).
• MailClientAttachmentTest - a byte[] and a JSON-array attachment reach the MIME part byte-identically.
• IntentEmissionCoverageIT (extended fixture) - emission: the PDF attachment part, Print.render("Bill","en", new BillPrintFeeder().feed(entity.Id)), the one-hop FK recipient load, the fail-soft catch, the BPMN binding of BillFlowMailBillSend, and no scaffolded custom/MailBill.java. Runtime: a notify-carrying transition returns 200 with the status written when the mail cannot be delivered, and a sending step logs its no-recipient no-op.
• Full engine-intent suite + api-mail green; formatter clean.

Docs

intent-assistant-guide.md gains a send a document by e-mail section and reference-table rows. The vendor-neutral spec (intentfile.org) and the platform docs (dirigible.io) are updated in their own PRs, per the documentation-sync contract in engine-intent/CLAUDE.md.

🤖 Generated with Claude Code