De berichten

Standaarden en conventies

Het DSP maakt gebruik van SOAP 1.1, SOAP with Attachments en XML 1.0 (fifth edition) standaarden voor hun berichten. Daarnaast wordt de TLS 1.2 standaard aangehouden voor SSL Tunneling.
De berichtdefinities (XSD) zijn opgebouwd volgens de onderstaande conventies. Bij toekomstige aanpassingen zullen deze ook toegepast worden.

1. Elementen en Types worden geschreven in ‘CamelCase’.
2. Type-namen worden gevolgd door ‘Type’ (bijvoorbeeld ‘AansluitingType’).
3. Losse woorden in waardelijsten (enumeration) beginnen met een hoofdletter (m.u.v. meeteenheden. Bijvoorbeeld ‘63 mm’).

In de berichtdefinities zijn de eisen en beperkingen van de verschillende elementen vastgelegd.
Naast de door de XSD definitie afgedwongen structuur van het bericht kunnen er ook specifieke Business Rules van toepassing zijn.

BerichtType

Alle berichten zijn uitbreidingen op het DSP ‘BerichtType’, ook wel ‘Overerving’ genoemd. In ‘BerichtType’ staat het versienummer van de gebruikte XSD’s. Het DSP ondersteunt het versturen van vorige versies, tenzij dit bij de release anders is aangegeven. Het gebruik van oude versies wordt echter niet aanbevolen omdat de uiteindelijke ontvanger hier last van kan ondervinden.

Bijlagen

Voor het uitwisselen van bijlagen biedt het DSP twee mogelijkheden, SOAP with Attachments (SwA) of MTOM. SwA is de standaardwijze waarmee het DSP platform werkt. Als een deelnemer kiest voor MTOM worden binnenkomende berichten door het DSP vertaald van MTOM naar SwA. Van de vertaling zelf zijn geen problemen te verwachten, maar het is wel een extra stap in de keten en vormt daarmee een groter risico.

Aan alle berichten kunnen bijlagen worden toegevoegd. Door het gebruik van MTOM/SwA zijn binnen een request het XML-gedeelte en de bijlage(n) van elkaar gescheiden. Om de behandeling van de bijlagen te stroomlijnen is er voor gekozen om een bijlage structuur op te nemen in ‘BerichtType’. Hierin beschrijft de verzendende partij wat voor bijlage(n) er bij het bericht zitten.

Voor SwA kan de bijlagestructuur in de XML gekoppeld worden aan de bijlage data door de waarden van ‘Bestandsnaam’ en ‘Extensie’ te correleren aan het 'name' attribuut in het attribuut ‘Content-Type’ van de betreffende MIME-part (bijlage).

Bij MTOM wordt gebruik gemaakt van de XOP berichten. Hierin is het ‘BijlageXOPType’ opgenomen met daarin het veld ‘Bijlage’. In dit veld wordt een zogenaamde XOP include opgenomen die naar het betreffende MIME-part (attachment) refereert op basis van het Content-ID van dat MIME-part. Hierdoor ontstaat een directe koppeling tussen het Bijlagen element en de daadwerkelijke bijlage.

Voor bijlagen geldt:

• Maximaal 255 karakters bestandsnaam, maar advies om minder dan 100 karakters te gebruiken
• UTF-8 standaard
• Het gebruik van speciale leestekens wordt ondersteund, maar kan problemen opleveren tussen deelnemers. Advies om altijd standaardkarakters te gebruiken.
• Geen XML tags (", ', <, >, &)
• Geen . in de naam (ivm extensie)
• DSP valideert niet op de inhoud van de bijlage(n), alleen op het valide invullen van de velden in het element Bijlagen (https://wiki.dsplatform.nl/index.php/Bijlagen). Als het bericht voldoet aan de XSD is het bericht technisch correct op het DSP.
• Verzendende deelnemer dient ervoor te zorgen dat de notatie van de velden Bestandsnaam, Extensie en het optionele veld MIMEtype overeen komen met de daadwerkelijke bijlage die aan het bericht is toegevoegd
• Ontvangende deelnemer dient bij afwijkingen tussen notatie in de velden & daadwerkelijke bijlage het bericht wel te accepteren, maar eventueel met een bijstelling/beoordeling aan de verzendende deelnemer om de correcte bijlage(n) te vragen.

Tijdsblokken

Levermomenten of planningen worden in het opdracht- of planningbericht verstuurd als tijdsblok (een start- en eindtijd). Om de start- en eindtijd goed vast te kunnen leggen wordt gebruik gemaakt van een ‘timestamp’, een exact tijdstip. Hiervoor wordt het standaard XSD type ‘datetime’ gebruikt. Bij het vullen van dit type is het belangrijk om een tijdzone-indicator mee te sturen voor een juiste interpretatie door de ontvanger.



Het tijdsblok kan worden gebruikt om op uur-, dag- of jaarbasis te plannen.

Elk levermoment of planning is voorzien van een ‘TypeTijdstip’ dat bepaalt hoe het tijdsblok geïnterpreteerd moet worden (bijvoorbeeld: vaste afspraak, nog nader te bepalen of wens van de klant).

Synchrone respons op ontvangen berichten

Zowel het DSP als deelnemers communiceren over de verwerking van een bericht met een synchrone respons. Voor de bevestiging van een goede verwerking is het type MT_CommonResponse gedefinieerd. Voor het communiceren van foutmeldingen worden in de communicatie SOAP faults (HTTP code 500) gebruikt. SOAP faults worden gebruikt in de onderstaande gevallen:

• Communiceren van fouten uit de XSD validatie.
• Communiceren van fouten uit de functionele validatie. Voorbeelden (het wordt afgeraden om logica op basis van deze voorbeelden te ontwikkelen omdat foutmeldingen kunnen wijzigen):

  • Opdracht [o] bestaat niet
  • Bijstellen van versie [v1] naar [v2] is niet toegestaan
  • Opdracht [o] is gelocked voor Conversie. Alleen een Opdracht bericht met nieuwere versie is toegestaan
  • Opdracht [o] met versie [v] is niet gelocked voor Conversie.
  • versieNummer [v] niet toegestaan voor Opdracht [o]
  • Bericht met type [t] niet toegestaan voor Opdracht [o] en gebruiker [g]
  • Ontvangende deelnemer is niet bekend op het DSP
  • Bericht met type [t] versie [v] wordt niet ondersteund door ontvanger [d]
  • Opdracht [o] heeft niet de correcte status voor bericht met type [t]. Huidige status: [s]
  • Onbekende deelnemer/samenwerkingsverband: [d]
  • Geen deelnemer gevonden voor samenwerkingsverband: [s]
  • Gevonden deelnemer niet onderdeel van samenwerkingsverband [s]
  • Kan geen ontvanger bepalen voor samenwerkingsverband [s]
    

Daarnaast worden de gebruikelijke HTTP errors gebruikt (bijv. 401 Unauthorized).

Maximale berichtgrootte

De maximale grootte van een bericht inclusief eventuele bijlagen is 51200 KB.