> For the complete documentation index, see [llms.txt](https://docs.valtimo.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valtimo.nl/features/plugins/configure-documenten-api-preview-plugin.md).

# 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',
    ],
  },
};
```