Criando sua primeira automação

Tempo estimado: 25 a 40 minutos

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 conversão.

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.

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.

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.

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.