Release-hantering för openEHR-templates
Innehållsförteckning
Versionshistorik
Version | Datum | Beskrivning | Ansvarig |
1.0 | 2024-05-27 | Publicerat första version. | openEHR Sverige |
2.0 | 2025-01-03 | Justerat text i 2.3.3 om taggnamn (Github) och 2.4.1 om namnsättning vid filexport (Archetype Designer). Anpassningar baserade på dokumentet "Versionering för openEHR-templates." Lagt till avsnitt 2.5: "Exempel-compositions för en template." | Oscar Karlsson |
1 Syfte
Syftet med detta dokument är att dokumentera hur vi i openEHR Sverige vill jobba med release-hantering för openEHR-templates, för att:
underlätta och effektivisera arbetet med templates
ha ett underlag att ta vidare till olika forum för att jobba för gemensamma överenskommelser kring detta.
2 Lathund – så här gör du en GitHub-release
När du har en version som ska användas för test eller t.ex. för att ta fram ett formulär så är det lämpligt att göra en release i GitHub, och därmed spara undan hur repositoryt på aktuell branch samt tillhörande OPT- och webtemplate-format av templaten såg ut vid detta tillfälle.
Man kan göra releaser i alla utvecklingsfaser, dvs. för både alpha-, RC- och publicerade versioner av en template. För mer information om versionering, läs dokumentet Versionering för openEHR-templates.
För att göra en GitHub-release, följ nedanstående anvisningar.
2.1 Öppna GitHub-repositoryt
Gå till aktuellt GitHub repository i en webbrowser, för openEHR Sverige är det detta repository:
modellbibliotek/CKM-mirror
2.2 Öppna release-vyn
Till höger om listan med filer och README-filen så finns länken ”Releases”, klicka på den:
2.3 Skapa en ny release
2.3.1 Påbörja arbetet
På Releasesidan, klicka på ”Draft a new release”:
2.3.2 Välj branch
Klicka på dropdownen för target branch, och välj aktuell branch (dvs. den branchen där den template du vill skapa en release för finns):
2.3.3 Skapa tagg
Klicka på dropdown-en ”Choose a tag”
Ange taggnamn som <use case + template-namn>.<sem_ver>, på engelska, dvs. t.ex.
ChemotherapyMedicationOrder.1.0.0-alpha.3
ChemotherapyMedicationOrder.1.0.0-rc.1
ChemotherapyMedicationOrder.1.0.0
och klicka sedan på ”Create New tag”:
2.3.4 Fyll på release information och publicera release
Ange Release titel till samma sak som taggen du just skapade:
Fyll i en beskrivning av releasen, och klicka sedan på knappen ”Publish release”:
2.4 Lägg till template i olika format i release
2.4.1 Exportera och namnge template
Exportera templaten i (åtminstone) OPT- och webtemplate-format, från Archetype Designer:
Öppna templaten i AD och klicka på ”Export” i menyn i Archetype Designer:
Välj vilket primärt språk respektive vilka översättningar du vill ha i de exporterade filerna:
Exportera till OPT respektive till webbtemplate. (Det är två separata steg, dvs. man behöver klicka på export två ggr och göra valen som beskrivs under punkt 9 a-c.):
Döp om de exporterade filerna enligt nedan:
<use case + template-namn>.<sem_ver>.<primary language>.<translation languages, dot separated>.<export type suffix(es)>, dvs. t.ex.
ChemotherapyMedicationOrder.1.0.0-alpha.3.sv.en.opt
ChemotherapyMedicationOrder.1.0.0-alpha.3.sv.en.wt.json
eller
ChemotherapyMedicationOrder.1.0.0-rc.1.sv.en.opt
ChemotherapyMedicationOrder e.1.0.0-rc.1.sv.en.wt.json
eller
ChemotherapyMedicationOrder.1.0.0.sv.en.opt
ChemotherapyMedicationOrder.1.0.0.sv.en.wt.json
2.4.2 Ladda upp template i releasen
Gå tillbaka till releasen i GitHub, och klicka på ikonen för att editera releasen:
Ladda upp de exporterade filerna och klicka sedan på ”Update release”:
2.5 Ta fram exempel-compositions för en template
En exempel-composition är en konkret instans av data som följer strukturen i en specifik openEHR-template. Den innehåller ifyllda fält med exempelvärden som illustrerar hur data kan representeras enligt templaten. De är särskilt användbara vid tidiga tester av en template, innan det finns integrationer eller system som producerar faktisk data. Exempel-compositions är också nödvändiga för att genomföra eventuella mappningar.
Exempel-compositions kan tas fram på flera sätt:
2.5.1 Alternativ 1 – använda en formulär-byggare
Ett sätt att ta fram exempel-compositions är att använda en formulär-byggare, som exempelvis Betters Frombuilder i Betters sandbox:
https://sandbox.better.care/studio/form-builder/select
I just Betters sandbox ser stegen ut som nedan, men motsvarande kan förstås göras i andra verktyg.
Ladda upp din (version av) template:
I sidebar-en längst ner till vänster på sidan, välj pilen för ”Import”:Ladda upp OPT-filen för aktuell template:
Klicka på ”Create New Form”:
Välj aktuell template i dropdown-en:
Dra-och-släpp aktuella delar av innehållet från templaten in i formulär-vyn:
För eventuella rödmarkerade delar i formuläret, gör de aktiva val som behövs, tex:
Spara formuläret, och ange något namn och klicka i status ”Active”:
Klicka på ”Preview”, för att få upp formuläret för användning/ifyllnad:
Fyll i (helst realistiska) exempel-värden i formuläret:
Man kan sedan validera data innan man skickar in formuläret, för att se om något behöver justeras i ifyllda värden eller i den underliggande template-en:
När du har ett ifyllt formulär som går igenom valideringen så är nästa steg att skicka in formuläret (spara en composition). För detta behöver man först välja ett EhrID (en patient som datat hör till) från dropdown-en i vänstermenyn. Denna lista visar Ehr-ID-n som finns i CDR-en.
Anteckna det Ehr ID du väljer här, då du behöver det senare för att kunna läsa ut den composition som skapas.
Sedan kan du skicka in formuläret (som en composition) genom att klicka på ”Save composition”:
Om detta lyckas får du en popup som den nedan, där compositionId för den composition i CDR-en där formulär-svaret sparats visas:
Kopiera/anteckna detta compositionId. (Denna popup visas dock ganska kort tid, så om du missar att kopiera compositionId så kan du antingen spara en ny instans, öppna dev tools i browsern och kopiera compositionId från responsen, eller läsa ut alla comositions för aktuell template med en AQL query.)
12. Läs ut composition med detta compositionId från CDR-en:
Detta kan göras antingen via standard API-et eller det proprietära API-et. För tillfället är det endast det proprietära API-et som stödjer både kanoniskt och flat format.
A) Med proprietära API-et:
Direktlänk till Betters proprietära API i sandbox-miljön: Better Platform - Sandbox.
Under composition GET,
expandera denna request, och tryck på ”Try it out”:
Fyll i det compositionID du antecknade tidigare, välj önskat filformat och tryck på ”Execute”.
Efterfrågad composition kan sedan kopieras från responsen:
Spara filen som .jason och inkludera den och eventuella ytterligare exempel-compositions i din github-release för template-en. Du kan med fördel inkludera en “max-populerad" och en “min-populerad” composition.
B) Med standard API-et
Direktlänk till Betters standard API i sandbox-miljön: Better Platform - Sandbox
Under composition GET:
expandera denna request, och tryck på ”Try it out”:
fyll i det Ehr ID och det compositionID du antecknat i tidigare steg, och klicka på ”Execute”:
Efterfrågad composition kan sedan kopieras från responsen:
Inkludera denna och eventuella ytterligare exempel-compositions i din github-release för template-en. Du kan med fördel inkludera en "max-populerad" och en "min-populerad" composition.
2.5.2 Alternativ 2 – använd en exempel-endpoint (dock ej del av standard-API-t)
Ett alternativ för att snabbt få fram en exempel-composition för en viss template är att använda en specifik endpoint för detta som finns i åtminstone Betters och EHRBase egna API-er.
Notera dock att värden som genereras från dessa inte nödvändigtvis är kliniskt rimliga.
I Betters sandbox finns exempel-endpoint som en del av deras Ehr API, direktlänk till detta API:
https://sandbox.better.care/institution/swagger-api/2;href=https:%2F%2Fsandbox.better.care%2Fehr%2Frest%2Fswagger%2Frest-api;panelTitle=EHR%20Server%20API
Där just exempel-endpointen ser ut så här:
Så det enda som är obligatoriskt att ange är just templateId, och det finns också möjlighet att ange tex format.
2.5.3 Alternativ 3 – använd en composition från en testmiljö (med testdata)
Om det finns en befintlig testmiljö för aktuellt användningsfall, där compositions genereras av en specifik formulärbyggare eller på annat sätt skapas av befintligt testflöde så kan förstås även exempel-compositions från en sådan testmiljö bifogas template-releasen.
Detta kan vara användbart för att skapa mer varierande exempel, man ett första test för att validera en ny/uppdaterad template gör med fördel i en sandbox-miljö enligt ovan.