Enable schematized parsing for HL7v2 messages

This page explains how to enable schematized parsing on an HL7v2 store to parse HL7v2 messages that align with the HL7v2 standard. Enabling schematized parsing without setting a schema configuration is referred to as using the default schema. The primary use case for enabling schematized parsing is to preserve grouping when ingesting or creating HL7v2 messages.

Default schematized parsing can only be used with messages that conform to the HL7v2 standard. To parse messages that deviate from the HL7v2 standard, you must use a custom schema. The default parser is based on version 2.8.2 of the HL7v2 standard.

Sample HL7v2 message

The samples in this page use the following HL7v2 message. The sample message conforms to the HL7v2 standard.

MSH|^~\&|My EHR|My Test Facility||My EHR Facility|20150926140551||ORU^R01^ORU_R01|My-LOI_5.0_1.1-NG|T|2.5.1|||AL|AL|||||\r
PID|1||PATID5421^^^My MPI^MR||Zhang^Sally^Brian^^^^L||19840611|F||2106-3^White^HL70005|123 Main Street^^Mountain Springs^CO^80439^^H||^PRN^PH^^^203^2290210|||||||||N^Not Hispanic or Latino^HL70189\r
ORC|RE|833582639|3266238193||CM||||2010-01-01T19:53:38.408547Z\r
OBR|1|833582639|3266238193|us-0005^Vital Signs^WinPath^^||2010-01-01T19:53:38.408547Z|2010-01-01T19:53:38.408547Z|||||||2010-01-01T19:53:38.408547Z||||||||2010-01-01T19:53:38.408547Z|||F||1\r
OBX|1|NM|tt-0005-07^MDC_PULS_RATE_NON_INV^MDC^^||52.31|MDC_DIM_BEAT_PER_MIN|50-200||||F|||2010-01-01T19:53:38.408547Z||\r
OBX|2|NM|tt-0005-12^PAIN LEVEL^L^^||1.71|/10|1-10||||F|||2010-01-01T19:53:38.408547Z||\r
OBX|3|NM|tt-0005-09^MDC_TEMP^MDC^^||36.22|MDC_DIM_DEGC|36-38||||F|||2010-01-01T19:53:38.408547Z||\r

Use the default schema to preserve grouping

When you create or ingest an HL7v2 message, the Cloud Healthcare API parses the message so that all segments in the message are returned in a ParsedData object as a flat hierarchy. As a result, grouping information in the message is lost. To preserve grouping, you can enable default schematized parsing when creating or patching an HL7v2 store by passing in the ParserConfig object.

After passing in ParserConfig, the segments in the message are returned in a SchematizedData object that preserves grouping.

For example, compare the parsed versions of an MSH segment in an HL7v2 message between the ParsedData version (without setting ParserConfig) and with the SchematizedData version (with setting ParserConfig):

ParsedDataSchematizedData
{
  "parsedData": {
    "segments": [
      {
        "segmentId": "MSH",
        "fields": {
          "0": "MSH",
          "1": "^~\\&",
          "2": "My EHR",
          "3": "My Test Facility",
          "5": "My EHR Facility",
          "6": "20150926140551",
          "9": "My-LOI_5.0_1.1-NG",
          "10": "T",
          "11": "2.5.1",
          "14": "AL",
          "15": "AL",
          "8.3": "ORU_R01",
          "8.2": "R01",
          "8.1": "ORU"
        }
      },
  ...
  }
}
{
  "schematizedData": {
    "data": "{
      "ORU_R01": {
        "DSC": null,
        "MSH": {
          "0": "MSH",
          "1": "|",
          "2": "^~\\\\\\u0026",
          "3": {
            "1": "My EHR"
          },
          "4": {
            "1": "My Test Facility"
          },
          "5": null,
          "6": {
            "1": "My EHR Facility"
          },
          "7": "20150926140551",
          "8": null,
          "9": {
            "1": "ORU",
            "2": "R01",
            "3": "ORU_R01"
          },
          "10": "My-LOI_5.0_1.1-NG",
          "11": {
            "1": "T"
          },
          "12": {
            "1": "2.5.1"
          },
          "13": null,
          "14": null,
          "15": "AL",
          "16": "AL",
          "17": null,
          "18": null,
          "19": null,
          "20": null,
          "21": null
        },
    ...
  }
}

Update an HL7v2 store with the default schema

To update an existing HL7v2 store and enable default schematized parsing, use the projects.locations.datasets.hl7V2Stores.patch method.

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

  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the location of the parent dataset
  • DATASET_ID: the HL7v2 store's parent dataset
  • HL7V2_STORE_ID: the HL7v2 store ID
  • {HARD_FAIL|SOFT_FAIL}: how to determine the failure mode for schematized parsing. To determine whether to use HARD_FAIL or SOFT_FAIL, see SchematizedParsingType.

Request JSON body:

{
  "parserConfig": {
    "schema": {
      "schematizedParsingType": "{HARD_FAIL|SOFT_FAIL}"
    }
  }
}

To send your request, choose one of these options:

curl

  1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
    cat > request.json << 'EOF'
    {
      "parserConfig": {
        "schema": {
          "schematizedParsingType": "{HARD_FAIL|SOFT_FAIL}"
        }
      }
    }
    EOF
  2. Execute the following command in the terminal. It references the request.json file you just created.
    curl -X PATCH \
    -H "Authorization: Bearer "$(gcloud auth application-default 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=parser_config.schema"

PowerShell

  1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
    @'
    {
      "parserConfig": {
        "schema": {
          "schematizedParsingType": "{HARD_FAIL|SOFT_FAIL}"
        }
      }
    }
    '@  | Out-File -FilePath request.json -Encoding utf8
  2. Execute the following command in the terminal. It references the request.json file you just created.
    $cred = gcloud auth application-default 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=parser_config.schema" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Ingest and parse the sample HL7v2 message with the default schema

After creating or updating the HL7v2 store with default schematized parsing, you can ingest an HL7v2 message into the store.

The following samples show how to ingest the sample message shown in Sample HL7v2 message converted to base64. The encoded message is supplied as a value to the data field inside of the message object.

To ingest the message, use the projects.locations.datasets.hl7V2Stores.messages.ingest method.

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

  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the location of the parent dataset
  • DATASET_ID: the HL7v2 store's parent dataset
  • HL7V2_STORE_ID: the HL7v2 store ID

Request JSON body:

{
  "message": {
    "data": "TVNIfF5+XCZ8TXkgRUhSfE15IFRlc3QgRmFjaWxpdHl8fE15IEVIUiBGYWNpbGl0eXwyMDE1MDkyNjE0MDU1MXx8T1JVXlIwMV5PUlVfUjAxfE15LUxPSV81LjBfMS4xLU5HfFR8Mi41LjF8fHxBTHxBTHx8fHx8DVBJRHwxfHxQQVRJRDU0MjFeXl5NeSBNUEleTVJ8fFpoYW5nXlNhbGx5XkJyaWFuXl5eXkx8fDE5ODQwNjExfEZ8fDIxMDYtM15XaGl0ZV5ITDcwMDA1fDEyMyBNYWluIFN0cmVldF5eTW91bnRhaW4gU3ByaW5nc15DT144MDQzOV5eSHx8XlBSTl5QSF5eXjIwM14yMjkwMjEwfHx8fHx8fHx8Tl5Ob3QgSGlzcGFuaWMgb3IgTGF0aW5vXkhMNzAxODkNT1JDfFJFfDgzMzU4MjYzOXwzMjY2MjM4MTkzfHxDTXx8fHwyMDIwMDUwNjE3MDgyMg1PQlJ8MXw4MzM1ODI2Mzl8MzI2NjIzODE5M3x1cy0wMDA1XlZpdGFsIFNpZ25zXldpblBhdGheXnx8MjAyMDA1MDYxNzA4MjJ8MjAyMDA1MDYxNzA4MjJ8fHx8fHx8MjAyMDA1MDYxNzA4MjJ8fHx8fHx8fDIwMjAwNTA2MTcwODIyfHx8Rnx8MQ1PQlh8MXxOTXx0dC0wMDA1LTA3Xk1EQ19QVUxTX1JBVEVfTk9OX0lOVl5NRENeXnx8NTIuMzF8TURDX0RJTV9CRUFUX1BFUl9NSU58NTAtMjAwfHx8fEZ8fHwyMDIwMDUwNjE3MDgyMnx8DU9CWHwyfE5NfHR0LTAwMDUtMTJeUEFJTiBMRVZFTF5MXl58fDEuNzF8LzEwfDEtMTB8fHx8Rnx8fDIwMjAwNTA2MTcwODIyfHwNT0JYfDN8Tk18dHQtMDAwNS0wOV5NRENfVEVNUF5NRENeXnx8MzYuMjJ8TURDX0RJTV9ERUdDfDM2LTM4fHx8fEZ8fHwyMDIwMDUwNjE3MDgyMnx8DQ=="
  }
}

To send your request, choose one of these options:

curl

  1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
    cat > request.json << 'EOF'
    {
      "message": {
        "data": "TVNIfF5+XCZ8TXkgRUhSfE15IFRlc3QgRmFjaWxpdHl8fE15IEVIUiBGYWNpbGl0eXwyMDE1MDkyNjE0MDU1MXx8T1JVXlIwMV5PUlVfUjAxfE15LUxPSV81LjBfMS4xLU5HfFR8Mi41LjF8fHxBTHxBTHx8fHx8DVBJRHwxfHxQQVRJRDU0MjFeXl5NeSBNUEleTVJ8fFpoYW5nXlNhbGx5XkJyaWFuXl5eXkx8fDE5ODQwNjExfEZ8fDIxMDYtM15XaGl0ZV5ITDcwMDA1fDEyMyBNYWluIFN0cmVldF5eTW91bnRhaW4gU3ByaW5nc15DT144MDQzOV5eSHx8XlBSTl5QSF5eXjIwM14yMjkwMjEwfHx8fHx8fHx8Tl5Ob3QgSGlzcGFuaWMgb3IgTGF0aW5vXkhMNzAxODkNT1JDfFJFfDgzMzU4MjYzOXwzMjY2MjM4MTkzfHxDTXx8fHwyMDIwMDUwNjE3MDgyMg1PQlJ8MXw4MzM1ODI2Mzl8MzI2NjIzODE5M3x1cy0wMDA1XlZpdGFsIFNpZ25zXldpblBhdGheXnx8MjAyMDA1MDYxNzA4MjJ8MjAyMDA1MDYxNzA4MjJ8fHx8fHx8MjAyMDA1MDYxNzA4MjJ8fHx8fHx8fDIwMjAwNTA2MTcwODIyfHx8Rnx8MQ1PQlh8MXxOTXx0dC0wMDA1LTA3Xk1EQ19QVUxTX1JBVEVfTk9OX0lOVl5NRENeXnx8NTIuMzF8TURDX0RJTV9CRUFUX1BFUl9NSU58NTAtMjAwfHx8fEZ8fHwyMDIwMDUwNjE3MDgyMnx8DU9CWHwyfE5NfHR0LTAwMDUtMTJeUEFJTiBMRVZFTF5MXl58fDEuNzF8LzEwfDEtMTB8fHx8Rnx8fDIwMjAwNTA2MTcwODIyfHwNT0JYfDN8Tk18dHQtMDAwNS0wOV5NRENfVEVNUF5NRENeXnx8MzYuMjJ8TURDX0RJTV9ERUdDfDM2LTM4fHx8fEZ8fHwyMDIwMDUwNjE3MDgyMnx8DQ=="
      }
    }
    EOF
  2. Execute the following command in the terminal. It references the request.json file you just created.
    curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default 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/messages:ingest"

PowerShell

  1. Save the request body in a file called request.json. Copy the following command and run it in the terminal to create this file.
    @'
    {
      "message": {
        "data": "TVNIfF5+XCZ8TXkgRUhSfE15IFRlc3QgRmFjaWxpdHl8fE15IEVIUiBGYWNpbGl0eXwyMDE1MDkyNjE0MDU1MXx8T1JVXlIwMV5PUlVfUjAxfE15LUxPSV81LjBfMS4xLU5HfFR8Mi41LjF8fHxBTHxBTHx8fHx8DVBJRHwxfHxQQVRJRDU0MjFeXl5NeSBNUEleTVJ8fFpoYW5nXlNhbGx5XkJyaWFuXl5eXkx8fDE5ODQwNjExfEZ8fDIxMDYtM15XaGl0ZV5ITDcwMDA1fDEyMyBNYWluIFN0cmVldF5eTW91bnRhaW4gU3ByaW5nc15DT144MDQzOV5eSHx8XlBSTl5QSF5eXjIwM14yMjkwMjEwfHx8fHx8fHx8Tl5Ob3QgSGlzcGFuaWMgb3IgTGF0aW5vXkhMNzAxODkNT1JDfFJFfDgzMzU4MjYzOXwzMjY2MjM4MTkzfHxDTXx8fHwyMDIwMDUwNjE3MDgyMg1PQlJ8MXw4MzM1ODI2Mzl8MzI2NjIzODE5M3x1cy0wMDA1XlZpdGFsIFNpZ25zXldpblBhdGheXnx8MjAyMDA1MDYxNzA4MjJ8MjAyMDA1MDYxNzA4MjJ8fHx8fHx8MjAyMDA1MDYxNzA4MjJ8fHx8fHx8fDIwMjAwNTA2MTcwODIyfHx8Rnx8MQ1PQlh8MXxOTXx0dC0wMDA1LTA3Xk1EQ19QVUxTX1JBVEVfTk9OX0lOVl5NRENeXnx8NTIuMzF8TURDX0RJTV9CRUFUX1BFUl9NSU58NTAtMjAwfHx8fEZ8fHwyMDIwMDUwNjE3MDgyMnx8DU9CWHwyfE5NfHR0LTAwMDUtMTJeUEFJTiBMRVZFTF5MXl58fDEuNzF8LzEwfDEtMTB8fHx8Rnx8fDIwMjAwNTA2MTcwODIyfHwNT0JYfDN8Tk18dHQtMDAwNS0wOV5NRENfVEVNUF5NRENeXnx8MzYuMjJ8TURDX0RJTV9ERUdDfDM2LTM4fHx8fEZ8fHwyMDIwMDUwNjE3MDgyMnx8DQ=="
      }
    }
    '@  | Out-File -FilePath request.json -Encoding utf8
  2. Execute the following command in the terminal. It references the request.json file you just created.
    $cred = gcloud auth application-default 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/messages:ingest" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

What's next

Use a custom schema to parse HL7v2 messages that don't conform to the HL7v2 standard.