# Documenten API Preview plugin

The "Documenten API Preview plugin" is used in combination with the "Documenten API plugin" to support previewing documents directly within GZAC.

> NOTE:
>
> The "Documenten API Preview plugin" requires at least one "Documenten API plugin" to be configured. More details on configuring the "Documenten API plugin" can be found in the [Documenten API plugin configuration guide](/features/plugins/configure-documenten-api-plugin.md).

## Configure the plugin

The "Documenten API Preview plugin" can be used to generate a read-only preview version of documents retrieved via the "Documenten API plugin" and works by converting documents to PDF which are displayed in the browser. The conversion of the original documents to PDF format is done using the open-source project [Gotenberg](https://gotenberg.dev), which is a Docker-based API specifically designed to convert documents to PDF. This means the "Documenten API Preview plugin" requires some configuration. A general description on how to configure plugins can be found in the [plugin configuration guide](/features/plugins/configure-plugin.md).

> IMPORTANT:
>
> The [Gotenberg](https://gotenberg.dev) PDF conversion API is available as a docker image and should be installed separately (see [installation guide](https://gotenberg.dev/docs/getting-started/installation)).

To configure this plugin the following properties have to be entered:

* **Configuration ID (`configurationId`).** The plugin will be saved under this ID. The ID must be in the format of a UUID.
* **Configuration name (`configurationTitle`).** A user-friendly name that is used to identify the plugin (default value is "Documenten API Preview").
* **PDF Conversion URL (`pdfConversionUrl`).** Contains the complete base URL pointing to the server hosting the [Gotenberg](https://gotenberg.dev) API (for example: `https://gotenberg:3000`).
* **Documenten API plugin configuration (`documentenApiConfigurationId`).** Contains a reference to the configuration of the "Documenten API plugin". The preview plugin will retrieve documents based on this configuration.

## Configure `application.yaml`

For the Documenten API Preview plugin to work correctly, the following MIME types must be added to the `application.yaml` configuration:

```yaml
spring:
  servlet:
    multipart:
      enabled: true
  codec:
    mime-types:
      - application/msword
      - application/vnd.openxmlformats-officedocument.wordprocessingml.document
```

These MIME types are required to support the conversion of Word documents (`.doc` and `.docx`) to PDF via the Gotenberg API.

## Configure the Content Security Policy (CSP)

Internally the Valtimo downloads the PDF file into a `blob` field and uses the HTML `<object>`, `<iframe>` tags to display the PDF. Since Valtimo offers a strongly typed CSP configuration (see [Content Security Policy](/running-valtimo/application-configuration/content-security-policy.md)), the CSP configuration needs to be updated to allow for `blob` resources to be displayed via the `<object>`, `<iframe>` tags.

To do so add the lines `'object-src': [SELF, BLOB]` and `'frame-src': [SELF, BLOB]` to the CSP configuration for each of the environments you want to support the preview plugin (see [Content Security Policy](/running-valtimo/application-configuration/content-security-policy.md) guide for more detailed instructions on CSP configuration). An example configuration that supports loading `blob` resources looks like this:

```ts
import {CSPHeaderParams, DATA, SELF, UNSAFE_EVAL, UNSAFE_INLINE, BLOB} from 'csp-header';
import {UrlUtils} from '@valtimo/shared';
import {authenticationKeycloak} from '../auth/keycloak-config';

export const cspHeaderParamsDev: CSPHeaderParams = {
  directives: {
    'default-src': [SELF],
    'frame-src': [SELF, BLOB],
    'object-src': [SELF, BLOB],
    'img-src': [SELF, DATA, 'https://tile.openstreetmap.org/'],
    'script-src': [SELF, UNSAFE_EVAL, UNSAFE_INLINE, 'https://cdn.form.io/'],
    'worker-src': [SELF, BLOB],
    'font-src': [
      SELF,
      DATA,
      UNSAFE_INLINE,
      'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/',
      'https://fonts.gstatic.com',
    ],
    'connect-src': [
      SELF,
      UrlUtils.getUrlHost(authenticationKeycloak.options.keycloakOptions.config.url),
    ],
    'style-src': [
      SELF,
      UNSAFE_INLINE,
      'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/',
      'https://fonts.googleapis.com',
    ],
  },
};
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valtimo.nl/features/plugins/configure-documenten-api-preview-plugin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.