Fluig na Prática #02: Como tornar anexos obrigatórios no TOTVS Fluig

Fluig na Prática #02: Como tornar anexos obrigatórios no TOTVS Fluig Em muitos processos empresariais, o envio de documentos é indispensável para que uma solicitação possa seguir para análise ou aprovação. Comprovantes, contratos, propostas, notas fiscais, documentos pessoais e evidências são exemplos de arquivos que precisam acompanhar determinadas solicitações. Quando o processo permite que o usuário avance sem anexar esses documentos, surgem problemas como: solicitações incompletas; devoluções para correção; aumento do retrabalho; atraso nas aprovações; falta de evidências; perda de rastreabilidade.

Neste artigo da série Fluig na Prática, vamos mostrar como impedir que uma atividade seja concluída sem que pelo menos um documento tenha sido anexado. O TOTVS Fluig reúne recursos para gestão de processos, formulários e documentos, permitindo organizar informações e movimentações em um mesmo ambiente. Exemplo prático: solicitação de reembolso Imagine um processo de Solicitação de Reembolso com o seguinte fluxo: Solicitação → Análise do gestor → Financeiro → Conclusão Na primeira atividade, o colaborador preenche informações como: tipo de despesa; data da despesa; valor; justificativa; centro de custo.

Além dessas informações, ele precisa anexar o comprovante da despesa. O problema acontece quando o usuário preenche o formulário e envia a solicitação sem adicionar o comprovante. Nesse caso, o gestor recebe uma solicitação incompleta e precisa devolvê-la para correção.

A melhoria será criar uma regra que impeça o avanço do processo enquanto nenhum anexo tiver sido incluído. Onde implementar a validação A validação pode ser realizada no evento de processo: beforeTaskSave Esse evento é executado antes de a tarefa ser salva ou movimentada. Ele permite interromper a operação por meio de uma exceção com throw, exibindo uma mensagem ao usuário.

Nos eventos do processo, a variável global hAPI disponibiliza métodos da API de Workflow. Para consultar os anexos relacionados à solicitação, utilizaremos: hAPI.listAttachments() Código completo No exemplo abaixo, consideramos: atividade de preenchimento: código 4; próxima atividade: código 5; obrigatoriedade de pelo menos um anexo. function beforeTaskSave(colleagueId, nextSequenceId, userList) { var atividadeAtual = parseInt(getValue("WKNumState")); var atividadeSolicitacao = 4; var atividadeAnaliseGestor = 5; /* * A validação será executada somente quando: * 1.

O usuário estiver na atividade de solicitação; * 2. Estiver enviando para a análise do gestor. */ if ( atividadeAtual === atividadeSolicitacao && parseInt(nextSequenceId) === atividadeAnaliseGestor ) { var anexos = hAPI.listAttachments(); if (anexos === null || anexos.size() === 0) { throw "É obrigatório anexar pelo menos um comprovante antes de enviar a solicitação."; } } } Os códigos 4 e 5 são apenas exemplos.

Eles devem ser substituídos pelos códigos das atividades existentes no seu processo. Como a regra funciona Quando o usuário clicar para enviar a solicitação, o Fluig executará o evento beforeTaskSave. O código verifica: qual é a atividade atual; para qual atividade o processo será enviado; quantos anexos existem na solicitação.

Caso nenhum arquivo tenha sido anexado, a movimentação será interrompida e o usuário receberá a mensagem: É obrigatório anexar pelo menos um comprovante antes de enviar a solicitação. Depois que o documento for adicionado, o usuário poderá enviar a atividade normalmente. Validando uma quantidade mínima Em alguns processos, pode ser necessário exigir mais de um documento.

Por exemplo, em um processo de contratação de fornecedor, podem ser obrigatórios: contrato social; comprovante bancário; certidão; documento do representante. Para exigir pelo menos três arquivos, basta alterar a condição: function beforeTaskSave(colleagueId, nextSequenceId, userList) { var atividadeAtual = parseInt(getValue("WKNumState")); var atividadeCadastro = 4; var proximaAtividade = 5; var quantidadeMinima = 3; if ( atividadeAtual === atividadeCadastro && parseInt(nextSequenceId) === proximaAtividade ) { var anexos = hAPI.listAttachments(); var quantidadeAnexos = anexos !== null ? anexos.size() : 0; if (quantidadeAnexos < quantidadeMinima) { throw "Anexe pelo menos " + quantidadeMinima + " documentos antes de enviar a solicitação."; } } } Validando apenas em uma decisão específica Em alguns processos, o documento é obrigatório somente quando determinada opção for selecionada.

Considere um campo chamado: <select name="tipoSolicitacao" id="tipoSolicitacao"> <option value="">Selecione</option> <option value="REEMBOLSO">Reembolso</option> <option value="ADIANTAMENTO">Adiantamento</option> </select> O comprovante será obrigatório apenas quando o tipo for REEMBOLSO. function beforeTaskSave(colleagueId, nextSequenceId, userList) { var atividadeAtual = parseInt(getValue("WKNumState")); var tipoSolicitacao = hAPI.getCardValue("tipoSolicitacao"); if ( atividadeAtual === 4 && parseInt(nextSequenceId) === 5 && tipoSolicitacao === "REEMBOLSO" ) { var anexos = hAPI.listAttachments(); if (anexos === null || anexos.size() === 0) { throw "Para solicitações de reembolso, o comprovante da despesa é obrigatório."; } } } Com essa abordagem, a regra é aplicada somente quando realmente necessária. Validando anexos em diferentes atividades Um processo pode exigir documentos em momentos distintos.

Exemplo: na abertura, o solicitante envia o comprovante; na análise, o gestor envia um parecer; no financeiro, é anexado o comprovante de pagamento. function beforeTaskSave(colleagueId, nextSequenceId, userList) { var atividadeAtual = parseInt(getValue("WKNumState")); var anexos = hAPI.listAttachments(); var quantidadeAnexos = anexos !== null ? anexos.size() : 0; if (atividadeAtual === 4 && quantidadeAnexos < 1) { throw "Anexe o comprovante da despesa antes de enviar a solicitação."; } if (atividadeAtual === 10 && quantidadeAnexos < 2) { throw "Anexe o parecer do gestor antes de concluir a análise."; } if (atividadeAtual === 15 && quantidadeAnexos < 3) { throw "Anexe o comprovante de pagamento antes de finalizar o processo."; } } Nesse exemplo, a quantidade total esperada aumenta conforme o processo avança.

Essa estratégia funciona, mas exige atenção: o código está contando todos os anexos existentes na solicitação, e não identificando exatamente qual documento foi incluído em cada atividade. Atenção: contar anexos não identifica o tipo do documento A validação simples confirma apenas que existe determinado número de anexos. Ela não garante que o arquivo enviado seja realmente: uma nota fiscal; um contrato; um comprovante; uma certidão; um documento específico.

O usuário pode anexar qualquer arquivo e, tecnicamente, a quantidade será atendida. Para controles mais rigorosos, existem algumas alternativas: padronizar o nome dos arquivos; utilizar campos específicos no formulário; criar uma tabela de documentos obrigatórios; registrar o tipo de documento selecionado; integrar o processo com o GED; criar componentes específicos de upload; aplicar validações adicionais no formulário. Quando o documento anexado a uma solicitação utiliza a opção de carregamento de arquivos, ele não é automaticamente publicado como documento no ECM; essa publicação é uma operação diferente e pode ser feita quando necessária.

Exemplo com campo de confirmação Outra opção é combinar o anexo com um campo de confirmação: <label> <input type="checkbox" name="confirmacaoComprovante" id="confirmacaoComprovante" value="sim" > Confirmo que anexei o comprovante da despesa. </label> Validação: function beforeTaskSave(colleagueId, nextSequenceId, userList) { var atividadeAtual = parseInt(getValue("WKNumState")); var confirmacao = hAPI.getCardValue("confirmacaoComprovante"); var anexos = hAPI.listAttachments(); var quantidadeAnexos = anexos !== null ? anexos.size() : 0; if (atividadeAtual === 4 && parseInt(nextSequenceId) === 5) { if (confirmacao !== "sim") { throw "Confirme que o comprovante foi anexado."; } if (quantidadeAnexos === 0) { throw "Nenhum comprovante foi localizado.

Anexe o documento antes de continuar."; } } } O campo de confirmação não substitui a validação técnica, mas ajuda a orientar o usuário. Como configurar no Fluig Studio 1. Abra o projeto do processo No Fluig Studio, localize o projeto correspondente ao processo que será alterado.

2. Abra o diagrama Acesse o diagrama BPMN e identifique o código da atividade em que o anexo deve ser obrigatório. 3.

Crie ou edite o evento Abra os eventos do processo e localize: beforeTaskSave Caso o evento ainda não exista, crie um novo arquivo de evento com esse nome. 4. Adicione o código Inclua a validação, ajustando: atividade atual; próxima atividade; quantidade mínima; mensagem apresentada; condições do processo.

5. Exporte e publique Salve o projeto, exporte o processo e publique a nova versão no ambiente Fluig. 6.

Execute os testes Inicie uma nova solicitação e teste os seguintes cenários: envio sem anexo; envio com um anexo; envio com vários anexos; envio para diferentes decisões; retorno de atividade; movimentação pelo aplicativo; reabertura ou correção da solicitação. Resultado esperado Tentativa sem documento O sistema impede o avanço e mostra: É obrigatório anexar pelo menos um comprovante antes de enviar a solicitação. Tentativa com documento A atividade é movimentada normalmente.

Consulta posterior O arquivo permanece associado à solicitação e pode ser consultado durante as próximas etapas, conforme as permissões existentes. Boas práticas Valide somente na atividade necessária Evite aplicar a regra indiscriminadamente em todo o processo. Utilize o código da atividade atual e, quando necessário, a próxima atividade.

Use mensagens claras Evite mensagens genéricas como: Erro ao enviar. Prefira: Anexe o comprovante da despesa antes de enviar a solicitação para aprovação. A mensagem deve dizer exatamente o que está faltando.

Considere os retornos do processo Quando uma atividade retorna para correção, verifique se a validação deverá ser executada novamente. Teste no navegador e no aplicativo Quando o processo for utilizado no My Fluig, teste também a movimentação pelo aplicativo. O aplicativo permite acompanhar e movimentar solicitações, inclusive em diferentes contextos de acesso.

Não dependa apenas do nome do arquivo O nome pode ser alterado pelo usuário. Em processos críticos, utilize controles complementares. Registre a regra na documentação Documente: em qual atividade a validação é executada; quantos documentos são obrigatórios; quais documentos são esperados; quais decisões ativam a regra; qual mensagem é apresentada.

Conclusão Tornar anexos obrigatórios no TOTVS Fluig é uma implementação relativamente simples, mas que pode melhorar significativamente a qualidade dos processos. Com essa validação, a empresa reduz solicitações incompletas, evita devoluções desnecessárias e garante que os responsáveis pelas próximas etapas recebam as informações necessárias para executar suas atividades. Mais do que obrigar o envio de arquivos, a regra contribui para: qualidade da informação; rastreabilidade; padronização; redução de retrabalho; maior velocidade nas aprovações; segurança na tomada de decisão.

Na FREEDOM, trabalhamos com o TOTVS Fluig desde as primeiras gerações da plataforma — passando pelo WebDesk, TOTVS ECM e ECM até o Fluig atual — desenvolvendo processos, formulários, integrações, portais, widgets e soluções personalizadas para diferentes operações. Seu processo precisa controlar documentos obrigatórios ou possui alguma regra específica de anexos? Fale com a FREEDOM.