> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/build-spark-services/additional-mappings/pdf-reports-xreport.md).

# PDF reports (Xreport)

Produce `PDF` reports from selected worksheets.

Syntax: `Xreport_<parameter>`

1. Define the [`Print_Area`](https://support.microsoft.com/en-US/Excel/set-or-clear-a-print-area-on-a-worksheet) for the target sheets.
   * Ensure that each `Xreport` worksheet has a worksheet scope variable called `Print_Area`.
   * Add an extra row and extra column of padding around any cells with large text.
   * Please do not include any `Xinput`s in the worksheet - these will not be rendered correctly.
   * Spark does not support `Print_Area` ranges that are dynamically defined using formulas.
2. Rename the worksheet(s) with a name in the format `Xreport_<parameter>`, for example, `Xreport_illustration`.
3. Upload the file to Spark and open the [API Tester](/navigation/api-tester.md).
4. **API request (inputs)** **Field view** lists all the `Xreport`s that have been defined in the workbook.
5. Next to the **Report Name** field, is the **File Name** field, which corresponds to the `FileName` parameter of the API request. Enter the desired filename here, for example, `customfilename.pdf`. If no filename is provided, then a UUID is used for the filename.
6. Click **Submit** to make the API request.
7. In the **API response (outputs)** **Field view**, open the **Reports** expandable.
8. Each report will be listed in the table with a link to download the `PDF` report.

## Sample file

{% file src="/files/2r6RZjuLTmsZzPeoeSvl" %}

## Control report rendering

Use [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#request_meta) `xreport_options` to modify how the report is rendered.

|                                              |                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No `xreport_options` are used in the request | `{ "produce_pdfs": true, "multiple_docs": true, "page_numbers": true, "render_chart_texture_bars_as_images": false }`                                                                                                                                                                                                               |
| `produce_pdfs`                               | <p>Boolean to indicate whether to return the <code>Xreport</code> sheets as <code>PDF</code>s. Default is <code>true</code>.</p><p></p><p>Set this to <code>false</code> for a faster API response or if the PDF report is not required.</p>                                                                                        |
| `multiple_docs`                              | <p>Boolean to indicate whether to return each <code>Xreport</code> sheet as a separate <code>PDF</code>.</p><ul><li>If no <code>xreport\_options</code> are used in the request, the default is <code>true</code> .</li><li>If <code>xreport\_options</code> are used in the request, the default is <code>false</code> .</li></ul> |
| `page_numbers`                               | Boolean to indicate whether to include page numbers. Default is `true`.                                                                                                                                                                                                                                                             |
| `render_chart_texture_bars_as_images`        | Boolean to resolve an issue with borders appearing for dynamic chart images. Default is `false`.                                                                                                                                                                                                                                    |

## **Formatting features**

### Supported fonts

`Xreport` supports the following fonts:

* **AR PL UMing** (Chinese)
* **Angsana** (Thai)
* **Arial** (default)
* **Garuda** (Thai)
* **Halant** (Devanagari script)
* **HK Grotesque**
* **Montserrat**
* **Noto Sans CJK Regular** (Chinese/Japanese/Korean)
* **Open Sans**

If Spark detects any font other than the ones listed above, it will use the **Arial** font.

### **Exclude certain rows**

Excel output content can vary in length. You may want to exclude extra empty pages at the end of the output.

Whether a row is included in an `Xreport` can be controlled by inserting a column within the `Print_Area` with the heading `Hide in Report Output`. Within this column a value of `FALSE` will exclude that row from being included in the report. The `Print_Area` must be a single contiguous area for this feature to work. Note the dotted line page breaks in the sample file.

{% file src="/files/Evf8Sc4vD6P6TWLtI1qa" %}

### Render charts

`Xreport` is able to render charts into the `PDF` reports. To make the data series for a chart visible, the data series must reference data that is within the `Xreport` worksheet's defined `Print_Area`. Not all chart types are supported by Spark.

### Change images based upon an input

Formulas that resolve the image must be within the `Xreport` worksheet's defined `Print_Area`.

{% file src="/files/6kuiDtlp6Cnc0O4Uiuiu" %}

## Troubleshoot inconsistent margins

Saving Excel workbooks while using different Windows [display scaling](https://support.microsoft.com/en-US/Windows/Hardware/Display-Graphics/change-your-screen-resolution-and-layout-in-windows) settings (`100%`, `125%`, `150%`, etc.) can lead to slightly different margin widths. When uploaded to Spark, this may lead to `Xreport` not rendering as intended by the author.

If you are seeing margins shift between different iterations of a Spark service, check that all contributors are using consistent display scaling.