Enterprise Architect Zib Add-in

Manual pagina's

• Enterprise Architect plug-in voor zib's
• Publicatie van zibs
• ZibExtraction user interface
• Configuratie user interface
• Controleren SNOMED CT en LOINC codes
• Beheer wikipage labels
• Beheer publicaties en groepen

Korte beschrijving

Enterprise Architect biedt de mogelijkheid om functionaliteit aan de applicatie toe te voegen door middel van add-in's.

Voor de zib's is een add-in gemaakt die de uitvoering een aantal handelingen en testen die gedaan moeten worden om tot een succesvolle publicatie te komen, vereenvoudigen.
Allereerst kunnen de zib's op een groot aantal punten getest worden of zij voldoen aan de afspraken die over de zib's gemaakt zijn.
Deze eisen varieren van modelleringsafspraken tot afspraken ten behoeve van de import in ART-DECOR. De eisen zijn in detail beschreven in de documentatie.
Daarnaast kunnen van één zib of een set zib's de publicatie tags geset en gereset worden en kunnen de datumvelden gewist worden (wat handmatig niet mogelijk is).
Tenslotte biedt de add-in de mogelijkheid om eenvoudig een nieuwe versie aan te maken ten behoeve van het verwerken van issues.

Om ook het maken en wijzigen van zib's te vereenvoudigen, biedt de add-in ondersteuning voor het maken en aanpassen van elementen, waardelijsten, connectors en boundaries, door middel van custom invoerdialogen

Enterprise Architect Zib Add-in gebruikersinterface

De Enterprise Architect Zib Add-in bestaat functioneel uit twee delen, tw. een uitbreiding van het menu en de eigenlijke testmodule.

Menu

Bij de installatie van de EA zib add-in worden de volgende menu items toegevoegd:

	Figuur 1: Enterprise Architect hoofdmenu (versie 12)

	Figuur 2: Enterprise Architect hoofdmenu (versie 14)

1. Menu item Zib
   Na installatie van de add-in wordt het Extensions (v.12)/Specialize(v.14) menu uitgebreid met het menu item 'Zib'
2. Submenu
   Het submenu kent vijf items:

   Tools: Hiermee wordt het zibtest scherm geopend in de EA add-in window.

   Als dit item uitgegrijsd is, wordt het eap bestand niet als Zib container beschouwd.

   Meestal betekent dit dat de tag HCIM::ZIBRepository ontbreekt of is false.

   Bilingual notes: Open een tweetalig editorscherm.

   Als dit item uitgegrijsd is, is geen item met tweetalige notes.

   Configure tools: Opent het configuratiescherm van de add-in.

   Help: Gebruiksaanwijzing van de add-in(deze pagina)

   About: Informatie over de add-in

3. Add-in Windows
   Mocht het add-in window niet verschijnen kan het met dit menu item getoond worden.

Add-in window

User interface

De EA Zib Add-in kent de volgende besturingselementen:

	Figuur 3: Enterprise Architect add-in window

1. Test Zib
   Start de test cyclus voor de zib.
   De eisen waar de zib op getest wordt, staan beschreven in de documentiepagina's.
   De resultaten worden in het add-in window weergeven.
2. Publish
   Wijzigt de publicatie tags van de zib. Voordat dat kan gebeuren, moeten eerst de twee volgende items op de juiste waarde gezet worden.
   De volgende tags worden aangepast:
   • DCM::PublicationDate : Publicatiedatum
   • DCM::PublicatieStatus: Published/Prepublished
   • DCM::LifecycleStatus : Final
3. Publicatie datum
   Datumdialoog om de gewenste publicatiedatum in te stellen.
4. Pre(publicatie)
   Dropdown list met de opties publicatie en prepublicatie.
5. Reset Tags
   Reset de publicatie tags van de zib.
   De volgende tags worden aangepast:
   • DCM::PublicationDate : leeg
   • DCM::PublicatieStatus: Unpublished
   • DCM::LifecycleStatus : Draft
6. Clear Tags
   Reset de publicatie tags zoal beschreven bij 'Reset tags' en wist bovendien de DCM::CreationDate en DCM::RevisionDate tags..
7. Voorbeeld waarschuwing
   Tijdens de test kunnen fouten (rood), waarschuwingen (oranje) en informatieve mededelingen (groen) verschijnen.
   Allen gaan vergezeld met mededeling in het opmerkingen veld.
   Hier wordt een voorbeeld van een waarschuwing getoond.
8. Samenvatting testresultaat
   De test besluit met een overzicht van het aantal geconstateerde afwijkingen.
9. New Version
   Faciliteert het maken van een nieuwe versie van een zib. Het gebruik van de knop roept een keuze scherm op met de mogelijke nieuwe versienummers.
   Na het kiezen van de nieuwe versie, worden alle vermeldingen van het versienummer aangepast.
   Indien het vinkvak 'Modify Example Filename' wordt geselecteerd, zal op de aangegeven locatie gezocht worden naar de example file en wordt de naam aangepast, de inhoud natuurlijk niet.
   Als geen locatie ingegeven is, wordt een folder selectiedialoog gestart.
   Als de examplefile locatie gevuld is, zal bij het testen van een zib ook gecontroleerd worden of de voorbeeld file de juiste versie heeft.
10. Notes Editor
    Opent een tweetalig editorscherm.

Gebruik

Om de add-inn te kunnen gebruiken moet eerst via het Extensions cq. Specialize menu Zib > Tools gekozen worden.

Test zib

De knop wordt pas actief als er een enkele zib geselecteerd wordt.
Na het indrukken van de knop zal de test gestart worden. De geteste punten worden per testsectie in tabelvorm weergegeven.
Bij geconstateerde afwijkingen zal de afwijkende waarde in kleur weergegeven worden en zal in de kolom 'Opmerkingen' additionale informatie getoond worden. De kleurcodering voor de afwijkingen is:

• rood: een foutconditie die opgelost moet worden voordat de zib gepubliceerd kan worden.
• oranje: een waarschuwing. De test constateert een afwijking maar kan niet vaststellen of het om een fout gaat of niet.

Voorbeeld is het ontbreken van een publicatiedatum: voor een test tijdens de ontwikkeling van de zib is dat een juiste conditie, maar bij een finale test voor de publicatie een fout.
Waarschuwingen moeten altijd beoordeeld worden op impact en noodzaak tot verbetering.

• groen: informatieve mededeling: een afwijking die geen actie vereist.

Als de test een afwijking constateert die de test zelf kan oplossen zal dit als informatie getoond worden.

Iedere mededeling in de kolom 'Opmerkingen' wijst op een geconstateerde afwijking. Idealiter verloopt de test zonder opmerkingen.
Aan het einde van de test wordt een overzicht getoond van het totaal aantal fouten, waarschuwingen en informatieve mededeingen.

Publish

De actie is beschikbaar voor enkele zib's en voor een folder met zib's.
Selecteer met behulp van de datumdialoog de publicatiedatum en geef met de dropdown list aan of om een publicatie gaat of om een prepublicatie
Als in de eap file de tag HCIM::ReleaseType bestaat, zal deze waarde als preset worden gebruikt. Druk vervolgens op de knop 'Publish'. De plugin voor iedere geselecteerde zib de publicatie tags op de gekozen waarden zetten.<br. Bovendien wordt in iedere zib in de sectie 'Revison History' gezocht naar de sjabloon tekst nn-nn-nnnn en wordt dit sjabloon vervangen door de publicatiedatum

Reset

De actie is beschikbaar voor enkele zib's en voor een folder met zib's.
Een druk op de knop zal voor de geselecteerde zib's de publicatie datum wissen en de publicatiestatus velden resetten.
Deze actie is nodig als de eap met een gepubliceerde set zib's gekopieerd wordt om als werkversie voor de volgende (pre)publicaite te dienen.

Clear

De actie is beschikbaar voor enkele zib's en voor een folder met zib's.
Een druk op deze knop doet hetzelfde als Reset maar wist bovendien de DCM::RevisionDate en de DCM::CreationDate tag.
Dit is handig als een bestaande zib gebruikt wordt als basis voor een nieuwe zib.

 De gewiste datumvelden kunnen niet meer hersteld worden. Wees dus voorzichtig met deze functie.

Tweetalige teksteditor

Tweetalige notes velden hebben een XML structuur om teksten in beide talen te kunnen opslaan.
Om het aanmaken en wijzigen van deze tweetalige notes velden makkelijker te maken, is een tweetalige editor beschikbaar.
De eerste keer dat een tot dan toe leeg tweetalig notes veld met de editor van tekst wordt voorzien, wordt automatisch een XML structuur aangemaakt.

		Figuur 4: Tweetalige teksteditor

1. Nederlands tekstveld
   De Nederlandse tekst van de notes. Ieder edit windows heeft een knoppen balk met de gebruikelijke edit functies.
   Als de muispointer boven de knop hover't, wordt de functie van de knop getoond.
   Het edit window heeft een Nederlandse taalcorrectie.
2. Engels tekstveld
   De Engelse tekst van de notes.
   Het edit window heeft een Engelse taalcorrectie.
3. Vertaalrichting
   NL>EN, EN>NL: Keuze van de bron en doel taal t.b.v. de vertalingen met Google translate.
4. Google vertaalservice
   Vertaal: Actieknop om de vertaling met behulp van de vertaalservice in gang te zetten. Indien geen tekst geselecteerd is wordt de hele tekst te vertaling aangeboden.
   De vertaalrichting geeft aan welke tekst aangeboden wordt, Nederlands of Engels.
   Indien wel een stuk tekst geselecteerd is, wordt alleen de geselecteerde tekst vertaald. Het resultaat kan met paste (Ctrl-V) opgehaald worden.
   Vertalingen met Google Translate kunnen slechts als eerste vertaal concept gezien worden. Het zonder meer gebruiken van de vertaling zal vaak tot niet accpetabele resultaten leiden.
   Als de knop uitgegrijst is, is in de configuratie ingesteld dat de service niet aangeboden wordt.
5. Google vertaalwebpagina
   Actieknop om de vertaling met behulp van de Google Translate webpagina. De opmerkingen bij 'Google vertaalservice' gelden hier ook.
   Hoewel vertaling met de webpagina het zelfde resultaat geeft als de service, werkt de laatste makkelijker en consistenter.
6. Actie knoppen
   Opslaan: Ingevoerde wijzigingen opslaan en scherm sluiten.

   Als beide taalvelden leeg zijn, wordt geen XML structuur aangemaakt.
   

   Annuleren: Scherm sluiten en eventuele wijzigingen negeren.
7. Naam notes veld
   Naam van de zib en het item waarvan de notes in de editor geladen is.

Invoer hulpdialogen

Concepten

De hulpdialoog van de invoer van concept eigenschappen wordt getoond als

• een Class element vanuit de toolbox
• een datatype als child uit de DCM Datatypes

in het diagram wordt gesleept. In het laatste geval zal het datatype al ingevuld en daarom uitgegrijst zijn.
Een doubleclick op een Class element zal de dialoog in edit mode openen. In deze mode zijn datatype en stereotype niet te wijzigen.
Het gedrag van deze hulpdialoog wordt beïnvloed door de keuzes in de configuratie.

		Figuur 5: Hulpdialoog voor het invoeren van conceptgegevens

1. Conceptnaam
   Naam van het concept. De naam mag geen spaties bevatten. Indien de naam samengeteld wordt uit meerdere losse woorden, krijgen de losse woorden in de conceptnaam een hoofdletter.
2. Engelse naam
   De Engelse naam komt in het alias veld van het concept. Voor de Engelse naam gelden dezelfde regels als voor de Nederlandse.
3. Stereotype
   Biedt de mogelijkheid het stereotype van het concept te kiezen.
4. Datatype
   Biedt de mogelijkheid het datatype van het concept te kiezen.
5. Tagged values
   Deze velden vereenvoudigen het vullen van de noodzakelijke DCM tagged values. Afhankelijk van het gekozen datatype zullen één of meerdere tags uitgegrijst zijn.
   Door de muis over de velden te hoveren, kan de betekenis van de velden worden achterhaald.
   DCM::ConceptId: Id van het concept. Deze tag wordt gegenereerd en is niet wijzigbaar.
   DCM::DefinitionCode: Code die de betekenis van het concept aangeeft. De tag kent drie velden: codesysteemnaam, code en codenaam.
   Voor de codesystemen SNOMED CT en LOINC is het mogelijk op grond van de code de naam automatisch aan te vullen (zie punt 7).
   DCM::ReferencedConceptId: ConceptId van de zib waar naar verwezen wordt.De tag kent drie velden: conceptId, zib naam en Engelse zibnaam.
   Normaal wordt de zibnaam gekozen dmv de dropdownlijst. Indien de zib daar (nog) niet in staat, kunnen de gegevens ook handmatig ingevoerd worden na het checken van de checkbox (zie punt 8).
   DCM::AssigningAuthority: Gegevens van de uitgevende organisatie van een nummersysteem (datatype II). De tag kent twee velden: nummersysteem naam en identificatie.
   DCM::Example: Optioneel voorbeeld van de waarde die het concept kan aannemen.
6. Notes
   Toont de inhoud van de concept definitietekst. Hoewel deze in dit onderdeel te wijzigen is, is het aan te bevelen dit via de tweetalige editor te doen.
7. Codenaam aanvullen
   Codenaam: Bij SNOMED CT en LOINC codes kan met deze checkbox er voor gekozen worden om de codenaam op grond van de code automatisch aan te vullen.
   In de configuratie is in te stellen of de Engelse naam of(indien beschikbaar) de Nederlandse naam genomen wordt.
   
8. Handmatige zib verwijzing
   Standaard wordt bij een verwijzing naar een andere zib, deze gekozen uit een dropdown lijst. Alle gegevens worden dan automatisch gevuld.
   Als de zib niet in de lijst staat, kunnen na het checken van deze box, de gegevens handmatig ingevoerd worden.
9. Tweetalige notes editor
   Hiermee wordt de tweetalige editor gestart om het aanmaken en wijzigen van de tweetalige definitie te vereenvoudigen.
10. Actie knoppen
    Klaar: Ingevoerde wijzigingen opslaan en scherm sluiten
    Annuleer: Scherm sluiten en element niet aanbrengen.
    Invoer in EA: Scherm sluiten, eventuele wijzigingen negeren en verder gaan in EA.

Waardelijsten

De hulpdialoog van de invoer van waardelijst eigenschappen wordt getoond als artifact van het type Document uit de Artifacts toolbox in het diagram wordt gesleept.
Het gedrag van deze hulpdialoog wordt beïnvloed door de keuzes in de configuratie.

		Figuur 6: Hulpdialoog voor het invoeren van waardelijstgegevens.

1. Aanwijzigen
   Instructie hoe na het aanmaken verder gegaan moet worden om de waardelijst automatisch de juiste naam te geven.
   Let op! De naam van de waardelijst zal in eerste instantie "Volgt" zijn. Laat de naam zo.
2. Tagged values
   DCM::ValueSetId: Automatisch gegenereerde OID voor de waardelijst.
   DCM::ValueSetBinding: De dropdownlijst geeft de mogelijke waarden voor de binding. Default wordt Extensible geselecteerd.
3. Actie knoppen
   Klaar: Ingevoerde wijzigingen opslaan en scherm sluiten.

Connectors

Een hulpdialoog voor de invoer van connector eigenschappen wordt getoond als connector wordt aangebracht tussen een class element en een document artifact of tussen twee class elementen.
Als een connector tussen een constraint en boundary wordt aangebracht, wordt geen dialoog getoond, maar wordt wel het type connector gecontroleerd en eventueel aangepast.
Als de boundary van het type zib begrenzing is, zal de constraint gevuld worden met een standaardtekst.
Het gedrag van deze hulpdialoog wordt beïnvloed door de keuzes in de configuratie.

		Figuur 7: Hulpdialoog voor het invoeren van connector gegevens bij waardelijsten.

1. Naam waardelijst
   Automatisch gegenereerd voorstel voor de Nederlandse en Engelse naam van het concept. De naam mag geen spaties bevatten.
   Het voorstel is gebaseerd op de naam van het CO of CD concept waar de connector naar toe loopt en op de eventueel al bestaande waardelijsten die aan het concept hangen.
2. Type waardelijst
   Indien het concept waar de connector naar toeloopt datatype CD heeft kan hier aangegeven worden of de lijst uit losse elementen uit een codesysteem bestaat of uit een heel codesysteem (incl. ref sets en expressies).
   Bij datatype CO zullen de keuzes uitgegrijst zijn.
3. Actie knoppen
   Klaar: Ingevoerde wijzigingen opslaan en scherm sluiten.
   Invoer in EA: Scherm sluiten, eventuele wijzigingen negeren en verder gaan in EA.

		Figuur 8: Idem tussen classes.

1. Van .. naar
   Namen van de concepten die door de connector verbonden worden.
2. Type connector
   Type van de aangebrachte connector. Aangezien alleen composition en aggregation toegestaan zijn, zal als er een ander type gekozen is dit als fout worden aangegeven.
   EA biedt helaas niet de mogelijkheid dit vooraf in te perken.
3. Cardinaliteit
   Een dropdown lijst biedt de mogelijkheid een keuze te maken uit de in EA gedefinieerde cardinaliteiten.
4. Actie knoppen
   OK: Ingevoerde wijzigingen opslaan en scherm sluiten.
   

Boundaries

		Figuur 8: Configuratiescherm van de add-in

1. Type boundary
   Voor de zibs zijn drie boundaries voorgedefinieerd. De keuzes staan vermeld als type boundary.
   Mocht een andere boundary gewenst zijn, moet het scherm via de knop 'Invoer in EA' verlaten worden.
2. Extra gegevens
   Afhankelijk van het gekozen type zijn extra gegevens nodig. De keuze activeert één van de invoervelden.
3. Aanwijzingen<br Voor ieder type boundary worden aangepaste aanwijzingen gegeven om de boundary en de eventueel connectors op de juiste wijze aan te brengen.
4. Actie knoppen
   Klaar: Ingevoerde wijzigingen opslaan en scherm sluiten
   Invoer in EA: Scherm sluiten, eventuele wijzigingen negeren en verder gaan in EA.

Configuratie van de add-in

Een aantal aspecten van de werking van de add-in zijn configureerbaar.

		Figuur 10: Configuratiescherm van de add-in

1. Invoerdialoog keuzes
   Concept eigenschappen: Indien gecheckt zal als een nieuwe data element hetzij uit de toolbox hetzij uit de standaard datatypes op het diagram wordt gesleept, een zib specifiek invoerdialoog getoond worden.
   

   De checkbox is tristate, dwz dat er drie toestanden zijn: geen vink=geen dialoog, vink= dialoog voor nieuwe concepten en gevuld vierkant (double check)=ook edit dialoog na double click op het item.

   Waardelijst eigenschappen: Indien gecheckt zal het in het diagram slepen van een document artifact een zib specifiek invoerdialoog scherm oproepen.
   Connector eigenschappen: Indien gecheckt zal bij het aanbrengen van een connector een zib specifiek hulpscherm opgeroepen worden en zal daarna het juiste type connector worden aangebracht.
   Boundary eigenschappen: Indien gecheckt zal bij het aanbrengen van een boundary een zib specifiek hulpscherm opgeroepen worden en zullen daarna he vereiste tags worden aangemaakt en eigenschappen van de boundary aangepast worden conform de afspraken hierover.
   Delete dialoog: Indien gecheckt zal bij het verwijderen van een 'Class' element uit een diagram de vraag gesteld worden of het element ook uit de projectbrowser verwijderd moet worden. Standaard gebeurt dit niet.
   Concept Id's aanvullen: Indien gecheckt, zal bij het aanmaken van een nieuw concept gecontroleerd worden of er concepten zonder DCM::ConceptId zijn.
   

   Indien dit zo is zal de vraag gesteld worden of deze eerst gegenereerd en toegekend moeten worden voordat een nieuwe Id wordt aangemaakt.
   

   In edit mode zal indien het gekozen element geen Id heeft gevraagd worden of een Id eerst toegekend moet worden.
   

   Foutieve Id's verwijderen: Als 'Concept Id's aanvullen' gecheckt is en de vraag om nieuwe Id's te genereren met Ja is beantwoord, zullen, als dit item gecheckt is, evt. bestaande DCM::ConceptId tags verwijderd worden.
2. Vertaalservice
   Google Translate webpage: Indien gecheckt, is de knop voor vertaling via de Google Translate webpagina geactiveerd.
   Google Translate service: Indien gecheckt, is de knop voor vertaling via de Google Translate service geactiveerd.
   

   Dit is een betaalde service. Om de service te kunnen gebruiken moet de locatie van de Google credentials json file op gegeven worden.

3. Google credentials locatie
   

   Locatie waar de Google credentials json file staat. Deze file is nodig om van de vertaal service te kunnen gebruiken.
   

   Met de knop Zoeken wordt een filebrowser window geopend om de file te selecteren.

4. Taal code definities
   Indien bij een SNOMED CT of LOINC code ervoor gekozen wordt om de codeomschrijving automatisch te vullen op basis van de code, kan hier gekozen worden of dit de Engelse of (indien beschikbaar) de Nederlandse omschrijving is.
5. Actie knoppen
   Opslaan: Ingevoerde wijzigingen opslaan en scherm sluiten
   Annuleren: Scherm sluiten en eventuele wijzigingen negeren.
6. Overige opties
   Zib prefix: Als een zib niet deze prefix heeft, zullen de invoerdialogen niet getoond worden (voorlopig readonly).
7. OID bases
   Om herkend te worden als valide onderdeel van een zib en om mee te tellen bij het bepalen van id's voor nieuwe elementen, moeten de bestaand elementen de volgende(symbolische) OID's als basis hebben.
   Zibs: Root OID voor de DCM::Id's (voorlopig readonly). Als er geen geldige DCM::Id gedefinieerd is kan automatische nummering niet plaatsvinden.
   Concepten: Symbolische OID voor de concepten van een zib, inclusief het rootconcept (voorlopig readonly).
   Op grond van deze symbolische OID worden de id's voor nieuwe concepten gegenereerd.
   Voor nieuwe zibs moet alleen de basis bekend te zijn. Het informatie model van een nieuwe zib mag leeg gestart worden, zonder rootconcept.
   Waardelijsten: Basis OID voor waardelijsten (voorlopig readonly).
   Op grond van deze OID worden de id's voor nieuwe waardelijsten gegenereerd.
8. Statusbalk
   Geeft de locatie aan waar de configuratie file is opgeslagen.

Known issues

- Doordat in het verleden in een aantal zib's de legenda op foutieve wijze gekopieerd is hebben deze zib's feitelijk geen eigen legenda maar een verwijzing naar de legenda van een andere zib.
In de presentatie van het informatie model in EA is dit niet te zien, dit is uitsluitend te constateren in de onderliggende database. Het levert dus ook geen problemen op.
Niettemin geeft dit aanleiding tot de informatieve mededeling: 'Gedeelde legenda' en een aantal legenda's van nul in plaats van één.

- In de laatste testsectie wordt getracht vast te stellen of het aantal elementen van de zib in de projectbrowser overeen komt met het aantal in het informatie model diagram.
Om een aantal redenen is deze test nog niet helemaal betrouwbaar en geeft soms aanleiding tot onterechte meldingen.
Niettemin verdient het aanbeveling om bij deze meldingen projectbrowser en het informatie model te checken op losse elementen.
Een bekend probleem ontstaat wanneer een element in het informatie model weggegooid wordt in plaats van in de project browser: het element blijft dan wel onderdeel van de zib maar wordt niet getoond.

- Bij een aantal verwijzigen binnen een zib naar andere zibs wordt binnen de boundary één specifiek element van de andere bouwsteen opgenomen om daar bv. een andere waarde lijst aan te hangen (zie bv nl.zorg.Ademhaling)
Dit element heeft een DCM::ConceptID dat niet bij verwijzende zib past: dit is aanleiding voor een (onterechte) foutmelding.

Configureerbare gegevens

Naam	Beschrijving	Gebruik	Locatie	Huidige waarde	Wijzigbaar via UI
WikiBase	De basis url van deze wiki	Hiermee wordt de url van deze pagina aangemaakt.	Properties.Settings.Default.WikiBase *	https://zibs.nl/wiki	Nee

* De C# applicatie settings worden opgeslagen in het standaard app.config bestand van de applicatie