Olá! Neste artigo, você vai encontrar o passo a passo como integrar uma aplicação PO-UI diretamente ao menu do TOTVS Protheus utilizando a função FwCallApp.

Por que abrir uma aplicação PO-UI dentro do Protheus?

Integrar uma aplicação PO-UI ao menu do Protheus permite que suas telas web sejam tratadas como rotinas nativas do ERP: o usuário acessa pelo menu, a aplicação é descarregada pelo Protheus e aberta dentro do próprio sistema. Isso facilita a adoção pelas equipes e promove uma experiência mais integrada com os processos existentes.

Visão geral do processo

• Configurar o VS Code para reconhecer arquivos .app;
• Gerar a build da aplicação Angular (ng build);
• Ajustar angular.json caso haja erro por tamanho do projeto;
• Compactar a build em .zip e renomear para .app;
• Criar a estrutura de pastas esperada pelo Protheus (proteus/resource e proteus/src);
• Criar um fonte .PRW utilizando a função FwCallApp;
• Compilar o fonte no Protheus, configurar o menu e testar;
• Extras: Resolver problemas comuns (index não encontrado, ajuste do builder, limpeza do HTTP Root).

Preparando o ambiente no VS Code

Abra o projeto no VS Code. Se você estava executando a aplicação com ng serve, finalize a execução antes de prosseguir.

Precisamos fazer com que o VS Code reconheça arquivos com extensão .app. Para isso, abra as configurações em JSON e adicione e extensão a lista existente.

Salve as alterações e prossiga com a próximos passos

Gerando a build Angular

No terminal do VS Code, na pasta raiz do projeto, execute:

ng build

O processo pode demorar dependendo da máquina. Se aparecer um erro relacionado ao tamanho do pacote (por exemplo aviso de limite e erro por ultrapassar o máximo), é hora de ajustar os budgets no arquivo angular.json.

Ajustando budgets no angular.json

Abra o arquivo angular.json e localize a seção “budgets” relacionada ao build de produção. Você pode ajustar os valores de warning e error para evitar que builds relativamente grandes sejam bloqueadas. Exemplo:

“budgets”: [

{

“type”: “initial”,

“maximumWarning”: “1mb”,

“maximumError”: “2mb”

}

 ],

No nosso caso definimos warning em 1 MB e erro em 2 MB, o que permitiu a compilação normalmente por conta do tamanho do nosso projeto. Após ajustar, rode novamente o comando ng build.

Gerando o .app e organizando a estrutura para o Protheus

Depois da build concluída, será criada a pasta dist/nome-do-projeto. Compacte o conteúdo dessa pasta em um .zip e renomeie a extensão para .app. Esse é o arquivo que o Protheus vai consumir.

Dentro da pasta principal do projeto (local do seu fonte), crie a seguinte estrutura:

• proteus/
• proteus/resource/ → aqui deve ficar o arquivo seuProjeto.app
• proteus/src/ → aqui ficará o fonte PRW que chamará a aplicação

Criando o fonte PRW para chamar a aplicação (FwCallApp)

Na pasta proteus/src crie um arquivo PRW (por exemplo primeiraTela.prw) que contenha uma user function simples que ative a função FwCallApp informando o nome do projeto (o mesmo nome do arquivo .app dentro de resource).

#include “totvs.ch”
User Function POUI_TEST()
FwCallApp(“MyPOProject”)
Return

Observações importantes:

• O nome passado para FwCallApp deve ser exatamente o nome do projeto dentro da pasta resource (sem extensão);
• As versões recentes do Protheus suportam a porta multiprotocolo sem consumir licença adicional — verifique se a LibCore está instalada e configurada;
• Verifique se appserver, dbaccess e license estão em execução antes de compilar o fonte .PRW no Protheus.

Compilar e configurar o menu no Protheus

Recompile o arquivo PRW. Após compilar, abra o Configurador e inclua um novo item de menu que aponte para a userfunction criada.

Ao gerar o menu e salvar, ao acessar a nova rotina o Protheus vai descarregar a aplicação para seu HTTP Root (AppRoot) e executar o .app apresentado em resource.

Erros comuns e como resolver

1) Index não encontrado (erro ao abrir a aplicação)

Dependendo da versão do Angular/JavaScript pode ocorrer um erro de “ajustar index” onde o Protheus não encontra o index.html gerado. Para resolver isso:

1. Apague a pasta correspondente ao seu app em: [Protheus]/Protheus_Data/HTTP_Root/AppRoot/ (o Protheus faz download e guarda cópias locais das aplicações);
2. No angular.json verifique o campo builder. Em versões mais novas do Angular esse campo pode vir como “application” e causar incompatibilidade. Altere para “browser” na configuração do build principal. Exemplo: trocar “builder”: “@angular-devkit/build-angular:application” para “builder”: “@angular-devkit/build-angular:browser”.

Depois de ajustar o builder, rode ng build novamente e verifique se o index.html foi gerado na pasta dist — o Protheus precisa desse arquivo para abrir a aplicação corretamente.

2) Limpeza do HTTP Root

Se o Protheus já armazenou uma versão anterior da sua aplicação e está apresentando comportamento estranho, acesse:

[Protheus]/Protheus_Data/HTTP_Root/AppRoot/

E apague a pasta do seu projeto antes de testar novamente — isso força o Protheus a baixar a nova versão.

Testando dentro do Protheus

Após seguir todos os passos (subir serviços, compilar PRW, colocar o .app em proteus/resource, gerar menu e limpar a pasta HttpRoot se necessário), acesse a rotina no Protheus. No momento da primeira execução o sistema criará uma pasta com os arquivos da aplicação dentro da pasta HttpRoot e abrirá a aplicação PO-UI dentro do Protheus.

Considerações Finais

Esta aula foi uma breve explicação de como abrir uma aplicação PO-U de forma nativa no menu do TOTVS Protheus, para conferir o processo completo de forma prática sugerimos que assista o vídeo no início da página.

Cursos

Se você está buscando se tornar um desenvolvedor completo no Protheus, dominar REST, PO-UI e as demais tecnologias relacionadas ao Protheus, não fique de fora da nossa turma de alunos, clique aqui para mais detalhes.