Find Document References

Endpoint

POST https://api.pjd.test.nhn.no/R4/fhir/DocumentReference/_search

Scopes

The endpoint requires one of the following two scopes. It's not possible to use both scopes in the same request.

Filtering according to Kjernejournalforskriften

If using the second scope.

Example

Simple POST to retreive all document references for LINE DANSER

• FHIR server root is https://api.pjd.test.nhn.no
• Patient reference id is 13116900216 (LINE DANSER)
• status of current

Example POST Body

POST api.pjd.test.nhn.no/fhir/DocumentReference/_search	  
Host api.pjd.test.nhn.no
Content-Type: application/x-www-form-urlencoded
Accept: application/fhir+json; fhirVersion=4.0
nhn-source-system: EPJ System 1.0
nhn-event-id: <unique id>
Authorization: DPoP <DPoP authorization bearer token>
DPoP: <DPoP proof token>

patient.identifier=13116900216&status=current

Header Parameters

Query Parameters

See ITI-67 for full details

Return value

If 200 OK then the endpoint returns a FHIR bundle according to ITI-67. See below for further response details.

Return header parameters

Response validation

The structure of the response has been validated with Matchbox.health validation service and should be compliant with FHIR R4 and ITI-67.

Personverninnstillinger (PVK stream)

The endpoint has access control according to Personverninnstillinger for patient in Helsenorge.

Possible responses

OperationOutcome resource in bundle when the response is 200 OK

When the API responds with status code 200 OK and a bundle with document references then the bundle may also contain a resource with "resourceType": "OperationOutcome".

The OperationOutcome resource may contain a list of issues which is a the list of registry errors received from various registry locations.

Example OperationOutcome resource type

 {
      "fullUrl": "urn:uuid:cfe86f3f-c21f-42c3-9d8b-878cd4217298",
      "resource": {
        "resourceType": "OperationOutcome",
        "meta": {
          "profile": [
            "http://hl7.org/fhir/StructureDefinition/OperationOutcome"
          ]
        },
        "issue": [
          {
            "severity": "error",
            "code": "exception",
            "details": {
              "coding": [
                {
                  "system": "urn:ihe:iti:xds",
                  "code": "XDSRegistryError",
                  "display": "XDSRegistryError"
                }
              ],
              "text": "Access denied"
            },
            "diagnostics": "{\"location\":\"urn:oid:2.16.578.1.12.4.1.7.1.11\",\"locationName\":\"Diakonhjemmet Sykehus\",\"errorCode\":\"XDSRegistryError\"}"
          },
          {
            "severity": "error",
            "code": "not-found",
            "details": {
              "coding": [
                {
                  "system": "urn:ihe:iti:xds",
                  "code": "XDSUnavailableCommunity",
                  "display": "XDSUnavailableCommunity"
                }
              ],
              "text": "Cannot retrieve from  target domain 2.16.578.1.12.4.1.2.5604"
            },
            "diagnostics": "{\"location\":\"urn:oid:2.16.578.1.12.4.1.2.5604\",\"locationName\":\"Helse S\\u00F8r-\\u00D8st regionalt helseforetak\",\"errorCode\":\"XDSUnavailableCommunity\"}"
          }
        ]
      }
    }

Issues

Diagnostics object

The diagnosstics object can be used to find the name of the location. Our API automatically maps OID to name and fills in the locationName.

We may expand the diagnostics object in later versions of the API

Example diagnostics object (deserialized from resource.issue.diagnostics)

{
  "location": "urn:oid:2.16.578.1.12.4.1.2.5604",
  "locationName": "Helse S\\u00F8r-\\u00D8st regionalt helseforetak",
  "errorCode": "XDSUnavailableCommunity"
}

Mapping from ebXML Registry Error Code to 'resource.issue.code' in issue object

Best practice for handling issues in bundled OperationOutcome:

• If there are issues with severity 'error' in the 'issues' array, then there has been errors reported from one or more registry locations

Option 1 (recommended) - display a list of unavailable locations

• Loop through the list of issues and deserialize the resource.issues.diagnostics property.
• Display a list of unavailable locations to the user, using the locationName property.

Option 2 - display a general error

• If there are any items with severity 'error' in the 'issues' array then you may simply display a general error notifying the user that some sources/locations are unavailable.