O HEFLO fornece um projeto de customização de API baseado em Node.js que permite a implementação de regras de negócios avançadas, integrações e manipulação de dados durante a execução do processo. Usando o projeto de API do HEFLO, os desenvolvedores podem estender o comportamento da automação de processos além das configurações padrão do BPMN. As customizações podem ser usadas com:

• Elementos BPMN;
• Campos de Dados Externos;
• Botões de Ação;
• Eventos de Campo de Formulário, como Inicialização, Adição, Alteração e Remoção;
• Gatilhos de fluxo de execução de processos;
• Definição dinâmica de participantes;
• Operações de registros personalizados, como criação, atualização e remoção.

A biblioteca da API do HEFLO também fornece funções utilitárias nativas que simplificam o acesso aos dados do processo, campos de itens de trabalho, registros, tokens e contexto de execução. Uma lista completa de gatilhos, eventos e funções utilitárias disponíveis pode ser encontrada na documentação da API do HEFLO: Link.

Embora os projetos de customização do HEFLO ofereçam a flexibilidade de um ambiente de web service completo, eles também exigem conhecimento em Node.js, manutenção de projetos, hospedagem e infraestrutura de implantação. Para organizações que preferem assistência na implementação, o HEFLO também oferece serviços de consultoria e implementação.

Observação: Uma abordagem alternativa para um projeto de API do HEFLO pode ser encontrada no artigo: Visão Geral de Integrações no HEFLO: Web Services vs. Customizações de API

Estrutura do projeto e elementos mínimos

Um projeto de customização do HEFLO é normalmente implementado como uma aplicação do Serverless Framework implantada no AWS Lambda. A estrutura mínima do projeto é:

├── package.json
├── process
├        └── functions.ts
├── serverless.yml
└── tsconfig.json

onde cada arquivo tem uma responsabilidade específica no projeto.

package.json

O arquivo package.json define as dependências e a configuração do projeto. Ele contém:

• Dependências de pacotes Node.js;
• Dependências do Serverless Framework;
• Pacotes de configuração do TypeScript;
• Dependência do SDK da API do HEFLO;
• Bibliotecas utilitárias como Axios, Moment, parse de CSV e pacotes do AWS SDK.

Exemplo de dependência: “heflo-api”: “^1.0.32”

O pacote heflo-api fornece acesso ao contexto de execução do HEFLO e métodos utilitários usados durante a automação do processo.

serverless.yml

O arquivo serverless.yml define como a aplicação é implantada no AWS Lambda.

Exemplo:
service: projectName
provider:
  name: aws
  runtime: nodejs16.x
  region: sa-east-1
functions:
  function01:
    handler: process/functions.function01
    events:
      – http:
          path: /function01
          method: post

Esta configuração:

• Cria uma função AWS Lambda;
• Expõe um endpoint HTTP;
• Conecta o endpoint a uma função TypeScript;
• Permite a implantação usando o Serverless Framework.

tsconfig.json

Este arquivo define a configuração do compilador TypeScript. Configurações de exemplo incluem:
{
“target”: “ES2020”,
“module”: “commonjs”,
“strict”: true
}

O projeto usa TypeScript para melhorar a manutenibilidade, a segurança de tipagem e os recursos de depuração.

processFunction.ts

O arquivo functions.ts contém a lógica de customização. Cada função exportada pode ser usada como:

• Manipuladores de eventos de formulário;
• Ações de gatilho;
• Endpoints de API;
• Manipuladores de execução de fluxo de sequência;
• Rotinas de automação personalizadas.

Exemplo:
exports.function01 = async (event: any) => {
    const body = JSON.parse(event.body);
    const context = new HEFLOApi.Events.WorkItem.OnChanged({ body });
    const textField = context.WorkItem.Get(“textField”);
    // custom business logic here
};

O elemento principal de toda customização é o objeto de contexto fornecido pela biblioteca da API do HEFLO. Este objeto dá acesso a:

• Campos de itens de trabalho;
• Dados do processo;
• Registros;
• Participantes;
• Informações do token atual;
• Métodos de execução de fluxo de trabalho.

Instalando dependências e pré-requisitos

Antes de executar o projeto, certifique-se de que as seguintes ferramentas estejam instaladas: Node.js;

• Node.js;
• npm;
• Serverless Framework;
• Ngrok.

Para este guia, o Visual Studio Code será usado como a IDE para edição, testes e depuração do projeto.

Os passos a seguir descrevem um processo de configuração simplificado para preparar o ambiente de desenvolvimento e criar a estrutura do projeto do zero.

1. Baixe e instale o Visual Studio Code.
2. Baixe e instale o Node.js a partir do site oficial.
3. Após a instalação, valide-a usando um prompt de comando ou terminal:
   node -v
4. Valide também o npm:
   npm -v
5. Instale o TypeScript.
   npm install typescript -g
6. Valide a instalação:
   tsc -v
7.  Instale o Serverless Framework.
   npm install serverless@3.39.0 -g
   Nota: Verifique a documentação oficial do Serverless Framework para obter a versão estável mais recente.
8.  Valide a instalação:
   serverless -v
9.  Instale o ngrok.
   O ngrok é usado durante o desenvolvimento local para expor publicamente a API local, de modo que o HEFLO possa acessar os endpoints de customização durante os testes.
   a. Crie uma conta no site do ngrok;
   b. Baixe o arquivo executável;
   c. Extraia e abra o ngrok;
   d. Autentique a instalação usando o comando fornecido no painel do ngrok.
   Exemplo: ngrok config add-authtoken YOUR_TOKEN
   Após a autenticação, o ngrok estará pronto para uso.

Criando uma função de customização simples

Após instalar todos os pré-requisitos, podemos criar o projeto de customização. Primeiro, crie a pasta do projeto, o que pode ser feito diretamente pelo VS Code ou por meio de um terminal; para isso:

1. Abra um terminal e crie o diretório do projeto:
   mkdir heflo-customization
   cd heflo-customization
2. Inicialize o projeto Node.js; para isso, execute:
   npm init -y
3. Instale as Dependências do Projeto.
   Para este exemplo, instalaremos apenas as dependências mínimas necessárias.
   npm install \
   heflo-api \
   serverless@3.39.0 \
   serverless-offline@8.8.0 \
   serverless-plugin-typescript@2.1.2 \
   typescript
   Nota: O pacote serverless-plugin-typescript atualmente suporta apenas as versões v2 e v3 do Serverless Framework. Por esse motivo, o projeto usa serverless@3.39.0. Instalar a versão mais recente do Serverless Framework pode causar conflitos de dependência durante a instalação. Para evitar problemas de compatibilidade, sempre instale as versões especificadas neste guia.
   Adicionalmente, instale as dependências de desenvolvimento::
   npm install –save-dev \
   @types/aws-lambda \
   serverless-plugin-common-excludes \
   serverless-plugin-include-dependencies
4. Crie a Estrutura do Projeto.
   Uma estrutura de projeto sugerida é mostrada abaixo.
   heflo-customization
   ├── package.json
   ├── process
   ├   └── functions.ts
   ├── serverless.yml
   └── tsconfig.json
5. Crie o arquivo tsconfig.json com o seguinte conteúdo:
   {
       “compilerOptions”: {
           “target”: “ES2020”,
           “module”: “commonjs”,
           “sourceMap”: true,
           “outDir”: “.build”,
           “strict”: true,
           “rootDir”: “./”,
           “esModuleInterop”: true
       }
   }
   Esta configuração permite a compilação do TypeScript compatível com o Serverless Framework e o AWS Lambda.
6. Crie o arquivo serverless.yml:
   service: heflo-customization
   frameworkVersion: ‘3’
   provider:
     name: aws
     runtime: nodejs16.x
     region: sa-east-1
     timeout: 30
     versionFunctions: false
   functions:
     function01:
       handler: process/functions.function01
       events:
         – http:
             path: /function01
             method: post
   plugins:
     – serverless-offline
     – serverless-plugin-typescript
     – serverless-plugin-common-excludes
     – serverless-plugin-include-dependencies
     – serverless-dotenv-plugin
7. Crie sua primeira função de customização.
   Crie o arquivo process/functions.ts:
   import * as HEFLOApi from “heflo-api”;
   exports.function01 = async (event: any) => {
       try {
           const body = JSON.parse(event.body);
           const context = new HEFLOApi.Events.WorkItem.OnExecuteSequenceFlow({
               body,
           });
           context.WorkItem.Set(
               “textField”,
               “Customization executed successfully”
           );
           return {
               statusCode: 200,
               body: JSON.stringify(
                   context.GetModifiedData()
               ),
           };
       } catch (error) {
           return {
               statusCode: 500,
               body: JSON.stringify({
                   message: `Something went wrong: ${error}`,
               }),
           };
       }
   };

Este exemplo simples recebe o payload do evento do HEFLO, cria o contexto de execução do HEFLO com base no tipo de evento, atualiza o campo do processo textField com a seguinte mensagem: “Customization executed successfully”, e depois retorna os dados modificados de volta para o HEFLO.

Executando o projeto localmente

1. Inicie o servidor local:
   serverless offline
   A API será executada localmente na porta 3000
2. Abra outro terminal e execute:
   ngrok http 3000
   O ngrok gerará uma URL HTTPS pública que pode ser configurada dentro do HEFLO para fins de teste..

Implantando a customização

Após testar localmente, implante o projeto no AWS Lambda usando:

serverless deploy

O processo de implantação:

• Empacota a aplicação;
• Faz o upload do código para a AWS;
• Cria as funções Lambda;
• Cria os endpoints do API Gateway;
• Retorna as URLs públicas da API.

Exemplo de saída:

endpoints:
POST – https://xxxx.execute-api.sa-east-1.amazonaws.com/dev/sampleFunction

Esses endpoints podem então ser usados diretamente dentro das configurações de automação do HEFLO.

Usando a customização na automação do HEFLO

Após a implantação, o endpoint pode ser conectado aos eventos de automação de processos dentro do HEFLO.

A próxima etapa é criar o processo BPMN e configurar a chamada do web service; para isso, usaremos um diagrama simples de duas tarefas para enviar, receber e exibir o evento no campo do formulário.

1. Na página principal do ambiente do HEFLO, acesse o editor de processos.
2. Abra um processo BPMN existente ou crie um do zero.
3. Verifique se o processo está com a opção Processo automatizado habilitada.
4. Adicione o elemento inicial, a “Primeira tarefa”, a “Segunda tarefa” e o elemento final, conforme mostrado na imagem abaixo.
   
5. Em ambas as tarefas, vincule uma entrada de dados (formulário).
6. Dê um duplo clique no formulário para acessar a janela de criação de formulários.
7. Na tarefa “Primeira tarefa”, crie um campo de texto chamado “Campo de Texto”.
   
8. Aqui precisamos dar um passo adicional e, para isso, temos duas abordagens possíveis:
   a. A primeira é usar o identificador do campo para mapear o campo do formulário dentro da aplicação; para isso:
   i. Clique no ícone de lápis no lado direito do campo e selecione a opção Editar.
   ii. Na parte inferior da janela, clique no ícone “</>” para acessar o identificador do campo e substitua field_id nas linhas como:
       context.WorkItem.Set(“textField”,);
   Para mapear o campo dentro da aplicação.
   b. A segunda é criar um alias personalizado; isso mantém o código da API mais simples e sustentável; para isso:
   i. Clique no ícone de lápis no lado direito do campo e selecione a opção Editar.
   ii. Na parte inferior da janela, clique no ícone “</>” para acessar o identificador do campo.
   iii. Selecione a opção para criar alias e confirme.
   iv. Use-os no lugar de field_id nas linhas como:
   context.WorkItem.Set(“textField”,);
   Para mapear o campo dentro da aplicação.
   Usando a segunda abordagem, crie o seguinte alias para o campo de texto; este deve ser o mesmo usado no código.
   Campo: Text Field Alias: textField;
9. Agora é hora de configurar a chamada da API; selecione o fluxo de execução entre as duas tarefas e, na aba de execução (menu de propriedades), clique no botão de execução.
   
10. No tipo de customização, selecione API usando NodeJS.
11. Aqui precisamos configurar a chamada do web service. Para este exemplo, crie um novo web service e defina:
    a. URL de Produção: https://abcd-1234.ngrok-free.app/
    b. Recurso: function01
    c. Método: Post
    d. Autenticação: Nenhuma
    Onde a URL de produção deve ser a mesma mostrada no terminal do ngrok.
    
    Observe que não precisamos configurar nenhum parâmetro de envio e resposta; todas as informações serão manipuladas dentro da aplicação e enviadas para o ambiente do HEFLO dentro de um contexto.
12. Confirme a configuração.
13. Salve a configuração.
14. No editor, clique com o botão direito no elemento inicial e selecione Testar, depois Iniciar novo item de trabalho.
15. Valide a configuração.

Um ponto interessante é que este pequeno projeto pode ser adaptado ainda mais para modelar regras de negócios complexas e servir como ponto de partida para futuros projetos. Outros cenários comuns de uso incluem:

• Eventos de alteração de campo;
• Inicialização de formulário;
• Execução de botão de ação;
• Execução de fluxo de sequência;
• Validações de aprovação;
• Atribuição dinâmica de participantes;
• Integrações externas.

O endpoint de customização recebe o contexto de execução do processo do HEFLO e retorna os dados modificados para a plataforma. Essa abordagem permite a implementação de regras de negócios avançadas, mantendo o modelo BPMN limpo e sustentável.

Considerações Finais

As customizações de API do HEFLO fornecem uma poderosa camada de extensão para projetos de automação de processos. Ao combinar a modelagem de processos BPMN, a customização em Node.js e a implantação Serverless, as organizações podem implementar soluções de automação altamente flexíveis e sustentáveis.

A biblioteca da API do HEFLO simplifica a interação com o processo e permite que os desenvolvedores foquem na lógica de negócios em vez de detalhes de infraestrutura.