Patient Service

A client application can use the PatientService to manage patient data. The service provides methods to create, read and update patient records. The endpoints are secured with the PHDIAM policy which means the client must provide valid credentials and a PHDIAM certificate to access the service. It allows following operations.

• Create a new patient record
• Read an existing patient record by FHIR ID
• Update an existing patient record by FHIR ID

Create a new patient record

To create a new patient record, the client can POST a Patient record to the server's Patient endpoint. For example:

curl -sS -X POST --json @patient.json "https://${server}/fhir/r5/api/Patient" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Where patient.json is a JSON file with information about the patient. The structure of this JSON is defined by the Roche's FHIR profile https://roche.com/fhir/iop/StructureDefinition/rdc-Patient, which is part of this implementation guide. The following example is a minimal JSON to create a Patient record with name, email and identifier, which contains the mandatory fields for the patient creation. The identifier.system is a String which is registered within the Roche system to identify the managing organization's system used for patient identification, and the identifier.value is a unique identifier for the patient within that system. Provided email also has to be unique.

The following example includes all the fields that can be specified in the Patient resource, where besides the mandatory field we can set also values for gender, birthDate, and another telecom (phone number). The telecom field can contain at most 2 entries, one of them having system set to email and the other one having system set to phone. The contained Condition resource describes the patient's diabetes type by the code value in the snomed system, the allowed values for this code are specified in ValueSet https://roche.com/fhir/iop/ValueSet/diabetes-type-codes, which is part of this implementation guide.

In case the request is successful, the server will respond with a 201 Created status code and the FHIR ID of the created patient will be returned in the Location header of the response. In case the request contains a JSON that does not conform to the profile or the unique condition for identifier or email values is violated, the server will respond with a 422 Unprocessable Entity status code with the following error message:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Patient.identifier: minimum required = 1, but only found 0 (from https://roche.com/fhir/iop/StructureDefinition/rdc-Patient|1.0.0)",
      "expression": [
        "Patient"
      ]
    }
  ]
}

Read an existing patient record by FHIR ID

To fetch an existing patient record by its FHIR ID, the client can send a GET request to the server's Patient endpoint with the FHIR ID of the patient. For example:

curl -sS "https://${server}/fhir/r5/api/Patient/${patient_fhir_id}" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Where ${patient_fhir_id} is the FHIR ID of the patient to be fetched. The response will be a JSON of Patient resource in the FHIR R5 format conforming to the Roche's FHIR profile https://roche.com/fhir/iop/StructureDefinition/rdc-Patient, for example:

Update an existing patient record by FHIR ID

Similarly to Patient record creation, to update a patient record, the client can send a PUT request to the server's Patient endpoint. For example:

curl -sS -X PUT --json @patient.json "https://${server}/fhir/r5/api/Patient/${patient_fhir_id}" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Where ${patient_fhir_id} is the FHIR ID of the patient to be updated and patient.json is a JSON file with the updated information about the patient, the full JSON of patient resource should be provided, not just the fields to be updated. In successful case, the server responds with 200 OK status. In case the record with ${patient_fhir_id} FHIR ID does not exist, the server responds with a 404 Not Found status code. In case the patient.json JSON file contains invalid data, the 422 Unprocessable Entity status code is returned with an error message, for example:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Patient.name: minimum required = 1, but only found 0 (from https://roche.com/fhir/iop/StructureDefinition/rdc-Patient|1.0.0)",
      "expression": [
        "Patient"
      ]
    }
  ]
}