Note: all upgrades from one micro version to another micro version (as in 5.7.1 → 5.7.2), using the same major and minor version (5.7 in the previous example), should be "drop-in replacements", except noted otherwise.

No configuration property was removed or renamed, the REST API paths and the data models are unchanged, and none of the three backends needs a data migration - the SQL schema version stays at V38. The items below are the ones that change existing behaviour.

• The audit trail of a Service Information replacement changed for the XML and the MongoDB backend: replacing an existing Service Information - as done by PUT /{ServiceGroupId}/services/{DocumentTypeId} - now writes a single MODIFY audit entry, instead of a DELETE entry followed by a CREATE entry. That makes the two backends behave like the SQL backend, but it also means that the audit log no longer contains the replaced content of the Service Information, because that content was part of the DELETE entry. Adapt any tooling that evaluates the audit trail of Service Information changes.
• Deleting a Process on the Endpoint Tree page now notifies the Peppol Directory, because deleteSMPProcess of ISMPServiceInformationManager never invoked the registered callbacks. If smp.directory.integration.autoupdate is enabled, that action therefore now triggers a Directory update that it did not trigger before. This applies to all three backends.
• The Migrate outbound and the Migrate inbound pages now read the participant list of this SMP from the SML, to fill the new SML state column. The list is read once per page rendering and is not cached, so opening one of these two pages now performs a remote SML call - as does the Unregister from SML page, which shows the number of participants that would be deleted. It only happens if the SML connection is enabled, an SML is selected, sml.smpid is configured and at least one participant migration is in progress - otherwise the column shows "Not checked". Only the first page of the SML participant list is read, so on an SMP with more participants than fit on a single page the state is reported as "Unknown - too many participants to tell", and a failing SML call is shown as "SML not reachable" instead of breaking the page.
• The Tasks/Problems page now verifies the registration of this SMP at the SML, using the Read() operation of the SML specification. The result is cached for one hour, so the page does not perform a remote call on every rendering, and the check is skipped entirely if the SML connection is disabled, no SML is selected or sml.smpid is not configured. Expect a new entry on that page if the SMP cannot reach the SML management service - e.g. because of a restrictive egress firewall - or if the logical address the SML resolves all participants to differs from the address this SMP is configured with.
• The Check DNS state action of the Service Groups page now runs as a long running job from smp.dnscheck.async.threshold Service Groups on, instead of rendering the result into the response of the action. The result is picked up from the page once the job has finished, so a script that evaluated the response of that action needs to be adapted. The lookups are performed by smp.dnscheck.threads threads in parallel - the default is 8 - which means noticeably more concurrent NAPTR queries against the configured resolver than before. Lower the value if your resolver does not like that.
• The SML reconciliation reports are written into the new directory sml-sync below the configured webapp.datapath, as ZIP files containing summary.xml, all-in-sml.txt, missing-in-sml.txt and orphans-in-sml.txt. Make sure that this location is writable and has enough free disk space - the text files contain one line per participant. Reports older than sml.sync.retention.days are deleted at the start of every reconciliation run; there is deliberately no scheduled job for it, because a reconciliation is always triggered manually. The result of a reconciliation is stored as a long running job result, so on the SQL backend the column job_type of the table smp_long_running_job - added by migration V35 in v8.3.0 - has to exist. That is the case for every installation that was started with v8.3.0 or higher.
• The new pages Administration / SML / Reconcile participants and Administration / SML / Repair SML differences are only created if the SML connection is enabled, and they use the same SML credentials - i.e. the configured keystore - as the existing SML pages. The repair page registers participants at the SML and deletes them from it, and every participant deleted at the SML becomes free for another SMP to claim, so treat the access to it like the access to the Unregister from SML page.
• New optional configuration properties - all of them have a usable default, so nothing has to be set:
  • sml.sync.retention.days: the number of days a created SML reconciliation report is kept on disk. The default is 30; a value ≤ 0 keeps the reports forever
  • sml.sync.page.delay: the delay between two page requests of the SML List() operation, using the duration grammar (e.g. 500ms), so that reading a large SMP does not hammer the SML. Unset or zero means no delay
  • sml.repair.chunk.size: the number of participants sent to the SML in a single CreateList() or DeleteList() call. The default is 100
  • smp.dnscheck.async.threshold: the number of Service Groups from which on the DNS state check runs as a background job. The default is 500; 0 means always
  • smp.dnscheck.threads: the number of DNS lookups performed in parallel by the DNS state check. The default is 8

Nothing to do - the schema version stays at V38.

• The lookup of a single Service Metadata is now a map lookup using the deterministic object ID, instead of a scan over all stored Redirects respectively Service Informations. The format of the stored IDs is unchanged and the IDs are recomputed while the data files are read, so the existing files are used as they are and nothing needs to be migrated. As a side effect, a lookup with a differently cased participant ID now finds the entry - as the Service Group lookup already did - whereas it previously required the exact URI encoded form.

Nothing to do.

• The Maven coordinates of the Peppol Directory client changed from com.helger:phoss-directory-client to com.helger.peppol.directory:peppol-directory-client (v1.0.0). The Java packages are unchanged - com.helger.pd.client stays as it is - so only the dependency declaration of a custom build has to be adapted.
• mergeSMPServiceInformation of ISMPServiceInformationManager is now contractually a replacement: the existing Service Information is searched by Service Group and Document Type ID and is completely replaced by the provided one, instead of being searched by Service Group, Document Type ID, Process ID and Transport Profile. A custom backend should replace the entry in place and report it as a modification, instead of deleting it and creating a new one.

The REST API paths, the identifier handling and the data models are unchanged, and none of the backends needs a data migration. The SQL backend runs one automatic Flyway migration and the MongoDB backend creates additional indexes at startup, so the first startup after the upgrade can take noticeably longer - see the backend specific sections below.

• The configuration property webapp.security.login.errordetails now defaults to false instead of true, so that a failed login in the management GUI no longer reveals whether a specific user exists. If you rely on the details - e.g. on a development installation - set the property to true explicitly. The detailed reason is still written to the audit log. See the Security page for details.
• The session cookie (JSESSIONID) now uses SameSite=Strict, so that a browser no longer sends it on cross-site requests. Because of that, following a link from an external page into the management GUI now leads to the login page. Set the new configuration property webapp.session.cookie.samesite to Lax if that is a problem, or to an empty value to not touch the attribute at all, so that only the web.xml or the application server determine it. An invalid value falls back to Strict and logs a warning on startup. Note that a browser rejects a cookie with SameSite=None that is not marked as Secure as well - a warning is logged on startup in that case.
• The session cookie can now be marked with the Secure flag, using the new configuration property webapp.session.cookie.secure. The default is auto, which enables the flag if smp.publicurl is an https URL and leaves it untouched otherwise, so that an installation that is only reachable via plain http - like a local development instance - keeps working unchanged. If smp.publicurl is an https URL but the management GUI is also opened via plain http, the login stops working, because the browser no longer sends the session cookie - set the property to false in that case. Only the explicit values true and false overrule an existing setting from the web.xml or from the application server. See the Configuration page for both cookie properties.
• The Service Group select boxes of the pages Endpoints, Redirects, Business Cards and Participant Migration (outbound) now load their entries on demand via Ajax, in chunks of 25 entries, instead of rendering every Service Group into the HTML. As a consequence the create forms of these pages open on "(please select)" instead of silently preselecting the first Service Group, so the Service Group has to be chosen explicitly now.
• Added the new REST API PUT /{ServiceGroupId}/services/{DocumentTypeId}/{ProcessId} that adds a single Endpoint to the referenced Process, keeping the existing Processes and Endpoints of the Document Type. This is purely additive - the existing PUT /{ServiceGroupId}/services/{DocumentTypeId}, which overwrites all Processes and Endpoints of a Document Type, is unchanged. See the REST API page for details.

• The new database migration V38 is applied automatically at startup. It creates the indexes that were missing on the hot paths, on the tables smp_ownership, smp_bce, smp_service_metadata_red, smp_endpoint, smp_pmigration, smp_audit, smp_secuser and smp_secusertoken, for MySQL, PostgreSQL, Oracle, DB2 and SQL Server. Only indexes are created - no table, column or constraint is touched - so existing data is preserved and no application change is required. Which indexes are created depends on the dialect, because some of them exist since V1 respectively V8 already. See the News and noteworthy page for the full list. The indexes are created unconditionally, so if you created one of them manually on your installation, drop it before starting, because V38 fails otherwise. Creating an index locks the respective table for the duration of the creation, so plan the startup accordingly if the tables smp_audit or smp_endpoint are large. If you apply the migrations manually, or if the JDBC user has no DDL permissions, make sure that V38 is applied before starting.
• If several SMP instances share a single database, upgrade all of them. A new block of IDs from the global ID factory is now reserved with a conditional UPDATE of the smp_settings entry latest-id, so that two instances can no longer hand out the identical block of IDs. An instance that still runs an older version keeps using the unguarded read-and-write and therefore keeps colliding.

Nothing to do.

• Additional indexes are created on the existing collections at startup: dt on smp-audit, sgid, doctypeid on smp-serviceinfo and on smp-redirect, ownerid on smp-servicegroup, sgid on smp-businesscard, pid as well as direction, state on smp-participant-migration, email on users and tokens.token on user-tokens. On a large installation the first startup after the upgrade therefore takes noticeably longer, while the indexes are built - most notably because of the audit collection, which grows unbounded. Subsequent startups are unaffected. No stored data is touched, so nothing needs to be migrated, and the indexes are created independent of any configuration property.

• peppol-commons 13.0.0 moved the network neutral base types of the Peppol libraries into separate submodules, and the public API of phoss SMP moved along with it. Nothing changes for a running installation, and no configuration property and no REST API is affected, but a custom backend has to be adapted, because the transport profile manager is one of the managers that a backend has to provide:
  • ISMPTransportProfile, SMPTransportProfile and ESMPTransportProfileState moved from com.helger.peppol.smp to com.helger.edelivery.smp, so ISMPTransportProfileManager and its implementations use the new types in their signatures
  • ESMPAPIType moved from com.helger.peppol.sml to com.helger.edelivery.smp, so ESMPRESTType.getAPIType () returns the new type
  • EPeppolCodeListItemState was renamed to ECodeListItemState and moved from com.helger.peppolid.peppol to com.helger.peppolid.codelist
  • The DNS based URL providers moved from com.helger.smpclient.url to com.helger.smpclient.url.dns, and IPeppolURLProvider is deprecated in favour of IBDXLURLProvider
  • SMPExtensionList.getAsPeppolExtension () was removed - use PeppolSMPExtensionHelper.getAsPeppolExtension (...) instead
• ISMPServiceGroupManager has three new methods that a custom backend has to implement, because they carry the page specific filters of the Ajax based Service Group select boxes into the backend query: getAllSMPServiceGroups (ESMPServiceGroupFilter, IPagingSpec, String), getSMPServiceGroupCount (ESMPServiceGroupFilter, String) and containsAnySMPServiceGroup (ESMPServiceGroupFilter).
• HCServiceGroupSelect is now a factory with the single method createAjax (...); the previous method create (...) and the eager select box were removed.
• CSMP.isNewPeppolSml (...) was removed, because the management GUI no longer shows a success badge for the new OpenPeppol SML - only the deprecation badge for the old European Commission based SML remains.

• Incompatible change: the public start page no longer lists the participants managed by this SMP, so that it is rendered without a single backend query, no matter how many participants the SMP manages. It contains a static description of this SMP instead. The configuration properties webapp.startpage.dynamictable, webapp.startpage.participants.none and webapp.startpage.extensions.show were removed accordingly. They are silently ignored if they are still contained in your configuration file, so they can be removed whenever convenient.
• Incompatible change for custom backends and forks: the manager methods getAllSMPServiceGroups (int, int), getAllSMPServiceGroups (String, int, int) and their counterparts for Service Information, Redirects and Business Cards were replaced by a single getAll... (IPagingSpec, String), because the paging, the sorting and the searching are now performed by the backend. The static isMatchingSearchText (...) methods of the four manager interfaces and the classes SMPPagingHelper and SMPJDBCPagingHelper were removed.

• The new database migration V36 is applied automatically at startup. It changes the columns creationuserid, lastmoduserid and deleteuserid of the tables smp_secrole, smp_secuser, smp_secusergroup and smp_secusertoken as well as the column userid of the table smp_audit from varchar(20) to varchar(45), for MySQL, PostgreSQL, Oracle, DB2 and SQL Server. All user IDs are limited to 45 characters that way, matching the id columns of the security tables, which were varchar(45) from the beginning. Only the length of the columns is changed - no column is added, removed or renamed, and the nullability stays as it was, so existing data is preserved and no application change is required. If you apply the migrations manually, or if the JDBC user has no DDL permissions, make sure that V36 is applied before starting. Note for DB2: all columns of a table are changed in a single ALTER TABLE statement, and every changed table is reorganized afterwards via SYSPROC.ADMIN_CMD('REORG TABLE ...'), because DB2 puts a table into reorg pending state after such a change.
• Since v8.4.3 the new database migration V37 is applied automatically at startup. It creates the new table smp_sectotp, which holds the two-factor authentication (TOTP) enrollments of the management GUI users, for MySQL, PostgreSQL, Oracle, DB2 and SQL Server. Only a new table is created - no existing table is touched - so nothing needs to be migrated and no reorganization is required. The table stays empty as long as the feature is not enabled via smp.totp.enabled and no user enrolled, and it is created independent of that property. If you apply the migrations manually, or if the JDBC user has no DDL permissions, make sure that V37 is applied before starting.

The REST API paths, the data models and the identifier handling are unchanged. The XML and the MongoDB backend need no data migration; the SQL backend runs one automatic Flyway migration (see below).

• The Service Group export of the management UI ("Service Groups / Export") is now executed as a background job instead of being a direct download. Pressing "Export all Service Groups" returns immediately, and the created file is downloaded from the new page "Service Groups / Export data". The state of a running export is additionally visible on the page "Administration / Application Information / Long running jobs". The export files are written to the new directory servicegroup-export below the configured webapp.datapath. Make sure that this location is writable and has enough free disk space for a full export.
• New optional configuration property smp.export.retention.days, defaulting to 30 days. Created export files older than that - and the long running job results referring to them - are deleted again. Use 0 or a negative value to keep the files forever. The deletion is performed by a new scheduled job that runs once a day at 02:00, and additionally whenever a new export is started. It is the first scheduled job of phoss SMP and shows up on the page "Administration / Application Information / Scheduled Actions". See the Configuration page for details.
• REST API behaviour change: only a single full export may run at a time now. If one is already running, GET /exchange/export/all/xml/v1 and GET /exchange/export/byowner/{UserId}/xml/v1 return HTTP 503 (Service Unavailable) with a Retry-After: 60 HTTP header instead of starting another one. Scripted clients should handle that response. GET /exchange/export/specific/{ServiceGroupId}/xml/v1 and the outbound migration export are not affected. The returned XML itself is unchanged. Similarly, the action "Update all Business Cards in the Directory" and the bulk changes "Endpoints / Change Certificate" and "Endpoints / Change URL" can no longer be started multiple times in parallel from the management UI.
• If you run phoss SMP behind a reverse proxy using smp.publicurl.mode = forwarded-header or smp.publicurl.mode = x-forwarded-header, the generated URLs may change, because three port handling bugs were fixed: a non-default port in the Forwarded HTTP header was dropped, the port of the incoming request was never used as a fallback, and a port contained in X-Forwarded-Host was emitted twice next to X-Forwarded-Port. Bracketed IPv6 host literals like [2001:db8::1]:8443 are now split correctly as well. After the upgrade, verify the URLs returned by a GET /{ServiceGroupId}. If you set smp.publicurl explicitly, nothing changes for you. See the Configuration page for the description of the modes.
• If the Content Security Policy is enabled (csp.enabled, the default), the management UI now additionally sends frame-ancestors 'none', base-uri 'self', form-action 'self' and object-src 'none'. This means the management UI can no longer be embedded in an <iframe> - e.g. inside a company portal. If you need that, the policy must be adopted. See the Security page for details.
• The relaxed TLS hostname verification for the SML management service is now only applied, if the host of the SML management service URL is exactly localhost or 127.0.0.1. Previously any URL merely containing the text "localhost" disabled the TLS hostname verification. Test setups that used a host name like localhost.example.org therefore now require a certificate that matches the host name.
• The Bearer scheme of the REST API Authorization HTTP header is now matched case-insensitively (bearer, BEARER, ...), as required by RFC 9110. The token value itself is used unchanged, so existing clients keep working.

• The new database migration V35 is applied automatically at startup. It adds the nullable column job_type varchar(100) and the index IX_smp_long_running_job_jt to the table smp_long_running_job, for MySQL, PostgreSQL, Oracle, DB2 and SQL Server. If you apply the migrations manually, or if the JDBC user has no DDL permissions, make sure that V35 is applied before starting - without the column, storing a long running job result (as done by the new Service Group export) fails. Long running job results created before this version keep an empty job type and therefore never match a job type filter.

Nothing to do.

• Four indexes are now created on the collection smp-serviceinfo at startup: id, sgid, processes.endpoints.endpointreference and processes.endpoints.transportprofile. On a large installation the first startup after the upgrade therefore takes noticeably longer, while the indexes are built. Subsequent startups are unaffected.
• The pages "Endpoints / Change URL" and "Endpoints / Change Certificate" now evaluate the endpoint usage inside MongoDB, using aggregations that are allowed to use disk. Note that MongoDB Atlas shared tier clusters (M0, M2 and M5) may not support that option.
• The REST API GET /servicegroupids/all returns different data now: it previously returned the owner IDs instead of the Service Group IDs. The same bug affected the Service Group import and the pages "Endpoints (Tree view)" and "Tasks/Problems". If you built on the previous - wrong - output, your client needs to be adapted.
• The deprecation state of a Transport Profile is now stored in the BSON field state instead of the obsolete field deprecated, so that a changed state is no longer silently lost. Existing data is still read correctly, so no action is required.

The management UI was migrated from Bootstrap 4 to Bootstrap 5 (5.3.8). This affects the rendering of the UI only - the REST API, the data models and the storage backends are unchanged, so no data migration is needed.

• If you use the configuration property webapp.imprint.cssclasses, its value must be changed from Bootstrap 4 to Bootstrap 5 CSS class names. Example: mx-3 badge badge-primary (Bootstrap 4) becomes mx-3 badge text-bg-primary (Bootstrap 5). Class names that no longer exist in Bootstrap 5 are simply ignored by the browser, so the imprint stays visible but is rendered unstyled. See the Bootstrap 5 migration guide for the full list of renamed CSS classes.
• No other configuration property was changed by the Bootstrap 5 migration.
• Recommended (optional): set the new configuration property smp.rest.auth.errordetails to false, so that failed REST API authentications no longer reveal whether a specific user exists. For backwards compatibility it defaults to true. See the Security page for details.

• The configuration property target-database is now deprecated. The preferred key is jdbc.database-type. The old key is still supported as a fallback if the new key is not set, so no immediate action is required.
• The configuration property jdbc.schema-create is now deprecated. The preferred key is smp.flyway.jdbc.schema-create. The old key is still supported as a fallback if the new key is not set, so no immediate action is required.
• New optional Flyway configuration properties are available: smp.flyway.history-table, smp.flyway.debug-mode, and smp.flyway.repair-mode. See the Configuration page for details.

• Some SQL database migrations via Flyway are performed. Some tables are created without a primary key because they don't need one.

• When using the SQL backend, it is possible that the selected SML from the "SMP settings" is lost. To resolve this, simply re-select the proper SML on the "SMP Settings" page and press "Save" again. This bug was resolved in v8.1.3 - so if you were on 8.0.15 or lower and did not try to install any version below 8.1.3 you will not face the issue.

The minimum requirement to run phoss SMP is Java 17. It runs with Java 21 as well.

Also an update from JakartaEE 9 to JakartaEE 10 was performed which means, that at least Apache Tomcat v10.1.x or Jetty 12.x are required to run phoss SMP.

• Removed support for the configuration property smp.publicurl.mode value dynamic-participant

Nothing to do.

Nothing to do. The primary reason for the minor version bump is the update to support Peppol SMP specification 1.3.0 (SHA-256).

The minimum requirement to run phoss SMP is Java 11. It runs with Java 17 and Java 21 as well.

Also an update from JavaEE to JakartaEE 9 was performed which means, that at least Apache Tomcat v10.0.x or Jetty 11.x are required to run phoss SMP.

The configuration system has been updated, so that system properties and environment variables can be used to configure parts of the system. The resolution of the new configuration file is described at https://github.com/phax/ph-commons/wiki/ph-config

Now the content of all the previous configuration files should be merged into the single file application.properties. Just copy all the lines from webapp.properties and smp-server.properties and append it to the existing application.properties. If you don't have application.properties but only pd-client.properties (which was obsoleted ages ago in v5.3 and is no longer supported in v6.x) then first rename pd-client.properties to application.properties and then append the contents of the other files. The old files webapp.properties and smp-server.properties can be removed. For the sake of backwards compatibility, the old files are still read - this feature will be removed in the next major release.

Note: the default encoding of the files changed from ISO-8859-1 to UTF-8.

The following system properties are no longer supported and their existence will lead to a startup error:

• peppol.smp.server.properties.path
• smp.server.properties.path
• peppol.smp.webapp.properties.path
• smp.webapp.properties.path

The following environment variables are no longer supported and their existence will lead to a startup error:

• SMP_SERVER_CONFIG
• SMP_WEBAPP_CONFIG

Note: for backwards compatibility, the old files with the old names will still be read - this feature will be removed in the next major release.

The following configuration properties, that are the defaults for the settings, have been renamed:

• sml.needed → sml.required
• sml.active → sml.enabled
• smp.peppol.directory.integration.required → smp.directory.integration.required
• smp.peppol.directory.integration.enabled → smp.directory.integration.enabled
• smp.peppol.directory.integration.autoupdate → smp.directory.integration.autoupdate
• smp.peppol.directory.hostname → smp.directory.hostname

Support for Vagrant has been removed. Docker support is untouched.

Flyway has been updated to the latest version v9.x which does not support MySQL 5.7 anymore. Please see the Flyway Release Notes for all details.

Nothing to do

Nothing to do

• The name of the configuration properties for SMP client proxy configuration changed. See https://github.com/phax/peppol-commons#configuration for details.
  • http.proxyHost is now http.proxy.host
  • http.proxyPort is now http.proxy.port
  • http.proxyUsername is now http.proxy.username
  • http.proxyPassword is now http.proxy.password
  • http.nonProxyHosts is now http.proxy.nonProxyHosts
  • http.useSystemProperties is now deprecated
• The name of the configuration properties for Directory client configuration changed. See https://github.com/phax/phoss-directory#client-configuration-properties for details.
  • keystore.type is now pdclient.keystore.type
  • keystore.path is now pdclient.keystore.path
  • keystore.password is now pdclient.keystore.password
  • keystore.key.alias is now pdclient.keystore.key.alias
  • keystore.key.password is now pdclient.keystore.key.password
  • truststore.type is now pdclient.truststore.type
  • truststore.path is now pdclient.truststore.path
  • truststore.password is now pdclient.truststore.password
  • http.proxyHost is now http.proxy.host
  • http.proxyPort is now http.proxy.port
  • proxy.username is now http.proxy.username
  • proxy.password is now http.proxy.password
  • connect.timeout.ms is now http.connect.timeout.ms
  • request.timeout.ms is now http.request.timeout.ms
  • https.proxyHost is no longer supported
  • https.proxyPort is no longer supported

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V19 (5.7.0) of the scheme.

This version ships with initial support for DB2. This DB system is still considered experimental, so handle with care.

See these folders for the DDL scripts:

• MySQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-mysql
• PostgreSQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-postgresql
• Oracle: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-oracle
• DB2: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-db2

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V17 (5.6.0) of the scheme.

See these folders for the DDL scripts:

• MySQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-mysql
• PostgreSQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-postgresql
• Oracle: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-oracle

Nothing to do

Nothing to do

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V14 (5.5.0 and 5.5.1) or V15 (5.5.2+) of the scheme.

See these folders for the DDL scripts:

• MySQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-mysql
• PostgreSQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-postgresql

Nothing to do

Nothing to do

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V3 of the scheme.

See these folders for the DDL scripts:

• MySQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-mysql
• PostgreSQL: https://github.com/phax/phoss-smp/tree/master/phoss-smp-backend-sql/src/main/resources/db/migrate-postgresql

Nothing to do

Nothing to do

Before upgrading to 5.3, please make sure that you have 5.2.x running. An update from previous versions may have unexpected side effects.

• When using the environment variable DIRECTORY_CLIENT_CONFIG to locate the pd-client.properties file:
  • you need to instead use the environment variable CONFIG_FILE and the file should be renamed to application.properties
• When using the system property peppol.pd.client.properties.path or pd.client.properties.path to locate the pd-client.properties file
  • you need to instead use the system property config.file and the file should be renamed to application.properties
• Note: the goal of these preparations is to harmonize the configuration system of the SMP, so that future versions only use a single configuration file.

• The SQL backend was changed from EclipseLink to native JDBC.
• Additionally FlyWay was introduced for SQL version management. This creates a new table flyway_schema_history and needs CREATE, DROP, INDEX and ALTER rights for the database user.
• Additionally PostgreSQL was added as a new supported database system
• The database table "smp_user" is removed, and all users are integrated into the "internal" user management. Due to internal requirements the usernames needed to be changed. The old name abc was automatically transformed to [email protected]. The password was taken over unchanged - compared to the DB table it is now only stored as a hash value. This login name can be easily edited under "Administration | Security | User management". So if you are using the REST API to communicate with the SMP please make sure to use the updated user name for authentication.

Nothing to do

Nothing to do

The names of the WAR files changed:

• peppol-smp-server-webapp-sql → phoss-smp-webapp-sql
• peppol-smp-server-webapp-xml → phoss-smp-webapp-xml

An update of the database structure is necessary. Please see the DDL instructions in https://github.com/phax/phoss-smp/blob/master/phoss-smp-backend-sql/database_backups/update-5.2.0-mysql.sql

ALTER TABLE `smp_service_metadata_redirection` ADD COLUMN `certificate` LONGTEXT NULL;
ALTER TABLE `smp_service_metadata_redirection` MODIFY `certificateUID` VARCHAR(256) NULL;

For DB2:

ALTER TABLE smp_service_metadata_redirection ADD COLUMN certificate CLOB NULL;
ALTER TABLE smp_service_metadata_redirection ALTER COLUMN certificateUID DROP NOT NULL;

Hint for DB2: it is suggested to REORG your tables afterwards (see http://publib.boulder.ibm.com/infocenter/db2e/v9r1/index.jsp?topic=%2Fcom.ibm.db2e.doc%2Fsqlreorgt.html)

Basically a new column is added, and another column is made nullable.

The file https://github.com/phax/phoss-smp/blob/master/phoss-smp-backend-sql/database_backups/smp_mysql_20200220_v5.2.x.sql is an "all-inclusive" file to be used for new users of phoss-smp 5.2.x for MySQL.

The file https://github.com/phax/phoss-smp/blob/master/phoss-smp-backend-sql/database_backups/smp_postgresql_20200820_5.2.x.sql is an "all-inclusive" file to be used for new users of phoss-smp 5.2.x for PostgreSQL.

Nothing to do

Nothing to do

It must be ensured that the new truststore (truststore/complete-truststore.jks) containing OpenPeppol v2 and v3 certificates is used.

The name of the WAR file changed. peppol-smp-server-webapp-X.Y.Z was changed to either peppol-smp-server-webapp-xml-X.Y.Z.war or peppol-smp-server-webapp-sql-X.Y.Z.war (depending on the backend you want to use). This was because of some weird application server logic in combination with EcliseLink JAR.

To upgrade from version 4.x of the SMP to version 5.x of the SMP, please consider the following aspects:

• Version 5 of the SMP server requires Java 8 both for development as well as for runtime. That means that also at least Tomcat 7 is recommended for execution.
• When using the sql backend, another table must be added to the database. For MySQL, use the following DDL:

DROP TABLE IF EXISTS `smp_bce`;
CREATE TABLE `smp_bce` (
 `id` varchar(45) NOT NULL COMMENT 'Internal ID',
 `pid` varchar(255) NOT NULL COMMENT 'Participant/Business ID',
 `name` text NOT NULL COMMENT 'Entity name',
 `country` varchar(3) NOT NULL COMMENT 'Country code',
 `geoinfo` text COMMENT 'Geographical information',
 `identifiers` text COMMENT 'Additional identifiers',
 `websites` text COMMENT 'Website URIs',
 `contacts` text COMMENT 'Contact information',
 `addon` longtext COMMENT 'Additional information',
 `regdate` date DEFAULT NULL COMMENT 'Registration date',
 PRIMARY KEY (`id`),
 KEY `FK_pid` (`pid`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='SMP Business Card Entitiy';

• There are a couple of new Configuration items in version 5 which may require customization. For all configuration items sensible default values are used so there is usually no need to change anything. See Configuration for all the details.
  • smp.truststore.path: The classpath - relative to the project - where the Java trust store (of type JKS) with the public certificates of the SMLs to communicate with are contained. This property is optional. If no trust store path is provided, the SML client caller trusts all SML https certificates.
  • smp.truststore.password: The password used to access the truststore.
  • smp.identifiertype: determine the identifier types to be used.
  • smp.rest.type: this property determines the layout of the REST responses.