Participant migration
Moving a Peppol participant from one service provider to another should not take it off the network. A participant migration does that: the participant keeps its identifier and stays reachable throughout. It is how a taxpayer switches provider. The alternative, deleting the participant and creating it again, leaves it unreachable in between.
The Peppol SML models a migration as two operations. The provider that holds the participant today mints a migration key and registers it. The provider taking over presents that key and claims the record, and DNS moves at that second step. The API has both sides. The API reference holds the endpoints, fields and error codes.
Three things to know
These three facts about the network shape the whole API, and each one surprises people.
A migration key is a bearer credential that cannot be revoked. Whoever holds it, together with any valid SMP certificate, can claim the participant. The SML has no way to revoke a key, so an issued key stays usable indefinitely. That is why the key is returned only once and never stored in plain text, and why marking a migration "not proceeding" changes nothing on the network.
Issuing a key transfers nothing. The provider that is losing the participant keeps its SML record until the gaining provider redeems the key, which is typically days later. For that whole time the participant's ordinary delete is refused, and the refusal is reported with the number 9027, with no AT- prefix. Deleting it would remove the SML record instead of handing it over. The DNS entry would disappear, and because a missing DNS record is cached as missing for 900 seconds, the gaining provider's migration would then fail and the participant would be off the network until someone registered it again from scratch. This is the largest single cause of real downtime in provider switches.
The SML operations return nothing, so DNS is the only evidence. Neither step gives a success answer, an expiry or a way to cancel. Every "did this really happen" answer in this API comes from a DNS query. That is why the teardown call refuses while DNS is unanswered or has not caught up, rather than going ahead.
When your participant leaves
- Issue the migration key. The participant stays fully registered and reachable, and DNS does not change. The key is returned once. Hand it to the gaining provider and treat it as a secret.
- Wait. Nothing tells you when the gaining provider redeems the key, and nothing checks for it. The participant stays marked as having a migration in flight until you finish or abandon it.
- Call the teardown to find out, and to finish. Teardown removes your own copy of the participant from your data and your SMP, and leaves its SML record exactly where it is, now pointing at the gaining provider. It refuses until two independent DNS answers agree that the participant has moved, so it is safe to call at any time and as often as you like. While it says the participant still resolves to your SMP, nothing has happened yet. When it says the record has moved but an ordinary resolver still serves your address, the gaining provider has redeemed the key. Retry shortly and the teardown goes through.
If teardown reports that the participant has no SML record at all, something removed the record instead of reassigning it. Do not retry. If it reports that every migration in flight was started by another organisation, only that organisation can complete or abandon it.
Read the current state of a participant's migrations, in both directions, at any time. The key is never shown again.
Which operation, when
- The participant is moving to another provider. Issue the key, wait, then tear down. Do nothing else in between.
- The move is not going ahead. "Not proceeding" records that locally. It does not cancel anything: the key stays usable, and the participant's delete stays refused.
- The participant is leaving you for good, or the migration is being called off with the other provider's knowledge. "Abandon and offboard" destroys the migration on purpose and deletes the SML record. The gaining provider's migration will then fail, and the participant is off the network until someone registers it again. You confirm it by repeating the id of the migration in flight. It is refused for a migration another organisation started.
- The incoming provider is not on the Peppol network. "Network withdrawal" takes the participant off the network entirely. You must give a written reason, and the migration id if one is in flight.
If the participant is still moving to another provider, do nothing and let them redeem the key.
When a participant arrives
Check first, without the key. The preflight reads who holds the participant today and what the losing SMP publishes, applies the same refusals as the real call, and writes nothing. It also tells you which access point and SMP to choose. A refusal comes back as data, not as an error. A clean preflight does not promise the migration will succeed: the key is checked by the SML, and the network can change in between.
Then run the migration with the key. Arratech publishes everything into its own SMP first and only then redeems the key at the SML, so the participant's metadata is live at the moment DNS moves and there is no gap. Everything before the SML call is undone if something fails. The SML call is the point of no return.
By default Arratech reads the losing SMP and republishes exactly what it publishes. A list you type in by hand that is short by one document type gives a participant that looks healthy and silently cannot receive that type. Supply the document types yourself only when the losing SMP is already unreachable. A business card published by the losing SMP is not carried over, so supply one if the participant had one.
The outcomes
- Completed. All steps ran and the DNS change was seen pointing at you. Nothing to do.
- Completed, DNS change not yet observed. All steps ran and the migration is done. Arratech simply did not see the DNS change before it stopped looking, which is the ordinary result of a successful migration, because the SML updates DNS slowly. Do not retry and do not delete the participant. If you want confirmation, read the migration record again later.
- Partly finished. The SML record moved to you and something after it did not finish. The participant is yours. Do not retry the migration and do not delete the participant to clean up, because either would take it off the network. Contact support and give the migration id.
- Nothing moved. The SML rejected the migration, or the request never reached it, and everything published was rolled back. The reference says which of these is safe to retry, and with which key. If the rollback itself did not finish, or the outcome could not be determined, do not retry. An operator has to settle the migration.