Do template ao primeiro deploy

Esta página conecta o template oficial ao fluxo real de desenvolvimento de uma automação TunnelHub.

O que a CLI gera

Quando você executa tunnelhub create-automation --env <ENV>, a CLI cria a automação na plataforma e baixa um dos templates oficiais para sua máquina.

O projeto gerado costuma incluir:

• src/index.ts com o handler principal;
• uma classe de integração no diretório src/core/ ou equivalente;
• metadata com os campos exibidos no monitoramento;
• __tests__ com exemplos básicos;
• tunnelhub.yml;
• scripts de build e teste.

1. Abra o handler

O handler normalmente:

• instancia sua classe de integração;
• chama AutomationExecution.executeAutomation(...);
• retorna sucesso HTTP quando a execução termina sem erro fatal.

Esse é o contrato central do runtime público.

2. Abra a classe de integração

É nessa classe que você implementa o flow escolhido.

Exemplos de responsabilidade por flow:

• No delta: loadSourceSystemData() e sendData();
• No delta batch: loadSourceSystemData() e sendDataInBatch();
• Delta: loadSourceSystemData(), loadTargetSystemData(), insertAction(), updateAction(), deleteAction();
• Delta batch: loadSourceSystemData(), loadTargetSystemData(), batchInsertAction(), batchUpdateAction() e batchDeleteAction().

3. Defina os metadados

defineMetadata() define as colunas visíveis no monitoramento.

Pense nesses campos como contrato operacional para suporte e negócio. Bons metadados ajudam a responder rapidamente:

• qual item falhou;
• qual identificador localizar no sistema de origem;
• qual status funcional estava envolvido.

4. Ligue código à configuração de produto

Antes de concluir a implementação, confirme que a automação no portal tem os recursos certos associados:

• systems necessários;
• parâmetros necessários;
• Tabelas De/Para necessárias;
• Sequências necessárias.

No código, o padrão recomendado é localizar systems por internalName e usar helpers do SDK em vez de espalhar configuração no projeto.

5. Revise o tunnelhub.yml

Confirme pelo menos:

• service.uuid preenchido;
• configuration.entrypoint coerente com o bundle gerado;
• package.artifact apontando para o ZIP final.

6. Rode testes locais

Os templates incluem um teste inicial. Expanda essa suíte conforme você implementa a integração.

Checklist mínimo:

• handler sobe sem erro;
• classe de integração instancia corretamente;
• metadados são válidos;
• principal caminho feliz da integração está coberto.

7. Gere o artefato

O comando exato depende do template, mas o resultado esperado é sempre um ZIP configurado em package.artifact.

Antes do deploy, confirme que o arquivo realmente existe no caminho configurado.

8. Publique

tunnelhub deploy-automation --env DEV --message "primeira versão"

Se necessário, sobrescreva o UUID com --automation.

Em pipelines CI/CD, mantenha o contexto humano no --message, por exemplo com SHA e e-mail do autor do commit.

9. Valide no produto

Depois do deploy, valide no portal:

• se a nova versão apareceu na automação;
• se os triggers esperados estão configurados;
• se a execução manual ou agendada funciona;
• se os logs e traces fazem sentido.

Checklist final

• flow escolhido corretamente;
• systems, parâmetros, Tabelas De/Para e Sequências configuradas;
• tunnelhub.yml coerente;
• artefato gerado;
• deploy publicado;
• monitoramento validado.