The application element defines settings for the web services and the portal page. Some of these changes might require a server restart to take effect.
The web services element defines settings for the web service endpoints.
The portal element defines settings for the portal page of the server.
The bridges element defines settings for the bridges (to other applications) used by the server. Such bridges are mostly used, to provide the Converter web service with instruments for a native and more accurate PDF conversion of specific file formats.
Important: Be aware that activating such a bridge requires the application to be installed and correctly configured on the server side. (Refer to the user manual for further information.)
Defines the settings for the MS Office Bridge. The Office Bridge can be used as an alternative (to the built-in conversion) for converting Office documents. The Office Bridge requires a local installation of MS Office on the server and works only on Windows.
Defines the settings for the SharePoint Bridge. The SharePoint Bridge can be used as an alternative (to the built-in conversion) for converting Office documents. The SharePoint Bridge uses SharePoint Online and therefore requires the corresponding Microsoft 365 service and a registered application on the Microsoft identity platform
Defines the settings for the Chromium bridge. The Chromium bridge is used for converting emails and HTML documents.
Defines the license to be used for the server.
Defines the global keystore used by the server. This keystore is used to store globally available certificates (e.g. for usage in the signature web service).
Defines a TSA (Time Stamp Authority which supports RFC3161) that shall be used by the server (e.g. when signing documents).
Defines proxy servers that shall be known to and used by the server to access external resources.
When enabled, proxy settings are automatically read from the operating system instead of using manually configured proxies.
Supported sources:
Important:
-Djava.net.useSystemProxies=true must be set.
Limitations: PAC (Proxy Auto-Config) files and WPAD (Web Proxy Auto-Discovery) are not supported. Only basic proxy configurations (host, port, bypass list) are read from the system.
Defines the configuration for collecting and exporting application metrics using the Micrometer framework.
Metrics are collected across multiple architectural layers:
Metrics can be exported to Prometheus and/or JMX for monitoring and visualization in tools like Grafana.
Defines the license to be used for the server.
License key. Divided into five parts, each part delimited by a minus sign. Each part has six characters.
Name of the licensee. Is used in conjunction with the license key. Notation is important.
Defines a set of options for all web services.
If enabled, then the web service is activated.
Number of parallel instances (threads) for the web service. Defines the number of requests that can be executed in parallel before requests are queued.
Maximum allowed time in seconds for the execution of a web service request (job) before the request is canceled. If the time has expired, the execution is aborted and an error code is returned.
Maximum number of waiting requests, before new requests are rejected.
If there are more requests than free instances, they are placed in the queue.
If this maximum value is reached, further requests are rejected directly.
This setting only applies if queueMode is set to MANUAL.
Defines a set of options specific for the "Converter" web service.
Sets the base path (including subfolders) of the server from which to retrieve installed fonts.
If no value is specified, then the default font directories (including subfolders) of the respective operating system are used.
Under Windows this is usually C:\Windows\Fonts and under Linux /usr/share/fonts/truetype.
Note:
On Linux, the home directory of the user under which the server is running is also always used in addition.
The environment variable user.home with the subdirectory .fonts is used.
Important: This setting is supported only by the built-in document converter OutsideIn.
Sets the default font to be used if the original font was not found and no matching character (for representation) was found in any other font with a similar font family or characteristic. Therefore, a font should be used that has the widest possible coverage of characters, especially in the Unicode range.
Note: If no font is specified, then the server tries to find a suitable font (such as "Arial Unicode MS" or "Go Noto Current"). If these fonts are not available, then the respective default font of the operating system (under Windows "Arial" and under Linux "DejaVu Sans") is used. If these are not available either, then a corresponding message appears on the server console (or in the logs).
Important: This setting is supported only by the built-in document converter OutsideIn.
Defines a set of options specific for the "OCR" web service.
Defines a set of options specific for the "Barcode" web service.
Defines a set of options specific for the "URL Converter" web service.
Sets a timeout in seconds, that shall be used for the HTTP request to get the URL.
Sets the text for the user agent to send to the destination server from which the URL is to be retrieved.
Defines a set of options specific for the "Signature" web service.
Defines a set of options specific for the "Toolbox" web service.
Defines a set of options specific for the "PDFA" web service.
Sets the base path of the server from which to retrieve installed fonts.
Defines settings for the global keystore used by the server. This keystore is used to store globally available certificates (e.g. for usage in the signature web service).
The format of the keystore file.
The password required to access the keystore.
Defines information about one entry of a keystore.
The alias under which the keystore entry was saved.
The password of the keystore entry.
Defines filters for the certificates used from the keystore.
Defines a filter pattern that allows the use of '*' and '?' wildcards.
Defines a TSA (Time Stamp Authority which supports RFC3161) that shall be used by the server.
The URL where the TSA can be reached.
The username required for authentication with the TSA.
The password required for authentication with the TSA.
The hashing algorithm used to check the validity of the timestamp.
Defines the settings for the SharePoint Bridge. The SharePoint Bridge can be used as an alternative (to the built-in conversion) for converting Office documents. The SharePoint Bridge uses SharePoint Online and therefore requires the corresponding Microsoft 365 service and a registered application on the Microsoft identity platform
When set to true the SharePoint Online bridge shall be enabled.
Defines the settings for the MS Office Bridge. The Office Bridge can be used as an alternative (to the built-in conversion) for converting Office documents. The Office Bridge requires a local installation of MS Office on the server and works only on Windows.
Defines settings specific for the MS Word application in the office bridge.
Defines settings specific for the MS Excel application in the office bridge.
Defines settings specific for the MS PowerPoint application in the office bridge.
Defines settings specific for the MS Visio application in the office bridge.
If enabled, then the MS Office bridge is activated.
If enabled, then MS Word is usable via the Office bridge.
If enabled, then MS Excel is usable via the Office bridge.
If enabled, then MS PowerPoint is usable via the Office bridge.
If enabled, then MS Visio is usable via the Office bridge.
If enabled, then all debug messages of the Office Bridge will be visible in the Windows application "SysInternals DebugView"
Defines the settings for the Chromium bridge. The Chromium bridge is used for converting emails and HTML documents.
If enabled, then the Chromium bridge is activated.
The port on which Chromium should listen for requests.
Sets a custom base path for the Chromium application.
The IP address on which Chromium should be reachable.
Sets this option whether the Chromium process should run in a sandbox or not.
Important: Be aware that running Chromium outside a sandbox can be a security risk. Proceed with caution!
Sets the headless mode (for unattended environments) when the Chromium instance starts.
Allows you to define a list of command line switches that will be passed to the Chromium process. These values must be valid and fully declared switches that are passed unchanged to the Chromium process. Switches passed in this way have priority over all other defined switches.
Defines a single command line switch for the Chromium process. This switch consists of a name for the switch and an associated value.
Sets the name of the Chromium command line switch. The name must be spelled correctly (without "--" and in correct upper/lower case), because it will be used unchanged.
Sets the mode for the command line switch.
Defines the operation mode for the command line switch.
Defines the different headless modes of the Chromium instance.
Defines settings for the user interface of the portal.
Specifies whether the portal page should display the maximum number of up-loadable files on the screen.
Defines whether the portal page should display the maximum available disk space on the screen.
Defines which portal functions are enabled or disabled.
When set to true the portal page shall display help and info messages.
If disabled, then the URL to PDF conversion is deactivated.
If disabled, then the "upload file" dialog is deactivated.
If deactivated, then the "convert document" dialog is deactivated.
If disabled, then the "rename document" dialog is deactivated.
If disabled, then the "OCR conversion" dialog is deactivated.
If disabled, then the "PDF/A conversion" dialog is deactivated.
If disabled, then the "rotate pages" dialog is deactivated.
If disabled, then the "delete pages" dialog is deactivated.
If disabled, then the "extract pages" dialog is deactivated.
If disabled, then the "extract content" dialog is deactivated.
If disabled, then the "add watermark" dialog is deactivated.
If disabled, then the "export as image" dialog is deactivated.
If disabled, then the "change document settings" dialog is deactivated.
If disabled, the "change document view" dialog is deactivated.
If disabled, then the "encrypt document" dialog is deactivated.
If disabled, then the "print document" dialog is deactivated.
If disabled, then the "merge document" dialog is deactivated.
If disabled, then the "split document" dialog is deactivated.
If disabled, then the "sign document" dialog is deactivated.
If disabled, then the "create Barcode" dialog is deactivated.
If disabled, then the "detect Barcode" dialog is deactivated.
If disabled, then the "edit forms" dialog is deactivated.
If disabled, then the "edit attachment" dialog is deactivated.
If disabled, then the "edit annotation" dialog is deactivated.
If disabled, then the "edit background" dialog is deactivated.
If disabled, then the "edit transitions" dialog is deactivated.
If disabled, then the "edit boxes" dialog is deactivated.
If disabled, then the "edit header/footer" dialog is deactivated.
If disabled, then the "move pages" dialog is deactivated.
If disabled, then the "edit outline" dialog is deactivated.
If disabled, then the "redact" dialog is deactivated.
If disabled, then the "sanitize" dialog is deactivated.
If disabled, then the "portfolio" dialog is deactivated.
If disabled, then the "scale pages" dialog is deactivated.
If disabled, then the "compress" dialog is deactivated.
If disabled, then the "transcribe document" dialog is deactivated.
Defines whether the portal displays a news page and where the content is loaded from.
Interval in seconds at which the content should be reloaded.
Defines a source for the entries in the "news panel" of the portal page".
URL from which to load the content for the "news panel".
Defines a proxy server that shall be known to and used by the server to access external resources.
The scheme to access the proxy server (currently only "http" or "https" are allowed).
The address of the proxy server.
The port on which the proxy listens.
The name of the user required to authenticate with the proxy server.
The password of the user required to authenticate with the proxy server.
When enabled, the proxy will be bypassed for local addresses such as localhost, 127.0.0.1, [::1], and addresses without a dot (e.g., "intranet").
Enables or disables this proxy configuration. When disabled, the proxy will not be used even if configured.
A single host entry for which the proxy should be bypassed. Wildcards ('*') are supported for pattern matching.
Defines settings specific for the MS Visio application in the office bridge.
If this option is enabled, the Office Bridge application is started in test mode when the server is initialized, which provides advanced debugging information.
The time in seconds to wait for the OLE server to start during initialization.
The time in seconds to wait for the OLE server to terminate at shutdown.
The minimum time frame provided for the execution of an operation with the Office bridge.
The portal element defines settings for the portal page of the server.
Defines which portal functions are enabled or disabled.
Defines settings for the user interface of the portal.
Defines whether the portal displays a news page and where the content is loaded from.
Defines global settings for the web service calls made from the portal page.
Defines which settings apply for authentication to the portal.
Defines global settings for the web service calls made from the portal page.
Defines the profile whose rules web services have to check before they can come to execution. These profiles define a set of rules concerning the validity of signatures. A web service whose execution for a given signed document would violate the rule set selected here should instead abort with an appropriate error code.
Important: You can find further explanations of these profiles in the chapter "Signature Validation".
Sets the profile for automatic document compression and thus defines whether compression should be applied when saving.
Defines which settings apply for authentication to the portal.
Defines the timeout settings related to authentication and session.
Defines whether the login for the front end portal page is available or not. This has no effect on the admin page, which is always available.
If enabled, then anonymous login (without username and password) are allowed on the front end portal page. This has no effect on the admin page, which always denies anonymous access.
Defines the timeout settings related to authentication and session.
Defines the time in seconds after which a user should be considered inactive if no activity is detected in the portal. If the value is '0', then the detection is disabled, i.e. the user is never inactive.
Defines the time in seconds before the access token expires at which an auto-refresh is performed. The auto-refresh prevents the session from expiring and the access token from becoming unusable. If the user is considered inactive, then a dialog is displayed before the auto-refresh is executed. If the value is '0', then the auto-refresh is disabled, i.e. the session ends when the access token expires.
Defines the settings for the registered application on the Microsoft identity platform for access to the SharePoint Online site
The ID of the application that was assigned during creation
The id of the tenant to which the application belongs
The secret that was generated for the application
Defines the name of the Sharepoint Online site that is used for document conversion. Access to the site must be configured as a registered application on the Microsoft identity platform
The name of the site to be used for converting the documents
Defines how the size of the queue is determined.
With AUTO, it is calculated automatically by the server based on the number of configured instances.
Defines the configuration for collecting and exporting application metrics using the Micrometer framework.
Metrics are collected across multiple architectural layers:
Metrics can be exported to Prometheus and/or JMX for monitoring and visualization in tools like Grafana.
Configures general application-wide metrics settings including percentiles, cardinality limits, and common tags.
These settings apply globally to all metric types unless overridden by specific layer configurations.
Configures authentication requirements for accessing the /metrics HTTP endpoint.
When enabled, clients must provide valid credentials via Basic Auth or Bearer Token.
Primary configuration is defined directly in this XML block via attributes
username, password and token.
Optional runtime overrides can be applied via environment variables or system properties. Runtime overrides have higher priority than XML values.
WEBPDF_METRICS_AUTH_USERNAME
/ webpdf.metrics.auth.username
WEBPDF_METRICS_AUTH_PASSWORD
/ webpdf.metrics.auth.password
WEBPDF_METRICS_AUTH_TOKEN
/ webpdf.metrics.auth.token
Configures metrics collection for the HTTP transport layer (Layer 1).
Measures complete HTTP request lifecycle including network I/O, authentication, CORS, and routing overhead.
Collected metrics include:
http_server_requests: Total request duration timer
http_server_requests_active: Currently active HTTP requests gauge
http_server_request_size: HTTP request body size distribution
http_server_response_size: HTTP response body size distribution
http_server_errors_client: 4xx client error counter
http_server_errors_server: 5xx server error counter
Configures metrics collection for the REST API layer (Layer 2).
Tracks Jersey REST endpoint execution including request deserialization, resource method invocation, and response serialization.
Collected metrics include:
api_operation_duration: REST endpoint processing time timer
Configures metrics collection for the business logic layer (Layer 3).
Monitors the execution of business logic (web service operation) in terms of duration, invocations and number of errors.
Collected metrics include:
service_method_duration: Total request duration from worker submission to response
service_method_requests_total: Total service method invocation counter
service_method_errors_total: Failed service method invocation counter
Applied to all server classes annotated with @TimedService.
Configures metrics collection for the thread pool and worker execution layer (Layer 4).
Tracks thread pool (web service instances) utilization, queue depth, and worker lifecycle metrics.
Collected metrics include:
threadpool_active: Currently active worker threads gauge
threadpool_size: Thread pool size gauge
threadpool_queue_size: Blocking queue size gauge
threadpool_queue_capacity: Maximum queue capacity gauge
threadpool_queue_remaining: Remaining queue capacity gauge
threadpool_completed: Completed task counter
threadpool_submitted: Submitted task counter
threadpool_rejected: Rejected task counter
Configures metrics collection for Java Virtual Machine (JVM) internal metrics.
Provides visibility into JVM health, memory usage, garbage collection, and thread activity.
Collected metrics include:
Essential for diagnosing memory leaks, GC issues, and performance problems.
Configures metrics collection for operating system and hardware resources.
Monitors system-level resources that affect application performance.
Collected metrics include:
Useful for capacity planning and identifying resource bottlenecks.
Configures Java Management Extensions (JMX) registry for metrics export.
JMX metrics can be viewed using standard tools like JConsole, VisualVM, or JMC (Java Mission Control).
Useful for local development and troubleshooting without requiring external monitoring systems.
Configures Prometheus registry for metrics export.
Prometheus is the primary time-series database for production monitoring and can be visualized using Grafana dashboards.
Metrics are exposed via HTTP endpoint at /metrics in Prometheus text exposition format.
Prometheus server scrapes this endpoint periodically to collect metrics.
Selects a predefined configuration preset optimized for different environments.
Available presets:
production: Optimized for production with minimal overhead (percentiles disabled, cardinality limits enabled)
development: Full metrics with percentiles for local development and debugging
minimal: Only essential metrics enabled (API and service layers)
custom: Use explicit configuration from child elements
Individual settings can override preset defaults when specified explicitly.
Master switch for the complete metrics subsystem.
When set to false, no metrics are collected, exported, or exposed via endpoint/filter integrations.
This setting has precedence over all other metrics options and layer flags.
Default:
true
Base type for metric layer configuration.
Provides a common enabled attribute to control whether the metrics collection is active for a specific layer.
Enables or disables metrics collection for this layer.
When disabled, no metrics are collected or exported, reducing overhead.
Default:
true
Configuration for HTTP transport layer metrics (Layer 1).
Inherits enabled attribute from MetricsBasicType.
Configuration for REST API layer metrics (Layer 2).
Inherits enabled attribute from MetricsBasicType.
Configuration for business logic layer metrics (Layer 3).
Inherits enabled attribute from MetricsBasicType.
Configuration for thread pool and worker execution layer metrics (Layer 4).
Inherits enabled attribute from MetricsBasicType.
Configuration for Java Virtual Machine internal metrics.
Inherits enabled attribute from MetricsBasicType.
Configuration for operating system and hardware resource metrics.
Inherits enabled attribute from MetricsBasicType.
Configuration for Java Management Extensions (JMX) metrics export.
JMX allows metrics to be accessed via standard Java management tools like JConsole, VisualVM, and JMC.
Enables or disables JMX metrics export.
When enabled, metrics are registered as MBeans and can be viewed in JMX-compatible tools.
Default:
true
Specifies the JMX domain name under which metrics are registered.
The domain groups related MBeans together in JMX management tools.
Default:
webpdf.metrics
Example ObjectName:
webpdf.metrics:name=http_server_requests,type=timers
Configuration for Prometheus metrics export.
Prometheus is a time-series monitoring system that scrapes metrics from HTTP endpoints.
When enabled, metrics are exposed at /metrics endpoint in Prometheus text format.
Enables or disables Prometheus metrics export.
When enabled, metrics are available at the /metrics HTTP endpoint.
Prometheus server should be configured to scrape this endpoint periodically.
Default:
true
Defines application-wide metrics configuration including percentiles, cardinality limits, and common tags.
These settings affect memory usage and metric granularity across all metric types.
Defines custom percentile values for timer metrics (e.g., p50, p95, p99).
Percentiles provide statistical distribution data but consume significant memory (~1MB per timer).
If not specified and percentilesEnabled="true", defaults to [0.5, 0.95, 0.99].
A single percentile value between 0.0 and 1.0.
Common values: 0.5 (median), 0.95 (95th percentile), 0.99 (99th percentile), 0.999 (99.9th percentile)
Enables or disables percentile calculation for timer metrics.
When enabled, percentile distributions (p50, p95, p99) are calculated and exported.
Memory Impact: Each timer with percentiles consumes approximately 1MB of memory.
Recommendation: Disable in production to reduce memory footprint (~560MB savings for typical deployment).
Default:
true
Common tag value applied to all metrics as application="...".
This tag identifies the application in multi-tenant monitoring systems like Prometheus.
Useful when multiple applications export metrics to the same monitoring infrastructure.
Default:
webPDF
Example metric:
http_server_requests{application="webPDF",method="POST"}
Enables or disables the HTTP metrics endpoint at /metrics.
When disabled, metrics are still collected but not exposed via HTTP.
This is useful when using only JMX export or when metrics should not be accessible externally.
Default:
true
Maximum number of unique REST endpoints to track separately.
Limits metric cardinality to prevent memory exhaustion from dynamic URLs.
When limit is reached, additional endpoints share a common metric with tag endpoint="overflow".
Value -1 means unlimited (not recommended for production).
Default: -1 (unlimited)
Recommendation: Set to 100-500 in production environments.
Maximum number of unique URI paths to track separately in HTTP metrics.
Prevents cardinality explosion from dynamic URI segments or query parameters.
When limit is reached, additional URIs share a common metric with tag uri="overflow".
Value -1 means unlimited (not recommended for production).
Default: -1 (unlimited)
Recommendation: Set to 100-500 in production environments.
Maximum number of unique HTTP status codes to track separately.
Limits metric cardinality for HTTP status code tags.
Value -1 means unlimited.
Default: -1 (unlimited)
Note: Status codes are typically limited (~60 standard codes), so this rarely needs adjustment.
Threshold for logging a warning when total metric count exceeds this value.
High metric counts indicate potential cardinality explosion and memory issues.
Use this to detect unbounded metric growth in production.
Default:
10000
Guideline: Typical deployments should have <5000 metrics. Over 10000 indicates configuration issues.
Configures authentication requirements for accessing the /metrics endpoint.
When enabled, prevents unauthorized access to application metrics which may contain sensitive information.
Primary credentials are configured via XML attributes username, password and token.
Environment variables and system properties are optional runtime overrides and take precedence over XML values.
If both Basic Auth credentials (username/password) and a Bearer token
(token) are configured, both authentication methods are active at the same time.
At request runtime, the method is selected by the HTTP Authorization scheme
(Basic or Bearer).
Enables or disables authentication for the metrics endpoint.
When enabled, requests must include valid credentials:
username/password or override via
WEBPDF_METRICS_AUTH_USERNAME / webpdf.metrics.auth.username and
WEBPDF_METRICS_AUTH_PASSWORD / webpdf.metrics.auth.password
token or override via
WEBPDF_METRICS_AUTH_TOKEN / webpdf.metrics.auth.token
When disabled, metrics endpoint is publicly accessible (suitable for development only).
Default:
true
Security: Always enable in production environments to protect sensitive operational data.
Username used for Basic Auth on the metrics endpoint.
Default:
prometheus
Primary source: XML attribute username.
Can be overridden via WEBPDF_METRICS_AUTH_USERNAME or webpdf.metrics.auth.username.
Password used for Basic Auth on the metrics endpoint.
Primary source: XML attribute password.
Can be overridden via WEBPDF_METRICS_AUTH_PASSWORD or webpdf.metrics.auth.password.
Bearer token used as alternative authentication on the metrics endpoint.
Primary source: XML attribute token.
Can be overridden via WEBPDF_METRICS_AUTH_TOKEN or webpdf.metrics.auth.token.
Predefined metric configuration presets optimized for different deployment environments.
Presets provide sensible defaults that can be overridden by explicit element configurations.
Optimized for production environments with minimal memory overhead.
Suitable for production deployments where stability and resource efficiency are priorities.
Full-featured configuration for local development and debugging.
Suitable for development environments where detailed metrics are needed for troubleshooting.
Minimal configuration with only essential business metrics.
Suitable for constrained environments or when only business KPIs are needed.
No preset defaults applied - all configuration must be explicitly specified.
Provides complete control over every metric configuration parameter.
Use when fine-grained customization is required beyond standard presets.