Pub/Sub notifications

This page provides an overview of using Pub/Sub to receive notifications when clinical events occur in a Cloud Healthcare API data store. To learn how to set up and use Pub/Sub messages, see Configuring Pub/Sub notifications.

Overview

You can receive notifications using Pub/Sub when any of the following clinical events occur:

  • A DICOM instance is stored in a DICOM store
  • A FHIR resource is created, updated, or deleted in a FHIR store. However, notifications are not sent when a FHIR resource is imported from Cloud Storage.
  • An HL7v2 message is ingested or created in an HL7v2 store

Information about each event is added to the corresponding data store's Pub/Sub topic in the form of a message.

These messages do not contain any personal information. They only include the following:

  • The project for which the message is generated
  • The message ID
  • In FHIR messages, the FHIR resource type and action that caused the message
  • In HL7v2 messages, the HL7v2 message type

You can publish messages to any Pub/Sub topic in any project for which you have sufficient permissions. After the Pub/Sub topic receives the message, the message will be forwarded to any number of subscribers to the topic.

DICOM notifications

The following diagram shows the flow of notifications that occur when a DICOM instance is stored:

dicom_pubsub

  1. A dicomStores.dicomWeb.studies.storeInstances request is made to store a DICOM instance.
  2. The DICOM store receives the instance and then creates and sends a message to its Pub/Sub topic.
  3. In the case of bulk import, a dicomStores.import request is made to bulk import DICOM files from Cloud Storage to a DICOM store.
  4. If the sendForBulkImport object is set to TRUE, the DICOM store receives the instance and then creates and sends a message to its Pub/Sub topic.
  5. Pub/Sub forwards the message to the topic's subscriptions.
  6. The subscribers receive a notification, in the form of a Pub/Sub message, from their subscription. Each subscription can have one or more subscribers for increased parallelism.

FHIR notifications

The following diagram shows the flow of notifications that occur when a FHIR resource is created, updated, or deleted:

fhir_pubsub

  1. A fhirStores.fhir.update API request is made to edit a FHIR resource.
  2. The FHIR store containing the resource creates and sends a Pub/Sub message to the store's Pub/Sub topic.
  3. Pub/Sub forwards the message to the topic's subscriptions.
  4. The subscribers receive a notification, in the form of a Pub/Sub message, from their subscription. Each subscription can have one or more subscribers for increased parallelism.

HL7v2 notifications

The following diagram shows the flow of notifications that occur when an HL7v2 message is ingested or created:

hl7v2_pubsub

  1. The Cloud Healthcare API ingests an HL7v2 message from a care system.
  2. The message is stored in an HL7v2 store.
  3. The HL7v2 store creates and sends a Pub/Sub message to the store's Pub/Sub topics that have a filter that matches the HL7v2 message.
  4. Pub/Sub forwards the Pub/Sub message to the topics' subscriptions.
  5. The subscribers receive a notification, in the form of a Pub/Sub message, from their subscription. Each subscription can have one or more subscribers for increased parallelism.

Notification format

Notifications sent to a Pub/Sub topic consist of two parts:

  • Attributes: A set of key:value pairs describing the event.
  • Data: A string that contains an identifier for the relevant FHIR resource, DICOM instance, or HL7v2 message.

DICOM instance data

When a DICOM instance is stored in a DICOM store, the following identifier is always included in the data field of the Pub/Sub message:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID

Notifications for a stored DICOM instance do not contain any attribute values.

FHIR resource data and attributes

Changes to FHIR resources always contain the following identifier in the data field of the Pub/Sub message:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/resources/RESOURCE_TYPE/RESOURCE_ID

The following set of key:value pairs is always included in the message's attributes field:

Attribute name Possible values Example Description
action
  • CreateResource
  • UpdateResource
  • DeleteResource
CreateResource The type of event that just occurred.
resourceType Any FHIR resource type. Patient The type of resource that was modified.

HL7v2 message data and attributes

When an HL7v2 message is created or ingested into an HL7v2 store, the following identifier is always included in the data field of the Pub/Sub message:

projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages/HL7V2_MESSAGE_ID

The following set of key:value pairs is always included in the Pub/Sub message's attributes field:

Attribute name Possible values Example Description
msgType Any HL7v2 message type. ADT The type of HL7v2 message that was created or ingested.

What's next