This page explains how to create, edit, view, and delete Health Level Seven Version 2.x (HL7v2) stores. HL7v2 stores hold HL7v2 messages, which are used to transmit clinical data between systems.
Creating an HL7v2 store
Before you can create an HL7v2 store, you need to create a dataset.
When creating an HL7v2 store, specify the V3
parser version. You can't change the parser version after creating the HL7v2 store.
The following samples show how to create an HL7v2 store using the V3 parser.
In the Google Cloud console, go to the Datasets page.
Select the dataset where you want to create the HL7v2 store. The Dataset page is displayed.
Click add_box Create data store. The Create data store page is displayed.
In the Type menu, select HL7v2.
In the ID field, enter a name for the HL7v2 store. The name must be unique in the dataset. See Permitted characters and size requirements for more naming requirements.
Click Next. The Configure your HL7v2 store section is displayed.
Configure the following settings:
- In the Version section, leave the default V3 selection unchanged.
- To allow the creation and ingestion of HL7v2 messages with no header, select Allow null message headers (MSH).
- To set a custom segment terminator, click Set a custom segment terminator and enter the terminator in the Segment terminator field. For more information, see Setting the segment terminator.
- To reject incoming HL7v2 messages with the same raw bytes as an HL7v2 message that already exists in the HL7v2 store, select Reject duplicate messages.
Click Next. The Receive Cloud Pub/Sub notifications section is displayed.
If you want to receive Pub/Sub notifications when a clinical event occurs in your HL7v2 store, specify the Pub/Sub topic. The topic must exist before you can configure it on the HL7v2 store.
Click Next. The Add labels to organize your data stores section is displayed.
To add one or more key/value labels to the HL7v2 store, click add Add label. For more information on resource labels, see Using resource labels.
Click Create. The Dataset page is displayed, and the HL7v2 store is displayed in the Data stores table.
To create an HL7v2 store, run the gcloud healthcare hl7v2-stores create
command.
Before using any of the command data below, make the following replacements:
: the ID of your Google Cloud projectPROJECT_ID
: the dataset locationLOCATION
: the HL7v2 store's parent datasetDATASET_ID
: an identifier for the HL7v2 store subject to the HL7v2 store character and size requirementsHL7V2_STORE_ID
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud healthcare hl7v2-stores createHL7V2_STORE_ID \ --dataset=DATASET_ID \ --location=LOCATION \ --parser-version=v3
Windows (PowerShell)
gcloud healthcare hl7v2-stores createHL7V2_STORE_ID ` --dataset=DATASET_ID ` --location=LOCATION ` --parser-version=v3
Windows (cmd.exe)
gcloud healthcare hl7v2-stores createHL7V2_STORE_ID ^ --dataset=DATASET_ID ^ --location=LOCATION ^ --parser-version=v3
You should receive a response similar to the following:
Response
Created hl7V2Store [HL7V2_STORE_ID ].
To create an HL7v2 store, use the
projects.locations.datasets.hl7V2Stores.create
method.
Before using any of the request data, make the following replacements:
: the ID of your Google Cloud projectPROJECT_ID
: the dataset locationLOCATION
: the HL7v2 store's parent datasetDATASET_ID
: an identifier for the HL7v2 store subject to the HL7v2 store character and size requirementsHL7V2_STORE_ID
Request JSON body:
{ "parserConfig": { "version": "V3" } }
To send your request, choose one of these options:
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' { "parserConfig": { "version": "V3" } } 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?hl7V2StoreId=HL7V2_STORE_ID "
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:
@' { "parserConfig": { "version": "V3" } } '@ | 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?hl7V2StoreId=HL7V2_STORE_ID " | Select-Object -Expand Content
Copy the request body and 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. Paste the request body in this tool, complete any other required fields, and click Execute.
You should receive a JSON response similar to the following:
Response
{ "name": "projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /hl7V2Stores/HL7V2_STORE_ID ", "parserConfig": { "version": "V3" } }
Use Pub/Sub topics and filters
Using Pub/Sub and filters with HL7v2 stores is a common use case, particularly when transmitting HL7v2 messages over TCP/IP connections.
Some of the examples on this page show how to configure an existing Pub/Sub topic to which the Cloud Healthcare API sends notifications of clinical events in an HL7v2 store. By specifying a list of existing Pub/Sub topics and filters, the Cloud Healthcare API can send notifications to multiple topics, and you can use the filters to restrict which notifications are sent. For more information on how to configure Pub/Sub topics and filters, see HL7v2 notifications and View HL7v2 notifications.
Editing an HL7v2 store
The following samples show how to edit the list of Pub/Sub topics and filters that the Cloud Healthcare API uses to send notifications of HL7v2 store changes.
Several samples also show how to edit the labels on the HL7v2 store.
When specifying a Pub/Sub topic, enter the qualified URI to the topic, as shown in the following sample:projects/PROJECT_ID /topics/PUBSUB_TOPIC
To edit an HL7v2 store, complete the following steps:
- In the Google Cloud console, go to the Datasets page.
- Select the dataset containing the HL7v2 store you want to edit.
- In the Data stores list, click the data store you want to edit.
- To edit the HL7v2 store's configuration, click HL7v2 Store Configuration.
For more information on the HL7v2 store's configuration options, see Creating an HL7v2 store. - If you want to configure a Pub/Sub topic for the data store, click Add Pub/Sub topic and select the topic name. When specifying a Pub/Sub topic, enter the qualified URI to the topic, as shown in the
following sample:
projects/
PROJECT_ID /topics/PUBSUB_TOPIC - If you have added a Pub/Sub topic, click Done.
- To add one or more labels to the store, click Using resource labels. Labels, click Add label, and enter the key/value label. For more information on resource labels, see
- Click Save.
The gcloud CLI doesn't support this action. Instead, use the Google Cloud console, curl
, PowerShell, or your preferred language.
To edit an HL7v2 store, use the projects.locations.datasets.hl7V2Stores.patch
method.
Before running the following samples, you must create at least one Pub/Sub topic in your project.
Before using any of the request data, make the following replacements:
PROJECT_ID : the ID of your Google Cloud projectLOCATION : the dataset locationDATASET_ID : the HL7v2 store's parent datasetHL7V2_STORE_ID : the HL7v2 store IDPUBSUB_TOPIC1 : a Pub/Sub topic to which messages are published when an event occurs in a data storeFILTER1 : a string used to match messages published to PUBSUB_TOPIC1See
filter
for examples of valid filter values.PUBSUB_TOPIC2 : a Pub/Sub topic to which messages are publishedFILTER2 : a string used to match messages published to PUBSUB_TOPIC2KEY1 : the first label keyVALUE1 : the first label valueKEY2 : the second label keyVALUE2 : the second label value
Request JSON body:
{ 'notificationConfigs': [ { 'pubsubTopic': 'projects/PROJECT_ID /topics/PUBSUB_TOPIC1 ', 'filter' : 'FILTER1 ' }, { 'pubsubTopic': 'projects/PROJECT_ID /topics/PUBSUB_TOPIC2 ', 'filter': 'FILTER2 ' }, ], 'labels': { 'KEY1 ':'VALUE1 ', 'KEY2 ':'VALUE2 ' } }
To send your request, choose one of these options:
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' { 'notificationConfigs': [ { 'pubsubTopic': 'projects/PROJECT_ID /topics/PUBSUB_TOPIC1 ', 'filter' : 'FILTER1 ' }, { 'pubsubTopic': 'projects/PROJECT_ID /topics/PUBSUB_TOPIC2 ', 'filter': 'FILTER2 ' }, ], 'labels': { 'KEY1 ':'VALUE1 ', 'KEY2 ':'VALUE2 ' } } EOF
Then execute the following command to send your REST request:
curl -X PATCH \
-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 ?updateMask=notificationConfigs,labels"
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:
@' { 'notificationConfigs': [ { 'pubsubTopic': 'projects/PROJECT_ID /topics/PUBSUB_TOPIC1 ', 'filter' : 'FILTER1 ' }, { 'pubsubTopic': 'projects/PROJECT_ID /topics/PUBSUB_TOPIC2 ', 'filter': 'FILTER2 ' }, ], 'labels': { 'KEY1 ':'VALUE1 ', 'KEY2 ':'VALUE2 ' } } '@ | 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 PATCH `
-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 ?updateMask=notificationConfigs,labels" | Select-Object -Expand Content
Copy the request body and 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. Paste the request body in this tool, complete any other required fields, and click Execute.
You should receive a JSON response similar to the following:
Response
{ "name": "projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /hl7V2Stores/HL7V2_STORE_ID ", "labels": { "KEY1 ": "VALUE1 ", "KEY2 ": "VALUE2 " }, "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID /topics/PUBSUB_TOPIC1 ", "filter": "FILTER1 " }, { "pubsubTopic": "projects/PROJECT_ID /topics/PUBSUB_TOPIC2 ", "filter": "FILTER2 " } ] }
Getting HL7v2 store details
The following samples show how to get details about an HL7v2 store.
To view an HL7v2 store's details:
- In the Google Cloud console, go to the Datasets page.
- Select the dataset containing the HL7v2 store you want to view.
- Click the name of the HL7v2 store.
The Datastore details page displays the details of the selected an HL7v2 store.
To get details about an HL7v2 store, run the gcloud healthcare hl7v2-stores describe
command.
Before using any of the command data below, make the following replacements:
LOCATION : the dataset locationDATASET_ID : the HL7v2 store's parent datasetHL7V2_STORE_ID : the HL7v2 store ID
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud healthcare hl7v2-stores describeHL7V2_STORE_ID \ --dataset=DATASET_ID \ --location=LOCATION
Windows (PowerShell)
gcloud healthcare hl7v2-stores describeHL7V2_STORE_ID ` --dataset=DATASET_ID ` --location=LOCATION
Windows (cmd.exe)
gcloud healthcare hl7v2-stores describeHL7V2_STORE_ID ^ --dataset=DATASET_ID ^ --location=LOCATION
You should receive a response similar to the following.
If you configured any fields in the Hl7V2Store
resource, they also appear in the response.
Response
... name: projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /hl7V2Stores/HL7V2_STORE_ID ...
To get details about an HL7v2 store, use the projects.locations.datasets.hl7V2Stores.get
method.
Before using any of the request data, make the following replacements:
PROJECT_ID : the ID of your Google Cloud projectLOCATION : the dataset locationDATASET_ID : the HL7v2 store's parent datasetHL7V2_STORE_ID : the HL7v2 store ID
To send your request, choose one of these options:
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 /hl7V2Stores/HL7V2_STORE_ID "
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 /hl7V2Stores/HL7V2_STORE_ID " | Select-Object -Expand Content
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.
You should receive a response similar to the following.
If you configured any fields in the Hl7V2Store
resource, they also appear in the response.
Response
{ "name": "projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /hl7V2Stores/HL7V2_STORE_ID " ... }
Listing the HL7v2 stores in a dataset
The following samples show how to list the HL7v2 stores in a dataset.
To view the data stores in a dataset:
- In the Google Cloud console, go to the Datasets page.
- Select the dataset containing the data store you want to view.
To list the HL7v2 stores in a dataset, run the gcloud healthcare hl7v2-stores list
command.
Before using any of the command data below, make the following replacements:
LOCATION : the dataset locationDATASET_ID : the HL7v2 store's parent dataset
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud healthcare hl7v2-stores list --dataset=DATASET_ID \ --location=LOCATION
Windows (PowerShell)
gcloud healthcare hl7v2-stores list --dataset=DATASET_ID ` --location=LOCATION
Windows (cmd.exe)
gcloud healthcare hl7v2-stores list --dataset=DATASET_ID ^ --location=LOCATION
You should receive a response similar to the following.
If you configured any fields in the Hl7V2Store
resource, they also appear in the response.
ID LOCATION TOPICHL7V2_STORE_ID LOCATION projects/PROJECT_ID /topics/PUBSUB_TOPIC PUBSUB_TOPIC ...
To list the HL7v2 stores in a dataset, use the projects.locations.datasets.hl7V2Stores.list
method.
Before using any of the request data, make the following replacements:
PROJECT_ID : the ID of your Google Cloud projectLOCATION : the dataset locationDATASET_ID : the HL7v2 store's parent dataset
To send your request, choose one of these options:
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 /hl7V2Stores"
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 /hl7V2Stores" | Select-Object -Expand Content
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.
You should receive a response similar to the following.
If you configured any fields in the Hl7V2Store
resource, they also appear in the response.
Response
{ "hl7V2Stores": [ { "name": "projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /hl7V2Stores/HL7V2_STORE_ID " ... }, { ... } ] }
Deleting an HL7v2 store
The following samples show how to delete an HL7v2 store.
To delete a data store:
- In the Google Cloud console, go to the Datasets page.
- Select the dataset containing the data store you want to delete.
- Choose Delete from the Actions drop-down list for the data store that you want to delete.
- To confirm, type the data store name and then click Delete.
To delete an HL7v2 store, run the gcloud healthcare hl7v2-stores delete
command.
Before using any of the command data below, make the following replacements:
LOCATION : the dataset locationDATASET_ID : the HL7v2 store's parent datasetHL7V2_STORE_ID : the HL7v2 store ID
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud healthcare hl7v2-stores deleteHL7V2_STORE_ID \ --dataset=DATASET_ID \ --location=LOCATION
Windows (PowerShell)
gcloud healthcare hl7v2-stores deleteHL7V2_STORE_ID ` --dataset=DATASET_ID ` --location=LOCATION
Windows (cmd.exe)
gcloud healthcare hl7v2-stores deleteHL7V2_STORE_ID ^ --dataset=DATASET_ID ^ --location=LOCATION
Deleted hl7v2Store [HL7V2_STORE_ID ].
To delete an HL7v2 store, use the projects.locations.datasets.hl7V2Stores.delete
method.
Before using any of the request data, make the following replacements:
PROJECT_ID : the ID of your Google Cloud projectLOCATION : the dataset locationDATASET_ID : the HL7v2 store's parent datasetHL7V2_STORE_ID : the HL7v2 store ID
To send your request, choose one of these options:
Execute the following command:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /hl7V2Stores/HL7V2_STORE_ID "
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /hl7V2Stores/HL7V2_STORE_ID " | Select-Object -Expand Content
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.
Response
{}
What's next
- Read the conceptual documentation on how HL7v2 is implemented in the Cloud Healthcare API.
- Learn how to create and manage HL7v2 messages.