Configuring Cloud Pub/Sub notifications

You can receive notifications when clinical events occur in Cloud Healthcare API data stores using Pub/Sub. These notifications inform you when:

  • A DICOM instance is stored in a DICOM store
  • A FHIR resource is created, updated, or deleted in a FHIR store
  • An HL7v2 message is ingested or created in an HL7v2 store

When one of these events occurs, the Cloud Healthcare API publishes a message to a named Pub/Sub resource called a topic. The message can then be received by applications subscribed to the topic.

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 resourceType and action that caused the message
  • In HL7v2 messages, the HL7v2 message type

For an overview of using Pub/Sub notifications with the Cloud Healthcare API, see Pub/Sub notifications.

Prerequisites

Before using this feature, complete the following sections:

Enable the Pub/Sub API

To enable the Pub/Sub API, click the following button:

Enable the API

Configure Pub/Sub permissions

To allow messages to be published from the Cloud Healthcare API to Pub/Sub, you must add the pubsub.publisher role to your project's Cloud Healthcare Service Agent service account. See DICOM, FHIR, and HL7v2 store Pub/Sub permissions for steps to add the required role.

Create a Pub/Sub topic

For each data store for which you want to receive notifications, you must configure a Pub/Sub topic. Individual data stores can have their own Pub/Sub topic, or multiple data stores can share the same topic. You can create a topic using the Google Cloud Console or the gcloud command-line tool.

When you create a topic, or refer to a topic in a data store's configuration, you need to use a qualified URI in the following format:

projects/PROJECT_ID/topics/TOPIC_NAME

where PROJECT_ID is your Google Cloud project ID and TOPIC_NAME is the name of the topic.

To create a topic, complete the following steps:

Console

  1. Go to the Pub/Sub Topics page in the Cloud Console.

    Go to the Pub/Sub topics page

  2. Click Create Topic.

  3. Enter a topic name with the URI:

    projects/PROJECT_ID/topics/TOPIC_NAME

    where PROJECT_ID is your Google Cloud project ID.

  4. Click Create.

gcloud

To create a topic, run the gcloud pubsub topics create command:

gcloud pubsub topics create projects/PROJECT_ID/topics/TOPIC_NAME

If the request is successful, the command returns the following output:

Created topic [projects/PROJECT_ID/topics/TOPIC_NAME].

Create a Pub/Sub subscription

To receive messages published to a topic, you need to create a Pub/Sub subscription. Every Pub/Sub topic should have at least one Pub/Sub subscription.

The subscription connects the topic to a subscriber application that receives and processes messages published to the topic.

Subscriptions can be configured to use a push model or a pull model.

To create a subscription, complete the following steps:

Console

  1. Go to the Pub/Sub Topics page in the Cloud Console.

    Go to the Pub/Sub topics page

  2. Click your project's topic.

  3. Click Create Subscription.

  4. Enter a subscription name:

    projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME

    Leave Delivery Type set to Pull.

  5. Click Create.

gcloud

To create a topic, run the gcloud pubsub subscriptions create command:

gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

If the request is successful, the command returns the following output:

Created subscription [projects/PROJECT_ID/subscriptions/TOPIC_NAME].

DICOM instances

The DicomStore resource contains a notificationConfig object where you can specify a Pub/Sub topic.

When a DICOM instance is stored in a DICOM store, even if the DICOM instance already exists, the Cloud Healthcare API publishes a message to the DICOM store's Pub/Sub topic.

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. 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.

To view a notification for a stored DICOM instance, complete the following steps:

  1. Create or edit a DICOM store and configure it with a Pub/Sub topic.
  2. Add the required pubsub.publisher role to your project's service account.
  3. Store an instance in the DICOM store. This triggers the Cloud Healthcare API to publish a message to the configured Pub/Sub topic.
  4. Run the gcloud pubsub subscriptions pull command to view the message published to the Pub/Sub topic:

    gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
    

    The command returns the following output about the DICOM instance that was stored:

    ┌----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------┐
    |                                                                          DATA                                                                           |    MESSAGE_ID   | ATTRIBUTES |
    ├---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|------------|
    | projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID | 123456789012345 |            |
    └----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------┘
    

FHIR resources

The FhirStore resource contains a notificationConfig object where you can specify a Pub/Sub topic.

When a FHIR resource is created, updated, or deleted in a FHIR store, the Cloud Healthcare API publishes a message to the FHIR store's Pub/Sub topic.

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.

To view a notification for a created FHIR resource, complete the following steps:

  1. Create or edit a FHIR store and configure it with a Pub/Sub topic.
  2. Add the required pubsub.publisher role to your project's service account.
  3. Create a FHIR resource in the FHIR store. This triggers the Cloud Healthcare API to publish a message to the configured Pub/Sub topic.
  4. Run the gcloud pubsub subscriptions pull command to view the message published to the Pub/Sub topic:

    gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
    

    The command returns the following output about the created FHIR resource:

    ┌----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------┐
    |                                                      DATA                                                      |    MESSAGE_ID   |       ATTRIBUTES      |
    ├----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------|
    | projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/resources/Patient/PATIENT_ID | 123456789012345 | action=CreateResource |
    |                                                                                                                |                 | resourceType=Patient  |
    └----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------┘
    

HL7v2 messages

The Hl7V2Store resource contains an array notificationConfigs where you can specify Pub/Sub topics and filtering criteria.

When an HL7v2 message is ingested or created in an HL7v2 store, the Cloud Healthcare API publishes a message to the Pub/Sub topics that have a filter that matches the HL7v2 message.

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.

To view a notification for an ingested HL7v2 message, complete the following steps:

  1. Create or edit an HL7v2 store and configure it with a Pub/Sub topic.
  2. Add the required pubsub.publisher role to your project's service account.
  3. Ingest an HL7v2 message into the HL7v2 store. This triggers the Cloud Healthcare API to publish a message to the configured Pub/Sub topic.
  4. To view the message published to the Pub/Sub topic, run the gcloud pubsub subscriptions pull command:

    gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
    

    The command returns the following output about the ingested HL7v2 message:

    ┌--------------------------------------------------------------------------------------------------------------------|-----------------|---------------┐
    |                                                                 DATA                                               |    MESSAGE_ID   |   ATTRIBUTES  |
    ├--------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
    | projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages/HL7V2_MESSAGE_ID | 123456789012345 | msgType=TYPE  |
    └--------------------------------------------------------------------------------------------------------------------|-----------------|---------------┘
    

Troubleshooting missed Pub/Sub messages

If a notification can't be published to Pub/Sub, an error is logged to Cloud Logging. For more information, see Viewing error logs in Cloud Logging.

If the rate of error generation exceeds a limit, errors in excess of this limit aren't submitted to Cloud Logging.

What's next

Learn how to configure a Pub/Sub topic in: