Configura perfiles de FHIR

Las guías de implementación y los perfiles de FHIR garantizan que los recursos en un almacén de FHIR cumplan con criterios definidos específicos. Algunos ejemplos de guías de implementación incluyen la Guía de implementación principal de EE.UU. 4.0.0 y la Guía de implementación de Blue Button de Carin.

En esta página, se explica cómo definir, configurar y usar las guías de implementación y los perfiles en los almacenes de FHIR R4 mediante la guía de implementación principal de EE.UU. 4.0.0.

Descripción general

Los perfiles de FHIR son un conjunto de reglas adicionales definidas sobre la especificación de base de FHIR que manejan cómo los diferentes sistemas de atención médica procesan los recursos. Puedes importar y habilitar perfiles de FHIR en un almacén de FHIR a fin de asegurarte de que todos los recursos en un almacén de FHIR cumplan con criterios específicos de la información y la estructura de recursos capturados.

Definiciones de estructura y guías de implementación

Puedes importar perfiles de FHIR para tu almacén de FHIR mediante la inserción de una o más definiciones de estructura agrupadas en una o más guías de implementación. Usa una definición de estructura para hacer lo siguiente:

• Define la restricción para un campo en un recurso de FHIR.
• Conjuntos de valores de referencia que vinculan sistemas de códigos y recursos de FHIR.

Usa una guía de implementación con definiciones de estructura para validar recursos que coincidan con el caso práctico de tu software de terceros.

Por ejemplo, supongamos que tu software de terceros debe cumplir con la regla final de interoperabilidad y acceso de pacientes de Servicios de Medicare y Medicaid (CMS) en EE.UU. El software de terceros tendría que proporcionar una API de acceso para pacientes que cumpla con los perfiles de CARIN. Puedes importar y habilitar la guía de implementación de CARIN en tu almacén de FHIR para validar los recursos en los perfiles de CARIN. La importación y la habilitación de las guías de implementación se describen en las secciones posteriores de esta página.

Después de importar la guía de implementación, puedes habilitarla en tu almacén de FHIR para la validación de recursos de FHIR. Cuando un recurso de FHIR se actualiza o se agrega al almacén, la API de Cloud Healthcare verifica si coincide con una definición de estructura de la guía de implementación. Si el recurso de FHIR coincide, el recurso de FHIR se agrega al almacén. Si el recurso de FHIR no cumple con las definiciones de estructura en la guía de implementación, se muestra un mensaje de error y el recurso se rechaza.

Aplicación de la validación de datos

La API de Cloud Healthcare aplica la validación de datos cuando usa los siguientes métodos:

• projects.locations.datasets.fhirStores.fhir.create
• projects.locations.datasets.fhirStores.fhir.update
• projects.locations.datasets.fhirStores.fhir.patch
• projects.locations.datasets.fhirStores.executeBundle

Flujo de trabajo de la validación de perfiles

En el siguiente diagrama, se muestra el flujo de trabajo de validación para agregar o actualizar recursos de FHIR:

Define tus perfiles de FHIR

En las secciones siguientes, se describe cómo descargar las definiciones de estructura de tu software de terceros y configurar una guía de implementación.

Descarga los recursos de validación de tu perfil

Para garantizar que tus definiciones de estructura coincidan con tu fuente de autorización, debes descargar los recursos de validación de perfiles, como definiciones de estructura, guías de implementación o conjuntos de valores, de una fuente externa, como el registro de la guía de implementación de FHIR.org. Las fuentes externas proporcionan un paquete que contiene todos los conjuntos de valores, perfiles, extensiones, una lista de páginas y URL para cada guía de implementación.

Por ejemplo, si tu sistema usa el perfil de pacientes US Core, puedes descargar las definiciones de estructura y la guía de implementación que usa US Core.

La API de Cloud Healthcare permite la validación para el siguiente tipo de reglas de definición de estructura:

• slicing, que admite los siguientes discriminadores:
  • value
  • pattern
  • profile
• min/max
• type
• fixed
• pattern
• minValue
• maxValue
• maxLength
• binding, con la excepción de las siguientes reglas:
  • ValueSet.compose.include.filter
  • ValueSet.compose.exclude

Configura tu guía de implementación

Después de descargar las definiciones de estructura, la guía de implementación y el conjunto de valores, debes agregar los perfiles que la guía de implementación usa para validar los recursos de FHIR.

Para configurar la guía de implementación, completa los siguientes pasos:

1. Abre el archivo de la guía de implementación que descargaste de tu proveedor de software de terceros.

2. Agrega la siguiente sección para incluir las definiciones de estructura que validará tu guía de implementación:

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

   Reemplaza lo siguiente:

   • RESOURCE_TYPE: Define el tipo de recurso al que se aplica la guía de implementación.
   • STRUCTURE_DEFINITION_URL: Es la URL a la definición de la estructura de origen del perfil, por ejemplo, el perfil principal de pacientes de EE.UU..

3. Guarda el archivo de la guía de implementación.

   En el siguiente ejemplo, se muestran los perfiles de pacientes y organizaciones habilitados para la guía de implementación de EE.UU.:

   "global":[
     {
       "type":"Patient",
       "profile":"https://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
     },
     {
       "type":"Organization",
       "profile":"https://hl7.org/fhir/us/core/StructureDefinition/us-core-organization"
     },
     ...
   ]
   

Sube tu guía de implementación a Cloud Storage

Después de editar la guía de implementación, debes subir los siguientes archivos a Cloud Storage:

• La guía de implementación
• Definiciones de estructura
• Conjuntos de valores

Después de subirlos, puedes usar estos archivos para validar recursos en tu almacén de FHIR.

Para subir tu guía de implementación a Cloud Storage, completa los siguientes pasos:

1. Borra todos los archivos de la guía de implementación que no usan los perfiles de FHIR en la API de Cloud Healthcare.

   Por ejemplo, si implementas la guía de implementación principal de EE.UU., puedes borrar los siguientes archivos:

   • .DS_Store
   • ig-r4.json
   • openapi/.index.json
   • package.json

2. Para agregar la guía de implementación, las definiciones de estructura y los conjuntos de valores a Cloud Storage, ejecuta los siguientes comandos:

   gcloud storage cp \
      PATH_TO_IMPLEMENTATION_GUIDE \
      gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY \
      --recursive

   Reemplaza lo siguiente:

   • PATH_TO_IMPLEMENTATION_GUIDE: Es la ruta de acceso a la guía de implementación en tu máquina local.
   • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: El bucket y el directorio en los que almacenas la guía de implementación en Cloud Storage

Importa la guía de implementación

Para usar la guía de implementación para validar perfiles en tu almacén de FHIR, impórtalo a tu almacén de FHIR como un recurso de FHIR.

En los siguientes ejemplos, se muestra cómo importar la guía de implementación a un almacén de FHIR:

gcloud healthcare fhir-stores import gcs FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --gcs-uri='gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY/*' \
  --content-structure=resource-pretty

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

gcloud healthcare operations describe OPERATION_ID \
  --dataset=DATASET_ID

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

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/IMPLEMENTATION_GUIDE_DIRECTORY/*"
      }
    }' "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import"

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

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"

{
  "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/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

$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/IMPLEMENTATION_GUIDE_DIRECTORY/*"
    }
  }' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import" | Select-Object -Expand Content

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

$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

{
  "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/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

Sube e importa dependencias de tu implementación

Antes de poder habilitar tu guía de implementación, debes asegurarte de que todas las dependencias de la guía se suban y se importen. Las dependencias se definen mediante el parámetro dependsOn en tu guía de implementación de la siguiente manera:

"dependsOn":[
  {
    "id":"hl7_fhir_uv_bulkdata",
    "uri":"http://hl7.org/fhir/uv/bulkdata/ImplementationGuide/hl7.fhir.uv.bulkdata",
    "packageId":"hl7.fhir.uv.bulkdata",
    "version":"1.0.1"
  },
  {
    "id":"vsac",
    "uri":"http://fhir.org/packages/us.nlm.vsac/ImplementationGuide/us.nlm.vsac",
    "packageId":"us.nlm.vsac",
    "version":"0.3.0"
  }
]

Para subir y, luego, importar dependencias, sigue las instrucciones en Sube tu guía de implementación a Cloud Storage y en Importa tu guía de implementación, respectivamente.

Habilita tu guía de implementación

Para usar un recurso de guía de implementación a fin de validar perfiles, debes habilitar la guía de implementación. Si habilitas más de una guía de implementación, la API de Cloud Healthcare intenta validar los perfiles en todas las guías de implementación. Un recurso de FHIR solo debe coincidir con un perfil de cualquier guía de implementación habilitada.

La API de Cloud Healthcare solo valida las guías de implementación cuando las habilitas. Si modificas una guía de implementación y la vuelves a habilitar, la API de Cloud Healthcare valida la guía de implementación modificada.

Si quitas una guía de implementación después de habilitarla, esta deja de tener efecto.

En los siguientes ejemplos, se muestra cómo habilitar la guía de implementación para la validación de perfiles en un almacén de FHIR existente:

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"],
          "disableProfileValidation": false
      }
    }' "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig"

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

$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/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig" | Select-Object -Expand Content

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

def enable_implementation_guide(
    project_id,
    location,
    dataset_id,
    fhir_store_id,
    implementation_guide_url,
):
    """
    Patches an existing FHIR store to enable an ImplementationGuide resource
    that exists in the FHIR store.

    See https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/healthcare/api-client/v1/fhir
    before running the sample."""
    # Imports the Google API Discovery Service.
    from googleapiclient import discovery

    api_version = "v1"
    service_name = "healthcare"
    # Instantiates an authorized API client by discovering the Healthcare API
    # and using GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = discovery.build(service_name, api_version)

    # TODO(developer): Uncomment these lines and replace with your values.
    # project_id = 'my-project'  # replace with your GCP project ID
    # location = 'us-central1'  # replace with the dataset's location
    # dataset_id = 'my-dataset'  # replace with your dataset ID
    # fhir_store_id = 'my-fhir-store'  # replace with the FHIR store's ID
    # implementation_guide_url =
    # 'http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core'  #
    # replace with the 'url' property in the ImplementationGuide resource
    fhir_store_parent = "projects/{}/locations/{}/datasets/{}".format(
        project_id, location, dataset_id
    )
    fhir_store_name = f"{fhir_store_parent}/fhirStores/{fhir_store_id}"

    validation_config = {
        "validationConfig": {"enabledImplementationGuides": [implementation_guide_url]}
    }

    request = (
        client.projects()
        .locations()
        .datasets()
        .fhirStores()
        .patch(
            name=fhir_store_name, updateMask="validationConfig", body=validation_config
        )
    )

    response = request.execute()
    print(
        "Enabled ImplementationGuide with URL {} on FHIR store {}".format(
            implementation_guide_url, fhir_store_id
        )
    )

    return response

Usa la consola de Google Cloud para habilitar las guías de implementación

Cuando usas la consola de Google Cloud para crear o editar un almacén de FHIR, puedes hacer lo siguiente:

• Selecciona las guías de implementación predeterminadas que proporciona la API de Cloud Healthcare.
• Importa una guía de implementación personalizada desde Cloud Storage a tu almacén de FHIR

Para importar una guía de implementación personalizada, sigue estos pasos:

1. Descarga los recursos de validación de tu perfil.

2. Opcional: Configura tu guía de implementación.

   Este paso es necesario para agregar el array global al recurso de la guía de implementación manualmente. Si decides omitir este paso, debes agregar el array global cuando crees el paquete de transacciones de FHIR en el siguiente paso con un método diferente, como la herramienta Bundler for FHIR profile validation resources con la marca generate_global_array.

3. Crea un paquete de transacciones de FHIR con los recursos de validación de tu perfil, que incluya la guía de implementación, las definiciones de estructura y los conjuntos de valores.

   Puedes crear el paquete de transacciones con la herramienta Bundler for FHIR profile validation resources.

4. Sube el paquete de validación de perfiles de FHIR a una ubicación de Cloud Storage.

   gcloud storage cp \
      PATH_TO_PROFILE_VALIDATION_BUNDLE \
      gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY \
      --recursive

   Reemplaza lo siguiente:

   • PATH_TO_PROFILE_VALIDATION_BUNDLE: Es la ruta de acceso al paquete de validación de perfiles en tu máquina local.
   • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: Es la ubicación de Cloud Storage en la que se debe almacenar el paquete.

5. Importa tu guía de implementación personalizada desde la ubicación de Cloud Storage cuando crees o edites tu almacén de FHIR.

Valida recursos en función de perfiles específicos

En los siguientes ejemplos, se muestra cómo validar un recurso de FHIR para un perfil específico o todos los perfiles definidos para un almacén de FHIR. Validar el recurso de FHIR te permite determinar si tu recurso de FHIR se ajusta a uno más.

Para validar un recurso de FHIR, usa el método fhir.Resource-validate.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @RESOURCE_FILE \
    'https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/$validate?profile=PROFILE_URL'

{
  "issue": [
    {
      "code": "informational",
      "details": {
        "text": "success"
      },
      "diagnostics": "success",
      "severity": "information"
    }
  ],
  "resourceType": "OperationOutcome"
}

{
    "issue": [
        {
            "code": "processing",
            "diagnostics": "Profile http://hl7.org/fhir/StructureDefinition/AuditEvent, Element 'AuditEvent.agent.requestor': minimum required = 1, but only found 0",
            "location": [
                "AuditEvent.agent"
            ],
            "severity": "error"
        }
    ],
    "resourceType": "OperationOutcome"
}

$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 '@RESOURCE_FILE' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/$validate?profile=PROFILE_URL" | Select-Object -Expand Content

{
  "issue": [
    {
      "code": "informational",
      "details": {
        "text": "success"
      },
      "diagnostics": "success",
      "severity": "information"
    }
  ],
  "resourceType": "OperationOutcome"
}

{
    "issue": [
        {
            "code": "processing",
            "diagnostics": "Profile http://hl7.org/fhir/StructureDefinition/AuditEvent, Element 'AuditEvent.agent.requestor': minimum required = 1, but only found 0",
            "location": [
                "AuditEvent.agent"
            ],
            "severity": "error"
        }
    ],
    "resourceType": "OperationOutcome"
}

def validate_resource_profile_url(
    project_id, location, dataset_id, fhir_store_id, resource_type, profile_url
):
    """Validates an input FHIR resource's conformance to a profile URL. The
    profile StructureDefinition resource must exist in the FHIR store before
    performing validation against the URL.

    See https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/healthcare/api-client/v1/fhir
    before running the sample."""
    # Imports Python's built-in "os" module
    import os

    # Imports the google.auth.transport.requests transport
    from google.auth.transport import requests

    # Imports a module to allow authentication using a service account
    from google.oauth2 import service_account

    # Gets credentials from the environment.
    credentials = service_account.Credentials.from_service_account_file(
        os.environ["GOOGLE_APPLICATION_CREDENTIALS"]
    )
    scoped_credentials = credentials.with_scopes(
        ["https://www.googleapis.com/auth/cloud-platform"]
    )
    # Creates a requests Session object with the credentials.
    session = requests.AuthorizedSession(scoped_credentials)

    # URL to the Cloud Healthcare API endpoint and version
    base_url = "https://healthcare.googleapis.com/v1"

    # TODO(developer): Uncomment these lines and replace with your values.
    # project_id = 'my-project'  # replace with your GCP project ID
    # location = 'us-central1'  # replace with the parent dataset's location
    # dataset_id = 'my-dataset'  # replace with the parent dataset's ID
    # fhir_store_id = 'my-fhir-store' # replace with the FHIR store ID
    # resource_type = 'Patient'  # replace with the FHIR resource type
    # profile_url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient'  # replace with the profile URL
    url = f"{base_url}/projects/{project_id}/locations/{location}"

    resource_path = "{}/datasets/{}/fhirStores/{}/fhir/{}".format(
        url, dataset_id, fhir_store_id, resource_type
    )

    resource_path += "/$validate"
    params = {"profile": profile_url}

    # The body shown works with a Patient resource and is not guaranteed
    # to work with other types of FHIR resources. If necessary,
    # supply a new body with data that corresponds to the resource you
    # are validating and supply a new resource_type.
    body = {
        "name": [{"use": "official", "family": "Smith", "given": ["Darcy"]}],
        "gender": "female",
        "birthDate": "1970-01-01",
        "resourceType": "Patient",
    }

    # Sets required application/fhir+json header on the request
    headers = {"Content-Type": "application/fhir+json;charset=utf-8"}

    response = session.post(resource_path, headers=headers, json=body, params=params)
    response.raise_for_status()

    resource = response.json()

    print(json.dumps(resource))

    return resource