01. DADOS GERAIS
Além das rotinas convencionais em ADVPL, que são acionadas no Protheus através do menu, se faz necessário que o menu também abra rotinas do tipo aplicativos web, no formato de front-end/back-end, como as rotinas que são criadas em Angular com o PO UI ou o antigo THF (TOTVS HTML Framework - Depreciado).
Para que isso seja possível, é necessário que esses aplicativos sejam armazenados no RPO e que tenham um controle de alterações. Essa solução deverá para permitir que o processo de atualização de um app seja feito com a aplicação de um patch, assim como uma rotina advpl comum.
O objetivo então é definir um padrão de criação de aplicativo para que seja possível automatizar o processo de extração, atualização, preparação de ambiente e abertura do aplicativo.
Disponível a partir da LIB 20190705.
Consumo de licenças
O consumo de licenças para aplicações PO-UI no Protheus funciona da seguinte forma:
1. Caso a aplicação for executada dentro do Protheus via função FwCallApp, utilizando a porta multiprotocolo, nenhuma licença adicional será consumida. Isso é possível utilizando a biblioteca de integração protheus-lib-core.
2. Caso a aplicação for executada via browser, acessando as requisições via REST padrão, sem o uso do protheus-lib-core, serão consumidas as licenças padrões do REST.
02. SOLUÇÃO
Criada a função FwCallApp("nome-do-aplicativo") para abrir através do menu, um aplicativo que tenha sido criado dentro dos seguintes padrões obrigatórios:
- Sua página principal precisa ter o nome index.html
- Dentro da <head> da index é necessário ter a tag <base href="/">
- Não fazer uso de nenhum recurso externo, com exceção apenas do back-end REST.
- Includes de arquivos js ou css diretamente de um CDN (Content Delivery Network) não são permitidos. É necessário baixar os arquivos de deixá-los disponíveis off-line.
- Todos os arquivos utilizados precisam ser salvos em uma pasta com o nome do aplicativo.
- A pasta com o nome do aplicativo deve ser criado com letras minúsculas.
- A pasta precisa ser compactada no formato zip.
- A extensão .zip precisa ser renomeada para .app
- O arquivo nome-do-aplicativo.app precisa ser compilado como resource no RPO.
- Caso utilize a comunicação com o back-end, é necessário possuir no diretório do app o arquivo /assets/data/appconfig.json com a chave "api_baseUrl": "/". (Será detalhado mais abaixo).
- Caso utilize rotas, será necessário existir uma rota para “index.html” apontando para o componente principal. (Geralmente aponta para o mesmo componente que a rota vazia '').
Requisitos provisórios de funcionamento (Apenas para ambientes com lib de label inferior à 20200214 ou appserver inferior à 7.00.191205P)
- Criação do parâmetro MV_GCTPURL do tipo caractere, com o conteúdo http://{hostname-do-servidor}:{porta-http}
- Criação do parâmetro MV_BACKEND do tipo caractere, com o conteúdo http://{hostname-do-servidor}:{porta-rest}/{chave-url-da-sessao-httpuri}
- Configurações ini do appserver:
[HTTP]
Enable=1
Port={porta-http-desejada}
Path={mesmo-caminho-do-rootpath-do-ambiente-utilizado}\http-root (valor fixo)
Obs.: Caso o ambiente já possua uma configuração de HTTP com outro PATH será necessário alterar para o valor fixo e mover todo o conteúdo da pasta antiga para essa pasta fixa chamada http-root que deve ficar dentro da rootpath.
Configuração para ambientes atualizados
Disponível a partir da LIB 20200214 e Appserver 7.00.191205P.
- Configuração ini do appserver:
[General]
App_Environment={nome-do-ambiente-utilizado}
* Para ambientes atualizados, os parâmetros MV_BACKEND e MV_GCTPURL e também a configuração de HTTP não são mais utilizados, bastando apenas a linha do App_Environment na General.
03. DEMAIS INFORMAÇÕES
Antes de abrir o browse com o aplicativo rodando, há um pré-carregamento HTML/JavaScript onde a FwCallApp carrega um token (bearer) de acesso às API’s REST e grava na sessionStorage['ERPTOKEN'] do aplicativo. (Obs.: As primeiras versões utilizavam o nome TOKEN, mas depois de alinhamento entre as marcas da Totvs foi mudado para ERPTOKEN)
Com esse token enviado no header Authorization de cada requisição HTTP é garantido o acesso às API’s com o perfil do usuário que se logou no Protheus antes de executar o aplicativo através do menu.
A partir da LIB 20210405 também será gravado na sessionStorage as informações de Grupo de Empresas e Filial, mais informações na documentação abaixo:
Contexto de Grupo de Empresas e Filial em aplicativos PO-UI embarcados no Protheus
Comunicação com o REST Server
Além do token de acesso, o front-end precisará saber o endereço em que o REST Server foi configurado.
Essa informação está disponível no arquivo appconfig.json que foi mencionado no item 8 dos padrões da solução.
Exemplo de arquivo de configuração:
{
"name": "Protheus PO UI",
"version": "1.1.0",
"api_baseUrl": "/"
}
Essa chave api_baseUrl é utilizada para definir o endereço e porta do servidor REST, e caso seja informada apenas como "/" será manipulada pela FwCallApp no momento de descompactação do resource. A chave api_baseUrl será atualizada para o endereço dinâmico que estiver respondendo o serviço do REST. Caso tenha outro valor diferente de barra, o mesmo não será alterado, porém é importante que o valor de endereço não contenha barra no final e que cada endpoint que será requisitado tenha seu endereço iniciado por barra (Isso irá evitar erros na concatenação do endereço).
* Existe também as chaves serverBackend e restEntryPoint que tinha o mesmo papel da api_baseUrl, mas devido à padronização de marcas, foram substituídas pela api_baseUrl.
Sendo assim o aplicativo tem o token na sessionStorage e o endereço no appconfig para fazer suas requisições ao backend.
*Caso utilize a biblioteca protheus-lib-core dentro de um projeto Angular, basta fazer as requisições informando apenas o endpoint, pois um interceptor se encarrega de anexar o host do appconfig e o token da sessionStorage de forma automática. Link https://npm.totvs.io/#/detail/protheus-lib-core
Cancelando o pré-carregamento
Caso um aplicativo não deseje utilizar os recursos disponibilizados pelo pré-carregamento, basta criar um arquivo em sua pasta raiz com o nome “noredirect” sem extensão.
Dessa maneira a função FWCallApp irá apenas fazer a extração do resource, o controle de atualização e irá chamar diretamente a index.html do aplicativo, sem carregar o token e sem configuração de backend.
Mesmo assim, ainda se faz necessário seguir os padrões obrigatórios para o correto funcionamento, inclusive o da tag base, pois mesmo não havendo pré-carregamento, se faz necessário manipular essa tag para que os caminhos relativos do aplicativo funcionem adequadamente.
Apenas para esclarecimento, essa tag se faz necessária pois o aplicativo não estará na pasta raiz do servidor HTTP. Ela estará em uma pasta com o nome do aplicativo que estará em uma pasta chamada app-root que por sua vez estará na pasta raiz.
Sendo assim qualquer chamada do tipo <script type="text/javascript" src="runtime.js"> iria procurar o arquivo na pasta raiz.
Então graças à tag <base href="app-root/myapp/"> o arquivo irá ser buscado na pasta myapp e não na raiz.
Pasta dentro do arquivo .app
Quando é gerado o arquivo .app, é recomendado que a pasta dentro do mesmo esteja com letras minúsculas.
Essa recomendação deve-se ao comportamento do appserver que sempre trabalha em lower case por padrão quando utilizadas funções de leitura e escrita no File System. Além disso, vale ressaltar, que o Appserver pode estar sendo executado em Linux, que á um S.O. case sensitive.
04. ERROS COMUNS
05. ASSUNTOS RELACIONADOS
PO UI - https://po-ui.io/
REST Server - http://tdn.totvs.com/pages/viewpage.action?pageId=75268866
Criação de parâmetros - http://tdn.totvs.com/pages/viewpage.action?pageId=306857908