Conector

Conector é o nome dado à solução tecnológica que acessa a RNDS. É este software que precisa ser desenvolvido pelo integrador e, de fato, o que implementa a troca de informação em saúde com a RNDS.

Atribuir funções e discutir aspectos de design e de implementação do software de integração com a RNDS, aqui denominado de Conector, atende o propósito de orientar integradores acerca de questões técnicas pertinentes à integração com a RNDS.

Este conteúdo não é prescritivo.

Sistema de Informação em Saúde (SIS)

Um estabelecimento de saúde usa, em geral, um Sistema de Informação em Saúde (SIS) para auxiliar na gestão das suas demandas, usuários, profissionais de saúde, procedimentos e outros. Tal sistema está ou não integrado à RNDS, o que é ilustrado pelos cenários abaixo.

Adicionalmente, pode-se representar abstratamente qualquer SIS como a união de dois componentes: (a) um Banco de Dados, no qual informações administrativas e outras de saúde são armazenadas; e (b) o software propriamente dito do SIS.

Esta organização abstrada de um SIS em apenas dois componetes é útil para identificar o que é denominado de Conector, o que é feito abaixo por meio dos dois cenários ilustrados acima.

Sem integração

Usando esta abstração, quando não há interoperabilidade do SIS com outro sistema, não há software de integração, não há Conector e, consequentemente, não há integração com a RNDS, conforme ilustrado abaixo.

Com integração

A integração exige a existência do Conector. A implementação das funções deste software pode assumir várias formas. Duas delas são apresentadas abaixo.

Na primeira, o SIS empregado pelo estabelecimento de saúde passa por uma manutenção na qual as funções do Conector são fundidas ao SIS existente. O SIS, agora modificado, torna-se um SIS que interage com a RNDS, um SIS integrado à RNDS.

Na segunda, um componente específico reúne e isola as funções necessárias para a integração com a RNDS, diferente do cenário anterior. Neste caso, é possível que o Conector seja encarregado de obter as informações em saúde a serem transferidas, possivelmente acessando diretamente o Banco de Dados do estabelecimento de saúde.

Design do Conector (sem restrições?)

Convém esclarecer que estas duas formas de integração não são as únicas, e que a RNDS não impõe exigências na organização do SIS em questão. De fato, nem sequer há uma sugestão de design para o Conector, pois isto depende de inúmeras variáveis específicas de cada estabelecimento de saúde e, consequentemente, é assunto interno de cada estabelecimento.

Conector de referência

Tendo em vista as especificidades de cada integração, única por estabelecimento de saúde, não é factível definir uma análise e um design adequados para todos eles. O que segue, portanto, é uma investigação preliminar com o objetivo de oferecer uma orientação para integradores. A estratégia é familiarizar o integrador com questões naturais da integração com a RNDS.

Escopo

O Conector, como qualquer outro software, visa atender alguma demanda. Para o Conector de referência a demanda (escopo) é a Portaria 1.792, que determina a obrigatoriedade de notificação de resultados de exame da COVID-19. Convém observar que a notificação de laudo de COVID-19 é a primeira necessidade de troca de informação contemplada pela RNDS.

Ao longo do tempo, outras necessidades serão incluídas, como a notificação do Sumário de Alta (SA) e do Registro de Atendimento Clínico (RAC), por exemplo. Cada necessidade é detalhada tanto pelo modelo de informação quanto pelo modelo computacional, o que viabiliza a integração com a RNDS para a necessidade em questão.

Naturalmente, à medida que novas necessidades de integração forem implementadas pela RNDS, mais informações em saúde e outros tipos de estabelecimentos de saúde estarão envolvidos.

Apesar do Conector de referência atender uma necessidade específica (notificar laudos de COVID-19), a discussão do mesmo permanece relevante para outras demandas.

Requisitos

Os requisitos são apresentados em duas perspectivas: uma de fluxo de dados e outra de casos de uso. O objetivo é contribuir com a compreensão das funções a serem implementadas pelo Conector. São, portanto, duas visões distintas das mesmas atribuições do Conector.

Fluxo de dados

A notificação de exame de COVID-19 é ilustrada abaixo na perspectiva de processos (funções) e do fluxo de informações entre eles. Aqueles processos coloridos são "genéricos", enquanto os demais dependem diretamente do SIS para o qual o Conector é criado.

Cada uma das funções acima são comentadas abaixo. Dependendo do SIS em questão, contudo, algumas delas podem não ser necessárias. Por exemplo, se um dado SIS já guarda informações sobre cada resultado de exame em documento XML próprio, então não será necessário coletar informações dispersas, filtrar e talvez nem tampouco efetuar algum mapeamento.

• Filtrar dados. Seleciona os dados de um resultado de exame contendo o que é necessário para o envio. Consome informações registradas no depósito de dados do laboratório.

• Mapear dados. Realiza a conversão e/ou mapeamento, se for o caso, entre o que é recuperado (função acima) e o formato exigido pela RNDS. Por exemplo, a data "01/01/21" é mapeada para "01/01/2021".

• Criar instância de recurso. Os dados já filtrados e mapeados empregam uma estrutura de dados que precisa ser representada em JSON, em conformidade com o recurso FHIR (resource) pertinente.

• Montar bundle. Empacota os recursos pertinentes na representação JSON de um Bundle (um dos recursos FHIR). Quando executada, esta função também pode realizar a verificação da representação resultante. Ou seja, assegurar que foi criada conforme esperado pela RNDS.

• Obter token. Obtém token do web service de segurança da RNDS para acesso aos demais serviços, inclusive aquele pelo qual a notificação de exame é realizada.

• Submeter requisição. Notifica o resultado de um exame à RNDS. Esta é a função que, de fato, realiza o envio desejado, faz uso de um web service distinto daquele de segurança, empregado para obter o token de acesso.

A figura abaixo ilustra os processos executados em uma sequência típica, além do web service de segurança e daqueles de saúde oferecidos pela RNDS, identificados respectivamente por Auth e EHR. Em tempo, tais serviços são oferecidos pelos ambientes da RNDS.

Casos de uso

A integração exige a interação entre um estabelecimento de saúde e a RNDS. As interações relevantes para a notificação de exame de COVID-19 são ilustradas abaixo por meio de casos de uso: (a) Obter token de acesso; (b) Montar payload para resultado de COVID e (c) Enviar resultado de COVID.

Uma integração pode demandar outras atividades a serem contempladas pelo Conector. Por exemplo, responder se um determinado resultado foi submetido satisfatoriamente ou não, e recuperar a resposta da RNDS para uma dada notificação entregue, dentre outras. Estas e outras atividades podem ser necessárias, mas não são específicas da integração com a RNDS. Em consequência, apenas os casos de uso citados acima são considerados doravante.

Nota

Compreender estes casos de uso significa compreender o que é relevante para qualquer integração com a RNDS, e não apenas para a notificação de resultado do COVID-19. Eles representam a segurança e uma necessidade típica de interoperabilidade em saúde.

Obter token de acesso

A obtenção de um token de acesso é obrigatória e visa contemplar aspectos de segurança. O token é obtido por meio de web service específico, e o valor recuperado será exigido em todas as requições endereçadas aos demais web services oferecidos pela RNDS.

Esta atividade é realizada por meio de uma requisição https, método GET, endereçada ao web service de autenticação. Este serviço é identificado por Auth, na documentação dos ambientes são fornecidos detalhes, inclusive o endereço onde está disponível. Esta requisição depende do certificado digital associado ao estabelecimento de saúde em questão.

Observe que o certificado digital é associado ao estabelecimento de saúde pelo gestor, durante a solicitação de acesso à RNDS. Consulte os passos do credenciamento para detalhes.

Uma requisição satisfatória deverá retornar o código HTTP 200, e o corpo da resposta terá o seguinte formato ilustrado abaixo. O principal valor é aquele para a chave access_token, uma "longa" sequência de caracteres que, no exemplo abaixo, foi substituída por texto explicativo.

{
  "access_token": "token (longa sequência de carateres)",
  "scope": "read write",
  "token_type": "jwt",
  "expires_in": 1800000
}

A resposta acima indica que o token tem validade de 30min, ou 1.800.000ms, e que idealmente deve ser reutilizado, neste período, ou seja, estabelece uma expectativa a ser honrada pelo Conector.

Noutras palavras, o Conector deve realizar uma requisição para obter o token de acesso, guardar o valor recebido e reutilizá-lo, até que seja substituído por uma nova requisição, cerca de 30 minutos depois.

Durante o período de validade muitas requisições aos web services da RNDS possivelmente serão feitas usando um mesmo valor de token, obtido de uma única requisição para o web service de segurança.

Montar payload para resultado de COVID

Um resultado de COVID-19 deve ser montado conforme os perfis definidos por modelos computacionais, para que possa ser compreendido pela RNDS. Este caso de uso caracteriza esta funcionalidade.

A montagem é realizada por quatro processos identificados anteriormente: (a) filtrar dados; (b) mapear dados; (c) criar instância e (d) montar bundle. Estes processos, executados nesta ordem, devem produzir um Bundle, o payload a ser submetido, os dados correspondente a um resultado de exame laboratorial no formato esperado pela RNDS. O modelo computacional detalha exaustivamente o formato a ser utilizado para enviar um resltado.

Este caso de uso, portanto, reúne processos que visam converter um resultado de exame laboratorial, qualquer que seja o formato empregado pelo estabelecimento de saúde em questão, em versão equivalente no formato esperado pela RNDS.

A filtragem dos dados exige conhecer o formato de dados empregado pelo SIS do estabelecimento de saúde em questão (entrada) e o que deve ser enviado para a RNDS (saída), o que exige o conhecimento do modelo de informação.

O processo de mapeamento realiza alguma transformação necessária entre formatos de dados.

A criação de instância de recurso exige o conhecimento do recurso FHIR empregado e, em particular, de eventuais perfis que estabelecem restrições a serem observadas.

Por último, o Bundle empacota os recursos criados no processo anterior, já serializados em JSON, em JSON resultante, o payload do resultado de COVID a ser enviado.

Enviar resultado de COVID

Cria uma requisição https e a submete à RNDS.

O caso de uso Montar payload para resultado de COVID define o que é necessário para produzir o conteúdo a ser enviado. De posse do payload a requisição ainda depende da URL e de headers.

A URL segue o formato htts://{{endereco}}/api/fhir/r4/Bundle.

Observe que {{endereco}} é substituído conforme o ambiente empregado. Por exemplo, para acesso ao ambiente de homologação o endereço é ehr-auth-hmg.saude.gov.br. Consulte ambientes para detalhes.

Dois headers devem ser fornecidos: X-Athorization-Server e Authorization. O primeiro é definido pela concatenação de "Bearer " com o valor do token de acesso. Consulte Obter token de acesso para detalhes de como obter o valor do token. O segundo é o CNS do profissional de saúde em nome do qual a requisição é feita. Necessariamente deve ser um profissional de saúde lotado no estabelecimento de saúde em questão.

o Dica

O postman é uma ferramenta empregada para experimentar web services e há uma collection (cofiguração) pronta para experimentar o que a RNDS oferece. Veja aqui.

A resposta de código HTTP 200 indica que a requisição foi executada satisfatoriamente. Neste caso, dentre os headers retornados está Location, que informa o identificador único atribuído pela RNDS ao resultado de exame submetido.

Este caso de uso observa uma sequência comum às requisições enviadas aos web services da RNDS:

1. Obter o token de acesso, possivelmente de cache. Consultar caso de uso Obter token de acesso.
2. Montar valor para X-Authorization-Server. Concatenar "Bearer " (observe o espaço em branco) com o valor do token de acesso (passo anterior).
3. Definir valor para Authorization. Recuperar o CNS do profissional de saúde do estabelecimento em questão, em nome do qual a requisição será submetida.
4. Montar a requisição. Isto exige o endereço e o path para a montagem da URL correspondente. Também é possível a existência de parâmetros. A sugestão aqui é consultar URLs prontas para as requisições oferecidas pela RNDS (aqui).
5. Submeter a requisição.

Design

Os requisitos atribuídos ao Conector podem ser realizadas de várias maneiras. Abaixo segue apenas um possível design, dado que não são fornecidos detalhes de uma integração específica. Noutras palavras, seguramente não é aplicável a todos os estabelecimento de saúde. Por outro lado, é relevante compreendê-lo como parte da formação de um integrador.

Nesta possível solução o Conector é implementado por um microsserviço acionado por evento.

IMPORTANTE: o emprego de um microsserviço visa ilustrar como o Conector pode ser implementado, e não se confunde com uma recomendação.

O evento sinaliza a geração de um laudo de exame, conforme ilustrado abaixo. Dessa forma, o SIS é modificado para gerar um evento, quando um laudo é registrado, e o microsserviço (Conector), ao recebê-lo, notifica o Ministério da Saúde por meio da RNDS.

O Conector está isolado do restante do SIS, é um microsserviço. O design do código deste microsserviço pode ser influenciado por vários fatores, questão já levantada anteriormente, isto inclui até mesmo a formação do integrador e a expectativa de qualidade para o Conector, por exemplo, dentre muitos outros. Ou seja, é natural existirem alternativas para o que segue, principalmente na ausência de requisitos de um cenário real.

Considerações feitas, o design visa privilegiar a legibilidade e a manutenibilidade. Um esboço inicial é apresentado, refinado e a versão resultante apresentada na sequência, por meio das seções seguintes.

Esboço inicial

Em um primeiro esforço foram identificadas as classes abaixo após uma leitura criteriosa dos casos de uso. Aquelas não coloridas realizam as funções do negócio, enquanto as demais oferecem o suporte necessário.

A classe Conector encapsula a conexão do SIS com o microsserviço (não confunda com a conexão do Conector com a RNDS). Desta forma, a implementação correspondente, por exemplo, se uma requisição https ou o envio de uma mensagem por meio de ActiveMQ (message broker) ou SNS, fica encapsulada nesta classe. Em consequência, o código que faz uso desta classe executa uma simples mensagem como Conector.notifique(resultado), por exemplo.

Este microsserviço deve possuir o seu próprio repositório onde são registradas as requisições recebidas para serem notificadas (eventos) e as respostas obtidas das submissões. Cada submissão reúne o que é submetido, além do Resultado de um exame e da resposta apresentada pela RNDS. A resposta inclui o identificadr único, atribuído pela RNDS, ao resultado de exame. Talvez um nome melhor para o repositório seja ConectorRepositry, em vez de ResultadoRepository.

O envio propriamente dito de informação para a RNDS está encapsulada na classe RNDSProxy. Este envio depende do token de acesso cuja gestão pode estar encapsulada na classe TokenCache. Naturalmente, estas funções dependem de valores que variam ao longo do tempo e são obtidos, nesta proposta, pela classe Configuracao. Por exemplo, o certificado digital e a senha correspondente são algumas das informações obtidas por meio desta classe.

As três classes comentadas no parágrafo anterior implementam funções de acesso à RNDS e, naturalmente, são candidatas naturais para serem reutilizadas. Em consequência, serão implementadas em uma biblioteca. A biblioteca rnds é uma implementação desta decisão.

Dado que as classes Conector e Resultado são empregadas para sinalizar a ocorrência de um evento (produção de um resultado de exame), o código que as emprega não é executado pelo microsserviço, mas pelo cliente do microsserviço, outra decisão é disponibilizá-las em uma outra biblioteca. Esta, ao contrário da anterior, deve ser utilizada pela parte do SIS a ser adaptada. Ou seja, esta investigação inicial resulta em algumas decisões e duas bibliotecas.

Esboço resultante

Visando aprofundar um pouco mais, tratar os processos filtrar, mapear e demais como função (Function em Java) é um passo natural. Sim, o design, neste caso, sofre influência de Java e o alerta foi feito anteriormente pela "ausência de um cenário real" que definiria restrições como a linguagem de programação a ser adotada. Adicionalmente, C# também pode ser empregada por meio de delegates. De fato, este design não é implementável apenas em Java ou C#.

Ao excluir as classes a serem implementadas nas bibliotecas comentadas anteriormente e introduzirmos detalhes para as funções, obtém-se o resultado abaixo. A opção de uma classe por função promove a coesão e a independência entre elas. A combinação destas funções, em uma única linha, conforme nota na figura, sugere que é uma alternativa a ser considerada para transformar uma Resposta na representação JSON de um Bundle (recurso FHIR), esperado pela RNDS.

A classe Filtrar implementa a função de mesmo nome identificada acima. Qualquer que seja a estrutura e as informações em Resultado, o que é relevante é depositado em um dicionário com chave pertinente, por exemplo, "cns" para o CNS do usuário em questão.

A classe Mapear realiza eventuais mapeamentos, por exemplo, o valor "positivo" para o código correspondente esperado pela RNDS e assim por diante.

A classe ToJson cria a representação JSON para um recurso FHIR. Um resultado de exame laboratorial de COVID-19 inclui a amostra biológica utilizada pelo exame. Esta amostra é definida pelo recurso FHIR Specimen. Em particular, há uma adapação nacional para este recurso, o que é chamado de perfil, neste caso, o perfil Amostra Biológica. Para ilustrar, se a amostra utilizada é "sangue", então a representação JSON, a ser gerada pela classe ToJson para esta amostra é fornecida abaixo:

{
  "fullUrl": "urn:uuid:transient-2",
  "resource": {
    "resourceType": "Specimen",
    "meta": {
      "profile": [
        "http://www.saude.gov.br/fhir/r4/StructureDefinition/BRAmostraBiologica-1.0"
      ]
    },
    "type": {
      "coding": [
        {
          "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRTipoAmostraGAL",
          "code": "SGHEM"
        }
      ]
    }
  }
}

A produção da representação JSON, para um dado recurso, pode ser realizada de várias formas, desde um mapeamento de cada possível amostra biológica para a estrutura correspondente, até o uso de uma biblioteca para esta finalidade, como a HAPI FHIR. Neste caso, cria-se uma instância da classe Specimen (javadoc) por meio do uso de métodos de "alto nível" (fluent interface) e a serialização em JSON pode ser usada por recurso da própria biblioteca.

A classe Empacotar recebe os recursos serializados em JSON e os agrupa em um Bundle, que possui seus próprios atributos. O resultado abaixo omite o valor para identifier e os elementos do vetor entry, por simplicidade.

{
   "resourceType":"Bundle",
   "type":"document",
   "timestamp":"2020-03-20T00:00:00-03:00",
   "meta": {
      "lastUpdated": "2020-03-20T00:00:00-03:00"
   },
   "identifier":{ ... omitido ... },
   "entry":[
      { ... Resultado de Exame Laboratorial ... },
      { ... Diagnóstico em Laboratório Clínico ... },
      { ... Amostra Biológica ... }
    ]
}

Os exemplos JSON fornecidos acima são parciais e os detalhes estão disponíveis no Modelo Computacional.

Implementação

O design fornece uma orientação para o código, mas ainda persistem opções de implementação, algumas delas são comentadas abaixo. Em vez de apresentar instruções em uma dada linguagem de programação, detalhes técnicos são comentados.

conector-cliente (aws)

A classe Conector deve encapsular a comunicação do SIS com o Conector e, em um cenário onde a nuvem da Amazon é empregada, o microsserviço Conector pode ser implementado por uma Lambda Function exposta por meio do serviço API Gateway. Neste cenário, a implementação do método Conector.notificar(Resultado) terá que fazer requisições https para o endpoint exposto pelo serviço API Gateway, que serão redirecionadas para a Lambda Function corresondente.

conector-cliente (arquivo)

O laboratório que usa infraestrutura própria e cujo SIS oferece recurso para exportar um laudo em documento XML, pode não demandar manutenção. O diretório em que tais documentos são depositados pode ser monitorado e, a cada novo arquivo, o método Conector.notificar(Resultado) deve iniciar o caso de uso Enviar resultado de COVID, após a montagem do payload.

A opção acima é uma estratégia amplamente empregada. A biblioteca Chokidar é uma evidência.

rnds (biblioteca)

Às funções atribuídas a esta biblioteca são bem específicas e podem ser encapsuladas e reutilizadas. É o que é feito por meio de bibliotecas como a HAPI FHIR e rnds.

Enquanto as funções de suporte podem ser reutilizadas, as funções como filtrar e mapear, por exemplo, dependem do contexto específico de cada estabelecimento de saúde.

Funções específicas por estabelecimento

As estratégias adotadas nas bibliotecas acima dificilmente podem ser replicadas na implementação das funções filtrar e mapear, por exemplo.

Quando um SIS é capaz de exportar um documento XML pertinente a um resultado de exame, tem-se uma função útil e que viabiliza o acréscimo do Conector sem necessidade de alteração do SIS. Contudo, o esquema empregado pelo SIS, provavelmente, é diferente daquele estabelecido pelo modelo computacional. Em consequência, não há como implementar uma função filtrar de forma genérica, que obtenha dados de um esquema desconhecido.

Em outro exemplo, a função filtrar pode exigir consultas em um Banco de Dados relacional, e que são naturalmente específicas para o esquema em questão.

Apesar de não ser viável uma implementação que possa ser reutilizada, é possível indicar ferramentas possivelmente relevantes para vários cenários.