Templated PDF actions
Use a templated PDF action when a service must fill an existing PDF layout: for example, a regulated form, a partner document or a carefully designed printable record. The action overlays text or marks onto positioned boxes in an uploaded PDF template.
This is a precision feature. Build and test the template with the document owner, because a small change to the source PDF can shift every mapped value.
Prepare a stable template
Use a final, approved PDF template with a clear version and owner. Upload it through the templated PDF action settings; Builder records the template used by the action. Avoid replacing a live template without reviewing every mapping and generating a comparison document in QA.
flowchart LR
A[Approved PDF template] --> B[Upload template]
C[Service fields and Liquid values] --> D[Mapping boxes]
B --> E[Templated PDF action]
D --> E
E --> F[Filled PDF for review or storage]Keep the source file’s page order and dimensions stable. A new template version should be treated as a controlled change, even if it appears visually similar.
Configure the action
- Add a Templated PDF action from Page actions.
- Set a stable Action ID and a descriptive name.
- Upload the approved PDF template and confirm its displayed filename.
- Add one mapping box for each answer or mark that should appear on the PDF.
- Choose the trigger after all mapped values are available.
- Enable digital signing only for an approved, configured signing process.
- Generate and inspect QA documents with representative answers.
The stored template reference is managed by Builder. Work through the template upload controls rather than attempting to set an internal file reference yourself.
Map text and marks
Each mapping has a stable Mapping ID, a page number and a box position. Page numbering begins at 0, so the first PDF page is page 0. The X and Y coordinates, width and height are proportions of the page, from 0 to 1.
Use a Text mapping for a field value, a selected part of a multi-part field, or a Liquid value. Use a Mark mapping for a selection, with a tick, cross, filled shape, circle or strikethrough as appropriate.
| Mapping choice | Use it for | Important check |
|---|---|---|
| Field ID | a direct answer from the service | the field exists on every route that produces the document |
| Field part | one part of an address, date, time or location | only the intended part appears |
| Value template | calculated or combined content | blank and unexpected values render safely |
| Choice ID + mark | marking a selected option | the mark appears only for the intended selection |
Make mapping IDs meaningful, such as applicant_name_page1 or consent_tick. They help maintainers trace each box back to its purpose.
Fit content into the document
Set font, alignment and vertical alignment to suit the allocated box. A single-line answer often works best with bottom alignment; longer text generally needs top alignment. Use a sensible font size and minimum font size, but do not depend on shrinking to make an unsuitable answer fit.
Test the longest realistic answer, including names, addresses and free text. If text becomes too small to read, redesign the question, restrict the input or use a different document layout. Do not solve a layout issue by silently reducing important information to illegible text.
Set Read only for boxes that must not be edited during PDF review when editing is enabled. Use it sparingly and make sure the person can still correct the original service answer where needed.
Test every layout route
Generate PDFs for each conditional route, each choice that creates a mark, a blank optional value, long text and a repeated-group answer where relevant. Inspect every page at normal zoom. Check that values do not overlap labels, marks do not appear in the wrong box, and page-specific mappings stay on the correct page.
When the template changes, repeat the whole mapping check. Do not assume a coordinate that worked in the prior version is still correct.