Extensies in DICO

Versiebeheer deze pagina

Datum	Versie	Door	Toelichting wijzigingen
1-1-2022	v1.0	Jos Hebing Luuk d'Hooghe Herman Drenth	• Eerste publicatie
1-12-2023	v2.0	Luuk d'Hooghe Herman Drenth	• Samenvoegen alle documentatie omtrent extensies • Technische toepassing UDE in DICO • Opsplitsen documentatie per extensie

1 Inleiding

Deze handleiding bevat de algemene spelregels voor bedrijven uit de bouw- en installatiesector die gestandaardiseerde en elektronische berichten willen uitwisselen en die te maken hebben met gegevens welke niet in de basisversie van de DICO berichten zijn opgenomen.

De DICO Standaard bestaat uit verschillende onderdelen en deelgebieden. Zo heeft de data extensie een overlap met de Databerichtenset. De DICO Standaard kent daarnaast ook de Onderhoudsberichten, de Transactieberichten en de Verhuurberichten.

In dit hoofdstuk wordt getracht het proces en het gebruik van extensies in de SALES005 te beschrijven.

1.1 Wat is het doel van dit document?

In dit document leest u welke overkoepelende afspraken zijn gemaakt binnen de branche over het gebruik van de DICO extensies. Dit procesmodel is bedoeld voor de genoemde uitbreiding en geeft een overzicht van de spelregels die gelden binnen de DICO Standaard.

1.2 Welke documenten maken deel uit van de gebruikersdocumentatie?

De gebruikersdocumentatie voor de extensies bestaat uit twee documenten: een procesbeschrijving voor het gebruik en spelregels, en een technisch deel per extensie. Dat laatste deel is gepubliceerd op Semantic Treehouse.

De documentatie is met zorg samengesteld, mochten er onverhoopt toch fouten of onduidelijkheden in staan wordt u verzocht contact op te nemen met Ketenstandaard voor uitsluitsel. Gelieve niet zelf een interpretatie te maken, om zo dialecten van de standaard te voorkomen. De documentatie beschrijft het toepassingsgebied, proces en technische uitgangspunten van de DICO Standaard. Voor de daadwerkelijke uitwisseling van DICO berichten is een licentie vereist. Voor meer informatie en gebruikersvoorwaarden hierover, zie de website van Ketenstandaard.

1.3 Samenstellers

Dit document wordt onderhouden door Ketenstandaard Bouw en Techniek. Ketenstandaard Bouw en Techniek beheert de DICO Standaard en faciliteert DICO Commissies voor de Bouw en Installatie sector. Bedrijven uit de sector zijn vertegenwoordigd binnen deze commissies, waarmee aansluiting op de informatiebehoefte van de sector gewaarborgd blijft.

Voor vragen of opmerkingen over dit document kunt u contact opnemen met dico@ketenstandaard.nl. 

2 Regels en richtlijnen DICO Extensies

Extensies zijn door de toenmalige SALES Commissie ingesteld bij de release van de DICO SALES005 versie om op een later moment elementen en velden toe te kunnen voegen aan een bestaand bericht, zonder dat daarvoor wijzigingen aangebracht moeten worden aan de reeds bestaande XSD van het betreffende bericht. Dit brengt tegelijkertijd stabiliteit op versie-gebied met zich mee en creëert voldoende flexibiliteit om omissies of nieuwe marktbehoeftes wel te kunnen ondersteunen.

Ketenstandaard maakt onderscheid tussen officiële DICO extensies en niet-DICO extensies. De officiële DICO extensies zijn via de gangbare procedures uit het beheerdocument tot stand gekomen, worden door Ketenstandaard erkend en zijn als zodanig ook onderdeel van de DICO Standaard. Uitgangspunt hierbij is wel dat dergelijke extensies altijd optioneel zullen zijn, dit omdat een ontvanger mogelijk niet van de extensie gebruik maakt.

Niet-DICO extensies worden niet door Ketenstandaard ondersteund en zijn geen onderdeel van de DICO Standaard. Een niet-DICO extensie is een zuiver bilaterale afspraak, gebruik van een dergelijke extensie is altijd op vrijwillige basis. Ketenstandaard moedigt aan om niet-DICO extensie initiatieven als RFC in te dienen om tot een marktbrede oplossing te komen. Gebeurt dit niet dan loopt de markt het risico om alsnog vele bilaterale oplossingen te ontwikkelen en het voordeel van een standaard te ondermijnen.

DICO extensies zijn:

• Officieel ondersteund door Ketenstandaard;
• In samenspraak met de markt en commissies opgesteld;
• Tot stand gekomen via de gangbare procedures;
• Optioneel voor de gebruikers;
• Te valideren middels een aanvullende XSD, aangeboden door Ketenstandaard;
• Opgenomen in relevante tools van Ketenstandaard, zoals een validatietool;
• Bieden de mogelijkheid om nieuwe processen, marktbehoeftes en/of marktpartijen aan te sluiten op de DICO Standaard.

Niet-DICO extensie (bilaterale extensie) zijn:

• Niet door Ketenstandaard ondersteund
• 100% bilaterale afspraak, doordat deze extensie niet tot de standaard behoord kan niet worden verwacht dat derde partijen deze extensie gebruiken
• Deze oplossing wordt afgeraden door Ketenstandaard omdat het bilaterale oplossingen in de hand werkt;
• Een niet-officiële extensie kan wel officieel gemaakt worden, ook hiervoor gelden de gangbare procedures en zal als ‘nieuwe RFC’ behandeld worden. Dit is echter niet het wenselijke proces.

Op diverse plekken in de SALES005 berichten zijn ‘User Defined Extension’ elementen opgenomen. Theoretisch kan elke extensie (zowel officiële als niet-officiële extensies) op elke plek waar een User Defined Extension voorkomt in de berichten toegepast worden. Per extensie zal dus beschreven worden waar en hoe deze toegepast moet worden. Het is immers onwenselijk dat een extensie, welke bedacht is om extra factuurinformatie aan het factuurbericht toe te voegen, ook in het artikelbericht gebruikt wordt. Per extensie zal gekeken worden of deze een vaste plek in de standaard krijgen. Bij branche-specifieke extensies kan het wenselijk zijn om deze extern te houden omdat deze geen relevantie hebben met de overige branches, terwijl generieke zaken juist wel voor meerdere partijen nuttig kunnen zijn.

2.1 Toepassen extensie binnen DICO

Voor elke toepassing (extensie) wordt een aparte XSD gemaakt. Het op deze manier toepassen van de extensie zorgt ervoor dat:

a. Te definiëren prefixes kunnen mogelijk conflicteren met bilaterale oplossingen. b. Adoptie van bilaterale oplossingen kan zeer eenvoudig c. Eenvoudig versiebeheer d. Duidelijk gescheiden functionaliteit e. Technisch mogelijk binnen de huidige afspraken f. Eenvoudig te realiseren

Bij conflicten met bilaterale oplossingen zal Ketenstandaard aangeven dat de DICO Standaard en daarmee dus de officiële extensies altijd prevaleren boven bilaterale afspraken.

2.2 Producten

Een officiële DICO extensie bestaat altijd uit tenminste de volgende onderdelen:

• Een XSD of een update van een bestaande extensie XSD;
• Versienummering;
• Procesdocumentatie;
  • Toegestane toepassing in XML;
  • Omschrijving van het beoogde proces;
• Technische documentatie (voorbeeld xml)
• Gebruiksregels

Indien er van het bestaande proces afgeweken wordt dan geldt het proces van de gebruikte extensie.

2.3 Procedure voor wijzigingen

• Indien marktpartijen constateren dat er informatie ontbreekt of een proces niet ondersteund wordt treden zij in overleg met Ketenstandaard;
• Samen met Ketenstandaard onderzoeken zij waar de behoefte allemaal leeft in de markt;
• Er wordt bepaald of de behoefte opgelost moet worden met een extensie of een nieuw bericht of in een volgende versie van de DICO Standaard;
• Samen met Ketenstandaard stelt men een RFC verzoek op. Dit verzoek wordt ondersteund met:
  • Onderbouwing van de noodzaak
  • Concept procesomschrijving
  • Optioneel: concept XSD
  • Optioneel: concept XML

Het bovenstaande sluit aan bij het "normale" proces omtrent RFC's.

2.4 Extra punten/uitgangspunten

Het doel is ten aller tijden dat een origineel bericht bruikbaar blijft op het moment dat de ontvanger de extensie niet gebruikt, een extensie mag het originele bericht niet breken.

• Doel is om het aantal extensies tot een minimum te beperken, adoptie van een extensie is immers niet gegarandeerd.
• Extensies vallen binnen de scope van het huidige proces en kunnen niet doormiddel van andere velden/elementen, andere standaarden of andere wijzen opgelost worden.
• Branche specifieke extensies voegen een niet ondersteund proces of informatie toe aan de bestaande standaard.

2.5 Technische toepassing UDE binnen DICO

2.5.1 Gebruik van de extensie in één bericht

Als er een extensie wordt toepast dan moet er een aparte header worden gedeclareerd. De positie wordt bepaald door het veld <UserDefinedExtension> in het bericht. Op meerdere plekken in een bericht komt dit veld voor. Ketenstandaard bepaalt de exacte locatie waar welke extensie moet worden toegepast.

Als er dan een extensie wordt gebruikt dan moet een header worden toegepast. Hieronder een voorbeeld van zo'n header, in dit geval voor het gebruik van een Transactie extensie (TransactionUDE):

<UserDefinedExtension xmlns:trans="http://www.ketenstandaard.nl/UDE/SALES/Transaction/v1" xsi:schemaLocation="http://www.ketenstandaard.nl/UDE/SALES/Transaction/v1 TransactionUDEv1.xsd">

Hieronder een ander voorbeeld, nu binnen een strucuur van het DICO Orderbericht. In dit geval wordt de Materieelverhuur extensie gebruikt in het orderbericht. De extensie heeft ook een andere prefix (rental:) dan het DICO bericht.

<OrderLine>
  <LineNumber>2</LineNumber>
  <OrderedQuantity>5</OrderedQuantity>
  <OrderedQuantityUoM>PCE</OrderedQuantityUoM>
  <LineIdentification>0002</LineIdentification>
  <TradeItemIdentification>
    <GTIN>08718851294272</GTIN>
    <AdditionalItemIdentification>
      <TradeItemDescription>Betonmolen, elektrisch - 145 l</TradeItemDescription>
    </AdditionalItemIdentification>
  </TradeItemIdentification>
  <UserDefinedExtension xmlns:rental="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2"
    xsi:schemaLocation="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2 RentalUDEv2.xsd">
    <rental:RentalUDE>
      <rental:RentalPeriod>
        <rental:FixedStartDateTime>2021-03-01T00:01:00+01:00</rental:FixedStartDateTime>
        <rental:FixedFinishDateTime>2021-03-16T23:59:00+01:00</rental:FixedFinishDateTime>
      </rental:RentalPeriod>
    </rental:RentalUDE>
  </UserDefinedExtension>
</OrderLine>

2.5.2 Gebruik van meerdere extensie in één bericht

Het kan voorkomen dat er meerdere extensies worden gebruikt op een specifieke plek in een bericht. Voorbeeld van de header met het gebruik van 2 verschillende extensies. In dit geval de DataUDE en de RentalUDE:

<UserDefinedExtension xmlns:rental="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2" xmlns:data="http://www.ketenstandaard.nl/UDE/SALES/Data/v2" xsi:schemaLocation="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2 RentalUDEv2.xsd http://www.ketenstandaard.nl/UDE/SALES/Data/v2 DataUDEv2.xsd">

2.6 Overzicht gepubliceerde DICO Extensies

Naam	Versie XSD	Namespace	Functie van de UDE's
DataUDE	DataUDE.xsd	http://www.ketenstandaard.nl/UDE/SALES/Data/v1	TradeItemIndicators
	DataUDEv2.xsd	http://www.ketenstandaard.nl/UDE/SALES/Data/v2	TradeItemIndicators Indicator ValueDetail ModelClassificationCharacteristics VariableOrderConditions
RentalUDE	RentalUDE.xsd	https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v1	Prices WeekendInvoicing ContinuesUse RentalPeriod StartRentalPeriod
	RentalUDEv2.xsd	https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2	Prices WeekendInvoicing ContinuesUse RentalPeriod StartRentalPeriod
TransactionUDE	TransactionUDEv1.xsd	http://www.ketenstandaard.nl/UDE/SALES/Transaction/v1	TransportInformation
EnergyUDE	EnergyUDEv1.xsd	https://ontology.ketenstandaard.nl/DICO/UDE/Energy/v1	nvt