Solução de problemas de conectores no Jitterbit Studio

Este guia abrange erros e comportamentos inesperados que são específicos para conectores individuais do Jitterbit Studio, organizados por conector. Ele lista apenas conectores que têm problemas conhecidos e específicos para documentar, não todos os conectores disponíveis. Para a lista completa de conectores, veja Conectores. Comece com os passos de diagnóstico abaixo e, em seguida, encontre seu conector na seção relevante.

Para problemas que não são específicos de um conector, como uma operação que não será executada ou um problema com uma transformação, script ou função, veja Solução de problemas de operação. Para problemas com agentes privados, como um agente que está offline, não saudável ou lento (o que pode impedir que operações sejam executadas), veja solução de problemas de agente privado.

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

Passos de diagnóstico

Esses passos se aplicam à maioria das falhas relacionadas a conectores e são o ponto de partida recomendado antes de investigar um erro específico do conector.

Testar a conexão

Na configuração da conexão, clique no botão Testar para confirmar que a conexão foi bem-sucedida. Clicar em Testar também baixa a versão mais recente do conector para o agente, a menos que a política da organização Desabilitar Atualização Automática do Conector esteja habilitada.

Atualizar os metadados da conexão e os esquemas de atividade

Muitos problemas de conectores, como objetos ausentes, uma lista de campos desatualizada ou um esquema que não corresponde mais ao endpoint, são causados por metadados em cache. Após qualquer alteração no lado do endpoint (novos campos, alteração de versão da API ou alteração de permissão), reabra a atividade afetada e clique no ícone de atualizar (Atualizar) para recarregar objetos e esquemas do endpoint.

Confirmar a disponibilidade do conector e mantê-lo atualizado

A coluna Disponibilidade do Agente na lista de Conectores mostra se um conector requer um agente privado.

Conectores são lançados e atualizados de acordo com o cronograma de lançamentos da Jitterbit, separadamente do agente. Em agentes privados, testar uma conexão baixa a versão mais recente do conector (veja Testar a conexão acima), a menos que a política organizacional Desativar Atualização Automática de Conectores esteja habilitada. Para atualizar os conectores de um grupo de agentes a qualquer momento, incluindo quando essa política está habilitada, selecione Ação > Atualizar conectores para o grupo na página Agentes do Console de Gerenciamento.

Habilitar registro detalhado do conector

Quando solicitado pelo suporte da Jitterbit, habilite o registro detalhado do conector no agente privado para capturar detalhes em nível de conector, em seguida, reproduza o problema e revise os logs. O registro detalhado utiliza uma entrada de logger específica do conector; a linha exata a ser adicionada ao logback.xml é fornecida na seção Solução de Problemas da página de documentação desse conector, sob Conectores.

Configuração da conexão

Propriedades de Configurações Avançadas: Variáveis contendo JSON bruto devem ser escapadas

• Sintoma: Muitos conectores incluem uma tabela de Propriedades de Configurações Avançadas para configurações de conexão opcionais. Variáveis usadas nesses campos que contêm JSON bruto devem ter o JSON escapado; passar JSON bruto não escapado por meio de uma variável faz com que o valor do campo fique malformado.
• Causa possível: Campos na tabela de Propriedades de Configurações Avançadas não suportam variáveis que carregam objetos JSON brutos não escapados.
• Resolução:
  • Antes de passar o conteúdo JSON por meio de uma variável em um campo de Propriedades de Configurações Avançadas, escape o JSON. Por exemplo, {"success": "true"} deve ser escapado como {\"success\": \"true\"} antes de ser atribuído à variável.
  • Se você estiver inserindo o valor JSON diretamente no campo (não por meio de uma variável), o escape não é necessário.
  • Variáveis em campos de Propriedades de Configurações Avançadas são preenchidas em tempo de execução apenas na versão do agente 10.75 / 11.13 ou posterior. Se um valor de variável não aparecer em tempo de execução, confirme se o agente atende a essa versão mínima.

Conector Amazon Bedrock

Amazon Bedrock: erro do modelo "throughput sob demanda não é suportado"

• Sintoma: Uma atividade Amazon Bedrock falha com:

  Invocation of model ID <model-name> with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model.
  

• Causa possível: Alguns modelos estão disponíveis apenas em regiões específicas e requerem um prefixo de região no ID do modelo.

• Resolução:
  1. Adicione o prefixo de região ao ID do modelo. Por exemplo, anthropic.claude-3-5-haiku-20241022-v1:0 se torna us-anthropic.claude-3-5-haiku-20241022-v1:0.
  2. Insira o ID do modelo com prefixo usando a opção Inserir identificador do modelo na configuração da atividade.

Conector Cloud Datastore

A atividade Deletar Itens relata sucesso, mas não exclui o registro

• Sintoma: Uma atividade Cloud Datastore Deletar Itens relata sucesso no log de operações, mas o registro alvo ainda existe quando consultado posteriormente.
• Causa possível: Deletar Itens identifica registros pelo valor da Chave (ou Chave Alternativa) do armazenamento, fornecido no array keys ou ids da solicitação. (Ambos os arrays aceitam valores de chave ou chave alternativa.) Se o ID interno do registro for fornecido em vez do valor da chave, nenhum item corresponde, e a atividade relata sucesso sem excluir nada.
• Resolução:
  • Na transformação que prepara a solicitação de Deletar Itens, mapeie o valor da Chave (ou Chave Alternativa) do armazenamento, não o ID interno do registro.
  • Ao encadear a partir de uma atividade Consultar Itens, mapeie o valor key da resposta da consulta na solicitação de exclusão.

Conector Coupa

Coupa: autenticação por chave de API retorna 403 Proibido

• Sintoma: Uma operação do conector Coupa falha com um erro Proibido (403) ao usar autenticação por chave de API.
• Possível causa: A partir da versão R35 do Coupa (janeiro de 2023), as chaves de API do Coupa estão obsoletas e não são mais suportadas para autenticação. Conexões configuradas para usar autenticação por chave de API recebem um erro 403.
• Solução:
  1. Na configuração da conexão Coupa, mude de autenticação por chave de API para autenticação OAuth 2.0.
  2. Na sua instância do Coupa, crie um aplicativo cliente OAuth 2.0 e obtenha as credenciais do cliente.
  3. Atualize a configuração da conexão com as credenciais OAuth 2.0, salve e teste novamente.

Conector de Banco de Dados

MySQL: driver ODBC não listado no dropdown do Studio

• Sintoma: Ao configurar uma conexão de Banco de Dados para MySQL usando um driver ODBC em um agente privado, o driver instalado não aparece no dropdown Driver no Studio.
• Possível causa: O gerenciador ODBC no host do agente privado não está mostrando o driver, geralmente devido a uma incompatibilidade entre 32 bits e 64 bits ou uma instalação incompleta do driver.
• Solução:
  • No host do agente privado (Windows), abra Fontes de Dados (ODBC) (em Ferramentas Administrativas) e confirme se o driver ODBC do MySQL está listado. Para opções de driver do MySQL, veja Conectar ao MySQL.
  • Confirme se o agente está se conectando à máquina correta: o driver ODBC deve estar instalado no host do agente, não na máquina do usuário do Studio.

MySQL: Acesso negado apesar de credenciais corretas

• Sintoma: A conexão a um banco de dados MySQL usando o conector de banco de dados falha com:

  Access denied for user 'root'@'%' to database 'test'
  

  mesmo quando o nome de usuário e a senha estão corretos.

• Causa possível: O MySQL pode conceder permissões diferentes com base no endereço IP do cliente. Uma conta de usuário pode ter os privilégios necessários de endereços IP específicos, mas não do endereço IP do agente privado.

• Solução:

  • No MySQL, verifique se a conta de usuário possui as concessões necessárias para conexões do endereço IP do agente privado. A sintaxe exata da concessão varia conforme a versão do MySQL (consulte a documentação do MySQL ou entre em contato com seu administrador do MySQL), mas geralmente tem a forma:

    GRANT ALL ON database.* TO 'user'@'agent-ip';
    

  • Teste a conectividade usando um cliente MySQL instalado diretamente no host do agente para isolar se o problema é baseado em rede ou específico do Jitterbit.

PostgreSQL: Erro de incompatibilidade de codificação do cliente

• Sintoma: Um teste de conexão do conector de banco de dados ao PostgreSQL falha com um erro de "incompatibilidade de codificação do cliente".
• Causa possível: A codificação que o servidor PostgreSQL utiliza difere da codificação padrão assumida pelo driver ODBC do PostgreSQL.
• Solução:
  • Nas configurações de conexão do banco de dados, adicione ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (substituindo pela codificação real do servidor) no campo Parâmetros Adicionais da String de Conexão.
  • No Windows, se o servidor usar uma codificação cirílica como WIN1251, também defina a codificação do cliente como WIN1251 nas configurações do driver ODBC.

Banco de Dados (ODBC): Caracteres multibyte não são tratados corretamente

• Sintoma: Ao ler ou gravar em um banco de dados através do conector de Banco de Dados usando um driver ODBC, caracteres multibyte ou não ASCII (por exemplo, caracteres acentuados ou não latinos) não são tratados corretamente.
• Causa possível: O suporte a caracteres multibyte para o conector de Banco de Dados através de um driver ODBC não está habilitado por padrão. A variável Jitterbit jitterbit.scripting.db.multibyte.enable deve ser configurada como true. Esse suporte está disponível na versão 12.6 do agente e posteriores, e não é necessário ao usar um driver JDBC.

• Solução:

  1. Confirme que o agente é da versão 12.6 ou posterior.

  2. Defina a variável jitterbit.scripting.db.multibyte.enable como true antes da operação no banco de dados ser executada. Por exemplo, em um passo de script:

     $jitterbit.scripting.db.multibyte.enable = true;
     

  Alternativamente, use um driver JDBC para a conexão com o banco de dados, que trata caracteres multibyte sem essa variável.

PostgreSQL: Use o driver fornecido pela Jitterbit no Linux

• Sintoma: Operações usando o conector de Banco de Dados para conectar ao PostgreSQL a partir de um agente privado Linux falham ou produzem erros, mesmo quando um driver parece estar instalado.
• Causa possível: Muitas distribuições Linux incluem um driver ODBC para PostgreSQL empacotado com unixODBC que não funciona de forma confiável com o Harmony.
• Solução: Não use o driver PostgreSQL empacotado pela distribuição. Use o driver ODBC para PostgreSQL incluído na instalação do agente Jitterbit.

IBM DB2 no iSeries: falha na conexão JDBC

• Sintoma: Uma conexão de Banco de Dados ao IBM DB2 no iSeries (AS/400 ou IBM i) usando um driver JDBC falha ao conectar.
• Possível causa: Algumas conexões ao DB2 no iSeries usando um driver JDBC encontram problemas que não ocorrem com um driver ODBC.
• Solução: Altere a conexão para usar um driver ODBC em vez de JDBC. Conexões ODBC são suportadas apenas em agentes privados.

IBM DB2: configuração do driver JDBC JCC (JAR e arquivo de licença obsoletos)

• Sintoma: Uma conexão de Banco de Dados usando o driver JDBC JCC do IBM DB2 falha com um erro referente a uma licença ausente, ou falha ou produz erros de compatibilidade com versões mais recentes do DB2.
• Possíveis causas:
  • O arquivo do driver db2jcc.jar implementa a especificação JDBC 3 obsoleta. O atual db2jcc4.jar implementa JDBC 4, que versões mais recentes do DB2 requerem.
  • O driver JCC requer um arquivo JAR de licença separado. Apenas o JAR do driver não é suficiente.
• Solução:
  • Use o driver db2jcc4.jar, não o obsoleto db2jcc.jar. Instale-o em <JITTERBIT_HOME>/tomcat/drivers/lib/ no agente privado.
  • Obtenha o arquivo JAR de licença da IBM (chamado db2jcc_license_cisuz-XX.jar, onde XX é o número da versão) e copie-o para <JITTERBIT_HOME>/tomcat/shared/lib/.
  • Alternativamente, use a biblioteca de código aberto JTOpen (também conhecida como driver AS400), que não requer o driver JCC ou um arquivo de licença.

Banco de Dados: a instrução SQL excede o limite de 2.000 caracteres

• Sintoma: Uma atividade de Consulta ao Banco de Dados falha ou é truncada quando a instrução SQL configurada é muito longa.
• Possível causa: O campo da instrução SQL em uma atividade de Consulta ao Banco de Dados aceita um máximo de 2.000 caracteres.
• Resolução:
  1. Crie uma visão de banco de dados que encapsule a lógica de consulta complexa.
  2. Referencie o nome da visão na atividade de Consulta em vez da instrução SQL completa.

Banco de Dados (JDBC): DBLookup ou DBExecute falha com um erro de decodificação Base64

• Sintoma: Uma função DBLookup ou DBExecute direcionada a um banco de dados PostgreSQL ou SQL Server através de um driver JDBC falha em tempo de execução com:

  Base64 decoding failed. Reason: error:00000000:lib(0)::reason(0)
  

  Isso ocorre sempre que o valor retornado se assemelha a dados codificados em Base64, como um JWT ou outro token de acesso, mesmo que a mesma consulta seja bem-sucedida quando executada diretamente contra o banco de dados.

• Possível causa: Versões do agente anteriores a 12.9 podem tentar incorretamente decodificar em Base64 um valor de resultado JDBC que corresponde a um padrão semelhante ao Base64, independentemente de o valor ser realmente dados codificados em Base64.

• Resolução:

  • Para agentes privados, atualize para a versão 12.9 ou posterior. Agentes em nuvem recebem a atualização automaticamente.
  • Se não for possível atualizar imediatamente, evite acionar a verificação de Base64 convertendo o valor afetado para hexadecimal na consulta SQL e, em seguida, decodificando-o em um passo de script usando HexToString. Por exemplo, no PostgreSQL: SELECT encode(<column>, 'hex'). Use o SQL equivalente decode(...,'hex') com StringToHex ao gravar o valor de volta no banco de dados.

Banco de Dados: DBLookup ou DBExecute falha com "Nenhum driver adequado encontrado" ao testar um script

• Sintoma: Testar um script (usando Executar teste) que chama DBLookup ou DBExecute falha com:

  No suitable driver found for [...]
  

  O mesmo script é executado com sucesso quando implantado e executado em uma operação.

• Possível causa: A Conexão de banco de dados usada pela função tem seu campo Login, Senha ou String de Conexão definido como uma variável global ou de projeto. Um teste de script executa apenas o script testado, portanto, a variável ainda não recebeu seu valor em tempo de execução quando a função resolve a conexão. Ao contrário de uma variável referenciada no campo configurado de uma atividade, isso não é coberto pelo valor padrão de uma variável; uma função de banco de dados não lê o valor padrão ao resolver uma conexão.

• Resolução: Antes da chamada da função, atribua temporariamente o mesmo valor real à variável global ou de projeto diretamente dentro do script testado (por exemplo, $login = "valor"; para uma variável chamada login), depois remova a atribuição antes de implantar a operação.

Microsoft Excel: "A operação deve usar uma consulta atualizável"

• Sintoma: Uma atividade de Banco de Dados Inserir ou Atualizar direcionada a um arquivo Microsoft Excel (via ODBC) falha com:

  [Microsoft][ODBC Excel Driver] Operation must use an updateable query
  

• Causa possível: O driver ODBC do Excel abre o arquivo do Excel em modo somente leitura por padrão, a menos que a string de conexão defina explicitamente o modo de leitura/gravação.

• Resolução: No campo String de Conexão da conexão com o Banco de Dados (inserido em Configurações Opcionais com Usar String de Conexão selecionado), acrescente ReadOnly=0; ao final da string de conexão para abrir o arquivo do Excel em modo de leitura/gravação.

Autenticação do Windows do SQL Server: Privilégios insuficientes

• Sintoma: Uma conexão Banco de Dados usando autenticação do Windows do SQL Server falha mesmo quando as credenciais do domínio parecem corretas.
• Causa possível: O usuário do domínio do Windows que executa o serviço do agente Jitterbit não possui os privilégios de nível de SO necessários para a Segurança Integrada do Windows.
• Resolução:
  1. Conceda ao usuário do domínio os privilégios do Windows Log on as a service e Act as part of the operating system no host do agente privado.
  2. Confirme que o usuário do domínio tem permissões de leitura e gravação no diretório de instalação do agente Jitterbit.
  3. Reinicie o serviço do agente Jitterbit após aplicar as alterações de privilégio.

SQL Server JDBC: A autenticação integrada do Windows falha

• Sintoma: Para agentes privados, uma conexão Banco de Dados ao SQL Server usando um driver JDBC e autenticação integrada do Windows falha com:

  This driver is not configured for integrated authentication. ClientConnectionId:...
  

  Os logs do agente também podem mostrar:

  java.lang.UnsatisfiedLinkError: no mssql-jdbc_auth-8.2.0.x64 in java.library.path
  

• Causas possíveis:

  • O DLL mssql-jdbc_auth necessário para a autenticação integrada do Windows está ausente dos diretórios JRE que o agente Jitterbit utiliza em tempo de execução. Colocar o DLL no mesmo diretório que o arquivo JAR JDBC não é suficiente.
  • A string de conexão não inclui o parâmetro integratedSecurity=true.

• Resolução:

  1. No host do agente privado, copie mssql-jdbc_auth-x.x.x.x64.dll (da distribuição do driver JDBC, usando a versão que corresponde ao arquivo JAR JDBC incluído com seu agente) para <JITTERBIT_HOME>/jre/bin e <JITTERBIT_HOME>/jre/lib. Faça um backup do arquivo, pois ele pode ser removido durante grandes atualizações do agente.
  2. Nas configurações de conexão do banco de dados, adicione integratedSecurity=true ao campo Parâmetros Adicionais da String de Conexão.
  3. Reinicie o serviço do agente Jitterbit.

SQL Server: A conexão falha com um erro de caminho de certificado PKIX

• Sintoma: Uma conexão Banco de Dados ao SQL Server falha com:

  "encrypt" property is set to "true" and "trustServerCertificate" property is set to "false" but the driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption: Error: (certificate_unknown) PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.
  

  Uma conexão que funcionou anteriormente pode começar a falhar após uma atualização do agente para a versão 12.8 ou posterior.

• Causa possível: As versões atuais do driver SQL Server MS JDBC solicitam uma conexão criptografada por padrão e validam o certificado que o servidor de banco de dados apresenta. A conexão falha quando esse certificado não pode ser rastreado até uma autoridade certificadora (CA) que o agente já confia, como um certificado autoassinado, um certificado emitido internamente ou o certificado CA da Amazon RDS que uma instância Amazon RDS para SQL Server apresenta. Esta é uma falha de confiança no certificado, e não de criptografia, portanto, um banco de dados pode ter a criptografia habilitada e um certificado válido instalado e ainda assim falhar. A versão 12.8 do agente atualizou o driver incluído para uma versão que solicita criptografia por padrão, portanto, uma conexão configurada antes dessa atualização pode falhar posteriormente.

• Resolução: Insira encrypt=false; no campo Parâmetros Adicionais da String de Conexão em Configurações Opcionais da conexão com o banco de dados, ou inclua-o em uma string de conexão manual. Isso funciona em agentes na nuvem e privados. Para mais informações, veja Criptografia de conexão e certificados de servidor.

  Cuidado

  Com encrypt=false, os dados transitam entre o agente e o banco de dados sem criptografia. Use esta opção apenas onde isso é aceitável para os dados e o caminho da rede envolvidos.

Kerberos: "Não foi possível inicializar a classe KerbAuthentication"

• Sintoma: Uma conexão de Banco de Dados usando autenticação Kerberos falha com:

  Could not initialize class com.microsoft.sqlserver.jdbc.KerbAuthentication
  

• Causa possível: Os arquivos de configuração do Kerberos no host do agente não têm as permissões de arquivo corretas.

• Resolução:

  1. No host do agente privado, defina as permissões de arquivo nos arquivos de configuração do Kerberos (jaas.conf, krb5.conf e o arquivo de cache de tickets do Kerberos) para 644:

     chmod 644 jaas.conf krb5.conf krb5cc_agent
     

  2. Reinicie o agente após aplicar as alterações de permissão.

Kerberos: Erros JGSS ou GSS durante o teste de conexão

• Sintoma: Uma conexão de Banco de Dados usando autenticação Kerberos falha com erros que referenciam jgss ou gss.
• Causa possível: A JVM está configurada com -Dsun.security.jgss.native=true, o que a direciona a usar a biblioteca GSSAPI nativa do SO. Em alguns sistemas, isso conflita com a configuração do Kerberos.
• Resolução:
  1. Remova o parâmetro -Dsun.security.jgss.native=true dos argumentos da JVM do agente.
  2. No krb5.conf, adicione udp_preference_limit = 1 na seção [libdefaults] para forçar TCP em vez de UDP para o tráfego do Kerberos.
  3. Reinicie o agente.

Banco de Dados: Arquivo JAR do driver JDBC sobrescrito em atualizações do agente

• Sintoma: Arquivos JAR de driver JDBC personalizados instalados para o conector de Banco de Dados são excluídos ou sobrescritos quando o agente é atualizado.
• Possível causa: Apenas o diretório <JITTERBIT_HOME>/tomcat/drivers/lib/ é preservado durante as atualizações do agente. Arquivos JAR de driver personalizados colocados em outros locais nos diretórios do agente fazem parte da implantação gerenciada e podem ser removidos ou sobrescritos durante uma atualização.
• Resolução:
  • Coloque arquivos JAR de driver JDBC personalizados em <JITTERBIT_HOME>/tomcat/drivers/lib/ em vez disso. Este diretório é preservado durante as atualizações do agente.
  • Se os drivers estiverem atualmente no local errado, mova-os para o diretório correto e reinicie o agente.

Banco de Dados: Caracteres especiais em nomes de colunas causam falhas em consultas

• Sintoma: Consultas ou transformações de Banco de Dados falham quando uma tabela de origem tem nomes de colunas que contêm caracteres especiais, como @.
• Possível causa: Drivers ODBC não conseguem lidar com certos caracteres especiais em nomes de colunas de banco de dados.
• Resolução:
  1. Crie uma visão de banco de dados na tabela física que exponha a coluna afetada sob um nome que não contenha caracteres especiais.
  2. Aponte a atividade de Banco de Dados para a visão em vez da tabela original.

SQL Server: "Não é possível inserir valor explícito na coluna de identidade" ao inserir em uma coluna de identidade

• Sintoma: Uma operação de conector de Banco de Dados que grava em uma tabela do SQL Server com uma coluna de identidade falha com:

  Database Error: Cannot insert explicit value for identity column in table '<table>' when IDENTITY_INSERT is set to OFF.
  

• Causa possível: A coluna de identidade está incluída na instrução INSERT que o conector de Banco de Dados gera para o destino. O SQL Server rejeita um INSERT que referencia uma coluna de identidade em sua lista de colunas (com um valor explícito ou nulo) enquanto IDENTITY_INSERT está definido como OFF. Mapear o campo para um valor nulo não o exclui: um campo de destino é omitido do INSERT apenas quando é mapeado com a função Unmap.

• Resolução:

  • Para permitir que o SQL Server atribua automaticamente o valor de identidade, exclua a coluna do INSERT mapeando o campo de destino de identidade com a função Unmap. Para excluir a coluna apenas quando a fonte não fornece valor, use um mapeamento condicional:

    If($source.id != "", $source.id, Unmap())
    

    Quando a condição é falsa, Unmap remove a coluna do INSERT e o SQL Server atribui o próximo valor de identidade. (Fornecer um valor explícito no ramo verdadeiro ainda requer que IDENTITY_INSERT esteja definido como ON; veja a próxima opção.)

  • Se você precisar inserir valores explícitos na coluna de identidade, defina IDENTITY_INSERT na tabela de destino em scripts SQL pré e pós dentro da atividade:

    SET IDENTITY_INSERT <table> ON;
    

    SET IDENTITY_INSERT <table> OFF;
    

    Use esta opção apenas quando você quiser intencionalmente controlar os valores de identidade de fora do banco de dados. Isso permite que valores explícitos sejam inseridos na coluna de identidade.

Banco de Dados: Erros de comprimento de campo na Inserção, Atualização ou Upsert

• Sintoma: Uma atividade de Inserir, Atualizar ou Upsert em um Banco de Dados falha com um status de operação Erro quando um valor de origem mapeado é maior do que o permitido pela coluna de destino. O log da operação contém uma das seguintes mensagens:

  One or more values were truncated when inserting and/or updating the field
  

  Field value too long
  FieldName: m_site  Length: 3  Length Allowed: 1
  

• Causa possível: Por padrão, se um valor de origem mapeado exceder o comprimento definido da coluna de destino, a atividade rejeita a linha e relata um status de Erro em vez de truncar o valor.

• Solução:
  1. Na configuração da atividade de Inserir, Atualizar ou Upsert do Banco de Dados, habilite Permitir truncamento de campos de caracteres para evitar erros de comprimento de campo. Com esta opção habilitada, os valores que excedem o comprimento do campo de destino são truncados e a operação relata um status de Sucesso com Informação em vez de um status de Erro.
  2. Se o truncamento não for aceitável, ajuste ou transforme o campo de origem no mapeamento de transformação para que os valores nunca excedam o comprimento da coluna de destino, ou amplie a coluna de destino no lado do banco de dados.
  3. Reimplante e execute novamente a operação.

Conector EDI para Cloud v2

As entradas de solução de problemas para o conector EDI para Cloud v2 estão documentadas no guia de solução de problemas de EDI, juntamente com problemas de EDI do Jitterbit. As entradas relevantes incluem:

• A atividade EDI para Cloud v2 falha em um agente privado atrás de um firewall ou proxy
• Erro de transformação: Campo não reconhecido na atividade EDI para Cloud v2
• Segmento ou loop EDI repetido mapeia apenas a última iteração
• Adicionando níveis de loop hierárquico aninhado (HL) a uma transformação EDI

Conector de Email

O teste de conexão do Gmail falha com erro de autenticação

• Sintoma: Um teste de conexão a uma conta do Gmail usando Autenticação Básica falha com um erro de autenticação, mesmo quando a senha correta da conta do Google é inserida.
• Causa possível: O Google exige uma senha de aplicativo para contas com a Verificação em Duas Etapas ativada. A senha da conta do Google não é aceita pelo SMTP ou IMAP quando a Verificação em Duas Etapas está ativa; apenas senhas de aplicativo são aceitas.
• Solução:
  1. Em sua conta do Google, gere uma senha de aplicativo para o aplicativo Jitterbit (veja a página de Entrar com senhas de aplicativo do Google).
  2. Na configuração de conexão de Email no Studio, insira a senha de aplicativo no campo Senha SMTP e/ou Senha IMAP em vez da senha da conta do Google.

A assinatura S/MIME falha ou é rejeitada por provedores de email em nuvem

• Sintoma: Emails configurados com assinatura S/MIME falham ao enviar, são rejeitados pelo servidor do destinatário ou chegam sem assinatura ao usar um provedor de email em nuvem, como Microsoft 365 ou Exchange Online.
• Causas possíveis:
  • Provedores em nuvem exigem um certificado S/MIME emitido por uma autoridade certificadora (CA) confiável. Certificados autoassinados não são aceitos por provedores em nuvem, como Microsoft 365 (Exchange Online).
  • O S/MIME é funcional apenas ao usar agentes privados. Se a operação for executada em um agente em nuvem, a assinatura S/MIME não se aplica, independentemente do tipo de certificado.
• Solução:
  1. Obtenha um certificado S/MIME de uma CA confiável. O Let's Encrypt fornece certificados gratuitos aceitos por grandes provedores em nuvem.
  2. Substitua o certificado autoassinado na atividade de Email Enviar Email pelo certificado emitido pela CA (veja Pré-requisitos para criptografia S/MIME).
  3. Para agentes privados, confirme se o certificado está corretamente importado no truststore padrão do agente. Para agentes em nuvem, a assinatura S/MIME não é suportada.

A conexão de email do Microsoft 365 usando autenticação ROPC falha quando MFA está habilitado

• Sintoma: Uma conexão OAuth 2.0 do Microsoft 365 que utiliza a concessão de Credenciais de Senha do Proprietário do Recurso (ROPC) falha na autenticação, mesmo quando o nome de usuário, senha, ID do cliente, ID do locatário e segredo do cliente estão todos corretos.
• Causa possível: A autenticação ROPC requer que a autenticação multifator (MFA) esteja desabilitada para as credenciais do Microsoft 365 usadas com o conector. A concessão ROPC não pode satisfazer um desafio de MFA, portanto, a solicitação de token falha quando uma política de MFA se aplica à conta.
• Resolução:
  • Use uma conta do Microsoft 365 cujas credenciais não estejam sujeitas a uma política de MFA. Para manter a segurança, crie um locatário ou diretório dedicado do Microsoft Entra ID que não imponha MFA, conforme descrito em Pré-requisitos para Microsoft 365.
  • Se a MFA não puder ser removida da conta, use um método de autenticação suportado diferente para a conexão em vez de ROPC.

O envio de email falha quando o mesmo endereço aparece em vários campos de destinatário

• Sintoma: Uma atividade de Enviar Email Email falha em tempo de execução quando o mesmo endereço de email está presente em mais de um dos campos Para, CC ou BCC.
• Causa possível: O conector de Email não permite que o mesmo endereço apareça em vários campos de destinatário em uma única solicitação de envio. Isso se aplica a endereços configurados diretamente na atividade e a endereços fornecidos dinamicamente por meio de um mapeamento de transformação.
• Resolução:
  • Revise os campos Para, CC e BCC na configuração da atividade e em qualquer mapeamento de transformação para a atividade para confirmar que nenhum endereço aparece em mais de um campo.
  • Se listas de destinatários forem montadas dinamicamente usando variáveis ou scripts, adicione uma verificação de deduplicação antes de passar endereços para a atividade.

Conectores Epicor

Epicor Prophet 21: A operação falha em tempo de execução com múltiplas condições de filtro

• Sintoma: Uma atividade de Consulta do Epicor Prophet 21 falha em tempo de execução quando a String de Filtro contém mais de uma condição de filtro, mesmo que a atividade pareça válida no Studio.
• Possível causa: Uma limitação na API Middleware do Epicor Prophet 21 impede que múltiplas condições de filtro sejam processadas. A operação parece válida no Studio, mas falha em tempo de execução quando mais de um filtro está presente.
• Resolução:
  • Reduza a String de Filtro para uma única condição de filtro.
  • Se múltiplas condições de filtro forem necessárias, recupere um conjunto de resultados mais amplo usando um único filtro e aplique a filtragem adicional em um passo de transformação ou script após a atividade.

Conectores de Arquivo

FTP, Compartilhamento de Arquivo e Armazenamento Local: "Nenhum arquivo corresponde ao filtro de arquivo" em etapas de arquivamento ou acompanhamento

• Sintoma: Uma atividade de leitura de FTP, Compartilhamento de Arquivo ou Armazenamento Local falha porque o arquivo que se espera ler não está mais no caminho de origem:

  Failed to read file from the source "Read". Reason: No files match the file filter "<filter>".
  

  A atividade que processou o arquivo anteriormente teve sucesso; a falha ocorre em uma etapa posterior (geralmente uma etapa de arquivamento ou notificação) que tenta ler o mesmo arquivo com o mesmo filtro.

• Possíveis causas:

  • A atividade de processamento já moveu ou excluiu o arquivo de origem como parte de seu comportamento de Após Processamento, então a etapa de arquivamento não tem nada para corresponder.
  • Uma operação filha é iniciada de forma assíncrona e a operação pai tenta ler o arquivo de saída da filha antes que a filha tenha terminado de escrevê-lo.
  • Uma atividade de Gravação FTP com Usar Renomeação FTP habilitada (o padrão) grava o arquivo sob um nome temporário e o renomeia para o nome final ao concluir. Uma operação de leitura a jusante que é acionada antes que a renomeação seja concluída não encontrará o arquivo.
• Resolução:
  • Confirme se a etapa anterior já tratou o arquivamento por meio de suas opções internas de Após Processamento (mover, renomear, excluir). Se sim, uma etapa de arquivamento separada é redundante e deve ser removida.
  • Se uma etapa de arquivamento separada for necessária, redesenhe a cadeia para que o processamento e o arquivamento ocorram contra a mesma referência de arquivo em memória, em vez de reler da origem. Por exemplo, passe o conteúdo lido através do Armazenamento Temporário para a etapa de arquivamento em vez de reler o caminho de origem.
  • Se uma etapa de acompanhamento ler a saída produzida por uma operação filha, execute a filha de forma síncrona para que sua saída exista antes da leitura. Defina o tipo de Execução da ferramenta Invocar Operação como Síncrono, ou, ao chamar a operação de um script, execute RunOperation de forma síncrona (o padrão). Inserir um atraso fixo (por exemplo, com a função Sleep) adiciona latência e não garante que o arquivo esteja pronto.
  • Se uma atividade de Gravação FTP estiver gravando no mesmo local, verifique se Usar Renomeação FTP está habilitado na atividade de Gravação FTP. Se a leitura a jusante estiver sendo acionada antes que a renomeação seja concluída, desative Usar Renomeação FTP na atividade de gravação ou assegure-se de que a operação de leitura não seja executada até que a operação de gravação tenha sido totalmente concluída.

FTP, Compartilhamento de Arquivos e Armazenamento Local: Pasta de erro não escrita em caso de falha de conexão

• Sintoma: Após uma atividade de FTP, Compartilhamento de Arquivos ou Armazenamento Local falhar, nenhum arquivo aparece na pasta de erro configurada.
• Possível causa: A pasta de erro é projetada para arquivar uma cópia do arquivo de origem após um processamento malsucedido, portanto, captura arquivos apenas quando a atividade é executada e depois falha (por exemplo, um erro de permissão de gravação no servidor). Se a conexão com o servidor não puder ser estabelecida, a operação falha antes que a atividade leia qualquer arquivo, portanto, não há arquivo para escrever na pasta de erro.
• Resolução:
  • Se a pasta de erro estiver vazia após uma falha, verifique os logs de operação em busca de um erro a nível de conexão (como uma falha de autenticação ou mensagem de host inacessível).
  • Use o botão Testar na conexão para confirmar se o problema está a nível de rede ou autenticação.

FTP, Compartilhamento de Arquivos e Armazenamento Local: Palavras-chave de nome de arquivo não resolvidas nos caminhos das pastas de sucesso e erro

• Sintoma: As operações movem arquivos para pastas de sucesso ou erro após o processamento, mas o caminho de destino inclui texto de palavra-chave não expandido em vez de valores resolvidos. A operação pode falhar ou gravar arquivos em locais inesperados.
• Possíveis causas:
  • Os campos de caminho da pasta de sucesso e da pasta de erro nas atividades de FTP, Compartilhamento de Arquivos e Armazenamento Local não suportam substituição de palavras-chave de nome de arquivo. Variáveis não são expandidas nesses campos.
  • Esses campos referem-se a diretórios na máquina do agente privado, não no servidor remoto. Caminhos relativos são interpretados em relação ao sistema de arquivos do host do agente.
• Resolução:
  • Use apenas caminhos literais (sem variáveis de palavras-chave de nome de arquivo) para os campos de pasta de sucesso e erro.
  • Se caminhos dinâmicos forem necessários, adicione um passo de script após a atividade para mover ou renomear o arquivo processado para o local pretendido usando funções de arquivo.

FTP, Compartilhamento de Arquivos, Armazenamento Local e Armazenamento Temporário: Os Cabeçalhos de Escrita não produzem um arquivo apenas com cabeçalho quando a fonte não retorna registros

• Sintoma: Uma atividade de escrita baseada em arquivo com a opção Escrever Cabeçalhos habilitada (Escrita FTP, Escrita em Compartilhamento de Arquivos, Escrita em Armazenamento Local, ou Escrita em Armazenamento Temporário) não escreve cabeçalhos quando a fonte não retorna registros. Um arquivo vazio é criado ou nenhum arquivo é criado (se Não criar arquivos vazios também estiver selecionado).
• Causa: Este é um comportamento esperado. Os cabeçalhos são escritos como parte da saída da transformação, e a transformação é executada apenas quando a fonte retorna pelo menos um registro. Quando a fonte não retorna registros, a transformação é ignorada, portanto, nenhuma saída (incluindo cabeçalhos) é escrita, e o Studio registra um aviso de que a fonte está vazia. Isso não é específico para um conector de fonte particular ou alvo de arquivo plano.

FTP: A operação falha após muitos logins rápidos no mesmo servidor

• Sintoma: Uma operação usando o conector FTP (sobre o protocolo FTP ou SFTP) que autentica no mesmo servidor muitas vezes em rápida sucessão (por exemplo, lendo centenas de pequenos arquivos dentro de um loop, ou muitas operações sendo executadas contra o mesmo servidor em um cronograma) eventualmente falha com uma negação de login ou erro de conexão. A mesma operação é bem-sucedida sob carga mais leve.
• Possíveis causas:
  • O conector FTP abre e autentica uma nova conexão para cada execução de atividade e a fecha quando a operação termina; uma sessão não é reutilizada entre atividades, entre execuções de operação ou entre projetos. Isso é intencional. Quando muitas operações são executadas contra o mesmo servidor, por exemplo, várias operações agendadas ou múltiplos projetos direcionados ao mesmo host, cada execução autentica de forma independente.
  • O servidor remoto está configurado com um número máximo de conexões, autenticações por minuto ou sessões simultâneas por usuário, e a taxa de login combinada do Jitterbit excede esse limite.
• Resolução:
  • Sempre que possível, redesenhe a operação para fazer menos conexões. Substitua uma atividade Ler dentro de um loop por uma única atividade Ler que use um caractere curinga no campo Obter Arquivos (por exemplo, *.xml ou data_*.csv), e depois divida os dados recuperados em registros individuais dentro de uma transformação.
  • Se a operação precisar processar arquivos um por um, peça ao administrador do servidor FTP para aumentar o limite de conexões simultâneas ou autenticações por minuto por usuário.

SFTP "Login negado. Falha na autenticação." ao usar chaves SSH

• Sintoma: Uma operação SFTP usando autenticação por chave privada SSH falha com Login negado. Falha na autenticação., mesmo que as mesmas chaves autentiquem com sucesso a partir de um cliente SFTP interativo.

  Failed to get ftp directory list for url sftp://example.com:22/. Login denied. Authentication failure.
  

• Causas possíveis:

  • A chave privada está protegida por uma frase secreta, mas a configuração PrivateKeyPassphrase está ausente na seção [SSH] do arquivo de configuração do agente jitterbit.conf.
  • Uma senha está configurada no endpoint FTP junto com a chave privada. A presença de uma senha nas configurações do endpoint interfere na autenticação baseada em chave.

• Resolução:

  • Para agentes privados, confirme que a seção [SSH] do jitterbit.conf contém o caminho correto para PrivateKeyFile e, se a chave estiver protegida por frase secreta, o valor correspondente de PrivateKeyPassphrase (veja Conectando ao SFTP com chaves SSH).
  • Na configuração do endpoint FTP, limpe o campo Senha quando a autenticação for por chave SSH.
  • Confirme que a chave está em um formato suportado pelo agente (OpenSSH). Converta a chave com ssh-keygen se estiver no formato PuTTY (.ppk) ou em outro formato que não seja OpenSSH.

FTP Write: "Usar Renomear FTP" falha ao gravar em um servidor SFTP

• Sintoma: Uma atividade FTP Gravar configurada com a opção Usar Renomear FTP falha quando o destino é um servidor SFTP, com um erro semelhante a:

  Failed to put ... to the url ...
  Quote command returned error. Rename command failed: <reason>.
  

  A <razão> é tipicamente Nenhum arquivo ou diretório desse tipo, ou Permissão negada para um arquivo cujo nome contém caracteres multibyte.

• Causas possíveis:

  • Em agentes anteriores à versão 11.56, a opção Usar Renomeação FTP não honrava de forma confiável a etapa de renomeação ao gravar em um servidor SFTP, particularmente em operações de padrão de arquivo.

  • O nome do arquivo contém caracteres multibyte e o servidor SFTP não suporta renomear arquivos cujos nomes os contenham. A partir da versão 12.8 do agente, o conector FTP pode ler e gravar arquivos com nomes multibyte; no entanto, com Usar Renomeação FTP, o agente faz o upload do arquivo sob um nome temporário (um sufixo -jbupload) e depois o renomeia para o nome final, e se o servidor não puder renomear o nome multibyte, ele retorna uma mensagem enganosa de Permissão negada. Nomes de arquivos que usam apenas caracteres ASCII não são afetados. Esta é uma limitação do servidor SFTP, não do Jitterbit.

• Solução:

  • Certifique-se de que o agente esteja na versão 11.56 ou posterior, onde Usar Renomeação FTP com SFTP funciona como esperado. Agentes em nuvem são atualizados automaticamente; atualize agentes privados se necessário.

  • Desmarque a caixa Usar Renomeação FTP na configuração da atividade para que o agente grave diretamente no caminho de destino em vez de fazer o upload para um nome temporário e renomear. Isso evita a etapa de renomeação e resolve ambas as causas.

  • Para o caso multibyte, use alternativamente um servidor SFTP que suporte renomear arquivos cujos nomes contenham caracteres multibyte.

SFTP: Anexar a arquivo não suportado

• Sintoma: Uma atividade FTP Gravar configurada com a opção Anexar ao Arquivo não anexa ao arquivo existente quando o destino é um servidor SFTP.
• Causa possível: O protocolo SFTP não suporta anexar a arquivos existentes. Esta é uma limitação a nível de protocolo, não um problema de configuração do Jitterbit.
• Solução:
  • Use FTP ou FTPS se o comportamento de anexar for necessário.
  • Se o SFTP for necessário, implemente a lógica de anexação manualmente: leia o conteúdo do arquivo existente, combine-o com os novos dados e grave o resultado completo de volta como um arquivo completo.

FTP: Nomes de arquivos contendo # não são tratados corretamente

• Sintoma: Uma atividade de conector FTP (seja pelo protocolo FTP ou SFTP) falha quando o nome do arquivo de origem ou destino contém um caractere hash (#). Ler o arquivo retorna um erro como No File with that name ou Error in SSH Layer, e gravar o arquivo produz um nome de arquivo truncado.
• Possível causa: O conector FTP trata o caminho do arquivo como uma URL, na qual o caractere hash é um delimitador de fragmento reservado. O conector analisa a parte do caminho antes do # e descarta o restante.
• Resolução:
  • Renomeie os arquivos para remover ou substituir o caractere # antes que o Jitterbit os leia ou grave.
  • Para que o conector codifique em URL nomes que contenham caracteres especiais como #, defina jitterbit.source.ftp.encode_url como true em um script de transformação para nomes de arquivos ou pastas de origem, e jitterbit.target.ftp.encode_url como true para arquivos gravados no destino.

Compartilhamento de Arquivos: Caminhos UNC com nomes de servidores falham em agentes na nuvem

• Sintoma: Conexões de Compartilhamento de Arquivos que usam caminhos UNC (por exemplo, \\server\share) falham ao se conectar quando a operação é executada em um agente na nuvem.
• Possível causa: Agentes na nuvem podem resolver caminhos UNC usando um endereço IP público, mas não conseguem resolver nomes de host de servidores em caminhos UNC.
• Resolução:
  • Substitua o nome do servidor no caminho UNC pelo endereço IP público do servidor (por exemplo, \\192.0.2.1\share).
  • Se a resolução de nomes de servidor em caminhos UNC for necessária, use um agente privado em vez disso.

Compartilhamento de Arquivos: Arquivos maiores que 2 GB podem falhar ao serem recuperados

• Sintoma: Uma atividade de Compartilhamento de Arquivos Leitura pode falhar ao recuperar arquivos individuais maiores que 2 GB. Arquivos menores são recuperados sem problemas.
• Causa possível: O conector de Compartilhamento de Arquivos tem uma limitação conhecida com arquivos individuais maiores que 2 GB.
• Resolução: Nenhuma opção de configuração remove esse limite. Como solução alternativa, divida o arquivo em segmentos menores na origem, de modo que cada arquivo esteja abaixo de 2 GB antes que a atividade de Compartilhamento de Arquivos Leitura o recupere.

Armazenamento Local: Não disponível em agentes na nuvem

• Sintoma: Uma operação usando um conector de Armazenamento Local falha quando é executada em um agente na nuvem.
• Causa possível: O Armazenamento Local acessa o sistema de arquivos na máquina onde o agente está instalado. Agentes na nuvem são executados em um ambiente hospedado e não expõem um sistema de arquivos local para esse propósito.
• Resolução:
  • Use agentes privados para quaisquer operações que exijam o conector de Armazenamento Local. O Armazenamento Local está desativado em agentes privados por padrão, então também ative-o no arquivo de configuração do agente privado (veja Ativar localização de arquivo local).
  • Para fluxos de trabalho de agentes na nuvem, substitua o Armazenamento Local por Armazenamento Temporário ou um conector de armazenamento externo (Compartilhamento de Arquivos, FTP ou Cloud Datastore).

Armazenamento Temporário: Arquivos ausentes quando lidos por uma operação posterior

• Sintoma: Arquivos de Armazenamento Temporário gravados por uma operação estão faltando quando uma operação posterior tenta lê-los.
• Causas possíveis:
  • O serviço de limpeza do Harmony exclui arquivos do Armazenamento Temporário após 24 horas por padrão.
  • Cada agente em um grupo de agentes possui seu próprio Armazenamento Temporário local. Operações na mesma cadeia de operações têm a garantia de serem executadas no mesmo agente, mas uma operação posterior que não está na mesma cadeia pode ser enviada a um agente diferente e acessar uma instância diferente de Armazenamento Temporário, portanto, não encontra o arquivo, independentemente da janela de 24 horas. Veja Notas importantes.
• Resolução:
  • Vincule operações que precisam compartilhar arquivos de Armazenamento Temporário na mesma cadeia de operações usando ações de operação, onde o comportamento do Armazenamento Temporário é consistente e confiável.
  • Para agentes privados, a frequência de limpeza pode ser ajustada na seção [FileCleanup] do jitterbit.conf. Veja [FileCleanup].
  • Se os arquivos não puderem ser consumidos dentro da mesma cadeia ou precisarem persistir por mais de 24 horas, use um conector de armazenamento persistente acessível a todos os agentes (como Compartilhamento de Arquivos, FTP ou Cloud Datastore) em vez de Armazenamento Temporário.

Armazenamento Temporário: Caracteres restritos em caminhos de arquivos

• Sintoma: Uma atividade de Leitura ou Gravação no Armazenamento Temporário falha quando o caminho do arquivo contém certos caracteres especiais.
• Causa possível: Os seguintes caracteres não são suportados em caminhos de arquivos do Armazenamento Temporário: ~, %, $, ", <, >, :, ?
• Resolução:
  • Remova ou substitua os caracteres não suportados no caminho do arquivo. Os seguintes caracteres são suportados: !, @, #, ^, &, *, (, ), [, ], ', ;
  • Tanto / quanto \ são aceitos como separadores de caminho.

Armazenamento Temporário: limite de tamanho de arquivo de 50 GB em agentes de nuvem

• Sintoma: Uma atividade de Armazenamento Temporário Gravar falha ao gravar arquivos grandes através de um agente de nuvem.
• Causa possível: Agentes de nuvem impõem um tamanho máximo de arquivo de 50 GB por arquivo para Armazenamento Temporário.
• Resolução:
  • Use um agente privado para fluxos de trabalho que precisam gravar arquivos individuais maiores que 50 GB no Armazenamento Temporário.
  • Se apenas agentes de nuvem estiverem disponíveis, divida grandes conjuntos de dados em vários arquivos menores que 50 GB antes de gravar no Armazenamento Temporário.

Conector HTTP

HTTP v2: Cabeçalho de Autorização duplicado causa 400 Bad Request

• Sintoma: Operações do conector HTTP v2 falham com um erro 400 quando tanto a autenticação em nível de conexão quanto um cabeçalho de solicitação Authorization definido manualmente estão configurados na mesma conexão ou atividade.
• Causa possível: Quando a autenticação é configurada em uma conexão HTTP v2 (por exemplo, Basic ou OAuth), o conector adiciona automaticamente um cabeçalho Authorization a cada solicitação. Adicionar um segundo cabeçalho Authorization manualmente resulta em dois cabeçalhos conflitantes, que a maioria dos servidores rejeita com um erro 400.
• Resolução:
  • Remova qualquer cabeçalho Authorization adicionado manualmente dos cabeçalhos de solicitação na configuração da atividade ou conexão.
  • Use apenas as configurações de autenticação integradas na conexão para lidar com a autorização. Não adicione um cabeçalho Authorization manual juntamente com a autenticação configurada.
  • Se precisar definir o cabeçalho Authorization dinamicamente no nível da atividade, defina o tipo de autenticação da conexão como Sem Autenticação e configure o cabeçalho de solicitação Authorization da atividade conforme necessário.

HTTP v2: Valor JSON em uma variável de cabeçalho de solicitação não consegue ser analisado

• Sintoma: Uma atividade HTTP v2 que lê um valor de cabeçalho de solicitação de uma variável de projeto contendo uma string JSON falha com um erro de análise:

  Expected a ',' or ']' at 139 [character 140 line 1]
  

  O mesmo JSON funciona quando colado diretamente na coluna Valor da tabela Cabeçalhos de Solicitação.

• Possível causa: Quando um valor de cabeçalho de solicitação é lido de uma variável de projeto, o conector HTTP v2 não escapa as aspas embutidas da mesma forma que faz quando você digita o valor diretamente na tabela Cabeçalhos de Solicitação. As aspas não escapadas quebram a string do cabeçalho antes de chegar ao destino.

• Resolução:
  • Ao armazenar JSON em uma variável de projeto que será usada como um valor de cabeçalho, escape cada aspas dupla com uma barra invertida. Por exemplo, armazene o valor como {\"success\": \"true\"} em vez de {"success": "true"}.
  • Se o conteúdo JSON for estático, cole-o diretamente na coluna Valor da tabela Cabeçalhos de Solicitação em vez de usar uma variável. O conector aplica o escape necessário nesse caminho.

HTTP e HTTP v2: URL contém múltiplos caracteres ?

• Sintoma: Uma operação HTTP ou HTTP v2 falha no sistema de destino. Os logs do agente mostram que a URL da solicitação contém mais de um ? entre os segmentos, por exemplo https://api.example.com/endpoint?param1=A?param2=B.
• Possível causa: Parâmetros de consulta foram declarados em dois lugares: anexados diretamente ao caminho da URL e também adicionados à tabela Parâmetros de Solicitação da atividade. O conector concatena ambos os conjuntos, inserindo um segundo ? em vez de um &.
• Resolução:
  • Remova qualquer segmento de string de consulta do caminho da URL. A URL base deve conter apenas o caminho em si (por exemplo, https://api.example.com/endpoint).
  • Defina cada parâmetro de consulta na tabela Parâmetros de Solicitação da atividade. O conector insere os caracteres ? e & automaticamente ao construir a URL final.

HTTP v2: Codificação dupla de URL quando "Codificar URL da solicitação" está habilitado

• Sintoma: Chamadas à API REST feitas através do conector HTTP v2 falham no sistema de destino porque os parâmetros da URL aparecem codificados duas vezes na solicitação de saída (por exemplo, um espaço %20 se torna %2520).
• Possível causa: Quando Codificar URL da solicitação está habilitado nas configurações de conexão HTTP v2, o conector codifica toda a URL antes de enviá-la. Se os parâmetros da URL já contêm caracteres codificados em porcentagem, esses caracteres são codificados uma segunda vez.
• Resolução:
  • Desabilite Codificar URL da solicitação nas configurações de conexão HTTP v2 quando a URL ou os parâmetros já estiverem codificados ou construídos usando a função URLEncode.
  • Se Codificar URL da solicitação precisar permanecer habilitado, assegure-se de que os parâmetros passados para a URL não estejam pré-codificados antes de chegarem à conexão.

HTTP v2: A operação falha quando a URL base redireciona

• Sintoma: Uma operação HTTP v2 falha imediatamente quando a URL base configurada retorna uma resposta de redirecionamento (3xx).
• Possível causa: Seguir redirecionamentos está desabilitado nas configurações de conexão HTTP v2, então as respostas de redirecionamento são tratadas como falhas em vez de serem seguidas automaticamente.
• Resolução: Nas configurações de conexão HTTP v2, habilite Seguir redirecionamentos para permitir que o conector siga automaticamente as respostas de redirecionamento até a URL final de destino.

HTTP v2: Variáveis no caminho da atividade não são resolvidas

• Sintoma: Uma atividade HTTP v2 utiliza uma variável global, de projeto ou Jitterbit no campo Caminho, mas em tempo de execução a variável é enviada literalmente (não resolvida) em vez de ser substituída pelo seu valor.
• Causa possível: Uma URL completa (uma que inclui o protocolo e o host, como https://api.example.com/...) foi inserida no campo Caminho. Variáveis não são suportadas em URLs completas. Elas são resolvidas apenas em um caminho parcial que é anexado à Base URL da conexão.
• Resolução:
  1. Na conexão HTTP v2, defina a Base URL para a parte do protocolo e do host do endpoint (por exemplo, https://api.example.com).
  2. No campo Caminho da atividade, insira apenas o caminho parcial que segue a base URL e coloque a variável dentro desse caminho parcial (por exemplo, /records/[recordId]). O conector resolve a variável e anexa o resultado à Base URL em tempo de execução.

HTTP v2: Código de status da resposta não disponível em variáveis Jitterbit

• Sintoma: Scripts que leem variáveis de origem ou destino Jitterbit para capturar o código de status da resposta HTTP após a execução de uma atividade HTTP v2 não recebem valor. A mesma abordagem funciona com o conector HTTP, mas não com HTTP v2.
• Causa possível: O conector HTTP v2 não preenche as variáveis Jitterbit de origem ou de destino. Os dados da resposta, incluindo o código de status HTTP, são retornados através do esquema de resposta da atividade.
• Resolução:
  • Para capturar o código de status usando o esquema de resposta padrão, mapeie o campo statusCode, que está localizado sob o nó responseItem/error da resposta e contém o código de status HTTP (por exemplo, 200, 403). Para detalhes sobre a estrutura do esquema de resposta, consulte a documentação de configuração da atividade para qualquer atividade HTTP v2.
  • Para capturar o código de status ao usar um esquema de resposta personalizado, ative Incluir Propriedades Adicionais da Resposta HTTP no Esquema na configuração da atividade. Isso envolve o esquema com uma estrutura definida pelo Jitterbit que inclui __jitterbit_api_statuscode__ (o código de status) e __jitterbit_api_errorbody__ (o corpo da resposta para solicitações malsucedidas).
  • Para que o código de status esteja disponível quando a API retornar uma resposta não bem-sucedida, ative Ignorar erro de operação em caso de código de status não bem-sucedido nas configurações opcionais da atividade. Sem essa configuração, a operação falha em respostas não bem-sucedidas antes que os dados da resposta possam ser mapeados.

HTTP v2: namespaces XML reescritos ao usar um esquema de solicitação personalizado

• Sintoma: Uma operação HTTP v2 que envia um payload XML para um serviço web SOAP ou XML falha com um erro de servidor (como 500 Internal Server Error), mesmo que o mesmo payload seja bem-sucedido quando enviado do Postman ou SoapUI. Inspecionando o corpo da solicitação recebido pelo destino, observa-se que as declarações de namespace XML foram consolidadas no elemento raiz e os prefixos de namespace originais foram substituídos por genéricos (por exemplo, soapenv:Envelope se torna Envelope xmlns="...", e os prefixos de elementos são renumerados como ns, ns1, ns2).
• Causa possível: Quando um esquema de solicitação personalizado é usado na configuração da atividade HTTP v2, a transformação normaliza o XML por padrão, movendo todas as declarações de namespace para o nó raiz e reatribuindo seus prefixos. Serviços SOAP e outros endpoints XML que validam a consistência dos prefixos de namespace rejeitam o payload modificado.

• Resolução:

  • Na versão do agente 12.8 ou posterior, defina jitterbit.target.xml.preserve.namespace.prefix como true em um passo de script antes da transformação, para manter os prefixos de namespace do XML de origem em vez de reatribuir genéricos:

    $jitterbit.target.xml.preserve.namespace.prefix = true;
    

  • Se seus agentes privados forem anteriores a 12.8, ou se o destino também rejeitar a consolidação das declarações de namespace no elemento raiz, use o esquema de solicitação padrão em vez de um personalizado e mapeie o payload XML completo como uma string no campo body do esquema. O payload é então tratado como uma string em vez de XML analisado, portanto, suas declarações de namespace são preservadas. O esquema de resposta ainda pode ser um esquema personalizado.

HTTP v2: Espaços codificados como + em vez de %20

• Sintoma: Chamadas da API REST usando o conector HTTP v2 falham no sistema de destino porque os espaços na URL são codificados como + em vez de %20, fazendo com que o destino retorne um erro de recurso não encontrado.
• Resolução:
  • Na conexão HTTP v2, ative a opção Codificar URL da solicitação. O conector então codifica a URL da solicitação, codificando os espaços como %20.
  • Forneça a URL da solicitação completamente não codificada. Não codifique caracteres previamente ou aplique a função URLEncode à URL, porque caracteres já codificados se tornam duplamente codificados quando Codificar URL da solicitação está ativado (por exemplo, example+string%20value se torna example%20string%2520value).

HTTP: Envia null como a string "null"

• Sintoma: Uma atividade HTTP POST ou PUT envia campos mapeados com a função Null como a string "null" (ou os omite) em vez de emitir um literal JSON null. Isso ocorre quando o esquema da solicitação é definido na atividade.
• Causa possível: Quando o esquema da solicitação é definido na atividade HTTP, o conector não serializa um Null mapeado como um JSON null. Quando o esquema é definido na transformação em vez disso, sem um esquema de solicitação fornecido na atividade, o conector envia um Null mapeado como um JSON null corretamente.
• Resolução:
  • Migre a atividade para o conector HTTP v2, que serializa Null corretamente. A Jitterbit recomenda converter conexões e atividades HTTP existentes para HTTP v2.
  • Se a atividade precisar permanecer no HTTP, defina o esquema da solicitação na transformação em vez de na atividade, e deixe o esquema da solicitação da atividade não definido. Com o esquema definido na transformação, o conector serializa um Null mapeado para um JSON null corretamente.

Conector LDAP

A exclusão de entrada LDAP falha quando a entrada alvo possui entradas filhas

• Sintoma: Uma atividade de Excluir Entrada LDAP falha com um erro do servidor LDAP (por exemplo, notAllowedOnNonLeaf ou uma mensagem indicando que a entrada não é um nó folha).
• Possível causa: O protocolo LDAP não permite a exclusão de uma entrada que possui entradas filhas (subordinadas). A entrada deve ser um nó folha sem filhos para que a exclusão seja bem-sucedida.
• Resolução:
  • Antes de excluir a entrada pai, exclua todas as entradas filhas primeiro. Percorra a hierarquia das entradas mais profundas para as superiores.
  • Se for necessário excluir toda uma subárvore, implemente um script que identifique e exclua entradas de baixo para cima, usando RunOperation com a atividade LDAP Excluir Entrada para cada entrada.

Entrada de Pesquisa LDAP: A expressão de filtro é sensível a maiúsculas em alguns servidores

• Sintoma: Uma atividade de Pesquisar Entrada LDAP não retorna resultados ou gera um erro, mesmo que as entradas consultadas existam no diretório.
• Possível causa: Alguns servidores LDAP exigem que os nomes dos atributos nas expressões de filtro correspondam exatamente ao caso usado pelo esquema desse servidor. A expressão de filtro pré-preenchida pelo Studio usa maiúsculas e minúsculas para a classe estrutural (por exemplo, ObjectClass), mas alguns servidores exigem um caso diferente (por exemplo, objectClass).
• Resolução:
  1. Na configuração da atividade LDAP Pesquisar Entrada, revise o campo Expressão de Filtro pré-preenchido.
  2. Ajuste o caso dos nomes dos atributos para corresponder ao que o servidor LDAP de destino espera. Por exemplo, mude ObjectClass para objectClass se o servidor exigir letras minúsculas.
  3. Consulte a documentação do seu servidor LDAP ou a definição do esquema para as convenções de nomenclatura de atributos exigidas.

Conectores Microsoft

Microsoft SharePoint Online: conexões do esquema SOAP falhando após a aposentadoria do IDCRL

• Sintoma: Operações usando um conector do Microsoft SharePoint Server com o tipo de conexão SOAP começaram a falhar ou retornar erros de autenticação ao se conectar ao SharePoint Online.
• Possível causa: A Microsoft aposentou o método IDCRL (Identity Client Runtime Library) usado por conexões do esquema SOAP para o SharePoint Online. Após 1º de maio de 2026, espera-se que operações usando o esquema SOAP do SharePoint para conexões com o SharePoint Online falhem.
• Resolução:
  1. No Studio, abra cada conexão do SharePoint afetada e altere a configuração de Esquema de SOAP para REST.
  2. Reconfigure quaisquer atividades que usaram o esquema SOAP para usar operações REST equivalentes.
  3. Teste e reimplante as operações afetadas.
  4. Para detalhes sobre migração, consulte a documentação do conector do Microsoft SharePoint Server.

Microsoft Dynamics 365 Business Central v2: Nomes de tipos incompatíveis com os metadados

• Sintoma: Operações usando o conector Microsoft Dynamics 365 Business Central v2 falham com erros indicando que os nomes de tipos na carga útil são incompatíveis com os metadados OData.
• Possível causa: Certos endpoints da API OData do Dynamics 365 Business Central exigem anotações de tipo OData na carga útil da solicitação. Por padrão, o conector não inclui essas anotações, o que causa erros de incompatibilidade de tipo para esses endpoints.
• Resolução:
  1. Abra a configuração da atividade Atualizar do Microsoft Dynamics 365 Business Central v2.
  2. Em Configurações opcionais, ative Definir tipo OData na carga útil.
  3. Salve a atividade e reteste as operações afetadas.

Microsoft Entra ID: Atributos de extensão não selecionáveis como condições de filtro de consulta

• Sintoma: Ao configurar uma atividade de Microsoft Entra ID Consulta, o campo onPremisesExtensionAttributes e seus campos de atributo de extensão filho (por exemplo, extensionAttribute1 até extensionAttribute15) não aparecem no seletor de Campos de Objeto na etapa 3 e não podem ser selecionados como condições de cláusula condicional.
• Possível causa: onPremisesExtensionAttributes é um objeto de tipo complexo (aninhado). O seletor de Campos de Objeto da etapa 3 expõe apenas campos de tipo de dado primitivo; campos de tipo complexo são excluídos da lista de seleção.
• Resolução: Os campos onPremisesExtensionAttributes não precisam ser selecionados na etapa 3 para serem retornados. Eles aparecem no esquema de saída da atividade na etapa 4 e são preenchidos em tempo de execução quando a operação é executada. Para acessar os valores dos atributos de extensão, mapeie a partir de onPremisesExtensionAttributes e seus campos filhos na transformação.

Atividade de atualização do Microsoft Entra ID: Campos DateTime rejeitados com incompatibilidade de tipo Edm.String

• Sintoma: Uma atividade de Microsoft Entra ID Atualização falha com:

  A value was encountered that has a type name that is incompatible with the metadata.
  The value specified its type as 'Edm.String', but the type specified in the metadata is 'Edm.DateTimeOffset'.
  [HTTP/1.1 400 Bad Request]
  

• Possível causa: O conector envia valores de campo DateTime (como employeeHireDate) sem a anotação @odata.type exigida pela API do Microsoft Graph. Sem a anotação, o valor é interpretado como Edm.String em vez de Edm.DateTimeOffset, causando um erro 400.

• Resolução:
  1. Abra a configuração da atividade Atualização do Microsoft Entra ID.
  2. Na etapa 1, expanda Configurações Opcionais e habilite Definir tipo OData na carga útil.
  3. Salve a atividade, redeploy e execute novamente a operação.

Consulta do Microsoft Entra ID: "Cláusula de filtro de consulta não suportada ou inválida" em propriedades filtradas

• Sintoma: Uma atividade de Consulta do Microsoft Entra ID falha quando uma condição de filtro é aplicada na etapa 3:

  (Request_UnsupportedQuery) Unsupported or invalid query filter clause specified for property '<property>' of resource '<object>'. [HTTP/1.1 400 Bad Request]
  

  A mesma consulta é bem-sucedida quando nenhum filtro é aplicado.

• Causa possível: Filtrar em certas propriedades do Microsoft Entra ID (como companyName e createdDateTime) utiliza a capacidade de consulta avançada da API Microsoft Graph, que requer $count=true na string da consulta. Sem isso, a API rejeita o filtro, mesmo quando a sintaxe está correta. O conector inclui automaticamente o cabeçalho ConsistencyLevel: eventual necessário, mas $count=true deve ser adicionado separadamente.

• Resolução: Escolha uma das seguintes opções dependendo da aba utilizada na etapa 3:
  • Aba Básica: Selecione a caixa de seleção Incluir Contagem. Isso adiciona $count=true à consulta automaticamente.

  • Aba Avançada: Anexe &$count=true à string do filtro manualmente. Por exemplo:

    $filter=companyName eq 'Example Corp'&$count=true
    

Para a lista de propriedades que requerem sintaxe de consulta avançada, consulte Capacidades de consulta avançada em objetos do Microsoft Entra ID na documentação do Microsoft Graph.

Operações do Microsoft Dynamics AX 2012 falham com "Falha no logon"

• Sintoma: Operações usando o conector Microsoft Dynamics AX contra o AX 2012 falham em tempo de execução, embora o teste de conexão passe no Studio. O log do Serviço REST do Conector Jitterbit Dynamics AX 2012 contém:

  The server has rejected the client credentials.
  

  The logon attempt failed
  

• Causa: O campo Nome do Domínio na conexão do AX 2012 não está definido com o valor correto. A autenticação do AX 2012 requer que o Nome do Domínio seja a extensão do nome de domínio DNS (por exemplo, suaempresa.com), e não um nome de domínio curto ou NetBIOS. Um valor de domínio incorreto faz com que o AX rejeite credenciais válidas com uma falha de login, mesmo quando o teste de conexão é bem-sucedido.

• Resolução:
  1. Abra a conexão do Dynamics AX 2012 no Studio.
  2. Defina o campo Nome do Domínio para a extensão do nome de domínio DNS (por exemplo, suaempresa.com), e não um nome de domínio curto/NetBIOS.
  3. Confirme que o Login é o nome de usuário da conta de serviço do AX com os privilégios necessários e reintroduza a Senha para descartar um valor desatualizado.
  4. Teste a conexão e, em seguida, execute novamente a operação.

Conector NetSuite

Criação, Atualização ou Upsert do NetSuite falha com "não é um valor legal para o País"

• Sintoma: Uma atividade Criar, Atualizar ou Upsert do NetSuite falha quando o valor de origem para um campo de país não corresponde a um valor de enumeração Country do NetSuite:

  FaultString: org.xml.sax.SAXException: <country_value> is not a legal value for {urn:types.common_<version>.platform.webservices.netsuite.com}Country
  

• Causa possível: A API SuiteTalk do NetSuite requer que Country (e outros campos enumerados) sejam um dos valores de enumeração predefinidos do WSDL (por exemplo, _unitedStates). Um nome de exibição de país, um código de país ISO ou qualquer valor que não corresponda exatamente à enumeração do WSDL é rejeitado.

• Resolução:
  • Na transformação que mapeia para o destino do NetSuite, traduza o valor de origem do país para o valor de enumeração correspondente do NetSuite antes de gravar. Um dicionário de referência cruzada, uma declaração Case ou uma tabela de consulta funcionam para isso.
  • Construa a referência cruzada a partir da enumeração Country definida no WSDL do SuiteTalk do NetSuite que seu conector está usando. Os valores válidos mudam entre as versões do WSDL, então sempre verifique contra a versão do WSDL atualmente configurada na conexão.
  • Aplique a mesma abordagem a qualquer outro campo respaldado por uma enumeração do NetSuite (por exemplo, State, Currency) onde os valores de origem já não correspondem à enumeração do WSDL.

Conector OData

Conjuntos de entidades OData v2 falham ao carregar com "Nenhum conjunto de entidades encontrado"

• Sintoma: Configurar uma atividade de Consulta OData que aponta para um serviço OData v2.0 retorna um erro ao buscar a lista de objetos, mesmo que o teste de conexão seja bem-sucedido:

  An error occurred while fetching the data:
  Error while generating for query activity object list. The Exception is No entity sets found for the address provided.
  

• Possível causa: O suporte para serviços OData V2 foi adicionado ao conector OData na versão 11.59 do agente, através da configuração de conexão Versão do OData. Em agentes anteriores à versão 11.59, o conector suporta apenas OData V4, portanto, uma conexão apontando para um serviço OData V2 não pode preencher a lista de objetos. A mesma falha ocorre na versão 11.59 ou posterior se a Versão do OData for deixada como V4 para um serviço OData V2.

• Resolução:
  1. Para agentes privados, atualize para a versão 11.59 ou posterior. Agentes em nuvem recebem a atualização automaticamente.
  2. Na conexão OData, defina a Versão do OData como V2 (o padrão é V4). Salve e reteste a conexão.
  3. Reabra a atividade de Consulta OData. Os conjuntos de entidades devem agora carregar.

OData: Microsoft Dynamics 365 retorna apenas os dados da empresa padrão

• Sintoma: Uma conexão OData para um endpoint do Microsoft Dynamics 365 Finance and Operations retorna dados apenas para a empresa padrão do usuário, portanto, registros de outras empresas estão ausentes dos resultados.
• Possível causa: Por padrão, um endpoint OData do Dynamics 365 Finance and Operations retorna apenas os dados que pertencem à empresa padrão do usuário. Para dar à conexão um escopo interempresarial (expandido), uma cláusula de filtro interempresarial deve ser anexada à URL de metadados OData da conexão (a URL $metadata). Na URL de metadados, ?cross-company=true por si só não aplica o escopo expandido.

• Resolução: Na conexão OData, anexe uma cláusula de filtro dataAreaId à URL de metadados OData, substituindo usrt pelo seu identificador de área de dados, e então salve e reteste:

  ?$filter=dataAreaId eq 'usrt'&cross-company=true
  

Para obter informações sobre como o Dynamics 365 delimita dados OData por empresa, consulte a documentação da Microsoft sobre comportamento entre empresas.

Conectores Oracle

Oracle EBS: erro de conexão "arquivo JAR do provedor personalizado não está presente"

• Sintoma: A conexão com uma instância do Oracle E-Business Suite (EBS) falha com:

  Error connecting to Oracle EBS instance. Error is: The custom provider JAR file is not present in the Jitterbit Private Agent or it is not in the right location ($JITTERBIT_HOME/Connectors/Providers)
  

• Causa possível: O conector Oracle EBS requer que o driver JDBC do Oracle (ojdbc8.jar) seja colocado manualmente no agente privado. Este arquivo não está incluído com o agente e deve ser adicionado antes que a conexão possa ser bem-sucedida.

• Solução:
  1. Baixe ojdbc8.jar do site da Oracle (uma conta da Oracle é necessária).
  2. Coloque ojdbc8.jar no diretório $JITTERBIT_HOME/Connectors/Providers/ no host do agente privado.
  3. Reinicie todos os agentes no grupo de agentes.
  4. Teste novamente a conexão do Oracle EBS.

Conectores Salesforce

Eventos do Salesforce: eventos não podem ser ativados após a reinicialização do agente

• Sintoma: Após a reinicialização ou reinstalação de um agente privado, os eventos do conector Salesforce Events falham ao serem ativados, mesmo quando as credenciais de conexão estão corretas.
• Causa possível: Após uma reinicialização, o arquivo JAR do conector pode ainda não estar presente no agente. Ativar um evento requer que o conector seja baixado para o agente primeiro.
• Solução:
  1. Abra a configuração de conexão do Salesforce Events no Studio.
  2. Clique em Testar para testar a conexão. Isso força o download do JAR do conector para o agente.
  3. Após o teste de conexão ser bem-sucedido, tente ativar o evento novamente.

Salesforce Events: Limitações de atividades de escuta

Os seguintes comportamentos das atividades de escuta de Salesforce Events (Subscribe Event e as atividades de CDC Event Subscribe Insert, Update e Delete) são esperados e não indicam um defeito no conector:

• Eventos não podem ser habilitados porque o número máximo de assinantes foi atingido. A instância do Salesforce limita o número de clientes (assinantes) concorrentes. Quando esse limite é atingido, nenhum evento adicional pode ser habilitado. Reduza o número de assinantes ativos conectados à instância.
• Símbolos de medição como $ e % estão ausentes da resposta. Esses símbolos não são retornados, por design da API do Salesforce.
• Campos não modificados são retornados como nulos nas respostas de Change Data Capture (CDC). Para atividades de CDC, apenas os campos alterados são preenchidos; campos não modificados são retornados como nulos, por design da API do Salesforce.

Conector SAP

Múltiplas atividades SAP em uma operação falham em tempo de execução

• Sintoma: Uma operação que contém mais de uma atividade SAP, ou que combina uma atividade SAP com uma atividade NetSuite, Salesforce, Salesforce Service Cloud, ServiceMax ou SOAP, é implantada sem nenhum erro de validação, mas falha ao ser executada.
• Possível causa: Operações que misturam esses tipos de atividades parecem válidas no Studio e podem ser implantadas com sucesso, mas essas combinações não são suportadas em tempo de execução. As regras de validação da operação não sinalizam esse padrão como um erro no tempo de design. Este é um problema conhecido do Studio documentado.
• Resolução:
  • Projete cada operação para conter apenas uma única atividade SAP, sem outras atividades SAP, NetSuite, Salesforce, Salesforce Service Cloud, ServiceMax ou SOAP na mesma operação.
  • Se dados de múltiplos sistemas forem necessários em um único fluxo de trabalho, divida a lógica em operações separadas e encadeie-as usando ações de operação.

SAP RFC: "Sem autorização RFC para o módulo de função BAPI_TRANSACTION_COMMIT"

• Sintoma: Uma atividade RFC do SAP falha em tempo de execução com:

  JCoException occurred No RFC authorization for function module BAPI_TRANSACTION_COMMIT
  

• Causas possíveis:

  • A conta de usuário SAP na conexão não possui autorização S_RFC para BAPI_TRANSACTION_COMMIT ou seus grupos de função relacionados.
  • O módulo de função BAPI_TRANSACTION_COMMIT não está configurado como habilitado para remoto no sistema SAP.
  • A transformação de solicitação que precede a atividade não define o campo de controle de commit.

• Resolução:

  • No sistema SAP, confirme que o módulo de função BAPI_TRANSACTION_COMMIT está habilitado para remoto.
  • Na transformação de solicitação que precede a atividade RFC do SAP, defina o campo BAPI_COMMIT como true.
  • Verifique se a conta de usuário SAP referenciada na conexão possui autorização S_RFC para BAPI_TRANSACTION_COMMIT e todos os grupos de função relacionados.
  • Se o problema persistir, entre em contato com o administrador SAP BASIS para revisar as atribuições de objetos de autorização do usuário.

A conexão SAP falha com "Chave de idioma inválida"

• Sintoma: Uma conexão SAP falha durante a inicialização com um erro sobre a chave de idioma:

  Connector Error: AdapterResourceException: Error while creating Destination. 00024Invalid language key when configuring the text environment.
  

• Causa possível: O código de Idioma configurado no endpoint SAP não é válido para o sistema SAP de destino: o código não está instalado ou suportado nesse sistema, ou está digitado incorretamente ou com letras maiúsculas/minúsculas erradas (por exemplo, en em vez de EN). O SAP rejeita a chave inválida ao inicializar o ambiente de texto do destino.

• Resolução:
  1. Edite o endpoint SAP no Studio e defina o campo Idioma para um código de idioma de duas letras suportado (por exemplo, EN para inglês).
  2. Verifique se o valor corresponde a um idioma instalado e ativo no sistema SAP de destino. Se não tiver certeza, confirme o idioma padrão do usuário de integração no perfil do usuário SAP e use esse.
  3. Teste a conexão do Studio para confirmar que a inicialização é bem-sucedida antes de redistribuir a operação.

Conector ServiceNow

As execuções iniciais de operação são lentas após a reinicialização do agente ou em agentes na nuvem

• Sintoma: Operações usando o conector ServiceNow são lentas em dois cenários:

  • Em agentes privados, a primeira operação após a reinicialização do agente pode levar vários minutos; execuções subsequentes são rápidas.
  • Em agentes na nuvem, as execuções são intermitentemente lentas, levando minutos sempre que o cache de metadados do conector é atualizado.

  Isso pode causar timeouts de API a montante.

• Causa possível: O conector armazena em cache os metadados do ServiceNow de forma agressiva. Após uma reinicialização do agente em um agente privado (ou em cada execução para um agente na nuvem que não preservou o cache), a primeira operação deve reconstruir o cache, o que leva vários minutos.

• Solução:
  • Em um agente privado, mitigue a lentidão pós-reinicialização adicionando getcolumnsmetadata=onUse às Opções Avançadas do endpoint do ServiceNow. Essa configuração é eficaz apenas em agentes privados.
  • Para desempenho consistente em agentes na nuvem, chame a API REST do ServiceNow através do conector HTTP v2 em vez de usar o conector do ServiceNow. O conector HTTP v2 não armazena em cache os metadados e evita o atraso de reconstrução.

Conector Shopify

Shopify: Seleções de objetos de atividade podem mudar após atualização da versão da API

• Sintoma: Após mudar a versão da API em uma conexão Shopify, uma ou mais atividades do Shopify retornam erros ou se comportam de maneira inesperada, e um objeto ou sub-objeto configurado parece ter mudado.
• Causa possível: O Shopify lança novas versões da API trimestralmente e descontinua versões mais antigas após 12 meses. Quando você muda para uma versão diferente da API, objetos ou sub-objetos que não estão disponíveis na nova versão podem não ser mais selecionáveis, fazendo com que a seleção configurada da atividade mude quando a configuração é atualizada.
• Solução:
  1. Após mudar a versão da API do Shopify na conexão, abra a configuração de cada atividade do Shopify afetada.
  2. Clique em Atualizar para recarregar os objetos disponíveis para a nova versão da API.
  3. Revise as seleções de objetos e sub-objetos para confirmar que refletem sua intenção na nova versão.
  4. Atualize quaisquer seleções que mudaram para os objetos de substituição corretos.
  5. Reimplante e reteste as operações afetadas.
  6. Para informações sobre os cronogramas de descontinuação da versão da API do Shopify, consulte o registro de alterações do Shopify.

Conector Snowflake

Snowflake: Conexões baseadas em senha falhando após a descontinuação da autenticação

• Sintoma: Operações conectando ao Snowflake usando o tipo de autenticação Senha (Descontinuada) começaram a falhar após funcionarem anteriormente.
• Possível causa: O Snowflake está descontinuando a autenticação de fator único (apenas senha). Conexões baseadas em senha falham a menos que a propriedade TYPE da conta de usuário do Snowflake esteja definida como LEGACY_SERVICE.

• Resolução: Escolha uma das seguintes opções:

  • Solução temporária: No Snowflake, defina a propriedade TYPE da conta de usuário como LEGACY_SERVICE para restaurar a conectividade baseada em senha:

    ALTER USER <username> SET TYPE = LEGACY_SERVICE;
    

    Esta solução temporária não é uma solução de longo prazo, pois o Snowflake pode remover o suporte para LEGACY_SERVICE em uma versão futura.

  • Migração recomendada: Atualize a conexão do conector Snowflake no Studio para usar autenticação OAuth ou Key-Pair, e configure a conta de usuário do Snowflake para corresponder.

Snowflake: Instância de desenvolvedor está em modo de espera, tabelas de metadados não estão sendo populadas

• Sintoma: Ao configurar uma atividade Snowflake, a lista de objetos disponíveis não é populada ou aparece vazia, mesmo que o teste de conexão seja bem-sucedido.
• Possível causa: Instâncias de desenvolvedor do Snowflake entram em estado de espera quando não foram acessadas recentemente. Embora o teste de conexão possa ser bem-sucedido contra uma instância em espera, a instância pode não retornar metadados de tabelas e objetos.
• Resolução:
  1. Faça login na interface web do Snowflake para ativar a instância.
  2. Reabra a conexão do Snowflake no Studio e clique em Testar para retestar as credenciais.
  3. Reabra a configuração da atividade para atualizar a lista de objetos disponíveis.

Snowflake Query: a diferença de maiúsculas e minúsculas no nó raiz do esquema plano causa erro ProcessFlatStream

• Sintoma: Uma atividade Query do Snowflake usando um esquema plano falha em tempo de execução com:

  StartElement() error, starting element does not match with the root.
  qName= "<table_name_lowercase>", root name="<TABLE_NAME_UPPERCASE>"
  
  ProcessFlatStream error
  

  Este erro ocorre quando a consulta inclui uma cláusula WHERE, uma cláusula LIMIT ou uma referência de variável em uma cláusula WHERE.

• Possível causa: O conector Snowflake retorna o nome da tabela em letras minúsculas na resposta XML. Quando o Studio gera um esquema plano a partir da consulta, o nome do nó raiz é criado em letras maiúsculas. A diferença de maiúsculas e minúsculas entre o nó raiz do esquema (maiúsculas) e o nó raiz da resposta XML (minúsculas) causa a falha no processamento do fluxo plano.

• Resolução: Escolha uma das seguintes opções:
  • No esquema plano, altere o nome do nó raiz para letras minúsculas para corresponder à saída do conector. Por exemplo, renomeie SALES_ORDERS para sales_orders.
  • Use o esquema espelho com mapeamento padrão em vez de um esquema plano construído manualmente. O esquema espelho deriva sua estrutura diretamente da resposta do conector e não possui essa diferença de maiúsculas e minúsculas.

Snowflake Merge: stageName e fileContent estão ausentes do esquema de solicitação para estágios externos

• Sintoma: Uma atividade Merge do Snowflake configurada contra um estágio externo mostra um esquema de solicitação sem os campos stageName e fileContent. A mesma atividade configurada contra um estágio interno expõe ambos os campos.
• Possível causa: Estágios externos são referências somente leitura a arquivos que já existem em armazenamento em nuvem externo (S3, GCS ou Azure Blob). A atividade Merge não pode fazer upload do conteúdo do arquivo em um estágio externo, portanto, o esquema omite os campos que impulsionam esse upload.
• Resolução:
  • Quando a atividade tem como alvo um estágio externo, certifique-se de que os arquivos de dados já estejam presentes na localização de armazenamento em nuvem que o estágio referencia. A atividade Merge lê diretamente desses arquivos; nenhum campo fileContent é necessário.
  • Quando você precisar enviar o conteúdo do arquivo da operação, configure a atividade Merge para usar um estágio interno. O esquema então expõe stageName e fileContent.

Snowflake Inserir ou Mesclar: erros de sintaxe SQL devido a caracteres especiais

• Sintoma: Uma atividade Inserir ou Mesclar do Snowflake falha com um erro de compilação SQL, como:

  SQL compilation error:
  syntax error line 1 at position <n> unexpected '<token>'.
  

  Os valores das colunas também podem aparecer mapeados incorretamente, com dados de um campo aparecendo na coluna errada.

• Possíveis causas:

  • Valores de campo contendo aspas simples (por exemplo, um valor como corner's) não são escapados antes de serem incluídos na carga útil SQL. A aspa não escapada termina a string prematuramente, fazendo com que o restante do valor seja interpretado como sintaxe SQL em vez de dados.
  • Um nome de coluna de destino contém um caractere especial, como um hífen (por exemplo, Zip-Code). O Snowflake requer que um identificador contendo um caractere especial seja colocado entre aspas; sem as aspas, produz um erro de sintaxe no hífen.

• Resolução:

  • Para valores contendo aspas simples: Nas Configurações Opcionais da conexão do Snowflake, ative Escapar caracteres especiais. Isso escapa automaticamente as aspas simples nas cargas úteis das atividades Inserir e Invocar Procedimento Armazenado. Para atividades Mesclar, ou como alternativa para Inserir, use SQLEscape no mapeamento de transformação para escapar as aspas simples nos valores de campo afetados antes que eles cheguem à atividade.
  • Para nomes de colunas contendo caracteres especiais: Confirme que Usar aspas para identificadores do Snowflake está ativado na conexão (ativado por padrão).

Snowflake: erro de espaço no heap do Java ao consultar grandes conjuntos de dados

• Sintoma: Uma atividade de Consulta do Snowflake falha com o seguinte erro quando a consulta retorna um grande número de linhas:

  Error executing query activity. Exception is Java heap space
  

  O conector relata o erro dessa forma porque envolve o erro subjacente do Java, que aparece mais abaixo na pilha de rastreamento:

  Caused by: java.lang.OutOfMemoryError: Java heap space
  

  Se esse erro ocorrer em consultas que retornam poucas linhas, ou se o mesmo agente também falhar com erros de heap através de outros conectores, a causa é mais provavelmente a alocação geral de heap do agente do que o tamanho do conjunto de resultados. Veja Espaço no heap do Java: OutOfMemoryError.

• Causa possível: O conector do Snowflake carrega todo o conjunto de resultados da consulta na memória da JVM antes de passá-lo para a transformação. Com conjuntos de resultados muito grandes, isso esgota o heap da JVM do Tomcat no agente privado.

• Resolução: Para grandes volumes de consulta, use o conector de Banco de Dados com um driver JDBC do Snowflake em vez do conector do Snowflake. O conector de Banco de Dados não armazena em buffer o conjunto completo de resultados na memória, portanto, pode lidar com volumes de consulta muito maiores. Instale o driver JDBC do Snowflake no agente privado e, em seguida, configure uma conexão de Banco de Dados que o utilize. No agente 12.x e posterior, essa conexão de Banco de Dados também precisa de jdbc_query_result_format=json em sua string de conexão; veja Snowflake (JDBC): Operações falham após a atualização do agente para 12.x.

  Se você precisar permanecer no conector do Snowflake, qualquer uma das seguintes opções pode reduzir a pressão na memória, embora nenhuma delas seja garantida como suficiente para conjuntos de dados na casa dos milhões de linhas:

  • Divida a consulta em lotes usando as cláusulas SQL LIMIT e OFFSET, executando a operação repetidamente com offsets incrementais até que todas as linhas sejam processadas.
  • Aumente o tamanho do heap da JVM do Tomcat no agente privado (veja memória heap do Tomcat).

Snowflake (JDBC): Operações falham após a atualização do agente para 12.x

• Sintoma: Após atualizar um agente privado para a versão 12.x, operações que consultam o Snowflake através de um driver JDBC do Snowflake (uma conexão de banco de dados ou um script DBExecute) falham em tempo de execução, mesmo que o teste de conexão seja bem-sucedido. O erro faz referência à camada de memória Arrow do driver:

  JDBC driver internal error: exception creating result java.lang.ExceptionInInitializerError at net.snowflake.client.jdbc.internal.apache.arrow.memory.unsafe.UnsafeAllocationManager
  

• Causa possível: Por padrão, o driver JDBC do Snowflake retorna resultados de consulta no formato Apache Arrow, que não é compatível com o agente 12.x e versões posteriores. O driver falha ao construir o conjunto de resultados, então o teste de conexão (que não retorna nenhum conjunto de resultados) ainda passa enquanto as consultas falham. Atualizar a versão do driver JDBC não resolve o problema.

• Solução: Adicione jdbc_query_result_format=json à string de conexão do Snowflake para que o driver retorne resultados em JSON em vez de Arrow. Anexe isso aos parâmetros existentes da string de conexão (por exemplo, &jdbc_query_result_format=json), em seguida, salve, reteste a conexão e execute novamente a operação.

Conector SOAP

Erro de implantação SOAP: "Sem WSDL com localizador"

• Sintoma: Implantar um projeto que inclui uma conexão SOAP, ou uma atividade de API SOAP Request ou SOAP Response, falha com:

  Failed to deploy - Internal Error: No WSDL with locator
  

• Causas possíveis:

• O WSDL foi removido, reimportado ou sua referência interna foi quebrada, então o projeto faz referência a um identificador WSDL que não existe mais.

• O projeto foi implantado ou transferido para outro ambiente antes do lançamento do Harmony 12.9, quando implantar um projeto poderia excluir arquivos WSDL que ainda estavam em uso. O lançamento 12.9 impede a exclusão, mas um WSDL excluído antes disso ainda deve ser re-enviado.

• Resolução:

  1. Reenvie o WSDL para o componente afetado:

     • Para uma conexão SOAP, abra a conexão e selecione Upload URL ou Upload file (não Select existing), reenvie o WSDL, revise as configurações de Port e Select methods, e clique em Save Changes.
     • Para uma atividade SOAP Request ou SOAP Response, abra a atividade e reenvie o WSDL na etapa 1 de sua configuração.

  2. Revise quaisquer transformações que herdem esquemas do WSDL reenviado e regere-as se necessário.

  3. Reimplante o projeto.

  4. Se o projeto tiver múltiplos WSDLs e não estiver claro qual deles está afetado, consulte solução de problemas de conexão SOAP para identificá-lo a partir de uma exportação JSON.

SOAP WSDL: schemaLocation deve usar referências relativas

• Sintoma: Uma conexão SOAP que referencia um WSDL com arquivos de esquema XSD importados falha ao carregar ou produz erros de resolução de esquema em tempo de design.
• Causa possível: O WSDL usa URLs absolutas em seus atributos schemaLocation para arquivos XSD importados (por exemplo, http://example.com/schema.xsd). O agente não consegue buscar esquemas de URLs remotas absolutas ao carregar um WSDL importado localmente.
• Resolução:
  1. Edite o WSDL para que todas as referências schemaLocation usem caminhos relativos (por exemplo, schema.xsd em vez de http://example.com/schema.xsd).
  2. Coloque todos os arquivos XSD referenciados no mesmo diretório que o WSDL e reimporte o WSDL na conexão SOAP.

O conector SOAP reescreve os prefixos de namespace XML e a estrutura

• Sintoma: O envelope XML produzido por uma atividade SOAP não corresponde aos prefixos de namespace literais ou à estrutura do WSDL de origem (por exemplo, o conector substitui xmlns:ns1 por xmlns:glob). Serviços SOAP rigorosos que comparam o texto exato do prefixo rejeitam a solicitação.
• Possível causa: O mecanismo de transformação processa mensagens SOAP como XML estruturado, não como texto literal. Ele produz uma carga útil semanticamente equivalente que pode usar diferentes prefixos de namespace do que o WSDL de origem.
• Resolução: Para serviços SOAP que exigem uma estrutura XML literal, contorne o conector SOAP e construa a carga útil da solicitação como uma string:
  1. Crie uma conexão HTTP v2 apontando para a URL do serviço SOAP.
  2. Em uma transformação, construa o envelope SOAP como uma string, concatenando literais de string e valores mapeados com o operador +. Alternativamente, leia um modelo de um arquivo e substitua valores dinâmicos com Replace.
  3. Na atividade POST do HTTP v2, use o esquema de solicitação padrão (não faça upload de um esquema de solicitação personalizado) e mapeie a string do envelope SOAP construído para o campo body desse esquema. O conector envia o valor de body como está, preservando o XML literal.
  4. Defina o cabeçalho Content-Type como text/xml ou application/soap+xml, e defina o cabeçalho SOAPAction se o serviço exigir.
  5. Leia a resposta do serviço do campo responseContent do esquema de resposta padrão da atividade.

SOAP: Mensagens MTOM/XOP não são suportadas

• Sintoma: O conector SOAP não suporta mensagens SOAP MTOM/XOP (Mecanismo de Otimização de Transmissão de Mensagens).
• Resolução: Use a solução alternativa em Suporte a mensagens SOAP MTOM/XOP usando o Jitterbit Studio, que constrói a solicitação MTOM fora do conector SOAP.

Conector VTEX

O teste de conexão falha com "Você não tem permissão para acessar este recurso"

• Sintoma: Um teste de conexão VTEX falha com um erro de permissão no Studio, mesmo que as mesmas credenciais funcionem em ferramentas externas como o Postman.

  You don't have permission to access this resource
  

• Causa possível: O usuário VTEX ou a chave de aplicativo associada à conexão está faltando uma ou mais permissões que o conector usa para validar a conexão. Essas permissões são mais rigorosas do que as necessárias para acesso básico a dados.

• Resolução:
  1. No portal de administração da VTEX, abra o perfil de acesso atribuído ao usuário ou à chave de aplicativo que o Jitterbit está usando.
  2. Confirme que o perfil de acesso inclui o recurso Gerenciador de Licenças com acesso ao recurso Obter conta por identificador.
  3. Salve o perfil e reteste a conexão VTEX no Studio.

Conector Workday

Workday: WSDL v42.0 e v42.1 retornam erros para serviços específicos

• Sintoma: Operações usando o conector Workday configurado com a versão WSDL 42.0 ou 42.1 falham ao acessar os serviços web Human_Resources ou Resource_Management.
• Causa possível: Sabe-se que a WSDL v42.0 retorna erros para os serviços Human_Resources (v42.0) e Resource_Management (v42.0). Sabe-se que a WSDL v42.1 retorna erros para o serviço Human_Resources (v42.1). Esses são problemas conhecidos específicos para essas versões de WSDL.
• Resolução:
  1. Na configuração da conexão Workday, altere a versão WSDL para 41.x ou 43.0 ou posterior para operações que utilizam os serviços Human_Resources ou Resource_Management.
  2. Teste a conexão e execute novamente as operações afetadas para confirmar que o problema foi resolvido.

Workday: O teste de conexão falha com "A tarefa submetida não está autorizada"

• Sintoma: Um teste de conexão do Workday falha com:

  Error occurred while opening connection. The Exception is Processing error occurred. The task submitted is not authorized.
  

  Este erro pode ocorrer tanto com autenticação Basic Auth quanto com tipos de autenticação JWT Bearer. Observe que as operações podem ser executadas com sucesso em tempo de execução, mesmo quando o teste de conexão retorna esse erro, porque o teste chama um serviço específico do Workday (Get_Message_Template_Translation_Request) que requer uma permissão que o ISU pode não ter, enquanto as operações de integração reais chamam serviços diferentes.

• Causas possíveis:

  • O Usuário do Sistema de Integração (ISU) não foi atribuído ao grupo de segurança Administrador de Configuração no Workday. A chamada de teste de conexão do conector é rejeitada se o ISU não tiver essa associação ao grupo de segurança.
  • O campo Host do Workday contém um valor incorreto. Um host incorreto faz com que a conexão falhe antes que a autenticação seja tentada.

• Resolução:

  1. Verifique se o valor do Host do Workday na configuração da conexão está correto. O host deve ser a URL base do seu inquilino Workday (por exemplo, https://wd5-impl-services1.workday.com/). Você pode confirmar o valor correto na página Visualizar Cliente API do Workday.
  2. Na instância do Workday, abra a tarefa Atribuir Usuários ao Grupo de Segurança Baseado em Usuário, selecione Administrador de Configuração e confirme se o ISU está listado sob Usuários do Sistema. Se não estiver, adicione o ISU. Para os passos completos, veja Pré-requisitos.
  3. Confirme que a tarefa Configurar Segurança do Serviço Web também foi concluída para o ISU, conforme descrito na página Pré-requisitos.
  4. Reteste a conexão.