-
Notifications
You must be signed in to change notification settings - Fork 18
Code Lists
This page defines all code lists (enumerations / value sets) used across the phoss-ap data model and APIs.
Distinguishes the purpose of an outbound transaction.
| Name | Value | Description |
|---|---|---|
| Business Document | business_document |
A regular Peppol business document sent from Sender Backend to a remote AP |
| MLS Response | mls_response |
A Message Level Status response sent back to the original sending AP |
Indicates how the outbound document was submitted by the Sender Backend.
| Name | Value | Description |
|---|---|---|
| Payload-only | payload_only |
Raw business document — the AP creates the SBDH envelope |
| Pre-built SBD | prebuilt_sbd |
Complete Standard Business Document with SBDH already present |
Lifecycle status of an outbound transaction (business document or MLS response).
| Name | Value | Final | Description |
|---|---|---|---|
| Pending | pending |
No | Stored in DB, awaiting processing |
| Rejected | rejected |
Yes | Failed optional verification — no sending attempt will be made |
| Sending | sending |
No | AS4 sending is currently in progress |
| Sent | sent |
Yes | Successfully sent via AS4 and receipt confirmed — no further attempts |
| Failed | failed |
No | Last sending attempt failed — scheduled for retry |
| Permanently Failed | permanently_failed |
Yes | Max retries exhausted — no further attempts |
Lifecycle status of an inbound transaction.
| Name | Value | Final | Description |
|---|---|---|---|
| Received | received |
No | Received via AS4 and stored in DB, awaiting processing |
| Rejected | rejected |
Yes | Failed optional verification — no forwarding attempt will be made |
| Verification Deferred | verification_deferred |
No | A document verifier was unavailable — scheduled for re-verification (since v0.12.0) |
| Forwarding | forwarding |
No | Forwarding to Receiver Backend (C3) is currently in progress |
| Forwarded | forwarded |
Yes | Successfully forwarded to Receiver Backend (C3) |
| Forward Failed | forward_failed |
No | Last forwarding attempt failed — scheduled for retry |
| Permanently Failed | permanently_failed |
Yes | Max retries exhausted — no further attempts |
The verdict of the inbound document verification, stored in inbound_transaction.verification_result.
It is deliberately independent of the Inbound Transaction Status: the status describes the lifecycle of a transaction and is overwritten by every forwarding attempt, whereas the verdict has to survive for auditing. NULL means that no verification was performed (yet) — either because verification.inbound.enabled is false, or because the verification is still deferred.
| Name | Value | Description |
|---|---|---|
| Passed | passed |
The document was inspected by all verifiers and accepted |
| Rejected | rejected |
The document was inspected and rejected — either by an explicit verifier rejection, or because a verifier was unavailable and verification.verifier-fail-mode=closed was configured |
| Unverified | unverified |
The document was never inspected, because a verifier was unavailable and verification.verifier-fail-mode=open was configured — it was forwarded unverified |
A verdict of rejected does not necessarily mean that the document was not forwarded — see Verification Rejection Forwarding.
The accompanying column verification_details carries the findings as a JSON array of VerificationIssue objects — the transport-neutral form, not their MLS projection, so it is identical to what the outbound submit API returns. It is NULL if the verifier provided no individual findings, and on a passed verification the findings are warnings. See Verification Issue Level and Type for the value ranges and Message Level Status for the MLS mapping.
Decides if an inbound document that did not pass the verification is nevertheless forwarded to C4 — and with which delivery strength. Configured via verification.inbound.rejection-forwarding.
The rejection itself is unaffected by this mode: the verdict rejected is always recorded in verification_result and the negative MLS (RE) is always sent to C2.
| Name | Value | Description |
|---|---|---|
| None | none |
The rejected document is never forwarded; the transaction ends in status rejected. Default and the behaviour of all versions before v0.12.0 |
| Best Effort | best-effort |
A fire-and-forget copy is dispatched to the primary and to all secondary forwarders; the transaction still ends in status rejected, no inbound_forwarding_attempt row is written and a failing forwarder is only logged |
| Retry | retry |
The document runs through the regular forwarding state machine including retries, so the transaction ends in status forwarded or permanently_failed while verification_result stays rejected
|
In the modes best-effort and retry C2 receives exactly one MLS, namely the RE of the rejection — any later positive or "forwarding failed" MLS is suppressed, derived from the persisted verification_result. See Receiving Process for the resulting flow.
What kind of document is handed to an document forwarder. It is carried in the kind component of a ForwardableDocument, the neutral description of a document to forward — the abstraction that decouples forwarding from received documents, so that a self-generated document can be forwarded too.
This is the one piece of information the document itself cannot provide: C4 can tell an MLS it received from the Peppol network apart from an MLS this AP sent, which matters as soon as both land on the same endpoint.
| Name | Value | Description |
|---|---|---|
| Inbound Document | inbound-document |
A business document received from the Peppol network |
| Inbound MLS | inbound-mls |
A Message Level Status received from the Peppol network |
| Outbound MLS Copy | outbound-mls-copy |
A copy of a Message Level Status that this AP generated and sent itself |
This is not persisted in any database column — it exists only for the duration of a forwarding call.
A VerificationIssue is a single finding of a document verification, independent of how it is later reported: for an inbound document the issues are mapped to Peppol MLS line responses, for an outbound document they are returned to the submitter as JSON.
The two dimensions are deliberately separate, because the Peppol MLS status reason codes conflate them into a single value and therefore cannot express, for example, "an XSD warning".
Level — does the issue prevent the document from being accepted?
| Name | Value | Description |
|---|---|---|
| Error | error |
The issue prevents the document from being accepted |
| Warning | warning |
Worth reporting, but does not prevent acceptance |
Type — what kind of rule was violated?
| Name | Value | Description |
|---|---|---|
| Syntax | syntax |
A structural or syntactical violation, e.g. an XML Schema validation failure |
| Business Rule | business_rule |
A business rule violation, e.g. a failed Schematron assertion |
An issue additionally carries code (the machine-readable rule identifier such as PEPPOL-EN16931-R001, if the verifier provides one), location (an XPath expression, if known) and a human-readable description. See Message Level Status for how level and type are projected onto the MLS status reason codes, and API Specification for the JSON shape.
Outcome of a single sending or forwarding attempt.
| Name | Value | Description |
|---|---|---|
| Success | success |
The attempt completed successfully |
| Failed | failed |
The attempt failed |
Whether a Peppol Reporting record has been created for a transaction.
| Name | Value | Description |
|---|---|---|
| Pending | pending |
Reporting record has not yet been created |
| Reported | reported |
Reporting record has been created |
| Excluded | excluded |
No reporting record is created, because the transaction is excluded from Peppol Reporting by configuration (since v0.13.0) |
Status of MLS response reception for an outbound business document (as C2).
| Name | Value | Description |
|---|---|---|
| Pending | pending |
MLS response has not yet been received |
| Received AP | received_ap |
MLS response received with code AP (Approved) |
| Received AB | received_ab |
MLS response received with code AB (Accepted Blind) |
| Received RE | received_re |
MLS response received with code RE (Rejection) |
| Not Applicable | not_applicable |
MLS is not expected for this transaction (e.g., MLS response transactions) |
Controls when the AP (as C3) sends an MLS response back to C2. Configured per AP instance, captured per inbound transaction at reception time. Mapped from EPeppolMLSType in peppol-commons (com.helger.peppol.sbdh.EPeppolMLSType). Values are case-sensitive. Default is ALWAYS_SEND.
| Name | Value | Description |
|---|---|---|
| Failure Only | FAILURE_ONLY |
MLS response is sent only on rejection (RE) |
| Always Send | ALWAYS_SEND |
MLS response is sent for all outcomes (RE, AP, or AB) |
What triggers the positive MLS of a successfully forwarded inbound document. Configured via mls.sending.trigger. Mapped from EMlsSendingTrigger (com.helger.phoss.ap.api.codelist.EMlsSendingTrigger).
This is an implementation concern of this AP and deliberately not a new value of mls.type, which maps 1:1 onto the Peppol enum EPeppolMLSType.
| Name | Value | Description |
|---|---|---|
| Auto | auto |
The positive MLS is sent immediately after the document was successfully forwarded to C4. Default and the behaviour of all versions before v0.13.0 |
| API | api |
The positive MLS is only sent when the Receiver Backend calls POST /api/mls/send. If it stays silent, the watchdog sends the fallback MLS after mls.sending.api.timeout
|
Only the success path is affected. The negative MLS (RE) of a failed inbound verification and the acknowledging MLS (AB) of exhausted forwarding retries are always sent automatically, because the document never reached the backend. See Message Level Status for the full behaviour.
The response code included in an MLS message sent by C3 back to C2. Mapped from EPeppolMLSResponseCode in peppol-commons (com.helger.peppol.mls.EPeppolMLSResponseCode).
| Name | Value | Description |
|---|---|---|
| Acceptance | AP |
Message delivered towards C4 with confirmation |
| Acknowledging | AB |
Message delivered towards C4 without confirmation |
| Rejection | RE |
Message rejected or delivery towards C4 failed |
The reason code included in an MLS rejection response line item, describing why the document was rejected. Mapped from EPeppolMLSStatusReasonCode in peppol-commons.
| Name | Value | Description |
|---|---|---|
| Business Rule Violation (Fatal) | BV |
Fatal business rule violation — document does not conform to required business rules |
| Business Rule Warning | BW |
Business rule warning — non-fatal issue, may accompany a BV but cannot trigger rejection alone |
| Failure of Delivery | FD |
Permanent inability to forward the document to C4 (used with error field NA) |
| Syntax Violation | SV |
XML schema or syntax validation failure |
Controls how the AP verifies that it is the intended recipient for incoming AS4 messages by cross-checking against SMP registrations. Configured via peppol.receiver-check.mode.
| Name | Value | Description |
|---|---|---|
| None | none |
Receiver checks are disabled (default) |
| SMP | smp |
Uses a fixed SMP URL for verification. Requires peppol.smp.url and phase4.endpoint.address
|
| SML | sml |
Uses dynamic per-participant SMP resolution via the SML derived from peppol.stage. Requires phase4.endpoint.address
|
Configurable behavior when a duplicate is detected on either detection level.
| Name | Value | Description |
|---|---|---|
| Reject | reject |
Duplicate message is rejected at the AS4 level |
| Store and Flag | store_and_flag |
Duplicate is stored in the DB but flagged per detection level |
The method used to deliver received documents to the Receiver Backend. Configured per AP instance.
| Name | Value | Description |
|---|---|---|
| HTTP POST (async) | http_post_async |
SBD is POSTed to the Receiver Backend; reporting is triggered asynchronously later |
| HTTP POST (sync) | http_post_sync |
SBD is POSTed to the Receiver Backend; C4 country code is returned synchronously in the response |
| S3 + Link | s3_link |
SBD is stored in S3; a link/reference is forwarded to the Receiver Backend |
| SFTP | sftp |
SBD is uploaded to the Receiver Backend via SFTP |
| Filesystem | filesystem |
SBD is written to a local directory on the filesystem (since v0.2.0) |
| SPI | spi |
SBD is forwarded by a deployment-provided IDocumentForwarderProviderSPI implementation (since v0.10.0) |
File layout for the filesystem forwarding mode. Controls whether files are stored in a flat directory or in per-transaction subdirectories. Configured via forwarding.filesystem.layout.
| Name | Value | Description |
|---|---|---|
| Flat | flat |
All files in a single flat directory (default) |
| Per-transaction | per-transaction |
One subdirectory per transaction |
Additional modes for automatically determining the C4 country code during inbound forwarding. Multiple modes can be configured as a comma-separated fallback chain via forwarding.c4countrycode.modes. The asynchronous reporting API (POST /api/inbound/report) always remains available as a fallback regardless of which modes are configured.
| Name | Value | Description |
|---|---|---|
| Receiver Participant ID | receiver_pid |
Derive from the receiver's Peppol Participant Identifier scheme. The ISO 6523 code prefix is mapped to a country code via the predefined scheme registry. Only works for country-specific schemes (e.g. 0007 for Sweden); international schemes like 0088 will not yield a result. |
| Business Card Cache | business_card |
Look up the country code from the receiver's Peppol Directory Business Card (fetched from SMP via SML, cached for 1 hour). Requires peppol.stage to be configured. |
Response status returned by the outbound submit APIs.
| Name | Value | Description |
|---|---|---|
| Queued | queued |
Document was accepted and stored for processing |
| Not Queued | not_queued |
Document was not accepted (e.g., verification failure, shutdown in progress) |
It is appreciated if you star the GitHub project if you like it.
Donation link: https://paypal.me/PhilipHelger
- Home
- News and noteworthy
- Running phoss AP
- Architecture Overview
- API Specification
- Configuration Properties
- Code Lists
- Database Design Notes
- Maven Module Structure
- Runtime Extensions
- OpenTelemetry Integration
- Security Considerations
- Peppol Specifics
- Testing Without Peppol Network
- Known Users
- Migrating from phase4-peppol-standalone
- Contributing