Flujo de trabajo de suscripción de FHIR R6

Cree un tema de suscripción y una suscripción de FHIR R6, configure una autorización de bloqueo de REST opcional, complete el establecimiento de comunicación, reciba notificaciones de eventos y recupere el estado de la suscripción.

Visión General de Flujo de Trabajo

DDFS admite la entrega de notificaciones de bloqueo de REST para suscripciones FHIR R6. Cada punto final de notificación debe ser una URL HTTPS enrutable públicamente que utilice el puerto 443.

Utilice https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r6-ballot4 como la URL base de la boleta electoral 4 de FHIR R6, sustituyendo los marcadores de posición de instancia y región por los valores de la instancia de DDFS.

  1. Cree un SubscriptionTopic activo que defina los eventos y filtros de recursos.
  2. Si el punto final necesita una cabecera Authorization saliente, cree un secreto de OCI Vault y otorgue permiso a la instancia de DDFS para leerlo.
  3. Cree un Subscription con el estado requested que haga referencia al tema activo e identifique el punto final de bloqueo de REST.
  4. DDFS devuelve la suscripción creada y, a continuación, envía la solicitud de establecimiento de comunicación. La respuesta create no confirma el éxito del establecimiento de comunicación.
  5. Un establecimiento de comunicación correcto cambia el estado de la Suscripción a active. Un establecimiento de comunicación fallido lo cambia a error.
  6. Después de la activación, los eventos de recursos coincidentes provocan solicitudes de notificación de eventos.
  7. Utilice la operación de nivel de tipo o de instancia $status para recuperar el estado actual.
RecursoFinalidad en DDFS
SubscriptionTopicDefine el tema de evento, el recurso de disparador, los criterios de disparador opcionales y los filtros que pueden utilizar las suscripciones.
SubscriptionSolicita notificaciones de bloqueo de REST para un tema.
SubscriptionStatusIndica el estado mediante las operaciones Subscription/$status de nivel de tipo y de instancia y aparece en los paquetes de notificaciones de bloqueo de REST.

Crear un tema de suscripción

Use Crear tema de suscripción para crear el tema antes de crear una suscripción. El tema debe ser active para que una suscripción pueda hacer referencia a él.

{
  "resourceType": "SubscriptionTopic",
  "url": "https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r6-ballot4/SubscriptionTopic/device-create",
  "status": "active",
  "title": "Device create events",
  "trigger": [
    {
      "resource": "Device",
      "supportedInteraction": [
        "create"
      ],
      "canFilterBy": [
        {
          "resource": "Device",
          "filterParameter": "manufacturer"
        }
      ]
    }
  ]
}

En este ejemplo, device-create es un nombre definido por el cliente dentro del canónico url del tema. No es el ID de recurso de DDFS. DDFS asigna el ID de recurso cuando crea el tema; utilice el ID devuelto en las URL de solicitud de lectura, actualización y supresión.

  • Utilice una URL canónica estable y absoluta bajo un espacio de nombres que controle. Seleccione un valor que identifique globalmente el tema.
  • Las URL canónicas son sensibles a mayúsculas/minúsculas. Evite espacios, barras verticales (|) y caracteres hash (#).
  • Se recomienda utilizar un nombre corto en minúscula con palabras separadas por guiones, como device-create, para facilitar la lectura; DDFS no asigna un significado especial a ese patrón de nomenclatura.
  • Los estados de tema soportados son draft, active, retired y unknown. Una suscripción solo puede hacer referencia a un tema activo.
  • Cada disparador debe identificar un recurso soportado.
  • trigger.queryCriteria.previous y trigger.queryCriteria.current, cuando están presentes, deben utilizar criterios de búsqueda de estilo FHIR soportados.
  • Todos los filtros declarados en trigger.canFilterBy deben estar soportados para el recurso disparador.
  • Utilice versionAlgorithmString o versionAlgorithmCoding. Un tema no puede contener ambas alternativas.
  • Los recursos, los parámetros de búsqueda o los valores de campo no soportados se rechazan con OperationOutcome.

Criterios de consulta cuando no existe un estado de recurso

En trigger.queryCriteria, previous prueba el estado del recurso antes de una interacción y current prueba su estado después de la interacción. Una creación no tiene estado anterior y una supresión no tiene estado actual. Utilice los siguientes campos para especificar cómo se evalúa la prueba correspondiente:

  • resultForCreate especifica si la prueba de estado anterior se aprueba o falla para una creación.
  • resultForDelete especifica si la prueba de estado actual se aprueba o falla para una supresión.

Para cualquiera de los campos, utilice test-passes para aprobar una prueba o test-fails para una prueba con fallos. Especifique el valor explícitamente cuando el flujo de trabajo dependa de este comportamiento; no asuma un resultado cuando se omite el campo.

El siguiente fragmento queryCriteria se puede colocar en un disparador de observación. Prueba status=final en cualquiera de los estados y falla explícitamente la prueba para un estado que no existe.

{
  "queryCriteria": {
    "previous": "status=final",
    "resultForCreate": "test-fails",
    "current": "status=final",
    "resultForDelete": "test-fails",
    "requireBoth": false
  }
}

Con requireBoth=false, cualquiera de las pruebas de estado puede cumplir los criterios de consulta. Defina requireBoth=true cuando se deban aprobar ambas pruebas. Configure el supportedInteraction del disparador para las interacciones que debe supervisar el tema.

Consulte las definiciones de criterios de consulta de boleta 4 de FHIR R6.

Declarar filtros permitidos y valores de filtro de suministro

trigger.canFilterBy de un tema declara qué filtros puede utilizar una suscripción. filterBy de la suscripción proporciona un valor para un filtro declarado. Una declaración de filtro no necesita un ID de recurso concreto.

Por ejemplo, coloque este fragmento en un disparador de observación para permitir el filtrado por dispositivo:

{
  "canFilterBy": [
    {
      "resource": "Observation",
      "filterParameter": "device"
    }
  ]
}

Una suscripción que haga referencia a este tema puede proporcionar el valor de filtro correspondiente. Coloque el siguiente fragmento en la raíz de suscripción, sustituyendo la referencia de dispositivo de ejemplo por la referencia utilizada por las observaciones que desea confrontar:

{
  "filterBy": [
    {
      "resource": "Observation",
      "filterParameter": "device",
      "value": "Device/11111111-2222-3333-4444-555555555555"
    }
  ]
}

Estos fragmentos son parte de un tema y una suscripción, no completan las solicitudes de creación. Incluya los demás campos obligatorios descritos en este flujo de trabajo.

Parámetros de filtro de tema soportados

Los siguientes parámetros canFilterBy están soportados para los recursos de disparador SubscriptionTopic. Los parámetros de recurso base _id y _tag se pueden aplicar entre los recursos.

Disparar recursoParámetros de filtro soportados
Device_id, _tag, identifier, manufacturer, model, status, type
DeviceAssociation_id, _tag, device, patient, status, subject
Encounter_id, _tag, class, location, patient, status, type
Location_id, _tag, status
Observation_id, _tag, category, code, device, encounter, patient, status
Patient_id, _tag, identifier
Practitioner_id, _tag, identifier

El soporte del modificador es intencionalmente estrecho. Los filtros de cadena de dispositivo manufacturer y model admiten :exact. El recurso _tag soporta :not. La mayoría de los filtros de referencia y token no admiten modificadores.

Configurar autorización de notificación

Si el punto final de bloqueo de REST necesita una cabecera Authorization saliente, almacene el valor de cabecera completo en un secreto de OCI Vault. Otorgue permiso a la instancia de DDFS para leer ese secreto específico y agregue la extensión del secreto a la suscripción.

Para conocer el contrato de extensión y el fragmento, consulte FHIR R6 Subscription OCI Vault Secret Extension. Para conocer la política de principal de recursos necesaria, consulte Otorgamiento de acceso de DDFS a un secreto de autorización de suscripción.

Omita la extensión cuando el punto final no necesite una cabecera Authorization saliente.

Creación de una Suscripción

Use Crear suscripción para crear una suscripción de FHIR R6 que haga referencia al tema activo.

Campo de suscripciónComportamiento de DDFS
statusDebe ser requested al crear. Los clientes no pueden definir active directamente.
topicDebe ser una URL con formato correcto que se resuelva en un SubscriptionTopic activo existente.
channelTypeDebe incluir rest-hook. Se rechazan otros tipos de canal.
endpointNecesario para la entrega de REST-hook; debe ser una URL HTTPS enrutable públicamente que utilice el puerto 443.
contentTypeUtilice application/fhir+json para que DDFS envíe un paquete de notificaciones FHIR R6 en el cuerpo de la solicitud.
contentOpcional. Los valores soportados son empty y id-only. Se ha rechazado full-resource.
filterByOpcional. Cada filtro debe ser declarado por un disparador de tema coincidente y soportado para ese recurso de disparador.
heartbeatPeriod, timeout y maxCountOpcional. DDFS conserva los valores válidos mediante operaciones de creación, lectura y actualización. Se rechazan los valores fuera de la representación de entero de FHIR admitida.
parameterCabeceras de salida opcionales. Se rechazan las cabeceras HTTP restringidas.
Extensión de secreto de OCI VaultExtensión de nivel raíz opcional. Una suscripción puede contener como máximo una instancia.

Configure los campos de la tabla anterior para los requisitos de tema, receptor y autorización. Valide que el receptor HTTPS esté listo para aceptar el establecimiento de comunicación antes de crear una suscripción de producción.

Filtros de suscripción

Cada entrada Subscription.filterBy debe utilizar un filtro declarado por un disparador coincidente en el SubscriptionTopic al que se hace referencia. El filtro también se debe admitir para ese recurso disparador. Si ningún disparador soporta los filtros proporcionados, se rechaza la suscripción.

Una entrada filterBy puede contener uno o más valores de CodeableConcept event. DDFS conserva varios valores de eventos en el pedido proporcionado.

Requisitos de cabecera y punto final de REST-hook

  • El URI de punto final debe ser absoluto y no opaco.
  • El esquema de punto final debe ser https y el punto final debe utilizar el puerto 443.
  • El punto final debe incluir un host y resolverlo en una dirección enrutable públicamente.
  • Los nombres de cabecera en Subscription.parameter deben ser nombres de token HTTP válidos.
  • Los valores de cabecera deben estar presentes y no deben contener caracteres CR o LF.
  • Hop-by-hop, proxy, enrutamiento, contenido, cookies y encabezados relacionados con la autorización están bloqueados.
  • Los nombres de cabecera que empiecen por x-forwarded- están bloqueados.
  • Authorization no se debe proporcionar mediante Subscription.parameter.

Entrega de notificaciones de eventos y establecimiento de comunicación

Después de devolver la suscripción creada, DDFS envía una solicitud de establecimiento de comunicación HTTP POST al punto final. Las entradas Subscription.parameter soportadas se copian como cabeceras de salida. Cuando se configura, la extensión de OCI Vault proporciona la cabecera Authorization saliente.

Con contentType=application/fhir+json, el cuerpo de la solicitud es un paquete FHIR R6 con type=subscription-notification. El paquete contiene un recurso SubscriptionStatus con type=handshake.

Cualquier respuesta de establecimiento de comunicación 2xx cambia el estado de la Suscripción a active. Un fallo de respuesta de solicitud-preparación, resolución secreta, transporte o no 2xx cambia el estado a error. DDFS no sigue redirecciones.

Después de la activación, un evento de recurso coincidente provoca una notificación de evento HTTP POST. Su paquete de notificaciones contiene SubscriptionStatus.type=event-notification. Una notificación posterior incorrecta es un fallo de entrega; no es otra transición de estado de establecimiento de comunicación.

Recuperar estado de suscripción

Utilice GET /api/fhir/r6-ballot4/Subscription/$status para recuperar el estado de las suscripciones o GET /api/fhir/r6-ballot4/Subscription/{rid}/$status para recuperar el estado de una suscripción. La operación de nivel de tipo acepta parámetros opcionales status y id; repita id para solicitar varios ID lógicos.

Autorice la operación de nivel de tipo con permiso de búsqueda de suscripción y la operación de nivel de instancia con permiso de lectura de suscripción. Otorgue y solicite ddfssystem/Subscription.s o ddfssystem/Subscription.r, respectivamente; los tokens emitidos utilizan el ámbito system/Subscription.s o system/Subscription.r correspondiente. No se requiere un ámbito SubscriptionStatus independiente. Un token sin el permiso de suscripción necesario recibe HTTP 403. Los ámbitos de suscripción parametrizados siguen restringiendo los resultados autorizados.

Estas operaciones devuelven un paquete de conjunto de búsqueda FHIR. Cada entrada coincidente tiene un valor fullUrl y contiene un valor SubscriptionStatus con la referencia de suscripción, el tema, el estado actual, type=query-status y eventsSinceSubscriptionStart. Un resultado puede informar status=error sin un elemento error. SubscriptionStatus es un resultado de operación, no un recurso CRUD gestionado por separado.

Resultados esperados

EscenarioResultado esperado
Tema activo y suscripción solicitada válidaLa suscripción se crea con el estado requested y el establecimiento de comunicación se intenta de forma asíncrona.
El Tema no está activoSe ha rechazado la suscripción.
content es empty o id-onlyLa suscripción puede ser aceptada.
content es full-resourceSe ha rechazado la suscripción.
El punto final utiliza HTTP, no es enrutable públicamente o no utiliza el puerto 443Se ha rechazado la suscripción.
Subscription.parameter contiene AuthorizationLa suscripción se ha rechazado; utilice la extensión de OCI Vault.
La extensión de OCI Vault está presente sin valueStringSe ha rechazado la suscripción.
El establecimiento de comunicación recibe una respuesta 2xxEl estado de la Suscripción pasa a ser active.
Falla la preparación o entrega del establecimiento de comunicaciónEl estado de la Suscripción pasa a ser error.
No se ha realizado correctamente una notificación de evento posteriorLa notificación de evento es un fallo de entrega.