Zib afspraken

Uit Zorginformatiebouwstenen
Naar navigatie springen Naar zoeken springen

Documentatie

De documentatie is gebaseerd op Enterprise Architect versie 14.
Niettemin zijn de acties zoveel mogelijk ook voor versie 12 beschreven.

Algemeen

Naast de meer algemene DCM/Zib toepassingsregels en aanwijzingen, zoals beschreven op de vorige pagina's, gelden voor de zib's uit de landelijke set een aantal additionele en meer gedetailleerde afspraken.
Deze hebben met name tot doel de set consistent tav de vorm te houden en publicatie via de wiki pagina's mogelijk te maken.
Op deze wiki pagina zijn deze afspraken en eisen weergegeven. Ze komen overeen met de items die in de EA add-in ZibTools gecontroleerd worden.

Meertalige zibs

De huidige zibs zijn tweetalig, Nederlands en Engels. Uitbreiding naar meer talen is in principe mogelijk.
De meertaligheid heeft betrekking op alle definities en ander tekstuele velden (zoals bv Notes) en op de namen.
In de delen hieronder staat expliciet vermeld wanneer geen meertaligheid verwacht wordt.
Voor de tekstuele velden wordt de meertaligheid gerealiseerd met een XML achtige structuur:

<languages xml:space="preserve">
<nl-NL>Nederlandse tekst</nl-NL>
<en-US>English translation</en-US>
</languages>

Bij namen wordt de Engelse vertaling in het Alias veld gezet in de vorm:

EN:English name.

Standaardteksten

Naast de secties Disclaimer, Terms of Use en Copyright, hebben ook sommige elementen standaard teksten:

  • Definitie rootconcept
<languages xml:space="preserve">
<nl-NL>Rootconcept van de bouwsteen ‘Naam zib’. Dit rootconcept bevat alle gegevenselementen van de bouwsteen ‘Naam zib’.</nl-NL>
<en-US>Root concept of the ‘English name hcim’ information model. This root concept contains all data elements of the ‘English name hcim’ information model.</en-US>
</languages>
  • Definitie container
<languages xml:space="preserve">
<nl-NL>Container van het concept ‘Naam container’. Deze container bevat alle gegevenselementen van het concept ‘Naam container’.</nl-NL>
<en-US>Container of the ‘English name container’ concept. This container contains all data elements of the ‘English name container’ concept.</en-US>
</languages>
  • Notes van de DCM::ReferencedConceptID tag
<languages xml:space="preserve">
<nl-NL>Dit is een verwijzing naar het rootconcept van de bouwsteen ‘Naam zib waar naar verwezen wordt’.</nl-NL>
<en-US>This is a reference to the rootconcept of information model ‘English name of the referenced hcim’.</en-US>
</languages>
  • Constraint van een ‘choicebox‘ boundary
<languages xml:space="preserve">
<nl-NL>Precies één concept in deze keuze box moet gekozen worden</nl-NL>
<en-US>One concept must be selected in this selection box</en-US>
</languages>
  • Sectie Disclaimer
<languages xml:space="preserve">
<nl-NL>De Zorginformatiebouwstenen zijn in samenwerking gemaakt door diverse partijen en zij hebben deze in beheer gegeven bij Nictiz (al deze partijen samen hierna de samenwerkende partijen genoemd). De samenwerkende partijen hebben de grootst mogelijke zorg besteed aan de betrouwbaarheid en actualiteit van de gegevens in de Zorginformatiebouwstenen. Onjuistheden en onvolledigheden kunnen echter voorkomen. De samenwerkende partijen zijn niet aansprakelijk voor schade als gevolg van onjuistheden of onvolledigheden in de  aangeboden informatie, noch voor schade die het gevolg is van problemen veroorzaakt door, of inherent aan het verspreiden van informatie via het internet, zoals storingen of onderbrekingen van of fouten of vertraging in het verstrekken van informatie of diensten door de samenwerkende partijen of door u aan de samenwerkende partijen via een website of via e-mail, of anderszins. Tevens aanvaarden de samenwerkende partijen geen aansprakelijkheid voor eventuele schade die geleden wordt als gevolg van het gebruik van gegevens, adviezen of ideeën verstrekt door of namens de samenwerkende partijen via de Zorginformatiebouwstenen. De samenwerkende partijen aanvaarden geen verantwoordelijkheid voor de inhoud van informatie in de Zorginformatiebouwstenen waarnaar of waarvan met een hyperlink of anderszins wordt verwezen.In geval van tegenstrijdigheden in de genoemde Zorginformatiebouwsteen documenten en bestanden geeft de meest recente en hoogste versie van de vermelde volgorde in de revisies de prioriteit van de desbetreffende documenten weer.Indien informatie die in de elektronische versie van de Zorginformatiebouwstenen is opgenomen ook schriftelijk wordt verstrekt, zal in geval van tekstverschillen de schriftelijke versie bepalend zijn. Dit geldt indien de versieaanduiding en datering van beiden gelijk is. Een definitieve versie heeft prioriteit echter boven een conceptversie. Een gereviseerde versie heeft prioriteit boven een eerdere versie.</nl-NL>
<en-US>The Health and Care Information Models (a.k.a Clinical Building Block) has been made in collaboration with several different parties in healthcare. These parties asked Nictiz to manage good maintenance and development of the information models. Hereafter, these parties and Nictiz are referred to as the collaborating parties. The collaborating parties paid utmost attention to the reliability and topicality of the data in these Health and Care Information Models. Omissions and inaccuracies may however occur. The collaborating parties are not liable for any damages resulting from omissions or inaccuracies in the information provided, nor are they liable for damages resulting from problems caused by or inherent to distributing information on the internet, such as malfunctions, interruptions, errors or delays in information or services provide by the parties to you or by you to the parties via a website or via e-mail, or any other digital means. The collaborating parties will also not accept liability for any damages resulting from the use of data, advice or ideas provided by or on behalf of the parties by means of the Health and Care Information Models. The parties will not accept any liability for the content of information in this Health and Care Information Model to which or from which a hyperlink is referred. In the event of contradictions in mentioned Health and Care Information Model documents and files, the most recent and highest version of the listed order in the revisions will indicate the priority of the documents in question. If information included in the digital version of a Health and Care Information Model is also distributed in writing, the written version will be leading in case of textual differences. This will apply if both have the same version number and date. A definitive version has priority over a draft version. A revised version has priority over previous versions.</en-US>
</languages>
  • Sectie Terms of use
<languages xml:space="preserve">
<nl-NL>De gebruiker mag de Zorginformatiebouwstenen zonder beperking gebruiken. Voor het kopiëren, verspreiden en doorgeven van de Zorginformatiebouwstenen gelden de copyrightbepalingen uit de betreffende paragraaf.</nl-NL>
<en-US>The user may use the Health and Care Information Models without limitations. The copyright provisions in the paragraph concerned apply to copying, distributing and passing on the Health and Care Information Models.</en-US>
</languages>
  • Sectie Copyrights
<languages xml:space="preserve">
<nl-NL>Een Zorginformatiebouwsteen kwalificeert als een werk in de zin van artikel 10 Auteurswet. Er rusten auteursrechten (copyrights) op een Zorginformatiebouwsteen en deze rechten liggen bij de samenwerkende partijen.
De gebruiker mag de informatie van de Zorginformatiebouwsteen kopiëren, verspreiden en doorgeven, onder de voorwaarden, die gelden voor Creative Commons licentie Naamsvermelding-NietCommercieel-GelijkDelen 3.0 Nederland (CC BY-NC-SA-3.0).
De inhoud is beschikbaar onder de Creative Commons Naamsvermelding-NietCommercieel-GelijkDelen 3.0 (zie ook http://creativecommons.org/licenses/by-nc-sa/3.0/nl/).
Dit geldt niet voor informatie van derden waar soms in een Zorginformatiebouwsteen gebruik van wordt gemaakt en/of naar wordt verwezen, bijvoorbeeld naar een internationaal medisch terminologie stelsel. De eventuele (auteurs) rechten die op deze informatie rusten, liggen niet bij de samenwerkende partijen maar bij die derden.</nl-NL>
<en-US>A Health and Care Information Model qualifies as a work within the meaning of Section 10 of the Copyright Act (Auteurswet). Copyrights protect the Health and Care Information Modesl and these rights are owned by the cooperating parties.
The user may copy, distribute and pass on the information in this Health and Care Information Model under the conditions that apply for Creative Commons license Attribution-NonCommercial-ShareAlike 3.0 Netherlands (CC BY-NCSA-3.0).
The content is available under Creative Commons Attribution-NonCommercial-ShareAlike 3.0 (see also http://creativecommons.org/licenses/by-nc-sa/3.0/nl/)
This does not apply to information from third parties that sometimes is used and / or referred to in a Health and Care Information Model, for example to an international medical terminology system. Any (copyright) rights that protect this information are not owned by the cooperating parties but by those third parties.</en-US>
</languages>

Afspraken over zib inrichting

Waarden op zib repository niveau

Om het testen en verwerken van de Enterprise Architect file te vereenvoudigen, moet op repository niveau een aantal tags aanwezig zijn. dit zijn:

Tabel 1: Omschrijvingen van de repository tagged values
Tag Omschrijving
HCIM::ZIBRepository Geeft aan dat de eap file ZIB's bevat (Boolean met verplichte waarde 'True').
HCIM::ReleaseType Waarde: 'Release' of 'PreRelease'. Gebruik: header van de publicatie hoofdpagina.
HCIM::ReleaseYear Waarde: (Pre)publicatie jaar. Gebruik: Check bij selectie configuratie in applicatie ZibExtraction
HCIM::PreReleaseNumber Waarde: Prerelease nummer (0 voor release). Gebruik: header van de publicatie hoofdpagina.

Waarden op zib niveau

Algemeen

  • De zibnaam bestaat uit de naam van het rootconcept + “-v” en het versienummer
  • De zib heeft een alias in de vorm EN: <Engelse naam zonder “-v” en versienummer>.

DCM tagged values

  • De DCM::Id heeft een OID waarvan de root 2.16.840.1.113883.2.4.3.11.60.40.3 is
  • De DCM::Name is gelijk aan de ZIB naam zonder “-v” en versienummer.
  • De DCM::Version is gelijk aan het versienummer in de naam.
  • De DCM::CreationDate is gevuld
  • De DCM::PublicationDate gevuld (alleen bij publicatie)
  • De DCM::Supersedes: bevat, indien deze zib een opvolger is van een oude zib, de naam en het versie nummer van de voorgaande zib.
Het oude versie nummer mag niet hetzelfde zijn als het huidige versie nummer van de zib

Secties

De volgende secties van de beschrijvingen zijn verplicht en mogen niet leeg zijn.

Revision History uitsluitend in het Nederlands, voor format zie onder
Concept meertalig
Purpose meertalig
Information Model geen tekst, voor diagram zie hieronder
Examples Instances geen tekst, voor vulling zie hieronder
Disclaimer meertalig, met standaard tekst
Terms of Use meertalig, met standaard tekst
Copyright meertalig, met standaard tekst

De volgende secties mogen gevuld zijn en bevatten, indien gevuld, meertalige tekst

Patient Population
Evidence base
Instructions
Interpretation
References meertaligheid niet nodig, Harvard Referencing Style (best effort)

De overige secties van de DCM standaard worden niet gebruikt.

Revision History

Het formaat van de revisie historie is:

Publicatieversie ‘versienummer’ (‘publicatie datum’)
Bevat: ZIB-‘issuenummer1’, ZIB-‘issuenummer2’.

Achter ‘Bevat’ staat een opsomming van alle issues die in de betreffende versie van de zib zijn verwerkt. (niet cumulatief). De issuenummers komen overeen met de vermelding in BITS (bits.nictiz.nl).
Zolang de publicatiedatum nog niet bekend is, wordt deze t.b.v. automatische updating op ‘nn-nn-nnnn’ gezet

Information model

Het informatiediagram van een zib heeft:

  • Als, bij submodellen, de naam anders is dan ’Information Model’ een alias in de vorm EN:<Engelse naam>
  • één rootconcept met daaronder één of meerdere van de volgende items
    • data elementen (Class, stereotype: Data)
    • verwijzingen (Class, stereotype: Data, Reference of Context, Reference)
    • containers (Class, stereotype: Container)
      met daaronder minimaal twee van de volgende items:
      • data elementen (Class, stereotype: Data)
      • verwijzingen (Class, stereotype: Data, Reference of Context, Reference)
      • containers (Class, stereotype: Container)
        met daaronder minimaal twee van de volgende items:
        • data elementen (Class, stereotype: Data)
        • verwijzingen (Class, stereotype: Data, Reference of Context, Reference)
          etc.


Deze concepten worden met connectors verbonden. Concepten kunnen alleen aan containers en rootconcepten gehangen worden.
Deze connectors hebben richting ‘Source->Destination’ (default), lopen richting rootconcept en zijn van het type Composition. Ook de pijl staat in de richting van het rootconcept.
Bij iedere connector wordt aan source kant de cardinaliteit opgegeven.

N.B.: Als onder het rootconcept uitsluitend een container staat met (daaronder) dataelementen, is de container overbodig en kan weggelaten worden.

Model elementen

Een rootconcept

  • is van het type Class
  • heeft stereotype Rootconcept
  • heeft geen datatype
  • heeft een definitie (tweetalig; standaard tekst)
  • heeft een alias in de vorm EN:<Engelse naam>
  • heeft tagged values conform tabel 6

Een container

  • is van het type Class
  • heeft stereotype Container
  • heeft geen datatype
  • heeft een definitie (tweetalig; standaard tekst)
  • heeft een alias in de vorm EN:<Engelse naam>
  • heeft tagged values conform tabel 6

Een data-element

  • is van het type Class
  • heeft stereotype Data
  • heeft een datatype uit de verzameling zib datatypes (Common -> DCM datatypes)
  • heeft een definitie (tweetalig; specifieke tekst)
  • heeft een alias in de vorm EN:<Engelse naam>
  • heeft tagged values conform tabel 6

Een verwijzing

  • is van het type Class
  • heeft stereotype Data, Reference of Context, Reference
  • heeft geen datatype
  • heeft een definitie (tweetalig; specifieke tekst)
  • heeft een alias in de vorm EN:<Engelse naam>
  • heeft tagged values conform tabel 6

Bij de naam van een verwijzing wordt de volgende conventie gehanteerd: Als in het informatiemodel de zib waarnaar verwezen wordt een specifieke rol heeft wordt deze voor de naam van de zib gezet gescheiden door “::”, bv verwijzer::zorgverlener. Indien deze rol niet benoemd of relevant is wordt alleen de zib naam gebruikt. De naam zorgverlener::zorgverlener is dus niet juist.

Waardenlijsten

Elk dataelement van het type CD en CO (zie tabel 6) heeft een ‘antwoord’ domein in de vorm van een waardenlijst element.
Een waardenlijst

  • is van het type Artifact
  • heeft stereotype Document
  • heeft geen datatype
  • heeft geen definitietekst
  • heeft een naam in de vorm <dataelementnaam>Codelijst
  • heeft een alias in de vorm EN:<Engelse naam>
  • heeft tagged values conform tabel 6
  • Heeft een ‘linked document’ met daarin de waardenlijst in (EA) RFT format

De waardenlijst wordt met het bijbehorende dataelement verbonden met een connector.
Deze connector heeft richting ‘Source->Destination’ (default), lopen richting dataelement en is van het type Dependency. De connector heeft geen pijl en geen cardinaliteit.

Voorbeelden van waardenlijst ‘linked documents’:

Tabel 2: Waardenlijst voorbeeld voor datatype CD
Codelijstnaam OID: 2.16.840.1.113883.2.4.3.11.60.40.2.n.m.p
Concept Name Concept Code Code System Name Code System OID Description
Fever 386661006 SNOMED CT 2.16.840.1.113883.6.96 Koorts
Tabel 3: Waardenlijst voorbeeld voor datatype CD, SNOMED CT expressie
Codelijstnaam OID: 2.16.840.1.113883.2.4.3.11.60.40.2.n.m.p
Codes Code System Name Code System OID
SNOMED CT:<442083009 - Anatomical or acquired body structure SNOMED CT 2.16.840.1.113883.6.96
Tabel 4: Waardenlijst voorbeeld voor datatype CD, geheel codestelsel
Codelijstnaam OID: 2.16.840.1.113883.2.4.3.11.60.40.2.n.m.p
Codes Code System Name Code System OID
Alle waarden G-standaard Stofnaamcode i.c.m. toedieningsweg (SSK) 2.16.840.1.113883.2.4.4.1.725
Tabel 5: Waardenlijst voorbeeld voor datatype CO
Codelijstnaam OID: 2.16.840.1.113883.2.4.3.11.60.40.2.n.m.p
Concept Name Value Concept Code Code System Name Code System OID Description
Pressure ulcer stage 1 1 421076008 SNOMED CT 2.16.840.1.113883.6.96 Decubitus categorie 1
  • De codelijstnaam in het linked document moet overeenkomen met de DCM::Valueset waarden van het bijbehorende concept.
  • De OID moet overeenkomen met de DCM::ValuesetID tag van het waardenlijst artefact

Constraints en Notes

Constraints en notes kunnen in principe ieder dataelement, aan iedere boundary en iedere waardenlijst gekoppeld worden. In Constraints worden inperkingen op de geldigheid van het betreffende element vastgelegd. Notes bevatten uitsluitend aanvullende informatie. Een constraint/note

  • is van het type Constraint/Note
  • heeft geen stereotype
  • heeft geen datatype
  • heeft een definitie (tweetalig)
  • heeft geen naam en dus ook geen alias.
  • heeft tagged values conform tabel 6

De constraint/note wordt met het bijbehorende dataelement verbonden met een connector. Deze connector is van het type NoteLink. Deze connector kent geen richting, maar wordt aangebracht van de constraint/note naar het dataelement. De connector heeft geen pijl en geen cardinaliteit. Bij Constraints wordt geen gebruik gemaakt van het constraint type veld.

Boundaries

Boundaries worden gebruikt om informatie of een inperking toe te voegen die betrekking heeft op meerdere elementen. Momenteel worden boundaries gebruikt om een keuzemogelijkheid te bieden bij verwijzing naar meerdere overeenkomstige concepten of zibs (type Choicebox) , om een inperking te doen op bv een waardenlijst van een zib waar naar verwezen wordt (type HCIM) of om informatie over een aantal elementen toe te voegen (type Info). In het eerste geval moet een constraint aanwezig zijn met de hierboven vermelde standaard tekst. Een boundary

  • is van het type Boundary
  • heeft geen stereotype
  • heeft geen datatype
  • heeft geen definitie
  • heeft een naam maar een alias is niet mogelijk.
    • Bij type Choicebox wordt geen naam gebruikt
    • Bij type HCIM de naam van de betreffende ZIB
    • Bij type Info een verduidelijkende naam
  • heeft border style ‘dashed’
  • heeft tagged values conform tabel 6

De elementen binnen de boundary en de boundary worden met connectors verbonden. Deze connectors hebben richting ‘Source->Destination’ (default), lopen richting boundary en zijn van het type Aggregation. De connectors hebben een pijl richting Boundary en geen cardinaliteit. Let op! Zolang de connector binnen de boundary valt is hij niet zichtbaar (maar wel nodig voor de conversie naar ART-DECOR).

De concepten binnen een ‘Choicebox’ boundary verwijzen (zoals bij dataelementen beschreven) bovendien naar het bovenliggende (container) concept. Indien de elementen binnen de boundary en het bovenliggende element conceptueel verschillend zijn, wordt een tussenliggende container geplaatst als ‘placeholder’ voor het te kiezen element. De naam van dit element geeft de rol aan van de onderliggende elementen in het informatiemodel. Hier wordt dus niet de <rol>::<naam> constructie van de verwijzingen gebruikt. Voorbeeld: tussen medicatietoediening wordt een container ‘Toediener’ geplaatst met daaronder een choicebox met verwijzingen naar ‘Patient’ en ‘Zorgverlener’.

Tabel 6: Tagged values per informatie element
Concept Type Stereotype Datatype Tag Card.
Class Rootconcept -- DCM::ConceptId 1..1
DCM::DefinitionCode 0..*
Class Container -- DCM::ConceptId 1..1
DCM::DefinitionCode 0..*
Class Data Alle, behalve CD, CO en II DCM::ConceptId 1..1
DCM::DefinitionCode 0..*
DCM::Example 0..*
Class Data CD, CO DCM::ConceptId 1..1
DCM::DefinitionCode 0..*
DCM::Valueset 1..1
DCM::Example 0..*
Class Data II DCM::ConceptId 1..1
DCM::DefinitionCode 0..*
DCM::Example 0..*
DCM::AssigningAuthority 1..1
Class Data,reference -- DCM::ConceptId 1..1
DCM::DefinitionCode 0..*
DCM::ReferencedConceptId 1..1
Class Context,reference -- DCM::ConceptId 1..1
DCM::DefinitionCode 0..*
DCM::ReferencedConceptId 1..1
Artifact Document -- DCM::ValueSetId 1..1
DCM::ValuesetBinding 1..1
Boundary -- -- HCIM::BoundaryType 1..1
Constraint -- -- -- --
Note -- -- -- --
Tabel 7: Omschrijvingen van de tagged values
Tag Omschrijving
DCM::AssigningAuthority Code die de uitgevende organisatie van een identificerend codesysteem identificeert (OID).
DCM::ConceptId Code die het concept (wereldwijd) uniek identificeert (NL-CM code).
DCM::DefinitionCode Betekenis van de term, uitgedrukt als één of meerdere codes uit bestaande codesystemen (SNOMED-CT, LOINC, etc).
DCM::Example Voorbeeld van de waarde die het concept kan aannemen.
DCM::ReferencedConceptId Dit is de ConceptId van het rootconcept van de zib, waarnaar wordt verwezen (NL-CM code).
DCM::Valueset Naam van de waardenlijst die bij een concept hoort waarvan het bereik uit gecodeerde waarden bestaat (datatypes CD en CO)
DCM::ValueSetId Code die de waardenlijst (wereldwijd) uniek identificeert (OID).
DCM::ValuesetBinding Waarde die aangeeft in welke mate het gebruik van de waardenlijst verplicht is. Mogelijke waarden zijn Required, Extensible, Preferred, Example.
(ten behoeve van de wiki)
HCIM::BoundaryType Waarde die de functie van de boundary aangeeft. Mogelijke waarden zijn Choicebox, HCIM, Info.

Let op!

  • ConceptID en ReferencedConceptID moeten in overeenstemming zijn met het betreffende ZIB Id.
  • ValuesetID moet in overeenstemming zijn met het ZIB Id.
  • ValuesetID’s , ConceptID’s zijn uniek d.w.z. komen (ook in de zib) maar één maar voor.

Examples Instances

De sectie bevat een in Word gemaakt integraal voorbeeld van de waarden die de elementen van de zib kan bevatten.
Het voorbeeld moet realistisch en illustratief zijn maar hoeft niet alle elementen van de zib te bevatten.
Om het voorbeeld te plaatsen, wordt het door het zib centrum in de map 'voorbeelden' bij de juiste EAP file geplaatst. (Het wordt niet langer in de EAP file gepaste als PNG file).
. Het Word bestand met het voorbeeld krijgt bij elke wijzing van de zib een nieuw volgnummer gelijk aan het versienummer van zib.

Afspraken over het maken van nieuwe zibs en nieuwe versies van bestaande zibs

Het maken van nieuwe zibs wordt gedaan in een test EA project file. Dit kan een kopie zijn van de officiele zib EA project file of een andere aan de eisen voldoende file.
Het wijzigen van bestaande zibs moet bij voorkeur te gebeuren in de werkversie van de onderhanden zijnde (pre)publicatie.
Goede afspraken over het exclusief gebruik van de file is hierbij een voorwaarde.

Nieuwe zibs

Deze sectie beschrijft alleen de handelingen die nodig zijn om in de EA omgeving een nieuwe zib aan te maken.
De inhoudelijke afstemming en vaststelling van de zib vallen buiten de scope van deze tekst.
Voor een nieuwe zib kan zowel een vergelijkbare bestaande zib als de zib bouwsteen template als voorbeeld gebruikt worden.
Let op! Het gebruik van een bestaande zib als template heeft het gevaar dat onbedoeld delen van de bestaande zib toch in de nieuwe zib komen.
Doorloop de volgende stappen:

  • Importeer de gewenste zib XMI in de EA project file.
  • Pas de DCM tags aan: wis alle niet gewenste tags, pas zeker ook DCM::Name en DCM::CreationDate aan.
  • Stel in overleg met het Zib centrum een ID vast voor de nieuwe zib en vul dit in als DCM::Id.
Let op! Het nieuwe Id moet ook aan het register toegevoegd worden. Dit mag alleen door het Zib centrum gedaan worden.
  • Exporteer, als de nieuwe zib onderdeel van een (pre)publicatie gaat worden, de zib en importeer deze in de officiele zib EA project file.

Nieuwe versies van bestaande zibs

Een nieuwe versie van een zib wordt uitsluitend aangemaakt indien na een (pre)publicatie een ingediend issue aanleiding is voor een wijziging van de zib.
De nieuwe versie gaat deel uitmaken van de volgende (pre)publicatie. Per (pre)publicatie kan slechts één nieuwe versie van de zib aangemaakt worden,
ongeacht het aantal issues dat als onderdeel van de nieuwe (pre)publicatie op de zib betrekking heeft.
Let op! Het aanmaken van nieuwe versies van zibs die in beheer zijn bij het Zib centrum kunnen alleen door of namens het Zib centrum gedaan worden.

Vaststellen nieuw versienummer

Het maken van een nieuwe versie begint met het vaststellen van het nieuwe versie nummer.
Een versienummer heeft het format m.n.p waarbij m het hoofd-versienummer is, n het sub-nummer en p het sub-sub-nummer. Het sub-sub-nummer hoeft niet aanwezig te zijn.
De nummers worden in voorkomende gevallen met één verhoogd.
Als een belangrijker nummer opgehoogd wordt, worden alle minder belangrijke nummers op nul gezet en zijn dan in het geval van het sub-sub-nummer niet meer aanwezig.

Voorbeelden van juiste versienummers zijn 1.0, 2.3, 2.2.1, 3.0.2. De versienummers 1.0.0 of 2.1.0 zijn foutief.
Voorbeeld van juiste ophoging is 2.3.6 wordt 3.0, 2.4 of 2.3.7. De ophoging 2.3.6 naar 3.3.6 is dus fout.

Bij het ophogen van het versienummer worden de volgende regels gehanteerd:

  • ophogen sub-sub-nummer (A&B):
correcties, wijzigingen en kleine aanvullingen van sectie of definitie teksten met geen of minimale impact op de compatibiliteit, b.v. toevoeging SNOMED CT of andere code als deze ontbrak. A is alleen voor het aanpassen van typo's die we tegen komen en meenemen. Formeel hoeven deze niet langs consultatie en autorisatie maar worden wel als wijzing meegenomen.
  • ophogen sub-nummer (C)
correcties, wijzigingen, toevoegingen, verwijderen van elementen en wijziging van SNOMED CT of andere codes en wijziging van inhoud van waardenlijsten,
grote inhoudelijke wijzigingen van concepten en purpose teksten,
  • ophogen hoofd versienummer (D):
grote, fundamentele modelwijzigingen. bijvoorbeeld opsplitsing of flinke uitbreiding zib. Dit soort wijzigingen moeten over het algemeen worden aangepakt in een project en breed worden afgestemd.

Waar deze regels geen uitsluitsel geven, zal het versienummer in overleg met het Zib centrum worden vastgesteld.

Verwerken nieuw versienummer

Als het versienummer vast staat wordt dit, als vervanging van het oude, ingevuld op de volgende plaatsen:

  • bouwsteennaam
  • DCM::Version tag
  • bestandsnaam van het voorbeeldbestand.

Daarnaast moet de DCM::Supersedes tag aangepast worden.

Verwerken issues

Deze sectie behandelt niet de inhoudelijke afhandeling van de issues, alleen de administratieve kant binnen de zib.
Bij het eerste issue van een nieuwe versie, moet een nieuwe entry toegevoegd worden aan de sectie Revision History, zoals hierboven beschreven is.
Voorbeeld van deze entries:

Publicatieversie 3.0 (01-05-2016)
Bevat: ZIB-453.

Publicatieversie 3.1 (04-09-2017)
Bevat: ZIB-429, ZIB-564, ZIB-575, ZIB-582, ZIB-583.

Bij ieder volgend issue wordt uitsluitend het issuenummer toegevoegd aan de rij. Voor de goede vertaling naar de wiki is het belangrijk dat de regel afgesloten is met een '.'

Voor alle issues geldt:

  • In EA wijzig de Revision History pas als de inhoudelijke aanpassing voltooid is. Hiermee is de status van de versie duidelijker.
  • In EA na het doorvoeren van het issue pas de DCM::RevisionDate tag aan.
  • Indien de wijzigingen impact hebben op het voorbeeld, moet het voorbeeld aangepast worden via Word in de directory waar deze in staat.
Doe dit door het voorbeeld in het separate Word bestand aan te passen en dit vervolgens in de sectie Example Instances te kopieren ter vervanging van het oude voorbeeld.
N.B.: het versienummer in de naam van het voorbeeld bestand wordt sowieso aangepast, los van het feit of het voorbeeld gewijzigd is.
  • In EA voeg tijdens de eerste wijziging aan een zib voor een (pre)publicatie de datum niet in maar zet er (nn-nn-nnnn achter). Dit wordt tijdens de daadwerkelijke (pre)publicatie gedaan waarna voor alle gewijzigde zibs de datum gelijk wordt gezet. vb. Publicatieversie 3.3.1 (nn-nn-nnnn)
  • In Bits check de categorie van de wijziging (B,C of D) en pas aan mocht dit niet kloppen.
  • In EA bij het aanpassen en wijzigen van waarden in een codelijst zet de uit te faseren waarden op DEPRECATED en voeg de nieuwe toe als een rij in de tabel. T.b.v backward compatibility moeten DEPRECATED items altijd in opvolgende pre-publicaties blijven bestaan. Na één maal in een publicatie te hebben gezeten mogen ze bij de volgende publicatie worden verwijderd (maak hier wel een wijzigingsverzoek voor aan). Dit is ook van toepassing bij het toevoegen van bijvoorbeeld SNOMED CT term bij 'code' als voor wijzigingen in de 'concept waarde' bij datatype CO. Een uitzondering hierop is een echte 'spelfout' of typo in een omschrijving. Deze mogen wel zonder deze regel aangepast worden.
  • Bij het doorvoeren van elke wijzing bekijk hoe deze indien mogelijk forward en backward compatible zijn. Backward compatible is een informatiemodel dat compatibel is met eerdere versies van zichzelf. Forward compatible is een informatiemodel dat compatibel is met toekomstige versies van zichzelf.
  • Verwerk in EA -indien mogelijk- alle wijzigingen per zib (ivm eenmalig aanpassen versienummer en voorbeeld). ( TIP Sorteer in bits alle wijzigsverzoeken per bouwsteen zodat je weet welke er op staan).
  • In Bits Verdeel als administrator -indien mogelijk- alle wijzingen op één zib aan dezelfde modelleur.
  • In Bits voeg een commentaar toe bij het issue "wijzing in EA doorgevoerd".
  • In EA run het Testreport via de EA Add-in minimaal één keer na het maken van alle aanpassingen (dit spaart tijd aan het eind bij de publicatie)
  • In Bits wijzig de administrator de status dan zoals afgesproken naar 'in realisatie'. Indien nodig vraag via comment @gebruikersnaamBits aan de administrator dit te doen.