Docling
Since Camel 4.15
Only producer is supported
The Docling component allows you to convert and process documents using IBM’s Docling AI document parser. Docling is a powerful Python library that can parse and convert various document formats including PDF, Word documents, PowerPoint presentations, and more into structured formats like Markdown, HTML, JSON, or plain text.
Maven users will need to add the following dependency to their pom.xml for this component:
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-docling</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency> Prerequisites
This component supports two modes of operation:
-
CLI Mode (default): Requires Docling to be installed on your system via pip:
pip install docling -
API Mode: Requires a running docling-serve instance. You can run it using:
# Install docling-serve pip install docling-serve # Run docling-serve docling-serve --host 0.0.0.0 --port 5001Or using Docker:
docker run -p 5001:5001 ghcr.io/docling-project/docling-serve:latest
URI format
docling:operation[?options]
Where operation represents the document processing operation to perform.
Supported Operations
The component supports the following operations:
| Operation | Description |
|---|---|
| Convert document to Markdown format (default) |
| Convert document to HTML format |
| Convert document to JSON format with structure information |
| Extract plain text content from document |
| Extract structured data including tables and layout information |
| Submit an async conversion and return task ID (docling-serve only) |
| Check the status of an async conversion task (docling-serve only) |
Configuring Options
Camel components are configured on two separate levels:
-
component level
-
endpoint level
Configuring Component Options
At the component level, you set general and shared configurations that are, then, inherited by the endpoints. It is the highest configuration level.
For example, a component may have security settings, credentials for authentication, urls for network connection and so forth.
Some components only have a few options, and others may have many. Because components typically have pre-configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.
You can configure components using:
-
the Component DSL.
-
in a configuration file (
application.properties,*.yamlfiles, etc). -
directly in the Java code.
Configuring Endpoint Options
You usually spend more time setting up endpoints because they have many options. These options help you customize what you want the endpoint to do. The options are also categorized into whether the endpoint is used as a consumer (from), as a producer (to), or both.
Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL and DataFormat DSL as a type safe way of configuring endpoints and data formats in Java.
A good practice when configuring options is to use Property Placeholders.
Property placeholders provide a few benefits:
-
They help prevent using hardcoded urls, port numbers, sensitive information, and other settings.
-
They allow externalizing the configuration from the code.
-
They help the code to become more flexible and reusable.
The following two sections list all the options, firstly for the component followed by the endpoint.
Component Options
The Docling component supports 23 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
The configuration for the Docling Endpoint. | DoclingConfiguration | ||
Include the content of the output file in the exchange body and delete the output file. | false | boolean | |
Docling-serve API URL (e.g., http://localhost:5001). | String | ||
Enable OCR processing for scanned documents. | true | boolean | |
Show layout information with bounding boxes. | false | boolean | |
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean | |
Language code for OCR processing. | en | String | |
Required The operation to perform. Enum values:
| CONVERT_TO_MARKDOWN | DoclingOperations | |
Output format for document conversion. | markdown | String | |
Use docling-serve API instead of CLI command. | false | boolean | |
API request timeout in milliseconds. | 60000 | long | |
Polling interval for async conversion status in milliseconds. | 2000 | long | |
Maximum time to wait for async conversion completion in milliseconds. | 300000 | long | |
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. | true | boolean | |
Docling-serve API convert endpoint path. | /v1/convert/source | String | |
Path to Docling Python executable or command. | String | ||
Timeout for Docling process execution in milliseconds. | 30000 | long | |
Use asynchronous conversion mode (docling-serve API only). | false | boolean | |
Working directory for Docling execution. | String | ||
Header name for API key authentication. | X-API-Key | String | |
Authentication scheme (BEARER, API_KEY, NONE). Enum values:
| NONE | AuthenticationScheme | |
Authentication token for docling-serve API (Bearer token or API key). | String | ||
Maximum file size in bytes for processing. | 52428800 | long |
Endpoint Options
The Docling endpoint is configured using URI syntax:
docling:operationId
With the following path and query parameters:
Query Parameters (21 parameters)
| Name | Description | Default | Type |
|---|---|---|---|
Include the content of the output file in the exchange body and delete the output file. | false | boolean | |
Docling-serve API URL (e.g., http://localhost:5001). | String | ||
Enable OCR processing for scanned documents. | true | boolean | |
Show layout information with bounding boxes. | false | boolean | |
Language code for OCR processing. | en | String | |
Required The operation to perform. Enum values:
| CONVERT_TO_MARKDOWN | DoclingOperations | |
Output format for document conversion. | markdown | String | |
Use docling-serve API instead of CLI command. | false | boolean | |
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean | |
API request timeout in milliseconds. | 60000 | long | |
Polling interval for async conversion status in milliseconds. | 2000 | long | |
Maximum time to wait for async conversion completion in milliseconds. | 300000 | long | |
Docling-serve API convert endpoint path. | /v1/convert/source | String | |
Path to Docling Python executable or command. | String | ||
Timeout for Docling process execution in milliseconds. | 30000 | long | |
Use asynchronous conversion mode (docling-serve API only). | false | boolean | |
Working directory for Docling execution. | String | ||
Header name for API key authentication. | X-API-Key | String | |
Authentication scheme (BEARER, API_KEY, NONE). Enum values:
| NONE | AuthenticationScheme | |
Authentication token for docling-serve API (Bearer token or API key). | String | ||
Maximum file size in bytes for processing. | 52428800 | long |
Message Headers
The Docling component supports 12 message header(s), which is/are listed below:
| Name | Description | Default | Type |
|---|---|---|---|
CamelDoclingOperation (producer) Constant: | The operation to perform. | DoclingOperations | |
CamelDoclingOutputFormat (producer) Constant: | The output format for conversion. | String | |
CamelDoclingInputFilePath (producer) Constant: | The input file path or content. | String | |
CamelDoclingOutputFilePath (producer) Constant: | The output file path for saving result. | String | |
CamelDoclingProcessingOptions (producer) Constant: | Additional processing options. | Map | |
CamelDoclingEnableOCR (producer) Constant: | Whether to include OCR processing. | Boolean | |
CamelDoclingOCRLanguage (producer) Constant: | Language for OCR processing. | String | |
CamelDoclingCustomArguments (producer) Constant: | Custom command line arguments to pass to Docling. | List | |
CamelDoclingUseAsyncMode (producer) Constant: | Use asynchronous conversion mode (overrides endpoint configuration). | Boolean | |
CamelDoclingAsyncPollInterval (producer) Constant: | Polling interval for async conversion status in milliseconds. | Long | |
CamelDoclingAsyncTimeout (producer) Constant: | Maximum time to wait for async conversion completion in milliseconds. | Long | |
| Constant: | Task ID for checking async conversion status. | String |
Usage
Input Types
The component accepts the following input types in the message body:
-
String- File path or document content -
byte[]- Binary document content -
File- File object -
InputStream- Input stream containing document data
Output Behavior
The component behavior depends on the contentInBody configuration option:
-
When
contentInBody=true(default: false): The converted content is placed in the exchange body and the output file is automatically deleted -
When
contentInBody=false: The file path to the generated output file is returned in the exchange body
Examples
Basic document conversion to Markdown
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
- to:
uri: "file:///data/output" Convert to HTML with content in body
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_HTML?contentInBody=true")
.process(exchange -> {
String htmlContent = exchange.getIn().getBody(String.class);
// Process the HTML content
}); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_HTML"
parameters:
contentInBody: true
- process:
ref: "htmlProcessor" Extract structured data from documents
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:EXTRACT_STRUCTURED_DATA?outputFormat=json&contentInBody=true")
.process(exchange -> {
String jsonData = exchange.getIn().getBody(String.class);
// Process the structured JSON data
}); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:EXTRACT_STRUCTURED_DATA"
parameters:
outputFormat: "json"
contentInBody: true
- process:
ref: "jsonDataProcessor" Convert with OCR disabled
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?enableOCR=false")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
enableOCR: false
- to:
uri: "file:///data/output" Using headers to control processing
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.setHeader("CamelDoclingOperation", constant(DoclingOperations.CONVERT_TO_HTML))
.setHeader("CamelDoclingEnableOCR", constant(true))
.setHeader("CamelDoclingOCRLanguage", constant("es"))
.to("docling:CONVERT_TO_MARKDOWN") // Operation will be overridden by header
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- setHeader:
name: "CamelDoclingOperation"
constant: "CONVERT_TO_HTML"
- setHeader:
name: "CamelDoclingEnableOCR"
constant: true
- setHeader:
name: "CamelDoclingOCRLanguage"
constant: "es"
- to:
uri: "docling:CONVERT_TO_MARKDOWN" # Operation will be overridden by header
- to:
uri: "file:///data/output" Processing with custom arguments
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.process(exchange -> {
List<String> customArgs = Arrays.asList("--verbose", "--preserve-tables");
exchange.getIn().setHeader("CamelDoclingCustomArguments", customArgs);
})
.to("docling:CONVERT_TO_MARKDOWN")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- setHeader:
name: "CamelDoclingCustomArguments"
expression:
method:
ref: "customArgsBean"
method: "createCustomArgs"
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
- to:
uri: "file:///data/output" Content in body vs file path output
-
Java
-
YAML
// Get content directly in body (file is automatically deleted)
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?contentInBody=true")
.process(exchange -> {
String markdownContent = exchange.getIn().getBody(String.class);
log.info("Converted content: {}", markdownContent);
});
// Get file path (file is preserved)
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?contentInBody=false")
.process(exchange -> {
String outputFilePath = exchange.getIn().getBody(String.class);
log.info("Output file saved at: {}", outputFilePath);
}); # Get content directly in body (file is automatically deleted)
- route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
contentInBody: true
- process:
ref: "contentProcessor"
# Get file path (file is preserved)
- route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
contentInBody: false
- process:
ref: "filePathProcessor" Processor Bean Examples
When using YAML DSL, the processor references used in the examples above would be implemented as Spring beans:
@Component("htmlProcessor")
public class HtmlProcessor implements Processor {
@Override
public void process(Exchange exchange) throws Exception {
String htmlContent = exchange.getIn().getBody(String.class);
// Process the HTML content
log.info("Processing HTML content of length: {}", htmlContent.length());
}
}
@Component("jsonDataProcessor")
public class JsonDataProcessor implements Processor {
@Override
public void process(Exchange exchange) throws Exception {
String jsonData = exchange.getIn().getBody(String.class);
// Process the structured JSON data
log.info("Processing JSON data: {}", jsonData);
}
}
@Component("contentProcessor")
public class ContentProcessor implements Processor {
private static final Logger log = LoggerFactory.getLogger(ContentProcessor.class);
@Override
public void process(Exchange exchange) throws Exception {
String markdownContent = exchange.getIn().getBody(String.class);
log.info("Converted content: {}", markdownContent);
}
}
@Component("filePathProcessor")
public class FilePathProcessor implements Processor {
private static final Logger log = LoggerFactory.getLogger(FilePathProcessor.class);
@Override
public void process(Exchange exchange) throws Exception {
String outputFilePath = exchange.getIn().getBody(String.class);
log.info("Output file saved at: {}", outputFilePath);
}
}
@Component("customArgsBean")
public class CustomArgsBean {
public List<String> createCustomArgs() {
return Arrays.asList("--verbose", "--preserve-tables");
}
} Asynchronous Processing
The component supports asynchronous document conversion when using docling-serve API mode. This is particularly useful for: - Large documents that take a long time to process - High-volume batch processing scenarios - Better resource utilization on the server side
Enabling Async Mode
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?" +
"useDoclingServe=true&" +
"useAsyncMode=true&" +
"asyncPollInterval=2000&" +
"asyncTimeout=300000&" +
"contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
useAsyncMode: true
asyncPollInterval: 2000
asyncTimeout: 300000
contentInBody: true
- to:
uri: "file:///data/output" Async Processing with Custom Timeout
For very large documents, you may need to increase the timeout:
-
Java
-
YAML
from("file:///data/large-documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?" +
"useDoclingServe=true&" +
"useAsyncMode=true&" +
"asyncPollInterval=5000&" +
"asyncTimeout=600000&" + // 10 minutes
"contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "file:///data/large-documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
useAsyncMode: true
asyncPollInterval: 5000
asyncTimeout: 600000
contentInBody: true
- to:
uri: "file:///data/output" Using Headers to Control Async Behavior
You can override async settings per-message using headers:
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.process(exchange -> {
File file = exchange.getIn().getBody(File.class);
// Use async mode only for large files
if (file.length() > 10 * 1024 * 1024) { // > 10MB
exchange.getIn().setHeader("CamelDoclingUseAsyncMode", true);
exchange.getIn().setHeader("CamelDoclingAsyncTimeout", 600000L);
}
})
.to("docling:CONVERT_TO_MARKDOWN?useDoclingServe=true&contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- process:
ref: "asyncDecisionProcessor"
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
contentInBody: true
- to:
uri: "file:///data/output" Custom Async Workflows
For advanced use cases, you can use the SUBMIT_ASYNC_CONVERSION and CHECK_CONVERSION_STATUS operations to build custom async workflows with full control over task submission and status polling.
When to use custom workflows:
-
You need custom polling intervals that vary per task
-
You want to implement custom retry or backoff strategies
-
You need to coordinate multiple async tasks
-
You want to store task IDs in a database for later retrieval
-
You need fine-grained control over timeout and error handling
When to use built-in async mode (useAsyncMode=true):
-
Standard use cases where automatic polling is sufficient
-
You want the simplest configuration
-
Default polling intervals and timeouts work for your needs
Custom polling workflows require Java processors and are more complex. The built-in async mode (useAsyncMode=true) is recommended for most use cases. |
Simple Manual Polling (Java)
The simplest custom workflow uses a Java loop to poll for status:
// Submit conversion
String taskId = template.requestBody(
"docling:convert?operation=SUBMIT_ASYNC_CONVERSION&useDoclingServe=true",
"/path/to/document.pdf", String.class);
// Poll for completion
ConversionStatus status;
int attempts = 0;
do {
Thread.sleep(1000);
status = template.requestBody(
"docling:convert?operation=CHECK_CONVERSION_STATUS&useDoclingServe=true",
taskId, ConversionStatus.class);
attempts++;
} while (status.isInProgress() && attempts < 60);
// Get result
if (status.isCompleted()) {
String result = status.getResult();
// Process result...
} Submit and Poll Pattern (Camel Route)
-
Java
-
YAML
// Submit async conversion and poll until complete
from("file:///data/documents?include=.*\\.pdf")
.log("Starting async conversion for: ${header.CamelFileName}")
// Step 1: Submit conversion
.to("docling:convert?operation=SUBMIT_ASYNC_CONVERSION&useDoclingServe=true")
.log("Submitted conversion with task ID: ${body}")
.setHeader("taskId", body())
.setProperty("maxAttempts", constant(60))
.setProperty("attempt", constant(0))
// Step 2: Poll for completion
.loopDoWhile(method(MyPollingHelper.class, "shouldContinuePolling"))
.process(exchange -> {
// Increment attempt counter
Integer attempt = exchange.getProperty("attempt", Integer.class);
exchange.setProperty("attempt", attempt != null ? attempt + 1 : 1);
})
.log("Polling attempt ${exchangeProperty.attempt} of ${exchangeProperty.maxAttempts}")
.setBody(header("taskId"))
.to("docling:convert?operation=CHECK_CONVERSION_STATUS&useDoclingServe=true")
.setProperty("conversionStatus", body())
.process(exchange -> {
ConversionStatus status = exchange.getProperty("conversionStatus", ConversionStatus.class);
if (status.isCompleted()) {
exchange.setProperty("isCompleted", true);
} else if (status.isFailed()) {
exchange.setProperty("isFailed", true);
exchange.setProperty("errorMessage", status.getErrorMessage());
}
})
.choice()
.when(exchangeProperty("isCompleted").isEqualTo(true))
.stop()
.when(exchangeProperty("isFailed").isEqualTo(true))
.throwException(new RuntimeException("Conversion failed"))
.end()
.delay(1000)
.end()
// Step 3: Extract result
.process(exchange -> {
ConversionStatus status = exchange.getProperty("conversionStatus", ConversionStatus.class);
if (status != null && status.isCompleted() && status.getResult() != null) {
exchange.getIn().setBody(status.getResult());
} else {
throw new RuntimeException("Conversion did not complete");
}
})
.to("file:///data/output");
// Helper class for loop condition
public class MyPollingHelper {
public static boolean shouldContinuePolling(Exchange exchange) {
Integer attempt = exchange.getProperty("attempt", Integer.class);
Integer maxAttempts = exchange.getProperty("maxAttempts", Integer.class);
Boolean isCompleted = exchange.getProperty("isCompleted", Boolean.class);
Boolean isFailed = exchange.getProperty("isFailed", Boolean.class);
if (Boolean.TRUE.equals(isCompleted) || Boolean.TRUE.equals(isFailed)) {
return false;
}
if (attempt != null && maxAttempts != null && attempt >= maxAttempts) {
return false;
}
return true;
}
} # Note: For YAML, consider using the built-in async mode (useAsyncMode=true)
# which handles polling automatically. Custom polling is easier in Java DSL.
- route:
id: async-with-custom-polling
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- log: "Starting async conversion for: ${header.CamelFileName}"
- to:
uri: "docling:convert"
parameters:
operation: "SUBMIT_ASYNC_CONVERSION"
useDoclingServe: true
- log: "Submitted conversion with task ID: ${body}"
- setHeader:
name: "taskId"
simple: "${body}"
# For YAML, simpler to use Java processor bean or built-in async mode
- to:
uri: "bean:asyncPollingProcessor"
- to: "file:///data/output" ConversionStatus Object
The CHECK_CONVERSION_STATUS operation returns a ConversionStatus object with the following properties:
-
taskId (String) - The task identifier
-
status (enum) - PENDING, IN_PROGRESS, COMPLETED, FAILED, or UNKNOWN
-
result (String) - Converted document content (available when status is COMPLETED)
-
errorMessage (String) - Error details (available when status is FAILED)
-
progress (Integer) - Task queue position
Helper methods: - isCompleted() - Returns true if conversion completed successfully - isFailed() - Returns true if conversion failed - isInProgress() - Returns true if conversion is still processing
Parallel Processing with Custom Workflow
-
Java
-
YAML
// Submit multiple conversions
from("file:///data/documents?include=.*\\.pdf")
.to("docling:convert?operation=SUBMIT_ASYNC_CONVERSION&useDoclingServe=true")
.to("seda:task-queue");
// Process task queue with multiple threads
from("seda:task-queue?concurrentConsumers=5")
.log("Processing task: ${body}")
.setHeader("taskId", body())
.setProperty("maxAttempts", constant(60))
.setProperty("attempt", constant(0))
.loopDoWhile(method(MyPollingHelper.class, "shouldContinuePolling"))
.process(exchange -> {
Integer attempt = exchange.getProperty("attempt", Integer.class);
exchange.setProperty("attempt", attempt != null ? attempt + 1 : 1);
})
.setBody(header("taskId"))
.to("docling:convert?operation=CHECK_CONVERSION_STATUS&useDoclingServe=true")
.setProperty("conversionStatus", body())
.process(exchange -> {
ConversionStatus status = exchange.getProperty("conversionStatus", ConversionStatus.class);
if (status.isCompleted()) {
exchange.setProperty("isCompleted", true);
} else if (status.isFailed()) {
exchange.setProperty("isFailed", true);
}
})
.choice()
.when(exchangeProperty("isCompleted").isEqualTo(true))
.stop()
.when(exchangeProperty("isFailed").isEqualTo(true))
.stop()
.end()
.delay(1000)
.end()
.process(exchange -> {
ConversionStatus status = exchange.getProperty("conversionStatus", ConversionStatus.class);
if (status != null && status.isCompleted()) {
exchange.getIn().setBody(status.getResult());
}
})
.choice()
.when(body().isNotNull())
.to("file:///data/output?fileName=${header.CamelFileName}")
.end(); # For parallel processing in YAML, recommend using built-in async mode
# which is simpler and handles concurrency automatically
- route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:convert"
parameters:
operation: "CONVERT_TO_MARKDOWN"
useDoclingServe: true
useAsyncMode: true
asyncPollInterval: 1000
asyncTimeout: 120000
contentInBody: true
- to:
uri: "file:///data/output"
parameters:
fileName: "${header.CamelFileName}" For a complete working example of custom polling workflow, see the testCustomPollingWorkflowWithRoute() test in DoclingServeProducerIT.java in the camel-docling test sources. |
Using Docling-Serve API
Basic usage with docling-serve
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?useDoclingServe=true&doclingServeUrl=http://localhost:5001&contentInBody=true")
.process(exchange -> {
String markdown = exchange.getIn().getBody(String.class);
log.info("Converted content: {}", markdown);
}); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
doclingServeUrl: "http://localhost:5001"
contentInBody: true
- process:
ref: "markdownProcessor" Converting documents from URLs using docling-serve
When using docling-serve API mode, you can also process documents from URLs:
-
Java
-
YAML
from("timer:convert?repeatCount=1")
.setBody(constant("https://arxiv.org/pdf/2501.17887"))
.to("docling:CONVERT_TO_MARKDOWN?useDoclingServe=true&contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "timer:convert"
parameters:
repeatCount: 1
steps:
- setBody:
constant: "https://arxiv.org/pdf/2501.17887"
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
contentInBody: true
- to:
uri: "file:///data/output" Batch processing with docling-serve
-
Java
-
YAML
from("file:///data/documents?include=.*\\.(pdf|docx)")
.to("docling:CONVERT_TO_HTML?useDoclingServe=true&doclingServeUrl=http://localhost:5001&contentInBody=true")
.to("file:///data/converted?fileName=${file:name.noext}.html"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.(pdf|docx)"
steps:
- to:
uri: "docling:CONVERT_TO_HTML"
parameters:
useDoclingServe: true
doclingServeUrl: "http://localhost:5001"
contentInBody: true
- to:
uri: "file:///data/converted"
parameters:
fileName: "${file:name.noext}.html" Authentication with docling-serve
The component supports multiple authentication mechanisms for secured docling-serve instances.
Bearer Token Authentication
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?" +
"useDoclingServe=true&" +
"doclingServeUrl=http://localhost:5001&" +
"authenticationScheme=BEARER&" +
"authenticationToken=your-bearer-token-here&" +
"contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
doclingServeUrl: "http://localhost:5001"
authenticationScheme: "BEARER"
authenticationToken: "your-bearer-token-here"
contentInBody: true
- to:
uri: "file:///data/output" API Key Authentication
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?" +
"useDoclingServe=true&" +
"doclingServeUrl=http://localhost:5001&" +
"authenticationScheme=API_KEY&" +
"authenticationToken=your-api-key-here&" +
"apiKeyHeader=X-API-Key&" +
"contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
doclingServeUrl: "http://localhost:5001"
authenticationScheme: "API_KEY"
authenticationToken: "your-api-key-here"
apiKeyHeader: "X-API-Key"
contentInBody: true
- to:
uri: "file:///data/output" Using Custom API Key Header
If your docling-serve instance uses a custom header name for API keys:
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?" +
"useDoclingServe=true&" +
"doclingServeUrl=http://localhost:5001&" +
"authenticationScheme=API_KEY&" +
"authenticationToken=your-api-key-here&" +
"apiKeyHeader=X-Custom-API-Key&" +
"contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
doclingServeUrl: "http://localhost:5001"
authenticationScheme: "API_KEY"
authenticationToken: "your-api-key-here"
apiKeyHeader: "X-Custom-API-Key"
contentInBody: true
- to:
uri: "file:///data/output" Using Authentication Token from Properties
For better security, store authentication tokens in properties or environment variables:
-
Java
-
YAML
from("file:///data/documents?include=.*\\.pdf")
.to("docling:CONVERT_TO_MARKDOWN?" +
"useDoclingServe=true&" +
"doclingServeUrl={{docling.serve.url}}&" +
"authenticationScheme=BEARER&" +
"authenticationToken={{docling.serve.token}}&" +
"contentInBody=true")
.to("file:///data/output"); - route:
from:
uri: "file:///data/documents"
parameters:
include: ".*\\.pdf"
steps:
- to:
uri: "docling:CONVERT_TO_MARKDOWN"
parameters:
useDoclingServe: true
doclingServeUrl: "{{docling.serve.url}}"
authenticationScheme: "BEARER"
authenticationToken: "{{docling.serve.token}}"
contentInBody: true
- to:
uri: "file:///data/output" Then define in application.properties:
docling.serve.url=http://localhost:5001
docling.serve.token=your-bearer-token-here Error Handling
The component handles various error scenarios:
-
File size limit exceeded: Files larger than
maxFileSizeare rejected -
Process timeout: Long-running conversions are terminated after
processTimeoutmilliseconds -
Invalid file formats: Unsupported file formats result in processing errors
-
Docling not found: Missing Docling installation causes startup failures (CLI mode)
-
Connection errors: When using docling-serve API mode, connection failures to the API endpoint will result in errors
-
Authentication errors: Invalid or missing authentication credentials will result in 401 Unauthorized errors from the docling-serve API
Performance Considerations
-
Large documents may require increased
processTimeoutvalues (CLI mode) -
OCR processing significantly increases processing time for scanned documents
-
Consider using
contentInBody=truewhen using docling-serve API mode to get results directly in the body -
The
maxFileSizesetting helps prevent resource exhaustion -
API Mode vs CLI Mode: The docling-serve API mode typically offers better performance and resource utilization for high-volume document processing, as it maintains a persistent server instance
-
Async Mode: For large documents or high-volume processing, enable
useAsyncMode=trueto prevent blocking the Camel thread pool. The component will poll the docling-serve API for completion status while freeing up processing threads -
Async Configuration: Adjust
asyncPollInterval(default 2000ms) andasyncTimeout(default 300000ms/5 minutes) based on your document size and processing requirements -
Batch Processing: When processing multiple documents, async mode allows better parallelization as the docling-serve instance can process multiple documents concurrently while Camel polls for results
Spring Boot Auto-Configuration
When using docling with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-docling-starter</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency> The component supports 24 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
Header name for API key authentication. | X-API-Key | String | |
API request timeout in milliseconds. | 60000 | Long | |
Polling interval for async conversion status in milliseconds. | 2000 | Long | |
Maximum time to wait for async conversion completion in milliseconds. | 300000 | Long | |
Authentication scheme (BEARER, API_KEY, NONE). | none | AuthenticationScheme | |
Authentication token for docling-serve API (Bearer token or API key). | String | ||
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. | true | Boolean | |
The configuration for the Docling Endpoint. The option is a org.apache.camel.component.docling.DoclingConfiguration type. | DoclingConfiguration | ||
Include the content of the output file in the exchange body and delete the output file. | false | Boolean | |
Docling-serve API convert endpoint path. | /v1/convert/source | String | |
Path to Docling Python executable or command. | String | ||
Docling-serve API URL (e.g., http://localhost:5001). | String | ||
Enable OCR processing for scanned documents. | true | Boolean | |
Whether to enable auto configuration of the docling component. This is enabled by default. | Boolean | ||
Show layout information with bounding boxes. | false | Boolean | |
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | Boolean | |
Maximum file size in bytes for processing. | 52428800 | Long | |
Language code for OCR processing. | en | String | |
The operation to perform. | convert-to-markdown | DoclingOperations | |
Output format for document conversion. | markdown | String | |
Timeout for Docling process execution in milliseconds. | 30000 | Long | |
Use asynchronous conversion mode (docling-serve API only). | false | Boolean | |
Use docling-serve API instead of CLI command. | false | Boolean | |
Working directory for Docling execution. | String |