Levando mudanças para outro ambiente

Antes de começar

• Módulos 01 e 02 concluídos: a janela Visita Técnica funciona, com as lógicas do módulo 02.
• Log Migration Script ligado desde o módulo 01. Se você esqueceu, este módulo ainda funciona: o 2Pack não depende dos scripts.

O que você vai construir

Até aqui, tudo o que você fez existe só no seu banco. Se o banco for apagado, o trabalho some. Se outra pessoa quiser rodar a sua janela, não tem como.

Neste módulo você empacota o projeto das visitas num arquivo que qualquer outro iDempiere consegue instalar. Esse arquivo vai para o Git junto com o seu código e, no módulo 04, passa a ser instalado sozinho quando o plugin sobe.

Duas formas de levar mudanças

A diferença está na segunda linha. Um script diz "insira a coluna de ID 1000123". Se o banco de destino já tem um registro com esse ID (outra customização, outro plugin), o script falha ou, pior, sobrescreve o que não devia. O 2Pack diz "insira a coluna com UUID a3f9..." e deixa o banco de destino escolher o ID.

Regra prática: scripts são o seu histórico; o 2Pack é o que você distribui.

Passo a passo

1. Encontre os seus scripts

Rodando pelo Eclipse, o iDempiere grava os scripts dentro do repositório do core:

ls ~/sources/idempiere/migration/iD14/postgresql/ | grep PlaceholderForTicket

Cada arquivo tem um nome como 202609231530_PlaceholderForTicket.sql. Abra um:

SELECT register_migration_script('202609231530_PlaceholderForTicket.sql') FROM dual;

-- Sep 23, 2026, 3:30:12 PM BRT
INSERT INTO AD_Element (AD_Element_ID, ColumnName, EntityType, Name, ...)
VALUES (1000123, 'EDU_DataVisita', 'EDU', 'Data da Visita', ...);

Repare nos dois detalhes: a primeira linha registra o script na tabela AD_MigrationScript (é assim que o iDempiere sabe o que já foi aplicado), e os IDs estão escritos como números fixos.

2. Tire os scripts do repositório do core

Esses arquivos não são do core. Deixá-los em migration/ tem dois problemas: o git status do iDempiere fica sujo, e o RUN_SyncDBDev.sh vai tentar aplicá-los em qualquer banco que você sincronizar.

Crie uma pasta para o seu projeto e mova os scripts para lá:

mkdir -p ~/sources/guia-idempiere-projeto/migration
mv ~/sources/idempiere/migration/iD14/postgresql/*_PlaceholderForTicket.sql \
   ~/sources/guia-idempiere-projeto/migration/

Essa pasta vira o repositório Git do projeto. No módulo 04 o plugin mora nela.

3. Crie o pacote com Pack Out

Conceito: o Pack Out exporta objetos do Dicionário para um zip. Você lista o que quer levar, e o iDempiere descreve cada objeto em XML.

Entre como System, abra a janela Pack Out e crie o cabeçalho:

Na aba de detalhes, adicione uma linha para cada objeto, nesta ordem:

A ordem importa: na chegada, os objetos são criados de cima para baixo. A tabela precisa do tipo de entidade e da referência; a janela precisa das tabelas; o menu precisa da janela.

Salve e clique em Export Package, no cabeçalho. O iDempiere pergunta o Export Format: deixe XML.

O iDempiere gera EDU_Visitas.zip. Dentro dele:

EDU_Visitas/
└── dict/
    └── PackOut.xml

Abra o PackOut.xml e procure suas tabelas, suas colunas e a janela. Cada registro aparece com o seu UUID (EDU_Visita_UU, AD_Column_UU...), não com o ID.

4. Guarde o pacote no projeto

Copie o zip para o projeto, com o nome que o módulo 04 vai usar:

mkdir -p ~/sources/guia-idempiere-projeto/2pack
cp EDU_Visitas.zip ~/sources/guia-idempiere-projeto/2pack/2Pack_1.0.0.zip

O 1.0.0 no nome é a versão do pacote. Quando você mudar algo no Dicionário, gera o pacote de novo como 2Pack_1.0.1.zip, e assim por diante. Nunca altere um pacote já distribuído.

Agora inicie o Git no projeto e faça o primeiro commit:

cd ~/sources/guia-idempiere-projeto
git init
git add .
git commit -m "EDU Visitas 1.0.0: tabelas, janela e menu"

5. Aplique em outro ambiente com Pack In

No ambiente de destino (o iDempiere de um colega ou um segundo banco importado como no módulo 00):

1. Entre como System e abra a janela Pack In.
2. Crie um registro, anexe o 2Pack_1.0.0.zip e salve.
3. Clique no botão PackIn.
4. Confira o resultado na aba Package Installation da própria janela: o pacote aparece com o status da importação.
5. Entre como GardenAdmin, rode Role Access Update e abra a janela Visita Técnica.

O Pack In cria as tabelas e colunas no banco, sem precisar de Synchronize Column.

Se não tiver um segundo ambiente agora, pule este passo. No módulo 04 o pacote passa a ser aplicado automaticamente, e você testa por lá.

Checkpoint

Erros comuns

Desafio

Faça uma mudança pequena no Dicionário (por exemplo, a Display Logic do desafio do módulo 02), gere o pacote de novo como 1.0.1 e compare o PackOut.xml das duas versões com diff. Quais objetos mudaram?

Referência

Tipos de item no Pack Out

Aplicando vários pacotes pelo terminal

No servidor, o script utils/RUN_ApplyPackInFromFolder.sh <pasta> aplica todos os pacotes de uma pasta, sem abrir a interface. É útil em deploy automatizado.

Formatos

O Pack Out do iDempiere 14 exporta em XML, JSON ou YAML (parâmetro Export Format, perguntado ao clicar em Export Package). XML é o padrão e o mais usado pela comunidade.

Próximo módulo

04 · Plugin e classe de modelo: o pacote vai para dentro de um plugin OSGi, é aplicado sozinho quando o plugin sobe, e as suas tabelas ganham classes Java.