Passagem de parâmetros no Pentaho PDI (Jobs e Transformações)

Alguns anos atrás, um amigo pediu para revisar processos que havia montado no Pentaho Data Integration (PDI). Ao abrir os repositórios, encontrei a mesma transformação copiada dezenas de vezes — uma para cada filial, cada competência, cada layout de arquivo — em vez de um único job parametrizado. Como arquiteto habituado a DRY (Don't Repeat Yourself) em Java, senti físico o desconforto. Escrevi este guia atualizado para quem ainda duplica .ktr/.kjb por falta de confiança com parâmetros. A boa notícia: no PDI, passar parâmetros é simples quando você entende declaração, chamada e consumo interno.

Conceito: três momentos

1. Declarar o parâmetro no job ou transformação que recebe.
2. Informar o valor na chamada (job pai, linha de comando ou agendador).
3. Consumir com sintaxe ${NOME_PARAM} ou variáveis de ambiente conforme step.

Pode ser passado parâmetro na chamada de Transformações, Jobs ou Mapping. Foco aqui em Transformações e Jobs; Mapping merece artigo próprio por nuances de sub-transformações.

Passo 1 — Declarar na transformação filha

Abra a transformação que deve receber valores externos. Vá em Parâmetros nas propriedades do arquivo. Adicione nome, valor default e descrição. Exemplo: DATA_REFERENCIA com default 2026-01-01, COD_FILIAL com default 001. Descrição clara ajuda quem opera às 2h da manhã.

Passo 2 — Informar na chamada

No job pai, step "Transformation" ou "Job" permite aba de parâmetros. Mapeie nome → valor ou passe variável do job pai. Exemplo: COD_FILIAL = ${FILIAL_ATUAL} iterado em loop ou vindo de parâmetro de linha de comando.

# Exemplo Kitchen (linha de comando)
kitchen.sh -file:/jobs/carga_diaria.kjb \
  -param:DATA_REFERENCIA=2026-08-14 \
  -param:COD_FILIAL=012

Passo 3 — Consumir dentro do componente

Dentro da transformação, steps como "Table Input" aceitam SQL com substituição:

SELECT * FROM pedidos
 WHERE filial = '${COD_FILIAL}'
   AND dt_emissao >= '${DATA_REFERENCIA}'

Não basta só na chamada — o componente precisa estar preparado para receber. A imagem abaixo mostra a configuração interna após abrir o step que consome o parâmetro:

Boas práticas que aprendi em produção

• Prefixe parâmetros: ERP_, STG_ — evita colisão entre jobs aninhados.
• Valide formato no primeiro step (Regex, Filter Rows) antes de SQL pesado.
• Nunca concatene parâmetro vindo de usuário final direto em SQL sem whitelist — risco similar a SQL injection; em Java uso PreparedStatement (PreparedStatement Java).
• Documente no README do repositório Pentaho: nome, tipo, exemplo, quem altera.

Job aninhado: cadeia de parâmetros

Job A chama Job B chama Transformação C. Parâmetros podem ser repassados explicitamente ou herdados conforme configuração "Pass all parameters". Prefiro explícito — herança acidental propagou ENV=prod para ambiente de teste uma vez; nunca esqueci.

Variáveis versus parâmetros

Parâmetros são imutáveis durante execução (salvo steps específicos). Variáveis (${Internal.Job.Filename.Name}) mudam em runtime. Use parâmetro para entrada controlada; variável para metadados de execução. Confundir os dois gera bug intermitente difícil de reproduzir.

Integração com agendador corporativo

Control-M, cron, Kubernetes CronJob ou GitHub Actions podem invocar Kitchen/Carte. Centralize segredos JDBC fora do .kjb — alinhado a integrações ERP descritas em integração Pentaho e arquitetura ERP.

Teste local antes de promover

Spoon → Execute → informe parâmetros de teste → compare contagem de linhas com query manual no banco. Diff de amostra 100 registros. Só então suba para Carte. CI/CD enxuto para ETL raramente existe em PME; disciplina manual compensa.

Erros comuns

Esquecer aspas no SQL para parâmetro string. Default vazio que zera filtro. Nome case-sensitive em Linux server vs Windows dev. Copiar job antigo com parâmetros obsoletos no XML. Limpeza periódica salva horas.

Exemplo filial iterada

Job pai lê CSV filiais ou query SELECT cod_filial FROM tb_filial WHERE ativo=1. Loop executa transformation carga com COD_FILIAL parametrizado. Log central registra filial, linhas lidas, rejeitadas, tempo. Falha filial 003 não aborta 004 se configure continue on error consciente com alerta.

Mapping sub-transformations

Mapping reutiliza subgraph com interface de parámetros explícita — útil quando mesma lógica limpeza endereço aparece em três cargas. Documente contrato entrada/saída como API interna.

Troubleshooting produção

Log level Detailed temporário. Kitchen -level Debug só homologação — volume enorme. Compare count(*) staging vs origem. Diff hash amostra 1% registros detecta corrupção silenciosa encoding Latin1 vs UTF-8.

Segurança parâmetros dinâmicos

Parâmetro vindo de arquivo externo editable usuário — sanitize, validate regex, reject path traversal se for caminho arquivo. Kitchen -param não substitui controle acesso repositório .kjb versionado Git.

Versionamento Git PDI

Diff XML barulhento mas rastreável. Tag release job produção. Changelog step novo documentado. Rollback git revert + redeploy Carte.

Performance grandes volumes

Aumente commit size JDBC, use batch insert, partition step paralelo filiais independentes. Parametrize FETCH_SIZE conexão Oracle. Monitor JVM heap Carte — OutOfMemory em job mal parametrizado filial única gigante.

Template job parametrizado reutilizável

Mantenho job template _TEMPLATE_CARGA.kjb com parâmetros DOCUMENTADOS tabela markdown README: nome, tipo, default, quem altera. Novo cliente copia template, ajusta conexão JDBC e dois parâmetros — não reinventa grafo. Onboarding consultor TEK cai de dois dias para quatro horas.

Conclusão

Vejam só: nenhum mistério com o PDI. Passagem de parâmetros não é difícil — é disciplina. Pare de duplicar transformações; consolide, parametrize, teste. Se integração batch faz parte do seu ERP, combine este guia com visão macro de integração de sistemas. Na TEK Softwares, essa correção simples já reduziu dezenas de arquivos mantidos para quatro jobs base — manutenção caiu proporcionalmente.