Issue/212 add troubleshooting page for reference resolution errors when sending task resources

docs/src/.vuepress/theme.ts

@@ -64,7 +64,7 @@ export default hopeTheme({
             text: `Current Version - ${latestVersion}`,
             link: "get-started",
             icon: "launch"
-          }, "old-versions"],
+          }, "old-versions", "troubleshooting/README.md"],
         },
       ],
     },

docs/src/operations/troubleshooting/README.md

@@ -0,0 +1,12 @@
+---
+title: Troubleshooting
+icon: tool
+---
+## Overview
+- [Common HTTP Status Codes](common-http-status-codes)
+- [Connection Refused](connection-refused)
+- [Connection Timeout](connection-timeout)
+- [FHIR Reference Resolution](fhir-reference-resolution)
+- [Read Timeout](read-timeout)
+- [SSL](ssl)
+- [Unknown Host](unknown-host)

docs/src/operations/troubleshooting/common-http-status-codes.md

@@ -1,31 +1,31 @@
 ---
 title: Common HTTP Status Codes
-icon: support
+icon: http
 ---
 
-# 401 Unauthorized
+## 401 Unauthorized
 This HTTP status code may be a result of an allow list mismatch. Either the requesting party is using a client certificate that was not updated after making changes to the allow list or the receiving party is using an outdated version of the allow list.
 
-# 403 Forbidden
+## 403 Forbidden
 This HTTP status code may be encountered in different ways in the context of the DSF:
 - Process plugin is not installed at FHIR server where the Task resource was posted
 - Client certificate of the FHIR server where the Task resource was posted is invalid e.g. because it is expired
 
-# 407 Proxy Authentication Required
+## 407 Proxy Authentication Required
 A proxy server between the requester and receiver denied the request because of invalid authentication credentials for the proxy.
 
-# 413 Content Too Large
+## 413 Content Too Large
 This HTTP status code is a result of trying to upload a resource that is too large for the server to handle. This might be due to a misconfiguration of the DSF FHIR server's reverse proxy not allowing this much data to be uploaded.
 
-# 500 Internal Server Error
+## 500 Internal Server Error
 This HTTP status may be a result of a connection timeout if a forward proxy is used or when using ping pong 2.x in DSF 1.x with a download resource size of >400MB.
 
-# 502 Bad Gateway
+## 502 Bad Gateway
 This HTTP status code is usually the response of a proxy because the upstream server sent an invalid response.
 
-# 503 Service Unavailable
+## 503 Service Unavailable
 This HTTP status code might be the result of the target server being temporarily unavailable e.g. because of maintenance.
 Some (forward) proxies might also respond with this status when they cannot establish a connection to the target server.
 
-# 504 Gateway Timeout
+## 504 Gateway Timeout
 This HTTP status code is usually the response of a proxy because the upstream server did not send a response in time.

docs/src/operations/troubleshooting/fhir-reference-resolution.md

@@ -0,0 +1,15 @@
+---
+title: FHIR Reference Resolution
+icon: file
+---
+
+Sending Task resources to another DSF FHIR Server causes that server to try to resolve any references inside the Task resource (usually on another DSF FHIR server).
+If this fails, the Task resource will be rejected and causes Processes like [Ping Pong 2.x](https://github.com/datasharingframework/dsf-process-ping-pong) and 
+[Data Sharing](https://github.com/medizininformatik-initiative/mii-process-data-sharing) to fail. Anything that can cause an HTTPS request to fail may also cause reference resolution to fail.
+Some specific reasons may include:
+- Firewall blocking connection between FHIR servers: A common issue is that firewalls are configured to allow DSF BPE and DSF FHIR servers to communicate but not DSF FHIR servers amongst themselves.
+- Certificate validation: The DSF FHIR server sent the Task resource will present its server certificate to the DSF FHIR server trying to resolve the reference. If the reference resolving DSF FHIR does not trust the certificate presented by the requesting DSF FHIR server, the reference won't be resolved. This issue may arise because the trust store of the reference resolving DSF FHIR server is misconfigured or the server certificate presented by requesting DSF FHIR server is invalid, e.g. because it is expired. 
+- Connection timeouts
+- SSL/TLS handshake failures
+
+This list is not exhaustive. Errors might need specific debugging

docs/src/s/fhir-reference-resolution.md

@@ -0,0 +1,2 @@
+<meta http-equiv="refresh" content="0; url=../operations/troubleshooting/fhir-reference-resolution" />
+<p>If you are not redirected, <a href="../operations/troubleshooting/fhir-reference-resolution">click here</a>.</p>