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

# Generating documents

> Generate new documents from custom templates that can be pre-filled with data from the current process instance.

> [!NOTE]
>
> Configure document templates using the [**WYSIWYG editor**](https://docs.flowx.ai/6.x/docs/platform-deep-dive/plugins/wysiwyg.md). Access and manage your templates through the **Document Templates** section in your Project in [**FlowX Designer**](https://docs.flowx.ai/6.x/docs/flowx-designer/overview.md).

![Document template interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/docs_plugin_template.png)

## Generating documents from HTML templates

The Documents plugin generates documents from predefined templates. This guide focuses on generating documents using HTML templates.

![Document templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_tmplts.png)

## Before you begin

1. **Verify access permissions**: Ensure you have the necessary [permissions to manage document templates](https://docs.flowx.ai/6.x/setup-guides/access-management/workspaces-access-rights.md).
2. **Check Kafka configuration**: Confirm that Kafka is properly configured and accessible:
   * The document plugin relies on Kafka for communication between nodes
   * Familiarize yourself with the required Kafka topics (detailed later in this guide)

## Creating an HTML template

1. Access the [**WYSIWYG editor**](https://docs.flowx.ai/6.x/docs/platform-deep-dive/plugins/wysiwyg.md) through **FlowX Designer → Plugins → Document templates**
2. Create or import your HTML template

![HTML template creation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_template.png)

For detailed template management instructions:

> [card] [Managing HTML templates](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/managing-html-templates.md)

> [!TIP]
>
> For comprehensive guidance, take the FlowX.AI Academy course: [**Creating a Document Template in Designer**](https://academy.flowx.ai/module/create-document-templates-flowxai-designer).

## Implementing document generation in a process

Let's build a document generation flow that creates personalized documents based on user input:

![Document generation process example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_upload_prev_ex.png)

### Step 1: Create a user input form

1. Add a **User Task** node to your process
2. Configure UI elements to collect the information needed for your document:
   * Input fields (text, numbers, dates, etc.)
   * Make sure to set appropriate keys for each field that match your template variables

<video autoPlay muted loop src="https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/generate_template1.mp4" />

### Step 2: Configure the document generation request

1. Add a **Send Message Task (Kafka)** node
2. Configure the Kafka send action with the appropriate topic:
   * For HTML template generation, use `ai.flowx.plugin.document.trigger.generate.html.v1` (or your configured equivalent, set via `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN`)

![Kafka send action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gen_template_action.png)

> [!TIP]
>
> To find your environment's configured topics:
>
> 1. Navigate to **FlowX Designer → Platform Status**
> 2. Find the **document-plugin-mngt** component and click the eye icon
> 3. Expand `KafkaTopicsHealthCheckIndicator → details → configuration → topic → document → generate`
> 4. Look under HTML and PDF sections for your in/out topics
>
> ![Kafka topics for document generation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_topics_html_generate.png)

3. Create the request payload with the following structure:

```json theme={"dark"}
{ 
  "documentList": [
    {
      "customId": "ClientsFolder",
      "templateName": "AccountCreation",
      "language": "en",
      "data": {
        "firstInput": "${application.client.firstName}",
        "secondInput": "${application.client.lastName}",
        "thirdInput": "${application.client.accountType}"
      },
      "includeBarcode": false
    }
  ]
}
```

![Kafka send action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gen_templ_payload.png)

Key parameters:

* **customId**: Folder name where the file will be saved
* **templateName**: Name of the template defined in Document templates
* **language**: Must match the language configured on the template
* **data**: Key-value pairs mapping template variables to process data
* **includeBarcode**: Set to true if you need a barcode on the document

> [!NOTE]
>
> When using templates in a process, the system uses default values from the default project language. For example, if English is your default project language, the template will use values from the English version.
>
> To check your default language: **FlowX Designer → Project Settings → Languages**

### Generating DOCX output

By default, generated documents are PDF files. To generate a DOCX file instead, add `outputFormat` to a document entry in the request payload:

```json theme={"dark"}
{
  "documentList": [
    {
      "customId": "ClientsFolder",
      "templateName": "AccountCreation",
      "language": "en",
      "outputFormat": "DOCX",
      "data": {
        "firstInput": "${application.client.firstName}"
      }
    }
  ]
}
```

* **outputFormat**: `PDF` or `DOCX`. When omitted, the document is generated as PDF.
* The generated DOCX preserves the template's styles, data, and images, and is stored and returned the same way as a PDF.
* **includeBarcode** applies to PDF output only; it is ignored when generating DOCX.

When testing a template in **FlowX Designer → Plugins → Document templates**, use the **Output format** dropdown in the test modal to download the test result as PDF or DOCX.

### Step 3: Receive the generated document

1. Add a **Receive Message Task (Kafka)** node
2. Configure it with:
   * The response topic: `ai.flowx.engine.receive.plugin.document.generate.html.results.v1` (or your configured equivalent, set via `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT`)
   * Key for storing the response: `generatedDocuments`

![Receive message configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/generate_template_receive.png)

The response contains information about the generated documents:

![HTML generation response](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/html_generated_response.png)

Sample response structure:

```json theme={"dark"}
{
  "generatedFiles": {
    "ClientsFolder": {
      "AccountCreation": {
        "customId": "ClientsFolder",
        "fileId": "320f4ec2-a509-4aa9-b049-87224594802e",
        "documentType": "AccountCreation",
        "documentLabel": "GENERATED_PDF",
        "minioPath": "{{your_bucket}}/2024/2024-01-15/process-id-865759/ClientsFolder/6869_AccountCreation.pdf",
        "downloadPath": "internal/files/320f4ec2-a509-4aa9-b049-87224594802e/download",
        "noOfPages": 1,
        "error": null
      }
    }
  },
  "error": null
}
```

Response fields:

* **fileId**: Unique identifier for the generated file
* **documentType**: Template name used for generation
* **minioPath**: Storage location (MinIO or S3)
* **downloadPath**: Download path relative to the Documents plugin base URL, for example `internal/files/{fileId}/download`. It is not a complete URL.
* **noOfPages**: Document page count
* **error**: Error information (null if successful)

### Error responses

When generation fails, `error` is populated as an object with three fields:

| Field | Description |
| - | - |
| `code` | Numeric status code: `400` for request or validation problems, `500` for rendering or storage failures |
| `message` | What went wrong |
| `timestamp` | When the error occurred (ISO-8601) |

The error appears at one of two levels, never both:

* **Request-level** (`error` at the root): the whole request was rejected before any document was processed, for example a malformed payload or an empty `documentList`. `generatedFiles` is not populated.

```json theme={"dark"}
{
  "generatedFiles": null,
  "error": {
    "code": 400,
    "message": "Document list is empty",
    "timestamp": "2026-09-14T08:31:46.512+00:00"
  }
}
```

* **Per-document** (`error` inside a `generatedFiles` entry): that document failed while the rest of the request proceeded. A missing template or failed input validation returns `400`; a rendering or storage failure returns `500`. Other documents in the same response can still succeed, so check the `error` field of each entry. The root `error` stays `null` in this case.

```json theme={"dark"}
{
  "generatedFiles": {
    "ClientsFolder": {
      "AccountCreation": {
        "customId": "ClientsFolder",
        "fileId": null,
        "documentType": "AccountCreation",
        "downloadPath": null,
        "error": {
          "code": 400,
          "message": "Template could not be found.",
          "timestamp": "2026-09-14T08:31:46.512+00:00"
        }
      }
    }
  },
  "error": null
}
```

> [!TIP]
>
> In the process, branch on the received `error` fields before using `downloadPath`: a failed document has `fileId` and `downloadPath` set to `null`, so wiring the happy path only leaves the user with a broken file preview when generation fails.

## Displaying the generated document

To display the generated document to the user:

1. Add a **User Task** with the File Preview UI Element.
2. Set its **Source** to **Document Plugin path**, **Value type** to **Variable**, and **Data key** to the key that holds the generated file's `downloadPath`.

The raw `downloadPath` is relative: with the **Document Plugin path** source, the renderer adds the Documents plugin base URL, so you don't need a business rule to build the complete URL. If the key path depends on a runtime value, such as a `customId` set to the process instance ID, add a business rule that copies `downloadPath` to a fixed key first. See [Preview an uploaded file](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md#preview-an-uploaded-file).&#x20;

You can also generate the document from an integration workflow with the **Template Filling** node. See [Fill a document template from a workflow and download it](https://docs.flowx.ai/6.x/cookbooks/generate-and-download-a-document.md), which also shows how to build the download URL.

For detailed instructions on displaying documents, see:

> [card] [Uploading a new document](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document.md)


## Related topics

- [FlowX.AI CMS](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/content-management.md)
- [Documents plugin setup](https://docs.flowx.ai/6.x/setup-guides/documents-plugin-setup.md)
- [Fill a document template from a workflow and download it](https://docs.flowx.ai/6.x/cookbooks/generate-and-download-a-document.md)
- [FlowX.AI 5.10.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026.md)
- [Sending an email](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.