VGR Fireplace

Exempel-instans

I Implementationsguider finns möjlighet att, utöver definierade artefakter, även inkludera instanser av desamma. Dessa kan fungera som konkreta pedagogiska exempel som kan underlätta förståelsen för såväl användare som förvaltare av implementationsguider och dess ingående delar.
Det kan också bidra till att hitta otydligheter eller luckor i de utvecklade profilerna och kan ses som ett första internt test.

Krav på exemplifiering av IG definitioner

  • Varje IG SKALL inkludera och publicera exempel - instanser av alla resurser som profileras i IG:n.
  • För varje profil
    • SKALL det finnas exempel-instanser för de definitioner och regler som profilen tillför jämfört med den profil den baseras på.
    • SKALL det finnas minst en exempel-instans som inkluderar alla Key elements (se flik i IG:ns webbsida för profilen).
    • BÖR det finnas en minimal exempel-instans innehållande endast obligatoriska och MS (must support) element.
  • För IG som utgör tillämpade profiler BÖR det finnas sammanhängande exempel-instanser som tillsammans representerar de olika användningsfall som IG:n syftar till att möjliggöra.
  • Exempel ska innehålla meningsfulla data. Ett exempel på meningsfulla data är att att de bör kunna återanvändas inom andra IG som specialiserar eller beror av den aktuella IG:n.

Dessa krav utgår från HL7 FHIR IG Guidance - Best Practices.

Namn på exempel-instans

Exempel-instanserna namnges på två olika sätt beroende på om de har en business identifier eller inte. Basresurs här avser den resurs som ligger till grund för profilen i IGn som exempliferas, alltså utan eventuella regionala eller tillämpningsprefix. OBS för exempel-instanser förkortas inte artefaktnamnet även om det är flera ord.

namn
Om resursen har en business identifier:
<basresursens namn förkortad om mer än två ord>-<typ av business identifier>-<värde på business identifier>
Exempel: Patient-PNR-191212121212

Om resursen saknar business identifier:
<basresursens namn förkortad om mer än två ord>-<unikt värde för exempelinstansen av denna resurs>
Exempel: Coverage-12345, QuestionnaireResponse-ABCD

Namnet är det som utgör exempelinstansens ID när det hänvisas till i andra artefakter, eftersom det står efter declarationen Instance:

titel
För exempelinstanser används titel för att särskilja dem från varandra i översiktsvyn i IGn, detta skiljer sig alltså från hur titel används i övriga artefakter.

Skrivs enligt mall <basresursens namn> with Exempel: Encounter with mandatory and must support elements only, Patient with identifier VGR LRID 19810829M071

Declaration

  • Instance: <exempelinstansens namn>

Keywords

  • InstanceOf: <namn på den profil detta är en instansiering av>
  • Title: <exempelinstansens titel>
  • Description: "Exemplifies <samma som InstanceOf> <beskrivning av syftet med exemplet; vad exempliferar denna instans?>"
  • Usage: #example

Exempel på exempel-instans

Instance: Patient-LRID-19810829M071 
InstanceOf: VGRBasePatient
Title: "Patient with identifier VGR LRID 19810829M071"
Description: "Exemplifies a VGRBasePatient with identifier of type LRID, i.e. on 'VGR Lokalt reservid' format."
Usage: #example

* identifier[LRID]
  * value = "19810829M071"
  * system = "https://fhir.vgregion.se/NamingSystem/LRID"
* name[0]
  * use = #official
  * family = "Mellannamn Efternamn"
  * given[0] = "Förnamn"
  * text = "Förnamn Mellannamn Efternamn"
  * extension[middleName].valueString = "Mellannamn"
  * extension[ownFamily].valueString = "Efternamn"
* gender = #female
* birthDate = "1981-08-29"
* address[0]
  * line[0] = "Careof"
  * line[1] = "Tillfällig adressrad"
  * city = "Orten"
  * postalCode = "54300"
  * extension[officialAddressType].valueCodeableConcept = $SCT_SE#63411000052104 "uppgiven adress"
* address[1]
  * line[0] = "Adressrad 1"
  * line[1] = "Adressrad 2"
  * line[2] = "Adressrad 3"
  * country = "DZ"
  * extension[officialAddressType].valueCodeableConcept = $SCT_SE#63401000052101 "utlandsadress"

Exempel på en inline exempel-instans

Exempel som används inline (contained) läggs i samma fil som det exempel som de hör till, eftersom de inte visas som eget exempel i IG:n. De har samma keywords som ett fristående exempel.

Instance: Encounter-ID12345
InstanceOf: VGRReimbursementEncounter
Title: "Encounter with associated Coverage (betalningsförbindelse)"
Description: "Exemplifies VGRReimbursementEncounter using an #inline Account to connect to a Coverage describing the financial agreement with external payor" 
Usage: #example
* contained[0] = Encounter-ID12345-Inline-Account
* account = Reference(Encounter-ID12345-Inline-Account)

Instance: Encounter-ID12345-Inline-Account
InstanceOf: VGRReimbursementAccount
Title: "Account for inline usage in Encounter with associated Coverage"
Description: "Exemplifies the #inline Account required to connect an Encounter to a Coverage." 
Usage: #example

Referenser till en exempel-instans

Om en exempel-instans innefattar element som håller en referens (Reference) till en annan instans av något slag, identifieras denna med sitt logical id. Möjliga logical id är de som identifierar någon av de instanser av aktuell resurstyp som finns tillgänglig i den aktuella IG:n, eller någon IG som denna beror av (t.ex. VGRBase eller SEBase).

* subject = Reference(Patient/Patient-LRID-19810829M071)

Återanvändning

Det bör undvikas att skapa exempel-instanser som inte representerar något av det som definieras och tillförs i IG:n. Om det för exemplifiering ändå behövs instanser av resurser som inte profilerats inom aktuell IG, bör det först undersökas om erforderlig exempel-instans finns att tillgå i någon IG som aktuell IG beror av, t ex VGR Base eller SE Base. I första hand bör i så fall dessa användas genom att refereras från aktuell IG:s exempel.