Solução de problemas do Design Studio

Este guia aborda erros e problemas comuns encontrados ao usar o Jitterbit Design Studio. Comece com as etapas de diagnóstico abaixo e depois encontre seu problema específico na seção relevante.

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

Se um agente privado estiver executando suas operações do Design Studio, consulte solução de problemas do agente privado para problemas com o próprio agente. Para erros que ocorrem quando as operações são executadas, o guia solução de problemas de operação aborda o Studio em vez do Design Studio, mas muitas das entradas (por exemplo, operações travadas, erros de script e falhas de conexão) também se aplicam às operações do Design Studio.

• Conector SAP

  -   [IDocs não encontrados quando uma operação agendada é executada em um agente diferente](#sap-idc-multi-agent)
  -   [Envios em massa de IDoc podem exceder limites de conexão do endpoint de destino](#sap-idc-bulk)
  -   [Carga útil do SAP IDoc perdida quando o endpoint de destino está inacessível](#sap-idoc-payload-lost)
  -   [Armazenamento e encaminhamento de SAP IDoc: arquivos temporários excluídos após 24 horas](#sap-idoc-temp-files)
  -   [Operação BAPI bem-sucedida, mas a transação não é confirmada no SAP](#bapi-no-commit)
  -   [SAP Event Listener não detecta IDocs no Windows](#sap-event-listener-no-trigger)
  

Etapas de diagnóstico

Verificar o log de erros

O Design Studio exibe erros do sistema em um painel de erros integrado. Selecione Error Log no menu View para abri-lo. Cada erro aparece como uma entrada separada com uma descrição. Para salvar os detalhes do erro para um caso de suporte, clique em Save no canto superior direito do painel de erros.

Verificar a página de problemas conhecidos

Consulte a página Problemas conhecidos do Design Studio para ver os problemas identificados em versões recentes do Design Studio.

Falhas de login e conexão

Erro de certificado SSL ou configuração de filtro de proxy

• Sintoma: O Design Studio exibe um erro de certificado SSL ou filtro de proxy ao tentar fazer login.
• Possíveis causas:
  • Um certificado SSL ou CA assinado usado pela rede (por exemplo, de um filtro da web, proxy ou VPN) não está presente no Jitterbit Java KeyStore.
  • A lista de permissões de IP do proxy de rede ou filtro da web não inclui os endereços Jitterbit necessários. Consulte Informações da lista de permissões.
• Resolução: Para obter as etapas completas de resolução, incluindo como adicionar certificados ao Jitterbit Java KeyStore, consulte Erro de certificado SSL ou configuração de filtro de proxy.

Usuários de SSO fora da região da organização não conseguem fazer login

• Sintoma: Após habilitar o logon único do Harmony (SSO) para a organização, usuários cuja região do Harmony é diferente da região padrão à qual a caixa de diálogo de login do Design Studio se conecta não conseguem concluir o login do SSO. Usuários na região padrão fazem login sem problemas.
• Possível causa: O Design Studio usa como padrão uma única URL de região do Harmony na caixa de diálogo de login. Quando o SSO está habilitado, o redirecionamento do SSO é resolvido apenas em relação à região do Harmony que hospeda a organização, portanto, os usuários devem apontar o Design Studio para a URL dessa região antes de fazer login.
• Resolução:
  • Na caixa de diálogo de login do Design Studio, pressione Ctrl + Shift + U para abrir o campo de URL. Digite a URL da região do Harmony da organização (por exemplo, https://na-east.jitterbit.com para NA ou https://emea-west.jitterbit.com para EMEA) e conclua o login do SSO.
  • Para tornar a alteração permanente, defina a URL no arquivo de configuração client.properties:
    • Abra <Jitterbit Studio Home>\configuration\client.properties em um editor de texto (no macOS, o caminho é /Applications/Jitterbit Studio [version].app/Contents/Java/configuration/client.properties).
    • Descomente o parâmetro cloud.url e defina-o como a URL regional.
    • Salve o arquivo e relance o Design Studio.

Instalação e inicialização

macOS: erro "Client Properties Do Not Exist" ao iniciar

• Sintoma: O Design Studio falha ao iniciar no macOS com um erro indicando que as propriedades do cliente não existem.
• Possível causa: O Design Studio foi iniciado diretamente da imagem de disco (.dmg) em vez da pasta Applications. O aplicativo deve ser copiado para a pasta Applications antes de conseguir localizar seus arquivos de configuração.
• Resolução:
  1. Saia do Design Studio se ele estiver em execução.
  2. Abra o arquivo do instalador .dmg.
  3. Arraste o ícone do Jitterbit Studio para o atalho da pasta Applications na janela do instalador.
  4. Inicie o Design Studio na pasta Applications (ou no Spotlight/Launchpad), não na imagem de disco.

Design Studio sinalizado como software malicioso no macOS Sequoia

• Sintoma: No macOS 15 (Sequoia), o macOS exibe um aviso de que o Design Studio é software malicioso e impede sua abertura.
• Possível causa: O Gatekeeper do macOS avisa sobre aplicativos que não são notarizados pela Apple e são distribuídos fora da Mac App Store. Como o Design Studio é distribuído pela página Downloads do portal Harmony, o macOS relata que não consegue verificá-lo quanto a software malicioso. Este é o comportamento padrão do macOS, não um problema real com o instalador.
• Resolução:
  1. Confirme que o Design Studio foi baixado da página oficial Downloads do portal Harmony.
  2. Se você vir o aviso de software malicioso para uma instalação baixada do portal, o aviso pode ser descartado: ele não indica um risco de segurança real com o instalador Jitterbit.

Problemas de exibição

Interface desfocada ou pequena no Windows 10 com monitores de alta densidade

• Sintoma: Os elementos do Design Studio aparecem desfocados ou muito pequenos ao executar no Windows 10 com um monitor de alta DPI, como um monitor 4K.
• Possível causa: Uma configuração padrão de dimensionamento de DPI do Windows 10 que não é compatível com o Design Studio.
• Resolução: Para as etapas de resolução, consulte Erro de dimensionamento de monitor de alta densidade do Windows 10.

Desempenho

Tempo longo de carregamento de projeto ao usar um proxy

• Sintoma: Abrir um projeto do Design Studio leva vários minutos quando se conecta através de um proxy. Isso pode vir acompanhado de um erro como:

  Message: Unable to load image icon at this address: https://citizen.jitterbit.eu/v1/endpoints/s3images/financialforce.png
  Details: Can't get input stream from URL!
  

• Possível causa: O atraso é normalmente causado pelo Design Studio tentando buscar ícones de receitas do Citizen Integrator através de um proxy que não consegue alcançar o servidor de imagens externo.

• Resolução: Para as etapas de resolução, consulte Tempos de carregamento longos ao usar um proxy.

Transformações

Transformação com script falha com erro /PRESCRIPT/ node

• Sintoma: Uma transformação que usa um script falha em tempo de execução com:

  Can not find target node (/PRESCRIPT/).
  The structure may have changed so try to open the transformation 'example' and refresh the structure trees.
  

• Possível causa: A estrutura XML interna da transformação ficou inconsistente com o esquema de destino atual, normalmente após uma alteração de esquema.

• Resolução:
  1. Abra a transformação com falha no Design Studio.
  2. No lado Target, clique no botão de atualização no topo da árvore de estrutura. Isso relê o esquema e reconstrói a estrutura interna da transformação.
  3. Salve e implante a transformação.

Unmap não desmapeia um campo quando usado junto com RunScript

• Sintoma: A expressão de mapeamento de um campo de destino envolve tanto RunScript quanto Unmap, mas o campo não é desmapiado. Para um destino JSON ou XML, o campo aparece na saída com um valor null em vez de ser omitido.

• Possíveis causas:

  • RunScript precede Unmap na mesma expressão de mapeamento (por exemplo, RunScript("<TAG>script:MyScript</TAG>"); Unmap();). Em versões de agente anteriores à 12.9, essa combinação não desmapeava o campo.
  • Unmap é chamado de dentro do script invocado por RunScript, em vez de diretamente na própria expressão de mapeamento do campo de destino. RunScript retorna o resultado do script chamado como uma string em vez de propagar um sinal de unmap de volta para o mapeamento, portanto chamar Unmap de dentro do script chamado não tem efeito, em qualquer versão de agente, independentemente de qualquer lógica condicional em torno da chamada. Este é o comportamento esperado.

• Resolução:

  • Se RunScript e Unmap forem ambos chamados diretamente na expressão de mapeamento do campo de destino, atualize o agente privado para a versão 12.9 ou posterior.

  • Se Unmap for chamado de dentro do script invocado por RunScript, mova a chamada Unmap para fora do script chamado e para a própria expressão de mapeamento do campo de destino, por exemplo:

    RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
    

Funções de data retornam meia-noite em vez de um valor apenas de data

• Sintoma: Após atualizar para a versão 12.8 ou posterior do agente, ConvertTimeZone, Date ou GeneralDate retorna uma string de data e hora completa (por exemplo, 2026-01-01 00:00:00) para uma entrada de exatamente meia-noite, em vez de uma string apenas de data (2026-01-01), o que pode quebrar a lógica downstream que espera o formato mais curto. CVTDate não é afetado.
• Possível causa: Com agentes versão 12.8 e posterior, essas funções tratam meia-noite (00:00:00) como um valor de hora válido e a preservam no valor retornado, da mesma forma que qualquer outra hora. Anteriormente, um valor de exatamente meia-noite era truncado para uma string apenas de data, enquanto qualquer outra hora era preservada corretamente.
• Resolução: Se a lógica downstream exigir um valor apenas de data, use FormatDate para formatar explicitamente o resultado em vez de depender do formato de saída padrão da função.

Marca de ordem de byte (BOM) em um arquivo de origem é passada para o valor do primeiro registro

• Sintoma: Quando um arquivo de origem (por exemplo, um arquivo CSV) começa com uma marca de ordem de byte (BOM) UTF-8, o primeiro campo do primeiro registro na saída de transformação contém um caractere extra ou inesperado que não faz parte dos dados de origem, em vez do valor esperado. Arquivos exportados como CSV UTF-8 do Microsoft Excel geralmente incluem esse BOM.
• Possível causa: Design Studio lê o conteúdo de um arquivo de origem como está e não detecta nem remove um BOM inicial. Os bytes brutos do BOM se tornam parte do valor do primeiro campo uma vez que o arquivo é analisado em registros.
• Resolução: Inspecione o valor do campo afetado para identificar os caracteres exatos produzidos pelo BOM e, em seguida, mapeie o campo usando Replace para removê-los. Em uma versão anterior, onde UTF-8 não é o padrão, você também pode definir explicitamente a codificação de caracteres como UTF-8 antes da atividade de origem ser executada, por exemplo $jitterbit.source.text.character_encoding = "utf-8";. Design Studio versão 11.63 e posterior, e agente versão 12.7 e posterior, usam UTF-8 por padrão.

Gerenciamento de projetos

Não é recomendado armazenar projetos do Design Studio em compartilhamentos de arquivo de rede

• Sintoma: Um projeto do Design Studio armazenado em um compartilhamento de arquivo de rede (em vez de localmente ou no armazenamento em nuvem do Harmony) apresenta perda de dados, onde as alterações da interface do usuário não persistem após reabrir o projeto, ou o desempenho é notavelmente mais lento do que o esperado.
• Possível causa: A Jitterbit não recomenda armazenar espaços de trabalho de projetos do Design Studio em compartilhamentos de arquivo de rede. O armazenamento em compartilhamento de arquivo de rede não possui os mecanismos de bloqueio de arquivo que o Design Studio requer, levando a salvamentos inconsistentes e possível perda de dados.
• Resolução: Mova o espaço de trabalho do projeto para armazenamento local ou use o armazenamento em nuvem do Harmony em vez de um compartilhamento de arquivo de rede.

O download do projeto falha com erro Invalid XML character

• Sintoma: O download de um projeto para o Design Studio falha com um erro indicando que um caractere XML inválido foi encontrado no conteúdo do elemento, por exemplo:

  An invalid XML character (Unicode: 0x15) was found in the element content of the document
  

  ou:

  org.xml.sax.SAXParseException; lineNumber: 17499; columnNumber: 21; An invalid XML character (Unicode: 0x5) was found in the element content of the document.
  

• Possível causa: Os metadados do projeto contêm um caractere de controle (como 0x05 ou 0x15) que não é válido em XML. Isso pode resultar de uma URL de endpoint corrompida ou de caracteres incomuns colados em scripts, notas ou outros campos de texto.

• Resolução:
  1. Abra o projeto no Design Studio (ou use um backup local recente) para inspecionar os metadados.
  2. Revise as URLs de endpoint, scripts e notas para caracteres invisíveis ou incomuns e remova-os ou substitua-os. O número da linha na mensagem de erro pode ajudar a localizar a área afetada no XML exportado.
  3. Salve e implante o projeto corrigido e tente novamente o download do Design Studio.
  4. Se o conteúdo ofensivo não puder ser identificado, entre em contato com o suporte da Jitterbit com a mensagem de erro completa e a ID do projeto para possível reparo de metadados no backend.

Componentes do projeto ausentes após download ou importação

• Sintoma: Abrir ou importar um projeto mostra operações na lista, mas nenhum componente (transformações, scripts, esquemas) aparece, ou um arquivo de exportação do projeto .json falha ao importar. A causa geralmente é um único componente corrompido na exportação do projeto que quebra a análise de todo o arquivo.
• Possível causa: Um componente dentro da exportação do projeto possui JSON malformado, como um corpo vazio ou caracteres incomuns que invalidam o arquivo.
• Resolução:
  1. Exporte o projeto do portal do Harmony para produzir um arquivo .json.
  2. Abra o arquivo .json em um editor de texto e inspecione o array components para entradas que pareçam vazias, malformadas ou contenham caracteres incomuns.
  3. Remova o objeto JSON completo do componente suspeito do array components.
  4. Salve o arquivo e importe-o novamente no Harmony.
  5. Se a corrupção não for identificável, envie a exportação do projeto para o suporte da Jitterbit para análise.

Operações ou transformações duplicadas aparecem em um projeto baixado

• Sintoma: Alguns usuários que baixam o mesmo projeto veem operações ou transformações duplicadas com nomes e esquemas idênticos, e essas duplicatas são sinalizadas como inválidas (marcadas em vermelho) no Design Studio. Outros usuários veem uma versão limpa do mesmo projeto.
• Possível causa: O projeto foi migrado no nível da operação (em vez de no nível do projeto), e a migração adicionou cópias duplicadas de dependências (como transformações) ao projeto original.
• Resolução:
  1. Faça um backup do projeto antes de fazer qualquer alteração.
  2. Identifique as operações ou transformações duplicadas. Exclua as duplicatas mantendo os originais.
  3. Implante o projeto limpo. Todos os usuários que baixarem novamente o projeto receberão a versão limpa.
  4. Para evitar isso no futuro, evite usar migração no nível da operação em um projeto que já contém os componentes de origem. Use migração no nível do projeto ou migre seletivamente apenas as dependências que ainda não estão presentes.

Falha na importação de projeto Salesforce com requisito de versão incorreto

• Sintoma: A importação ou abertura de um projeto com um endpoint Salesforce falha com um erro como:

  The Jitterpak requires version 12.7.0.0 or higher. The Studio is currently running version [your Design Studio version]. This means that the Jitterpak cannot be opened by this Studio.
  

  Isso pode ocorrer mesmo em uma versão atual e suportada do Design Studio, porque o Design Studio nunca teve um lançamento 12.x.

• Possível causa: O projeto foi exportado do Design Studio 11.63 ou 11.64. Essas versões marcam um projeto contendo um endpoint Salesforce com um requisito de versão incorreto (12.7.0.0) em vez da versão mínima correta. Design Studio 11.64.1 e posteriores exportam o requisito de versão correto.

• Resolução:

  • Se o projeto foi exportado para um arquivo .jpk local:

    1. Renomeie o arquivo .jpk para .zip e extraia-o.
    2. Em environment.properties, altere o valor requires-version para corresponder à sua versão instalada do Design Studio, por exemplo: requires-version=11.63.0.0.
    3. Em jitterpak.properties, altere o valor required_version para o valor codificado correspondente. Para Design Studio 11.63.0.0, use required_version=110630000000000. Para qualquer outra versão, exporte um novo projeto vazio do seu Design Studio instalado e copie os valores required_version e requires-version dos arquivos desse projeto.
    4. Comprima os arquivos extraídos de volta em um arquivo .zip, renomeie para .jpk e importe-o.

    Essas etapas corrigem apenas o arquivo .jpk que você edita. Reexportar o projeto do Design Studio 11.63 ou 11.64 escreve o requisito de versão incorreto novamente, portanto, atualize para Design Studio 11.64.1 ou posterior para evitar isso.

  • Se o erro ocorrer ao baixar ou abrir um projeto implantado na nuvem Harmony em vez de ao importar um arquivo .jpk local:

    1. Atualize para Design Studio 11.64.1 ou posterior.
    2. Entre em contato com o suporte Jitterbit para solicitar a correção de backend no requisito de versão armazenado do projeto, que não está disponível na interface do Design Studio. Solicite a correção apenas após atualizar: abrir ou reexportar o projeto com uma versão anterior afetada posteriormente pode escrever o requisito de versão incorreto de volta ao projeto.

Notificações

Falha de SOAP não consegue ser implantada quando configurada para disparar um email diretamente

• Sintoma: Configurar uma falha de SOAP para disparar diretamente uma notificação por email falha na implantação ou não funciona conforme esperado.
• Possível causa: Implantar uma operação na qual uma falha de SOAP dispara diretamente uma mensagem de email pode produzir um erro.
• Resolução:
  1. Configure a falha de SOAP para disparar uma operação em vez disso.
  2. Nessa operação, use a função SendEmailMessage em um script para enviar o email de notificação.

Conector de banco de dados

Banco de dados: Conexão bloqueada por política de segurança

• Sintoma: Um teste de conexão de origem ou destino de banco de dados falha com:

  HttpErrorResponse: The database connection could not be established due to a security policy violation.
  

  com uma linha de detalhes nomeando uma conexão de loopback:

  Details: java.lang.IllegalArgumentException - JDBC connections to loopback addresses are not permitted.
  

ou um parâmetro de string de conexão específico:

Details: java.lang.IllegalArgumentException - JDBC connection parameter 'allowmultiqueries' cannot be enabled.

• Possível causa: O Agent versão 12.10 e posterior restringe certas conexões de banco de dados e parâmetros de string de conexão por padrão, por segurança. Isso inclui conexões com localhost ou 127.0.0.1, e parâmetros de string de conexão específicos para os drivers MySQL, PostgreSQL, Oracle e SQL Server. Uma conexão que funcionava antes pode falhar após atualizar um agente privado para a versão 12.10, porque a restrição se aplica por padrão mesmo que a seção [JdbcSecurity] não seja adicionada automaticamente a um arquivo jitterbit.conf existente.

• Resolução: Em um agente privado, configure a seção [JdbcSecurity] do arquivo de configuração do agente (jitterbit.conf) para permitir a conexão ou o parâmetro específico necessário e reinicie o agente.

Fontes FTP e de arquivo

Transferências de arquivo se repetem inesperadamente

• Sintoma: Uma operação retransferencia um arquivo de origem que já foi processado em uma execução anterior.
• Possível causa: O Design Studio rastreia três critérios para determinar se um arquivo já foi transferido: nome do arquivo, data de modificação e ID da operação. Se algum desses valores tiver mudado desde a última transferência, o Design Studio trata o arquivo como novo e o transfere novamente.
• Resolução: Para evitar que um arquivo específico seja retransferido, delete sua entrada da lista de histórico de transferências: marque a caixa de seleção ao lado da entrada no painel inferior e clique em Delete.

FTP: Modo passivo e restrições de firewall de portas altas

• Sintoma: Uma fonte FTP se conecta com sucesso de uma estação de trabalho, mas falha quando a operação é executada no agente privado, ou as transferências de arquivo expiram apesar do agente conseguir alcançar o servidor FTP.
• Possível causa: O modo passivo FTP usa portas numeradas dinamicamente e altas para transferências de dados. Firewalls que restringem conexões de saída para portas bem conhecidas bloqueiam essas conexões de canal de dados, mesmo quando o canal de controle (porta 21) está aberto.
• Resolução:
  • Confirme que o Passive Mode está habilitado na configuração da fonte FTP (está habilitado por padrão).
  • Trabalhe com seu administrador de rede para abrir o intervalo de portas altas usado pelo seu servidor FTP para conexões de dados passivas no firewall entre o host do agente privado e o servidor FTP.

FTP: Os caminhos das pastas de sucesso e erro estão no agente, não no servidor FTP

• Sintoma: Os arquivos não aparecem na pasta de sucesso ou erro configurada após uma operação FTP ser executada, ou os caminhos parecem resolver para locais inesperados.
• Possíveis causas:
  • Os campos de caminho da pasta de sucesso e pasta de erro em uma fonte FTP se referem a diretórios na máquina do agente privado, não no servidor FTP remoto. Caminhos relativos são interpretados em relação ao sistema de arquivos do host do agente.
  • Variáveis de palavras-chave de nome de arquivo não são resolvidas nesses campos.
• Resolução:
  • Digite caminhos absolutos no host do agente privado para os campos de pasta de sucesso e erro (por exemplo, C:\Jitterbit\processed\ no Windows ou /var/jitterbit/processed/ no Linux).
  • Não use palavras-chave de nome de arquivo ou caracteres especiais como * nesses campos de caminho.
  • Confirme que a conta de serviço do agente tem permissões de escrita nos diretórios configurados.

FTP: Listagem de diretório não pode ser analisada

• Sintoma: Uma fonte FTP falha ao listar arquivos, ou arquivos conhecidos estão faltando na fonte mesmo que existam no servidor FTP.
• Possível causa: Alguns servidores FTP retornam listagens de diretório em um formato não padrão que o Design Studio não consegue analisar usando seu analisador padrão.
• Resolução:
  • Na configuração da fonte FTP, ative Listar apenas nomes de arquivo. Isso faz com que a fonte use o comando NLST, que retorna apenas nomes de arquivo em vez de uma listagem de diretório completa e é mais amplamente suportado em servidores FTP.
  • Alternativamente, defina a variável Jitterbit jitterbit.source.ftp.enable_regex_parser como true antes da etapa de leitura FTP para ativar um analisador de listagem mais flexível.

Alvo FTP: Usar Renomeação FTP não é funcional com operações de arquivo SFTP

• Sintoma: Arquivos gravados em um servidor SFTP usando um alvo FTP com Usar Renomeação FTP ativada falham ou não são gravados corretamente quando o tipo de operação é arquivo.
• Possível causa: A opção Usar Renomeação FTP não é funcional ao gravar em um servidor SFTP em uma operação de arquivo.
• Resolução: Na configuração do alvo FTP, desmarque a caixa de seleção Usar Renomeação FTP quando o servidor de destino for um servidor SFTP e a operação gravar um arquivo.

Alvo FTP: Criar Diretórios Automaticamente não é confiável

• Sintoma: Uma operação de alvo FTP falha porque um diretório de destino não existe, mesmo com Criar Diretórios Automaticamente ativado.
• Possível causa: É um problema conhecido que a opção Criar Diretórios Automaticamente funciona de forma inconsistente. Dependendo do servidor FTP específico, o diretório pode não ser criado.
• Resolução:
  • Crie manualmente os diretórios necessários no servidor FTP antes de executar a operação.
  • Se usar Criar Diretórios Automaticamente, confirme se o diretório foi criado antes de depender dele em produção.

Fonte de Compartilhamento de Arquivo: Arquivos individuais maiores que 2 GB não podem ser recuperados

• Sintoma: A recuperação de um arquivo grande de uma fonte de Compartilhamento de Arquivo falha, mesmo que o arquivo exista e a conexão da fonte esteja configurada corretamente.
• Possível causa: As fontes de Compartilhamento de Arquivo têm uma limitação conhecida em que arquivos individuais maiores que 2 GB podem não ser recuperáveis.
• Resolução: Divida arquivos maiores que 2 GB em segmentos menores antes de colocá-los no compartilhamento de arquivo para recuperação.

Fonte HTTP

Teste de conexão falha mesmo quando o endpoint está acessível

• Sintoma: Testar uma conexão de fonte HTTP falha com um erro de conexão ou autorização, mas o endpoint é confirmado como acessível e retorna dados quando acessado diretamente em um navegador ou cliente de API.
• Possível causa: O botão Testar Conexão na configuração da fonte HTTP envia uma solicitação HTTP HEAD. Alguns servidores não suportam o método HEAD e retornam um erro 405 ou similar, mesmo que solicitações GET e POST sejam bem-sucedidas.
• Resolução:
  1. Se o endpoint for confirmado como acessível em um navegador ou por meio de uma solicitação GET/POST direta, o teste de conexão com falha pode ser desconsiderado. Prossiga com a implantação e execução da operação para verificar a conectividade real.
  2. Se a operação também falhar em tempo de execução, investigue melhor usando os logs da operação.

Conector NetSuite

Erro de URL do data center: Use a URL WSDL específica da conta

• Sintoma: Um endpoint NetSuite que anteriormente se conectava com sucesso agora falha com:

  Connector Error: Error getting the data center URL.
  ...
  In this account, you must use account-specific domains with this SOAP web services endpoint.
  

  ou:

  You are not requesting the correct data center for your company.
  

• Possível causa: O NetSuite não aceita mais URLs WSDL genéricas (por exemplo, https://webservices.netsuite.com/...) ou URLs WSDL específicas do data center (por exemplo, https://webservices.na3.netsuite.com/...). O endpoint deve usar uma URL WSDL específica da conta.

• Resolução:
  1. No NetSuite, acesse Setup > Company > Company Information e abra a aba Company URLs para encontrar o domínio específico da conta.
  2. Construa a URL WSDL específica da conta no formato https://<account-id>.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl.
  3. Atualize o campo WSDL Download URL na configuração do endpoint NetSuite com a URL específica da conta.
  4. Para instruções completas, consulte URL WSDL específica da conta NetSuite.

Usuários com TFA não devem usar o tipo de autenticação SSO

• Sintoma: Um endpoint NetSuite configurado com autenticação de logon único (SSO) falha ou se comporta de forma inesperada para um usuário com autenticação de dois fatores (TFA ou 2FA) ativada em sua conta NetSuite.
• Possível causa: Usuários do NetSuite com TFA ativado não devem usar o tipo de autenticação SSO ao configurar um endpoint NetSuite. Essa combinação pode causar falha no endpoint. O tipo de autenticação SSO também está sendo descontinuado pelo NetSuite.
• Resolução:
  1. Ative a autenticação baseada em token (TBA) na conta NetSuite.
  2. Reconfigure o endpoint NetSuite para usar TBA em vez de SSO.

TBA: erro INSUFFICIENT_PERMISSION em tempo de execução apesar do teste de conexão bem-sucedido

• Sintoma: Um endpoint NetSuite configurado com autenticação baseada em token (TBA) testa a conexão com sucesso, mas as operações falham em tempo de execução com:

  INSUFFICIENT_PERMISSION
  

• Possível causa: A função usada para gerar os tokens de acesso TBA não possui permissões suficientes para as operações sendo executadas. O teste de conexão é bem-sucedido mesmo com uma função com permissões insuficientes, mas as verificações de permissão em tempo de execução falham.

• Resolução:
  1. No NetSuite, alterne para uma função de Acesso Total ou Administrador ao gerar os tokens de acesso, ou adicione as permissões necessárias à função atual.
  2. Regenere os tokens de acesso usando a função atualizada e reconfigure o endpoint NetSuite.

O dropdown de pesquisa salva fica vazio quando o objeto tem mais de 1.000 pesquisas salvas

• Sintoma: O dropdown de pesquisa salva na configuração da atividade NetSuite não é preenchido com nenhuma opção, mesmo que existam pesquisas salvas para o objeto no NetSuite.
• Possível causa: O NetSuite impõe um limite de 1.000 registros em solicitações de API. Se um objeto tiver mais de 1.000 pesquisas salvas, a solicitação de API para recuperá-las excede esse limite e não retorna resultados, deixando o dropdown vazio.
• Resolução: No NetSuite, exclua ou arquive pesquisas salvas que não estão mais em uso para reduzir a contagem total abaixo de 1.000 para o objeto afetado. O dropdown será preenchido assim que a contagem for reduzida. Para mais detalhes, consulte Limitações de pesquisa salva do NetSuite.

Não é possível passar valores NULL ou em branco para campos personalizados do NetSuite

• Sintoma: Mapear um valor NULL ou em branco (string vazia) para um campo personalizado do NetSuite não limpa o campo no NetSuite.
• Possível causa: A API do NetSuite não aceita valores NULL ou em branco para campos personalizados através da abordagem padrão de mapeamento de campos.
• Resolução: Para passar valores NULL ou em branco para um campo personalizado, mapeie o campo de origem para os campos filhos externalId e name do nó de destino do campo personalizado na transformação. Para mais detalhes, consulte Passando valores nulos para campos personalizados.

Segmentos personalizados não aparecem na configuração de atividade

• Sintoma: Segmentos personalizados não aparecem na tela de configuração de atividade do NetSuite quando deveriam estar disponíveis para mapeamento.
• Possível causa: A conta de usuário do NetSuite configurada no endpoint não possui permissões suficientes para acessar o segmento personalizado ou o objeto ao qual está associado.
• Resolução:
  1. No NetSuite, verifique se a conta de usuário configurada no endpoint do NetSuite possui as permissões apropriadas para interagir com o segmento personalizado e seu objeto associado.
  2. Se as permissões forem insuficientes, atualize a função do usuário no NetSuite para incluir o acesso necessário ao segmento personalizado.

Conector SAP

IDocs não encontrados quando uma operação agendada é executada em um agente diferente

• Sintoma: Em um grupo multi-agente usando processamento de IDoc com armazenamento e encaminhamento, a operação agendada que verifica arquivos de IDoc armazenados não encontra arquivos para processar em algumas execuções, e o processamento de IDoc é atrasado ou ocorre fora de ordem.
• Possível causa: No processamento com armazenamento e encaminhamento, o SAP Event Listener armazena cada IDoc recebido no sistema de arquivos local do agente que o recebeu. Uma operação separada com agendamento rápido verifica e processa esses arquivos, mas o Harmony pode enviar essa operação agendada para qualquer agente do grupo. Cada agente processa apenas os arquivos armazenados nele mesmo, portanto, arquivos armazenados em um agente não são processados até que o agendamento selecione esse agente novamente.
• Resolução: Cada agente processa seus próprios arquivos armazenados na próxima vez que a operação agendada é executada nele, portanto, os arquivos são eventualmente processados. Se os IDocs devem ser processados em uma ordem garantida, ou sem aguardar a próxima execução agendada do agente de armazenamento, grave os arquivos de IDoc em um recurso compartilhado que todos os agentes possam acessar, como um site FTP, um sistema de arquivos compartilhado ou um banco de dados. Observe que um armazenamento de dados externo adiciona um ponto de falha; clusters de agentes são usados para failover e balanceamento de carga.

Envios em massa de IDocs podem exceder limites de conexão do endpoint de destino

• Sintoma: Após uma grande operação em massa do SAP enviar milhares de IDocs, operações contra um sistema de destino downstream (como Salesforce) falham intermitentemente com erros de limite de conexão ou login.
• Possível causa: IDocs são enviados de forma assíncrona. Quando milhares de IDocs são gerados por uma atualização em massa, todos tentam disparar suas operações downstream simultaneamente. Sistemas como Salesforce aplicam limites de conexão de API simultânea, e uma enxurrada repentina de operações disparadas por IDoc pode exceder esses limites.
• Resolução:
  • Use um padrão de armazenamento e encaminhamento: configure o listener de IDoc para gravar IDocs recebidos em arquivos temporários e, em seguida, use uma operação agendada para processá-los em lotes controlados em uma taxa previsível.
  • Revise os limites de conexão simultânea e chamadas de API do endpoint de destino e configure a operação do Design Studio para permanecer dentro desses limites limitando o número de operações simultâneas.

Carga útil do IDoc do SAP perdida quando o endpoint de destino está inacessível

• Sintoma: Um IDoc é recebido pelo SAP Event Listener, mas os dados não chegam ao endpoint de destino e não podem ser recuperados.
• Possível causa: No processamento direto, se o endpoint de destino estiver inacessível quando o IDoc for processado, a carga útil não será entregue e será perdida permanentemente. Não há mecanismo de repetição automática no processamento direto.
• Resolução: Use o processamento store-and-forward: configure a primeira operação para gravar o IDoc recebido em um arquivo temporário e, em seguida, use uma operação agendada para processar o arquivo. Se o destino estiver inacessível, o arquivo é retido e reprocessado na próxima execução agendada. Para orientações sobre como implementar o processamento store-and-forward, consulte Práticas recomendadas para SAP.

SAP IDoc store-and-forward: Arquivos temporários excluídos após 24 horas

• Sintoma: Em um fluxo de trabalho de IDoc store-and-forward, arquivos temporários que não foram processados desaparecem do diretório de armazenamento antes da operação de processamento ser executada.
• Possível causa: Por padrão, arquivos IDoc temporários no processamento store-and-forward são automaticamente excluídos após 24 horas. Se a operação de processamento agendada não for executada dentro dessa janela (por exemplo, devido ao tempo de inatividade do agente), os arquivos serão removidos antes de poderem ser processados.
• Resolução:
  • Garanta que a operação de processamento agendada seja executada pelo menos uma vez a cada 24 horas para processar os arquivos antes de expirarem.
  • Como alternativa, aumente o período de retenção se uma janela mais longa for necessária. Para detalhes, consulte Práticas recomendadas para SAP.

Operação BAPI bem-sucedida, mas a transação não é confirmada no SAP

• Sintoma: Executar um BAPI parece ser executado sem erros, mas a transação esperada não aparece no SAP.
• Possível causa: O SAP Connector emite uma confirmação de transação BAPI apenas quando o BAPI retorna um tipo de resposta S (Sucesso). Se o BAPI retornar um tipo de resposta I (Informação), E (Erro) ou W (Aviso), nenhuma confirmação é emitida e a transação não é salva no SAP.
• Resolução:
  1. Verifique o campo TYPE do nó RETURN na resposta do BAPI para confirmar o tipo de resposta que está sendo retornado.
  2. Se estiver usando um BAPI personalizado, atualize-o para retornar um tipo de resposta S quando a transação deve ser confirmada. Para mais detalhes, consulte Solução de problemas de confirmações BAPI.

SAP Event Listener não detecta IDocs no Windows

• Sintoma: O serviço SAP Event Listener está em execução, o sistema SAP relata que os IDocs de saída foram enviados com sucesso, mas nenhuma operação é acionada. Os logs do agente mostram erros de conexão para o ID do programa RFC, como:

  serverException occured on [Program ID] connection null
  

• Possível causa: O arquivo de serviços do Windows no host do agente não contém uma entrada para o serviço de gateway SAP. Sem essa entrada, o listener do ID do programa RFC não consegue resolver o nome do host e a porta do gateway SAP, impedindo que iDocs sejam entregues ao Design Studio.

• Resolução:

  1. No host Windows que executa o agente privado, abra %WINDIR%\System32\drivers\etc\services como administrador.

  2. Adicione as seguintes linhas:

     sapgw00 3300/tcp
     sapgw00 3300/udp
     

  3. Salve o arquivo, reinicie o serviço SAP Event Listener e o agente, e teste novamente enviando um IDoc do SAP.

O nome do serviço sapgw00 e a porta 3300 correspondem ao serviço de gateway SAP padrão para o número do sistema 00. Se o seu sistema SAP usar um número de sistema diferente, ajuste as entradas de acordo (por exemplo, sapgw01 3301/tcp e sapgw01 3301/udp para o número do sistema 01).