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

By default, all HL7v2 messages in an HL7v2 store are exported. To export a subset of HL7v2 messages, you can use filters to only export messages that match the filter criteria. For more information, see Specify a filter.

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"
  }
}

Specify a filter

To export a subset of HL7v2 messages, you can use filters to only export messages that match the filter criteria.

Valid filter parameters include the following:

• 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".
• startTime: the start time of a time range, specified as the send_time parameter, during which the HL7v2 messages are sent. For more information, see startTime.
• endTime: the end time of a time range, specified as the send_time parameter, during which the HL7v2 messages are sent. For more information, see endTime.

Note: Specifying a filter using startTime and endTime is more efficient than specifying a filter using send_time. A filter created using the startTime and endTime parameters defines a range of messages to which the filter is applied while a send_time filter is applied to only those messages with the exact send time.

You can specify any filter using these terms. To learn how to specify the filter syntax and construct queries, see Query strings.

The following example shows how to specify a filter that matches only 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"
    }
  }
]