Fælles Medicinkort - Dokumentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== FMKRequest/response headers i soap-header (Tidligere løsning) ======

**OBS!** Denne løsning beskriver skemaversionen, der placerer FMKRequestHeader og -response i de respektive soap-headers. Denne løsning bliver afløst af en skemaversion, der placerer FMKHeaderne direkte i hhv. request og respons.
Dette er derfor **kun** en reference for udviklere, der allerede **har** implementeret denne løsning.
For ny udvikling, se [[fmk:1.6.0:xml-elementer:FMKRequest/response headers i body| den blivende løsning]] i stedet!

Et overblik over transitionen samt forskellene på skemaversionerne kan ses [[fmk:1.6.0:xml-elementer:beskrivelse af parallel skemastruktur | her]] .

SecurityHeader og MedcomHeader er stadigvæk defineret uændret i DGWS standarden.

====== Generel Request Header ======

<code xml>
<FMKRequestHeader  ... >
    <OnBehalfOfHeader>
    ...
    </OnBehalfOfHeader>
    <WhitelistingHeader>
    ...
    </WhitelistingHeader>
    <ConsentHeader>
    ...
    </ConsentHeader>
    <MinLogSessionId>...</MinLogSessionId>
    <Paging>
    ...
    </Paging>
    <ExtendedValidationHeader>
    ...
    </ExtendedValidationHeader>
    <FMKConfigurationLastUpdated>
    ...
    </FMKConfigurationLastUpdated>
    <PreflightOnly/>
    <PartOfBatchOperation/>
</FMKRequestHeader>
</code>

==== OnBehalfOfHeader ====
FMK specifik header med oplysninger om person, som der foretages en handling på vegne af. Se også [[fmk:1.6.0:generel:bemyndigelse|Bemyndigelse]]. 

Eksempel:
<code xml>
  <OnBehalfOfHeader>
    <HealthcareProfessionalIdentifier source="Autorisation">BR56T</HealthcareProfessionalIdentifier>
  </OnBehalfOfHeader>

</code>

==== WhitelistingHeader ==== 
FMK specifik header med oplysninger der anvendes til validering af FMK adgangen i henhold til aktive whitelistings, såsom systemnavn, -ejer og -version, OrgUsingId og -Name, se [[fmk:generel:systemautorisation|Systemautorisation]]

Eksempel:
<code xml>
  <WhitelistingHeader>
        <SystemOwnerName>Leverandør A</SystemOwnerName>
        <SystemName>System A</SystemName>
        <SystemVersion>1.0.2</SystemVersion>
        <OrgResponsibleName>ROS IT-afdeling</OrgResponsibleName>
        <OrgUsingName>Alb Plastikkirurgisk Dagafdeling</OrgUsingName>
        <OrgUsingID NameFormat="medcom:sor">621491000016008</OrgUsingID>
        <RequestedRole>Læge</RequestedRole>
    </WhitelistingHeader>
</code>

==== ConsentHeader ====

FMK specifik header der angiver, om en handling er tilladt som følge af samtykke eller værdispring. Se [[fmk:1.6.0:xml-elementer:soap_header_--_specifikt_omkring_samtykke|Samtykke]]

Eksempel:
<code xml>
 <ConsentHeader>
        <Consent source="User">
            <FromDate>2023-03-24</FromDate>
            <ToDate>2023-03-30</ToDate>
            <ConsentType>PrivateDataConsentGiven</ConsentType>
            <Content>MedicineCard</Content>
        </Consent>
    </ConsentHeader>
</code>

==== MinLogSessionId ====
I NSP's MinLog service er der på registreringstidspunktet mulighed for at angive et sessions id (også kaldet Correlation ID). Ideen er, at minlog registreringer der stammer fra den samme behandling, konsultation o.lign. tildeles samme session id, som derved giver de sites/apps der viser MinLog for borgeren, en bedre mulighed for at gruppere log linjer per session i visningen. FMK kan af gode grunde ikke selv konstatere, om et opslag eller en handling stammer fra samme behandling, men klientsystemerne vil i nogle tilfælde kunne det, og derfor er der blevet indført mulighed for, at FMK klientsystemerne kan sende en MinLogSessionID med i request-headeren, som videresendes til MinLog2 registreringsservicen, når opslaget/handlingen er blevet udført. Der er ingen særlige krav til indholdet af id'et, udover at det er en streng på max 40 tegn.

Eksempel:

<code xml>
<MinLogSessionId>FMK_Klient_X_288938787902</MinLogSessionId>
</code>



==== Paging ====
Hvis der i et svar returneres en stor mængde elementer, er der mulighed for at der i kaldet kan angives parametre til brug for paginering, således at de returnede svar ikke blive unødigt store. FMK vil selv i visse tilfælde gøre det uden klienten har bedt om det, igen for at undgå, at svarene bliver så store så svartiderne risikerer at blive påvirkede. Hvis paginering er anvendt returneres information herom i [[fmk:1.6.0:xml-elementer:request_response_headers##paging|response headeren]] som klienten herefter kan kopiere ind i request headeren for at hente næste "page" af data hvis det måtte være relevant.

I requestet skal angives hhv. 
PagingObject: hvilke objekter pagineres der henover (er ikke altid givet, hvis et svar kan indeholde flere under-objekter)
PageSize: hvad er det største antal objekter man ønsker retur for "PagingObject" typen
LastReceived: pegepind til de data man modtog i det seneste kald, så FMK i det efterfølgende kald returnerer paginerede data fra det sted. LastReceived kan findes i ResponseHeader fra det seneste kald. Angives LastReceived ikke, returneres side 1.

Eksempel:

Et kald til [[fmk:1.6.0:services:hent_udleveringer|Hent udleveringer]] returnerer totalt 37 udleveringer, men der ønskes max 25 udleveringer returnerer pr. kald. Det er første kald, så LastReceived er ikke angivet:

<code xml>

<FMKRequestHeader>
...
  <Paging>
    <PagingObject>Handovers</PagingObject>
    <PageSize>25</PageSize>	
  </Paging>
...
</FMKRequestHeader>
</code>

Eksempel på response header fra ovenstående kald:

<code xml>
<FMKResponseHeader>
...
  <Paging>
    <PagingObject>Handover</PagingObject>
    <ParentObjectIdentifier type="Warrant">12321233</ParentObjectIdentifier>
    <PageSize>25</PageSize>
    <TotalSize>37</TotalSize>
    <LastReceived>
      <Field name="Identifier">983552773455</Field>
    </LastReceived>
  </Paging>
..
</FMKResponseHeader>
</code>

Ønsker klienten at hente de efterfølgende udleveringer, skal det næste kald indeholde et PagingElement hvor LastReceived er kopieret fra ovenstående svar, d.v.s.:

<code xml>
<FMKRequestHeader>
...
  <Paging>
    <PagingObject>Handovers</PagingObject>
    <PageSize>25</PageSize>
    <LastReceived>
      <Field name="Identifier">983552773455</Field>
    </LastReceived>
  </Paging>
...
</FMKRequestHeader>
</code>

Ikke alle kald eller delementer af svar supporterer paging. Der vil senere blive tilføjet information om hvilke services og delelementer hvorpå dette supporteres.

==== ExtendedValidationHeader ====
Herunder angives de fejlkoder vedr. udvidet validering, som der hhv. ønskes foretaget udvidet validering for, og som der ønskes ignoreret. Der findes 2 typer udvidet validering:
  * forud valgte udvidede valideringer, som vil blive anvendt med mindre de er angivet i SkipValidations elementet (eller fravalgt i system whitelistingen)
  * udvidede valideringer som klienten eksplicit kan bede om at få udført (også omtalt som "valgfri" udvidede valideringer), ved at angive dem i ApplySelectedOptionalValidations elementet i request headeren, alternativt til at udfylde koderne enkeltvist kan ApplyAllOptionalValidations angivet, hvilket aktivere samtlige valgfrie udvidede valideringer.

Valgfrie udvidede validering er på nuværende tidspunkt ikke anvendt i FMK, men indføres i 1.6.0 så det er en mulighed i fremtiden at FMK kan tilbyde udvidede valideringer som kunne være nyttige for klienterne, men uden at den pågældende udvidet validering bliver et krav som alle skal overholde.

Ud over listen af fejlkoder kan der angives en ElementPath der referer til det element i requestet, som den pågældende valideringer til/fra-valgt for. Udelades ElementPath gælder fra/tilvalgtet hele requestet.

Herunder et eksempel, hvor klienten har tilvalgt valideringerne 10801 og 10802, fravalgt 10100 og 10101 for den første DrugMedication i requestet, samt fravalgt 10100 og 10102 for den anden DrugMedication i kaldet:

<code xml>
<ExtendedValidationHeader>
  <ApplySelectedOptionalValidations>
    <ErrorCode>10801</ErrorCode>
    <ErrorCode>10802</ErrorCode>
  </ApplySelectedOptionalValidations>
  <SkipValidations>
    <ExtendedValidation>
      <ErrorCode>10100</ErrorCode>
      <ErrorCode>10101</ErrorCode>
      <ElementPath>DrugMedication[1]</ElementPath>
    </ExtendedValidation>
    <ExtendedValidation>
      <ErrorCode>10100</ErrorCode>
      <ErrorCode>10102</ErrorCode>
      <ElementPath>DrugMedication[2]</ElementPath>
    </ExtendedValidation>
  </SkipValidations>
</ExtendedValidationHeader>
</code>
==== FMKConfigurationLastUpdated ====
Der er mulighed for at få oplysninger om specifikke dele af FMK's konfiguration, i tilfælde af at det er nødvendigt at udstille information om ændringen, så klienter kan indrette sig efter hvilken konfiguration, FMK er i. Sædvanligvis foretages der ikke større ændringer i FMK uden at det indgår som en del af en ny FMK snitflade/extension, men i enkelte tilfælde foretages også semantiske ændringer der kan styres vha. disse konfigurationsoplysninger. Hvis FMKConfigurationLastUpdated sendes med i et kald til FMK, returneres FMKConfigurationUpdatedWarning elementet i response headeren, i tilfælde af at konfigurationen har ændret sig siden det tidsstempel der er angivet i FMKConfigurationLastUpdated elementet. Herefter kan klienten kalde [[fmk:1.6.0:services:hent_fmk_konfiguration|GetFMKConfiguration]] servicen og indhente detaljerede oplysninger om konfiguration. Hvis elementet udelades, returnes ingen konfigurationsinformation.

Eksempel:

<code xml>
  <FMKConfigurationLastUpdated>2025-10-31T00:00:00</FMKConfigurationLastUpdated>
</code>

Se [[fmk:1.6.0:xml-elementer:request_response_headers#fmkconfigurations|FMKConfigurations]] vedr. det returnerede svar.
==== PreflightOnly ====
Anmodning der kan anvendes i request headeren for at angive, at en opdaterende handling ikke skal foretages, men i stedet kun valideres så langt som det er teknisk muligt.

<code xml>
<FMKRequestHeader>
..
<PreflightOnly/>
...
</FMKRequestHeader>
</code>
==== PartOfBatchOperation ====

Flag der kan anvendes for at angive, at en operation skal ses som en del af en batch operation (UpdateMedicineCard), og derved skal udvidede valideringer ikke længere foretages. Dette element er foreløbigt reserveret til fremtidig brug, og vil p.t. ikke have nogen betydning for kald til FMK.

<code xml>
<FMKRequestHeader>
   ...
   <PartOfBatchOperation/>
   ...
</FMKRequestHeader>
</code>
====== Generel response header ======

Elementer af ikke-kliniske data, der er relevante på tværs af svar fra mange services, er samlet i en response header. Derved holdes kliniske og rent snitflade tekniske data bedre adskilt, og giver en større fleksibilitet mht. ændringer af ren teknisk karakter, samt bedre muligheder for FMK klienter. Oversigt over indhold:

<code xml>
<FMKResponseHeader  xmlns="http://fmk-teknik.dk/160"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://fmk-teknik.dk/160 FMKResponseHeader.xsd">
                         
    <KnownPersonIdentifiers>
    ...
    </KnownPersonIdentifiers>
    <MedicineCardInvalid />
    <VersionMismatchWarning />
    <HiddenData>
    ...
    </HiddenData>
    <Paging>
    ...
    </Paging>
    <Warnings>
       ...
    </Warnings>
    <FMKConfigurationUpdatedWarning>
        ...
    </FMKConfigurationUpdatedWarning>
    <Informations>
        ...
    </Informations>
</FMKResponseHeader>
</code>

==== KnownPersonIdentifiers ====

Informationer omkring kendte PersonIdentifiers for den fremsøgte person, i tilfælde af patienten har skiftet CPR-nummer, eller eCPR som er blevet ændret)

<code xml>
    <KnownPersonIdentifiers>
        <KnownPersonIdentifier>
            <PersonIdentifier source="CPR">2512489996</PersonIdentifier>
            <Name>Nancy Berggren</Name>
            <ValidSince>1948-12-25</ValidSince>
        </KnownPersonIdentifier>
        <KnownPersonIdentifier>
            <PersonIdentifier source="X-eCPR">25124899Y6</PersonIdentifier>
            <Name>N. Berggren</Name>
            <ValidSince>2025-10-27</ValidSince>
        </KnownPersonIdentifier>
    </KnownPersonIdentifiers>
</code>

==== MedicineCardInvalid ====

Response headeren kan indeholde en markering af at medicinkortet for den pågældende person er ugyldigt, vha. ''MedicineCardInvalid''-elementet. Markeringen kan sættes og fjernes af den dataansvarlige (SDS), eventuelt på opfordring af en læge, og betyder at der er sket en fejl under opdatering af medicinkortet således at det ikke længere er retvisende. 

Medicinkortet skal efterfølgende enten ignoreres eller bringes tilbage i korrekt stand. Af hensyn til sidstnævnte er det derfor muligt at hente og opdatere ugyldige medicinkort. 

Se [[fmk:generel:ugyldig-markering_af_data|Ugyldig-markering og administrativ sletning af data]]

==== VersionMismatchWarning ====
Markering af at opdatering er sket på baggrund af forkert medicinkort-version, svarende til den tidligere ‘VersionMismatchWarning’ som fandtes på en lang række 1.4.x responses fra FMK.

==== HiddenData ====
Information omkring privatmarkering eller af andre årsager skjulte data. 
I tilfælde af udeladte data angives elementet ''<HiddenData>'' med yderligere underelement der beskriver årsagen.
Det inkluderer identifikation på klienten, årsag til udeladelse samt en liste af de udeladte elementer

OBS! Dette felt er generaliseret i forhold til tidligere af hensyn til en evt. kommende MinSpærring integration. P.t. vil kun ''<HasNegativeConsent>'' være implementeret som grundlag, men altså med mulighed for udvidelser. 


Eksempel:

<code xml>
<HiddenData>
  <PersonIdentifier source="CPR">2512489996</PersonIdentifier>
  <HasNegativeConsent/>
  <HiddenElements>
    <HiddenElement>
      <Type> DrugMedication </Type>
      <Identifier> 123 </Identifier> 
      <Version> 1 </Version>
    </HiddenElement>
    <HiddenElement>
    ...
    </HiddenElement>
  </HiddenElements>
</HiddenData>
</code>

==== Paging ====

Paginering anvendes i tilfælde af, at der skal returneres et stort antal resultater i et svar. Klienten har i request headeren mulighed for at angive pagineringssidestørrelsen, d.v.s. antal svar der max returneres, men i visse tilfælde overtrumfer FMK's interne grænser for pagineringsstørrelser denne parameter, for at undgå problemer med at danne meget store svar.  I svaret returneres information om resultatstørrelse, hvilket objekttype der pagineres over, samt hvilket parent object, d.v.s. "ejer" af objekterne der pagineres over, fx. "Warrant" hvis der pagineres over "Handover" objekter. Se [[fmk:1.6.0:xml-elementer:request_response_headers#paging|Paging]] afsnittet herover vedr. request headeren, for et eksempel på anvendelse af paginering.



==== Warnings =====
Advarsler vedrørende potentielle problemer eller andet, som brugeren bør være opmærksom på, i lighed med de eksisterende advarsler på dosisdispenserings-kortet.  Advarslerne er på samme form som fejlkoder og udvidede valideringer, d.v.s. med en fejlkode, -tekst og detaljer, hvorunder ElementPath til det element i request'et som advarslen vedrører, er angivet. Der vil senere blive publiceret en liste over hvilke advarsler FMK vil kunne returnere i et svar.

Bemærk i øvrigt, at det ikke har været vurderet som hensigtsmæssigt at flytte DD advarslerne til headeren, idet de typisk knytter sig til et specifikt element i selve DD kortet. Et eksempel på dette er advarslen til lægen om en igangværende ekspedition, ifm annullering af recepten. 

Eksempel:
<code xml>
<Warnings>
  <Warning>
    <FaultCode>10800</FaultCode>
    <FaultText>Advarselstekst vedr. klausuleret tilskud</FaultText>
    <FaultDetails>
      <KeyValueSet>
      <Key>DrugMedicationIdentifier[1]</Key>
        <Value>2190751217130</Value>
      </KeyValueSet>
    </FaultDetails>
  </Warning>
</Warnings>
</code>

==== FMKConfigurationUpdatedWarning ====
Der returneres information om FMK's senest ændrede konfigurationsdato, hvis den har ændret sig siden den i request headeren angivne [[fmk:1.6.0:xml-elementer:request_response_headers#fmkconfigurationlastupdated|FMKConfigurationLastUpdated]] dato. Med "konfiguration" menes her egenskaber som gør, at FMK's semantik vedr. en eller flere services ændrer sig. Det kunne eksempelvis være ny funktionalitet, som kun er delvis implementeret og på vej mod en endelig implementationsfase (fx overgang fra 1.6.0 fase 1 til fase 2). 

Eksempel:
<code xml><FMKConfigurationUpdatedWarning>2026-01-12T17:14:00</FMKConfigurationUpdatedWarning>
</code>

==== Informations ====
Dette element er indtil videre reserveret til fremtidigt brug!

Det er tiltænkt som værende en måde dynamisk at kunne tilføje yderligere information til responses via response headeren, uden påkrævede snitfladeændringer.

Eksempel:

<code xml>
<Informations>
  <Information>
    <Text>AdditionalHeaderData</Text>
    <KeyValuePair>
      <Key>NewDrugMedicationState</Key>
      <Value>2190751217130</Value>
    </KeyValuePair>
    <KeyValuePair>
      <Key>State</Key>
      <Value>29</Value>
    </KeyValuePair>
  </Information>
  <Information>
    <Text>Some flag'ish type of information without KeyValuePair</Text>
  </Information>
</Informations>
</code>