Method: hl7V2Stores.export

Full name: projects.locations.datasets.hl7V2Stores.export

Exports the messages to a destination. To filter messages to be exported, define a filter using the start and end time, relative to the message generation time (MSH.7).

This API returns an Operation that can be used to track the status of the job by calling operations.get.

Immediate fatal errors appear in the error field. Otherwise, when the operation finishes, a detailed response of type ExportMessagesResponse is returned in the response field. The metadata field type for this operation is OperationMetadata.

HTTP request

POST https://healthcare.googleapis.com/v1/{name=projects/*/locations/*/datasets/*/hl7V2Stores/*}:export

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The name of the source HL7v2 store, in the format projects/{projectId}/locations/{locationId}/datasets/{datasetId}/hl7v2Stores/{hl7v2_store_id}

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.hl7v2Stores.export

Request body

The request body contains data with the following structure:

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "filter": string,

  // Union field destination can be only one of the following:
  "gcsDestination": {
    object(GcsDestination)
  },
  "pubsubDestination": {
    object(PubsubDestination)
  }
  // End of list of possible types for union field destination.
}
Fields
startTime

string(Timestamp format)

The start of the range in sendTime (MSH.7, https://www.hl7.org/documentcenter/public_temp_2E58C1F9-1C23-BA17-0C6126475344DA9D/wg/conf/HL7MSH.htm) to process. If not specified, the UNIX epoch (1970-01-01T00:00:00Z) is used.

This value has to come before the endTime defined below. Only messages whose sendTime lies in the range startTime (inclusive) to endTime (exclusive) are exported.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
endTime

string(Timestamp format)

The end of the range in sendTime (MSH.7, https://www.hl7.org/documentcenter/public_temp_2E58C1F9-1C23-BA17-0C6126475344DA9D/wg/conf/HL7MSH.htm) to process. If not specified, the time when the export is scheduled is used.

This value has to come after the startTime defined below. Only messages whose sendTime lies in the range startTime (inclusive) to endTime (exclusive) are exported.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
filter

string

Restricts messages exported to those matching a filter, only applicable to PubsubDestination and GcsDestination. The following syntax is available:

  • A string field value can be written as text inside quotation marks, for example "query text". The only valid relational operation for text fields is equality(=), where text is searched within the field, rather than having the field be equal to the text. For example, "Comment = great" returns messages with great in the comment field.
  • A number field value can be written as an integer, a decimal, or an exponential. The valid relational operators for number fields are the equality operator(=), along with the less than/greater than operators(<, <=, >, >=). Note that there is no inequality (!=) operator. You can prepend the NOT operator to an expression to negate it.
  • A date field value must be written in the yyyy-mm-dd format. Fields with date and time use the RFC3339 time format. Leading zeros are required for one-digit months and days. The valid relational operators for date fields are the equality operator(=) , along with the less than/greater than operators(<, <=, >, >=). Note that there is no inequality(!=) operator. You can prepend the NOT operator to an expression to negate it.
  • Multiple field query expressions can be combined in one query by adding AND or OR operators between the expressions. If a boolean operator appears within a quoted string, it is not treated as special, and is just another part of the character string to be matched. You can prepend the NOT operator to an expression to negate it.

The following fields and functions are available for filtering:

  • messageType, from the MSH-9.1 field. For example, NOT messageType = "ADT".
  • send_date or sendDate, the yyyy-mm-dd date the message was sent in the dataset's timeZone, from the MSH-7 segment. For example, send_date < "2017-01-02".
  • sendTime, the timestamp when the message was sent, using the RFC3339 time format for comparisons, from the MSH-7 segment. For example, sendTime < "2017-01-02T00:00:00-05:00".
  • createTime, the timestamp when the message was created in the HL7v2 store. Use the RFC3339 time format for comparisons. For example, createTime < "2017-01-02T00:00:00-05:00".
  • sendFacility, the care center that the message came from, from the MSH-4 segment. For example, sendFacility = "ABC".

Note: The filter will be applied to every message in the HL7v2 store whose sendTime lies in the range defined by the startTime and the endTime. Even if the filter only matches a small set of messages, the export operation can still take a long time to finish when a lot of messages are between the specified startTime and endTime range.
Union field destination. Export destination. destination can be only one of the following:
gcsDestination

object(GcsDestination)

Export to a Cloud Storage destination.
pubsubDestination

object(PubsubDestination)

Export messages to a Pub/Sub topic.

Response body

If successful, the response body contains an instance of Operation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

GcsDestination

The Cloud Storage output destination.

The Cloud Healthcare Service Agent requires the roles/storage.objectAdmin Cloud IAM roles on the Cloud Storage location.

JSON representation 
{
  "uriPrefix": string,
  "messageView": enum(MessageView),
  "contentStructure": enum(ContentStructure)
}
Fields
uriPrefix

string

URI of an existing Cloud Storage directory where the server writes result files, in the format gs://{bucket-id}/{path/to/destination/dir}. If there is no trailing slash, the service appends one when composing the object path.
messageView

enum(MessageView)

Specifies the parts of the Message resource to include in the export. If not specified, FULL is used.
contentStructure

enum(ContentStructure)

The format of the exported HL7v2 message files.

ContentStructure

The content structure of the exported HL7v2 message files.

Enums
CONTENT_STRUCTURE_UNSPECIFIED If the content structure is not specified, the default value MESSAGE_JSON will be used.
MESSAGE_JSON Messages are printed using the JSON format returned from the GetMessage API. Messages are delimited with newlines.

PubsubDestination

The Pub/Sub output destination.

The Cloud Healthcare Service Agent requires the roles/pubsub.publisher Cloud IAM role on the Pub/Sub topic.

JSON representation 
{
  "pubsubTopic": string
}
Fields
pubsubTopic

string

The Pub/Sub topic that Pub/Sub messages are published on. Supplied by the client.

The PubsubMessage contains the following fields:

  • PubsubMessage.Data contains the resource name.
  • PubsubMessage.MessageId is the ID of this notification. It is guaranteed to be unique within the topic.
  • PubsubMessage.PublishTime is the time when the message was published.

Topic names must be scoped to a project.

The Cloud Healthcare API service account, service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com, must have publisher permissions on the given Pub/Sub topic. Not having adequate permissions causes the calls that send notifications to fail.