Configuring 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:

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

View DICOM notifications

The DicomStore resource contains a notificationConfig object where you can specify a Pub/Sub topic. Optionally, the notificationConfig object also allows you to indicate whether or not Pub/Sub notifications should be sent during bulk import. This field is only available in the v1beta1 version.

When you store a new DICOM instance in a DICOM store, the Cloud Healthcare API publishes a message to the DICOM store's Pub/Sub topic.

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. Optionally, indicate whether Pub/Sub notifications should be sent during bulk import (this feature is only available in the v1beta1 API).
  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 |            |
    └----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------┘
    

View FHIR notifications

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.

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  |
    └----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------┘
    

View HL7v2 notifications

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.

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: