TOTVS Educacional - Educacional - Portal - Portal Gestão Educacional não carrega a página inicial para Login

Incidente

Esse documento servirá como base para solução de alguns incidentes no Portal Gestão Educacional como a Página inicial para Login não carregar, 'Servidor não está respondendo', 'Ocorreu um erro', 'Ocorreu um erro interno no Servidor' e 'Alias não encontrado'. Obs: Caso o ambiente esteja armazenado em nosso Cloud TOTVS, as configurações abaixo deverão ser solicitadas ao nosso time de Suporte ao Cloud.

Ambiente

TOTVS Educacional - Educacional - Portal - A partir da versão 12.1.32

Solução

O Portal Gestão Educacional realiza o uso de API'S para buscar e armazenar informações. O controle destas API'S é feito pelo HOST. Para que o Portal funcione corretamente, é necessário expor as API'S para web, desta maneira, é necessário o uso do módulo URL Rewrite do IIS para que este módulo filtre as solicitações e encaminhe para o HOST as solicitações que sejam para a API. Nesse passo a passo, devem ser conferidas todas as configurações onde o Portal estiver instalado (caso usem ambiente n camadas).

1) O primeiro passo é acessar o IIS (Gerenciador de Serviços da Internet) e validar se o ARR está instalado e configurado. (caso tenha instalado e configurado o Application Request Routing (ARR) para o novo Portal do Professor ou o novo Portal de Pesquisa Pública, não é necessário realizar esse processo). O ARR é um módulo de roteamento baseado em proxy que encaminha solicitações HTTP para servidores de conteúdo com base em cabeçalhos HTTP, variáveis de servidor e algoritmos de balanceamento de carga.

Dicas: O IIS pode ser acessado por vários caminhos (lembre-se sempre de executar o mesmo como Administrador conforme print abaixo) entre eles, pesquisando pelo menu Iniciar em Ferramentas do Windows | IIS, pela Lupa na barra de tarefas, usando as teclas Windows + R digitando no menu Executar o comando InetMgr.exe, pela barra de endereço do Explorador de Arquivos usando o comando InetMgr.exe, pelo Gerenciador de Tarefas, pelo Painel de Controle, pelo Prompt de Comando, pelo diretório System32 da pasta Windows e pelo Power Shell.

Realize o download do ARR no link: https://www.microsoft.com/en-us/download/details.aspx?id=47333. Após realizar o download e instalação, clique no Servidor dentro do IIS, dê um duplo clique no ARR (estará dentro dos módulos no item IIS) e em seguida clique em Server Proxy Settings. 

Marque o checkbox 'Enable proxy' e em seguida clique em 'Aplicar'.

2) O segundo passo será acessar o IIS (Gerenciador de Serviços da Internet) e validar se o URL Rewrite está instalado e configurado. (caso tenha instalado o URL Rewrite para o novo Portal do Professor ou o novo Portal de Pesquisa Pública, não é necessário realizar esse processo). O URL Rewrite permite que os administradores do IIS criem regras personalizadas avançadas para mapear URLS de solicitação para outras URLS e também facilitar a localização dos mecanismos de pesquisa. 

Acesse o site https://www.iis.net/downloads/microsoft/url-rewrite para realizar o download do módulo do rewrite para o IIS conforme a versão do servidor. Após a Instalação, será criado um ícone com o nome 'URL Rewrite' no IIS. Lembrando que não vamos configurar o URL Rewrite que está no item do Servidor, somente o URL Rewrite que está no caminho da pasta de instalação do Portal Gestão Educacional.

Acessando o caminho da pasta de instalação no Portal pelo IIS e clicando em URL Rewrite, vamos ver que o Portal Gestão Educacional utiliza três regras para o rewrite (as regras vêm instaladas automaticamente, bastando configurá-las). A primeira é utilizada para direcionamento de API's onde não é necessário passar o alias selecionado. A segunda é utilizada para as API's onde é necessário passar o alias selecionado. A terceira é utilizada para fazer a comunicação entre o Portal Gestão Educacional e o eduCONNECT com o HUB (tecnologia utilizada para realizar a troca de mensagens entre usuários do Portal e o eduCONNECT).

Configuração da primeira regra: URL.

Dê um duplo clique para abri-la. Na parte de cima da regra no item Match URL, devemos deixar selecionado a opção 'Matches the Pattern' no item Requested URL e a opção 'Regular Expressions' no item Using. No campo 'Pattern' o caminho aliasname\.(.*)/api/(.*) já vem descrito automaticamente, caso não venha, o insira (observe se não ficará nenhum espaço em branco no início e no fim do caminho). O checkbox 'Ignore case' também deverá estar marcado.

Na parte baixa da tela no item Action, o sub item Action Type deverá estar selecionado como 'Rewrite'. Os checkboxes 'Append query string' e 'Stop processing of subsequente rules' deverão estar flagados.

Na linha chamada Rewrite URL, devemos inserir o seguinte caminho http://{R:1}.NOME DA MÁQUINA ONDE DO HOST OU IP SE FOR PUBLICADO:MESMA PORTA PRESENTE NA CHAVE APIPORT DO ARQUIVO DE HOST/api/{R:2}. Exemplo: http://{R:1}.maquinahost:8051/api/{R:2}. 

Validar o uso do HTTP e HTTPS na URL (conforme configurações customizadas da Instituição). Validar se existem espaços em branco a frente ou final da URL. Conferir se as chaves ou chavetas ( este símbolo no teclado } ) estão trocadas pelos colchetes ( este símbolo no teclado ] ). A configuração correta e original são as chaves (}) caracterizadas pela cor vermelha.

Sobre a parte onde está escrito para inserir o Nome da Máquina do Host ou IP se o DNS for publicado; dentre as formas mais simples de validar tanto o nome da máquina que está sendo executado o Host quanto o IP é pela utilização do Prompt de Comando (CMD). Para saber o nome da máquina podemos usar o comando 'HOSTNAME' e para o IP podemos usar o comando 'IPCONFIG' conforme exemplos dos prints abaixo. 

Obs: Existem diversas formas de saber se o DNS da Instituição está publicado em domínio .br ou domínios internacionais, esta configuração fica a cargo da equipe de Infra Estrutura de cada empresa, não sendo uma ação do escopo do suporte do Educacional. A validação dos nameservers do domínio pode ser feita por exemplo no site DNS Check.

Na URL nesse campo também precisamos ajustar a informação que virá como 'NULL", que será onde colocaremos a mesma porta da chave APIPORT do arquivo RM.Host.EXE ou RM.Host.Service.EXE presentes no caminho de instalação (de acordo com o uso do Host local ou Host Service de cada empresa) C:\totvs\CorporeRM\RM.Net. Importante que a porta não seja utilizada por outros processos.

A porta da APIPORT deverá estar reservada no Prompt de Comando (CMD). No CMD execute o comando netsh http and urlacl url=http://+:8051/ user=NetworkService. O CMD exibirá a mensagem 'Reserva de URL adicionada com êxito'. No exemplo acima utilizamos a porta 8051, mas caso a API esteja apontada para outra porta no Host, a porta deve ser alterada no comando acima. Caso a reserva já tenha sido feita, o CMD exibirá  mensagem abaixo. Caso tenha reservado uma porta incorretamente e deseje excluir a reserva, use o comando netsh http delete urlacl http://8051.

Após os devidos ajustes, clique no botão 'Aplicar'.

Configuração da segunda regra: API (apenas para versões anteriores à 12.1.2402)

A parametrização seguirá basicamente a mesma configuração da primeira regra. Dê um duplo clique para abri-la. Na parte de cima no item Match URL, devemos deixar selecionado a opção 'Matches the Pattern' no item Requested URL e a opção 'Regular Expressions' no item Using. No campo 'Pattern' o caminho api/(.*) já vem descrito automaticamente, caso não venha, o insira (observe se não ficará nenhum espaço em branco no início e no fim da URL inserida no caminho). O checkbox 'Ignore case' também deverá estar marcado.

Na parte baixa da tela no item Action, o sub item chamado Action Type deverá estar selecionado como 'Rewrite'. O checkbox 'Append query string' deverá estar flagado e o checkbox 'Stop processing of subsequente rules' não. Na linha chamada Rewrite URL, devemos inserir o seguinte caminho http://NOME DA MÁQUINA DO HOST OU IP SE FOR PUBLICADO:PORTA DA APIPORT/API/{R:1}. Exemplo: http://maquinahost:8051/api/{R:1}. As validações de nome de máquina do host, IP, portas, chaves, espaços em branco e etc, seguem as mesmas da primeira regra.

Configuração da terceira regra: HUB

Nessa configuração, não é necessário alterar nenhuma informação. A mesma já está preparada para atender o objetivo que será a atualização automática das mensagens recebidas no Portal Gestão Educacional através do menu Central quando utilizamos a funcionalidade para as Salas de Atendimento no Educonnect. Portanto a mesma não é necessária para o objetivo desse documento, que é fazer o Portal Gestão Educacional ser acessado com sucesso pelos Usuários. Caso queiram mais informações, seguem documentos abaixo.

Saiba mais: Configuração HUB

Saiba mais: Salas de Atendimento

Saiba mais: Configuração Rewrite TOTVS Educa Mobile

3) Seguindo as configurações para o Portal Gestão Educacional, o terceiro passo será validar se um dos arquivos RM.Host.EXE (se Instituição utilizar o Host local) ou RM.Host.Service.EXE (se a Instituição utilizar o Host Service) estão devidamente configurados no caminho da pasta de instalação: C:\totvs\CorporeRM\RM.Net.

Importante: Se utilizar o RM.HOST este tem que ser executado como administrador. Se utilizar o HOST.SERVICE, o usuário associado ao serviço tem que ter permissão para acessar a porta da API definida no URL. A configuração é realizada somente em um deles de acordo com o uso do Host no ambiente da Instituição!

No arquivo vamos inserir as chaves abaixo, sendo a chave EnableRealtime usada para a terceira regra do IIS (essa chave irá habilitar a comunicação com o HUB). Para a opção 'SubDomainMask' (apenas para versões anteriores a 12.1.2402) o nome da máquina deve ser inserido utilizando letras minúsculas (caso não seja um DNS publicado; caso seja um DNS publicado vamos inserir o IP publicado). O texto [ALIAS] não deve ser alterado. Exemplo abaixo.

<add key="EnableRealtime" value="true" />

<add key="ApiPort" value="porta_definida_no_rewrite (IIS)" />

<add key="DefaultDB" value="informe_aqui_o_nome_do_alias" />

<add key="SubDomainMask" value="[ALIAS].nome_da_máquina_do_host" />

4) Validar a configuração do arquivo CONFIG presente na pasta de instalação no caminho C:\totvs\CorporeRM\FrameHTML\web\app\Edu\PortalGestaoEducacional\config. No arquivo, vamos conferir as informações a seguir.

apiServer: Essa configuração é utilizada para realizar o redirecionamento para a API que será feito pelo módulo URL Rewrite do IIS. O endereço parametrizado, deve conter o endereço público do portal. A partir da versão 12.1.2402 este parâmetro poderá ficar vazio, pois o portal irá preenchê-lo com o mesmo endereço configurado para acessar o portal automaticamente. Saiba mais: ApiServer. Exemplo.

"apiServer": "http://NomeServidorIIS/FrameHTML/web/app/Edu/PortalGestaoEducacional",

urlHub: Usada para comunicação com as Salas de Atendimento do APP Educonnect. Exemplo. "urlHub": "http://NomeServidorIIS//framework/v1/realtime/hubs",

basepath: Deve ser configurado com o mesmo caminho relativo utilizado no portal no IIS. Exemplo. "basePath": "/FrameHTML/Web/App/Edu/PortalGestaoEducacional",

defaultAlias: Deve ser configurado com o alias padrão utilizado para fazer o acesso a base de dados. Este alias, deve estar cadastrado no arquivo Alias no caminho C:\totvs\CorporeRM\RM.Net. Exemplo. "defaultAlias": "CorporeRM",

multitenant: Configuração usada para ter apenas uma instalação e atender várias bases/alias sem a necessidade do usuário selecionar alias no RM.EXE e no Portal. Além disso a configuração permite que os web services fornecidos pelo HOST trabalhem sem a configuração de Alias Default para atender as requisições, ou seja um 'MultiAlias'. Se o ambiente da Instituição utilizar Multi Tenancy, a tag do SubDomainMask abaixo será obrigatória. Se o ambiente não for Multi-Tenancy, a utilização da TAG será opcional. Saiba mais: RM Multi Tenancy. Saiba mais: Configurando o Multi Tenancy. Exemplo.

"multitenant": true", (Alterar para TRUE, se utilizar MultiTenancy)

subDomainMask: Obrigatório informar somente para ambientes que usem Multi Tenancy. Obs: A tag "transport": 2, não deve ter seu valor alterado. Exemplo do arquivo após os ajustes. Exemplo. "subDomainMask": "[ALIAS].totvsserver",

5) Validar a configuração do arquivo Hosts do caminho C:\Windows\System32\drivers\etc (para o usuário do sistema fazer alterações nesse arquivo, o mesmo precisa ter liberado permissão ao Controle total na pasta Windows). Essa configuração é necessária apenas para as versões anteriores a 12.1.2402. A partir da versão 12.1.2402 está configuração não é necessária. Esta configuração precisa ser realizada em todas as máquinas que o IIS estiver configurado.

Quando a requisição da API chega no IIS, ela é filtrada pelo módulo do Rewrite e é redirecionada para o Host, mas como a requisição vem do IIS, o mesmo não consegue encontrar o endereço do Host, desta forma, a configuração que é feita no arquivo de Host do Windows irá informar para o IIS qual a máquina do Host.

Para cada alias cadastrado no RM, deve existir um registro no arquivo de host no seguinte modelo: Nome_Do_Alias.Nome_Da_Maquina_Do_Host ou Nome_Do_Alias.IP Publicado se o DNS for publicado, com todas as letras em minúsculo. Exemplo: 127.0.0.1 corporerm.servidor. Se a máquina em que o host está configurado é a mesma máquina em que o IIS está instalado, deve ser informado o nome ou IP das configurações do Rewrite (no item 'Actions' e no campo Rewrite URL); o valor pode ser localhost ou 127.0.0.1. Caso o Host esteja configurado em uma máquina diferente do IIS, o IP informado deve ser o IP da máquina do Host. Exemplo: 127.0.0.1 corporerm.10.0.0.0

Saiba mais: Configuração dos Hosts do Windows. Exemplo abaixo após a configuração.

6) Validar as configurações do Usuário que executa o Host Local na pasta RM.NET ou o Usuário que executa Host Service do Windows. Se utilizar o RM.Host, este tem que ser executado como administrador. Para que este aplicativo seja sempre executado como Administrador de forma automática, clique no RM.Host no caminho C:\totvs\CorporeRM\RM.Net. Ao selecioná-lo, clique com o outro botão do mouse em Propriedades. Acesse a guia Compatibilidade e clique em 'Alterar configurações de todos os usuários'. Dentro dessa opção marque o checkbox 'Executar este programa como Administrador' e em 'Aplicar'.

Para o Host.Service, execute o aplicativo 'Serviços' como Administrador (pode ser encontrado através do menu Iniciar do Windows. Clique duas vezes no registro para editá-lo. Por padrão, na aba 'Logon' vem marcada a opção 'Esta conta'. O usuário informado precisa ser administrador do servidor onde o Host estiver sendo executado, ou seja, o usuário associado ao serviço tem que ter permissão para acessar a porta da API definida na URL. Uma outra opção seria alterar a configuração de 'Esta conta' para 'Conta do Sistema Local'.

Após o ajuste (se necessário), acesse o aplicativo RM.Host.ServiceManager no seguinte caminho C:\totvs\CorporeRM\RM.Net e o execute como Administrador. Pare o (s) Host (s) e reinicie ele (s).

7) Reinicie o IIS como Administrador. O IIS pode reiniciado pelo próprio Gerenciador no botão 'Reiniciar' ao selecionar o servidor no lado esquerdo ou pelo Prompt de Comando (CMD) com o comando IISRESET.

Após as configurações, o Portal Gestão Educacional carregará sua tela para login e poderá ser acessado com sucesso. Conheça todas as funcionalidades do Portal Gestão Educacional: PGE - Funcionalidades