Merge pull request #24 from qligier/ql_mkdocs

Use mkdocs to publish documentation
ehealthsuisse · Jul 24, 2024 · fdfdee1 · fdfdee1
2 parents 316ba25 + 5bbdee1
commit fdfdee1
Show file tree

Hide file tree

Showing 34 changed files with 1,764 additions and 2,650 deletions.
diff --git a/.github/workflows/publish_doc.yml b/.github/workflows/publish_doc.yml
@@ -0,0 +1,28 @@
+name: Publish documentation
+on:
+  workflow_dispatch: # On manual trigger
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Publish documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+
+      - name: Install Python 3
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+          cache-dependency-path: 'requirements.txt'
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Build static documentation and publish
+        run: mkdocs gh-deploy --force
+        # https://www.mkdocs.org/user-guide/deploying-your-docs/#github-pages
diff --git a/Auth_samples/04_AuthnRequest.xml b/Auth_samples/04_AuthnRequest.xml
@@ -1,31 +1,31 @@
-1 <AuthnRequest
-2  xmlns="urn:oasis:names:tc:SAML:2.0:protocol"
-3  AssertionConsumerServiceURL="https://epdtest.mycompany.local:8549/ACS"
-4  IssueInstant="2020-09-24T13:19:25.208+02:00"
-5  Destination="https://fed.idp.ch:443/saml/3.0/idp/"
-6  ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
-7  ID="SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0"
-8  Version="2.0">
-9  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://epdtest.mycompany.local</Issuer>
-10  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
-11   <SignedInfo>
-12    <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
-13    <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
-14    <Reference URI="#SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0">
-15     <Transforms>
-16      <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
-17      <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
-18     </Transforms>
-19     <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
-20     <DigestValue>TdN8cZ5mvY7pOsrpOK0h+YlnvlhOOHYecaBN59yH4w0=</DigestValue>
-21    </Reference>
-22   </SignedInfo>
-23   <SignatureValue><!-- omitted for brevity --></SignatureValue>
-24   <KeyInfo>
-25    <X509Data>
-26     <X509Certificate><!-- omitted for brevity --></X509Certificate>
-27    </X509Data>
-28   </KeyInfo>
-29  </Signature>
-30  <NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" AllowCreate="true"/>
-31 </AuthnRequest>
+<AuthnRequest
+ xmlns="urn:oasis:names:tc:SAML:2.0:protocol"
+ AssertionConsumerServiceURL="https://epdtest.mycompany.local:8549/ACS"
+ IssueInstant="2020-09-24T13:19:25.208+02:00"
+ Destination="https://fed.idp.ch:443/saml/3.0/idp/"
+ ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
+ ID="SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0"
+ Version="2.0">
+ <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://epdtest.mycompany.local</Issuer>
+ <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
+  <SignedInfo>
+   <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+   <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
+   <Reference URI="#SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0">
+    <Transforms>
+     <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+     <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+    </Transforms>
+    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
+    <DigestValue>TdN8cZ5mvY7pOsrpOK0h+YlnvlhOOHYecaBN59yH4w0=</DigestValue>
+   </Reference>
+  </SignedInfo>
+  <SignatureValue><!-- omitted for brevity --></SignatureValue>
+  <KeyInfo>
+   <X509Data>
+    <X509Certificate><!-- omitted for brevity --></X509Certificate>
+   </X509Data>
+  </KeyInfo>
+ </Signature>
+ <NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" AllowCreate="true"/>
+</AuthnRequest>
diff --git a/Auth_samples/09_ArtifactResolve_raw.xml → Auth_samples/08_ArtifactResolve_raw.xml b/Auth_samples/09_ArtifactResolve_raw.xml → Auth_samples/08_ArtifactResolve_raw.xml
diff --git a/Auth_samples/09_ArtifactResponse.xml b/Auth_samples/09_ArtifactResponse.xml
@@ -23,9 +23,7 @@
             <ds:DigestValue>1RZPbh508clAQoKhxnQZEenNFyg=</ds:DigestValue>
           </ds:Reference>
         </ds:SignedInfo>
-        <ds:SignatureValue>
-          <!-- omitted for brevity -->
-        </ds:SignatureValue>
+        <ds:SignatureValue><!-- omitted for brevity --></ds:SignatureValue>
         <ds:KeyInfo>
           <ds:X509Data>
             <ds:X509SKI>gYMVdgdR5LG/983GRTJIch0a+zU=</ds:X509SKI>
@@ -63,14 +61,10 @@
                 <ds:DigestValue>P/I9Ym+p/Zzs0ANXHmAjqZcuBp2FJ75j6oCM6Gd0bVg=</ds:DigestValue>
               </ds:Reference>
             </ds:SignedInfo>
-            <ds:SignatureValue>
-              <!-- omitted for brevity -->
-            </ds:SignatureValue>
+            <ds:SignatureValue><!-- omitted for brevity --></ds:SignatureValue>
             <ds:KeyInfo>
               <ds:X509Data>
-                <ds:X509Certificate>
-                  <!-- omitted for brevity -->
-                </ds:X509Certificate>
+                <ds:X509Certificate><!-- omitted for brevity --></ds:X509Certificate>
               </ds:X509Data>
             </ds:KeyInfo>
           </ds:Signature>

diff --git a/Auth_samples/Renew_request.xml b/Auth_samples/Renew_request.xml
@@ -1,65 +1,65 @@
-1 <Envelope>
-2  <Header>
-3   <Security mustUnderstand="1">
-8    <Timestamp Id="TS-15277e04-85e0-4b9c-9692-76c3e7be17bc">
-9     <Created>2019-03-26T15:13:15.144Z</Created>
-10     <Expires>2019-03-26T15:18:15.144Z</Expires>
-11    </Timestamp>
-12    <BinarySecurityToken
-13     EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
-14     ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
-15     Id="X509-6dfe58da-6804-48ba-ad52-e871c63455df">
-18     MIIDPTCCAiWgAwIBAgIEPVbC1zANBgkqhkiG9w0BAQUFADBPMQswCQYDVQQGEqSqEb/3VB3ITUav3DIo2o2mRCKyfHV471QUNt4qNFmEwRxpsoGst/UYoTqW8/buv4A=
-19    </BinarySecurityToken>
-20    <Signature Id="SIG-98f468bf-4022-4e31-9886-6f30f1c676bc">
-21     <SignedInfo>
-22      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
-23       <InclusiveNamespaces PrefixList="soap"/>
-24      </CanonicalizationMethod>
-25      <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256" />
-26      <Reference URI="#TS-15277e04-85e0-4b9c-9692-76c3e7be17bc" >
-27       <Transforms>
-28        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" >
-29         <InclusiveNamespaces PrefixList="soap wsse"/>
-30        </Transform>
-31       </Transforms>
-32       <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
-33       <DigestValue >LCxW9EORpApnpju2Q17b0MB1LGt8CMCuvoOqCtlhFx0=</DigestValue>
-34      </Reference>
-35      <Reference URI="#_33c9f0c5-c7d2-4d53-ad2f-944320637754" >
-36       <Transforms>
-37        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
-38       </Transforms>
-39       <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
-40       <DigestValue >TwKUz3SxOx1NaFVvy55AbbpWXbUJmfn+mreDpkNa/pg=</ds:DigestValue>
-41      </Reference>
-42     </SignedInfo>
-43     <SignatureValue>
-44      <!-- signature value omitted -->
-45     </SignatureValue>
-46     <KeyInfo Id="KI-2c6438fa-738a-4ffb-aa52-379bd9380b1a" >
-47      <SecurityTokenReference Id="STR-76ccd654-581d-446e-a00b-8ed529bcc4ab">
-51       <X509Data>
-52        <X509IssuerSerial>
-53         <X509IssuerName >CN=lk,OU=lk,O=lk,L=lsn,ST=vd,C=ch</X509IssuerName>
-54         <X509SerialNumber >1029096151</X509SerialNumber>
-55        </X509IssuerSerial>
-56       </X509Data>
-57      </SecurityTokenReference>
-58     </KeyInfo>
-59    </Signature>
-60   </Security>
-61  </Header>
-62  <Body Id="_33c9f0c5-c7d2-4d53-ad2f-944320637754">
-63   <RequestSecurityToken>
-64    <RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Renew</RequestType>
-65    <TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</TokenType>
-66    <RenewTarget>
-67     <Assertion ID="ID_6ff2590e-8df8-4f04-9ae0-cfd16d816c49" IssueInstant="2019-03-26T15:12:13.246Z" Version="2.0">
-68      <!-- assertion omitted -->
-69     </Assertion>
-70    </RenewTarget>
-71    <Renewing/>
-72   </RequestSecurityToken>
-73  </Body>
-74 </Envelope>
+<Envelope>
+ <Header>
+  <Security mustUnderstand="1">
+   <Timestamp Id="TS-15277e04-85e0-4b9c-9692-76c3e7be17bc">
+    <Created>2019-03-26T15:13:15.144Z</Created>
+    <Expires>2019-03-26T15:18:15.144Z</Expires>
+   </Timestamp>
+   <BinarySecurityToken
+    EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
+    ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
+    Id="X509-6dfe58da-6804-48ba-ad52-e871c63455df">
+    MIIDPTCCAiWgAwIBAgIEPVbC1zANBgkqhkiG9w0BAQUFADBPMQswCQYDVQQGEqSqEb/3VB3ITUav3DIo2o2mRCKyfHV471QUNt4qNFmEwRxpsoGst/UYoTqW8/buv4A=
+   </BinarySecurityToken>
+   <Signature Id="SIG-98f468bf-4022-4e31-9886-6f30f1c676bc">
+    <SignedInfo>
+     <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
+      <InclusiveNamespaces PrefixList="soap"/>
+     </CanonicalizationMethod>
+     <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256" />
+     <Reference URI="#TS-15277e04-85e0-4b9c-9692-76c3e7be17bc" >
+      <Transforms>
+       <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" >
+        <InclusiveNamespaces PrefixList="soap wsse"/>
+       </Transform>
+      </Transforms>
+      <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
+      <DigestValue >LCxW9EORpApnpju2Q17b0MB1LGt8CMCuvoOqCtlhFx0=</DigestValue>
+     </Reference>
+     <Reference URI="#_33c9f0c5-c7d2-4d53-ad2f-944320637754" >
+      <Transforms>
+       <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
+      </Transforms>
+      <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
+      <DigestValue >TwKUz3SxOx1NaFVvy55AbbpWXbUJmfn+mreDpkNa/pg=</ds:DigestValue>
+     </Reference>
+    </SignedInfo>
+    <SignatureValue>
+     <!-- signature value omitted -->
+    </SignatureValue>
+    <KeyInfo Id="KI-2c6438fa-738a-4ffb-aa52-379bd9380b1a" >
+     <SecurityTokenReference Id="STR-76ccd654-581d-446e-a00b-8ed529bcc4ab">
+      <X509Data>
+       <X509IssuerSerial>
+        <X509IssuerName >CN=lk,OU=lk,O=lk,L=lsn,ST=vd,C=ch</X509IssuerName>
+        <X509SerialNumber >1029096151</X509SerialNumber>
+       </X509IssuerSerial>
+      </X509Data>
+     </SecurityTokenReference>
+    </KeyInfo>
+   </Signature>
+  </Security>
+ </Header>
+ <Body Id="_33c9f0c5-c7d2-4d53-ad2f-944320637754">
+  <RequestSecurityToken>
+   <RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Renew</RequestType>
+   <TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</TokenType>
+   <RenewTarget>
+    <Assertion ID="ID_6ff2590e-8df8-4f04-9ae0-cfd16d816c49" IssueInstant="2019-03-26T15:12:13.246Z" Version="2.0">
+     <!-- assertion omitted -->
+    </Assertion>
+   </RenewTarget>
+   <Renewing/>
+  </RequestSecurityToken>
+ </Body>
+</Envelope>
diff --git a/README.md b/README.md
@@ -1,66 +1,22 @@
-# Swiss EPR Transactions
+# EPD by example
 
-Primary systems need to implement only a handful of transactions to connect to the Swiss Electronic Patient Record (EPR), i.e., for Patient and Document Mangement as well as for Authentication and Authorisation.
+This repository contains the project EPD by example.
+The documentation is published on [https://ehealthsuisse.github.io/EPD-by-example](https://ehealthsuisse.github.io/EPD-by-example),
+the repository contains the markdown sources and examples of transactions.
 
-The specification of the transactions are published in the ordinances of the law of the electronic patient dossier. There all details and options are found in the ordinances and the references therein.
+## Automatic publication
 
-The pages explain the transactions by using samples recorded or adapted from transactions performed during the annual Swiss projectathon (September 2020). The pages shall be used as additional material to support developer and architects of primary systems to integrate to the Swiss EPR or plan to do so in the near future.
+The workflow described in `.github/workflows/publish_doc.yml` ensures that the documentation is build and published 
+in GitHub Pages each time a commit is pushed to the `main` branch.
 
-Primary systems which wan't to test their implementation of the EPR transactions may either use the test systems provided by the communities or public available test systems. Currently there are two public test systems available:
+## Manual 
 
-The Gazelle test environment provides the full set of tests available for EPR transactions. Tests may be used to verify the EPR compliance of each isolated transation.
+The documentation can be locally built and previewed with the following commands:
 
-The EPR Playground is a public available installation of the EPR core infrastructure provided the BfH Bern. To reduce the gap for primary systems and ease the usage, the EPR playground dropped some of the security functions present in the Swiss EPR (e.g., mutual authentication, authorization). Up to this limitation the EPR playground supports the requirements of the Swiss EPR and vendors of primary systems may use the EPR playground to verify the transactions but also full use cases from patient registration to document exchange scenarios.    
-
-Please see section below for details on the available public test systems.
-
-## Patient Management
-
-**[PDQ V3](../main/files/PDQ.md)** - Search for patient data using demographic data as search criteria
-
-**[PIX V3 Feed](../main/files/PIXFeed.md)** - Register patient data
-
-**[PIX V3 Query](../main/files/PIXQuery.md)** - Query the master patient ID and EPR-SPID for patients
-
-## Document Management
-
-**[Registry Stored Query](../main/files/RegistryStoredQuery.md)** - Get and display document metadata
-
-**[Retrieve Document Set](../main/files/RetrieveDocumentSet.md)** - Get and display documents
-
-**[Provide and Register Document Set](../main/files/ProvideAndRegister.md)** - Store documents in the EPR
-
-## Authentication
-
-**[Authenticate User](../main/files/AuthenticateUser.md)** - Authenticate a user
-
-**[IdP Renew](../main/files/IdPRenew.md)** - Renew a IdP assertion
-
-**[SSO Logout](../main/files/SSOLogout.md)** - Logout of authenticated user  
-
-## Authorization
-
-**[Get X-User Assertion](../main/files/GetXAssertion.md)** - Retrieve SAML 2.0 Assertions for authorization
-
-**[Provide X-User Assertion](../main/files/ProvideXAssertion.md)** - Use SAML 2.0 Assertion in transactions to authorize access
-
-## Public Test Systems
-
-**[EPR Playground](../main/files/playground.md)** - Public available test system to test transaction messages and complex use cases.
-
-**[EPR Reference Environment](../main/files/gazelle.md)** - Public available test system to test isolated transaction for EPR compliance.
-
-# Swiss EPR Exchange Formats
-
-Exchange formats permit the simple exchange of data between different health professionals' information technology systems without the need for any special agreement. The specifications of the exchange formats define the technical, syntactic and semantic standards required for the consistent exchange of information. The objective is to standardize data exchange in the healthcare sector, especially with regard to the Swiss Electronic Patient Record (EPR).
-
-## eMedication
-
-**[Medication Card document](../main/files/MedicationCardDocument.md)** - Complete overview about the current Medication from the patient.
-
-## eVaccination
-
-**[Immunization Administration Document](../main/files/ImmunizationAdministrationDocument.md)** - Contains information on applied immunizations.
-
-## FHIR Questionnaire
-**[How to build a FHIR-Questionnaire](../main/files/Questionnaire.md)** - Contains information on how a FHIR Questionnaire can be built and displayed for an user to fill out.
+```bash
+pip install -r requirements.txt
+# To preview the documentation on http://127.0.0.1:8000/EPD-by-example/:
+mkdocs serve
+# To build the documentation:
+mkdocs build
+```