Atividade de serviço no Fluig: servicetask na prática

A atividade de serviço é a ferramenta certa quando um processo precisa conversar com outro sistema sem deixar o usuário esperando. Ela roda um script separado, com tentativas automáticas e um caminho para o erro desenhado no próprio fluxo.

Automatizada ou imediata

Existem dois modos, conforme a documentação da TOTVS:

Automatizada. É assíncrona. A solicitação entra em uma fila no servidor, o usuário segue a vida e o script roda quando chegar a vez. Em caso de sucesso, avança sozinha. Em caso de erro, tenta de novo e, ao esgotar as tentativas, vai para o fluxo de erro.

Imediata. É síncrona. O script roda logo após o afterStateEntry. Se der erro, a movimentação é cancelada e o usuário vê a mensagem.

Use a automatizada para integrações e tarefas demoradas. Use a imediata quando o usuário precisa saber na hora se deu certo.

Como configurar

Na atividade, defina:

• Execução: automatizada ou imediata.
• Tentativas: quantas vezes o servidor repete o script em caso de erro.
• Mensagem: texto gravado no histórico quando dá certo.
• Frequência: o intervalo entre as execuções.

O código da atividade define o nome do script. Uma atividade servicetask9 usa a função de mesmo nome:

function servicetask9(attempt, message) {
    var solicitacao = getValue("WKNumProces");
    log.info("[COMPRAS][S9] tentativa " + attempt + " solicitacao " + solicitacao);

    var resposta = enviarAoErp();

    if (!resposta.sucesso) {
        throw "ERP recusou: " + resposta.mensagem;
    }

    hAPI.setCardValue("numeroPedido", resposta.numero);
    return true;
}

attempt indica a tentativa atual, e message traz o erro da tentativa anterior. Na primeira execução, message vem vazio.

Cada tentativa com erro gera um complemento no histórico da solicitação, o que ajuda bastante no diagnóstico.

O fluxo de erro

Desenhe o evento intermediário de captura de erro e aponte para uma atividade humana. Sem isso, a falha fica sem destino claro.

Essa atividade deve dizer:

• Quem recebe o problema, de preferência um grupo.
• O que deu errado, com a mensagem do sistema.
• O que a pessoa pode fazer: corrigir e reenviar para a atividade de serviço, ou seguir outro caminho.

Assim, um erro de cadastro é resolvido por quem entende do cadastro, sem chamado para a TI.

Cuidados importantes

Reexecutar exige idempotência. O caso clássico: o ERP grava, a resposta demora, o Fluig recebe timeout e tenta de novo. Sem proteção, surgem dois registros. Antes de usar tentativas em gravações, leia sobre pedidos duplicados na integração.

Pegar o erro e retornar true esconde a falha. Isso faz a solicitação avançar como se tudo estivesse certo. Use apenas quando o erro realmente não importar.

Não crie uma tempestade de execuções. A TOTVS alerta que uma atividade com timer curto e muitas tentativas pode acumular muitas solicitações rodando ao mesmo tempo depois de uma falha. Se o ERP cair, centenas de solicitações tentam ao mesmo tempo. Prefira um número moderado de tentativas e um intervalo maior.

A transação dura o script. A transação começa quando o script inicia e termina depois que ele volta ao produto. Scripts longos seguram recursos, então defina um timeout nas chamadas externas.

Trate indisponibilidade como caso normal. Um ERP fora do ar por dez minutos não deveria exigir ação manual. Ajuste as tentativas para sobreviver a isso.

Atividade de serviço ou evento condicional?

Quando o processo precisa fazer algo, use a atividade de serviço. Quando precisa esperar algo, como um retorno de outro sistema ou uma data, considere o evento intermediário condicional, reavaliado periodicamente. Em processos com recorrência ou dependência externa, os dois se complementam.

Evite colocar lógica pesada no condicional, porque ele é reavaliado para cada solicitação em espera.

Como testar

1. Teste o caminho feliz.
2. Force um erro do serviço e veja o histórico.
3. Esgote as tentativas e confira o fluxo de erro.
4. Reenvie da tarefa de erro e confirme que nada duplicou.
5. Simule o sistema externo fora do ar.
6. Teste o timeout: resposta demorada depois de o destino gravar.

O restante do código de integração está em como chamar a API REST do Protheus pelo Fluig.

Perguntas frequentes

O que é servicetask no Fluig?

É a função do script ligada a uma atividade de serviço. O número no nome corresponde ao código da atividade no diagrama.

Como fazer a atividade de serviço cair no fluxo de erro?

Lance uma exceção no script. Ao esgotar as tentativas, a solicitação segue pelo evento de captura de erro.

Devo usar execução automatizada ou imediata?

Automatizada para integrações que podem demorar ou falhar. Imediata quando o usuário precisa da resposta para continuar.

Integrações com tentativas, fluxo de erro e proteção contra duplicidade dão mais trabalho no começo e evitam incidentes depois. A MyQube constrói e corrige integrações Fluig e Protheus. Vamos conversar.