--- title: Record Handlers slug: reports/record-handlers description: Use record handlers in Unaric Reports to trigger actions based on report data changes in Salesforce. docTags: createdAt: 2026-02-12T18:46:24.717Z --- Use Record Handlers to move beyond displaying report data as just table rows. Normally each row in a report is placed into a table row. With Record Handlers, you can change that behaviour to format the rows using one of four types of Record Handlers: - Document - Page - Block - Cell ## Workflow All Record Handlers follow the same basic process: ::::::WorkflowBlock :::::WorkflowBlockItem Create a Solution containing: - A Word Document Template. - A source report with the record handler token and an alias (e.g., OPPORTUNITIES, CONTACTS). The alias must match the alias configured in your Solution. ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **Document Template** ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/NQfhjLGPMHvkPMQqp_t98_document-record-handler-alias.png) ::: :::VerticalSplitItem **Solution** ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/z-TR5r1913u8RMEq6nmTv_document-record-handler-schedule-alias.png) ::: :::: ::::: :::::WorkflowBlockItem Add variables from the report into the Document Template. You can find the list of variable names by going to run report page and selecting the info icon: ::::VerticalSplit{layout="middle"} :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/-0qjXlEU38ZOE7s-tx3QS_report-variables1.png) ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/iqppC-MwbSpOieOwcirty_report-variables2.png) ::: :::: You can put these variables anywhere in your Document Template: ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/7Irj1uEcAxDsxsj6_y4sZ_document-record-handler-template.png) ::::: :::WorkflowBlockItem When the Solution runs, fields are merged and content repeats according to the selected Record Handler. ::: :::::: ## Record Handler types ::::::ExpandableHeading ### Document record handler This record handler creates a full document for each report row, then merges all documents together. **Typical use cases:** - One full report per record. - Individual letters, summaries, or contracts per item. **Token:** :::::VerticalSplit{layout="middle"} ::::VerticalSplitItem :::BlockQuote {{DOCUMENT\_RECORD\_HANDLER-ALIAS}} ::: :::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/afV-xY6JWJE1QEex1FjtF_document-record-handler-template-1.png) ::: ::::: **Example:** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem If your report lists Opportunities, each Opportunity generates a complete document (for example, a full opportunity summary), and all summaries are merged into one final PDF. ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/6jqoqgxfnD0VETGKF0Gv9_document-record-handler-output.png) ::: :::: :::::: ::::::ExpandableHeading ### Page record handler Creates a new page per report row within a single document. Unlike Document handlers, this lets you include static pages (cover pages, disclaimers, summaries). **Typical use cases:** - Reports that include cover or closing pages - Structured multipage reports with consistent page layout per record - Situations where each record should start on a new page but remain in one document **Tokens:** :::::VerticalSplit{layout="middle"} ::::VerticalSplitItem **Start token:** :::BlockQuote {{PAGE\_RECORD\_HANDLER-ALIAS}} ::: **Optional end token (if static pages follow):** :::BlockQuote {{PAGE\_RECORD\_HANDLER\_END-ALIAS}} ::: :::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/t4yJy0e7hroedWSaqWZbA_page-record-handler.png) ::: ::::: **Example:** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem A report of Opportunities generates: - Cover page (static) - One page per Opportunity - Final disclaimer page (static) ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/IWv_49rmrXSdnKXPuBqbJ_page-record-handler-output1.png) ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/SbYybyG36g7IjrV21WdwF_page-record-handler-output2.png) ::: :::: :::::: ::::::ExpandableHeading ### Block Record Handler Repeats a section of content per record without forcing page breaks. This handler supports two implementations**:** - **Record blocks:** repeat a section for each row in a report (multiple records per page). - **Grouped blocks:** repeat a section per report grouping, optionally with nested record blocks inside each group. **Typical use cases:** - Compact summaries or listings - Dashboards or grouped record displays inside documents - Situations where page breaks would waste space **Tokens** :::::VerticalSplit{layout="middle"} ::::VerticalSplitItem :::BlockQuote {{BLOCK\_RECORD\_HANDLER\_START-ALIAS}} ::: :::BlockQuote {{BLOCK\_RECORD\_HANDLER\_END-ALIAS}} ::: :::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/jQVEZweQ1S3UEw1k70xfz_block-record-handler.png) ::: ::::: **Grouping variables:** :::::VerticalSplit{layout="middle"} ::::VerticalSplitItem :::BlockQuote \{{GROUPING\_1\_LABEL} ::: :::BlockQuote {{GROUPING\_1\_VALUE}} ::: :::BlockQuote {{GROUPING\_1\_COUNT}} ::: :::BlockQuote {{GROUPING\_1\_COUNT\_LABEL}} ::: :::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/LIElVFMtV9OwzaJOlkYlo_grouped-block-report.png) ::: ::::: **Record block example:** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem Instead of one Opportunity per page, multiple Opportunities appear on the same page as repeating sections, each showing key details like name, amount, and close date. ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/EdHyqW1Wh5GoFp276WQ0N_block-record-handler-output.png) ::: :::: **Grouped blocks example:** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem If Opportunities are grouped by Account: - One block per Account group - Nested blocks for each Opportunity inside the group. ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/bEdc_zlkguUTzWuqKSO3N_grouped-block-report-output.png) ::: :::: :::::: ::::::ExpandableHeading ### Cell Record Handler Creates one table cell per report row. **Typical use cases:** - Mailing labels. - Address or contact grids. - Any layout where records should populate table cells instead of rows or pages. **Token:** :::::VerticalSplit{layout="middle"} ::::VerticalSplitItem :::BlockQuote {{CELL\_RECORD\_HANDLER-ALIAS}} ::: :::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/kCrT_YUQ97rFULjQKL640_cell-record-handler.png) ::: ::::: **Example:** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem A Contacts report generates mailing labels where each Contact’s address fills one cell in a label grid. ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/mKyJ-zZr0IbQgZ8tYxCCS_cell-record-handler-output.png) ::: :::: :::::: ## Spacing One common issue with adding Record Handler tokens is removing the space the token is taking up. By default, Unaric Reports will remove the entire line that the token is on. Sometimes though you want to keep the line but just remove the token. We have added an extra token to all of these features, except Repeat Cell, to allow you to keep the space. The token is {{KEEP\_SPACE}} and you place it directly after any of the Record Handler tokens to leave the line in the document. For example, if you are doing a Page Record Handler and keep the line that contains the token, it would look like this: `{{PAGE_RECORD_HANDLER-ALIAS}}{{KEEP_SPACE}}`. ::Image[]{src="https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/AwLM_VUM4XOgOkeETH69T_keep-space.png" size="64" width="827" height="303" position="center" darkWidth="827" darkHeight="303" showCaption="false"} ## ***No Results*** message If you would like to insert a message when there is no data, you can place a message the between {{NO\_RESULTS\_MESSAGE\_START-ALIAS}} and {{NO\_RESULTS\_MESSAGE\_END-ALIAS}} tokens. For example, if you have a template that lists out of the Contacts for an Account, you can use the following tokens to insert a message when there are no Contacts. ::Image[]{src="https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/g1osUh_teSrCLAS6aYtth_no-results-message-template.png" size="64" width="881" height="469" position="center" darkWidth="881" darkHeight="469" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/10Nod6Ww95R3dPr0k0TCJ/tsCQWlp3JWxKYBtIsZ6lJ_no-results-message.png" size="72" width="689" height="294" position="center" darkWidth="689" darkHeight="294" showCaption="false"}