Generate a document

Fills a Word template with the workflow data (fields, repeated table rows, conditions) and produces a PDF or a .docx, added to the run’s attachments so that “Send” can attach it.

Generate a document fills a Word template (.docx) with the workflow data — fields, repeated table rows, conditions — and produces a PDF, a .docx, or both. The document is added to the run attachments: a Send node placed after it attaches it like any attachment.

The node is only offered when the instance has a documents service.

At a glance

• Type: document.generate · version 1
• Category: Data
• Kind: Step — one stage of a run
• Effect: No external effect (none) — nothing is written outside Loop & Roll; safe to replay
• Needs a carrier email: No
• Connection: None
• Inputs: main
• Outputs: main

The ports of “Generate a document”: what comes in on the left, what goes out on the right

Parameters

source

The template comes from

• Type: One choice (options)
• Required: Yes
• Default: library
• Options:
  • library — The template library: A Word template uploaded in Settings › Document templates.
  • attachment — An attachment of this run: A .docx received by email, or fetched from SharePoint or Drive at an earlier step.

template

Template — The template’s {{ … }} fields are written as anywhere else: {{ data.extract.buyer }}, {{ email.from.name }}.

• Type: Remote resource (resourceLocator)
• Required: Yes
• Ways to choose: pick from a list, type an ID (document_template)
• Shown when: source is library

templateName

Template file name — The first .docx of the run whose name matches. * matches anything.

• Type: Text (string)
• Required: Yes
• Default: *.docx
• 200 characters at most
• Example: *.docx
• Shown when: source is attachment
• Expressions: {{ }} accepted

output

Output format

• Type: One choice (options)
• Required: Yes
• Default: pdf
• Options:
  • pdf — PDF: What you send a client: the layout no longer moves.
  • docx — Word (.docx): A draft to be touched up before signing.
  • both — Both: The PDF to send, and the Word file to keep.

filename

Produced file name — Without extension, added from the format. May hold fields: certificate-{{ data.extract.name }}.

• Type: Text (string)
• Required: No
• Default: "" (empty)
• 300 characters at most
• Example: certificate
• Expressions: {{ }} accepted

onMissingField

If a field has no value

• Type: One choice (options)
• Required: Yes
• Default: empty
• Options:
  • empty — Leave it blank: The document is produced; missing fields are listed in the step data.
  • fail — Fail the step: For a deed: no document beats a sale agreement without the buyer’s name.
• Shown under “Advanced” in the editor

Outputs

• main

Data produced

What this node adds to the run data, and how to read it in an expression. <step> stands for the step key: the node name turned into an identifier (see Data and expressions).

• {{ data.<step>.position }} — number. The position of the produced document (the PDF if there is one, otherwise the .docx) in the run attachments: the one a Send node or a drive upload selects.
• {{ data.<step>.files }} — array of { position, filename, mime, size, origin }. The produced files, already added to the run attachments.
• {{ data.<step>.pdf }} — { position, filename, mime, size }. The produced PDF, when the format asks for one. docx describes the .docx the same way.
• {{ data.<step>.pages }} — number. The number of pages of the produced PDF.
• {{ data.<step>.template }} — { name, fields }. The template used (its name in the library, or the attachment's name) and its number of fields.
• {{ data.<step>.missingFields }} — array of string. The template fields left blank for lack of a value (data.extract.notary). Empty when everything was filled in.
• {{ data.<step>.summary }} — string. A one-line description for the run detail, in the member's language.

Example

An email asks for a visit certificate. An Extract node named extract takes out the visitor's name, the property address and the date. The “Visit certificate” template of the library contains:

I, the undersigned, certify that {{ data.extract.visitor }}
visited the property at {{ data.extract.address }} on {{ data.extract.date }}.
{{#if data.extract.accompanied}}The visit was accompanied.{{/if}}

The node:

source: library
template: Visit certificate
output: pdf
filename: "certificate-{{ data.extract.visitor }}"

Then a Send node that replies to the email with Attachments set to Those of the run, filtered and the name certificate-*.pdf: the certificate goes out with the reply.

The template

The syntax is described in Documents › Writing a template: {{ path | filter }} for a field, {{#each list}} … {{/each}} to repeat a table row or paragraphs ({{ item.x }}, {{ index }} inside), {{#if value}} … {{else}} … {{/if}} for a condition. The context is the same as for parameters: data (the outputs of earlier steps) and email (the triggering email).

The template comes from the library (Templates › Document templates), or from a run attachment: a .docx received by email, or fetched from SharePoint or Drive at an earlier step — the first one whose name matches the pattern (*.docx by default).

Tips

• Missing fields. By default a field without a value is left blank and listed in missingFields. For a deed, set If a field has no value to Fail the step: nothing is produced, and the step fails with document.invalid_template.
• File name. Without extension (added from the format); characters not allowed in a file name are replaced.
• Test runs. Producing a run attachment writes nothing outside Loop & Roll: in a test run the document is really produced, and you can open it in the run detail.
• Errors. Service unreachable or busy: document.service_unavailable, retried. Template deleted or not found: document.template_not_found. Malformed template: document.invalid_template. No service configured: document.not_configured.