Using documents

A document is rendered when something asks for it by key: a customer notification or product module code. Root renders the version that applies (see Document concepts), stores the PDF with the entity, and hands it back to whatever asked for it.

Attaching documents to customer notifications

A custom notification event email template can attach documents. In the template's email details, pick the documents under Documents. Only enabled documents are listed. When the event is triggered, Root renders each document, waits until they have all finished, and sends the email with the PDFs attached. A document that fails or is skipped is left out, and the email is still sent.

To choose documents per send, pass document_keys to trigger a custom notification event. It replaces the template's list for that send.

📘

Which documents a notification can attach

A policy, payment method, claim or payment custom event can attach documents about its policy, that policy's application and payment method, and the claim or payment it was raised for. It can't attach invoice or alteration documents. An application custom event can't attach documents.

Saving a template, or triggering an event over the API with document_keys, is rejected if a key names a document the event can't reach. When a product module triggers the event, such keys are left out instead. A key with no matching document, for example one that was archived, is left out when the email is sent.

Rendering from product module code

Return a render_org_document action from a lifecycle hook, for example to post a letter to a policyholder with no email address. Application lifecycle hooks and afterDocumentGenerated can't return it, and the hook fails if org documents aren't enabled or no document has the key.

{
  name: 'render_org_document',
  document_key: 'welcome_letter',
  module_data: { correlation_id: '8b0c6c1e-…' },
}

When the PDF is ready, Root calls the product module's afterDocumentGenerated hook with the policy, the policyholder, the claim (for a claim document) and a document object. Fetch the PDF from document.file_url inside the hook, using Authorization: Bearer ${process.env.API_TOKEN}, or replace /file with /base64 in the URL to get it as base64.

const afterDocumentGenerated = async ({ policy, document }) => {
  const response = await fetch(document.file_url.replace(/\/file$/, '/base64'), {
    headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
  });
  const { file_base64 } = await response.json();
  const { correlation_id } = document.module_data;
  // send the PDF to your postal provider; use document.org_document_render_id to avoid posting it twice
};

🚧

The hook is not retried

If afterDocumentGenerated throws, the error is recorded in the code-run logs and Root does not call it again. A run can still repeat after an infrastructure failure, so use document.org_document_render_id to avoid acting on the same render twice. Failed and skipped renders do not call the hook.

Render statuses

Finding renders

• On a policy: the policy's Documents section lists renders of policy documents under Policy docs, one row per document version, with its status. Repeat renders of the same version share a row. Search by file name, or filter by date, to find a render. Use the row's ⋯ menu to View or Download a complete render. Show history adds earlier versions and pending, failed and skipped renders. Renders of other entity types, such as claim letters, are listed on the document instead.
• On a document: in Version history, expand a version's renders to see its latest renders, with the custom notification event that triggered each one, when it was rendered and its status. A version with more than five renders also shows View all … renders.
• Over the API: list a policy's document renders and download a policy document render, or list the renders of a document.