1673 Tarefas Servidor

Area_Ferramentas

Este recurso permite cadastrar tarefas automáticas no Touch Comp ERP. Um cadastro define o que será executado (um perfil de Smart Component), quando será executado e, opcionalmente, para quem enviar o resultado por e-mail. A tela também pode exibir tarefas técnicas do tipo Classe, mas novos cadastros são criados como Smart Component e o tipo não pode ser alterado na tela.

Antes de começar

Tenha acesso ao cadastro de tarefas e um perfil de Smart Component já configurado.
Confirme com a equipe de TI que o agendador está habilitado no servidor responsável. Salvar uma tarefa não garante, por si só, que o agendador esteja em execução.
Para receber notificações, tenha um servidor de e-mail cadastrado e os endereços dos destinatários.

Como cadastrar

Abra o cadastro de tarefas em Ferramentas > TI > Configurações > Tarefas.
Crie um registro e preencha a Descrição; use Observação para registrar a finalidade da rotina.
Selecione o Perfil de Smart Component que deverá ser executado.
Na aba Intervalo, informe o período de execução em minutos ou uma expressão de agendamento válida.
Na aba Parâmetros, revise os valores que serão enviados ao componente. Preencha os itens obrigatórios.
Se desejar notificações, configure a aba Notificação Email.
Salve o registro e deixe o Status ativo quando quiser que ele participe do agendamento.

É possível criar um novo cadastro ou clonar um existente. Ao clonar, revise principalmente perfil, intervalo, parâmetros e destinatários antes de ativar.

Campos do cadastro

Campo	Finalidade
Status	Define se a tarefa está ativa. Somente registros ativos são carregados pelo agendador.
Habilitada para uso do cliente	Indicador exibido sem edição nessa tela. Novos registros desse recurso são criados com o indicador habilitado.
Descrição	Nome da tarefa; obrigatório.
Observação	Informação complementar para identificação da rotina.
Tipo de tarefa	Exibido sem edição. Novos registros usam Smart Component; tarefas técnicas preexistentes podem ser do tipo Classe.
Perfil de Smart Component	Perfil que contém o componente a executar. Obrigatório para tarefas do tipo Smart Component.

Intervalo

O campo Intervalo de execução é obrigatório e aceita:

Um número inteiro, interpretado como intervalo em minutos. Exemplo: 60 para repetir a cada 60 minutos, contado a partir do disparo do agendador.
Uma expressão cron do Quartz com seis campos separados por espaços: segundos, minutos, horas, dia do mês, mês e dia da semana. Exemplo: 0 0 21 * * ? para executar diariamente às 21h.

Atenção: a ajuda da tela mostra uma coluna adicional de Ano e sugere separar vários períodos por ponto e vírgula (;). A validação atual do cadastro, porém, aceita somente um número ou uma expressão cron de seis campos. Para mais de um horário, use cadastros separados até que essa divergência seja corrigida.

Parâmetros

A aba mostra a descrição, a indicação de obrigatoriedade e o valor de cada parâmetro associado à tarefa. O campo Valor é editável. Os nomes e os valores esperados dependem do Smart Component escolhido. Revise-os antes de ativar a tarefa, especialmente se tiver clonado outro cadastro.

Notificação por e-mail

Opção de envio	Quando envia
Não enviar	Não envia mensagens.
Enviar sempre	Envia após as execuções.
Somente quando houver falhas	Envia se o resultado contiver erros.
Quando houver advertências	Envia se o resultado contiver advertências.

Ao selecionar uma opção de envio diferente de Não enviar, informe Destinatários, Servidor de e-mail e Título do e-mail. A tela orienta separar vários destinatários com ponto e vírgula (;). O resultado enviado inclui o nome e o identificador da tarefa e os detalhes da execução.

Execução e acompanhamento

O agendador carrega os cadastros ativos e executa o Smart Component indicado pelo perfil, repassando os valores dos parâmetros da tarefa. A execução registra resultado, erros e advertências. Em caso de alteração no cadastro, confirme com a equipe de TI se é necessário recarregar o agendador para aplicar a nova configuração; este cadastro não aciona esse recarregamento diretamente. Os registros antigos de execução são removidos automaticamente após cinco dias quando o agendador é iniciado.

Se uma tarefa não executar, verifique o Status, o perfil, o intervalo, os parâmetros e se o agendador está habilitado no servidor. Se o e-mail não chegar, confira a opção de envio, os destinatários e o servidor de e-mail. Somente quando houver falhas e Quando houver advertências não enviam mensagens em execuções que não tenham o respectivo resultado.

Integração por API

As operações abaixo pertencem à API autenticada. O caminho-base é /auth/ferramentas/ti/tarefas/tasks/; acrescente o endereço-base da instalação e use as credenciais/permissões exigidas pelo ERP. As respostas seguem os envelopes JSON da API, com campos como status, message e result conforme a operação.

Método e caminho	Uso
`GET /auth/ferramentas/ti/tarefas/tasks/show`	Obtém os dados iniciais para um novo cadastro, incluindo opções de seleção.
`GET /auth/ferramentas/ti/tarefas/tasks/clone-entity/{id}`	Carrega os dados de um cadastro existente para criar uma cópia, respeitando as permissões da operação.
`PUT /auth/ferramentas/ti/tarefas/tasks/save`	Cria ou atualiza um cadastro; envia JSON no envelope de entrada da API, em `input`.
`GET /auth/ferramentas/ti/tarefas/tasks/get-smart-component-pref/{idSmartComponentPref}`	Consulta o perfil de Smart Component pelo identificador.
`GET /auth/ferramentas/ti/tarefas/tasks/get-servidor-email/{idServidorEmail}`	Consulta o servidor de e-mail pelo identificador.

Parâmetros para criar ou atualizar

No objeto input, use os campos abaixo. Para atualizar, inclua também identificador da tarefa existente. A autenticação fornece o usuário, a empresa e o grupo de usuários da operação; não envie esses dados como substitutos dos campos da tarefa.

Campo JSON	Tipo / valor	Observação
`taskName`	Texto	Descrição obrigatória.
`intervaloExecucao`	Texto	Número de minutos ou expressão cron de seis campos; obrigatório.
`tipoTask`	Número	`1` = Smart Component; `0` = Classe. Para novos cadastros deste recurso, use `1`.
`smartComponentPrefIdentificador`	Número	Identificador do perfil; obrigatório para Smart Component.
`ativo`	Número	`1` = ativo; `0` = inativo.
`paramConf`	Lista	Parâmetros da tarefa; cada item contém `nomeParametro`, `valorParametro` e, quando aplicável, `identificador`, `descricaoParametro` e `obrigatorio`.
`enviarEmailStatus`	Número	`0` = não enviar; `1` = sempre; `2` = falhas; `3` = advertências.
`tituloEmail`, `destinatarios`, `servidorEmailIdentificador`	Texto, texto e número	Necessários quando houver envio de e-mail.
`observacao`	Texto	Informação complementar.

Exemplo ilustrativo do corpo para PUT .../save:

{
  "input": {
    "taskName": "Atualização diária",
    "intervaloExecucao": "0 0 21 * * ?",
    "tipoTask": 1,
    "smartComponentPrefIdentificador": 123,
    "ativo": 1,
    "enviarEmailStatus": 0,
    "paramConf": [
      { "nomeParametro": "exemploParametro", "valorParametro": "valor" }
    ]
  }
}

Substitua o identificador do perfil e os parâmetros pelos valores reais do componente. Para integrações de produção, obtenha primeiro um cadastro pela API e use sua estrutura como referência para os campos aceitos no ambiente.

Problemas e soluções

Não recebo email, ou tarefa não funciona

Neste caso algum erro está acontecendo ao executar a tarefa, ou o servidor WEB não está em execução. Tente:

Verifique se a Task/tarefa está ativa.
Verifique se o Wildfly ou Docker estão iniciados como serviços.
Verifique a seção problemas e soluções de acordo com a tarefa em si. Cada tarefa tem suas particularidades. Por exemplo, se a task for de Envio de Emails BI, acesse 1126_Envio_Email_Business_Intelligence
Reiniciar o serviço Wildfly ou o Docker, ou se preferir o computador;
Ative o envio de emails sobre a tarefa, conforme a seção "Notificação/Email" e aguarde alguns instantes, conforme tempo de execução entre as tarefas. Caso queira, reinicie o serviço, e logo ao subir o ERP irá executar novamente a tarefa, se não estiver utilizando uma expressão para determinar a execução da tarefa.
Mude o tempo de envio. Experimente se estiver utilizando expressão, informar o tempo de recorrência de envio em minutos.
Execute o Wildfly ou Docker em modo depuração a acompanhe o log. Quando a tarefa é iniciada, é exibido um log. Verifique se está ocorrendo algum erro.
Caso o problema persista, contate o suporte.

Mudanças nas configurações não surtem efeito

Ao efetuar alguma mudança na configuração da Task, será necessário reiniciar o serviço/Docker(Mentor WEB, Touch Comp API) para que tais alterações surtam efeito.

Tarefa não inicia/executa (Versão 20230401 em diante)

É necessário mapear e configurar corretamente o recurso 493_Opcoes_Sistema, para que o sistema possa iniciar as tarefas.