Peppol SML Insourcing 2026 - phase4 changes

[phax]

Before you read this, make sure that you have read the official information from OpenPeppol.

See phax/phoss-smp#445 for similar information on phoss-smp

Short version

• Update at least to "peppol-commons" 12.4.0
• Update at least to "phase4" 4.4.1
• Make sure you use only ESML.PEPPOL_TEST and ESML.PEPPOL_PRODUCTION and not the DIGIT_ versions

Extended version

Unfortunately, changing the DNS domains for AP lookups is more then a simple configuration change, it is most likely a code change.

The generic "phase4-lib" code is of course completely independent from Peppol requirements. The other generic submodules phase4-profile-peppol, phase4-peppol-servlet and phase4-peppol-client are also created in a generic way and do not require any changes.

The main source for the specific DNS domains for lookup is the ESML enumeration (located in the submodule peppol-commons of the peppol-commons project (not a typo ;-) ). Until now, you are using ESML.DIGIT_TEST for accessing the Peppol Test Network and ESML.DIGIT_PRODUCTION to access the Peppol Production Network. Since peppol-commons v12.3.9 the ESML enumeration was extended to also include the new predefined values for the Peppol SML. Since v12.4.0 the primary ESML in EPeppolNetwork was switched from DIGIT_* to PEPPOL_*

So for the period from March 19th, 2026 until May 31st, 2026 you need to do the following;

1. Update to the latest version of "peppol-common" (at least 12.4.0)
2. Recommendation is also to update to the latest version of "phase4" (at least 4.4.1)
3. Search your code for occurrences of ESML.DIGIT_TEST and replace them with ESML.PEPPOL_TEST
4. Search your code for occurrences of ESML.DIGIT_PRODUCTION and replace them with ESML.PEPPOL_PRODUCTION
5. Build and redeploy your solution

[wildhai]

Hi Philip,
thank you for the development and maintenance of the phax/phase4 Java libraries and this detailed description.

Our question regarding this article is:
Why exactly should we switch to "peppol-commons" v12.4.0 and why is an update to at least "phase4" v4.4.1 recommended, as described in the migration description, if "peppol-commons" v12.3.9 already provides the new URLs?

Background:
A major update of the entire library landscape of the Peppol Access Point entails significantly higher workloads. We therefore update our Peppol Access Point regularly every six months - synchronously with the BIS Billing (and XRechnung) update. We would like to avoid unnecessary additional expenses as much as possible. Therefore, we want to understand more precisely where the cause of the requested minor version update lies. Thanks for more information on this.

Best regards,
Frank

[phax]

Hi Frank,
Indeed you can use peppol-commons 12.3.9 onwards.
My thought was primarily on the average user, because peppol-commons 12.4.0 also deprecates the old ESML.DIGIT_* based identifiers which makes their existing usage more visible.
phase4 4.4.1 is the first version that builds on top of peppol-commons 12.4.0 and is therefore considered the "Rundum-Sorglos-Paket" (all-inclusive service package). If you know what you are doing you can of course also "cherry-pick" :)
hth, Philip

[wildhai]

Your clarification is completely understandable.
Thank you very much and best regards.