> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize PDF Export Scripts

> Write custom Velocity templates to control the layout, sections, and content of your Nextedy RISKSHEET PDF exports, including cover pages, rating tables, downstream traceability, and custom data sections.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Prerequisites

* Administrator access to attach files to Polarion LiveDoc documents
* Familiarity with Apache Velocity template syntax
* A working Risksheet document with PDF export enabled

## How PDF Export Scripts Work

When you trigger a PDF export, Risksheet follows this processing chain:

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/yWl5nA2D0IzEnZC1/risksheet/diagrams/guides/export/pdf-custom-scripts/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=c9dd3c9f7fa5e35831df8835b61b994e" alt="diagram" style={{ maxWidth: "680px", width: "100%" }} width="680" height="170" data-path="risksheet/diagrams/guides/export/pdf-custom-scripts/diagram-1.svg" />
</Frame>

1. Loads the `risksheetPdfExport.vm` template from the document attachment or inherited template
2. Renders the Velocity template with access to `pdfExportMacros.vm` helpers
3. Executes the generated JavaScript against the exporter object
4. Produces the final PDF document

The script has access to these scope variables:

| Variable          | Type    | Description                                   |
| ----------------- | ------- | --------------------------------------------- |
| `exporter`        | Object  | PDF export controller with all export methods |
| `PDFExport`       | Class   | PDF document creation utilities               |
| `GridPDF`         | Class   | Grid-to-PDF rendering engine                  |
| `isInCompare`     | Boolean | Whether the sheet is in comparison mode       |
| `compareRevision` | String  | Revision being compared against               |
| `currentRevision` | String  | Current document revision                     |
| `showUnchanged`   | Boolean | Whether to show unchanged items in comparison |

## Create a Custom Export Script

### Step 1: Create the Template File

Create a file named `risksheetPdfExport.vm` with your custom export logic:

```velocity theme={null}
## Custom PDF Export Script for FMEA Risk Analysis

## Export the main risk sheet
exporter.exportMainSheet();

## Add a page break
#newPage()

## Export severity rating definitions
exporter.exportRatingTable("severity");

## Export occurrence rating definitions
exporter.exportRatingTable("occurrence");

## Export detection rating definitions
exporter.exportRatingTable("detection");
```

### Step 2: Attach to the Document

1. Open the LiveDoc document in Polarion.
2. Navigate to the document attachments.
3. Upload the `risksheetPdfExport.vm` file as an attachment.
4. Save the document.

Alternatively, attach the file to the global template so all documents inheriting from that template use the same export script.

### Step 3: Test the Export

Save the document and trigger a PDF export from the Risksheet view. The output should now follow your custom layout.

## Available Export Methods

The exporter object provides these methods for building your PDF layout:

| Method                                          | Purpose                                                                      |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `exporter.exportMainSheet(hideColumns?)`        | Export the main risk grid. Optional comma-separated column bindings to hide. |
| `exporter.exportSubTable(controlColumn)`        | Export rows where the control column has non-empty values                    |
| `exporter.exportDownstreamTable(controlColumn)` | Like `exportSubTable` but with automatic deduplication                       |
| `exporter.exportRatingTable(ratingId)`          | Export a rating scale definition table (ID, Label, Description)              |
| `exporter.exportEnumTable(enumId)`              | Export an enumeration definition table (ID, Label, Description)              |
| `exporter.exportCustomTableData(columns, data)` | Export arbitrary tabular data with custom column definitions                 |

Set `exporter.emptyPlaceholder = "N/A"` before exporting to display custom text for empty cells.

For full method signatures, parameters, and cell formatting behavior, see the [PDF Export Template](/risksheet/reference/templates/pdf-export-template) reference.

## Velocity Context and Macros

The Velocity template has access to the full Polarion Velocity context, including:

* `$document` -- the current Polarion document object
* `$transaction` -- the current transaction context
* Custom macros from `pdfExportMacros.vm` (page breaks, table helpers)

<Warning title="doc.pageAdded applies per page only">
  The `doc.pageAdded` event only applies to the specific page where it is called. To show images or headers on every page, you must add `doc.pageAdded` after each `#newPage()` call. It does not auto-repeat for table overflow pages.
</Warning>

## Complete Example: FMEA Report

```velocity theme={null}
## FMEA Risk Analysis Report - Custom PDF Export

## Section 1: Main Risk Analysis Table (hide internal columns)
exporter.exportMainSheet("internalNotes,reviewStatus");

## Page break before rating definitions
#newPage()

## Section 2: Rating Definitions
exporter.exportRatingTable("severity");
exporter.exportRatingTable("occurrence");
exporter.exportRatingTable("detection");

## Page break before downstream items
#newPage()

## Section 3: Mitigation Tasks (deduplicated)
exporter.exportDownstreamTable("mitigationTask");

## Section 4: Verification Activities
exporter.exportSubTable("verificationActivity");
```

<Tip title="Template vs. Document Scope">
  Attach `risksheetPdfExport.vm` to the **global template** if all documents should use the same export layout. Attach it to a **specific document** to override the template for that document only. The `fromTemplate` flag tracks which source was used.
</Tip>

## Troubleshooting

| Problem                        | Cause                       | Solution                                                                                            |
| ------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------- |
| Export produces default layout | Custom `.vm` file not found | Verify the file is attached with the exact name `risksheetPdfExport.vm`                             |
| Script error in export         | Velocity syntax error       | Check for unclosed directives or invalid variable references                                        |
| Empty rating tables            | Rating ID mismatch          | Verify the rating ID matches the Polarion enumeration ID referenced by the `rating:<enumId>` column |
| Missing columns in output      | Wrong binding names         | Use column binding names (not display headers) in `hideColumns`                                     |

## Verification

You should now see a PDF export that follows your custom layout. Verify that:

* The main sheet appears with the correct visible columns
* Rating tables display the expected scale definitions
* Downstream tables show deduplicated linked items
* Page breaks appear where you placed `#newPage()` calls

## See Also

* [Export to PDF](/risksheet/guides/export/pdf-export) -- standard PDF export workflow and validation
* [Add Multi-Page Images to PDF](/risksheet/guides/export/pdf-multi-page-images) -- repeating headers and logos across pages
* [Control Column Visibility in Exports](/risksheet/guides/export/column-visibility-export) -- managing column visibility

<LastReviewed date="2026-06-24" />