Practitioner Service

A client application can use the PractitionerService to manage practitioners data. The service provides methods to create, read and update practitioner 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 practitioner record
• Read an existing practitioner record by FHIR ID
• Update an existing practitioner record by FHIR ID

Create a new practitioner record

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

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

Where practitioner.json is a JSON file with information about the practitioner. The structure of this JSON is defined by the Roche's FHIR profile https://roche.com/fhir/iop/StructureDefinition/rdc-Practitioner, which is part of this implementation guide. The identifier.system is a String which is registered within the Roche system to identify the managing organization's system used for practitioner identification, and the identifier.value is a unique identifier for the practitioner within that system. Provided email also has to be unique. Example of the practitioner JSON:

In case the request is successful, the server will respond with a 201 Created status code and the FHIR ID of the created practitioner 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": "value",
      "diagnostics": "Exactly one Practitioner.identifier must be present and it needs to be the identifier in the  managing organization's system",
      "expression": [
        "Practitioner.identifier"
      ]
    }
  ]
}

Read an existing practitioner record by FHIR ID

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

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

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

{
  "resourceType": "Practitioner",
  "id": "000eecf5-b5a7-443e-9e5d-ee69ddeeedcd",
  "meta": {
    "profile": [
      "https://roche.com/fhir/iop/StructureDefinition/rdc-Practitioner"
    ]
  },
  "identifier": [
    {
      "system": "urn:oid:2.16.724.4.41",
      "value": "2d6b0e1f-b9c8-4d2c-bad6-9a7f8cbcd2b3"
    }
  ],
  "name": [
    {
      "family": "Doe",
      "given": [
        "Jane"
      ]
    }
  ],
  "telecom": [
    {
      "system": "email",
      "value": "jane.doe@email.com"
    }
  ]
}

Update an existing practitioner record by FHIR ID

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

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

Where ${practitioner_fhir_id} is the FHIR ID of the practitioner to be updated and practitioner.json is a JSON file with the updated information about the practitioner. The full JSON of the practitioner 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 ${practitioner_fhir_id} FHIR ID does not exist, the server responds with a 404 Not Found status code. In case the practitioner.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": "Practitioner.name: minimum required = 1, but only found 0 (from https://roche.com/fhir/iop/StructureDefinition/rdc-Practitioner|1.0.0)",
      "expression": [
        "Practitioner"
      ]
    }
  ]
}