Enabling FHIR profiles

This page explains how to import and enable FHIR implementation guides and profiles in FHIR stores.

To ensure that all FHIR resources in a FHIR store meet a specific criteria for resource structure and information captured, use FHIR implementation guides and profiles. If a FHIR resource meets the rules specified in a profile, the FHIR resource conforms to the profile.

Overview

FHIR profiles are a set of additional rules defined on top of the base FHIR specification that handle how different healthcare systems process resources. You can import and enable FHIR profiles in a FHIR store to ensure that all resources in a FHIR store meet specific criteria for resource structure and information captured.

Structure definitions and implementation guides

You can import FHIR profiles for your FHIR store by inserting one or more structure definitions grouped into one or more implementation guides. Use a structure definition to do the following:

  • Define the constraint for a field in a FHIR resource.
  • Reference value sets that link code systems and FHIR resources.

You use an implementation guide with structure definitions to validate resources so that they match the use case of your third-party software.

For example, suppose that your third-party software needs to comply with the Centers for Medicare & Medicaid Services (CMS) interoperability and Patient Access final rule in the US. Your third-party software would need to provide a Patient Access API that complies with the CARIN profiles. You can import and enable the CARIN implementation guide in your FHIR store to validate the resources against the CARIN profiles. Importing and enabling implementation guides is described in the subsequent sections of this page.

After you have imported your implementation guide, you can enable it in your FHIR store for FHIR resource validation. When a FHIR resource is updated or added to the store, the Cloud Healthcare API verifies whether it matches a structure definition in the implementation guide. If the FHIR resource does match, the FHIR resource is added to the store. If the FHIR resource does not conform to the structure definitions in the implementation guide, an error message is returned and the FHIR resource is rejected.

Data validation enforcement

The Cloud Healthcare API enforces data validation when using the following methods:

Profile validation workflow

The following diagram shows the validation workflow for adding or updating FHIR resources:

fhir-profiles

Define your FHIR profiles

The following sections describe how to download structure definitions from your third-party software and configure an implementation guide.

Download your structure definitions

To ensure your structure definitions match your authoritative source, download the structure definitions, implementation guides, and value sets from your third-party software provider.

For example, if your system uses the Blue Button patient profile, you can download the structure definitions and implementation guide used by Blue Button.

The Cloud Healthcare API allows validation for the following type of structure definition rules:

  • slicing (on the value or pattern type)
  • min/max
  • type
  • fixed
  • pattern
  • minValue
  • maxValue
  • maxLength
  • binding

Configure your implementation guide

After you have downloaded your structure definitions, implementation guide, and value set, you must add the profiles that the implementation guide uses to validate FHIR resources.

To add the implementation guide to a FHIR store, complete the following steps:

  1. Open the implementation guide file you downloaded from your third-party software provider.

  2. Add the following section to include the structure definitions to be validated by your implementation guide:

    {
        "resourceType": "ImplementationGuide",
        ...
        "global": [
            {
            "type": "RESOURCE_TYPE",
            "profile": "STRUCTURE_DEFINITION_URL"
            }
        ]
        ...
    }
    

    Replace the following:

    • RESOURCE_TYPE: the FHIR resource type
    • STRUCTURE_DEFINITION_URL: the URL to the profile's source structure definition
  3. Save the implementation guide file.

Upload your implementation guide to Cloud Storage

After you have edited your implementation guide, you must upload the following files to Cloud Storage:

  • The implementation guide
  • Structure definitions
  • Value sets

After uploading, you can use these files to validate resources in your FHIR store.

To add the implementation guide, structure definitions, and value sets to Cloud Storage, run the following commands:

gsutil cp -r \
   PATH_TO_IMPLEMENTATION_GUIDE \
   gs://BUCKET/IMPLEMENTATION_GUIDE

Replace the following

  • PATH_TO_IMPLEMENTATION_GUIDE: the path to the implementation guide on your local machine
  • BUCKET/IMPLEMENTATION_GUIDE: the bucket and directory where you store the implementation guide in Cloud Storage

Import your implementation guide

To use the implementation guide to validate profiles in your FHIR store, import it to your FHIR store as a FHIR resource.

The following samples show how to import your implementation guide to a FHIR store:

gcloud

To add your implementation guide as a resource to a FHIR store, run the gcloud healthcare fhir-stores import gcs command:

gcloud healthcare fhir-stores import gcs FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --gcs-uri=gs://BUCKET/DIRECTORY

Replace the following:

  • FHIR_STORE_ID: the FHIR store ID
  • DATASET_ID: the dataset ID
  • BUCKET/DIRECTORY: the location of the implementation guide in a Cloud Storage bucket

The output is the following:

Request issued for: [FHIR_STORE_ID]
Waiting for operation [OPERATION_ID] to complete...done.
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

In this output:

  • PROJECT_ID, LOCATION, DATASET_ID: the values that you provided in the method call
  • OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To view more details of the operation, run the gcloud healthcare operations describe command, providing the OPERATION_ID from the response:

gcloud healthcare operations describe OPERATION_ID \
  --dataset=DATASET_ID

The output is the following. If the response contains done: true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then run the gcloud healthcare operations describe command again.

done: true
metadata:
  '@type': type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata
  apiMethodName: google.cloud.healthcare.v1.fhir.FhirService.ImportResources
  createTime: 'CREATE_TIME'
  endTime: 'END_TIME'
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID
response:
  '@type': type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse
  fhirStore: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

API

curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '{
      "contentStructure": "RESOURCE_PRETTY",
      "gcsSource": {
        "uri": "gs://BUCKET/DIRECTORY"
      }
    }' "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import"

Replace the following:

  • BUCKET/DIRECTORY: the location of the implementation guide in a Cloud Storage bucket
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

In this output:

  • PROJECT_ID, LOCATION, DATASET_ID: the values that you provided in the method call
  • OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To track the status of the operation, use the operations.get method:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID
  • OPERATION_ID: the ID returned from the long-running operation

The output is the following. If the response contains "done": true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then call the operations.get method again.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.ImportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/viewer/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

PowerShell

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body '{
    "contentStructure": "RESOURCE_PRETTY",
    "gcsSource": {
      "uri": "gs://BUCKET/DIRECTORY"
    }
  }' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import" | Select-Object -Expand Content

Replace the following:

  • BUCKET/DIRECTORY: the location of the implementation guide in a Cloud Storage bucket
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

In this output:

  • PROJECT_ID, LOCATION, DATASET_ID: the values that you provided in the method call
  • OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To track the status of the operation, use the operations.get method:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID
  • OPERATION_ID: the ID returned from the long-running operation

The output is the following. If the response contains "done": true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then call the operations.get method again.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.ImportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/viewer/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

Enable your implementation guide

To use an implementation guide resource to validate profiles, you must enable the implementation guide. If you enable more than one implementation guide, both implementation guides take effect. A FHIR resource only needs to to match one profile from any enabled implementation guide.

The following samples show how to enable your implementation guide for profile validation on an existing FHIR store:

curl

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/fhir+json; charset=utf-8" \
    --data '{
      "validationConfig": {
          "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
      }
    }' "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig"

Replace the following:

  • IMPLEMENTATION_GUIDE_URL: the path to the implementation guide resource
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "validationConfig": {
    "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
  }
}

PowerShell

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body '{
      "validationConfig": {
          "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
      }
  }' `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig" | Select-Object -Expand Content

Replace the following:

  • IMPLEMENTATION_GUIDE_URL: the path to the implementation guide resource
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "validationConfig": {
    "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
  },
}