Como customizar relatórios no Business Central com AL?

Quando falamos de relatórios no Dynamics 365 Business Central, é comum o primeiro contato ser através dos layouts (Word, Excel ou RDLC). Eles resolvem boa parte das necessidades visuais, mas rapidamente chegam ao limite quando precisamos incluir novos campos, alterar datasets, aplicar regras de negócio ou expor dados que simplesmente não existem no relatório padrão.

É nesse ponto que entra a customização via código AL.

Este artigo é voltado para um público mais técnico, especialmente desenvolvedores e consultores técnicos de Business Central, e foca em como estender relatórios usando código, desde a preparação do ambiente até a criação de Report e Report Extension.

Quando usar código em vez de layout

Antes de entrar no código, vale alinhar o cenário correto de uso:

Use layout apenas quando:

• A informação já existe no dataset do relatório

• A necessidade é apenas visual (posição, fonte, formatação)

Use customização via AL quando:

• É necessário adicionar campos de outras tabelas

• A lógica de negócio define se o dado deve ou não aparecer

• O relatório padrão não expõe todos os dados necessários

• Você precisa reutilizar o relatório em múltiplos layouts

Layouts controlam como os dados aparecem.
Código controla quais dados existem.

Preparando o ambiente de desenvolvimento

Visual Studio Code

O Visual Studio Code é o editor padrão para desenvolvimento AL no Business Central.

Após instalar o VS Code, o próximo passo é preparar o ambiente com as extensões corretas.

Extensões essenciais

Instale obrigatoriamente:

• AL Language (Microsoft)
  Extensão oficial que permite criar, compilar, publicar e depurar extensões do Business Central.

Com isso, o ambiente já estará pronto para desenvolvimento técnico.

Criando um projeto AL

Com o VS Code aberto:

1. Pressione Ctrl + Shift + P

2. Execute AL: Go!

3. Selecione a pasta do projeto

4. Escolha o ambiente (Sandbox ou Docker)

Esse processo cria a estrutura base do projeto, incluindo o arquivo app.json , onde são definidos versão, dependências e permissões.

Report vs Report Extension

Esse é um dos pontos mais importantes — e onde muitos erros de arquitetura acontecem.

Report

Um objeto Report é utilizado quando:

• Você está criando um relatório totalmente novo

• Não existe um relatório padrão que atenda minimamente o cenário

• Você controla 100% do dataset e da lógica

Exemplo básico:

report 50100 "Sales Summary Custom"

{

UsageCategory = eportsAndAnalysis;

ApplicationArea = All;

dataset

{

dataitem(SalesHeader; "Sales Header")

{

column(No_; "No.") { }

column(SellToCustomerNo; "Sell-to Customer No.") { }

}

}

}

Report Extension

Já o Report Extension deve ser sua primeira escolha quando:

• O relatório padrão já existe

• Você precisa apenas adicionar campos ou lógica

• Quer manter compatibilidade com upgrades da Microsoft

Em ambientes SaaS, Report Extension é a abordagem recomendada.

Exemplo de extensão do relatório Sales – Invoice:

reportextension 50101 "Sales Invoice Ext" extends "Sales - Invoice"

{

dataset

{

add(SalesHeader)

{

column(MyCustomField; SalesHeader."Your Reference") { }

}

}

}

Nesse exemplo:

• O relatório original permanece intacto

• Um novo campo é adicionado ao dataset

• O campo passa a ficar disponível para layout Word, Excel ou RDLC

Nenhuma modificação direta no objeto padrão é necessária.

Adicionando dados de outras tabelas

Em cenários mais avançados, é comum precisar buscar dados que não estão diretamente no dataitem principal.

Exemplo usando variáveis e triggers:

var

Customer: Record Customer;

trigger OnAfterAfterGetRecord()

begin

if Customer.Get("Sell-to Customer No.") then;

end;

E então expor o campo no dataset:

column(CustomerName; Customer.Name) {}

Esse tipo de abordagem é muito comum em relatórios fiscais, comerciais e gerenciais.

Request Page: configurações e comportamento

A Request Page é a interface apresentada ao usuário antes da execução do relatório. É nela que definimos filtros adicionais, opções de processamento e parâmetros que influenciam diretamente o dataset.

requestpage

{

layout

{

area(content)

{

group(Options)

{

field(ShowDetails; ShowDetails)

{

ApplicationArea = All;

Caption = 'Show Details';

}

}

}

}

}

Aqui, o campo ShowDetails controla o comportamento do relatório em tempo de execução.

Triggers da Request Page

As principais triggers são:

• OnInit()
  Executada quando a request page é inicializada. Ideal para definir valores padrão.

• OnOpenPage()
  Disparada quando a página é aberta. Útil para validações iniciais.

• OnQueryClosePage(CloseAction)
  Executada quando o usuário clica em OK ou Cancel. Muito usada para validações antes da execução do relatório.

Exemplo:

trigger OnQueryClosePage(CloseAction: Action): Boolean

begin

if CloseAction = Action::OK then

if not ShowDetails then

Error('You must select Show Details to continue.');

end;

Estrutura básica da Request Page

Triggers de relatórios: quando cada uma é executada

Entender o ciclo de execução do relatório é fundamental para escrever código correto e performático.

Principais triggers

• OnPreReport()
  Executada uma única vez, antes do processamento do dataset. Ideal para inicializações globais.

• OnPostReport()
  Executada após o relatório terminar. Usada para limpeza ou logs.

• OnPreDataItem()
  Executada antes do dataitem ser processado.

• OnAfterGetRecord()
  Executada para cada registro do dataitem. Aqui acontece a maior parte da lógica.

• OnPostDataItem()
  Executada após o término do dataitem.

Atenção: lógica pesada dentro de OnAfterGetRecord() pode impactar seriamente a performance.

Labels: textos, traduções e boas práticas

Os labels são utilizados para textos fixos no relatório e permitem fácil tradução e manutenção.

Exemplo:

labels

{

TotalCaption = 'Total Amount';

}

Uso no código:

column(TotalText; TotalCaption) {}

Boas práticas:

• Use labels para qualquer texto fixo

• Evite strings hardcoded no código

• Facilita localização e manutenção

Definindo o formato do relatório (Word ou RDLC)

Ao criar um relatório novo, você define qual formato será utilizado.

report 50110 "Sales Report Word"

{

ApplicationArea = All;

DefaultRenderingLayout = LayoutWord;

...

...

rendering

{

layout(LayoutWord)

}

type = Word;

LayoutFile = 'myDocWord.docx';

}

layout(LayoutRDLC)

}

type = RDLC;

LayoutFile = 'myDocRDLC.rdlc';

}

}

}

O layout deve estar incluído no projeto e referenciado corretamente.

Relatório com layout Word

Boas práticas técnicas

Algumas recomendações importantes:

• Prefira Report Extension sempre que possível

• Evite lógica pesada em relatórios (impacta performance)

• Nomeie corretamente colunas do dataset (facilita manutenção)

• Documente campos adicionados ao relatório

• Pense sempre em upgrade safety

Relatórios são usados em massa — qualquer erro de performance aparece rápido.

Código e layout trabalham juntos

Um ponto importante para fechar:

Código não substitui layout.
Código habilita o layout.

Depois de adicionar campos via AL, eles passam a ficar disponíveis nos layouts Word, Excel ou RDLC, mantendo a separação correta de responsabilidades.

Conclusão

A customização técnica de relatórios no Business Central é o que separa ajustes simples de soluções realmente robustas.

Entender quando usar Report, quando usar Report Extension e como estruturar corretamente o dataset garante:

• Soluções mais limpas

• Menos retrabalho em upgrades

• Maior controle sobre dados e regras de negócio

Se você já domina layouts, dar esse próximo passo com AL é praticamente obrigatório.