FAQ - Omnlink

Esta documentação abrange a área de troubleshooting, essencial para resolver problemas técnicos e manter sistemas funcionando adequadamente. Exploraremos a abordagem sistemática de análise de sintomas, testes e diagnóstico, além de destacar a importância da colaboração e compartilhamento de conhecimento. O guia fornece informações valiosas para aprimorar habilidades técnicas e enfrentar desafios com confiança, garantindo a eficiência operacional. Mantenha-se atualizado com as últimas tendências nesse campo em constante evolução.

Timezone

Problema: Como colocar os horários dos logs corretamente?

Para trocar o fuso horário (timezone) de um container Docker em execução, você pode seguir estas etapas:

1. Primeiro, você precisa entrar no container. Você pode fazer isso usando o comando docker exec seguido pelo ID ou nome do container e um shell interativo, como o bash. Por exemplo:

   docker exec -it <container_id_ou_nome> bash

2. Dentro do container, você pode configurar o fuso horário usando o comando tzdata, selecionando o local de horário correspondente a sua área de localização (São Paulo/Brasilia, Acre, Amazonas ou Fernando de Noronha)

   # Configurar o fuso horário interativamente dpkg-reconfigure tzdata

3. Após configurar o fuso horário, saia do shell interativo dentro do container, digitando exit.

4. Reinicie o container para que as alterações se reflitam

5. Verifique que agora os horários estão corretamente acompanhando o seu container

Omnilink não responde !?

Problema: Ao tentar realizar o login na plataforma da Mobile, não é retornado nada!

É necessário confirmar se o omnilink está funcionando corretamente, vamos seguir algumas etapas:

1. Verifique se as requisições de login efetuadas pelo Configurador Público estão batendo em seu Firewall (é obrigatório que as requisições sejam realizadas do configurador público e não da rede local), caso não esteja é necessário verificar com sua equipe de infraestrutura ( no 5 passo sempre coloque um timeout entre 30 e 45 segundos)

Open

2. Em caso destas requisições estarem batendo pelo firewall da empresa vamos para a segunda etapa (siga para esta etapa apenas confirmação das requisições realizadas pelo configurador público estarem “batendo" no firewall da empresa), que é verificar dentro na maquina na qual está instalado o omnilink as queries que estão sendo executadas;

• Acesse o terminal linux do seu servidor e execute o comando:

• Na saída desse comando procure a instancia do omnlink que está apresentando problemas em retornar as devidas informações (Autenticação, Boletos, Extratos , etc.. ) deve ser semelhante a essa:

Open

• Para analisar as falhas, recomendamos verificar o log do OMNILINK, através do comando de análise de logs:

• Realize uma nova requisição a partir do configurador público, neste momento com este comando sendo executado em seu terminal, será possível capturar as requisições efetuadas para o omnilink;

Open

• Pegue as queries que foram capturadas no Omnilink e realize essa requisição no SGDB para o seu banco de dados e verifique se estão retornando dados. (Não mude nenhum parâmetro ao rodar a query em seu banco de dados, se está precisando mudar os parâmetros para que se obtenha retornos é necessário verificar as regras de negócio da Operadora).

Open

• Verifique as Views que foram implementadas (existem views que são opcionais e caso não tenha sido implementada pela operadora podem ser ignoradas, mas apenas as views opcionais que NÃO foram implementadas, a partir do momento que foi implementadas a verificação e suas regras de negócio tornam-se OBRIGATÓRIAS).

• Identifique e ajuste o problema para que o omnilink possa a funcionar novamente de forma correta.

Omnilink - Débitos não retorna os dados ordenados!

Problema: Ao tentar utilizar a rotina de boletos a mesma não vem com os dados ordenados

O Omnilink não possui ordenação em sua requisições, os dados são retornados conforme estão disponíveis nas views, ou seja é necessário que os dados estejam ordenados na view ( e isso deve ser feito conforme a necessidade de regras de negócio da Operadora).

Ou seja a aplicação Web ou App só reflete o retorno da API que é gerada pelo Omnilink, existem alguns filtros existentes nas aplicações porém a exibição padrão é definida pelo retorno da API que é gerada pelo Omnilink.

Como consigo verificar se minha view está retornando os dados corretamente?

• Acesse o terminal linux do seu servidor e execute o comando:

• Na saída desse comando procure a instancia do omnlink que está apresentando problemas em retornar as devidas informações (Autenticação, Boletos, Extratos , etc.. ) deve ser semelhante a essa:

Open

• Para analisar, recomendamos verificar o log do OMNILINK, através do comando de análise de logs:

• Realize uma nova requisição a partir do configurador público (neste caso na acessando a funcionalidade de boletos) no método listaDebitos

Open

• Neste momento com este comando sendo executado em seu terminal, será possível capturar as requisições efetuadas para o omnilink;

Open

• Pegue as queries que foram capturadas no Omnilink e realize essa requisição no SGDB para o seu banco de dados e verifique se estão retornando dados. (Não mude nenhum parâmetro ao rodar a query em seu banco de dados, se está precisando mudar os parâmetros para que se obtenha retornos é necessário verificar as regras de negócio da Operadora).

• O resultado destas queries são o resultado que será levado para a API de listagem do débito.

• Ajuste a view ordenando de forma que as queries de listagem do débito retornem da forma que seja desejado pela operadora.

Testes de conexão Omnilink - Postman

Após instalação do OMNILINK, para iniciar os testes de conexão a partir de seu computador, recomendamos que acesse o painel e baixe a collection do POSTMAN
Acesse o Painel > Ferramentas > Omnilink > Editar > Coleção do Postman.

Open

Caso não tenha o Postman instalado no seu computador, instale-o utilizando o link Download Postman | Get Started for Free

Estes testes servem para certificar se os Endpoints gerados estão retornando corretamente, sendo possível verificar as queries que foram capturadas conforme explicado no passo anterior.
FAQ - Omnlink | Omnilink não responde !?

Importante ao realizar uma requisição via Postman é obrigatório inserir header da requisição o parâmetro “Authorization” com este token só podendo ser preenchido acessando o Painel > Ferramentas > Omnilink > Copiar Token de Testes.

Recomendamos fortemente os testes realizados no Postman verificando as queries antes de prosseguir com a integração no Painel Publico, pois estes testes ajudam a verificar eventuais problemas antes de disponibilizar os Endpoints na plataforma.

Atualização de Omnilink

Caso exista necessidade de atualizar o Omnlink recomendamos atentar para:

1 - Atualizações que são apenas para atualizar o Omnlink com a versão mais atual que a Mobile Saúde disponibiliza.

Resposta: Se não existe mudança a da infra estrutura ( Local onde está instalado Omnlink e mudança de banco de dados), pode ser feita a atualização diretamente, pois só serão atualizados dados do Omnlink.

2 - Atualização de Omnlink visando migrar a máquina onde está instalado o Omnlink

Resposta: No caso de existir necessidade de mudança da infra estrutura onde está instalado o Omnlink ( mudança de servidor, atualização do docker instalado na máquina, mudança de sistema operacional na maquina que esta o omnilink Ex: do Ubuntu para um CentOs), recomendamos que a atualização/migração seja realizada de forma cautelosa onde recomendamos que seja testado a instalação do Omnlink na infra nova e depois de testa-la que seja feito o apontamento do Omnlink no Painel da Mobile Saúde para a nova infra.

Exemplo: Omnilink - PRD - Autenticação instalado é necessário ser migrado para uma nova infra estrutura, neste caso instale o Omnlink - Sandbox/Homologação - Autenticação na nova infra ( Existem portas para o Omnlink Produção e Sandbox (clique aqui para ver serviços e portas dos serviços do Omnlink) com isso realize todos os teste em todos os serviços e métodos ( Trocar senha, relogin, buscaBeneficiarios e etc) com tudo validado é rodar o script de produção na nova infra com a certeza de que tudo funcionará corretamente.

3 - Atualização de Omnlink visando migrar/atualizar versão do banco de dados

Resposta: No caso de necessidade de atualização de versão do banco de dados (Postgress X → Postres X+1) ou mesmo migrar de um banco para outro (Posgres → MySql), recomendamos fortemente que seja realizado a mesma orientação do anterior ( 2 - Atualização de Omnlink visando migrar a máquina onde está instalado o Omnlink), onde deve-se instalar uma versão com as portas de sandbox/homologação e realizar todos os testes de forma interna e externa a fim de garantir que a migração não impactará nos serviços já disponíveis.

Falha no carregamento de cartões virtuais de beneficiários

Open

Como resolver este tipo de problema no Omnilink

Open

1. Visão Geral do Incidente

• Resumo claro e direto do problema: Beneficiários não conseguem visualizar o cartão virtual no aplicativo Mosia Omnichannel. A tela de seleção de contrato/beneficiário não retorna dados, exibindo a mensagem "Não retorna nada no contrato, não há beneficiários no contrato", apesar de inicialmente listar contratos.

2. Contexto Técnico

• Ambiente: Produção (inferido por "clientes" e "problema que está acontecendo").

• Stack envolvida:

  • Cloud: Suposição: Ambiente baseado em containers Docker para OmniLink.

  • Backend / API Gateway: OmniLink - Software que transforma views de banco de dados em APIs consumíveis.

  • Frontend / Aplicação Cliente: Mosia Omnichannel - Produto que consome as APIs geradas pelo OmniLink.

  • Banco de Dados: Suposição: SGPD (Sistema Gerenciador de Banco de Dados) relacional que armazena os dados dos contratos e beneficiários, e onde as views do OmniLink são definidas.

• Componentes afetados:

  • API de contratos/beneficiários gerada pelo OmniLink.

  • Módulo de cartão virtual no Mosia Omnichannel.

• Dependências externas: Banco de Dados (SGPD da operadora).

3. Sintomas Observados

• Erros reportados:

  • Na interface do Mosia Omnichannel: Mensagem "Não retorna nada no contrato, não há beneficiários no contrato" após seleção inicial.

  • No "validador de integrações": "35 erros" apontados, especificamente arrays de contrato retornando vazios ou como NULL.

• Comportamentos inesperados:

  • A aplicação inicialmente mostra uma lista de contratos/beneficiários, mas após a seleção, falha em carregar os detalhes do cartão virtual.

  • A API do OmniLink retorna um array de objetos de contrato com atributos NULL ou vazio ([]).

• Logs relevantes (normalizados e limpos):

  • Validador de Integrações (Login):

    { "status": "error", "message": "Encontrados 35 erros de validação.", "details": [ { "field": "contracts", "error": "Array de contrato vazio ou com atributos NULL.", "value": [] // ou [{"id": null, "name": null, ...}] }, // ... outros 34 erros ] }

  • Retorno da API do OmniLink (inferido):

    { "data": { "beneficiaries": [ { "id": "123", "name": "João", "contracts": [] // Array de contratos vazio para este beneficiário } ] } }

    Ou atributos NULL:

    { "data": { "beneficiaries": [ { "id": "123", "name": "João", "contracts": [ { "contractId": null, "planName": null, "status": null // ... todos os atributos como NULL } ] } ] } }

4. Impacto

• Usuários afetados: Beneficiários que tentam acessar seus cartões virtuais.

• Funcionalidades comprometidas: Acesso e visualização do cartão virtual.

• Escopo do incidente: Pode ser específico para um grupo de beneficiários ou contratos, ou generalizado se a causa for uma alteração global nos dados ou na lógica das views.

5. Hipóteses de Causa

• Mais provável: Falha na montagem do array de objetos de contrato pelo OmniLink devido a dados inconsistentes.

  • Descrição técnica: As queries SQL subjacentes que o OmniLink utiliza para montar o payload de contratos estão falhando em retornar dados válidos, resultando em arrays vazios ou com todos os atributos NULL. Isso impede que a lógica de amarração do usuário logado com o contrato funcione corretamente.

  • Evidências a favor:

    • "Validador de integrações" aponta "35 erros" e menciona array de contrato vazio/NULL.

    • Experiência prévia de problemas similares ("já aconteceu outras vezes").

    • A etapa de diagnóstico focada em analisar queries SQL é a principal recomendação.

• Possível: Alteração nos dados da operadora que não se alinha com as views do OmniLink.

  • Descrição técnica: Modificações nos dados de contrato, beneficiários, ou na estrutura de como os titulares/beneficiários são distribuídos no SGPD da operadora (ex: "troca, sucessão") podem ter levado a um desalinhamento com a lógica das views que o OmniLink espera.

6. Passos de Diagnóstico

Este checklist visa identificar o ponto exato da falha na recuperação dos dados do contrato.

1. Verificação do Validador de Integrações:

   • Acesse a ferramenta "validador de integrações".

   • Insira o login do beneficiário afetado.

   • Analise as críticas e erros retornados, focando nas mensagens relacionadas a contratos e beneficiários.

   • Saída esperada: Identificação de arrays de contrato vazios ou com atributos NULL.

2. Inspeção de Logs do OmniLink (Docker):

   • Acesse o console do servidor onde o container Docker do OmniLink está em execução.

   • Execute o comando docker logs para o container do OmniLink com a flag -f para seguir os logs.

   • Reproduza o problema no Mosia Omnichannel (tente acessar o cartão virtual para o login em questão).

   • Observe os logs para capturar as queries SQL executadas pelo OmniLink durante a requisição.

   # Acessar o console do servidor ou ambiente Docker # ssh user@seu_servidor_docker # Encontrar o nome do container do OmniLink (se não souber) docker ps | grep OmniLink # Exemplo: Se o nome for 'OmniLink-prod-1' docker logs -f OmniLink-prod-1 # Enquanto o comando acima estiver rodando, reproduza o problema na UI. # As queries SQL serão exibidas no console.

3. Análise Individual das Queries SQL:

   • Copie cada query SQL identificada nos logs do OmniLink.

   • Conecte-se ao SGPD da operadora (banco de dados).

   • Execute cada SELECT individualmente no banco de dados.

   • Verifique os resultados:

     • Query 1: Retorna dados?

     • Query 2 (que pode depender da Query 1): Retorna dados com base nos resultados da anterior?

     • Identifique qual SELECT está falhando em retornar dados esperados ou está retornando NULL onde deveria haver valores.

   • Ferramentas: Cliente SQL (DBeaver, SQL Developer, pgAdmin, DataGrip, etc.).

4. Consulta à Documentação do OmniLink (documentação):

   • Consulte a documentação de artefatos de banco de dados e views de login do OmniLink.

   • Entenda a descrição de cada atributo e a lógica aplicada para o funcionamento das views.

   • Compare a lógica esperada com os resultados obtidos nas queries SQL executadas manualmente.

7. Análise Técnica

• Correlações encontradas: A mensagem de erro no Mosia Omnichannel e os erros no validador de integrações correlacionam-se diretamente com o array de contratos vazio ou NULL retornado pelo OmniLink. Este, por sua vez, é correlacionado com a falha de uma ou mais queries SQL subjacentes em retornar dados válidos, ou com a montagem incorreta do payload final pelo OmniLink devido a essa ausência de dados.

8. Causa Raiz (Root Cause)

• Explicação técnica clara: As views de banco de dados utilizadas pelo OmniLink para gerar a API de contratos não estão retornando os dados esperados ou estão retornando valores NULL para atributos cruciais dos contratos e beneficiários. Isso ocorre porque uma ou mais das queries SQL que compõem essas views estão falhando ao consultar o SGPD da operadora, possivelmente devido a:

  • Alterações nos dados da operadora: Dados que antes eram compatíveis com a lógica das views do OmniLink foram alterados (ex: sucessões, trocas de plano, cancelamentos que não foram tratados corretamente na view).

  • Inconsistência de dados: Registros faltando, IDs incorretos, ou dados em formatos não esperados pelas views.

  • Lógica da view não suporta novo cenário: O OmniLink segue regras específicas; se o fluxo de dados da operadora se desviou dessas regras, as views não se adaptam automaticamente.

• Cadeia de eventos que levou ao problema:

  1. Beneficiário tenta acessar cartão virtual no Mosia Omnichannel.

  2. Mosia Omnichannel faz uma requisição para a API de contratos/beneficiários do OmniLink.

  3. OmniLink executa uma série de queries SQL baseadas em suas views para montar o payload de resposta.

  4. Uma ou mais dessas queries SQL falham em encontrar os dados de contrato esperados no SGPD (ou retornam NULL / vazio).

  5. OmniLink monta um payload com o array de contratos vazio ou com atributos NULL.

  6. Mosia Omnichannel recebe o payload inconsistente e não consegue prosseguir com a montagem do cartão virtual, exibindo a mensagem de erro.

• Desalinhamento de Dados/Lógica da View com as Expectativas do OmniLink, provavelmente originado por mudanças no lado da operadora ou inconsistências no SGPD.

9. Solução / Mitigação

• Ação aplicada: Identificação e correção da causa da falha das queries SQL que alimentam as views do OmniLink. Isso geralmente envolve a correção dos dados no banco de dados da operadora ou, em casos mais complexos, o ajuste das views (se permitido e alinhado às regras do OmniLink).

10. Passos de Correção

1. Isolamento da Query Problemática: Através dos "Passos de Diagnóstico", identifique a query SQL exata que está retornando resultados inesperados (vazio, NULL, ou dados incorretos).

2. Análise de Dados Subjacentes: Para a query identificada, investigue as tabelas e condições (WHERE clauses) envolvidas. Verifique os dados diretamente nas tabelas para o beneficiário e contrato em questão.

   • Há registros ausentes?

   • Há IDs que não se correlacionam?

   • Os status ou tipos de contrato estão de acordo com o que a view espera?

   • Houve alguma mudança recente nos dados (sucessões, trocas, etc.) que não se reflete na view?

3. Comparação com Documentação do OmniLink (documentação): Utilize a documentação dos artefatos e views de login do OmniLink para entender a lógica esperada para cada atributo e verificar se o dado atual no banco de dados se alinha com essa lógica.

4. Proposição de Correção:

   • Opção A (Preferencial): Correção dos Dados no SGPD: Se a investigação revelar inconsistências nos dados do banco de dados da operadora (ex: um campo que deveria estar preenchido está vazio, um ID de relacionamento está incorreto), aplique as correções necessárias diretamente no banco. Sempre com backup e em ambiente de staging primeiro.

   • Opção B (Avaliar com Cuidado): Ajuste da Lógica da View (Se Customizada ou Aplicável): Se a view estiver mal formulada ou não considerar um cenário de dados válido, pode ser necessário ajustá-la. Importante: O OmniLink possui regras fixas; a lógica da operadora precisa se adaptar ao OmniLink. Modificar as views pode ser inviável ou não recomendado para o OmniLink padrão. Solicitar apoio da Mobile Saúde pode ser necessário para esta etapa.

5. Testes e Validação: Após qualquer correção, siga os "Passos de Validação da Solução".

11. Validação da Solução

• Como confirmar que o problema foi resolvido:

  1. Repetição do Teste de Diagnóstico:

     • Execute novamente o "validador de integrações" para o beneficiário afetado.

     • Logs esperados: Nenhuma crítica ou erro relacionado ao array de contratos.

  2. Verificação da API:

     • Faça uma requisição direta à API do OmniLink (se houver ferramenta para isso, como Postman/Insomnia ou via curl) para o beneficiário.

     • Payload esperado: O array de contratos deve conter objetos válidos com todos os atributos preenchidos.

  3. Testes funcionais no Frontend:

     • Acesse o Mosia Omnichannel e tente novamente acessar o cartão virtual para o beneficiário que estava com problema.

     • Comportamento esperado: O cartão virtual deve carregar e ser exibido corretamente.

12. Monitoramento e Prevenção

• Alertas recomendados:

  • Erros de API: Alerta para retornos de API do OmniLink com status code 5xx (erros de servidor) ou status code 200, mas com payloads contendo arrays vazios ou NULL para atributos críticos.

  • Saúde do OmniLink: Alertas para consumo de CPU/Memória elevados ou reinícios inesperados do container Docker do OmniLink.

  • Consistência de Dados (DB): Alertas sobre anomalias em queries ou views críticas, ou sobre a presença de dados NULL em campos obrigatórios de tabelas de contrato/beneficiário.

• Métricas a acompanhar:

  • Taxa de sucesso/erro das APIs do OmniLink relacionadas a contratos e beneficiários.

  • Latência das requisições ao OmniLink.

  • Contagem de arrays vazios ou NULL retornados por APIs críticas do OmniLink.

  • Desempenho das queries SQL executadas pelo OmniLink no SGPD.

• Melhorias sugeridas:

  • Data Validation: Implementar rotinas regulares de validação de dados no SGPD para identificar inconsistências proativamente.

  • Schema Evolution: Estabelecer um processo mais rigoroso para gerenciar alterações de esquema ou regras de negócio no SGPD da operadora, garantindo que sejam compatíveis com as views do OmniLink.