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 Portinari ou o antigo THF (TOTVS HTML Framework).

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.

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:

  1. Sua página principal precisa ter o nome index.html
  2. Dentro da <head> da index é necessário ter a tag <base href="/">
  3. Não fazer uso de nenhum recurso externo, com exceção apenas do back-end REST.
    1. 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.
  4. Todos os arquivos utilizados precisam ser salvos em uma pasta com o nome do aplicativo.
  5. A pasta precisa ser compactada no formato zip.
  6. A extensão .zip precisa ser renomeada para .app
  7. O arquivo nome-do-aplicativo.app precisa ser compilado como resource no RPO.
  8. 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 "serverBackend": "/". (Será detalhado mais abaixo).
  9. 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)

[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.

[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.


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 THF",
"version": "12.23.0",
"serverBackend": "/",
"restEntryPoint": "rest",
"versionAPI": ""
}

Essa chave serverBackend é 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 serverBackend 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.

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.


04. ASSUNTOS RELACIONADOS




<style>
div.theme-default .ia-splitter #main {
    margin-left: 0px;
}
.ia-fixed-sidebar, .ia-splitter-left {
    display: none;
}
#main {
    padding-left: 10px;
    padding-right: 10px;
    overflow-x: hidden;
}

.aui-header-primary .aui-nav,  .aui-page-panel {
    margin-left: 0px !important;
}
.aui-header-primary .aui-nav {
    margin-left: 0px !important;
}
</style>