Fluxo de Integração

Sumário

1. Conceito

O Fluxo de Integração disponibiliza concepções de processamento de dados, chamadas de ações, permitindo um alto nível de customização na elaboração e manutenção de processos de integração.

O que pode ser feito através do Fluxo de Integração:

• Disponibilizar Serviços REST;
• Executar tarefas agendadas;
• Realizar leituras de arquivos;
• Realizar conversões: String para Json, Json para XML, XML para Json, etc;
• Gerar planilhas Excel e outros relatórios;
• Enviar e-mails;
• Executar códigos Java.

2. Menu de Acesso

• Realize o login na Plataforma do CONNECT;
• Selecione Sobre;
• Clique em Fluxo de Integração.

3. Funcionalidades

3.1 Listagem de Fluxos de Integração

A tela de listagem exibe todos os Fluxos de Integração do ambiente, permitindo que os usuários visualizem o Nome do Método (equivalente ao endpoint gerado para a chamada da integração), última data de modificação, indicador de integração ativa, tipo do modo de ativação e contador de falhas consecutivas nas últimas execuções.

Na aba de ações é possível iniciar o processamento do fluxo, ir para a tela de edição, deletar o registro, exportar (para backups ou migração) ou navegar para a tela de monitoramento da integração.

4. Criando um Fluxo de Integração

4.1 Fluxo REST

Disponibiliza um endpoint que pode ser chamado por sistemas externos.

Campos disponíveis e suas respectivas funcionalidades:

• Ativo: Define se o endpoint pode ser chamado;
• Mostrar URL: Exibe a URL do endpoint realiza a chamada do Fluxo de Integração;
• Nome do Fluxo: Identificador do endpoint;
• Tipo de Integração: REST;
• Fila de integração: Contexto de execução dentro do ambiente, escopo de filas de processamento;
• Máximo de falhas consecutivas: Define o número máximo de falhas consecutivas antes de enviar uma notificação de instabilidade (ver Notificações);
• Descrição do Fluxo: Editor de texto que permite criar documentações e contextualizações referentes ao Fluxo;
• Método HTTP do Serviço Web: Método da requisição de chamada do Fluxo de Integração;
• Tipo de Autorização do Serviço Web: Nenhum (público), Bearer (código fixo) ou Basic Auth (associado a um registro de Credencial da plataforma);
• Token de Autenticação: Token ou Credencial a ser associado ao Tipo de Autorização do Serviço Web.

4.2 Fluxo Agendado (JOB)

Campos disponíveis e suas respectivas funcionalidades:

• Ativo: Define se o endpoint pode ser chamado;
• Nome do Fluxo: Identificador do endpoint;
• Tipo de Integração: JOB;
• Fila de integração: Contexto de execução dentro do ambiente, escopo de filas de processamento;
• Descrição do Fluxo: Editor de texto que permite criar documentações e contextualizações referentes ao Fluxo;
• Agendamento CRON: Código com 6 parâmetros que definem a periodicidade da integração conforme [http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html)
• Máximo de falhas consecutivas: Define o número máximo de falhas consecutivas antes de enviar uma notificação de instabilidade (ver Notificações).

5. Ações

Ações são as peças que compõem um Fluxo de Integração e representam abstrações de procedimentos como: chamadas de serviços web, consultas e alterações em bancos-de-dados, envio de e-mails, substituição de conteúdo, concatenação de dados, dentre outros. Para realizar operações que não estão previstas nas Ações nativas existe a ExecuteJavaAction, responsável por interpretar código Java durante a execução do Fluxo de Integração.

Cada Ação é configurada de uma maneira conforme as indicações da interface, mas todas compartilham os seguintes campos:

• Nome: Identificador da Ação, utilizado para referenciar seu valor em outros pontos do contexto de execução do Fluxo;
• Ação: Identificador do Tipo de Ação acompanhado de uma descrição do processamento. O campo possui a funcionalidade de busca/ autocomplemento.
• Desabilitar Ação: Ignora o processamento dessa Ação;
• Desabilitar Logs: Não escreve o detalhamento de processamento dessa Ação no Painel de Monitoramento (ver Monitoramento);
• Descrição: Campo para descrever o propósito dessa Action no Fluxo, é exibida no Fluxo de Ações durante a edição de um Fluxo;
• Campos customizados: De acordo com cada Ação.

5.1 Fluxo de Ações

Exibe a sequência de Ações que serão processadas em determinado nível (ou endentação) do Fluxo de Integrações.

5.2 Mapa de Ações

Exibe uma visão geral do Fluxo de Integração, indicando todos os Fluxos Alternativos (endentações na execução) associados a Ações Condicionais ou Ações Iterativas.

6. Conceito de Replace

Durante os fluxos de integração é possível referenciar os valores de outras Ações que já tenham sido executadas até o momento no contexto da integração. Por exemplo, uma ExecuteQueryDatabaseAction.

Além disso, o contexto de integração também pode acessar os valores do corpo de requisição recebido (RequestBody), cabeçalhos da chamada e parâmetros de URL por meio dos objetos de contexto: body, headers e params, respectivamente.

7. Referência do Valor em Texto

Todos os campos de texto da plataforma que permitem a referência dinâmica de valores vão possuir o seguinte descritor:

O texto entre os símbolos # vão indicar qual Ação ou campo de uma Ação (caso ela tenha um valor do tipo Objeto), possui o valor a ser utilizado durante o tempo de execução.

O valor é substituído em tempo de execução em forma de texto ocupando o espaço identificado pelos símbolos #. Por exemplo, se configurarmos uma ExecuteQuerySingleLineDatabaseAction a seguinte forma:

Assumimos que as Ações verifica-numemp e verifica-numcad existem na integração e foram executadas antes da nossa consulta, da seguinte forma:

Dessa forma, a query resultante:

Caso a Ação referenciada não exista (ou não tenha sido executada durante o contexto de execução da integração), o resultado da substituição vai ser vazio e pode ocasionar em erros de integração como, por exemplo, se a Ação verifica-numemp não existisse teríamos a seguinte situação:

8. Referência do Valor em Objeto

Em alguns tipos de Ações, como as condicionais, os campos de entrada vão esperar uma avaliação de condição que pode consultar o valor em Objeto (String, Map, Integer…) de determinada Ação (ou campo de uma Ação) por meio da sintaxe get(identificador) ou get(identificador).get(atributo).

9. Fluxos Alternativos

Chamamos de Fluxo Alternativo qualquer conjunto de Ações executadas apenas em determinadas situações. Para acessar o Fluxo Alternativo de uma Ação, basta clicar no ícone de Fluxo Alternativo localizado tanto no Mapa de Ações, quanto no Fluxo de Ações. Em seguida, o conteúdo do Fluxo de Ações irá exibir as Ações do Fluxo Alternativo acompanhados de um indicador de qual Ação está executando essas instruções.

Para voltar ao nível de execução anterior, basta utilizar o botão Voltar ou utilizar o atalho para Localização da Ação.

10. Ações

10.1 Ações Iterativas

Ações do tipo ForAction esperam receber um objeto do tipo List e realizar os procedimentos descritos em seu Fluxo Alternativo para cada objeto da lista de entrada. Durante a execução do Fluxo Alternativo, o objeto que está sendo iterado pode ser acessado no valor da própria Ação iterativa.

Após a finalização de todas as iterações, o contexto de execução vai para a Ação que estiver após a Iterativa (ou “abaixo” na vista da interface.

No exemplo acima podemos acessar o valor do objeto sendo iterado na for-processa-registro dentro de seu Fluxo Alternativo, para isso basta referenciar o valor da for-processa-registro, como na imagem da seção de Ações Condicionais onde temos a configuração do trata-atualizacao, uma Ação Condicional que está no Fluxo Alternativo da nossa Ação Iterativa.

10.2 Ações Condicionais

Ações do tipo IfAction avaliam uma condição descrita em Java e processam o seu Fluxo Alternativo caso o resultado seja false. Se o resultado da avaliação de expressão retorna um true, o contexto de execução vai para próxima Ação.

É importante notar que após a finalização do processamento de um Fluxo Alternativo de uma Ação Condicional, o contexto de execução do “nível” no qual a IfAction foi chamada é interrompido. Isso quer dizer que no exemplo acima, se trata-atualização retornar false, seu Fluxo Alternativo vai ser processado e após isso vamos para a próxima iteração da nossa ForAction, sem executar a msg-erro-tipOpe e as seguintes, pois o contexto de execução dessa iteração foi tratado na IfAction. Se a IfAction está fora de uma iteração (como na raiz/fluxo principal) o processo de integração vai ser finalizado.

Abaixo, um diagrama que representa um exemplo de processamento do tipo Fluxo de Integração:

11. Desvios no Processamento

O que fazer quando desejamos continuar o processamento da integração após uma tratativa condicional? No fim desse condicional, podemos inserir uma GoToAction, responsável por mover o ponteiro de execução do fluxo para qualquer outra Ação, utilizando o nome da Ação como identificador (cuidado ao criar múltiplas Ações com o mesmo nome). Deve-se tomar cuidado com a lógica utilizada em conjunto com essa Ação pois ela pode gerar loops infinitos dentro de um processamento. Por via de regra, evite realizar desvios para Ações que estão no passado em relação ao contexto de execução. Por exemplo:

12. Ações Java

A Ação ExecuteJavaAction disponibiliza um campo para a inserção de um trecho de código Java a ser processado durante o tempo de execução do Fluxo de Integração.

Podemos associar uma Ação Java com um método no sentido que, quando o interpretador identifica um retorno no código Java, esse valor vai ser atribuído à Ação (no caso da imagem, meu-processo) em questão para futuras referências dentro do contexto da Integração (get(meu-processo)). Se o código não possui uma instrução de retorno, a Ação vai ter o valor nulo.

Para mais informações acerca deste assunto, acesse ao manual de Ações Java.

13. Referenciando Valores de Ações no Código Java

Durante o processamento de uma Action Java, é possível obter valores do contexto de integração utilizando o método de referência por valor em texto (utilizando símbolo #) da mesma forma que em outras Ações. A referência de valor em objeto é semelhante, mas deve ser utilizada em um objeto de contexto (chamado context) que o Interpretador da Ação Java já possui.

Por exemplo: String urlStr = "#baseURL#"; e String urlStr = context.get(baseURL); vão retornar a mesma informação se a Ação baseURL contém, em seu valor, uma informação do tipo String. Agora digamos que uma Ação chamada minha-query, do tipo ExecuteQuerySingleLineDatabaseAction, contém o resultado de uma consulta em banco (representado no contexto de integração como um Objeto do tipo Map). A forma correta de referencia-la por código Java seria Map consulta = context.get(minha-query);:

Se o interpretador encontrar Map consulta = #minha-query#; seria como estar atribuindo um valor do tipo String (referência de valor por texto) a um Objeto do tipo Map e isso vai resultar em um erro de processamento da integração.

Pois o que foi interpretado durante o processamento foi:

14. Limitações do Interpretador ExecuteJavaAction

O interpretador de código Java dos Fluxos de integração, até o momento, não tem suporte a Arrow Functions e Generics.

Exemplo:

Enquanto:

15. Fluxos de Integração do tipo REST: Formatando a Resposta do Endpoint

Nos fluxos REST, existem respostas padrão para situações onde há algum erro de processamento ou nas entradas da requisição (códigos 4XX e 5XX) no seguinte formato:

Onde timestamp tem o formato YYYY/MM/DD HH:mm:SS:sss e path indica o endpoint da integração que retornou determinado erro em error e detalhamento em message.

Em caso de processamentos com sucesso (Status 200), o CONNECT permite que a resposta seja customizada com base no valor da **última Ação executada**. Dessa forma o endpoint de um Fluxo de Integração pode retornar diretamente o valor em texto, um número ou booleano por exemplo.

Para que a resposta do endpoints esteja em formato JSON, o último valor retornado dentro do contexto de execução deve ser do tipo Objeto/Map. Esse objeto pode ser construído com Ações dedicadas como CreateEmptyMap, AddObjectToMapAction,ConvertJsonStringToJsonObjectAction, ExecuteJavaAction, dentre outras.

Considere o seguinte fluxo:

Ao chamarmos o endpoint com o ultimo-processamento trazendo o retorno-string temos como resposta:

Enquanto se retornamos um Map como último valor, ele é transformado em um JSON:

16. Tratativas de Erros com a TryCatchAction

A TryCatchAction funciona de forma similar a ifAction, ou seja, o bloco de execução onde a TryCatchAction for chamada é interrompido após o fim do processamento do seu Fluxo Alternativo. Para continuar a integração após o trecho da TryCatchAction, é necessário utilizar uma GoToAction (ver seção sobre desvios no processamento).

TryCatchAction sem erros no seu fluxo alternativo, retornará null na Ação:

TryCatchAction com erros no seu fluxo alternativo, retorna a mensagem descritiva do erro no log, enquanto a Ação em si armazena o ExceptionObject na Ação:

Objeto de Exception salvo na Ação try, do tipo TryCatchAction, após um erro:

Para realizar um tratamento do tipo Catch, basta utilizar uma ação condicional (ifAction) logo após a TryCatchAction, que vai seguir em frente se a mesma retornou null, caso retorne qualquer outra coisa, será realizada uma tratativa condicional.

Exemplo de utilização:

17. Timeout das Integrações

O controle do tempo de execução dos processos de integração é crucial, garante a eficiência e desempenho adequado nas integrações entre sistemas. A configuração de Timeout nas integrações REST e JOB podem ser utilizadas para definir um tempo máximo de execução para as integrações, em segundos, garantindo que as integrações sejam concluídas dentro dos prazos estabelecidos ou retornem um erro:

18.Paralelismo em Fluxos Agendados

Além do controle do tempo de execução, os fluxos do tipo JOB tem a definição de Execuções Simultâneas, permitindo controlar o número de processos dessas integrações, sendo possível estarem ativos nos casos onde o tempo de execução do fluxo é maior do que o tempo entre as execuções. Essa é uma consideração importante, pois enquanto integrações REST podem receber na requisição valores específicos a serem integrados, os fluxos agendados sempre iniciam o processamento com o mesmo estado, situações como essa podem ser perigosas, pois permitiria que outro processo se inicie antes da finalização do anterior.

O valor padrão para Execuções Simultâneas é 1, representando assim a execução de apenas um processo. Caso um novo disparo agendado aconteça durante uma execução em andamento, o novo disparo será impedido.

19. Chamadas Síncronas e Assíncronas para Fluxos REST

Os fluxos REST do CONNECT podem ser chamados de maneira síncrona ou assíncrona, conforme a URL utilizada. A escolha entre o processo síncrono e assíncrono depende das necessidades específicas do sistema e das expectativas de desempenho.

Em chamadas síncronas, o solicitante aguarda a conclusão da execução do processo antes de receber a resposta estabelecida no Fluxo de Integração. Isso geralmente implica em tempos de resposta previsíveis, curtos ou imediatos, adequados para interações que precisam de alguma informação obtida no retorno do fluxo do CONNECT.

Por outro lado, chamadas assíncronas permitem que a solicitação seja enviada sem esperar pela conclusão imediata do processo, recebendo um “OK” (status 200) imediato após a requisição.

Essa abordagem é valiosa para tarefas que podem levar mais tempo, como processamentos em lotes ou operações intensivas. No entanto, introduz a necessidade de gerenciar o estado de transação, lidando com possíveis discrepâncias temporais entre as solicitações e as respostas.

20. Encerrando Processamentos em Andamento

A interrupção de um fluxo de integração é fundamental para lidar com imprevistos, corrigir erros ou realizar adaptações dinâmicas no ambiente operacional, com intuito de evitar impactos negativos diante de problemas como falhas de comunicação, mudanças inesperadas nos dados ou ajustes necessários nas regras de negócio. Essa capacidade de intervenção proporciona uma gestão proativa do sistema de integração, assegurando estabilidade e eficiência contínua nas operações.

Ao acompanhar o monitoramento de qualquer Fluxo de Integração no estado de Em Progresso é possível interromper a execução utilizando a opção Encerrar. Após a interrupção do processamento, o log de monitoramento aponta qual usuário foi responsável pela atuação e encerra o fluxo em estado de Erro.

21. Compilação do Fluxo ao Salvar

Sempre que um Fluxo de Integração é salvo, todas as suas Ações são analisadas pela plataforma. O retorno dessa análise define se o fluxo pode ser salvo (warnings), ou se existe alguma configuração não-permitida - esse último caso geralmente reservado para operações em Ações do tipo ExecuteJavaAction.