Pular para conteúdo

Criando um Alerta

Introdução

O GeoProcess é uma plataforma de ciência de dados baseada no conceito de perguntas e respostas, conforme apresentado em Início. Por meio de perguntas, é possível acessar diversas bases de dados e, a partir das respostas, construir dashboards interativos compostos por mapas, gráficos e tabelas.

Nesse cenário, o consumidor desempenha o papel de conectar as perguntas formuladas pelos usuários às bases de dados disponíveis, retornando as informações necessárias para construir os dashboards. Assim, sempre que um usuário deseja desenvolver um dashboard, é necessário criar um consumidor, que será responsável por formular as perguntas apropriadas e organizar os dados para gerar as visualizações desejadas.

O desafio da interação ativa

Atualmente, para obter respostas, o usuário precisa acessar o sistema, executar sua pergunta e aguardar a resposta. Esse modelo de interação ativa pode se tornar trabalhoso, especialmente para consultas frequentes.

Por exemplo, considere o caso das escolas do município de Lavras, apresentado em Visual Builder. Um usuário pode querer acompanhar regularmente a quantidade de pessoas em idade escolar que não estão matriculadas na rede municipal de ensino. Essa informação pode ser crucial para tomada de decisões e precisaria ser atualizada semanalmente ou mensalmente. Realizar esse processo manualmente repetidas vezes pode ser inconveniente e propenso a falhas.

Solução: Automação com Alertas

Para resolver esse problema, o GeoProcess oferece a funcionalidade de Alertas. Um alerta é, essencialmente, uma pergunta automatizada, agendada para ser executada pelo sistema em intervalos regulares, como diariamente, semanalmente ou mensalmente.

Com os alertas, o usuário pode configurar uma pergunta, como “quantas pessoas em idade escolar não estão matriculadas?”, e deixar que o sistema a execute automaticamente. Sempre que a resposta da pergunta retornar dados relevantes (não vazia), o GeoProcess gerará uma indicação de alerta. Dessa forma, o usuário será notificado apenas quando houver algo significativo a ser consultado, eliminando a necessidade de interações manuais recorrentes.

Como iniciar a criação de alertas

A criação de alertas segue um processo semelhante ao de um consumidor padrão. Há duas abordagens principais para começar:

  1. Visual Builder: Ferramenta para projetar a interface de resposta antes de escrever o código, permitindo visualizar e refinar o design do consumidor.
  2. Consumer Basic: Um modelo básico de consumidor, fornecido para facilitar o desenvolvimento e a adaptação às necessidades específicas.

A seguir, será demonstrado como usar o Consumer Basic para construir um alerta personalizado. Neste exemplo, será desenvolvido um alerta para informar se há pessoas em idade escolar que não estão matriculadas na rede municipal de ensino.

Criando o Alerta

Para começar a criar um alerta, é necessário Instalar, Clonar e Configurar o Consumer Basic, seguindo as orientações descritas em Criando um Consumidor. Após essa etapa, você estará pronto para adaptá-lo às necessidades específicas do seu consumidor. Recomenda-se seguir os passos indicados em Criando um Consumidor e utilizar nomes que reflitam a funcionalidade desejada, como AlertWorker e outros similares, para manter clareza e organização.

Adaptações Iniciais

Após realizar as configurações iniciais, o próximo passo é criar um código simples para verificar se um alerta deve ser emitido. O Consumer Basic já possui uma estrutura básica com suporte à inclusão de mapas, gráficos e tabelas. Esses elementos podem ser construídos diretamente no código ou utilizando o Visual Builder, como descrito em seção específica.

No entanto, para este exemplo, o foco estará em implementar a lógica de verificação necessária para a emissão ou não de um alerta.

Código de Exemplo

Abaixo, segue um exemplo de código que verifica registros fictícios de pessoas e emite um alerta caso alguma delas, em idade escolar, não esteja matriculada na rede de ensino:

# Dados fictícios
pessoas = [
    {"nome": "Ana", "sobrenome": "Silva", "idade": 10, "matriculado": "não", "escola": None},
    {"nome": "João", "sobrenome": "Pereira", "idade": 8, "matriculado": "sim", "escola": "Centro Educacional Saber"},
    {"nome": "Maria", "sobrenome": "Oliveira", "idade": 15, "matriculado": "não", "escola": None},
    {"nome": "Carlos", "sobrenome": "Santos", "idade": 18, "matriculado": "sim", "escola": "Academia do Conhecimento"},
    {"nome": "Luiza", "sobrenome": "Costa", "idade": 7, "matriculado": "sim", "escola": "Instituto Educar"},
]

# Faixa etária considerada como "idade escolar"
IDADE_ESCOLAR_MIN = 4
IDADE_ESCOLAR_MAX = 17
emitir_alerta = False

# Verifica pessoas em idade escolar não matriculadas
for pessoa in pessoas:
    if (IDADE_ESCOLAR_MIN <= pessoa["idade"] <= IDADE_ESCOLAR_MAX
        and pessoa["matriculado"].lower() == "não"
    ):
        print(f"{pessoa['nome']} {pessoa['sobrenome']} tem {pessoa['idade']} anos, "
            "está em idade escolar e não está matriculado(a) na rede de ensino.")

        emitir_alerta = True

if emitir_alerta:
    titulo_alerta = f"Há pessoas em idade escolar que não estão matriculadas."
    ## Emite alerta
    answer.setAlert(titulo_alerta)

return answer

Explicação

O código acima realiza as seguintes ações:

  1. Define um conjunto de dados fictícios representando pessoas.

  2. Estabelece uma faixa etária para identificar pessoas em idade escolar (4 a 17 anos).

  3. Itera pelos registros, verificando quem está em idade escolar e não está matriculado na rede de ensino.

  4. Se ao menos uma pessoa atender a esses critérios, um alerta é gerado e exibido.

Testando a Aplicação

Para testar a aplicação, execute o seguinte comando no terminal:

   python3 main.py CONTRACT_TEST 001

Após a execução, o resultado estará disponível em http://127.0.0.1:8000/.

Próximos Passos

Os próximos passos a serem seguidos dependem muito da aplicação que desejamos desenvolver. Assim, iremos dar apenas uma visão geral do que pode-se fazer e onde devemos alterar.

Atualizando o Arquivo questions.json

O próximo passo é realizar a atualização do arquivo questions.json. Para mais detalhes sobre o funcionamento geral desse arquivo, leia a seção Configurando o arquivo questions.json.

É necessário informar no arquivo questions.json que se trata de um alerta, para isso basta incluir o atributo "alert" com valor true. Veja o exemplo abaixo:

{
    ...
    "questions": [
        {
            "consumer_question_id": "...",
            "version": "...",
            "consumer_theme_id": "...",
            "title": "...",
            "description": "...",
            "role_tag": "...",
            "consumer_sources": ["..."],
            "alert": true,    #novo atributo incluído
            "config_items": [
                {
                    ...
                }
            ]
        }
    ]
}

Caso deseja criar um alerta apenas para testes de alguma funcionalidade, existe uma opção para executar o teste a cada poucos minutos (não tendo que esperar dias, semanas ou meses que demoraria muito tempo). Essa execução ocorre a cada alguns minutos configurado pelo usuário. Para isso basta incluir o trecho (bloco) com id minutes_interval. Veja o exemplo abaixo:

{
    "questions": [
        {
            "consumer_question_id": "...",
            "version": "...",
            "consumer_theme_id": "...",
            "title": "...",
            "description": "...",
            "role_tag": "...",
            "alert": true,
            "consumer_sources": ["..."],
            "config_items": [
                {
                    ...
                },
                {   # opção incluída para testes a cada poucos minutos
                    "id": "minutes_interval",
                    "label": "Escolha a cada quantos minutos o alerta será verificado (obs.: esse parâmetro é apenas para testes)",
                    "type": "range", "min": 1, "max": 60, "step": 1, 
                    "required": "True"
                }
            ]
        }
    ]
}

Atenção: Remover o bloco minutes_interval quando colocar em produção para não sobrecarregar o sistema com muitas mensagens (alertas).

Escreva os Testes de Software

À medida que for desenvolvendo os códigos em Python desse novo consumidor crie testes de unidade, testes de contrato e testes de integração de forma a avaliar melhor o código antes de colocar a aplicação em produção. É recomendado que os testes de software sejam criados nessa ordem, pois assim fazemos a validação das partes menores do sistema para as partes maiores.

Com relação aos testes de contrato, o arquivo test_00X.py não precisa de alterações significativas, exceto uma possível atualização da mensagem de log informando o arquivo correto que está sendo executado. Já o arquivo answerRequest.json precisa ser alterado conforme os parâmetros da pergunta que o consumidor é capaz de responder. Nesse arquivo os atributos que devem ser alterado são: consumer_question_id, answer_request_id e data.

Fazendo a Implantação do Consumidor

Após o código ter sido desenvolvido e avaliado, precisamos fazer a implantação do nosso consumidor na plataforma do PGST.