The eMedication service exposes its own endpoints.
Implemented transactions are XDSITI-18, ITI-41, ITI-43, ITI-57 and CH:PHARM-1. MHD equivalents are given here for information but are not supported yet by the eMedication service.
XDS is the profile prescribed by the Swiss EPR ordinance, but MHD is simpler to implement, as it doesn’t require the complex XDS stack (SOAP, WSSE, MIME-Multipart, MTOM/XOP, ebRIM, and multi-depth XML), and relies on a lighter REST interface.
Even though the eMedication service doesn’t support it yet, it is possible to use the MHD profile though a third party component named mobile access gateway. This component is not affiliated with this service, but referenced here for information purpose.
Generic error codes
XDS error code
Details
XDSRegistryError
In case of business rule error, missing/invalid XUA (authentication errors), unexpected exception.
XDSUnknownPatientId
If the patient ID is unknown (i.e. the patient has not registered), if the subjects is missing rights to preform the action (authorization errors).
This page was updated 2023-10-04
\ No newline at end of file
+ Transactions - CARA's eMedication IG
The eMedication service exposes its own endpoints.
Implemented transactions are XDSITI-18, ITI-41, ITI-43, ITI-57 and CH:PHARM-1. MHD equivalents are given here for information but are not supported yet by the eMedication service.
XDS is the profile prescribed by the Swiss EPR ordinance, but MHD is simpler to implement, as it doesn’t require the complex XDS stack (SOAP, WSSE, MIME-Multipart, MTOM/XOP, ebRIM, and multi-depth XML), and relies on a lighter REST interface.
Even though the eMedication service doesn’t support it yet, it is possible to use the MHD profile though a third party component named mobile access gateway. This component is not affiliated with this service, but referenced here for information purpose.
Generic error codes
XDS error code
Details
XDSRegistryError
In case of business rule error, missing/invalid XUA (authentication errors), unexpected exception.
XDSUnknownPatientId
If the patient ID is unknown (i.e. the patient has not registered), if the subjects is missing rights to preform the action (authorization errors).
Other transactions
In addition to the XDS transactions implemented by the service, implementers may find it useful to check out the following profiles and transactions : * Cross Enterprise User Assertion (XUA) profile, and the Provide X-User Assertion (XUA ITI-40) transaction. * The XUA profile defines the format of assertions inserted in transactions, that contain information about the users and their roles. * The ITI-40 transaction is used to obtain the assertions from an assertion provider. * Healthcare Provider Directory (HPD) profile, and the Provider Information Query (HPD ITI-58) transaction. * The HPD profile defines the management of healthcare provider information in a directory structure. * The ITI-58 transaction can be used to lookup healthcare provider information from a healthcare provider directory. * Audit Trail and Node Authentication (ATNA) profile, and the record audit event (ATNA ITI-20) transaction. * The ATNA profile might be used by implementers to record audit events through the ITI-20 transaction.
This transaction has been implemented in order to respect the Swiss EPR regulation. However, it is very generic, and CH:PHARM-1 should be favored, as it offers emedication-specific query parameters.
Stored queries
Generic rules
Folders option not supported
The only [association]https://profiles.ihe.net/ITI/TF/Volume3/ch-4.1.html#4.1.2.2) supported is RPLC (replace)
Documents with deletionStatus=deletionRequested are ignored
Common query parameters
$MetadataLevel: If present, the attribute shall equal to 1, as per Nationale Anpassungen der Integrationsprofile nach Artikel 5 Absatz 1 Buchstabe b EPDV-EDI.
$XDSDocumentEntryPatientId, $patientId: The patient XAD-PID.
homeCommunityId: If present, it shall be the eMedication service OID.
FindDocuments
This stored query allows to search for APPC and CH-EMED-EPR documents. CH-EMED-EPR documents could also be searched through the PHARM-1 transaction (it’s a specialized ITI-18 transaction).
When processing requests, the following rules are applied:
This transaction has been implemented in order to respect the Swiss EPR regulation. However, it is very generic, and CH:PHARM-1 should be favored, as it offers emedication-specific query parameters.
The only [association]https://profiles.ihe.net/ITI/TF/Volume3/ch-4.1.html#4.1.2.2) supported is RPLC (replace)
Documents with deletionStatus=deletionRequested are ignored
Common query parameters
$MetadataLevel: If present, the attribute shall equal to 1, as per Nationale Anpassungen der Integrationsprofile nach Artikel 5 Absatz 1 Buchstabe b EPDV-EDI.
$XDSDocumentEntryPatientId, $patientId: The patient XAD-PID.
homeCommunityId: If present, it shall be the eMedication service OID.
FindDocuments
This stored query allows to search for APPC and CH-EMED-EPR documents. CH-EMED-EPR documents could also be searched through the PHARM-1 transaction (it’s a specialized ITI-18 transaction).
When processing requests, the following rules are applied:
Two types of documents might be published to the service : - CH-EMED-EPR documents (MTP, PRE, DIS and PADV only, PML and PMLC can only be retrieved from the service and not published to it). These documents contain the eMedication data. See also the corresponding page in this guide. - APPC (Advanced Patient Privacy Consent) documents. These documents are used to let patients define access rights to their data (who can publish and retrieve their data). See also the corresponding page in this guide.
SubmissionSet and relations
The eMedication service does not support folders and can only receive ONE document at a time. Hence, the metadata must always contain a SubmissionSet with a single DocumentEntry.
Possible values are defined in ch-epr-term IG. For APPC, only PAT (patient) and REP (Representative) are allowed. Must be aligned with document content author (see below).
author.authorSpecialty
O
Possible values are defined in ch-epr-term IG. Must be aligned with document content author (see below).
availabilityStatus
O
The value set in the metadata is always ignored, and replaced by approved.
Must be globally unique and be a UUID. Must match the document id in the case of CH-EMED-EPR documents.
URI
O
-
version
O
If present shall be empty, the value is ignored and set by the document registry.
Publishing a CH-EMED-EPR document
This section details the specific rules to follow when publishing CH-EMED-EPR documents.
Only MTP, PRE, DIS and PADV docs can be published. PML and PMLC can only be retrieved from the service.
Referencing external documents
When publishing CH-EMED-EPR documents, all references (from the key elements) shall be known to the eMedication service. All non-key elements are ignored by the eMedication service.
This implies that the metadata cannot contain Reference ids. This option is not supported, and submission of a reference to an existing document is forbidden.
Creation times
Creation time of a document must be equal or greater than the creation time of the last document of the treatment chain, ie. the last published document targeting the treatment (either the original MTP if no other document, or the last document published referencing this treatment).
Creation time of the document has to be in the past.
All references to other documents or items have to refer to existing approved non deleted documents.
Each PRE item should refer to an MTP item (CHEMEDEPRMedicationRequest.treatmentplan) that must:
Exist (has already been published, and never deleted)
Be approved, ie. DocumentEntry.availabilityStatus = approved,
Preferably be valid, i.e. the submission date should be within the MTP dosage’sboundsPeriod (CHEMEDEPRDosage.repeat.bounds).
If the boundsPeriod is not defined, the entry is considered to be always active.
If only a startDate is specified, the MTP is considered to be active if the current date is after that date.
Active, ie. CHEMEDEPRDocumentMedicationTreatmentPlan.CHEMEDEPRMedicationStatement.status = active
For the same patient.
Code of medication should match the code of medication of the MTP referenced by the PRE (CHEMEDEPRMedicationRequest.treatmentplan). This rule is not enforced and might be extended in the future.
If lot number (CHEMEDEPRMedication.batch) is specified in referenced MTP, the one in the PRE (CHEMEDEPRMedicationRequest.medication[x]:medicationReference.batch) should match it. This rule is not enforced and might be extended in the future.
PADV
PADV against a provisional PRE
A “provisional PRE” is a prescription for which the CHEMEDEPRMedicationRequest.status is SUBMITTED or PROVISIONAL and for which a PADVOK has not been completed yet.
Medication cannot be changed. This rule is not enforced and might be extended in the future.
Dosage instructions cannot be changed. This rule is not enforced and might be extended in the future.
Substitution cannot be disallowed if the existing dispense includes one. This rule is not enforced and might be extended in the future.
Observation code REFUSE cannot be issued.
PADV CANCEL
Sets status to CANCELED.
Not allowed against DIS or other PADV documents.
Against MTP
Also set related prescriptions’ status to CANCELED if their status was not already REFUSED or CANCELED.
Treatment plan status must be ACTIVE or SUSPENDED.
Against PRE
Not allowed for prescriptions whose status is already CANCELED or REFUSED.
Not allowed to target anything else than MTP or PRE
PADV OK
Sets targeted MTP or PRE status to ACTIVE.
Against MTP: only allowed for treatment plans with status ACTIVE or SUSPENDED.
Against PRE: only allowed for prescriptions with status SUBMITTED or PROVISIONAL.
PADV OK cannot target anything else than MTP or PRE.
PADV CHANGE
Changes the treatment plan or prescription.
Can only target MTP or PRE.
Against MTP
The treatment status must be ACTIVE or SUSPENDED.
The treatment must not have been prescribed.
Additionally, the treatment’s status is set to ACTIVE as a result of the aggregation.
Against PRE
The prescription’s status must not be CANCELED or REFUSED.
If the prescription’s status is SUBMITTED, the aggregation sets it to ACTIVE as a result.
PADV REFUSE
Sets status to REFUSED.
Against MTP
Sets also related prescriptions’ status to REFUSED if the status was not already REFUSED or CANCELED.
Treatment’s status must be ACTIVE or SUSPENDED.
Against PRE
The prescription’s status must not be REFUSED, CANCELED or PROVISIONAL.
Cannot target anything else than MTP or PRE.
PADV SUSPEND
Sets status to SUSPENDED
Only allowed to target MTP entries
The treatment status must be ACTIVE
PADV COMMENT:
Can target MTP, PRE and DIS entries only.
DIS
If lot number (batch) is specified in referenced MTP(treatmentPlan) or PRE (prescription), then it should match the one in the DIS if substitution is not allowed. This rule is not enforced and might be extended in the future.
DIS against MTP or PRE + MTP:
Medication should not be different if substitution is not allowed by PRE. This rule might be extended in the future.
Dispense should not occur after the end of validity of the PRE document. This rule might be extended in the future.
Dispense should not occur after the end of the treatment if specified in the prescription item. This rule might be extended in the future.
If referenced PRE is not provisional, it should be dispensable (that is have status either PROVISIONAL or ACTIVE). This rule is not enforced and might be extended in the future.
List of active ingredients should be the same than the one in the referenced PRE (prescription). This rule is not enforced and might be extended in the future.
If the treatment has been prescribed (at least one PRE document has been successfully submitted for it), then any DIS document targeting this treatment must reference one of its prescriptions as well.
736378000Medication management plan (record artifact)
The class and type codes are from the SNOMED CT system: 2.16.840.1.113883.6.96. The system for the formatCode is 2.16.756.5.30.1.127.3.10.10
Replacing a CH-EMED-EPR document
The following rules must be observed when replacing a document :
Patients and their representatives can only replace a document published by the same patient.
representatives are not supported by the service yet.
Healthcare professionals (HCP) can only replace a document published by himself or by another HCP of same community of affiliation.
Current implementation: an HCP can replace a document published by any other HCP. Further rules and possible implementations are under discussion.
Document administrator may only replace a document published by an HCP of the same community of affiliation.
Not implemented in PMP, to be discussed, for now a document admin can replace any document.
Replacing and replaced documents have to be of the same type (e.g. both MTP documents).
Replacing and replaced documents have to refer to the same patient.
Only documents at the end of a treatment chain can be replaced.
Replaced document must exist in the repository.
A replacement document must can be linked only to elements of the same medication chain. In case a PRE document is replaced, it may be linked only to elements of the medication chain of the referenced MTP.
Replaced document must be approved (although this is always the case after an initial ITI-41 transaction, documents might become deprecated after another ITI-41 transaction with a replacement association).
Replaced document must not have deletionStatus = deletionRequested (this is relevant since although it is not the case at the moment with the current implementation, there might be files in the repository flagged for deletion but not deleted yet).
Publishing a PMP-APPC document
This section details the rules applicable to metadata when publishing APPC documents.
Rules for APPC:
Only Patients and their representatives or policy administrators can publish a new APPC document.
representatives are not supported by the service yet.
Only Patients and their representatives can replace their own APPC documents (if it exists).
representatives are not supported by the service yet.
Policy administrators of the reference community of the patient can replace any existing APPC document.
No APPC for the specified patient exists in the system (unless the published document is a replacement), otherwise the document is refused.
As for CH-EMED-EPR, APPC documents to be replaced must:
Be approved (as before, this is always the case for documents in the PMP repository when they are published, but their status might change to deprecated after a replacement).
Two types of documents might be published to the service : - CH-EMED-EPR documents (MTP, PRE, DIS and PADV only, PML and PMLC can only be retrieved from the service and not published to it). These documents contain the eMedication data. See also the corresponding page in this guide. - APPC (Advanced Patient Privacy Consent) documents. These documents are used to let patients define access rights to their data (who can publish and retrieve their data). See also the corresponding page in this guide.
SubmissionSet and relations
The eMedication service does not support folders and can only receive ONE document at a time. Hence, the metadata must always contain a SubmissionSet with a single DocumentEntry.
Possible values are defined in ch-epr-term IG. For APPC, only PAT (patient) and REP (Representative) are allowed. Must be aligned with document content author (see below).
author.authorSpecialty
O
Possible values are defined in ch-epr-term IG. Must be aligned with document content author (see below).
availabilityStatus
O
The value set in the metadata is always ignored, and replaced by approved.
Must be globally unique and be a UUID. Must match the document id in the case of CH-EMED-EPR documents.
URI
O
-
version
O
If present shall be empty, the value is ignored and set by the document registry.
Publishing a CH-EMED-EPR document
This section details the specific rules to follow when publishing CH-EMED-EPR documents.
Only MTP, PRE, DIS and PADV docs can be published. PML and PMLC can only be retrieved from the service.
Referencing external documents
When publishing CH-EMED-EPR documents, all references (from the key elements) shall be known to the eMedication service. All non-key elements are ignored by the eMedication service.
This implies that the metadata cannot contain Reference ids. This option is not supported, and submission of a reference to an existing document is forbidden.
Creation times
Creation time of a document must be equal or greater than the creation time of the last document of the treatment chain, ie. the last published document targeting the treatment (either the original MTP if no other document, or the last document published referencing this treatment).
Creation time of the document has to be in the past.
All references to other documents or items have to refer to existing approved non deleted documents.
Each PRE item should refer to an MTP item (CHEMEDEPRMedicationRequest.treatmentplan) that must:
Exist (has already been published, and never deleted)
Be approved, ie. DocumentEntry.availabilityStatus = approved,
Preferably be valid, i.e. the submission date should be within the MTP dosage’sboundsPeriod (CHEMEDEPRDosage.repeat.bounds).
If the boundsPeriod is not defined, the entry is considered to be always active.
If only a startDate is specified, the MTP is considered to be active if the current date is after that date.
Active, ie. CHEMEDEPRDocumentMedicationTreatmentPlan.CHEMEDEPRMedicationStatement.status = active
For the same patient.
Code of medication should match the code of medication of the MTP referenced by the PRE (CHEMEDEPRMedicationRequest.treatmentplan). This rule is not enforced and might be extended in the future.
If lot number (CHEMEDEPRMedication.batch) is specified in referenced MTP, the one in the PRE (CHEMEDEPRMedicationRequest.medication[x]:medicationReference.batch) should match it. This rule is not enforced and might be extended in the future.
PADV
PADV against a provisional PRE
A “provisional PRE” is a prescription for which the CHEMEDEPRMedicationRequest.status is SUBMITTED or PROVISIONAL and for which a PADVOK has not been completed yet.
Medication cannot be changed. This rule is not enforced and might be extended in the future.
Dosage instructions cannot be changed. This rule is not enforced and might be extended in the future.
Substitution cannot be disallowed if the existing dispense includes one. This rule is not enforced and might be extended in the future.
Observation code REFUSE cannot be issued.
PADV CANCEL
Sets status to CANCELED.
Not allowed against DIS or other PADV documents.
Against MTP
Also set related prescriptions’ status to CANCELED if their status was not already REFUSED or CANCELED.
Treatment plan status must be ACTIVE or SUSPENDED.
Against PRE
Not allowed for prescriptions whose status is already CANCELED or REFUSED.
Not allowed to target anything else than MTP or PRE
PADV OK
Sets targeted MTP or PRE status to ACTIVE.
Against MTP: only allowed for treatment plans with status ACTIVE or SUSPENDED.
Against PRE: only allowed for prescriptions with status SUBMITTED or PROVISIONAL.
PADV OK cannot target anything else than MTP or PRE.
PADV CHANGE
Changes the treatment plan or prescription.
Can only target MTP or PRE.
Against MTP
The treatment status must be ACTIVE or SUSPENDED.
The treatment must not have been prescribed.
Additionally, the treatment’s status is set to ACTIVE as a result of the aggregation.
Against PRE
The prescription’s status must not be CANCELED or REFUSED.
If the prescription’s status is SUBMITTED, the aggregation sets it to ACTIVE as a result.
PADV REFUSE
Sets status to REFUSED.
Against MTP
Sets also related prescriptions’ status to REFUSED if the status was not already REFUSED or CANCELED.
Treatment’s status must be ACTIVE or SUSPENDED.
Against PRE
The prescription’s status must not be REFUSED, CANCELED or PROVISIONAL.
Cannot target anything else than MTP or PRE.
PADV SUSPEND
Sets status to SUSPENDED
Only allowed to target MTP entries
The treatment status must be ACTIVE
PADV COMMENT:
Can target MTP, PRE and DIS entries only.
DIS
If lot number (batch) is specified in referenced MTP(treatmentPlan) or PRE (prescription), then it should match the one in the DIS if substitution is not allowed. This rule is not enforced and might be extended in the future.
DIS against MTP or PRE + MTP:
Medication should not be different if substitution is not allowed by PRE. This rule might be extended in the future.
Dispense should not occur after the end of validity of the PRE document. This rule might be extended in the future.
Dispense should not occur after the end of the treatment if specified in the prescription item. This rule might be extended in the future.
If referenced PRE is not provisional, it should be dispensable (that is have status either PROVISIONAL or ACTIVE). This rule is not enforced and might be extended in the future.
List of active ingredients should be the same than the one in the referenced PRE (prescription). This rule is not enforced and might be extended in the future.
If the treatment has been prescribed (at least one PRE document has been successfully submitted for it), then any DIS document targeting this treatment must reference one of its prescriptions as well.
736378000Medication management plan (record artifact)
The class and type codes are from the SNOMED CT system: 2.16.840.1.113883.6.96. The system for the formatCode is 2.16.756.5.30.1.127.3.10.10
Replacing a CH-EMED-EPR document
The following rules must be observed when replacing a document :
Patients and their representatives can only replace a document published by the same patient.
representatives are not supported by the service yet.
Healthcare professionals (HCP) can only replace a document published by himself or by another HCP of same community of affiliation.
Current implementation: an HCP can replace a document published by any other HCP. Further rules and possible implementations are under discussion.
Document administrator may only replace a document published by an HCP of the same community of affiliation.
Not implemented in PMP, to be discussed, for now a document admin can replace any document.
Replacing and replaced documents have to be of the same type (e.g. both MTP documents).
Replacing and replaced documents have to refer to the same patient.
Only documents at the end of a treatment chain can be replaced.
Replaced document must exist in the repository.
A replacement document must can be linked only to elements of the same medication chain. In case a PRE document is replaced, it may be linked only to elements of the medication chain of the referenced MTP.
Replaced document must be approved (although this is always the case after an initial ITI-41 transaction, documents might become deprecated after another ITI-41 transaction with a replacement association).
Replaced document must not have deletionStatus = deletionRequested (this is relevant since although it is not the case at the moment with the current implementation, there might be files in the repository flagged for deletion but not deleted yet).
Publishing a PMP-APPC document
This section details the rules applicable to metadata when publishing APPC documents.
Rules for APPC:
Only Patients and their representatives or policy administrators can publish a new APPC document.
representatives are not supported by the service yet.
Only Patients and their representatives can replace their own APPC documents (if it exists).
representatives are not supported by the service yet.
Policy administrators of the reference community of the patient can replace any existing APPC document.
No APPC for the specified patient exists in the system (unless the published document is a replacement), otherwise the document is refused.
As for CH-EMED-EPR, APPC documents to be replaced must:
Be approved (as before, this is always the case for documents in the PMP repository when they are published, but their status might change to deprecated after a replacement).
This transaction, implemented as per the specifications. All documents are retrievable with an ITI-43 transaction (with the proper access rights : only patients, representatives and policy administrators can retrieve APPC (Advanced Patient Privacy Consent) documents).
The document associated with the uniqueId is not available. This could be because the document is not available, the requestor is not authorized to access that document or the document is no longer available.
XDSMissingHomeCommunityId
A value for the homeCommunityId is required and has not been specified.
XDSRegistryBusy XDSRepositoryBusy
Too much activity. (Not used now)
XDSRegistryError XDSRepositoryError
Internal Error. The error codes XDSRegistryError or XDSRepositoryError shall be returned if and only if a more detailed code is not available.
This error signals that a single request would have returned content for multiple Patient Ids. TODO: that would leak that the ID exists and belongs to another patient. For privacy reasons, would it be treated like a non-existing document? If yes, this error wouldn’t be possible.
XDSUnavailableCommunity
A community that was queried was not available.
XDSUnknownCommunity
A value for the homeCommunityId is not recognized.
XDSUnknownRepositoryId
The repositoryUniqueId value could not be resolved to a valid document repository or the value does not match the repositoryUniqueId.
This page was updated 2023-10-04
\ No newline at end of file
+ XDS: retrieve documents (ITI-43) - CARA's eMedication IG
This transaction, implemented as per the specifications. All documents are retrievable with an ITI-43 transaction (with the proper access rights : only patients, representatives and policy administrators can retrieve APPC (Advanced Patient Privacy Consent) documents).
The document associated with the uniqueId is not available. This could be because the document is not available, the requestor is not authorized to access that document or the document is no longer available.
XDSMissingHomeCommunityId
A value for the homeCommunityId is required and has not been specified.
XDSRegistryBusy XDSRepositoryBusy
Too much activity. (Not used now)
XDSRegistryError XDSRepositoryError
Internal Error. The error codes XDSRegistryError or XDSRepositoryError shall be returned if and only if a more detailed code is not available.
This error signals that a single request would have returned content for multiple Patient Ids. TODO: that would leak that the ID exists and belongs to another patient. For privacy reasons, would it be treated like a non-existing document? If yes, this error wouldn’t be possible.
XDSUnavailableCommunity
A community that was queried was not available.
XDSUnknownCommunity
A value for the homeCommunityId is not recognized.
XDSUnknownRepositoryId
The repositoryUniqueId value could not be resolved to a valid document repository or the value does not match the repositoryUniqueId.