Skip to main content
The Documents Plugin supports two types of file conversion:
  • PDF to JPEG — converts an uploaded PDF into JPEG images via Kafka messaging
  • CSV/Excel to JSON — converts CSV, XLS, or XLSX files to structured JSON on-the-fly when downloading, using content negotiation (no new files are stored)

​
CSV/Excel to JSON conversion

Available starting with FlowX.AI 5.6.0
You can download CSV or Excel files as structured JSON directly from the file download endpoints. The conversion happens on-the-fly — no new files are created in storage. To request JSON output, set the Accept header to application/json when calling either of these endpoints:
  • GET /internal/files/{fileId}/download
  • GET /internal/storage/download

​
Supported file types

Content typeExtensions
text/csv.csv
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.xlsx
application/vnd.ms-excel.xls

​
Query parameters

ParameterTypeDefaultDescription
formatstringobjectsOutput shape: objects (array of key-value maps using the header row as keys) or arrays (array of arrays including headers as the first row)
sheetstringFirst sheetFor Excel files, the name of the sheet to convert. If omitted, the first sheet is used

​
Example

curl -H "Accept: application/json" \
  "https://{your-document-url}/internal/files/{fileId}/download?format=objects"
Given a CSV file: 
name,age,city
Alice,30,New York
Bob,25,London
format=objects returns: 
[
  {"name": "Alice", "age": "30", "city": "New York"},
  {"name": "Bob", "age": "25", "city": "London"}
]
format=arrays returns: 
[
  ["name", "age", "city"],
  ["Alice", "30", "New York"],
  ["Bob", "25", "London"]
]

​
Behavior

  • If the file is already JSON, the raw content is passed through unchanged.
  • If the file is not a supported tabular format (for example, PDF), the endpoint returns 406 Not Acceptable.
  • If no Accept: application/json header is sent, the file downloads as raw bytes — preserving existing behavior.

​
PDF to JPEG conversion

The PDF to JPEG conversion uses Kafka messaging and creates a new file in storage, unlike the on-the-fly CSV/Excel to JSON conversion described above.
This section provides step-by-step instructions on how to convert an uploaded file from PDF to JPEG.

​
Prerequisites

  1. Access Permissions: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.
  2. Kafka Configuration: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.
  • Kafka Topics: Familiarize yourself with the Kafka topics used for these operations (later in this section)
  1. Before initiating the conversion process, it is essential to identify the file in the storage solution using its unique ID. This ensures that the conversion is performed on an already uploaded file.
You have two options to obtain the file ID:
In the following example, we will use the fileId generated for Uploading a New Document scenario.
{
  "customId": "119246",
  "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
  "documentType": "BULK",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119246/119246/458_BULK.pdf",
  "downloadPath": "internal/files/96975e03-7fba-4a03-99b0-3b30c449dfe7/download",
  "noOfPages": null,
  "error": null
}

​
Configuring the process

To create a process that converts a document from PDF to JPEG format, follow these steps:
  1. Create a process that includes a Send Message Task (Kafka) node and a Receive Message Task (Kafka):
  • Use the Send Message Task node to send the conversion request.
  • Use the Receive Message Task node to receive the reply.
  1. Configure the first node (Send Message Task) by adding a Kafka send action.
  1. Specify the Kafka topic where you send the conversion request.
To identify your defined topics in your current environment, follow the next steps:
  1. From the FLOWX.AI main screen, navigate to the Platform Status menu at the bottom of the left sidebar.
  2. In the FLOWX Components list, scroll to the document-plugin-mngt line and press the eye icon on the right side.
  3. In the details screen, expand the KafkaTopicsHealthCheckIndicator line and then details → configuration → topic → file → convert. Here will find the in and out topics for converting files.
  1. Fill in the body of the message request.

​
Message request example

This is an example of a message that follows the custom integration data model.
{
  "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
  "to": "image/jpeg"
}
  • fileId: The file ID that will be converted
  • to: The file extension to convert to (in this case, “JPEG”)
  1. Configure the second node (Receive Message Task) by adding a Data stream topic:
The response will be sent to this ..out Kafka topic.

​
Receiving the reply

The following values are expected in the reply body:
  • customId: The unique identifier for your document (it could be for example the ID of a client)
  • fileId: The file ID
  • documentType: The document type
  • documentLabel: The document label (if available)
  • minioPath: The path where the converted file is saved. It represents the location of the file in the storage system, whether it’s a MinIO path or an S3 path, depending on the specific storage solution
  • downloadPath: The download path for the converted file
  • noOfPages: If applicable
  • error: Any error message in case of an error during the conversion process

​
Message response example

{
  "customId": "119246",
  "fileId": "8ec75c0e-eaa6-4d80-b7e5-15a68bba7459",
  "documentType": "BULK",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119246/119246/461_BULK.jpg",
  "downloadPath": "internal/files/461/download",
  "noOfPages": null,
  "error": null
}
The converted file is now available in the storage solution and it can be downloaded:
Note that the actual values in the response will depend on the specific conversion request and the document being converted.
Last modified on March 25, 2026