You can export HL7v2 messages to Pub/Sub for downstream processing.
Suppose you have a Dataflow pipeline that transforms HL7v2 messages
when new messages are ingested into an HL7v2 store. The pipeline reads from a
Pub/Sub subscription and waits for notifications of new HL7v2
messages. When you import HL7v2 messages into an HL7v2 store using thehl7V2Stores.importmethod, the method doesn't sendPub/Sub notifications.
To trigger the pipeline, import the HL7v2 messages and then use thehl7v2Stores.exportmethod to export them to Pub/Sub.
Before you begin
Enable the Pub/Sub API
In the Google Cloud console, enable the Pub/Sub API:
You can specify the following filter parameters as your filter criteria in thefilterfield. To learn the filter
syntax and construct queries, seeQuery strings.
message_type: from the MSH.9.1 field. For example,NOT message_type = "ADT".
send_date: theYYYY-MM-DDdate the message was sent from the MSH.7 segment, specified in the time zone of the dataset. For example,send_date < "2017-01-02".
send_time: the timestamp when the message was sent. This parameter is from
the MSH.7 segment of the message. This parameter uses theRFC 3339time format for comparisons.
For example,send_time < "2017-01-02T00:00:00-05:00".
create_time: the timestamp when the message was created in the Cloud Healthcare API, using the RFC 3339 time format for comparisons.
For example:create_time < "2017-01-02T00:00:00-05:00".
send_facility: the care center that the message came from, from the MSH.4 segment. For example,send_facility = "ABC".
The following samples show how to specify a filter to only export HL7v2 messages
of typeADT.
To view the exported HL7v2 messages in Pub/Sub,
run thegcloud pubsub subscriptions pullcommand. The command uses the--format=jsonflag to return the output as JSON instead of the default YAML.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis guide outlines how to export HL7v2 messages from an HL7v2 store to Pub/Sub for downstream processing using the \u003ccode\u003ehl7V2Stores.export\u003c/code\u003e method, which is necessary to trigger Dataflow pipelines when importing messages, as the \u003ccode\u003ehl7V2Stores.import\u003c/code\u003e method does not send Pub/Sub notifications.\u003c/p\u003e\n"],["\u003cp\u003eBefore exporting, users must enable the Pub/Sub API, configure the necessary Pub/Sub permissions by adding the \u003ccode\u003epubsub.publisher\u003c/code\u003e role to the Cloud Healthcare Service Agent service account, and create a Pub/Sub topic.\u003c/p\u003e\n"],["\u003cp\u003eTo export messages, a \u003ccode\u003ePOST\u003c/code\u003e request must be made, specifying the parent dataset name, HL7v2 store name, and the destination Pub/Sub topic in the request body.\u003c/p\u003e\n"],["\u003cp\u003eThe export process returns an operation name that can be used to track the status of the export using the Operation \u003ccode\u003eget\u003c/code\u003e method, and it can use filters such as \u003ccode\u003emessage_type\u003c/code\u003e, \u003ccode\u003esend_date\u003c/code\u003e, \u003ccode\u003esend_time\u003c/code\u003e, \u003ccode\u003ecreate_time\u003c/code\u003e, and \u003ccode\u003esend_facility\u003c/code\u003e to narrow down what messages to export.\u003c/p\u003e\n"],["\u003cp\u003eOnce exported, HL7v2 messages can be viewed in Pub/Sub using the \u003ccode\u003egcloud pubsub subscriptions pull\u003c/code\u003e command, returning output in JSON format.\u003c/p\u003e\n"]]],[],null,["# Export HL7v2 messages to Pub/Sub\n\nThis page describes how to export HL7v2 messages to Pub/Sub using the\n[`projects.locations.datasets.hl7V2Stores.export`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores/export)\nmethod.\n\nYou can export HL7v2 messages to Pub/Sub for downstream processing.\nSuppose you have a Dataflow pipeline that transforms HL7v2 messages\nwhen new messages are ingested into an HL7v2 store. The pipeline reads from a\nPub/Sub subscription and waits for notifications of new HL7v2\nmessages. When you import HL7v2 messages into an HL7v2 store using the\n[`hl7V2Stores.import`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores/import)\nmethod, the method doesn't send [Pub/Sub notifications](/healthcare-api/docs/how-tos/pubsub).\nTo trigger the pipeline, import the HL7v2 messages and then use the\n`hl7v2Stores.export` method to export them to Pub/Sub.\n\nBefore you begin\n----------------\n\n### Enable the Pub/Sub API\n\nIn the Google Cloud console, enable the Pub/Sub API:\n\n[Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=pubsub)\n\n### Configure Pub/Sub permissions\n\nTo export messages from an HL7v2 store to Pub/Sub, you must add\nthe `pubsub.publisher` role to your project's **Cloud Healthcare Service Agent**\n[service account](/iam/docs/service-accounts).\nSee [DICOM, FHIR, and HL7v2 store Pub/Sub permissions](/healthcare-api/docs/how-tos/permissions-healthcare-api-gcp-products#dicom_fhir_and_hl7v2_store_cloud_pubsub_permissions)\nfor steps to add the required role.\n\n### Create a Pub/Sub topic\n\nTo create a topic, see [Create a topic](/pubsub/docs/create-topic#create_a_topic).\n\nIndividual data stores can have\ntheir own Pub/Sub topic, or multiple data stores can share the\nsame topic.\n\nUse the following format when specifying the Pub/Sub topic: \n\n```bash\nprojects/PROJECT_ID/topics/TOPIC_NAME\n```\n\n\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e is your Google Cloud project ID and\n\u003cvar translate=\"no\"\u003eTOPIC_NAME\u003c/var\u003e is the name of the Pub/Sub topic.\n\nExport HL7v2 messages to Pub/Sub\n--------------------------------\n\n### curl\n\nTo export HL7v2 messages to Pub/Sub, make a `POST` request and\nspecify the following information:\n\n- The name of the parent dataset\n- The name of the HL7v2 store\n- The destination Pub/Sub topic\n\nThe following sample shows a `POST` request using `curl`. \n\n```bash\ncurl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth application-default print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n --data \"{\n 'pubsubDestination': {\n 'pubsubTopic': 'projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/topics/\u003cvar translate=\"no\"\u003ePUBSUB_TOPIC\u003c/var\u003e'\n }\n }\" \"https://healthcare.googleapis.com/v1/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/locations/\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e/datasets/\u003cvar translate=\"no\"\u003eDATASET_ID\u003c/var\u003e/hl7V2Stores/\u003cvar translate=\"no\"\u003eHL7V2_STORE_ID\u003c/var\u003e:export\"\n```\n\nIf the request is successful, the server returns the response in JSON format: \n\n```\n{\n \"name\": \"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID\"\n}\n```\n\nThe response contains an operation name. To track the status of the operation,\nyou can use the\n[Operation `get` method](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.operations/get): \n\n```bash\ncurl -X GET \\\n -H \"Authorization: Bearer $(gcloud auth application-default print-access-token)\" \\\n \"https://healthcare.googleapis.com/v1/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/locations/\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e/datasets/\u003cvar translate=\"no\"\u003eDATASET_ID\u003c/var\u003e/operations/\u003cvar translate=\"no\"\u003eOPERATION_ID\u003c/var\u003e\"\n```\n\nIf the request is successful, the server returns a response with the status of\nthe operation in JSON format: \n\n```\n{\n \"name\": \"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID\",\n \"metadata\": {\n \"@type\": \"type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata\",\n \"apiMethodName\": \"google.cloud.healthcare.v1.hl7v2.Hl7V2Service.ExportMessages\",\n \"createTime\": \"CREATE_TIME\",\n \"endTime\": \"END_TIME\",\n \"counter\": {\n \"success\": \"RESOURCE_COUNT\"\n }\n },\n \"done\": true,\n \"response\": {\n \"@type\": \"type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ExportMessagesResponse\"\n }\n}\n```\n\n\u003cbr /\u003e\n\n### Export a subset of HL7v2 messages using a filter\n\nYou can use the following fields in your filter criteria:\n\n- [`startTime`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores/export#body.request_body.FIELDS.start_time)\n- [`endTime`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores/export#body.request_body.FIELDS.end_time).\n\nYou can specify the following filter parameters as your filter criteria in the [`filter`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores/export#body.request_body.FIELDS.filter)\nfield. To learn the filter\nsyntax and construct queries, see\n[Query strings](/appengine/docs/standard/python/search/query_strings).\n\n- `message_type`: from the MSH.9.1 field. For example, `NOT message_type = \"ADT\"`.\n- `send_date`: the `YYYY-MM-DD` date the message was sent from the MSH.7 segment, specified in the time zone of the dataset. For example, `send_date \u003c \"2017-01-02\"`.\n- `send_time`: the timestamp when the message was sent. This parameter is from the MSH.7 segment of the message. This parameter uses the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) time format for comparisons. For example, `send_time \u003c \"2017-01-02T00:00:00-05:00\"`.\n- `create_time`: the timestamp when the message was created in the Cloud Healthcare API, using the RFC 3339 time format for comparisons. For example: `create_time \u003c \"2017-01-02T00:00:00-05:00\"`.\n- `send_facility`: the care center that the message came from, from the MSH.4 segment. For example, `send_facility = \"ABC\"`.\n\n| **Note:** Filtering with `startTime` and `endTime` is more efficient than specifying a filter using `send_time`. A filter created using the `startTime` and `endTime` fields defines a range of HL7v2 messages to which the filter is applied. A `send_time` filter only applies to HL7v2 messages with the exact send time.\n\nThe following samples show how to specify a filter to only export HL7v2 messages\nof type `ADT`. \n\n### curl\n\n```bash\ncurl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth application-default print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n --data \"{\n 'pubsubDestination': {\n 'pubsubTopic': 'projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/topics/\u003cvar translate=\"no\"\u003ePUBSUB_TOPIC\u003c/var\u003e'\n },\n 'filter': 'message_type = \\\"ADT\\\"'\n }\" \"https://healthcare.googleapis.com/v1/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/locations/\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e/datasets/\u003cvar translate=\"no\"\u003eDATASET_ID\u003c/var\u003e/hl7V2Stores/\u003cvar translate=\"no\"\u003eHL7V2_STORE_ID\u003c/var\u003e:export\"\n```\n\n\u003cbr /\u003e\n\n### View exported HL7v2 messages in Pub/Sub\n\nTo view the exported HL7v2 messages in Pub/Sub,\nrun the [`gcloud pubsub subscriptions pull`](/sdk/gcloud/reference/pubsub/subscriptions/pull)\ncommand. The command uses the `--format=json` flag to return the output as JSON instead of the default YAML. \n\n```bash\ngcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION \\\n --format=json\n```\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e is the ID of your Google Cloud project\n- \u003cvar translate=\"no\"\u003ePUBSUB_SUBSCRIPTION\u003c/var\u003e is the subscription attached to the Pub/Sub topic where you exported HL7v2 messages\n\nThe output is the following: \n\n```\n[\n {\n \"ackId\": \"ACK_ID\",\n \"message\": {\n \"attributes\": {\n \"msgType\": \"TYPE\"\n },\n \"data\": \"DATA\",\n \"messageId\": \"8076570784126536\",\n \"publishTime\": \"YYYY-MM-DDTHH:MM:SS+ZZ:ZZ\"\n }\n }\n]\n```"]]
