These are the transactions defined for ips-pilgrimage
record consent from wallet - request
The Record Consent Request Event transaction is initiated by a Origin Country Health Solution against the Origin Country HIE. This transaction shall follow the IHE PCF record consent (ITI-108) transaction. The Origin Country Health Wallet acts as the Consent Record actor role and the Origin Country HIE acts as the Consent Registry actor role.
⟦not rendered: send_consent_request.svg⟧ — the IG Publisher renders it from input/images-source/send_consent_request.plantuml; no renderer was given to this build.
Trigger Events
- A new consent directive has been recorded by a Digital Health Wallet.
Message Semantics
Message Semantics Request
-
The message semantics for Record Consent Request utilizes a FHIR Consent resource set as PUT or POST http request.
-
See https://profiles.ihe.net/ITI/PCF/ITI-108.html for more details.
-
Specifically,
- Access Consent - Create (ITI-108)
- Access Consent - Update (ITI-108)
Message Semantics Response
- See the ITI 108 for Create and Update sections. The success or failure of the create/ update interaction is indicated by the http response code (e.g., 400, 200, etc.).
Expected Actions
- The consent is stored in the consent registry. Please see here for Capability statements for the Consent Registry actor
issue VHL - request
The issue VHL Request Event transaction is initiated by a Origin Country Health Wallet against the Origin Country HIE.
⟦not rendered: issue_shl_request.svg⟧ — the IG Publisher renders it from input/images-source/issue_shl_request.plantuml; no renderer was given to this build.
Trigger Events
- The issue VHL request transaction is initiated when a privacy configuration form has been recorded by a digital health wallet that includes disclosure and time limit settings.
Message Semantics
Message Semantics Request
- The message semantics for issue VHL Request shall include parameters that are required to construct a SMART Health Link Payload, specifically
- flag for Passcode
- expiration time
Message Semantics Response
- The issue VHL Request - Response shall include a serialized CWT via a QR Code Image as specified in the Expected Actions section.
Expected Actions
The following are the expected actions for the Origin Country HIE once it receives the privacy configuration:
- The Origin Country HIE creates a Folder for the pilgrim that includes the pilgrim’s
- IPS document in FHIR or PDF or both
- Signed IPS document as DSG jws JSON object for each document included in the folder
- The SHL specificationsshall be followed to create a SMART Health Link which is then wrapped in HCERT structure and shared as a CWT structure, by following the below steps:
- Establish a location that points to the document references within the folder for the pilgrim in the following syntax: “{host}/List?_id={folder_id}&_include=List:item” where ‘folder_id’ is a unique ID for the folder of health documents for the pilfrim. This shall be used as the Health Link URL within the VHL Payload
- Construct SHLink Payload
- Minified
- Base64urlencoded
- Prefixed with shlink:/
- Build HCERT containing SHL generated in previous step
- Build COSE Payload including the HCERT and sign with private key using Kid
- Build CWT with header payload and signature
- Serialize the CWT and using Base64
- Generate QR code
retrieve VHL folder docs - request
The Retrieve VHL folder docs Request Event transaction is initiated by the Host Country EMR against the Origin Country HIE.
⟦not rendered: retrieve_MHD_folder_request.svg⟧ — the IG Publisher renders it from input/images-source/retrieve_MHD_folder_request.plantuml; no renderer was given to this build.
Trigger Events
- The retrieve VHL folder docs request transaction is initiated when the host country EMR has extracted a VHL payload from a QR code that was scanned and the decrypted CWT decrypted yielded a HCERT payload that wrapped the VHL payload within it.
Message Semantics
Message Semantics Request
- The message semantics for retrieve VHL folder docs request shall be a POST request as specified by SMART Health Link Manifest Request, along with the passcode provided in the body of the request.
Message Semantics Response
- The message semantics shall follow a modified version of the ITI-67 Find Document References response message and for a successful queries return a FHIR bundle that includes all documentReference available in the VHL folder for the pilgrim. The modification of the ITI-67 transaction is that the Origin Country HIE shall respect the _include search parameter with value List:item as the URL generated in the VHL Payload is of of the format:
{host}/List?_id={folder_id}&_include=List:item”
Authentication of the Host Country EMR
The retrieve VHL folder docs request corresponds to the IHE Verifiable Health Link (VHL) Retrieve Manifest transaction [ITI-YY5]. VHL is cited here at version 1.0.0-comment, which is a public-comment ballot, not a final or trial-implementation publication; its text and section numbers may change. The sections cited below were read from the IHE/ITI.VHL source (commit 48201473), not from the published ballot pages.
VHL [ITI-YY5] names three options by which the VHL Receiver (here, the Host Country EMR) authenticates to the VHL Sharer (here, the Origin Country HIE):
- HTTP Message Signatures (RFC 9421), ITI-YY5 §2:3.YY5.4.1.3;
- OAuth with SSRAA Option, using the HL7 Security for Scalable Registration, Authentication, and Authorization (SSRAA) implementation guide, the HL7 FHIR profile of UDAP, ITI-YY5 §2:3.YY5.4.1.4;
- Verifiable Credential Option, ITI-YY5 §2:3.YY5.4.1.5.
This guide currently shows the Host Country EMR authenticating to the Origin Country HIE with mTLS node authentication ([ITI-19]) (see the unplanned care encounter sequence diagram). mTLS node authentication is not one of the three VHL authentication options. VHL still requires secure transport: ITI-YY5 §2:3.YY5.5.1 requires compliance with the IHE ATNA Profile for transport security, and VHL Volume 1 §1:XX.3 requires the VHL Receiver and the VHL Sharer to be grouped with an ATNA Secure Node or Secure Application. A TLS channel is therefore still expected, but on its own it does not satisfy any of the VHL authentication options.
It is recommended that the Host Country EMR authenticate with the OAuth with SSRAA Option. Like the current mTLS approach it is based on X.509 certificates: the Host Country EMR’s certificate chains to an anchor accepted in the ips-pilgrimage trust domain, so the Origin Country HIE identifies the receiver by that trust, not by looking up a separate agreement. Under that option, SSRAA discovery and registration are completed before an access token is requested (ITI-YY5 §2:3.YY5.4.1.4). How the Host Country EMR’s certificate or key is published in the ips-pilgrimage trust domain is not yet specified by this guide.
Expected Actions
- The recipient OCHIE checks if the VHL request is valid and responds with the documentReference as a FHIR bundle Json.
- The recipient OCHIE acts as a VHL Document Responder and must conform with the capability statement for VHL Document Responder
Deciding the request: the pilgrim’s consents are the policy
For the pilgrimage there is no separate data sharing agreement to look up. The pilgrim’s two HajjConsent resources are the policy, and each one binds the party it names:
- The origin-release consent (for example
CONSENT-MYS, or the fictionalCONSENT-XXKof this guide’s examples) lets the Origin Country HIE release the IPS to the recipient named inConsent.provision.actor(roleIRCP, information recipient), for the purpose inConsent.provision.purpose(TREAT), duringConsent.provision.period. The Origin Country HIE enforces this consent from its own Consent Registry (as recorded by the Record Consent transaction, [ITI-108]), not from the copy carried inside the IPS. The IPS copy is signed when the IPS is issued, so it cannot show a later withdrawal. - The host-use consent (
CONSENT-KSA, or the fictionalCONSENT-XXRof this guide’s examples) governs the Host Country Ministry of Health’s use of the IPS after it is received: for treatment during the pilgrimage and any follow-up care, as its consent text states.
Which consent a Consent is, and the consent text the pilgrim was shown, are carried in Consent.policyRule: a code from the IPS.HAJJ.CONSENT CodeSystem, with coding.version set to the CodeSystem version.
The Host Country EMR is identified by trust in the ips-pilgrimage trust domain (see the authentication note in the message semantics). The Origin Country HIE releases the documents only when the passcode is valid, the VHL has not expired, the origin-release consent is active in its registry, the verified receiver matches Consent.provision.actor, the purpose is treatment, and the request falls within Consent.provision.period. If any of these cannot be established, the request is not permitted.
Audit event
The Origin Country HIE records an audit event with Record Audit Event [ITI-20] for each request, whether documents are released or refused. VHL Volume 1 §1:XX.3 requires the VHL Sharer and the VHL Receiver to be grouped with an ATNA Secure Node or Secure Application, and ITI-YY5 §2:3.YY5.5.6 says both SHOULD log document access requests, the authentication method used, the receiver identity, the VHL folder ID and the authorization decision. In this guide the audit event recorded by the Origin Country HIE shall also cite:
- the governing policy: the pilgrim’s consents, each by its
Consent.policyRulecode and CodeSystem version (for exampleCONSENT-XXKandCONSENT-XXRin this guide’s examples, version 2.1.0); - the
idandmeta.versionIdof each Consent read from the Consent Registry for the decision; - the receiver, as identified by the VHL authentication option used;
- the purpose of use (
TREAT); - the documents released (the DocumentReferences returned), or the refusal.
This guide uses no separate data sharing agreement for the pilgrimage, so the consents themselves are the policy the audit event cites. The Host Country EMR, as an ATNA Secure Node or Secure Application, should also audit what it receives.
retrieve IPS - request
The Retrieve IPS Request Event transaction is initiated by the Host Country EMR against the Origin Country HIE.
⟦not rendered: retrieve_IPS_request.svg⟧ — the IG Publisher renders it from input/images-source/retrieve_IPS_request.plantuml; no renderer was given to this build.
Trigger Events
- The retrieve IPS request transaction is initiated when the host country EMR has extracted the bundle of documentReference from within the VHL folder and is now requesting for retrieving the IPS in JSON format.
Message Semantics
Message Semantics Request
- The message semantics for retrieve IPS Request shall be a GET request for the IPS json.
- The Host Country EMR shall act as a Document Consumer and follow ITI-68.
Message Semantics Response
- The message semantics for retrieve IPS Request-response shall send the IPS as a Json file.
Expected Actions
- The recipient OCHIE responds with the IPS Json.