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](https://docs.cloud.google.com/healthcare-api/docs/how-tos/pubsub.md.txt).

## Overview

You can receive notifications using
[Pub/Sub](https://docs.cloud.google.com/pubsub) when any of the following clinical events occur:

- You store a DICOM instance in a DICOM store using the [`dicomStores.dicomWeb.studies.storeInstances`](https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores.studies/storeInstances.md.txt) method.
- You import a DICOM instance into a DICOM store using the [`dicomStores.import`](https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores/import.md.txt) method.
- A FHIR resource is created, patched, updated, or deleted in a FHIR store. However, notifications are not sent when a FHIR resource is [imported from Cloud Storage](https://docs.cloud.google.com/healthcare-api/docs/how-tos/fhir-import-export.md.txt#importing_fhir_resources).
- 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.

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

For information on using Pub/Sub notifications with DICOM data, see
[DICOM Pub/Sub notifications](https://docs.cloud.google.com/healthcare-api/docs/dicom-pubsub.md.txt).

## FHIR notifications

For information on using Pub/Sub notifications with FHIR data,
see [FHIR Pub/Sub notifications](https://docs.cloud.google.com/healthcare-api/docs/fhir-pubsub.md.txt).

## HL7v2 notifications

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

![hl7v2_pubsub](https://docs.cloud.google.com/static/healthcare-api/images/hl7v2_pubsub.png)

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. These values can be used to filter which events a client receives by [filtering messages
  from a subscription](https://docs.cloud.google.com/pubsub/docs/subscription-message-filter).
- **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:

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

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

```bash
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](https://www.hl7.org/special/committees/vocab/V26_Appendix_A.pdf). | `ADT` | The type of HL7v2 message that was created or ingested. |

## What's next

- Read the [Pub/Sub documentation](https://docs.cloud.google.com/pubsub/docs.md.txt).
- For an in-depth explanation of Pub/Sub, see [What is Cloud Pub/Sub?](https://docs.cloud.google.com/pubsub/docs/overview.md.txt)