Solução de problemas do App Builder

Este guia cobre erros e problemas comuns encontrados ao instalar, configurar e usar o Jitterbit App Builder. Comece com os passos de diagnóstico abaixo e, em seguida, encontre seu problema específico na seção relevante.

Para uma referência unificada que abrange integração, automação, gerenciamento de API, EDI e problemas de desenvolvimento de aplicativos em um só lugar, consulte o guia de solução de problemas do Harmony.

Passos de diagnóstico

Verifique sua versão em relação às notas de lançamento

O App Builder é entregue como versões discretas on-premises (App Builder 4.0 e posteriores; a linha 3.x e anteriores era chamada de Vinyl, cuja documentação é mantida separadamente), e cada versão incorpora correções acumuladas. Um sintoma que você está investigando pode já ter sido resolvido em uma versão mais recente, então anote a versão que você está executando e verifique as notas de lançamento do App Builder para uma correção correspondente antes de investigar mais a fundo. Atualizar para a versão mais recente disponível é a maneira mais rápida de descartar isso.

Determine se o erro é do lado do cliente ou do lado do servidor

Erros do lado do cliente e do lado do servidor são diagnosticados em lugares diferentes, e apenas erros do lado do servidor chegam aos logs do App Builder:

• Erros do lado do servidor ocorrem no próprio App Builder e quase sempre são registrados nos logs da aplicação. Você pode recuperar os detalhes mais tarde, mesmo que o usuário não tenha copiado a mensagem quando ela apareceu.
• Erros do lado do cliente ocorrem no navegador no computador do próprio usuário e não são registrados pelo App Builder. Para ver os detalhes, abra as ferramentas de desenvolvedor do navegador (F12 no Chrome ou Edge) e verifique o painel Console enquanto reproduz o erro.

Um erro que reporta um valor Url e faz referência a um arquivo JavaScript (.js) é do lado do cliente. Causas comuns incluem o design da página, um problema no template do aplicativo ou em um widget, ou uma conexão de rede lenta ou interrompida.

O painel Network do navegador também mostra o código de status HTTP retornado para cada solicitação, o que distingue um erro do cliente (por exemplo, 401 ou 404) de um erro do servidor (por exemplo, 500 ou 504). Veja Identificar códigos de erro HTTP.

Verifique os logs da aplicação

O App Builder registra logs tanto no produto quanto como arquivos no servidor. Em IDE > Monitoramento, você pode visualizar vários tipos de logs, cada um adequado a um tipo diferente de problema:

• Logs de Banco de Dados e Logs de Memória: Entradas de erro e eventos da aplicação, incluindo rastreamentos de pilha. Comece aqui para a maioria dos erros. As entradas são ordenadas por LogId, então classifique em ordem decrescente para trazer o erro mais recente para o topo.
• Logs de Eventos e Eventos do Sistema: Atividade de eventos em segundo plano e nível de sistema.

Para capturar mais detalhes, selecione uma entrada de log, clique em Editar Configuração e aumente a verbosidade do log (por exemplo, para Trace). Para incluir também os dados da aplicação que o App Builder normalmente oculta nos logs, ative Log Secure Data; veja Registrar dados seguros.

Na mesma caixa de diálogo, use Baixar Logs de Disco para baixar os logs de disco de todos os servidores no ambiente. Os arquivos também são gravados no diretório logs sob a raiz da instalação do App Builder. Para todas as opções de Monitoramento, veja Página de Monitoramento do IDE.

Ativar o registro do servidor de dados CData

Muitos conectores do App Builder são baseados em CData. Se um problema envolver um desses servidores de dados, ative o registro para ele e baixe o arquivo de log para inspecionar os detalhes no nível do conector. Veja Ativar o registro do servidor de dados CData.

Verificar logs de sessão, visualização de página e REST

Dependendo do problema, outros logs podem ser mais úteis do que os logs da aplicação:

• Logs de sessão e visualização de página: Os logs de sessão ajudam com problemas de autenticação, autorização e identidade; os logs de visualização de página mostram quais páginas um usuário visitou. Veja Registro de atividade de visualização de página e sessão.
• Aba de sessões: Em Monitoramento > Sessões, veja quem está atualmente conectado, a última atividade de cada sessão e contagens de visualização de página.
• Logs de REST: Solucione problemas de chamadas de API e webhooks de entrada e saída. Veja Configurar registro de REST.

Copiar mensagens de erro da interface do usuário

Quando uma mensagem de erro aparece na interface do App Builder, use o botão Copiar dentro da região de erro para copiar o texto completo do erro para a área de transferência. Cole-o em um editor de texto ou em um caso de suporte para uma revisão mais fácil. No log copiado, role até os dados da exceção, geralmente a parte mais descritiva e muitas vezes suficiente para resolver o erro por conta própria. Se Registrar Dados Seguros estiver ativado, os metadados da consulta SQL aparecem abaixo.

Diagnosticar problemas de conectividade de rede

Falhas de conexão ocorrem em um dos dois caminhos: do navegador de um usuário para o servidor do App Builder, ou do servidor do App Builder para outro servidor, como um banco de dados, uma API ou um host SMTP. Execute esses comandos a partir da máquina no início do caminho com falha, para que um teste do servidor do App Builder seja executado nesse servidor em vez de em uma estação de trabalho:

• telnet <hostname> <port> ou, no PowerShell, Test-NetConnection <hostname> -Port <port>: confirma que uma conexão TCP com a porta pode ser aberta. Uma falha indica uma regra de firewall, uma porta incorreta ou um serviço que não está escutando.
• nslookup <hostname>: confirma que o nome do host resolve para o endereço esperado.
• ping <hostname> e tracert <hostname>: mostram se o host é acessível e a rota tomada, em redes que permitem tráfego ICMP.
• ipconfig /displaydns: lista entradas DNS em cache, o que é útil após uma alteração no registro DNS.

Causas frequentes de falhas de conexão incluem um nome de host ou porta incorretos, resolução DNS, um firewall ou lista de permissões que omite alguns dos endereços IP do serviço remoto (alguns serviços publicam uma ampla gama), configuração do IIS e um servidor sobrecarregado ou mal configurado entre os dois pontos finais.

Capture um arquivo HAR

Um arquivo HAR (HTTP Archive) registra cada solicitação de rede que um navegador fez enquanto uma página estava carregando ou uma ação estava sendo realizada. É útil quando uma página carrega lentamente, nunca termina de carregar ou falha sem produzir um erro registrado, e o suporte da Jitterbit pode pedir que você forneça um. Para o procedimento, veja Gerar um arquivo .har.

Recupere um despejo de processo

Se o App Builder estiver lento para responder ou não responder, recuperar um despejo de processo do processo de trabalho w3wp.exe do IIS pode ajudar o suporte a diagnosticar a causa. Veja Recuperar um arquivo de despejo para instruções.

Instalação e inicialização

O App Builder não inicia e retorna um erro 500

• Sintoma: O App Builder não inicia no IIS e retorna um erro HTTP 500.
• Possível causa: O Pacote de Hospedagem do Runtime ASP.NET Core que o App Builder requer não está instalado no servidor Windows, portanto, o IIS não consegue iniciar o aplicativo.
• Solução:
  1. Instale o Pacote de Hospedagem do Runtime ASP.NET Core necessário para o App Builder, conforme listado nos Requisitos do sistema.
  2. Reinicie o IIS e verifique se o App Builder carrega corretamente.

O App Builder não inicia e retorna um erro HTTP 500.30

• Sintoma: O App Builder não inicia e retorna:

  HTTP Error 500.30 - ASP.NET Core app failed to start
  

• Possível causa: A identidade do pool de aplicativos do IIS não tem acesso total à pasta raiz do App Builder, portanto, o aplicativo não consegue iniciar.

• Solução:

  1. Conceda à identidade do pool de aplicativos do App Builder (por padrão, IIS AppPool\Vinyl) Controle total da pasta raiz do App Builder. Veja Definir permissões.
  2. Reinicie o pool de aplicativos e, em seguida, recarregue o App Builder.

O App Builder retorna um erro HTTP 503

• Sintoma: Abrir o App Builder retorna:

  HTTP Error 503. The service is unavailable.
  

• Possível causa: O pool de aplicativos do IIS para o App Builder está parado.

• Solução:

  1. Abra o Gerenciador do IIS e selecione Pools de Aplicativos.
  2. Selecione o pool de aplicativos do App Builder (por padrão, Vinyl), e em seguida selecione Iniciar.

  Nota

  Se o pool de aplicativos parar novamente imediatamente após iniciar, é provável que o App Builder esteja falhando na inicialização. Revise os logs da aplicação e o Visualizador de Eventos do Windows para o erro subjacente.

O App Builder inicia, mas não cria bancos de dados

• Sintoma: O App Builder inicia com sucesso, mas nenhum banco de dados é criado no SQL Server.
• Causa possível: O arquivo de conexão tem uma extensão incorreta (por exemplo, .txt em vez de .xml).
• Solução: Localize o arquivo de conexão do App Builder e confirme se ele usa a extensão .xml. Renomeie o arquivo se a extensão estiver incorreta e, em seguida, reinicie o App Builder. Se o App Builder iniciar, mas retornar um erro de conexão em vez de criar silenciosamente nenhum banco de dados, consulte Ocorre um erro ao carregar as informações de conexão do banco de dados.

Ocorre um erro ao carregar as informações de conexão do banco de dados

• Sintoma: O App Builder retorna o seguinte erro:

  An error occurred while attempting to load the database connection information.
  

• Causa possível: O arquivo Connection.xml está ausente ou contém dados de conexão incorretos.

• Solução:

  • Substitua ou atualize o Connection.xml com os dados de conexão corretos e, em seguida, reinicie o App Builder. Consulte Criar um arquivo de conexão.
  • Se o App Builder iniciar sem erro, mas não criar bancos de dados, consulte O App Builder inicia, mas não cria bancos de dados.

O App Builder carrega com estilo ausente ou quebrado

• Sintoma: O App Builder inicia, mas as páginas são renderizadas com estilo ausente ou quebrado (CSS).
• Possível causa: O arquivo ZIP de instalação não foi desbloqueado antes de ser extraído. O Windows marca arquivos baixados de outro computador como bloqueados (a "marca da web"), e extrair um arquivo ainda bloqueado propaga essa marca para os arquivos extraídos, o que pode impedir que os ativos de estilo do App Builder sejam carregados corretamente.
• Resolução:
  1. Exclua os arquivos extraídos.
  2. Desbloqueie o arquivo ZIP original: clique com o botão direito nele, selecione Propriedades, abra a aba Segurança e selecione Desbloquear. Veja Obter e descompactar o software.
  3. Extraia o ZIP novamente e reinicie a instalação ou atualização.

Falha no upload da licença

• Sintoma: O upload de um arquivo de licença falha com um dos seguintes erros:

  An unknown error occurred.
  

  405 POST Method not allowed
  

  Failed to deserialize license (d3fc6d4e835e)
  

• Possível causa: O WebDAV está instalado ou habilitado no IIS e pode interferir na solicitação POST usada para fazer o upload da licença.

• Resolução:
  1. Desinstale ou desative o módulo WebDAV no IIS.
  2. Tente fazer o upload da licença novamente.
  3. Se o WebDAV for necessário para outros aplicativos no servidor, entre em contato com o suporte da Jitterbit para obter orientações sobre como configurar ambos os serviços para coexistirem.

O App Builder não inicia automaticamente após uma reinicialização do servidor

• Sintoma: O App Builder não se torna disponível automaticamente após a reinicialização do servidor Windows, exigindo uma solicitação manual inicial para inicializar o aplicativo.
• Resolução: Para os passos de resolução, veja Solução de problemas do comportamento de inicialização automática.

Implantação do Docker: Licença do App Builder 4.x não pode ser carregada na interface do usuário

• Sintoma: Após atualizar do Vinyl 3.3 para o App Builder 4.x no Docker, o carregamento da licença do App Builder pela interface do usuário do App Builder falha ou a opção não está disponível.
• Possível causa: Implantações do App Builder 4.x no Docker não suportam o carregamento de licença pela interface do usuário.
• Resolução: Forneça a licença através de um dos seguintes métodos:
  • No arquivo docker-compose.yml, defina a variável de ambiente License__LicenseKey com a chave de licença do App Builder 4.x codificada em base64.
  • Adicione a chave de licença ao arquivo appsettings.json no subdiretório data do diretório de composição do Docker.

Alta disponibilidade: Todas as instâncias devem usar o mesmo appsettings.json

• Sintoma: Em uma implantação de alta disponibilidade, alguns nós do App Builder se comportam de maneira diferente de outros (por exemplo, a autenticação funciona em alguns nós, mas não em outros, ou as chaves de criptografia de dados são inconsistentes entre os nós).
• Possível causa: Cada instância do App Builder em uma implantação de alta disponibilidade deve usar um arquivo de configuração appsettings.json idêntico. Se os arquivos diferirem entre as instâncias, o comportamento será inconsistente entre os nós.
• Resolução:
  • Confirme que todas as instâncias do App Builder na implantação de HA possuem arquivos appsettings.json idênticos.
  • Após alterar a configuração em uma instância, aplique a mesma alteração a todas as outras instâncias e reinicie cada uma.

Falhas de autenticação

Falhas de login SSO ou redirecionamentos para a URL errada

• Sintoma: Usuários que tentam fazer login via single sign-on (SSO) encontram um erro de redirecionamento ou são enviados para uma URL inesperada.
• Possíveis causas:
  • O URI de Redirecionamento configurado no Provedor de Identidade (IdP) não corresponde à URL que o App Builder está usando.
  • Um proxy reverso ou balanceador de carga na frente do App Builder (por exemplo, IIS atrás de um F5) encerra o TLS, então o App Builder vê http enquanto a URL pública usa https. O URI de Redirecionamento então usa o protocolo errado e não corresponde ao valor registrado no IdP.
  • A URL de integração SSO no App Builder faz referência a um endereço desatualizado ou incorreto.
  • O provedor de segurança OpenID Connect no App Builder está mal configurado.
• Resolução:
  • No IdP (por exemplo, Okta ou Azure AD), confirme que o URI de Redirecionamento corresponde exatamente à URL do aplicativo App Builder, incluindo o protocolo (https://) e qualquer caminho.
  • No App Builder, revise a configuração do provedor de segurança em IDE > Provedores de Segurança e verifique se as configurações do OpenID Connect correspondem aos valores esperados pelo IdP.
  • Se a URL do App Builder mudou (por exemplo, após uma migração ou atualização de domínio), atualize o URI de Redirecionamento tanto no App Builder quanto no IdP.

A URL base não redireciona para a página de login

• Sintoma: Abrir a URL base de um ambiente do App Builder (por exemplo, https://example.com/) não redireciona para a página de login. Visitantes não autenticados são levados diretamente a um aplicativo em vez disso.
• Possível causa: O usuário anonymous integrado tem acesso à página inicial de um aplicativo. O App Builder redireciona automaticamente cada usuário para uma página inicial à qual eles podem acessar, então, quando o usuário anonymous pode acessar a página inicial de um aplicativo, todos os visitantes não autenticados são redirecionados para lá em vez de para a página de login.
• Resolução: Remova o acesso do usuário anonymous à página inicial do aplicativo para que os visitantes não autenticados sejam direcionados para a página de login.

Usuários locais não conseguem redefinir uma senha esquecida

• Sintoma: Usuários locais não conseguem redefinir uma senha esquecida. O link Esqueceu a Senha na tela de login está ausente ou não completa a redefinição.
• Possível causa: O grupo Usuários Anônimos não recebeu acesso ao aplicativo de redefinição de senha, então usuários não autenticados não conseguem acessar o fluxo de trabalho de redefinição de senha.
• Resolução: Conceda ao grupo Usuários Anônimos acesso ao aplicativo App Builder - Redefinição de Senha e adicione-o ao papel Redefinição de Senha. Veja Redefinição de senha para os passos completos de configuração, incluindo a configuração SMTP necessária.

A autenticação OAuth do Salesforce falha ou autentica com a instância errada

• Sintoma: Usuários que fazem login com SSO do Salesforce são inesperadamente autenticados com a instância errada do Salesforce, ou os tokens do Salesforce param de funcionar e os usuários são solicitados a reautenticar repetidamente.
• Possíveis causas:
  • Múltiplas instâncias do App Builder compartilham o mesmo Aplicativo Conectado do Salesforce. O Salesforce retém apenas os quatro tokens de atualização mais recentes por Aplicativo Conectado. Quando um quinto token é emitido, o mais antigo é invalidado, fazendo com que a instância que possui esse token perca a autenticação.
  • Múltiplas instâncias do Salesforce estão configuradas no App Builder, e o navegador do usuário já possui uma sessão ativa com uma instância do Salesforce. Quando o usuário tenta fazer login em uma segunda instância, o Salesforce reutiliza a sessão existente e faz o login do usuário na primeira instância em vez disso.
• Resolução:
  • Atribua um Aplicativo Conectado do Salesforce separado para cada instância do App Builder para evitar conflitos de tokens de atualização. Veja a documentação do provedor de segurança do Salesforce para detalhes de configuração.
  • Se um usuário estiver sendo autenticado com a instância errada do Salesforce, peça ao usuário para sair de todas as sessões ativas do Salesforce em seu navegador antes de tentar fazer login novamente.

Desempenho

O App Builder está lento ou não responde

• Sintoma: O App Builder responde lentamente às interações do usuário, ou o carregamento da página e as consultas estão expirando.
• Causas possíveis:
  • O servidor do App Builder possui recursos de CPU ou memória insuficientes para a carga atual.
  • Um problema de rede entre o usuário e o servidor do App Builder, como largura de banda limitada, perda de pacotes ou um firewall, está desacelerando a transmissão de dados.
  • Consultas ou lógica de aplicação não otimizadas estão produzindo páginas lentas, ou um serviço em segundo plano está consumindo recursos excessivos.
  • O processo de trabalho do IIS entrou em um estado não saudável.
  • Uma operação de longa duração excedeu o tempo limite de um proxy, balanceador de carga ou outro dispositivo de rede entre o navegador e o App Builder, que então desconectou o navegador. O navegador relata um erro como 504 Gateway Timeout, mas a operação continua a ser executada no servidor e pode ainda ter sucesso ou falhar após a desconexão do navegador.
• Resolução:
  • Revise a utilização de recursos do servidor (CPU, memória, I/O de disco) para identificar qualquer saturação de recursos.
  • Para descartar um problema de rede, conecte-se a partir de uma rede diferente (por exemplo, outra rede Wi-Fi ou um dispositivo móvel em uma conexão celular) e execute um teste de velocidade da internet. Se o desempenho melhorar em outra rede, a causa provavelmente é largura de banda limitada, um problema com o ISP ou um firewall, em vez do próprio App Builder.
  • Verifique os logs da aplicação em busca de erros recorrentes, timeouts ou avisos que possam indicar a causa.
  • Se o navegador relatou um timeout de gateway, use o histórico de eventos para determinar se a operação foi concluída no servidor antes de você tentar novamente. Como a operação continua a ser executada após a desconexão do navegador, tentar novamente pode duplicar o trabalho.
  • Revise os serviços em segundo plano ativos e o histórico de eventos em busca de trabalhos de longa duração ou travados. Para identificar consultas SQL lentas especificamente, veja Capturar e analisar consultas lentas.
  • Para páginas lentas causadas por consultas ou lógica de aplicação não otimizadas, veja Ajuste de desempenho do App Builder para orientação sobre otimização de consultas, indexação e design de aplicação.
  • Se o servidor parecer saudável, mas o App Builder continuar não respondendo, recicle o pool de aplicativos do IIS para o App Builder.
  • Se o problema for intermitente e difícil de diagnosticar, recupere um dump de processo para análise adicional. Veja Recuperar um arquivo de dump.

Dados e integrações

Valores de coluna criptografados aparecem em branco após reconfiguração da fonte de dados

• Sintoma: Valores armazenados em uma coluna criptografada aparecem em branco (nulo) no aplicativo após uma fonte de dados, tabela ou coluna ter sido excluída e recriada, ou após a atualização ou migração do ambiente do App Builder.
• Possíveis causas:
  • O App Builder deriva a chave de criptografia de cada coluna dos valores DataSourceId, TableId e ColumnId em seu modelo lógico. Se algum desses identificadores mudar (por exemplo, após excluir e recriar uma fonte de dados, tabela ou coluna), os valores criptografados existentes não poderão mais ser descriptografados. Nenhum erro é exibido: o valor aparece silenciosamente como nulo.
  • Durante uma atualização ou migração, a pasta keys da instalação anterior não foi copiada para a nova pasta de instalação, então o App Builder não consegue acessar o material da chave necessário para descriptografar os valores existentes.
• Resolução:
  • Se os valores criptografados aparecerem em branco após uma atualização ou migração, confirme que o conteúdo da pasta keys foi copiado da pasta de instalação anterior para a nova. Veja a etapa 5 de Restaurar configurações.
  • Para evitar perda de dados devido a mudanças de identificadores, evite excluir e recriar fontes de dados, tabelas ou colunas criptografadas que contenham dados. Para uma lista completa de limitações de criptografia, veja Criptografia de coluna em nível de aplicativo.
  • Antes de fazer alterações estruturais, exporte ou faça backup de quaisquer valores de coluna criptografada.
  • Se os identificadores já mudaram e os dados não puderem ser recuperados de um backup, entre em contato com o suporte da Jitterbit com detalhes da configuração original.

Falha ao preencher a linha de base do log de auditoria

• Sintoma: Preencher a linha de base do Log de Auditoria Completo gera um erro e a linha de base não é criada.
• Causa possível: A tabela não possui uma chave primária UUID de uma única parte. O Log de Auditoria Completo requer um UUID único para cada registro, portanto, tabelas com uma chave primária composta (de várias partes) não são auditadas por padrão. Para auditar tal tabela, você deve primeiro adicionar uma coluna de auditoria UUID.
• Resolução:
  1. Adicione uma coluna UUID à tabela e defina seu tipo de uso de coluna como Auditoria, em seguida, preencha-a para registros existentes. Para o procedimento completo, consulte Outras configurações de chave primária.
  2. Navegue até Painel de Ação > IDE > Configurações Adicionais e clique no botão Preencher Registros de Auditoria.
  3. Localize a fonte de dados do aplicativo, clique em Preencher Tudo (ou Preencher em tabelas individuais), em seguida, clique em Prosseguir para tentar novamente.

Sistema de Arquivos SharePoint: autenticação OAuth necessária a partir de abril de 2026

• Sintoma: Conexões do Sistema de Arquivos SharePoint falham na autenticação ou não podem ser criadas.
• Possível causa: A partir de 30 de abril de 2026, conexões do Sistema de Arquivos SharePoint requerem autenticação OAuth. Conexões usando autenticação legada não funcionam mais.
• Resolução:
  1. Atualize para o App Builder 4.61 ou posterior.
  2. Siga o guia de conexão OAuth do Microsoft SharePoint para configurar um provedor de segurança OAuth antes de criar ou atualizar o servidor de dados.

Sistema de Arquivos SharePoint: Arquivos não exibidos ou caminhos retornam erros

• Sintoma: Uma fonte de dados do Sistema de Arquivos SharePoint está conectada com sucesso, mas os arquivos não são exibidos, o conteúdo não é renderizado ou um caminho de diretório causa um erro.
• Possíveis causas:
  • O App Builder só pode acessar arquivos armazenados no diretório Documentos. Arquivos em outros diretórios do SharePoint não são acessíveis.
  • Nomes de arquivos são sensíveis a maiúsculas e minúsculas ao vincular entre fontes de dados. Uma discrepância de caixa entre o nome do arquivo do SharePoint e o nome usado em outra fonte de dados impede a renderização do conteúdo.
  • Usar uma barra (/) em um caminho de diretório em um objeto de negócios causa um erro.
• Resolução:
  • Confirme que os arquivos estão armazenados no diretório Documentos no SharePoint.
  • Verifique se os nomes de arquivos usados em objetos de negócios e vinculações de fontes de dados correspondem exatamente à caixa dos nomes de arquivos do SharePoint.
  • Ao especificar um caminho de diretório em um objeto de negócios, use barras invertidas (\) em vez de barras (/) . Por exemplo, use \documents\employees em vez de /documents/employees.

Conector do App Builder: A chave da API gerada não pode ser recuperada após sair da tela

• Sintoma: Um usuário do conector configurou o Conector do App Builder, mas o valor da chave da API não está mais disponível após navegar para fora da tela de geração da chave.
• Possível causa: A chave da API gerada é exibida apenas uma vez na tela Gerar Chave. Uma vez que você sai da tela, o valor não pode ser recuperado.
• Resolução:
  • Copie o valor da chave para a área de transferência imediatamente após ser gerado, antes de navegar para fora.
  • Se a chave não foi copiada, gere uma nova chave.

Conector do App Builder: erro 403 Proibido

• Sintoma: Conectar a um ambiente remoto do App Builder usando o Conector do App Builder retorna um erro 403 Proibido.
• Possível causa: A conta de usuário configurada para o conector não recebeu a função Conector Remoto do App Builder no ambiente de origem do App Builder.
• Resolução:
  1. No ambiente de origem do App Builder, abra a conta de usuário utilizada pelo conector.
  2. Atribua a função Conector Remoto do App Builder a esse usuário.

Webhook: Autenticação HTTP Básica requer o cabeçalho Authorization no payload

• Sintoma: Um webhook configurado para usar Autenticação HTTP Básica não processa os payloads recebidos corretamente.
• Possível causa: O método Autenticação HTTP Básica requer que o cabeçalho Authorization esteja presente no payload recebido. Sistemas de terceiros que omitem esse cabeçalho não se autenticam corretamente.
• Resolução: Use o método de autenticação Chave da API para o provedor de segurança do webhook em vez de Autenticação HTTP Básica. O método Chave da API não requer o cabeçalho Authorization e é mais amplamente compatível com remetentes de webhook externos.

O tempo de migração de data expira em grandes conjuntos de dados

• Sintoma: Uma operação de migração de data não é concluída e falha com um erro de tempo limite.
• Causa possível: As migrações de data são executadas como uma única transação de banco de dados durante uma atualização de aplicativo ou fonte de dados. Com grandes conjuntos de dados, a transação pode exceder o tempo limite de comando padrão do banco de dados.
• Solução: No arquivo Connection.xml do App Builder, aumente o valor de CommandTimeOut para permitir mais tempo para a conclusão da transação de migração.

Configuração de fuso horário

O servidor de aplicativo do App Builder e o servidor de banco de dados devem usar o mesmo fuso horário

• Sintoma: Os valores DateTime no aplicativo estão deslocados por compensações inesperadas, ou os horários exibidos no App Builder diferem do que é mostrado no banco de dados.
• Causa possível: O servidor de aplicativo do App Builder e o servidor de banco de dados estão configurados com fusos horários diferentes. Esses servidores devem estar sincronizados para que os valores DateTime sejam renderizados corretamente.
• Solução:
  1. Confirme que o servidor de aplicativo do App Builder e todos os servidores de banco de dados estão configurados para o mesmo fuso horário.
  2. No App Builder, defina o Fuso Horário Padrão da Fonte de Dados em cada servidor de fonte de dados e o Fuso Horário em cada fonte de dados para corresponder ao fuso horário do servidor de banco de dados. Consulte Fusos horários para etapas de configuração.

Notificações por e-mail

Erros de configuração SMTP

• Sintoma: O App Builder não consegue enviar notificações por e-mail, e os logs do aplicativo ou a saída do Testar E-mail mostram um dos seguintes erros:

  Argument passed in is not serializable. Parameter name: value
  

  Value cannot be null. ParameterName: From Address
  

  Unknown URI scheme. Parameter name: uri
  

  Authentication required
  

• Causas possíveis:

  • O campo Endereço de Origem do servidor de notificação SMTP está vazio, nulo ou usa um endereço de e-mail inválido (produz os dois primeiros erros acima).
  • O campo URI usa um formato inválido ou esquema não suportado (produz o erro "Esquema de URI desconhecido"). O URI deve usar o esquema smtp:// ou smtps://, por exemplo smtp://mail.exemplo.com:587.
  • Os campos Nome de Usuário ou Senha contêm credenciais incorretas (produz o erro "Autenticação necessária").

• Resolução: No IDE, nas opções Conectar, abra Servidores de Notificação, em seguida, abra o registro do servidor SMTP e verifique o campo que corresponde ao erro que você recebeu:

  • Verifique se o Endereço de Origem é um endereço de e-mail válido permitido para enviar e-mails através do host SMTP configurado.
  • Verifique se o URI usa o formato smtp://<hostname>:<port> ou smtps://<hostname>:<port>. Veja Configurar SMTP para protocolos e formatos suportados.
  • Verifique se o Nome de Usuário e a Senha correspondem às credenciais do servidor SMTP.
  • Após fazer uma alteração, use o recurso Testar E-mail na janela do servidor de notificação para confirmar as configurações antes de implantá-las em um fluxo de trabalho.

Páginas e comportamento do aplicativo

Links profundos param de funcionar após um aplicativo ou página ser renomeado

• Sintoma: Um link profundo que anteriormente direcionava os usuários para um aplicativo ou página específica não funciona mais.
• Causa possível: Renomear um aplicativo ou página no App Builder altera o caminho da URL usado nos links profundos. Qualquer link existente que contenha o antigo nome do aplicativo ou página não é mais válido.
• Resolução:
  • Atualize quaisquer sistemas externos, e-mails, portais ou favoritos que contenham a antiga URL do link profundo para usar o novo nome do aplicativo ou página.
  • Construa o novo link profundo navegando até a página de destino no App Builder e copiando a URL da barra de endereços do navegador, removendo a string de consulta (tudo a partir de ?) para obter a URL canônica.
  • Para evitar esse problema no futuro, use o campo Label para nomes de exibição e mantenha o campo Name (que determina o caminho da URL) curto e estável.

Um evento é acionado várias vezes ao salvar, inserir, atualizar ou excluir

• Sintoma: Um evento que deveria ser acionado uma vez é acionado várias vezes na mesma ação do usuário, resultando em registros duplicados, notificações duplicadas ou outros efeitos colaterais repetidos.
• Causas possíveis:
  • A ação ou validação do evento está registrada tanto na camada de dados quanto na camada de lógica de negócios simultaneamente. O App Builder permite essa configuração, mas aciona o evento uma vez por registro de camada.
  • O vínculo da ação está desvinculado ou está vinculado a mais de um registro. A ação é acionada uma vez para cada registro em escopo.
• Resolução: Abra o App Workbench, localize a configuração do evento e, em seguida, aborde a causa que se aplica:
  • Determine se a lógica pertence à camada de dados (para comportamento em toda a tabela) ou à camada de lógica de negócios (para comportamento específico da página). Consulte Configurar eventos para orientações e remova o registro duplicado da camada à qual não pertence.
  • Revise o vínculo da ação. Se estiver desvinculado ou vinculado a mais de um registro, limite-o ao único registro pretendido. Consulte Vinculação implícita e explícita.

Os controles de ícone HTML não respeitam as permissões de função

• Sintoma: Um controle de ícone HTML em uma página não respeita as permissões de função de um usuário. Por exemplo, um ícone que deveria estar desativado para usuários sem permissão permanece ativo.
• Possível causa: Ícones HTML se comportam como botões. Sem um evento anexado, as permissões baseadas em função não se aplicam ao ícone, portanto, ele permanece visível e ativo, independentemente da função do usuário.
• Resolução:
  1. Anexe um evento vazio ao controle de ícone HTML para que a visibilidade baseada em função se aplique.
  2. Especifique o acesso apropriado (por exemplo, Atualizar) na função para os usuários que devem ver o ícone.

O ícone de auditoria não aparece em uma página

• Sintoma: O botão ou ícone de Auditoria usado para visualizar os logs de Auditoria Completa não está visível em um painel de Formulário ou Grade.
• Possíveis causas:
  • O usuário não pertence à função App Builder - Administradores ou à função App Builder - Auditoria.
  • O painel da página não tem Mostrar Auditoria habilitado, ou o painel não é um painel de Formulário ou Grade.
• Resolução:
  • Confirme que o usuário pertence à função App Builder - Administradores ou à função App Builder - Auditoria. Veja Segurança.
  • Em um painel de Formulário ou Grade, habilite Mostrar Auditoria para o painel da página. Veja Habilitar auditoria completa em uma página.

Aplicativos móveis e offline

Para problemas com o aplicativo móvel App Builder (incluindo travamentos, falhas, links bloqueados e problemas de salvamento de imagens), consulte Solução de problemas do aplicativo móvel.

Aplicativo offline: O banco de dados local é apagado quando o aplicativo é atualizado

• Sintoma: Após um aplicativo offline ser atualizado, todos os dados armazenados localmente no dispositivo móvel desaparecem.
• Causa possível: O banco de dados local de um aplicativo offline é apagado sempre que o aplicativo é atualizado. Esta é uma limitação conhecida dos aplicativos offline.
• Solução:
  • Certifique-se de que todos os dados coletados localmente estejam totalmente sincronizados com o servidor antes que uma atualização do aplicativo seja implantada.
  • Informe os usuários sobre as atualizações planejadas com antecedência para que possam sincronizar antes que a atualização entre em vigor.

Aplicativo offline: Agendas em segundo plano não são executadas quando o aplicativo está fechado

• Sintoma: Tarefas agendadas ou processos em segundo plano em um aplicativo offline não estão sendo executados em um dispositivo móvel quando esperado.
• Causa possível: As agendas em segundo plano não são executadas quando o aplicativo App Builder está fechado no dispositivo móvel. As agendas só são executadas enquanto o aplicativo está aberto.
• Solução:
  • Informe os usuários que o processamento em segundo plano agendado requer que o aplicativo permaneça aberto.
  • Redesenhe fluxos de trabalho que dependem de agendas em segundo plano para serem acionados pela interação do usuário ou mova o processamento agendado para o lado do servidor.

Widgets

Para problemas com widgets que não ativam, carregam incorretamente ou falham ao ler um arquivo zip de widget, consulte Solução de problemas de widget.