Criando sua primeira automação

Este guia mostra um fluxo atual de onboarding para criar, desenvolver, publicar e acompanhar uma automação no TunnelHub.

Antes de começar

Você vai precisar de:

• uma conta TunnelHub com acesso a pelo menos um ambiente;
• Node.js 22+ na sua máquina;
• npm ou pnpm;
• permissão para criar pacote e automação no ambiente desejado.

1. Instale a CLI

npm install -g @tunnelhub/cli

Depois da instalação, você pode usar tunnelhub ou o alias curto th.

2. Faça login

O fluxo recomendado usa autenticação via navegador:

tunnelhub login

Durante o login, a CLI solicita o Tenant ID e abre a autenticação no frontend do TunnelHub. Em casos específicos, existe fallback por usuário e senha:

tunnelhub login --password

Para validar a sessão atual:

tunnelhub login-check

3. Descubra seus ambientes

Liste os ambientes disponíveis e identifique o nome ou UUID do ambiente onde você quer trabalhar:

tunnelhub list-environments

Os comandos da CLI aceitam nome ou UUID do ambiente. Internamente, a CLI resolve esse valor para o identificador correto.

4. Crie um pacote

Pacotes organizam recursos relacionados, como automações, sistemas e Tabelas De/Para.

tunnelhub create-package --env DEV

O comando é interativo e solicita nome e descrição.

5. Crie uma automação

Agora crie a automação com bootstrap local de um template oficial:

tunnelhub create-automation --env DEV

Durante o fluxo, você escolhe:

• o tipo base da automação;
• o pacote;
• nome e descrição;
• período de retenção de logs;
• URL do repositório, se desejar informar.

Os templates atuais cobrem quatro modelos:

• No delta
• No delta batch
• Delta
• Delta batch

Ao final, a CLI:

• cria a automação no TunnelHub;
• baixa um template do GitHub;
• extrai o projeto para uma nova pasta local;
• grava o service.uuid no tunnelhub.yml.

6. Entenda a estrutura do projeto

O projeto gerado normalmente inclui:

• src/index.ts como handler principal;
• uma classe de integração que herda um dos flows do SDK;
• metadata para definir as colunas visíveis no monitoramento;
• tunnelhub.yml com identificação do serviço e configuração de build/deploy;
• testes básicos para execução local.

O desenvolvimento atual deve ser feito com o @tunnelhub/sdk, usando um dos fluxos públicos:

• NoDeltaIntegrationFlow
• NoDeltaBatchIntegrationFlow
• DeltaIntegrationFlow
• BatchDeltaIntegrationFlow

7. Escolha o flow certo

Use esta regra prática:

• No delta quando a automação apenas lê e envia dados, sem reconciliar estado;
• No delta batch quando o fluxo continua sem delta, mas o volume pede processamento em lote;
• Delta quando você precisa comparar origem e destino para decidir entre insert, update e delete;
• Delta batch quando esse mesmo cenário de reconciliação precisa operar em lotes.

Se estiver em dúvida, comece pelo flow mais simples que atende o caso.

8. Modele no produto antes de codar

Evite valores fixos no código. O padrão atual é configurar no produto:

• Sistemas para conexões com serviços externos;
• Parâmetros para valores variáveis da automação;
• Tabelas De/Para para mapeamentos e regras de negócio configuráveis;
• Sequências para geração de identificadores.

No SDK, esses dados chegam no payload de execução e podem ser acessados pelos helpers públicos.

9. Implemente a integração

Em alto nível, sua automação precisa:

• carregar dados da origem;
• opcionalmente comparar com o destino, nos fluxos com delta;
• executar insert, update, delete ou send;
• definir os metadados que aparecerão no monitoramento.

Exemplo simplificado de metadados:

defineMetadata(): Metadata<MyItem>[] {
  return [
    { fieldName: 'id', fieldLabel: 'ID', fieldType: 'TEXT' },
    { fieldName: 'status', fieldLabel: 'Status do item', fieldType: 'TEXT' },
    { fieldName: 'updatedAt', fieldLabel: 'Atualizado em', fieldType: 'DATETIME' },
  ];
}

Os metadados controlam como os itens aparecem nos logs de processamento.

10. Teste localmente

Os templates incluem testes iniciais. Para testes locais, habilite o modo de teste do SDK quando fizer sentido:

import { SDK } from '@tunnelhub/sdk';

beforeAll(() => {
  SDK.testMode = true;
});

Esse modo evita efeitos colaterais da execução real da plataforma durante os testes.

11. Gere o artefato

Antes do deploy, gere o bundle definido no seu projeto. O contrato importante é:

• existir um tunnelhub.yml na raiz do projeto;
• o campo package.artifact apontar para o ZIP ou artefato publicado;
• o projeto estar pronto para o ambiente de execução configurado.

12. Faça o deploy

Com o artefato pronto, publique uma nova versão:

tunnelhub deploy-automation --env DEV --message "primeiro deploy"

Opcionalmente, você pode informar --automation e --publish.

Em pipelines CI/CD, use --message para carregar contexto como SHA, autor do commit ou identificador da execução.

O deploy:

• valida seu tunnelhub.yml;
• faz upload do artefato para S3 por URL assinada;
• solicita a criação do deploy na plataforma.

13. Configure o disparo

Na tela da automação, você pode configurar os gatilhos suportados hoje:

• webhook;
• agendamento;
• inbound email.

Dependendo do tipo escolhido, a automação pode ser executada manualmente, por URL ou por agenda.

Para gatilhos de agendamento, use Não executar antes de quando quiser preparar a agenda antecipadamente e permitir execuções somente a partir de uma data e hora de go-live.

14. Acompanhe a execução

Depois do deploy, use a interface web em Automations > Monitoring para acompanhar:

• status geral da execução;
• volume processado;
• logs de processamento por item;
• traces técnicos;
• downloads e ações operacionais quando disponíveis.

15. Configure notificações de falha

Na aba Notificações da automação, adicione os destinatários que devem ser alertados quando uma execução falhar.

Você pode enviar alertas por e-mail, Discord, Microsoft Teams, Google Chat, Slack ou webhook genérico. Para os canais de colaboração, siga as instruções específicas do provedor e informe a URL gerada no produto. No Microsoft Teams, gere a URL com o Workflows (Power Automate), e não com o conector legado Incoming Webhook. Escolha também o idioma da mensagem e trate URLs de webhook como segredos. Para instruções e links de configuração de cada canal, consulte Notificações.

Próximos passos

• Leia Do template ao primeiro deploy.
• Leia Modelando uma automação no produto.
• Leia SDK para escolher o flow correto.
• Leia Monitoramento para investigar falhas e execuções.
• Leia tunnelhub.yml para entender o contrato de build e deploy.