🤔 Fields not showing in your document?

When adding merge fields to your Word document, it's important to add an equals sign in front of the available references that are listed below.

As an example, referencing the project name in a Word document as "project_name" will not work, you must refer to it as "=project_name".

Preview Claim Document vs Generate Document

On a progress claim you will see two different document actions. They are not the same thing.

Preview Claim Document (near the bottom of the claim) opens Drum's built-in claim PDF. It picks up your account logo and Account Billing Detail (billing name, address, phone, email, and tax number). The table layout itself is fixed. You cannot upload or edit a Word template for that button.

Generate Document (near the top of the claim, once you have a Progress Claim template) runs a custom Word document you manage yourself.

To set that up:

Go to Settings → Document Templates → Progress Claim. You need the Customisation permission.
Create a template or open an existing one, then upload a .docx with merge fields. Use the example under Reference Documents as a starting point.
On the claim, choose Generate Document and pick that template.

The merge fields in this article apply to those custom Word templates (Generate Document), not to Preview Claim Document.

What the built-in claim PDF lists

Preview Claim Document only includes included claim items (same filter as the Generate Document claim_items loop). Rows are grouped by deliverable / procedure where relevant.

Fixed table columns:

Item
Approved Value
Complete %
Complete Amount
Prev %
Prev Amount
This Period
Remaining (only when Show Remaining Column is on for that claim)

Those money columns are not coloured red in the product PDF. If you mark Drum figures in red on a screenshot, that is your highlight, not a PDF style. On the Claims tab, Total Claimed and Remaining can show in a darker orange when a fixed-price line is overclaimed.

Available To All Dynamic Documents

Project Information

project_name - Name of the project
project_number - Project reference number
total_budget - Total project budget with currency formatting
start_date - Project start date (DD Month YYYY format)
end_date - Project end date (DD Month YYYY format)

Company Details

company_name - Project client company name
company_trading_name - Project client trading name
company_legal_name - Project client legal name
company_* - Any custom company fields on the project client (replace * with field name in snake_case)

Those flat company fields are always the project client. They are not the Work tab Invoice to company when that is set to someone else.

Invoice to (Work Tab)

There is no merge field called Billing Client. On the Work tab the field is labelled Invoice to. That company is available on Progress Claim and other Word templates as invoice_to_client.

It uses the Invoice to company when one is set, otherwise it falls back to the project client. If Invoice to differs from the client, use these nested fields rather than company_name.

In Word, insert a real merge field with an equals sign, for example =invoice_to_client.name.

invoice_to_client.name - Invoice to company name (trading name, or legal name if trading is blank)
invoice_to_client.trading_name - Trading name
invoice_to_client.legal_name - Legal name
invoice_to_client_address.summary - Full address on one line
invoice_to_client_address.line_one - Street / first address line

Project Custom Fields

Any custom project fields will be available using their label in snake_case

Project Roles

Each project role is available using its name in snake_case
For single-user roles: access first_name and last_name
For multi-user roles: iterate through the array of users with first_name and last_name

System Information

date - Current date (DD Month YYYY format)
user_name - Current user's full name
user_email - Current user's email address

For Progress Claims

These fields are filled when you generate a document from a progress claim. Claim-level money fields, plus item approved_amount and total_budget, are excluding tax and come through with the currency symbol. item.previous_claim_amount and item.total_claimed_amount follow different rules (see Claim Items below). Do not look for a separate excluding-tax field. There is no requested total or requested amount.

In Word, each value has to be a merge field, with an equals sign in front of the name. =approved_total works. approved_total on its own does not.

Progress Claim Details

name - Progress claim name
description - Progress claim description
start_date - Claim period start date (DD Month YYYY). On a progress claim this replaces the project start date of the same name.
end_date - Claim period end date (DD Month YYYY). On a progress claim this replaces the project end date of the same name.
issued_date - Date the claim was issued (DD Month YYYY)
approved_date - Date the claim was approved (DD Month YYYY)
status - Current claim status
approved_by - Name of the person who approved the claim

Financial Totals

These are all excluding tax. approved_total is already excluding tax. approved_total_excluding_tax, requested_total, and requested_total_excluding_tax are not merge fields.

approved_total - Approved amount for this claim, excluding tax
previously_claimed_total - Amount previously claimed, excluding tax
approved_budget - Approved budget, excluding tax
retention - Retention amount, excluding tax
new_approved_total - This claim's approved total plus the previously claimed total, excluding tax

Claim Items

Only claim items included on the claim are available. Loop them with Sablon claim_items:each(item), and inside the loop use a merge field with an equals sign, such as =item.name.

name - Item name
description - Item description
approved_amount - This period / This Claim amount for the item, already excluding tax. There is no approved_amount_excluding_tax field. Closest match to Claims tab This Claim and built-in PDF This Period.
claim_percentage - Percentage claimed this period against approved value. Closest match to Claims tab % Claimed.
total_budget - Approved value for this item. The merge field is still called total_budget so existing templates keep working. It is the approved value, not a budget. There is no total_budget_excluding_tax field. Closest match to Claims tab / PDF Approved Value.
previous_claim_amount - Amount on the single most recent earlier claim for this item (by issued date). It is not the same figure as Prev. Claimed on the Claims tab or Prev Amount on the built-in claim PDF, which sum all earlier approved claims excluding tax. Expect this field to disagree with those screens when you have more than one prior claim, or when tax is in play.
costs_in_period - Costs incurred during the claim period. Closest match to Claims tab Costs in Period (not shown on the built-in claim PDF).
total_claimed_amount - Running total for this item across claims. It is not the same figure as Total Claimed on the Claims tab or Complete Amount on the built-in claim PDF (those use approved prior claims plus this claim, excluding tax). Do not treat it as a drop-in for Complete Amount.

Building a Claims-tab-like Word template

Closest Generate Document mapping if you want a table like the Claims tab or built-in claim PDF:

Approved Value → =item.total_budget
This Claim / This Period → =item.approved_amount
% Claimed → =item.claim_percentage
Costs in Period → =item.costs_in_period
Prev. Claimed / Prev Amount → =item.previous_claim_amount (available, but different calculation; see above)
Total Claimed / Complete Amount → =item.total_claimed_amount (available, but different calculation; see above)
Remaining / Value Remaining → no merge field. The Claims tab and built-in PDF can show Remaining when Show Remaining Column is on, but Generate Document does not expose Remaining, Value Remaining, or remaining_balance today.

😵‍💫 Looping through lists in your Word document

A progress claim in Drum potentially has many claim items associated with it. Only items included on the claim are in this list.

This means you have to "loop" through each claim item to display it within your Word document (e.g. in a table or list).

In the case of claim items, your document will look something like:

<< claim_items:each(item) >>

<< =item.name >> - << =item.approved_amount >>

<< claim_items:endEach >>

Each of the dynamic fields above is a merge field in Word, so the above cannot be copied and pasted directly into a Word document. You have to insert the merge fields yourself. The equals sign is required on the item fields (for example =item.approved_amount). approved_amount is already excluding tax. Do not use approved_amount_excluding_tax, requested_amount, requested_amount_excluding_tax, or project_procedure. Those are not claim item fields.

Remember to reference the video at the top of this article for additional detail!

For Invoices

Invoice-Specific Fields

invoice_number - Unique invoice identifier
invoice_date - Date invoice was issued (DD Month YYYY format)
due_date - Invoice payment due date (DD Month YYYY format)
description - Invoice description
reference - Invoice reference number
total - Total invoice amount including tax
total_excluding_tax - Total invoice amount excluding tax
amount_paid - Amount already paid
status - Current invoice status
currency_code - Invoice currency
sent_to - Invoice recipient

Line Items

Use these fields within a line_items loop:

name - Item name
description - Item description
quantity - Item quantity
price - Unit price with currency formatting
total - Line item total
total_excluding_tax - Line item total excluding tax
tax_amount - Tax amount
tax_rate - Applied tax rate percentage
discount - Applied discount with currency formatting
position - Line item position/order

All monetary values are automatically formatted with currency symbols and decimal places.

Dynamic Document Generation Reference