Configurar perfiles FHIR

Las guías y los perfiles de implementación de FHIR aseguran que los recursos de un almacén FHIR cumplan criterios específicos. Algunos ejemplos de guías de implementación son la guía de implementación de US Core 4.0.0 y la guía de implementación de Carin Blue Button.

En esta página se explica cómo definir, configurar y usar guías de implementación y perfiles en almacenes FHIR R4 con la guía de implementación US Core 4.0.0.

Información general

Los perfiles de FHIR son un conjunto de reglas adicionales definidas sobre la especificación base de FHIR que gestionan cómo procesan los recursos los diferentes sistemas sanitarios. Puede importar y habilitar perfiles FHIR en un almacén FHIR para asegurarse de que todos los recursos de un almacén FHIR cumplen criterios específicos en cuanto a la estructura de los recursos y la información registrada.

Definiciones de estructura y guías de implementación

Puede importar perfiles de FHIR a su almacén de FHIR insertando una o varias definiciones de estructura agrupadas en una o varias guías de implementación. Utiliza una definición de estructura para hacer lo siguiente:

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

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

Por ejemplo, supongamos que tu software de terceros debe cumplir la norma final sobre interoperabilidad y acceso de los pacientes de los Centros de Servicios de Medicare y Medicaid (CMS) de EE. UU. Tu software de terceros tendría que proporcionar una API de acceso de pacientes que cumpla los perfiles de CARIN. Puede importar y habilitar la guía de implementación de CARIN en su almacén FHIR para validar los recursos con los perfiles de CARIN. En las secciones siguientes de esta página se describe cómo importar y habilitar guías de implementación.

Una vez que hayas importado tu guía de implementación, puedes habilitarla en tu almacén FHIR para validar los recursos FHIR. Cuando se actualiza o se añade un recurso FHIR al almacén, la API Cloud Healthcare verifica si coincide con una definición de estructura de la guía de implementación. Si el recurso FHIR coincide, se añade al almacén. Si el recurso FHIR no se ajusta a las definiciones de estructura de la guía de implementación, se devuelve un mensaje de error y se rechaza el recurso FHIR.

Medidas para asegurar la validación de datos

La API Cloud Healthcare aplica la validación de datos cuando se usan 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 validación de perfiles

En el siguiente diagrama se muestra el flujo de trabajo de validación para añadir o actualizar recursos FHIR:

Definir perfiles FHIR

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

Descargar los recursos de validación de tu perfil

Para asegurarse de que las definiciones de estructura coincidan con su fuente oficial, debe descargar los recursos de validación de perfil, como las definiciones de estructura, las guías de implementación o los conjuntos de valores, de una fuente externa, como el registro de guías 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 URLs de cada guía de implementación.

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

La API Cloud Healthcare permite validar los siguientes tipos de reglas de definición de estructura:

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

Configurar la guía de implementación

Una vez que hayas descargado las definiciones de estructura, la guía de implementación y el conjunto de valores, debes añadir los perfiles que utiliza la guía de implementación para validar los recursos de FHIR.

Para configurar la guía de implementación, sigue estos pasos:

1. Abre el archivo de la guía de implementación que has descargado de tu proveedor de software externo.

2. Añade la siguiente sección para incluir las definiciones de estructura que se van a validar en tu guía de implementación:

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

   Haz los cambios siguientes:

   • RESOURCE_TYPE: define el tipo de recurso al que se aplica la guía de implementación.
   • STRUCTURE_DEFINITION_URL: la URL de la definición de estructura de la fuente del perfil; por ejemplo, el perfil de paciente de US Core.

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

   En el siguiente ejemplo se muestran los perfiles Patient y Organization habilitados para la guía de implementación de US Core:

   "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"
     },
     ...
   ]
   

Subir la guía de implementación a Cloud Storage

Una vez que hayas editado la guía de implementación, debes subir los siguientes archivos a Cloud Storage:

• Guía de implementación
• Definiciones de estructura
• Conjuntos de valores

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

Para subir tu guía de implementación a Cloud Storage, sigue estos pasos:

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

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

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

2. Para añadir 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

   Haz los cambios siguientes:

   • PATH_TO_IMPLEMENTATION_GUIDE: la ruta a la guía de implementación en tu máquina local
   • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: el segmento y el directorio en los que almacena la guía de implementación en Cloud Storage

Importar la guía de implementación

Para usar la guía de implementación y validar los perfiles de tu almacén FHIR, impórtala a tu almacén FHIR como recurso FHIR.

En los ejemplos siguientes se muestra cómo importar tu guía de implementación a un almacén 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",
  }
}

Subir e importar las dependencias de tu implementación

Antes de habilitar la guía de implementación, debe asegurarse de que se han subido e importado todas las dependencias de la guía. Las dependencias se definen mediante el parámetro dependsOn de la 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 e importar dependencias, sigue las instrucciones de los artículos Subir la guía de implementación a Cloud Storage y Importar la guía de implementación, respectivamente.

Habilitar la guía de implementación

Para usar un recurso de guía de implementación con el 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 Cloud Healthcare intentará validar los perfiles con todas las guías de implementación. Un recurso FHIR solo tiene que coincidir con un perfil de cualquier guía de implementación habilitada.

La API 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 Cloud Healthcare validará la guía de implementación modificada.

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

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

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

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

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

• Selecciona las guías de implementación predeterminadas que proporciona la API Cloud Healthcare.
• Importar una guía de implementación personalizada de Cloud Storage a un almacén 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 añadir manualmente la matriz global al recurso de la guía de implementación. Si decides saltarte este paso, debes añadir el array global cuando crees el paquete de transacciones FHIR en el siguiente paso con otro método, como la herramienta Bundler for FHIR profile validation resources con la marca generate_global_array.

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

   Puede crear el paquete de transacciones con la herramienta Bundler for FHIR profile validation resources (Paquetizador para recursos de validación de perfiles de FHIR).

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

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

   Haz los cambios siguientes:

   • PATH_TO_PROFILE_VALIDATION_BUNDLE: la ruta al paquete de validación del perfil en tu máquina local
   • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: la ubicación de Cloud Storage donde 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 FHIR.

Validar recursos con perfiles específicos

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

Para validar un recurso 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