Agendar e enviar

Um relatório desenhado é um relatório que alguém tem de ir buscar. Os agendamentos resolvem o caso mais comum sem escrever uma linha de código: "o pipeline comercial vai para a direcção todas as segundas às 8h".

"Enviar este relatório por email, sozinho, à hora marcada." É isso, e mais nada — o que precisar de mais faz-se com um script, e esta página explica quando.

Continuamos no relatório Oportunidades por conta da app Gestão de Clientes, com o agendamento Pipeline de segunda-feira.

#Os agendamentos de um relatório

Os agendamentos vivem no próprio relatório: abre o relatório e olha para o fim da coluna da esquerda, na secção Agendamentos. Cada linha é um envio marcado, com o resumo por baixo do nome — a hora, o fuso, o formato e para quem vai.

Um agendamento desligado aparece marcado como desligado. Os ícones à direita de cada linha editam e apagam.

Num relatório que ainda não tem nenhum, a lista mostra "Sem agendamentos." e só resta criar o primeiro:

#Criar um agendamento

1. Abre o relatório e clica no + da secção Agendamentos (ou no botão Acrescentar agendamento, no fim da lista).
2. Preenche a ficha.
3. Clica em Guardar.

#Quando

Campo	Notas
Nome	Identifica o agendamento. É por ele que aparece no histórico.
Frequência	Diária, semanal ou mensal.
À hora	A hora do envio.
Dias (frequência diária)	Todos, Úteis ou Fim-de-semana.
Dia da semana (frequência semanal)	De Seg a Dom.
Dia do mês (frequência mensal)	De 1 a 31.
Fuso horário	Por omissão Europe/Lisbon. É neste fuso que a hora é lida.

#O quê

Campo	Notas
Formato	PDF ou Excel.
Parâmetros	Um campo por cada parâmetro que o relatório declara. É com estes valores que ele corre.
Activo	Desligado, o agendamento fica registado mas não dispara.

No exemplo, o parâmetro Fase vai preenchido com Proposta e Fecho a partir de fica vazio — o mesmo relatório serve vários agendamentos, cada um com o seu recorte.

#Para quem

Há três formas de dizer o destino, e podem usar-se as três ao mesmo tempo:

Campo	Notas
Para	"Endereços de email separados por vírgula." Para quem não tem conta na app.
Utilizadores	"Utilizadores da app. Vai para o email do registo deles; quem não tiver email fica de fora."
Papéis	"Todos os utilizadores com este papel. Escolher o papel em vez do endereço mantém o agendamento certo quando alguém entra ou sai."

#O email

Assunto é a linha do email; vazio, usa o nome do relatório. Mensagem abre um editor próprio para o corpo:

O relatório vai em anexo, no formato escolhido, com o nome do documento. O corpo é só a mensagem que acompanha.

#O que acontece à hora marcada

1. O relatório é gerado no servidor, com os parâmetros do agendamento.
2. O ficheiro é anexado a um email e enviado pelo canal de email da app.
3. Fica registado o que aconteceu: o ficheiro gerado e quantos destinatários o aceitaram.

Se alguma coisa correr mal — o relatório falha, o canal de email não está configurado, um destinatário não tem endereço — fica registado e o agendador segue. Um envio que falha não trava os outros.

Um agendamento sem destinatários também não envia — fica registado "sem destinatários" e nada acontece.

#Quando um agendamento não chega

O atalho serve o caso comum. Precisas de um script Python quando queres:

• enviar só se houver linhas ("não mandes o mapa dos atrasos se não houver atrasos");
• um email por cliente, cada um com o seu recorte;
• guardar o ficheiro noutro sítio em vez de o enviar;
• gerar o documento a meio de um processo maior.

O SDK dos scripts faz exactamente isso:

from api_manager import reports, notify

r = reports.render("Oportunidades por conta", {"fase": "Proposta"})
notify.email(
    "Pipeline da semana",
    to=["direccao@exemplo.pt"],
    attachments=[{"filename": r["filename"], "content": r["base64"]}],
)

reports.render(...) recebe o nome ou o identificador do relatório, os parâmetros que ele declara e o formato ("pdf", por omissão, ou "xlsx"), e devolve o ficheiro pronto a gravar ou a anexar. A partir daí, o agendamento é o do script — com todas as opções que os Agendamentos dos scripts têm, incluindo recuperação do que ficou por correr.

#Gerar um relatório noutros sítios

Além dos agendamentos e dos scripts, um relatório pode ser gerado:

De onde	Como
Um ecrã da app	Num evento TypeScript, com o SDK dos ecrãs — abre o PDF ao utilizador ou devolve os bytes para lhes dares outro destino.
Um workflow	O passo Email anexa um relatório, gerado no momento do envio para o registo daquela execução. Ver Passos, decisões e esperas.
O desenho	Os botões Pré-visualizar e Excel, para conferir enquanto se desenha.

Em todos, o relatório corre com as permissões de quem o pede: um utilizador só vê no documento os registos que veria nos ecrãs. O âmbito dos dados é aplicado no servidor, também nos relatórios.

#Perguntas frequentes

O agendamento está activo e não recebi nada. Confere, por esta ordem: o canal de email da app está activo e testado; o agendamento tem destinatários; os destinatários têm email no registo; o relatório corre sem erro (usa Pré-visualizar com os mesmos parâmetros).

A hora está certa mas chegou uma hora depois. O Fuso horário do agendamento é o que manda, não o do servidor nem o de quem lê. Confirma que está em Europe/Lisbon (ou no fuso que queres).

Posso mandar o mesmo relatório a duas horas diferentes? Sim — cria dois agendamentos no mesmo relatório, cada um com o seu nome, hora, destinatários e parâmetros.

Apaguei um agendamento sem querer. Não há como voltar atrás. Volta a criá-lo: um agendamento é só uma ficha com hora e destinatários, e leva um minuto.