Skip to content

Configuration Properties

Jump to bottom
Philip Helger edited this page May 14, 2026 · 49 revisions

Configuration Properties

All properties are located in the file application.properties which resides in src/main/resources of the phoss-ap-webapp module.

All configuration properties are resolved according to the rules described in https://github.com/phax/ph-commons/wiki/ph-config

Duration values (since 0.9.0)

Many time-related properties accept a duration grammar since v0.9.0. The format is one or more [sign]<number><unit> segments, summed together, with optional whitespace between segments. Supported units:

Suffix Meaning
ns nanoseconds
us microseconds
ms milliseconds
s seconds
m minutes
h hours
d days

Examples: 5s, 1m 30s, 2d 12h, 90d.

The previous millisecond-typed keys (with .ms / .millis suffix) continue to be honored for backwards compatibility, but a deprecation warning is logged when they are used. The legacy .ms / .millis keys will be removed in v1.0.0. Migrate to the new duration-grammar keys as soon as possible.

Table of Contents

General Configuration

  • global.debug: Enable or disable overall debug mode. Enables additional checks that should not be active in production (e.g. verbose logging, slower validation). Default is false.
  • global.production: Enable or disable overall production mode. When false, certain production-only functionality may be disabled. Default is false.
  • global.nostartupinfo: Set to true to suppress the startup information banner. Default is false.
  • global.datapath: The path where all relevant data files are stored (e.g. keystores, dumps, logs). Should be an absolute path in production (e.g. /var/phoss-ap/data).

Peppol Configuration

  • peppol.stage: The Peppol network stage. Either test or prod. Determines which PKI certificates and SML endpoints are used.
  • peppol.owner.seatid: The Peppol Seat ID of this AP (e.g. POP000000). Used in reporting and MLS processing.
  • peppol.owner.countrycode: The 2-letter country code of the AP operator. Used as C2 or C3 country in reporting context.
  • peppol.receiver-check.mode (since v0.1.3): Controls how incoming messages are verified against SMP registrations. Possible values:
    • none (default) — Receiver checks are disabled.
    • smp — Uses a fixed SMP URL for verification. Requires peppol.smp.url and phase4.endpoint.address to be set.
    • sml — Uses dynamic per-participant SMP resolution via the SML derived from the configured peppol.stage. Requires phase4.endpoint.address to be set.
  • peppol.smp.url: The URL of this AP's own SMP (e.g. http://localhost:8080). Required when peppol.receiver-check.mode=smp.
  • peppol.dns.servers (since v0.1.3): Comma-separated list of DNS server hostnames or IP addresses to use for Peppol NAPTR lookups (e.g. 8.8.8.8,8.8.4.4). Optional. When not set, the system default DNS resolver is used.
  • peppol.identifier.mode: The Peppol identifier validation mode. Either strict or lax. In strict mode (default), all Peppol identifier rules are enforced. In lax mode, identifier validation is more lenient. Default is strict.
  • peppol.revocation.soft-fail (since 0.9.0): Global soft-fail mode for certificate revocation checks. When true, certificate validation succeeds even if the revocation status cannot be determined (e.g. CRL/OCSP responder unreachable due to a network error). Maps to CertificateRevocationCheckerDefaults.setAllowSoftFail(boolean). Default is false (hard fail on indeterminate revocation status).

AS4 Keystore and Truststore

These properties configure the cryptographic material used by phase4 for AS4 message signing, encryption, and certificate validation.

AP Keystore (signing and decryption)

  • org.apache.wss4j.crypto.merlin.keystore.type: Keystore type. Either JKS or PKCS12. Default is JKS.
  • org.apache.wss4j.crypto.merlin.keystore.file: Path to the keystore file containing the AP certificate and private key.
  • org.apache.wss4j.crypto.merlin.keystore.password: Password for the keystore.
  • org.apache.wss4j.crypto.merlin.keystore.alias: Alias of the key entry within the keystore.
  • org.apache.wss4j.crypto.merlin.keystore.private.password: Password for the private key entry.

AP Truststore (validating remote AP certificates)

  • org.apache.wss4j.crypto.merlin.truststore.type: Truststore type. Either JKS or PKCS12. Default is PKCS12.
  • org.apache.wss4j.crypto.merlin.truststore.file: Path to the truststore file for validating incoming AS4 message signatures.
  • org.apache.wss4j.crypto.merlin.truststore.password: Password for the truststore.

SMP Client Configuration

These properties configure the SMP client used for outbound SMP lookups (to resolve receiver AP endpoints).

  • smpclient.truststore.type: Truststore type for SMP client TLS connections. Either JKS or PKCS12. Default is PKCS12.
  • smpclient.truststore.path: Path to the truststore file for SMP client connections.
  • smpclient.truststore.password: Password for the SMP client truststore.

Database Configuration

PostgreSQL and MySQL are the supported databases. The database schema is managed automatically via Flyway.

JDBC configuration properties are defined by JdbcConfigurationConfig from ph-db. All properties use the prefix phossap.jdbc..

  • phossap.jdbc.database-type: The target database type. Either PostgreSQL or MySQL.
  • phossap.jdbc.driver: The JDBC driver class. For PostgreSQL use org.postgresql.Driver. For MySQL use com.mysql.cj.jdbc.Driver.
  • phossap.jdbc.url: The JDBC URL of the database. Example for PostgreSQL: jdbc:postgresql://localhost:5432/phossap. Example for MySQL: jdbc:mysql://localhost:3306/phoss-ap?useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false. It's recommended to not use the serverTimezone parameter.
  • phossap.jdbc.user: The database user.
  • phossap.jdbc.password: The password of the database user.
  • phossap.jdbc.schema: The database schema to use. For PostgreSQL defaults to public. Not used for MySQL (the database name in the JDBC URL serves this purpose).
  • phossap.jdbc.execution-time-warning.enabled: Enable or disable logging of long-running JDBC transactions. Default is true.
  • phossap.jdbc.execution-time-warning.ms: Threshold in milliseconds for the long-running JDBC transaction warning. Default is 1000.
  • phossap.jdbc.debug.connections: Enable or disable debug logging of JDBC connection lifecycle (open/close). Default is false.
  • phossap.jdbc.debug.transactions: Enable or disable debug logging of JDBC transactions (begin/commit/rollback). Default is false.
  • phossap.jdbc.debug.sql: Enable or disable debug logging of executed SQL statements. Default is false.

Connection Pooling

  • phossap.jdbc.pooling.max-connections: Maximum number of active connections in the pool. Default is 8.
  • phossap.jdbc.pooling.max-wait (since 0.9.0): Maximum time to wait for a connection from the pool before throwing an exception. Default is 10s.
  • phossap.jdbc.pooling.max-wait.millis (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 10000.
  • phossap.jdbc.pooling.between-evictions-runs (since 0.9.0): Interval between runs of the idle connection evictor. Default is 5m.
  • phossap.jdbc.pooling.between-evictions-runs.millis (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 300000.
  • phossap.jdbc.pooling.min-evictable-idle (since 0.9.0): Minimum idle time before a connection is eligible for eviction. Default is 30m.
  • phossap.jdbc.pooling.min-evictable-idle.millis (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 1800000.
  • phossap.jdbc.pooling.remove-abandoned-timeout (since 0.9.0): Timeout before an abandoned connection can be removed. Default is 5m.
  • phossap.jdbc.pooling.remove-abandoned-timeout.millis (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 300000.

Flyway

Configuration properties for Flyway database migrations, as defined by FlywayConfigurationBuilderConfig from ph-db. All properties use the prefix flyway. and fall back to the main JDBC properties if not explicitly set.

  • phossap.flyway.enabled: Enable or disable Flyway database migrations on startup. Default is true.
  • phossap.flyway.jdbc.url: Optional separate JDBC URL for Flyway migrations. Falls back to phossap.jdbc.url if not set.
  • phossap.flyway.jdbc.user: Optional separate database user for Flyway. Falls back to phossap.jdbc.user if not set.
  • phossap.flyway.jdbc.password: Optional separate database password for Flyway. Falls back to phossap.jdbc.password if not set.
  • phossap.flyway.jdbc.schema-create: Whether Flyway should attempt to create the database schema. Default is false.
  • phossap.flyway.baseline.version: The Flyway baseline version (integer). Used when baselining an existing database. Default is 0.
  • phossap.flyway.history-table (since 0.2.2): Custom name for the Flyway schema history table. If not set, the Flyway default (flyway_schema_history) is used.
  • phossap.flyway.debug-mode (since 0.2.2): Enable Flyway debug logging during migration execution. Default is false.
  • phossap.flyway.repair-mode (since 0.2.2): Run Flyway's repair() before executing migrations to fix inconsistencies in the schema history table. Default is false.

Peppol Reporting SQL Backend

The peppol-reporting library uses its own database for storing Peppol Reporting items (TSR/EUSR). It defines JDBC properties under the prefix peppol.reporting.jdbc. and Flyway properties under peppol.reporting.flyway.. See the peppol-reporting SQL backend configuration for the full list of properties.

When sharing the same database as phoss-ap, set a custom Flyway history table to avoid conflicts:

  • peppol.reporting.flyway.history-table: Custom name for the Flyway schema history table used by peppol-reporting. If not set, the Flyway default (flyway_schema_history) is used — which would conflict with the phoss-ap history table when using the same database. Example: flyway_schema_history_reporting.

Peppol Report Sending SQL Backend

The peppol-ap-support library uses its own database for tracking Peppol Report sending state. It defines JDBC properties under the prefix peppol.report.jdbc. and Flyway properties under peppol.report.flyway.. See the peppol-ap-support SQL backend configuration for the full list of properties.

When sharing the same database as phoss-ap, set a custom Flyway history table to avoid conflicts:

  • peppol.report.flyway.history-table: Custom name for the Flyway schema history table used by peppol-ap-support. If not set, the Flyway default (flyway_schema_history) is used — which would conflict with the phoss-ap history table when using the same database. Example: flyway_schema_history_report.

API Configuration

  • phase4.endpoint.address: The public AS4 endpoint URL of this AP (e.g. https://ap.example.com/as4). Used by phase4 for endpoint comparison and in reporting.
  • phase4.api.requiredtoken: The API token required for authenticating REST API calls (sent via X-Token header). If empty or not set, API authentication is disabled.

Document Storage

Document payloads (SBD files) are stored outside the database. The storage backend is selected via storage.mode — either the local filesystem (default) or Amazon S3.

  • storage.mode: The document storage backend. Either filesystem (default) or s3. When set to s3, documents are stored in an S3 bucket and their paths are recorded as s3://bucket/key URIs in the database. When set to filesystem, documents are stored as flat files on disk.
  • storage.inbound.path: Base path for inbound document storage. Used by all storage modes — as a filesystem directory when storage.mode=filesystem, or as a key path component when storage.mode=s3. Default is ${user.home}/phoss-ap/inbound.
  • storage.outbound.path: Base path for outbound document storage. Used by all storage modes — as a filesystem directory when storage.mode=filesystem, or as a key path component when storage.mode=s3. Default is ${user.home}/phoss-ap/outbound.

S3 Storage Backend (since 0.1.1)

These properties configure the S3 bucket used as the document storage backend when storage.mode=s3. All document payloads (both inbound and outbound) are stored in this bucket. Document paths in the database are recorded as s3://bucket/key URIs.

  • storage.s3.bucket: (Required when storage.mode=s3) The S3 bucket name for document storage.
  • storage.s3.region: (Required when storage.mode=s3) The AWS region of the S3 bucket (e.g. eu-central-1).
  • storage.s3.access-key-id: AWS access key ID for S3 access. Optional — if not set, the default AWS credential chain is used (IAM roles, environment variables, etc.).
  • storage.s3.secret-access-key: AWS secret access key for S3 access. Optional — if not set, the default AWS credential chain is used.
  • storage.s3.endpoint (since 0.2.2): Custom S3 endpoint URL for S3-compatible providers (e.g. MinIO, Garage). Optional — if not set, standard AWS S3 is used.
  • storage.s3.path-style-access (since 0.2.2): Enable S3 path-style access instead of virtual-hosted style. Required by most S3-compatible providers. Default is false.

Note: The S3 storage backend is independent of the S3 forwarding mode (forwarding.mode=s3_link). S3 storage affects where the AP persists document payloads internally, while S3 forwarding controls how received documents are delivered to the Receiver Backend. Both can be used simultaneously.

Outbound S3 Submission (since 0.1.1)

These properties configure the AP's ability to fetch outbound documents from an S3 bucket provided by the Sender Backend, instead of receiving the document payload inline via the HTTP request body.

When enabled, the Sender Backend uploads the document to its own S3 bucket and then calls the POST /api/outbound/submit-s3 endpoint with the S3 bucket/key reference plus Peppol metadata. The AP fetches the document from S3 and processes it through the normal outbound pipeline.

  • outbound.s3.enabled: Enable or disable the /api/outbound/submit-s3 endpoint. Default is false.
  • outbound.s3.bucket: Default S3 bucket from which the AP fetches sender-uploaded documents. Can be overridden per request in the JSON body. Optional if always specified in the request.
  • outbound.s3.region: (Required when outbound.s3.enabled=true) The AWS region of the sender's S3 bucket (e.g. eu-central-1).
  • outbound.s3.access-key-id: AWS access key ID for accessing the sender's S3 bucket. Optional — if not set, the default AWS credential chain is used.
  • outbound.s3.secret-access-key: AWS secret access key for accessing the sender's S3 bucket. Optional — if not set, the default AWS credential chain is used.
  • outbound.s3.endpoint (since 0.2.2): Custom S3 endpoint URL for S3-compatible providers (e.g. MinIO, Garage). Optional — if not set, standard AWS S3 is used.
  • outbound.s3.path-style-access (since 0.2.2): Enable S3 path-style access instead of virtual-hosted style. Required by most S3-compatible providers. Default is false.

Note: The sender's S3 bucket (configured here) may differ from the AP's storage S3 bucket (configured under storage.s3.*). The outbound S3 submission endpoint fetches from the sender's bucket and stores through the AP's own IDocumentPayloadManager (which may itself be S3-backed or filesystem-backed).

Sending Configuration

  • peppol.sending.enabled: Enable or disable outbound AS4 sending. Set to false to operate as a receive-only AP. Default is true.

Receiving Configuration

  • peppol.receiving.enabled: Enable or disable inbound AS4 receiving. Set to false to operate as a send-only AP. Default is true.

Forwarding Configuration

  • forwarding.mode: (Required) Selects the active forwarding implementation. One of: http_post_sync, http_post_async, s3_link, sftp, filesystem. Must be explicitly configured — there is no default.
  • forwarding.c4countrycode.modes (since v0.1.3): Comma-separated list of modes to try (in order) for automatically determining the C4 country code after successful inbound forwarding. Available modes: receiver_pid (derive from receiver participant ID scheme), business_card (look up from Peppol Directory Business Card via SMP). The asynchronous reporting API (POST /api/inbound/report) always remains available as an additional fallback. Default is empty (no automatic determination). Example: receiver_pid,business_card.

HTTP POST Forwarding

  • forwarding.http.endpoint: The URL of the Receiver Backend endpoint to POST the SBD to.

Custom HTTP Headers (since v0.2.0)

Custom HTTP headers can be added to every forwarding request using indexed properties. This is useful for authentication (e.g., Bearer tokens, API keys) or passing custom metadata to the Receiver Backend.

  • forwarding.http.headers.{n}.name: The header name (case-insensitive). {n} is a 1-based index.
  • forwarding.http.headers.{n}.value: The header value.

Headers are read sequentially starting from index 1. The sequence stops at the first missing .name entry.

Example:

forwarding.http.headers.1.name=Authorization
forwarding.http.headers.1.value=Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
forwarding.http.headers.2.name=X-Tenant-ID
forwarding.http.headers.2.value=customer-42

The HTTP client used for forwarding is configured via HttpClientSettingsConfig from ph-web with the prefix forwarding.. All properties below are optional and have sensible defaults.

Timeouts

  • forwarding.http.timeout.connect.millis (or .seconds, .minutes, .hours): Connect timeout for the HTTP POST.
  • forwarding.http.timeout.response.millis (or .seconds, .minutes, .hours): Response/read timeout for the HTTP POST.
  • forwarding.http.timeout.connectionrequest.millis (or .seconds, .minutes, .hours): Timeout for obtaining a connection from the pool.

Retry

  • forwarding.http.retry.count: Number of HTTP-level retries (integer, >= 0). Not set by default.
  • forwarding.http.retry.interval.millis (or .seconds, .minutes, .hours): Interval between HTTP-level retries.
  • forwarding.http.retry.always: Whether to retry on all failures (boolean). Default is the HttpClient default.

Proxy

  • forwarding.http.proxy.enabled: Enable a separate HTTP proxy for forwarding requests. Default is false.
  • forwarding.http.proxy.host: Proxy hostname.
  • forwarding.http.proxy.port: Proxy port (integer).
  • forwarding.http.proxy.username: Proxy authentication username.
  • forwarding.http.proxy.password: Proxy authentication password.
  • forwarding.http.proxy.nonProxyHosts: Pipe-separated list of hosts that bypass the proxy.

TLS

  • forwarding.http.tls.checks.disabled: Disable all TLS checks (hostname + certificate). Default is false. Security risk — use only for testing.
  • forwarding.http.tls.hostname-check.disabled: Disable TLS hostname verification only. Default is false.
  • forwarding.http.tls.certificate-check.disabled: Disable TLS certificate verification only. Default is false.

Miscellaneous

  • forwarding.http.useragent: Custom User-Agent header for forwarding requests.
  • forwarding.http.follow-redirects: Whether to follow HTTP redirects. Default is the HttpClient default.
  • forwarding.http.keep-alive: Whether to use HTTP keep-alive connections. Default is the HttpClient default.
  • forwarding.http.dnsclientcache.use: Whether to use the DNS client cache.
  • forwarding.http.protocol-upgrade.enabled: Enable HTTP/2 protocol upgrade. Default is the HttpClient default.

S3 Forwarding

  • forwarding.s3.bucket: The S3 bucket name where received SBDs are stored.
  • forwarding.s3.region: The AWS region of the S3 bucket (e.g. eu-central-1).
  • forwarding.s3.access-key-id: AWS access key ID for S3 access. Optional if using IAM roles.
  • forwarding.s3.secret-access-key: AWS secret access key for S3 access. Optional if using IAM roles.
  • forwarding.s3.endpoint (since 0.2.2): Custom S3 endpoint URL for S3-compatible providers (e.g. MinIO, Garage). Optional — if not set, standard AWS S3 is used.
  • forwarding.s3.path-style-access (since 0.2.2): Enable S3 path-style access instead of virtual-hosted style. Required by most S3-compatible providers. Default is false.
  • forwarding.s3.key-prefix: Optional prefix (folder path) for S3 object keys.

SFTP Forwarding

  • forwarding.sftp.host: The hostname or IP address of the SFTP server.
  • forwarding.sftp.port: The port of the SFTP server. Default is 22.
  • forwarding.sftp.connectiontimeoutms: Connection timeout in milliseconds. Default is defined by ISftpSettingsHost.DEFAULT_CONNECTION_TIMEOUT_MS.
  • forwarding.sftp.user: The username for SFTP authentication.
  • forwarding.sftp.password: The password for SFTP authentication. Either this or a key pair must be provided.
  • forwarding.sftp.keypair.privatekeypath: Path to the private key file for key-based authentication.
  • forwarding.sftp.keypair.publickeypath: Path to the public key file for key-based authentication.
  • forwarding.sftp.keypair.passphrase: Optional passphrase for the key pair.
  • forwarding.sftp.knownhostspath: Path to the SSH known_hosts file for host key verification. Optional — if not set, host key checking may be skipped.
  • forwarding.sftp.maxconnections: Maximum number of parallel SFTP connections. Default is defined by ISftpSettingsHost.DEFAULT_MAX_CONNECTIONS.
  • forwarding.sftp.uploaddir: The remote directory on the SFTP server where SBDs are uploaded.

Filesystem Forwarding (since v0.2.0)

Writes the received SBD to a local directory. Useful for integrations where the Receiver Backend picks up files from a shared filesystem or NFS mount.

  • forwarding.filesystem.directory: (Required when forwarding.mode=filesystem) The absolute path of the target directory. Created automatically if it does not exist.
  • forwarding.filesystem.layout: File layout mode. Either flat (default) or per-transaction.
    • flat — All files are written directly into the configured directory. Each transaction produces two files: {sbdhInstanceID}.xml (the SBD) and {sbdhInstanceID}.json (metadata).
    • per-transaction — Each transaction gets its own subdirectory named by SBDH Instance ID, containing sbd.xml and metadata.json.

Files are written atomically using a .tmp extension and renamed after the transfer completes, so the Receiver Backend never sees partial files. If a file with the same SBDH Instance ID already exists (e.g., due to duplicate detection in store_and_flag mode), a numeric suffix is appended to ensure uniqueness.

The metadata JSON file contains: sbdhInstanceID, senderID, receiverID, docTypeID, processID, as4MessageID, c1CountryCode, and receivedDT.

Delivery confirmation: No — MLS response code is AB (Accepted Blind), same as S3 and SFTP modes.

Retry Configuration

Retry behavior is defined via customizable Java interfaces. The following properties configure the default retry strategy.

  • retry.sending.max-attempts: Maximum number of AS4 sending attempts for outbound transactions before marking as permanently failed. Default is 3.
  • retry.sending.initial-backoff (since 0.9.0): Initial backoff interval between sending retries. Default is 3m.
  • retry.sending.initial-backoff.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 180000.
  • retry.sending.backoff-multiplier: Multiplier applied to the backoff interval after each failed attempt (exponential backoff). Default is 2.0.
  • retry.sending.max-backoff (since 0.9.0): Maximum backoff interval. Default is 1h.
  • retry.sending.max-backoff.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 3600000.
  • retry.forwarding.max-attempts: Maximum number of forwarding attempts for inbound transactions before marking as permanently failed. Default is 3.
  • retry.forwarding.initial-backoff (since 0.9.0): Initial backoff interval between forwarding retries. Default is 1m.
  • retry.forwarding.initial-backoff.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 60000.
  • retry.forwarding.backoff-multiplier: Multiplier applied to the backoff interval after each failed forwarding attempt. Default is 2.0.
  • retry.forwarding.max-backoff (since 0.9.0): Maximum backoff interval for forwarding retries. Default is 1h.
  • retry.forwarding.max-backoff.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 3600000.
  • retry.scheduler.interval (since 0.9.0): Interval at which the retry scheduler checks for transactions eligible for retry. Default is 1m. Safe to enable on all instances — uses SKIP LOCKED for work distribution.
  • retry.scheduler.interval.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 60000.
  • retry.scheduler.batch-size (since 0.1.2): Maximum number of transactions to retry per scheduler cycle (inbound and outbound each). Must be >= 1. Default is 50.

Circuit Breaker

Per-C3 circuit breaker for outbound AS4 sending. Implemented in-memory using Failsafe. See Retry and Resilience Patterns for details.

  • circuit-breaker.failure-threshold: Number of consecutive failures to a C3 endpoint before the circuit breaker opens. Default is 5.
  • circuit-breaker.open-duration (since 0.9.0): Duration the circuit breaker stays open before transitioning to half-open. Default is 1m.
  • circuit-breaker.open-duration.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 60000.
  • circuit-breaker.half-open-max-attempts: Number of probe attempts allowed through in half-open state to test if the C3 endpoint has recovered. Default is 1.

Verification Configuration

  • verification.outbound.enabled: Enable or disable optional verification of outbound documents before AS4 sending. Default is false.
  • verification.inbound.enabled: Enable or disable optional verification of inbound documents before forwarding. Default is false.
  • verification.phorm.url: Base URL of the phorm Validation Service used for document verification (e.g. http://localhost:8080). Default is http://localhost:8080.
  • verification.phorm.token: The X-Token header value required by the phorm Validation Service for authentication. If empty, no token is sent.

The built-in verification implementation (phoss-ap-validation module) calls the phorm Validation Service's /api/dd_and_validate/ endpoint. The service auto-detects the document type and validates it against Peppol BIS rules. If the overall validation conformance is INVALID, the document is rejected. Custom verification logic can also be provided via the pluggable IDocumentVerifier SPI.

MLS Configuration

  • mls.sending.enabled (since 0.1.2): Global switch to enable or disable all outbound MLS sending. When set to false, the AP will not send any MLS responses (neither success nor failure) for inbound transactions. Default is true.
  • mls.type: The MLS sending strategy for this AP instance (as C3). Either FAILURE_ONLY or ALWAYS_SEND. Default is ALWAYS_SEND. This value is captured per inbound transaction at reception time. Only effective when mls.sending.enabled is true.

Reporting Configuration

  • peppol.reporting.schedule.enabled: Enable or disable the reporting schedule. Default is true.
  • peppol.reporting.schedule.day-of-month: Day of the month on which reporting is submitted (1-31). Default is 2.
  • peppol.reporting.schedule.hour: Hour of the day at which reporting is submitted (0-23). Default is 6.
  • peppol.reporting.schedule.minute: Minute of the hour at which reporting is submitted (0-59). Default is 7.

Duplicate Detection Configuration

  • duplicate.detection.as4.mode: Behavior when an AS4 Message ID duplicate is detected. Either reject or store_and_flag. Default is reject.
  • duplicate.detection.sbdh.mode: Behavior when an SBDH Instance Identifier duplicate is detected. Either reject or store_and_flag. Default is reject.

Archival Configuration

  • archival.scheduler.enabled: Enable or disable the periodic archival scheduler. Default is true. Safe to enable on all instances — uses SKIP LOCKED for work distribution.
  • archival.scheduler.interval (since 0.9.0): Interval at which the archival scheduler runs. Default is 1h.
  • archival.scheduler.interval.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 3600000.
  • archival.scheduler.batch-size (since 0.1.2): Maximum number of transactions to archive per scheduler cycle (inbound and outbound each). Must be >= 1. Default is 100.

Cleanup Configuration (since 0.9.0)

Periodically deletes archived inbound and outbound transactions whose completed_dt is older than the configured retention. Both the database row (and its archived attempt rows) and the associated document file are removed. Cleanup operates only on archive tables — primary tables are never touched.

Preconditions (validated at startup, otherwise InitializationException):

  • archival.scheduler.enabled must be true. Cleanup only operates on already-archived rows; it cannot run without the archiver feeding it.
  • cleanup.scheduler.retention must be at least 2 days.
  • cleanup.scheduler.retention must be greater than 2 × archival.scheduler.interval, so the archiver has time to land completed transactions before cleanup considers them.

Document file deletion is attempted before the row is deleted: a transient storage error leaves the row for the next cycle so that orphan files cannot accumulate.

Duration values use suffixes: ns, us, ms, s, m, h, d. Examples: 90d, 2d 12h, 36h. See the ph-config Duration values format.

  • cleanup.scheduler.enabled: Enable or disable the cleanup scheduler. Default is false.
  • cleanup.scheduler.interval: Interval at which the cleanup scheduler runs. Default is 24h.
  • cleanup.scheduler.retention: Retention duration. Archived transactions whose completed_dt is older than this are eligible for cleanup. Default is 90d. Minimum is 2d.
  • cleanup.scheduler.batch-size: Maximum number of archived transactions to clean up per scheduler cycle (inbound and outbound each). Must be >= 1. Default is 100.

Directory Sender Configuration (since v0.2.0)

Optional directory-based batch sender that watches a directory for pre-built SBD (Standard Business Document) XML files and submits them via the normal outbound pipeline. Files are moved to success/ or error/ subdirectories after processing, with a JSON result file written alongside each. A pending/ subdirectory is used during processing to prevent duplicate pickup.

  • dirsender.enabled: Enable or disable the directory sender. Default is false.
  • dirsender.directory: (Required when enabled) Absolute path to the watch directory. The directory must exist. Subdirectories pending/, success/, and error/ are created automatically.
  • dirsender.scan-interval (since 0.9.0): Interval between directory scans. Default is 30s.
  • dirsender.scan-interval.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 30000.
  • dirsender.initial-delay (since 0.9.0): Delay before the first scan after startup. Default is 30s.
  • dirsender.initial-delay.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 30000.

Only files with the .xml extension in the watch directory root are picked up. Files must be complete, valid Peppol SBD documents (SBDH envelope + business document). Raw business documents without SBDH are not supported — use the REST API (POST /api/outbound/submit/...) for those.

On startup, files found in the pending/ directory from a previous run are recovered: the database is checked to determine whether each file was already submitted, and files are moved to the appropriate target directory. Files with no database entry are moved back to the watch directory for reprocessing.

HTTP Proxy Configuration

These settings are needed when the AP runs behind an outbound proxy server. They affect AS4 sending, SMP lookups, CRL downloads, and reporting submission.

  • http.proxy.enabled: Enable or disable the use of an outbound HTTP proxy. Default is false.
  • http.proxy.host: Proxy host name or IP address.
  • http.proxy.port: Proxy port number.
  • http.proxy.username: Optional username for proxy authentication.
  • http.proxy.password: Optional password for proxy authentication.
  • http.proxy.nonProxyHosts: Pipe-separated list of hosts that should bypass the proxy (e.g. localhost|127.0.0.1).

Shutdown and Startup Recovery

  • shutdown.timeout (since 0.9.0): Maximum time to wait for in-flight sending and forwarding operations to complete during graceful shutdown. After this timeout, remaining tasks are interrupted. Default is 30s.
  • shutdown.timeout.ms (deprecated since 0.9.0; removal scheduled for v1.0.0): Legacy millisecond-typed key. Default is 30000.
  • startup.recovery.enabled: Enable or disable stale transaction recovery at startup. When true, transactions left in transient states (sending, forwarding) from a previous unclean shutdown are reset to their retry-eligible states (failed, forward_failed) with next_retry_dt = NOW(). Default is true.

See also the Spring Boot properties server.shutdown and spring.lifecycle.timeout-per-shutdown-phase in the Spring Boot / Server Configuration section.

Management Status Endpoint

The AP exposes a JSON status endpoint at GET /management/status that returns non-sensitive configuration values, version information, and runtime metadata. It is intended for health probes, dashboards, and operational tooling.

  • management.status.enabled (since v0.1.3): Enable or disable the status endpoint. When false, the endpoint returns {"status.enabled": false} instead of the full status data. Default is true.

See API Specification for the full response schema.

Logging and Diagnostics

  • phase4.dump.path: Directory path where AS4 message dumps (request/response) are stored for debugging purposes. If not set, no dumps are created. Example: /var/phoss-ap/data/phase4-dumps/.
  • phase4.dump.mode: Controls the file layout of AS4 message dumps. Either direction or grouped. Default is direction.
    • direction — the existing behavior: dumps are placed into separate incoming/ and outgoing/ subdirectories.
    • grouped — correlated messages of a single AS4 exchange (UserMessage + SignalMessage) are placed together in a shared directory under grouped/<date>/<correlation-id>/. For inbound exchanges the correlation ID is the internal unique request ID; for outbound exchanges it is the sanitized AS4 Message ID.

Sentry Error Tracking

Optional integration with Sentry for real-time error tracking and alerting. Sentry is fully disabled by default and activates only when the sentry.dsn property is set and the sentry-logback dependency is on the classpath.

When active, a Logback SentryAppender is registered automatically. Additionally, a SentryNotificationHandler is registered that reports business-level failure events (e.g. sending failures, forwarding failures, verification rejections, reporting failures) to Sentry with structured attributes.

  • sentry.dsn: The Sentry Data Source Name (DSN) for your project (e.g. https://<key>@sentry.io/<project>). If not set, Sentry is fully disabled. Treat as a secret — place it in application-private.properties or inject via environment variable.
  • sentry.send-default-pii: Enable sending of Personally Identifiable Information such as request headers and IP addresses. See the Sentry PII documentation for details. Default is true.
  • sentry.logging.minimum-event-level: The minimum Logback level at which log events are sent to Sentry as events. Default is ERROR.
  • sentry.logging.minimum-breadcrumb-level: The minimum Logback level at which log events are captured as Sentry breadcrumbs. Default is INFO.

Spring Boot / Server Configuration

Standard Spring Boot properties for configuring the embedded server.

  • server.port: The HTTP port on which the AP listens. Default is 8080.
  • server.shutdown: Shutdown mode. Set to graceful to enable graceful shutdown (stop accepting new requests, drain in-flight requests). Default is immediate.
  • spring.lifecycle.timeout-per-shutdown-phase: Maximum time Spring Boot waits for the servlet container to drain in-flight HTTP requests during graceful shutdown. Example: 30s. Default is 30s.
  • server.forward-headers-strategy: Strategy for handling forwarded headers when running behind a reverse proxy. Set to native when behind a proxy.
  • spring.servlet.multipart.max-file-size: Maximum file size for multipart uploads (document submission). Example: 100MB.
  • spring.servlet.multipart.max-request-size: Maximum request size for multipart uploads. Example: 100MB.

It is appreciated if you star the GitHub project if you like it.

Donation link: https://paypal.me/PhilipHelger

Clone this wiki locally