Nesta página, explicamos como configurar um esquema personalizado para analisar mensagens HL7v2 que não estão em conformidade com o padrão HL7v2.
Se você estiver convertendo mensagens HL7v2 para outro formato, como FHIR ou OMOP, primeiro será necessário ser capaz de analisar e ingerir as mensagens HL7v2 em um armazenamento HL7v2. Use este guia para garantir que é possível analisar e ingerir mensagens HL7v2 com êxito.
Informações gerais
Às vezes, as mensagens de HL7v2 podem não estar em conformidade com os padrões de HL7v2. Por exemplo, as mensagens de HL7v2 podem conter segmentos não incluídos no padrão HL7v2, ou os segmentos podem estar fora de ordem. Ao tentar processar mensagens não conformes, você pode encontrar erros.
Para ingerir as mensagens de HL7v2 não conformes, modifique o objeto ParserConfig
ao criar ou editar um armazenamento HL7v2. Dentro de ParserConfig, é possível configurar a análise esquematizada com base em tipos e segmentos personalizados, determinar como as mensagens HL7v2 rejeitadas são tratadas e muito mais.
Antes de configurar ParserConfig, leia as seções a seguir para entender as mensagens do HL7v2, as definições de tipo e as definições de grupo.
Mensagens HL7v2
Esta seção fornece uma breve visão geral da estrutura das mensagens de HL7v2, que será útil ao configurar o analisador de esquema personalizado.
As mensagens de HL7v2 são baseadas em eventos e descrevem transições de estado e atualizações parciais em registros clínicos. Cada mensagem HL7v2 tem um tipo que define a finalidade. Os tipos de mensagem usam um código de três caracteres e são especificados no cabeçalho de segmento principal obrigatório (MSH, na sigla em inglês) da mensagem. Há dezenas de tipos de mensagens, incluindo os seguintes:
ADT: usado para transmitir partes dos dados de administração do paciente de um pacienteORU: usado para transmitir resultados de observação.ORM: usado para transmitir informações sobre um pedido.
Revise a estrutura das mensagens de HL7v2, que incluem segmentos, campos, componentes e subcomponentes:
Na Figura 1, as seguintes partes da mensagem HL7v2 são rotuladas: o segmento, o cabeçalho do segmento, os campos e os componentes.
Por padrão, as mensagens de HL7v2 usam os caracteres a seguir para separar informações. É possível modificar os delimitadores, separadores e terminadores de uma mensagem HL7v2 por mensagem no segmento MSH.
Terminador de segmento:
\rCaso suas mensagens de HL7v2 usem um separador de segmento diferente, consulte o exemplo de Terminador de segmento personalizado e campo personalizado.
Separador de campo:
|Separador de componentes:
^Separador de subcomponente:
&Separador de repetição:
~Caracteres de escape:
\
Definições de tipo e grupo
Compreender o analisador de esquemas envolve o uso de definições de tipo e de grupos.
Definição de tipo
O termo "types" abrange o seguinte:
Tipos de segmento HL7v2, como
MSH(cabeçalho do segmento de mensagem),DG1(diagnóstico) ePID(identificação do paciente)Para uma lista de todos os tipos de segmento HL7v2, consulte Definições de segmento.
Tipos de dados HL7v2, como
ST(dados de string),TS(carimbo de data/hora) eSI(ID da sequência)Para uma lista de todos os tipos de dados padrão de HL7v2, consulte Tipos de dados.
Você especifica tipos no campo name
dentro do objeto Type.
Os tipos usam um formato modular que consiste em um segmento e nos campos, componentes e
subcomponentes do segmento. As informações em um objeto Type indicam como analisar ou interpretar um segmento e
respondem a perguntas como as seguintes:
- Quais campos estão no segmento?
- Quais são os tipos de dados dos campos?
O exemplo a seguir mostra a definição de tipo de um segmento ZCD personalizado:
{
"type": {
"name": "ZCD", // Segment type
"fields": [
{
"name": "1",
"type": "ST", // Primitive string data type
"minOccurs": 1, // Must occur at least once
"maxOccurs": 1 // Not repeated, because it can only occur once
},
{
"name": "2",
"type": "A", // Custom data type
"minOccurs": 1 // Repeated, because maxOccurs is not defined
}
]
}
}
Neste exemplo, o segmento ZCD contém dois campos, chamados 1 e 2.
O tipo de dados para 1 é ST, que é um tipo de dados de string primitivo. O tipo de dados para 2
é A, que é um tipo de dados personalizado.
A definição de tipo a seguir para o tipo de dados personalizados A mostra que ele também contém
outro tipo de dados personalizado, chamado B.
{
"type": {
"name": "A", // Custom data type
"fields": [
{
"name": "1",
"type": "ST", // Primitive string data type
"minOccurs": 1, // Must occur at least once
"maxOccurs": 1 // Not repeated, because it can only occur once
},
{
"name": "2",
"type": "B", // Custom data type
"minOccurs": 1,
"maxOccurs": 1
}
]
}
}
O exemplo a seguir mostra a definição de tipo de dados personalizados B,
que tem um campo chamado 1 com o tipo de dados ST e um campo chamado
2 que tem um tipo de dados de repetição ST:
{
"type": {
"name": "B", // Custom data type
"fields": [
{
"name": "1",
"type": "ST", // Primitive string data type
"minOccurs": 1, // Must occur at least once
"maxOccurs": 1 // Not repeated, because it can only occur once
},
{
"name": "2",
"type": "ST"
"minOccurs": 1,
"maxOccurs": 1
}
]
}
}
Com as informações sobre o segmento e os tipos de dados, você pode estimar a aparência do segmento ZCD na mensagem HL7v2 original. Este exemplo mostra
a mensagem de HL7v2 com o campo A repetido uma vez, o que é permitido
porque maxOccurs não está definido no campo A:
ZCD|ZCD_field_1|A_field_1^B_component_1&B_component_2_repetition_1~A_field_1^B_component_1&B_component_2_repetition_2
Na Figura 2, as seguintes partes da definição de tipo são rotuladas: o segmento, o cabeçalho do segmento, os campos, os componentes, os subcomponentes e as repetições.
Definição do grupo
Os grupos são definidos no nível do segmento e fornecem informações sobre quais tipos de segmentos podem aparecer em cada mensagem HL7v2.
Você especifica grupos na matriz groups
dentro do objeto
GroupOrSegment.
Considere o seguinte snippet de uma estrutura de grupo para uma mensagem ADT_A01 HL7v2:
- O primeiro
segmentna matrizmemberséMSH(cabeçalho do segmento de mensagem), porqueMSHé obrigatório em todas as mensagens HL7v2. Uma
groupcom o nomeGroup 1.Esse grupo pode ocorrer no máximo
2vezes e contém o segmentoZCDpersonalizado.Normalmente, um
groupcontém vários segmentos aninhados agrupados logicamente e outros grupos, mas, neste exemplo,Group 1contém apenas um único segmento:ZCD.
{
"ADT_A01": {
"members": [
{
"segment": {
"type": "MSH"
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"maxOccurs": "2",
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
Com as informações sobre os grupos, é possível estimar a aparência da mensagem HL7v2 original se ZCD ocorrer duas vezes nela, o que é permitido porque maxOccurs em Group 1 está definido como 2.
O restante do segmento ZCD é desconhecido sem conhecer a definição do tipo.
MSH|^~\&|||||20100308000000||ADT^A01|23701|1|2.3|| ZCD|ZCD_CONTENT ZCD|ZCD_CONTENT
Na Figura 3, as seguintes partes da definição do grupo são rotuladas: o segmento e o cabeçalho do segmento.
Configurar um esquema personalizado em um armazenamento HL7v2
As seções a seguir explicam os componentes de um esquema personalizado e como configurá-lo em um armazenamento HL7v2.
Configuração do tipo de repositório HL7v2
Depois de entender a definição de tipo de uma mensagem de HL7v2, você pode especificar uma
configuração de tipo em um armazenamento de HL7v2. Para especificar a configuração, adicione
uma matriz de types
e uma version.
O exemplo a seguir mostra como especificar a configuração para os tipos mostrados em Definição de tipo em um armazenamento HL7v2.
A configuração usa a matriz version para
especificar os campos mshField e value. Esses
campos correspondem a campos e componentes no segmento de MSH.
A matriz types especificada só se aplica a mensagens que têm um segmento MSI que corresponde aos valores de mshField e value na matriz version. Isso permite a ingestão de mensagens de HL7v2 com versões diferentes
no mesmo armazenamento de HL7v2.
{
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD", // Segment type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A", // Data type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B", // Data type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST"
}
]
}
]
}
]
}
Configuração do grupo de armazenamentos HL7v2
É possível usar grupos para configurar uma estrutura aninhada no nível de uma "associação".
Os grupos são especificados em uma matriz
members
no nível do segmento. A estrutura de um segmento é previsível e normalmente
contém campos, componentes e subcomponentes, mas o segmento em si pode estar em
qualquer nível da mensagem HL7v2.
Como uma configuração de tipo, uma configuração de grupo usa
um filtro version
para permitir a ingestão de mensagens HL7v2 com versões diferentes no mesmo armazenamento HL7v2.
O exemplo a seguir mostra como especificar a configuração para o grupo mostrado em Definição de grupo em um armazenamento HL7v2:
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"members": [
{
"segment": {
"type": "MSH"
}
},
{
"group": {
"name": "Group 1",
"maxOccurs": "2",
"members": [
"segment": {
"type": "ZCD"
}
]
}
}
]
}
}
}
Concluir a configuração do repositório HL7v2
Ao combinar a configuração de tipo e a configuração de grupo, você pode determinar como será a configuração de esquema personalizado completa no armazenamento HL7v2. Também é possível determinar se o esquema personalizado corresponde a uma mensagem de HL7v2 semelhante a esta:
MSH|^~\&|||||20100101000000||ADT^A01^A01|23701|1|2.3||
ZCD|ZCD_field_1|A_field_1^B_component_1&B_component_2_repetition_1~A_field_1^B_component_1&B_component_2_repetition_2
Expanda a seção a seguir para ver o esquema personalizado completo no armazenamento de HL7v2 e continue a criar um repositório de HL7v2 que use o esquema personalizado:
Abrir
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1,
"maxOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"maxOccurs": "2",
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD", // Segment type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A"
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "A", // Data type
"fields": [
{
"name": "1",
"type": "ST"
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B"
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B", // Data type
"fields": [
{
"name": "1",
"type": "ST"
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST"
"minOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
Criar um armazenamento HL7v2 com o esquema personalizado
Para criar um armazenamento HL7v2 que usa o esquema personalizado completo, conclua esta seção.
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do seu projeto do Google Cloud;
- LOCATION: o local do conjunto de dados;
- DATASET_ID: o conjunto de dados pai do armazenamento de HL7v2.
- HL7V2_STORE_ID: o ID do armazenamento de HL7v2.
Solicitar corpo JSON:
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
cat > request.json << 'EOF'
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
EOF
Depois execute o comando a seguir para enviar a solicitação REST:
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"
PowerShell
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
@'
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
'@ | Out-File -FilePath request.json -Encoding utf8
Depois execute o comando a seguir para enviar a solicitação REST:
$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
Você receberá uma resposta JSON semelhante a esta:
ingerir e analisar a mensagem HL7v2 usando o esquema personalizado
Para ingerir uma versão codificada em base64 da mensagem HL7v2, conclua esta seção.
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: é o ID do projeto do Google Cloud.
- LOCATION: o local do conjunto de dados pai
- DATASET_ID: o conjunto de dados pai do armazenamento de HL7v2.
- HL7V2_STORE_ID: o ID do armazenamento de HL7v2.
Solicitar corpo JSON:
{
"message": {
"data": "TVNIfF5+XCZ8fHx8fDIwMTAwMTAxMDAwMDAwfHxBRFReQTAxXkEwMXwyMzcwMXwxfDIuM3x8DVpDRHxaQ0RfZmllbGRfMXxBX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMX5BX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMQ=="
}
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
cat > request.json << 'EOF'
{
"message": {
"data": "TVNIfF5+XCZ8fHx8fDIwMTAwMTAxMDAwMDAwfHxBRFReQTAxXkEwMXwyMzcwMXwxfDIuM3x8DVpDRHxaQ0RfZmllbGRfMXxBX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMX5BX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMQ=="
}
}
EOF
Depois execute o comando a seguir para enviar a solicitação REST:
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/messages:ingest"
PowerShell
Salve o corpo da solicitação em um arquivo chamado request.json.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
@'
{
"message": {
"data": "TVNIfF5+XCZ8fHx8fDIwMTAwMTAxMDAwMDAwfHxBRFReQTAxXkEwMXwyMzcwMXwxfDIuM3x8DVpDRHxaQ0RfZmllbGRfMXxBX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMX5BX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMQ=="
}
}
'@ | Out-File -FilePath request.json -Encoding utf8
Depois execute o comando a seguir para enviar a solicitação REST:
$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/messages:ingest" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a esta:
Determinar a cardinalidade do campo
É possível determinar a cardinalidade de um campo em uma mensagem HL7v2 definindo os seguintes campos no armazenamento HL7v2:
minOccurs: determina o número mínimo de vezes que um grupo, segmento, campo, componente ou subcomponente precisa estar presente ou repetido nas mensagens HL7v2 recebidas.maxOccurs: determina o número máximo de vezes que um grupo, segmento, campo, componente ou subcomponente pode estar presente ou repetido nas mensagens HL7v2 recebidas
Ignorar elementos ausentes
Defina ignoreMinOccurs
como true se quiser que a API HL7v2 aceite todas as mensagens HL7v2 recebidas, independentemente
de elementos ausentes. Isso significa que uma mensagem não será rejeitada se não tiverem grupos, segmentos, campos, componentes ou subcomponentes obrigatórios.
Se não for possível ingerir mensagens HL7v2 porque elas
não têm campos obrigatórios, defina ignoreMinOccurs como true.
Tipo de campo de caractere curinga
O caractere curinga, *, é um tipo especial usado para campos. O uso de * indica ao
analisador de HL7v2 que o campo precisa ser analisado com base na estrutura na
mensagem de HL7v2. Usar * no lugar de um valor para um campo é útil
quando você não quer aplicar um tipo de dados de campo restrito. Contanto que o conteúdo no campo siga o padrão HL7v2, a API Cloud Healthcare poderá analisar a mensagem HL7v2.
Por exemplo, considere a seguinte definição de tipo. O campo 2 usa um caractere curinga em vez de um tipo de dados de campo. A definição é
equivalente à primeira definição em Definição de tipo e não
exige que você especifique os tipos A e B:
"type": {
"name": "ZCD"
"fields": [
{
"name": "1",
"type": "ST"
},
{
"name": "2",
"type": "*"
}
]
}
A seguir
Saiba mais sobre a configuração de analisadores de esquema personalizados em Exemplos de analisadores de esquemas personalizados.