Ga naar inhoud

Ketenprotocol AVG

De beschrijving van de technische systeem interfaces voor Actuele verkeersgegevens is vastgelegd in het, in de onderliggende paragrafen beschreven, ketenprotocol-AVG. Dit protocol is bedoeld om een beschrijving te geven hoe systemen DATEX II gegevens met een payload actuele verkeersgegevens dienen uit te wisselen.

Voor alle interfaces geldt dat er zowel een Push- (Het aanleverende systeem initieert de verzending van gegevens) als een Pull (het afnemende systeem initieert de verzending) mechanisme beschikbaar is. Uitwisseling van gegevens geschiedt op basis van SOAP (versie 1.1) over HTTP (versie 1.1). De wijze waarop authenticatie wordt toegepast is afhankelijk van het gekozen mechanisme. De authenticatie kan bestaan uit een combinatie van gebruikersnaam en wachtwoord en/of één of meerdere toegestane ip adressen. Voor alle beschreven methodes geldt dat er gebruik gemaakt moet worden van compressie om de hoeveelheid data verkeer te beperken. Hiervoor dienen de HTTP headers "Accept-Encoding: gzip" en En "Content-Encoding: gzip" gebruikt te worden.

Push Methode

Systemen binnen de AVG keten hebben een interface beschikbaar om data te "pushen" naar een afnemende partij. Het systeem van deze partij moet gebouwd zijn volgens de "DATEX II Push WSDL omschrijving".

De push methode bevat een aantal onderdelen die hier onder beschreven worden. Het gaat om:

  • Administratie
  • Klaar voor levering
  • Onderhouden verbinding
  • Weigeren van data

Administratie

De leverende partij houdt een (offline) administratie bij. Hierin staat geregistreerd:

  • End Point waarop het afnemende systeem de data wil ontvangen.

Zodra een afnemer administratief is geregistreerd wordt de afnemer geactiveerd. Het leverende systeem gaat dan naar Klaar voor levering.

Klaar voor levering

Het aanleverende systeem maakt kenbaar dat het klaar is om de levering te starten door een DATEX II Keep-Alive bericht te sturen naar het afnemende systeem. Indien het afnemend systeem niet reageert, zal het leverend systeem dit bericht iedere minuut blijven herhalen tot het ontvangende systeem reageert. Het exchange element van dit Keep-Alive bericht bevat de volgende waarden:

Elementen binnen exchange waarde
keepAlive true
--- ---
XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
      <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
        <exchange>
          <keepAlive>true</keepAlive>
          <supplierIdentification>
            <country>nl</country>
            <nationalIdentifier>NLNDW</nationalIdentifier>
          </supplierIdentification>
        </exchange>
      </d2LogicalModel>
    </SOAP:Body>
</SOAP:Envelope>

Zodra het afnemende systeem het Keep-Alive bericht correct bevestigd met een DATEX II acknowledge bericht, gaat het leverende systeem over tot het onderhouden van de verbinding.

Het acknowledge bericht van het afnemende systeem moet de volgende waardes bevatten:

Elementen binnen exchange waarde
response acknowledge
--- ---
XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
  <SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
      <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" modelBaseVersion="2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <exchange>
          <response>acknowledge</response>
          <supplierIdentification>
            <country>nl</country>
            <nationalIdentifier>exampleuser</nationalIdentifier>
          </supplierIdentification>
        </exchange>
     </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

Klaar voor levering

Onderhouden verbinding

De verbinding tussen het aanleverend systeem en het afnemend systeem zal worden onderhouden door het aanleverend systeem.

De push methode maakt gebruik van het mechanisme SupplierPushOnOccurrence. De "occurrence" kan tweeërlei zijn:

  • het beschikbaar zijn van een (volledige) bijgewerkte gegevens set,
  • het verstrijken van het tijdstip waarop gegevens gepubliceerd dienen te worden, conform de actualiteitseisen.

Tijdens het onderhouden van de verbinding zal het leverende systeem, zodra er sprake is van het optreden van een van deze voorwaarden, de gegevens naar het afnemend systeem gaan versturen. Dit gebeurt door de "DATEX II Client Push Service" aan te roepen die beschikbaar is op het systeem van de afnemer.

Indien het afnemend systeem niet reageert, zal het leverend systeem direct een DATEX II Keep-Alive bericht sturen, en dit bericht iedere 20 seconden blijven herhalen tot het ontvangende systeem reageert. Reageert het afnemende systeem niet (met een DATEX II acknowledge bericht) op drie achtereenvolgende Keep-Alive berichten, dan wordt een escalatieprocedure in gang gezet, en gaat het leverende systeem over naar Klaar voor levering.

Indien de data incorrect is of de push niet succesvol was, dan zal het teruggezonden DATEX II bericht dienovereenkomstig gevuld worden. Zie hiervoor weigeren van data.

Om een haperende verbinding te kunnen detecteren wordt de escalatieprocedure ook in werking gezet, als het vijf keer niet lukt om data te verzenden, maar het ontvangende systeem wel steeds binnen drie keer op een DATEX II Keep-Alive bericht reageert.

Het exchange element van het DATEX II Keep-Alive bericht bevat de volgende waarden:

Elementen binnen exchange waarde
keepAlive true
--- ---
XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
      <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
        <exchange>
          <keepAlive>true</keepAlive>
          <supplierIdentification>
            <country>nl</country>
            <nationalIdentifier>NLNDW</nationalIdentifier>
          </supplierIdentification>
        </exchange>
      </d2LogicalModel>
    </SOAP:Body>
</SOAP:Envelope>

Het DATEX II acknowledge bericht van het afnemende systeem moet de volgende waardes bevatten:

Elementen binnen exchange waarde
response acknowledge
--- ---
XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
  <SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
      <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" modelBaseVersion="2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <exchange>
          <response>acknowledge</response>
          <supplierIdentification>
            <country>nl</country>
            <nationalIdentifier>exampleuser</nationalIdentifier>
          </supplierIdentification>
        </exchange>
     </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

Onderhouden verbinding

Weigeren van data

Het afnemend systeem kan een data levering weigeren. Binnen het Nederlandse profiel zijn er twee manieren om een weigering van data op te nemen. Via de elementen denyReason en ExtendedDenyReason.

Bij het weigeren van data moet het element denyReason altijd gevuld zijn. Indien het element ExtendedDenyReason gebruikt wordt dient het element denyReason gevuld te worden met "unkownReason".

Binnen de keten zijn de volgende berichten afgesproken:

Generiek

Publicatie tijd in te toekomst (of in het verleden bij een MST)

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
  <SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
      <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
        </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
              <denyReasonExtension>otherReason</denyReasonExtension>
              <denyReasonExtensionDescription>
                <values>
                  <value lang="nl">Ontvangen bericht heeft geen geldige publicationTime.</value>
                </values>
              </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

Een niet valide xml bericht (Geen xml, corrupte xml, validatie fout)

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
  <SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
      <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
        <exchange>
          <denyReason>unknownReason</denyReason>
          <response>requestDenied</response>
          <supplierIdentification>
            <country>nl</country>
            <nationalIdentifier>NLNDW</nationalIdentifier>
          </supplierIdentification>
          <exchangeExtension>
            <exchangeExtension>
              <denyReasonExtension>
                <denyReasonExtension>invalidXml</denyReasonExtension>
                <denyReasonExtensionDescription>
                  <values>
                    <value lang="nl">Aangeleverde XML is niet geldig</value>
                  </values>
                </denyReasonExtensionDescription>
             </denyReasonExtension>
           </exchangeExtension>
         </exchangeExtension>
       </exchange>
     </d2LogicalModel>
   </SOAP:Body>
 </SOAP:Envelope>

Onbekende National Identifier (Provider ID)

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
  <SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
      <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
        <exchange>
          <denyReason>unknownReason</denyReason>
          <response>requestDenied</response>
          <supplierIdentification>
            <country>nl</country>
            <nationalIdentifier>NLNDW</nationalIdentifier>
          </supplierIdentification>
          <exchangeExtension>
            <exchangeExtension>
              <denyReasonExtension>
                <denyReasonExtension>otherReason</denyReasonExtension>
                <denyReasonExtensionDescription>
                  <values>
                    <value lang="nl">nationalIdentifier is onbekend.</value>
                  </values>
                </denyReasonExtensionDescription>
              </denyReasonExtension>
            </exchangeExtension>
          </exchangeExtension>
        </exchange>
      </d2LogicalModel>
    </SOAP:Body>
  </SOAP:Envelope>

Foute Vild verwijzing (locatie of versie)

XML Voorbeeld 
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
        </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
               <denyReasonExtension>invalidConfigurationReference</denyReasonExtension>
               <denyReasonExtensionDescription>
                 <values>
                   <value lang="nl">Aangeleverde SituationPublication bevat SituationRecords met foutieve VILD locaties</value>
                </values>
              </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

Foute configuratie verwijzing, of een andere conditionele validatie fout

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
        </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
              <denyReasonExtension>conditionalValidationFailed</denyReasonExtension>
              <denyReasonExtensionDescription>
                <values>
                  <value lang="nl">NationalIdentifier is onbekend</value>
                </values>
              </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

MST Specifiek

MST verkeerde tabel ID verwijzing (als eerder ingestuurd)

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
         </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
              <denyReasonExtension>conditionalValidationFailed</denyReasonExtension>
              <denyReasonExtensionDescription>
                <values>
                  <value lang="nl">MST komt niet overeen met de MST die eerder is aangeleverd.</value>
                </values>
              </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

MST oudere versie dan bekend bij NCIS

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
        </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
              <denyReasonExtension>conditionalValidationFailed</denyReasonExtension>
              <denyReasonExtensionDescription>
                <values>
                  <value lang="nl">MST versie is ouder dan of gelijk aan de MST die eerder is aangeleverd.</value>
                </values>
               </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

MST Dubbele ID's in bestand

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
        </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
              <denyReasonExtension>conditionalValidationFailed</denyReasonExtension>
              <denyReasonExtensionDescription>
                <values>
                  <value lang="nl">Aangeleverde data bevat meerdere keren hetzelfde ID.</value>
                </values>
              </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

MST Teveel records tov ingestelde waarde

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
        </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
              <denyReasonExtension>unExpectedPubSize</denyReasonExtension>
              <denyReasonExtensionDescription>
                <values>
                  <value lang="nl">Er zijn te veel MeasurementSiteRecords aangeleverd.</value>
                </values>
              </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

MST te weinig records tov ingestelde waarde

XML Voorbeeld 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelBaseVersion="2">
      <exchange>
        <denyReason>unknownReason</denyReason>
        <response>requestDenied</response>
        <supplierIdentification>
          <country>nl</country>
          <nationalIdentifier>NLNDW</nationalIdentifier>
        </supplierIdentification>
        <exchangeExtension>
          <exchangeExtension>
            <denyReasonExtension>
              <denyReasonExtension>unExpectedPubSize</denyReasonExtension>
              <denyReasonExtensionDescription>
                <values>
                  <value lang="nl">Er zijn te weinig MeasurementSiteRecords aangeleverd.</value>
                </values>
              </denyReasonExtensionDescription>
            </denyReasonExtension>
          </exchangeExtension>
        </exchangeExtension>
      </exchange>
    </d2LogicalModel>
  </SOAP:Body>
</SOAP:Envelope>

Pull

Een aanleverend systeem kan tevens uitgerust zijn met functionaliteit om gegevens, op verzoek van het afnemend systeem te publiceren. Het zijn altijd de meest actuele gegevens die worden gepubliceerd.

De pull methode is geïmplementeerd op basis van het "simple http server-profile", wat betekent dat de afnemer een HTTP-request doet en in de body van de response de gegevens krijgt.

Deze gegevens worden in hetzelfde formaat aangeboden als bij de push methode. Om interoperabiliteit te behouden tussen deze twee methoden wordt de data bij de pull methode ook in een SOAP enveloppe verpakt.

Pull procedure

Current=true

Configuratiebestanden worden ook via de pull methode aangeboden. 24 uur voor het live gaan van een nieuwe versie is deze beschikbaar via de pull methode. De parameter 'current=true' kan worden om altijd de huidige MST op te halen, ook al is een wisseling naar de volgende versie aangekondigd en de nieuwe versie beschikbaar.

Push afnemers dienen, wanneer zij een configuratiebestand gemist hebben, ook altijd via de pull methode de configuratiebestanden op te kunnen halen.

1 WSDL omschrijvingen zijn hier te vinden.

2 De inhoud van een escalatie procedure valt niet binnen de scope van het Nederlands profiel DATEX II.

Ga terug naar de vorige pagina