R4 Overview

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 are over HTTPS. See Service Root URL for more information on the URL format. All data are 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:

Service Root URL

URLs for the FHIR® server vary according to the tenant (data source or client) being accessed, as well as other factors. If the application is a Substitutable Medical Applications and Reusable Technologies (SMART)® application, the service root url is provided at launch time. For standalone applications, the URL can be requested or configured when the application is set up to run against a specific tenant. SMART® applications make FHIR® calls against URLs of the following format:

:serviceRootURL/:resource[?:parameters]

Secure Sandbox

You can use the secure sandbox for testing an application with authorization. The service root URL for this instance is different if the patient or a patient’s proxy is logging in.

Patient or Patient’s Proxy Access: https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/:resource[?:parameters] Non-Patient Access: https://fhir-ehr-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/:resource[?:parameters]

Open Sandbox

Cerner does not currently provide an open sandbox instance of Soarian Clinicals®. Please use the Secure Sandbox URL.

Resource

:resource represents the FHIR® standard resource to access. Example: Patient

Parameters

Many API methods support optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -i -H "Accept: application/json+fhir" "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/MedicationRequest?patient=4C05F5F357EE44FC874C0CF4AB249F99&status=active"

In this example, MedicationOrder is the FHIR® standard resource being accessed, while patient and status are passed in the query string.

Resource Identity

Please note that no IDs or identifiers in the Soarian Clinicals® EHR are intended to be used outside of the context of their complete URL. A complete URL is composed of the service root url, the resource, and the parameters (if any).

For example, you must take into account the entire URL and not simply the ID or resource + ID:

https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Patient/4C05F5F357EE44FC874C0CF4AB249F99

In another context, the ID Patient/4C05F5F357EE44FC874C0CF4AB249F99 may identify another person entirely. In the following example, a different resource may be returned because the context (service root URL) has changed.

https://fhir-myrecord-sc.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Patient/4C05F5F357EE44FC874C0CF4AB249F99

Similarly, when considering an identifier, you must consider it only in its full context. Even though some identifiers may exist across multiple systems (for example, MRN), they may not refer to the same resource.

https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Patient?identifier=urn:oid:1.1.1.1.1.1|1001006

For example, when using the above MRN in a different system, the same Patient resource may not be returned in the response bundle:

https://fhir-myrecord-sc.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Patient?identifier=urn:oid:1.1.1.1.1.1|1001006

Client Errors

Several possible types of client errors may occur on API calls that receive request bodies:

Operation Outcomes

An OperationOutcome resource may be returned to provide additional context to an error. The following tables describe common operation outcomes 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 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

  1. 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

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® FHIR® R4 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 documentation for details on how to authorize using the Soarian Clinicals® FHIR® R4 server.

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 Links, rather than 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 in 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 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