​

Generating documents from HTML templates

​

Before you begin

1. Verify access permissions: Ensure you have the necessary permissions to manage document templates.
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 through FlowX Designer → Plugins → Document templates
2. Create or import your HTML template

​

Implementing document generation in a process

​

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

​

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)

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

3. Create the request payload with the following structure:

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

• 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

​

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

{
  "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
}

• fileId: Unique identifier for the generated file
• documentType: Template name used for generation
• minioPath: Storage location (MinIO or S3)
• downloadPath: URL path for downloading the file
• noOfPages: Document page count
• error: Error information (null if successful)

​

Error responses

• 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.

{
  "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.

{
  "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
}

​

Displaying the generated document

1. Add a Task Node to extract the document path from the response
2. Add a User Task with the Document Preview UI Element:
   • Configure the element with the download path from the previous node