1. FHIR R4 APIs for Oracle Soarian ClinicalsFHIR R4 APIs for Oracle Soarian Clinicals
  2. R4 Overview

R4 Overview

This topic describes the R4 (4.0.1) specification.

Oracle Cerner's Soarian Clinicals implementation currently supports both the R4 First Normative Content (4.0.1) version and DSTU 2 Final (1.0.2) version of the Health Level Seven (HL7) International Fast Healthcare Interoperability Resources (FHIR) standard. Cerner's implementation of the R4 version is ongoing and new resources and actions will be added over time.

Existing DSTU 2 patient-facing applications will eventually need to be migrated to the Soarian Clinicals FHIR R4 implementation. For this reason, Cerner strongly encourages development against R4 whenever possible.

Schema

All API access is over HTTPS. See Service Root URL for more information on URL format. All data is sent and received as JSON. 

$ curl -i -H "Accept: application/fhir+json" https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata
HTTP/1.1 200 OK
Date: Tue, 26 Mar 2019 15:50:49 GMT
Cache-Control: no-cache
Vary: Origin
X-Request-Id: ecd13b72-4fde-11e9-8674-8b0a57a130fd
Content-Type: application/json+fhir
{
  "resourceType": "CapabilityStatement",
  "publisher": "Cerner Corporation",
  "date": "2021-09-06T03:25:46-04:00",
  "url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata",
  "name": "Soarian Clinicals Capability Statement",
  "title": "Soarian Clinicals Capability Statement",
  "status": "active",
  "description": "Cerner Soarian Clinicals FHIR API",
  "kind": "instance",
  "fhirVersion": "4.0.1",
  "format": [
    "json",
    "application/json",
    "application/fhir+json",
    "application/json+fhir"
  ],
  "implementation": {
    "description": "Cerner Soarian Clinicals FHIR API",
    "url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata"
  },
  "rest": [
    {
      "mode": "server",
      "documentation": "Cerner Soarian Clinicals FHIR API",
      "security": {
        "extension": [
          {
            "url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris",
            "extension": [
              {
                "url": "token",
                "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/hosts/fhir-myrecord-sc.cerner.com/protocols/oauth2/profiles/smart-v1/token"
              },
              {
                "url": "authorize",
                "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/protocols/oauth2/profiles/smart-v1/personas/patient/authorize"
              },
              {
                "url": "introspect",
                "valueUri": "https://authorization.cerner.com/tokeninfo"
              },
              {
                "url": "manage",
                "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/personas/patient/my-authorizations"
              }
            ]
          },
          {
            "url": "http://cerner.hs.fhir.com/StructureDefinition/SoarianIdLinking-uris",
            "extension": [
              {
                "url": "token",
                "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/protocols/oauth2/profiles/soarian-identity-linking-v1/token"
              },
              {
                "url": "authorize",
                "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/protocols/oauth2/profiles/soarian-identity-linking-v1/personas/patient/authorize"
              }
            ]
          }
        ],
        "cors": true,
        "description": "OAuth2 with SMART extensions"
      },
      "resource": [
        {
          "type": "Condition",
          "profile": "http://hl7.org/fhir/condition",
          "interaction": [
            {
              "code": "search-type"
            },
            {
              "code": "read"
            }
          ],
          "searchParam": [
            {
              "name": "_id",
              "definition": "http://hl7.org/fhir/SearchParameter/Resource-id",
              "type": "token",
              "documentation": "Bundle contains a Condition resource with the id requested plus any other search criteria."
            },
            {
              "name": "patient",
              "definition": "http://hl7.org/fhir/SearchParameter/clinical-patient",
              "type": "reference",
              "documentation": "Bundle contains Condition resources for the patient requested plus any other search criteria."
            },
            {
              "name": "encounter",
              "definition": "http://hl7.org/fhir/SearchParameter/Condition-encounter",
              "type": "reference",
              "documentation": "Bundle contains Condition resources for visit requested plus any other search criteria."
            },
            {
              "name": "_revinclude",
              "definition": "http://hl7.org/fhir/search.html#revinclude",
              "type": "reference",
              "documentation": "Includes Provenance resource in response. It may only be provided if at least one other parameter is provided."
            }
          ],
          "searchRevInclude": [
            "Provenance:target"
          ]
        },
        {
          "type": "Immunization",
          "profile": "http://hl7.org/fhir/immunization",
          "interaction": [
            {
              "code": "search-type"
            },
            {
              "code": "read"
            }
          ],
          "searchParam": [
            {
              "name": "_id",
              "definition": "http://hl7.org/fhir/SearchParameter/Resource-id",
              "type": "token",
              "documentation": "Fetches an Immunization resource by the logical id of the resource"
            },
            {
              "name": "patient",
              "definition": "http://hl7.org/fhir/SearchParameter/clinical-patient",
              "type": "reference",
              "documentation": "Fetches a bundle of Immunization records for the specified patient."
            },
            {
              "name": "_revinclude",
              "definition": "http://hl7.org/fhir/search.html#revinclude",
              "type": "reference",
              "documentation": "Includes Provenance resource in response. It may only be provided if at least one other parameter is provided."
            }
          ],
          "searchRevInclude": [
            "Provenance:target"
          ]
        },
        {
          "type": "MedicationRequest",
          "profile": "http://hl7.org/fhir/medicationrequest",
          "interaction": [
            {
              "code": "search-type"
            },
            {
              "code": "read"
            }
          ],
          "searchParam": [
            {
              "name": "_id",
              "definition": "http://hl7.org/fhir/SearchParameter/Resource-id",
              "type": "token",
              "documentation": "Bundle contains a MedicationRequest resource with the id requested plus any other search criteria"
            },
            {
              "name": "patient",
              "definition": "http://hl7.org/fhir/SearchParameter/clinical-patient",
              "type": "reference",
              "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] plus any other criteria."
            },
            {
              "name": "intent",
              "definition": "http://hl7.org/fhir/SearchParameter/MedicationRequest-intent",
              "type": "token",
              "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] plus any other criteria."
            },
            {
              "name": "status",
              "definition": "http://hl7.org/fhir/SearchParameter/medications-status",
              "type": "token",
              "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] and requested [status] plus any other criteria."
            },
            {
              "name": "encounter",
              "definition": "http://hl7.org/fhir/SearchParameter/medications-encounter",
              "type": "reference",
              "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] and requested [encounter] plus any other criteria."
            },
            {
              "name": "_revinclude",
              "definition": "http://hl7.org/fhir/search.html#revinclude",
              "type": "reference",
              "documentation": "Fetches all the MedicationRequest resources matching the search criteria and the Provenance resources for the result set."
            }
          ],
          "searchRevInclude": [
            "Provenance:target"
          ]
        }
      ]
    }
  ]
}

Blank fields are omitted.

All timestamps are returned in FHIR standard date/dateTime formats.

Media Types

Soarian Clinicals supports the R4 FHIR standard defined media type for JSON content:

application/fhir+json

Soarian Clinicals recommends that you explicitly request this accept type using the Accept header, however, it's not mandatory except places required by the HL7 FHIR specification. In addition Soarian Clinicals also supports following media types for JSON content for backward compatibility only and these are not recommended to be used for R4 FHIR APIs:

Client Errors

There are several possible types of client errors on API calls that receive request bodies:

  • Failing to send a required query parameter or sending an unsupported parameter when the header processing preference is set to "handling=strict" results in a 400 Bad Request response. 

    HTTP/1.1 400 Bad Request

no supported search parameters provided

  • Requesting the secure endpoint (non-open) without valid OAuth2 access token in the ‘Authorization' header results in a 401 Unauthorized response. 

    HTTP/1.1 401 Unauthorized

  • Requesting data from an unknown instance or an instance where the application or user is not authorized to access the requested resource or the patient results in a 403 Forbidden response. 

    HTTP/1.1 403 Forbidden

  • Requesting a resource which does not exist or that is masked by security results in a 404 Not Found response. 

    HTTP/1.1 404 Not Found

  • Requesting a media type other than application/json, application/fhir+json or application/json+fhir in the HTTP accept header will result in a 406 Not Acceptable response. 

    HTTP/1.1 406 Not Acceptable

Content-Length: 0

  • Posting an unsupported media format will result in a 415 Unsupported Media Type response. 

    HTTP/1.1 415 Unsupported Media Type

Operation Outcomes

An OperationOutcome may be returned to provide additional context to an error. The tables below describes common OperationOutcomes and their causes.

HTTP Status Cause Severity Code

400

Format of the parameter list is invalid

error

structure

400

Required parameter missing

error

required

400
  • Code value or coding system not supported
  • Duplicate parameters error
  • Unsupported interaction
  • Unsupported operation
  • Unsupported parameter error

error

not-supported

400

Unexpected multiple matches for a given ID

error

multiple-matches

400

Too many results; narrow search

error

business-rule

401

Invalid token

error

Unknown

403
  • Persona missing from JWT claims
  • Unrecognized scope

error

Security

404
  • Patient ID was merged to a target
  • No matching results

error

not-found

Handling Required Fields

An OperationOutcome resource may be returned to provide information regarding missing fields that are required by HL7 FHIR or the US Core HL7 profile. This OperationOutcome resource contains the DataAbsentReason. 

{
   "coding": [
     {
       "extension": [
         {
           "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
           "valueCode": "unknown"
         }
       ]
     }
   ]
 }

General Security Filtering

Certain data may not be available to all applications or users. Encounter or organization security, privileges, and preferences may filter data.

Authorization

Oracle Cerner Ignite APIs for Soarian Clinicals has an endpoint secured with OAuth 2.0 with support for SMART Applications. Refer to the extensions on the Conformance.rest.security element in the Soarian Clinicals server metadata.

Scopes supported: launch, launch/patient, openid, fhirUser, offline_access, online_access, profile, patient/AllergyIntolerance.read, patient/Binary.read, patient/CarePlan.read, patient/CareTeam.read, patient/Condition.read, patient/Device.read, patient/DiagnosticReport.read, patient/DocumentReference.read, patient/Encounter.read, patient/Goal.read, patient/Immunization.read, patient/MedicationRequest.read, patient/Observation.read, patient/Patient.read, patient/Procedure.read, patient/Provenance.read, user/AllergyIntolerance.read, user/Binary.read, user/CarePlan.read, user/CareTeam.read, user/Condition.read, user/Device.read, user/DiagnosticReport.read, user/DocumentReference.read, user/Encounter.read, user/Goal.read, user/Immunization.read, user/MedicationRequest.read, user/Observation.read, user/Organization.read, user/Patient.read, user/Person.read, user/Practitioner.read, user/Procedure.read, user/Provenance.read, system/AllergyIntolerance.read, system/Binary.read, system/CarePlan.read, system/CareTeam.read, system/Condition.read, system/Device.read, system/DiagnosticReport.read, system/DocumentReference.read, system/Encounter.read, system/Goal.read, system/Immunization.read, system/MedicationRequest.read, system/Observation.read, system/Organization.read, system/Patient.read, system/Practitioner.read, system/Procedure.read, system/Provenance.read

Each resource interaction documents the type of acceptable authentication (patient, provider, or system). While an interaction may list system authentication, this functionality is currently not available in production.

See the Authorization topics for more information.

Pagination

The pagination links are included in the Bundle when a resource returns more items than the Bundle page size. It is important to follow these Link header values instead of constructing your own URLs.

{
  "resourceType": "Bundle",
  "id": "f22ca456-19a7-45ce-8586-0079495783ef",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Observation?patient=4C05F5F357EE44FC874C0CF4AB249F99&category=vital-signs&_count=50&_format=json"
    },
    {
      "relation": "next",
      "url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Observation?patient=4C05F5F357EE44FC874C0CF4AB249F99&category=vital-signs&_count=50&_format=json&page=2&pageBookmark=NRS.VS.15262"
    }
  ],
  ...
}

The possible relation values are:

Name Description

self

Shows the URL of the current page of results.

next

Shows the URL of the next sequential page of results.

Search Result Currency

Developers need to account for data currency within the response. See the FHIR specification, where HL7 states the following about this requirement:, :

The results of a search operation are only guaranteed to be current at the moment the operation is executed. After the operation is executed, ongoing actions performed on the resources against which the search was executed will render the results increasingly stale. The significance of this depends on the nature of the search, and the kind of use that is being made of the results.

This is particularly relevant when the server is returning the results in a series of pages. It is at the discretion of the search engine of how to handle ongoing updates to the resources while the search is proceeding.

When results are returned in a series of pages, you may see the same resource ID on subsequent pages. Developers need to take this situation into account by filtering by resource ID and only return the latest version of that resource ID. Displaying duplicate resource IDs or any other manipulation may misrepresent the data, thus affecting clinical decision support and patient safety.

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

Here's a sample GET request sent from the Origin http://example.com: 

$ curl -i -H "Origin: http://example.com" -H "Accept: application/json+fhir" https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, POST
Access-Control-Max-Age: 0
Access-Control-Allow-Credentials: true

This is what a CORS preflight request looks like:

$ curl -X OPTIONS -i -H "Origin: http://example.com"  https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, POST
Access-Control-Max-Age: 0
Access-Control-Allow-Credentials: true