FHIR Implementation Guide for NJSAMS


1.0.0 - release

NJSAMS - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

API

Capability Statement

The FHIR server supports the CapabilityStatement resource, which describes the server's capabilities and supported operations. The capability statement is publicly available at the following URL: https://fhir.njsams.rutgers.edu/NJSAMS-FHIR-API/metadata?_format=application/json

The API supportings search , read, create, and update operations.

Authorization (Production & Sandbox)

The FHIR server endpoint is protected. Third-party applications (Apps) can ask the resource owner (a User) for permission to access protected resources on their behalf. The server implements OAuth2 and SMART on FHIR standards, which describe how the App can ask the User for such permission.

Before an App can run against the FHIR API, it must be registered with the NJSAMS authorization server. Every registered App receives its client_id and client_secret. Please contact NJSAMS for getting access.

In addition to the parameters specified in the SMART on FHIR documentation, the Apps must use the following parameters when making a request to the /authorize endpoint:

  • response_type: code
  • redirect_uri: any of the redirect_uri values communicated to NJSAMS when registering the App
  • scope: openid fhirUser user/*.read
  • aud: https://fhir.njsams.rutgers.edu/NJSAMS-FHIR-API

The OpenID Connect configuration is available at the following URL:

The SMART on FHIR configuration is available at the following URL:

Security Labels

The FHIR server uses security labels to protect sensitive information. The server supports the following security labels: https://fhir.njsams.rutgers.edu/NJSAMS-fhir/fhir/security/provider-id

Every resource must be tagged with a security label. The server will return a 403 Forbidden error if the resource does not have the required security label.

Authentication (Single Sign-On)

The FHIR server supports Single Sign-On (SSO) using the OpenID Connect protocol. External identity providers (IdPs) such as Microsoft Entra, Okta, and Auth0 can be used to authenticate users. The FHIR server will redirect users to the IdP for authentication, and upon successful authentication, the IdP will redirect the user back to the FHIR server with an authorization code.

IdPs SHALL include a unique identifier as an OIDC claim for each user: https://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#scopes-for-requesting-identity-data.

Ideally, the IdP SHOULD include the fhirUser scope in the OIDC claims. This scope is used to identify the user in the FHIR server and is required for accessing protected resources.

Support for asymmetric clients using JWKs is also available. This allows clients to authenticate using public/private key pairs instead of client secrets. If a client wants to hosts its own JWKs, it can provide NJSAMS with a JWKs URL. The FHIR server will use this URL to retrieve the JWKs and verify the client's signature.

Please contact NJSAMS for more information on setting up SSO with your IdP.

Sandbox

There is a non-production NJSAMS FHIR sandbox server with anonymized example data for testing. This Sandbox requires authentication. The {server-base} for the sandbox is:

The SMART on FHIR configuration for the sandbox is available at:

The URL for the Sandbox authorization server is:

The OpenID Connect configuration for the sandbox is available at:

Read and Search: Patient

The patient resource represents a client and includes demographics and contact information.

Read

To read a patient, provide the patient's Logical ID.

Request abstract

GET [server-base]/Patient/:logical-id
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request with a fake logical-id

GET [server-base]/Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response example

{
  "resourceType": "Patient",
  "id": "8d5802a8-14ea-4198-ba0d-bd1884e63053",
  "meta": {
    "profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSPatient"]
  }
  // ...
}

See also

To search patients, provide patient search criteria

Search

GET [server-base]/Patient?:search-criteria
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for patients with family name "smith"

GET [server-base]/Patient?family=smith
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for patients with client identifier "12345"

GET [server-base]/Patient?identifier=12345
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response

The response is a FHIR Bundle containing the matching patients:

{
  "resourceType": "Bundle",
  "type": "search-result",
  "entry": [
    // ... Patient resources
  ]
}



Read and Search: Encounter

An encounter represents a vist for a client, including the location and length of stay.

Read

To read an encounter, provide the encounters's Logical ID.

Request abstract

GET [server-base]/Encounter/:logical-id
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request with a fake logical-id

GET [server-base]/Encounter/9c9ee5c7-f972-4b19-8e68-07b8b95cfe4e
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response example

{
  "resourceType": "Encounter",
  "id": "9c9ee5c7-f972-4b19-8e68-07b8b95cfe4e",
  "meta": {
    "profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSEncounter"]
  }
  // ...
}

See also

Search

To search encounters, provide encounter search criteria

Search

GET [server-base]/Encounter?:search-criteria
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for encounters for a known patient

GET [server-base]/Encounter?subject=Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for encounters overlapping a specified date

GET [server-base]/Encounter?date=2022-01-01
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for all encounters and include the patient in response

GET [server-base]/Encounter?_include=Encounter:subject
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response

The response is a FHIR Bundle containing the matching patients:

{
  "resourceType": "Bundle",
  "type": "search-result",
  "entry": [
    // ... Encounter resources
  ]
}



Read and Search: Coverage

An coverage represents a a payor for a client

Read

To read a coverage, provide the coverage's Logical ID.

Request abstract

GET [server-base]/Coverage/:logical-id
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request with a fake logical-id

GET [server-base]/Coverage/d06175bc-1513-4831-ab3f-9f23b019a6c1
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response example

{
  "resourceType": "Coverage",
  "id": "d06175bc-1513-4831-ab3f-9f23b019a6c1",
  "meta": {
    "profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSCoverage"]
  }
  // ...
}

See also

Search

To search coverage, provide coverage search criteria

Search

GET [server-base]/Coverage?:search-criteria
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for coverages for a known patient

GET [server-base]/Coverage?beneficiary=Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for coverages by payor organization

GET [server-base]/Coverage?payor=Organization/1r566il9-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response

The response is a FHIR Bundle containing the matching patients:

{
  "resourceType": "Bundle",
  "type": "search-result",
  "entry": [
    // ... Coverage resources
  ]
}

Create and Update : Bundle

⚠️ WARNING: Please be aware that FHIR resources created in NJSAMS will not be immediately available to read from the FHIR API. FHIR resources must be processed by NJSAMS before they are available to read. This may take at least 24 hours.

Only FHIR Bundles can be created or updated. The FHIR server does not support creating or updating individual resources.

Bundles are used to create or update multiple resources in a single request. The bundle must contain the resources to be created or updated, and the bundle type must be set to transaction. The bundle must also contain a Bundle.entry.request element for each resource to be created or updated. The method field must be set to POST for creating resources and PUT for updating resources. The url field must be set to the resource type and logical ID of the resource being created or updated.

Create

To create a bundle, provide the bundle contents in the request body. The bundle must be of type transaction and contain the resources to be created. Request abstract

POST [server-base]/Bundle
Content-Type: application/json+fhir
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request example

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:8d5802a8-14ea-4198-ba0d-bd1884e63053",
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSPatient"],
          "security": [
            {
              "system": "https://fhir.njsams.rutgers.edu/NJSAMS-fhir/fhir/security/provider-id",
              "code": "123456"
            }
          ]
        },
        // ...
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    }
  ]
}

Response example

{
  "resourceType": "Bundle",
  "id": "8d5802a8-14ea-4198-ba0d-bd1884e63053",
  "type": "transaction-response",
  "entry": [
    {
      "response": {
        "status": "201 Created",
        "location": "[server-base]/Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053"
      }
    }
  ]
}

Update

To update a bundle, provide the bundle contents in the request body. The bundle must be of type transaction and contain the resources to be updated.

The bundle must also contain a Bundle.entry.request element for each resource to be updated. The method field must be set to PUT for updating resources. The url field must be set to the resource type and logical ID of the resource being updated.

Request abstract

PUT [server-base]/Bundle
Content-Type: application/json+fhir
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request example

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:8d5802a8-14ea-4198-ba0d-bd1884e63053",
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSPatient"],
          "security": [
            {
              "system": "https://fhir.njsams.rutgers.edu/NJSAMS-fhir/fhir/security/provider-id",
              "code": "123456"
            }
          ]
        },
      },
      "request": {
        "method": "PUT",
        "url": "Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053"
      }
    }
  ]
}

Response example

{
  "resourceType": "Bundle",
  "id": "8d5802a8-14ea-4198-ba0d-bd1884e63053",
  "type": "transaction-response",
  "entry": [
    {
      "response": {
        "status": "200 OK",
        "location": "[server-base]/Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053"
      }
    }
  ]
}