1. Introdução

O sistema permite que consultas customizadas sejam enviadas periodicamente a um determinado destinatário, ou que sejam salvas, nos formatos de CSV ou Excel, em pontos de extremidades cadastrados no sistema.

Exemplo: O gestor "X" quer receber via e-mail periodicamente toda segunda-feira as informações de uma determinada consulta customizada disponibilizada para a sua empresa.

A função do agendamento tem como comportamento padrão a criação de um evento de notificação que será utilizado posteriormente na criação de notificadores. Além disso, também é possível, ao invés de criar o evento de notificação, gerar um arquivo CSV ou Excel que será enviado para um ponto de extremidade selecionado na criação do agendamento.

2. Permissão de acesso

Para ter acesso a esta funcionalidade, a permissão "Agendar Consulta Customizada" deverá ser concedida aos perfis responsáveis por controlar tal função.

Para conceder tal permissão, leia o artigo: Segurança - Configurar acesso (NOVO).

3. Acesso

3.1 Possuindo a permissão citada acima, acesse a funcionalidade pelo seguinte caminho: Configurações > Notificadores > Agendamento de consulta.

3.2 Feito o acesso, a tela abaixo será exibida, na qual serão listados os agendamentos já realizados.

Quando o tipo de saída for um evento, será exibido um ícone indicando se o evento está vinculado a um notificador ou não. Quando o tipo de saída for um arquivo (CSV ou Excel), será exibido o ponto de extremidade para o qual o arquivo será enviado.

4. Realizando um novo agendamento

4.1 Para iniciar o procedimento de agendamento, clique no botão de "Inclusão".

4.2 Após o clique no botão de "Inclusão", um modal será exibido contendo alguns campos que deverão ser preenchidos na aba "Definir Execução". O primeiro passo a ser feito é informar a consulta que será aplicada.

4.3 Após isto, o campo "Nome" será automaticamente preenchido com o nome da consulta definida, porém altere o mesmo se for necessário

Além disso, o quadro "Parâmetros" será disponibilizado para que seja definido o contexto que será aplicado para a geração das informações dos diferentes tipos de consultas customizadas.

Os tipos de parâmetro irão variar de acordo os parâmetros existentes na consulta.

No caso do parâmetro data, quatro tipos poderão ser aplicados: Hoje, Data fixa, Data dinâmica, Sem valor.

Hoje: Define que o dia da execução da consulta será levando em consideração para definir quais as informações serão enviadas para o destinatário.

Exemplo: Caso o dia da execução da consulta seja 09/01/2017, as informações serão exibidas tomando como base tal data.

Data Fixa: Serão exibidas as informações levando-se em conta a data informada.

Data dinâmica: Utiliza-se um contexto com base no dia que a consulta foi executada.

Exemplo: Exibir informações 15 dias após o dia da execução.

Sem valor: Equivale a deixar o parâmetro em branco. Este não terá valor na execução da consulta.

4.4 Em seguida, defina a frequência na qual as informações da consulta serão enviadas aos destinatários. Defina também o status da consulta (Ativa/Inativa).

4.5 O próximo passo é definir o tipo de saída da consulta agendada. Esta opção definirá se os resultados da consulta serão emitidos em um evento ou salvos em um arquivo CSV ou Excel.

Evento: Após a execução da consulta, será gerado um evento contendo seus resultados, que poderá ser utilizado posteriormente em notificadores.

CSV: Após a execução da consulta, será gerado um arquivo CSV contendo seus resultados e este será enviado para um ponto de extremidade previamente cadastrado no sistema, à escolha do usuário.

Excel: Após a execução da consulta, será gerado um arquivo Excel contendo seus resultados e este será enviado para um ponto de extremidade previamente cadastrado no sistema, à escolha do usuário.

Para maiores informações sobre o cadastro de pontos de extremidade, leia o artigo: Integração - Pontos de Extremidade.

4.5.1 Caso seja selecionado o tipo de saída CSV, serão apresentados novos campos no formulário de agendamento de consulta, relevantes à geração do arquivo CSV.

Será necessário, ainda, selecionar o ponto de extremidade para onde o arquivo será enviado.

Pontos de extremidade dos tipos Azure Storage, S3 e SFTP permitem que o usuário defina um nome personalizado para o arquivo, selecione a concatenação ou não da data e hora da exportação no nome do arquivo, e selecione a sobrescrita ou não do arquivo caso ele já exista no ponto de extremidade selecionado.

Já pontos de extremidade do tipo API não permitem as personalizações mencionadas acima, e o arquivo será enviado para o ponto de extremidade com o nome da consulta.

4.5.2 Caso seja selecionado o tipo de saída Excel, serão apresentados os campos referentes à seleção do ponto de extremidade e à personalização do nome do arquivo e sua sobrescrita.

Assim como no caso do CSV, pontos de extremidade do tipo API não permitem as personalizações mencionadas acima, e o arquivo será enviado para o ponto de extremidade com o nome da consulta.

4.6 Será possível ter uma pré-visualização, na aba "Definir Exemplo", das informações que serão exibidas de acordo com o parâmetro aplicado. Para isto, informe o parâmetro e clique em "Gerar exemplo".

Em seguida, o exemplo será exibido de acordo com a especificação do parâmetro.

No exemplo abaixo, por se tratar da consulta "Aniversariantes do mês", foram exibidos todos os aniversariantes do mês de janeiro, pois o parâmetro aplicado foi a data 01/01/2024.

4.7 De volta a aba principal, após inserir todas as informações necessárias, clique em "Salvar" para confirmar o agendamento.

4.8 Após o clique em "Salvar", o agendamento será listado na tela principal da funcionalidade.

Quando o tipo de saída for um evento, será exibido um ícone indicando se o evento está vinculado a um notificador ou não. Quando o tipo de saída for um arquivo (CSV ou Excel), será exibido o ponto de extremidade para o qual o arquivo será enviado.

4.9 Após a realização do agendamento, quando o tipo de saída for Evento, o mesmo poderá ser relacionado a um notificador.

Durante o procedimento de criação de um notificador, no campo "Tipo de Evento", os agendamentos criados serão identificados com o prefixo "RS".

5. Editando um agendamento realizado

5.1 Caso seja necessário realizar alterações em um agendamento realizado, dê um duplo clique no agendamento desejado.

5.2 Em seguida, faça as alterações que desejar e finalize clicando em "Salvar".

6. Excluindo um agendamento de consulta

6.1 Para excluir um agendamento, basta selecionar (marcar) os agendamentos desejados e finalizar clicando em "Remover".

7. Permissões necessárias para enviar arquivos para pontos de extremidade

Quando os tipos de saída selecionados para a consulta agendada forem CSV ou Excel, o ponto de extremidade selecionado para o envio do arquivo deve possuir as permissões adequadas para escrita e/ou leitura no local de armazenamento. São elas:

Tipo de ponto de extremidade	Permissões necessárias
API	As credenciais cadastradas no ponto de extremidade deverão permitir que seja feito um POST para a rota informada.
Azure Storage	O usuário informado na string de conexão deve ter a permissão "Put Blob" no Azure Storage, para que seja possível fazer o upload de arquivos.
S3	Para fazer o upload de arquivos, é necessário que o usuário informado possua a permissão "s3:PutObject" no bucket informado. Caso deseje evitar que arquivos existentes no bucket do S3 sejam sobrescritos, o usuário informado deverá ter também as permissões "s3:GetObject" e "s3:ListBucket".
SFTP	O usuário informado deve ter permissão de leitura e escrita no caminho informado.

8. Método de envio dos arquivos gerados para pontos de extremidade

Quando os tipos de saída selecionados para a consulta agendada forem CSV ou Excel, o arquivo gerado pela execução da consulta será disponibilizado através do ponto de extremidade selecionado. Para pontos de extremidade dos tipos Azure Storage, S3 e SFTP, será feito o upload do arquivo diretamente para o caminho configurado no ponto de extremidade. Para pontos de extremidade do tipo API, será enviado um payload, através de requisição POST, contendo o nome do arquivo, url para download do mesmo e data de expiração da url, como ilustrado no exemplo abaixo:

Exemplo de payload enviado para ponto de extremidade do tipo API:

{
  "name": "1 - teste relatório.csv",
  "url": "https://url_de_exemplo/xxxxxxxxxxxxxxx",
  "validUntil": "2024-03-20T16:37:12.7381147-03:00"
}

9. Executando manualmente consultas agendadas

9.1 Para executar manualmente uma ou mais consultas agendadas fora do horário programado, basta selecionar (marcar) os agendamentos desejados e clicar no botão de "play" no menu de contexto. As consultas selecionadas vão, então, ser adicionadas na fila de execução e serão executadas em breve.

Qualquer consulta que já tenha sido executada pelo menos uma vez, manualmente ou no horário programado, terá o registro de status da sua última execução. Em caso de erro, passar o mouse sobre o status exibirá, em forma de tooltip, detalhes sobre o erro ocorrido.

Navegador não compatível