Export HL7v2 messages to Cloud Storage

This page describes how to export HL7v2 messages from an HL7v2 store to Cloud Storage. You can bulk export HL7v2 messages to Cloud Storage for downstream processing.

Before you begin

See Export HL7v2 messages from Cloud Storage for the roles you must grant to the Cloud Healthcare Service Agent service account.

Export HL7v2 messages to Cloud Storage

Permissions required for this task

To perform this task, you must have been granted the following permissions or the following Identity and Access Management (IAM) roles:

Permissions

healthcare.hl7V2Stores.export on the requested HL7v2 store

Roles

Healthcare HL7v2 Store Administrator (roles/healthcare.hl7V2StoreAdmin)

You can ask your administrator to grant you these Identity and Access Management roles. For instructions on granting roles, see Manage access or Control access to Cloud Healthcare API resources. You might also be able to get the required permissions through custom roles or other predefined roles.

Note: If you created a Google Cloud project for this guide, then, as the project creator, you're automatically granted the Owner (roles/owner) IAM role, which has the permissions. You don't need to be granted any additional IAM roles.

The Cloud Healthcare API exports each HL7v2 message as a line in an NDJSON .ndjson file. The HL7v2 messages are ordered chronologically by their sendTime value.

Export to a Cloud Storage bucket or folder, rather than an object, because the Cloud Healthcare API might create multiple NDJSON files when there are many HL7v2 messages.

If you export to a Cloud Storage folder that doesn't exist, the folder is created.

Console

To export HL7v2 messages to Cloud Storage, complete the following steps:

In the Google Cloud console, go to the Datasets page.

Go to Datasets
Click the dataset that contains the HL7v2 store from which you are exporting HL7v2 messages.
In the list of data stores, choose Export from the Actions list for the HL7v2 store.

The Export HL7v2 messages page appears.
In the Project list, select a Cloud Storage project.
In the Location list, select a Cloud Storage bucket.
Click Export to export HL7v2 instances to the defined location in Cloud Storage.
To track the status of the operation, click the Operations tab. After the operation completes, the following indications appear:
- The Long-running operation status section has a green check mark under the OK heading.
- The Overview section has a green check mark and an OK indicator in the same row as the operation ID.
If you encounter any errors, click Actions, and then click View details in Cloud Logging.

Export HL7v2 messages to Cloud Storage using filters

By default, exporting HL7v2 messages to Cloud Storage includes all HL7v2 messages in an HL7v2 store and all fields in each Message object.

You can filter the exported HL7v2 messages as follows:

Use filters to export a subset of HL7v2 messages that match a filter criteria. For more information, see Export a subset of HL7v2 messages using a filter.
Use the MessageView object to select the fields in each Message to export. For more information, see Export HL7v2 messages by Message field.

Export a subset of HL7v2 messages using a filter

You can use the following fields in your filter criteria:

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

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

REST

Use the hl7V2Stores.export method to export the HL7v2 messages:

Before using any of the request data, make the following replacements:
- PROJECT_ID: the ID of your Google Cloud project
- LOCATION: the dataset location
- DATASET_ID: the HL7v2 store's parent dataset
- HL7V2_STORE_ID: the HL7v2 store ID
- CLOUD_STORAGE_LOCATION: the name of a Cloud Storage bucket or folder where exported HL7v2 messages are written
Request JSON body:
```
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
  },
  "filter": "message_type = \"ADT\""
}
```
To send your request, choose one of these options:
curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:
```
cat > request.json << 'EOF'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
  },
  "filter": "message_type = \"ADT\""
}
EOF
```
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export"
PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:
```
@'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
  },
  "filter": "message_type = \"ADT\""
}
'@  | Out-File -FilePath request.json -Encoding utf8
```
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export" | Select-Object -Expand Content
The output is the following. The response contains an identifier for a long-running operation (LRO). Long-running operations are returned when method calls might take additional time to complete. Note the value of OPERATION_ID. You need this value in the next step.
Response
```
{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}
```

Use the projects.locations.datasets.operations.get method to get the status of the long-running operation.

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID of your Google Cloud project
DATASET_ID: the dataset ID
LOCATION: the dataset location
OPERATION_ID: the ID returned from the long-running operation

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

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

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

APIs Explorer

Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

The output is the following. When the response contains "done": true, the long-running operation has finished.

Response

{
  "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": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ExportMessagesResponse",
    
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

Export HL7v2 messages by `Message` field

In the Cloud Healthcare API, HL7v2 messages are stored in Message resources. You can use the MessageView enum to determine which fields in the Message resource are included in each exported HL7v2 message.

The following samples show how to use the BASIC value in MessageView to only include the name field in the exported HL7v2 messages.

REST

Use the hl7V2Stores.export method to export the HL7v2 messages:

Before using any of the request data, make the following replacements:
- PROJECT_ID: the ID of your Google Cloud project
- LOCATION: the dataset location
- DATASET_ID: the HL7v2 store's parent dataset
- HL7V2_STORE_ID: the HL7v2 store ID
- CLOUD_STORAGE_LOCATION: the name of a Cloud Storage bucket or folder where exported HL7v2 messages are written
Request JSON body:
```
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
    "messageView": "BASIC"
  }
}
```
To send your request, choose one of these options:
curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:
```
cat > request.json << 'EOF'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
    "messageView": "BASIC"
  }
}
EOF
```
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export"
PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:
```
@'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
    "messageView": "BASIC"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8
```
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export" | Select-Object -Expand Content
The output is the following. The response contains an identifier for a long-running operation (LRO). Long-running operations are returned when method calls might take additional time to complete. Note the value of OPERATION_ID. You need this value in the next step.
Response
```
{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}
```

Use the projects.locations.datasets.operations.get method to get the status of the long-running operation.

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID of your Google Cloud project
DATASET_ID: the dataset ID
LOCATION: the dataset location
OPERATION_ID: the ID returned from the long-running operation

To send your request, choose one of these options:

curl

Execute the following command:

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

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

APIs Explorer

Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

The output is the following. When the response contains "done": true, the long-running operation has finished.

Response

{
  "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": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ExportMessagesResponse",
    
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

Troubleshoot HL7v2 export requests

If errors occur while exporting HL7v2 messages, the errors are logged to Cloud Logging. For more information, see Viewing error logs in Cloud Logging.

If a long-running operation returns an error, see Troubleshooting long-running operations.

Export HL7v2 messages to Cloud Storage

Before you begin

Export HL7v2 messages to Cloud Storage

Permissions required for this task

Console

Export HL7v2 messages to Cloud Storage using filters

Export a subset of HL7v2 messages using a filter

REST

curl

PowerShell

Response

curl

PowerShell

APIs Explorer

Response

Export HL7v2 messages by Message field

REST

curl

PowerShell

Response

curl

PowerShell

APIs Explorer

Response

Troubleshoot HL7v2 export requests

Export HL7v2 messages by `Message` field