Export HL7v2 messages to Pub/Sub

This page describes how to export HL7v2 messages to Pub/Sub using the projects.locations.datasets.hl7V2Stores.export method.

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 the hl7V2Stores.import method, the method doesn't send Pub/Sub notifications. To trigger the pipeline, import the HL7v2 messages and then use the hl7v2Stores.export method to export them to Pub/Sub.

Before you begin

Enable the Pub/Sub API

In the Google Cloud console, enable the Pub/Sub API:

Enable the API

Configure Pub/Sub permissions

To export messages from an HL7v2 store 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

To create a topic, see Create a topic.

Individual data stores can have their own Pub/Sub topic, or multiple data stores can share the same topic.

Use the following format when specifying the Pub/Sub topic:

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID is your Google Cloud project ID and TOPIC_NAME is the name of the Pub/Sub topic.

Export HL7v2 messages to Pub/Sub

curl

To export HL7v2 messages to Pub/Sub, make a POST request and specify the following information:

• The name of the parent dataset
• The name of the HL7v2 store
• The destination Pub/Sub topic

The following sample shows a POST request using curl.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'pubsubDestination': {
        'pubsubTopic': 'projects/PROJECT_ID/topics/PUBSUB_TOPIC'
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export"

If the request is successful, the server returns the response in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

The response contains an operation name. To track the status of the operation, you can use the Operation get method:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

If the request is successful, the server returns a response with the status of the operation in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.hl7v2.Hl7V2Service.ExportMessages",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "counter": {
      "success": "RESOURCE_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ExportMessagesResponse"
  }
}

Export a subset of HL7v2 messages using a filter

You can use the following fields in your filter criteria:

• startTime
• endTime.

You can specify the following filter parameters as your filter criteria in the filter field. To learn the filter syntax and construct queries, see Query strings.

• message_type: from the MSH.9.1 field. For example, NOT message_type = "ADT".
• 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 < "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 the RFC 3339 time 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".

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.

The following samples show how to specify a filter to only export HL7v2 messages of type ADT.

curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'pubsubDestination': {
        'pubsubTopic': 'projects/PROJECT_ID/topics/PUBSUB_TOPIC'
      },
      'filter': 'message_type = \"ADT\"'
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export"

View exported HL7v2 messages in Pub/Sub

To view the exported HL7v2 messages in Pub/Sub, run the gcloud pubsub subscriptions pull command. The command uses the --format=json flag to return the output as JSON instead of the default YAML.

gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION \
    --format=json

• PROJECT_ID is the ID of your Google Cloud project
• PUBSUB_SUBSCRIPTION is the subscription attached to the Pub/Sub topic where you exported HL7v2 messages

The output is the following:

[
  {
    "ackId": "ACK_ID",
    "message": {
      "attributes": {
        "msgType": "TYPE"
      },
      "data": "DATA",
      "messageId": "8076570784126536",
      "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
    }
  }
]