Ir para o conteúdo

Solução de problemas de conectores no Jitterbit Studio

Este guia aborda erros e comportamentos inesperados específicos de conectores individuais do Jitterbit Studio, organizados por conector. Lista apenas conectores com problemas conhecidos e específicos do conector para documentar, não todos os conectores disponíveis. Para a lista completa de conectores, consulte Conectores. Comece com as etapas de diagnóstico abaixo e depois localize seu conector na seção relevante.

Para problemas nã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, consulte Solução de problemas de operação. Para problemas de agente privado, como um agente offline, não íntegro ou lento (que pode impedir a execução de operações), consulte 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 único lugar, consulte o guia de solução de problemas do Harmony.

Todas as entradas de solução de problemas nesta página

Etapas de diagnóstico

Estas etapas 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 de conexão, clique no botão Test para confirmar que a conexão é bem-sucedida. Clicar em Test também baixa a versão mais recente do conector para o agente, a menos que a política de organização Disable Auto Connector Update esteja ativada.

Atualizar os metadados de conexão e esquemas de atividade

Muitos problemas de conector, 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 atualização (Refresh) para recarregar objetos e esquemas do endpoint.

Confirmar disponibilidade do conector e mantê-lo atualizado

A coluna Disponibilidade do Agent na lista de Connectors mostra se um conector requer um agent privado.

Os connectors são lançados e atualizados conforme o cronograma de lançamentos da Jitterbit, separadamente do agent. Em agents 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 de organização Desabilitar Atualização Automática de Connector esteja ativada. Para atualizar os connectors de um grupo de agents a qualquer momento, inclusive quando essa política está ativada, selecione Action > Update connectors para o grupo na página Agents do Management Console.

Ativar log detalhado do conector

Quando direcionado pelo suporte da Jitterbit, ative o log detalhado do conector no agent privado para capturar detalhes no nível do conector, reproduza o problema e analise os logs. O log detalhado usa uma entrada de logger específica do conector; a linha exata a adicionar em logback.xml é fornecida na seção Troubleshooting da página de documentação do próprio conector, em Connectors.

Configuração de conexão

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

  • Sintoma: Muitos connectors incluem uma tabela 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 causa a malformação do valor do campo.
  • Possível causa: Campos na tabela Propriedades de Configurações Avançadas não suportam variáveis que carregam objetos JSON não escapados.
  • Resolução:
    • Antes de passar conteúdo JSON por meio de uma variável para um campo 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 Propriedades de Configurações Avançadas são preenchidas em tempo de execução apenas na versão do agent 10.75 / 11.13 ou posterior. Se um valor de variável não aparecer em tempo de execução, confirme se o agent atende a essa versão mínima.

Conector Amazon Bedrock

Amazon Bedrock: erro de modelo "on-demand throughput isn't supported"

  • Sintoma: Uma atividade do 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.

  • Possível causa: 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. Digite o ID do modelo com prefixo usando a opção Enter model identifier na configuração da atividade.

Conector Cloud Datastore

Atividade Delete Items relata sucesso mas não deleta o registro

  • Sintoma: Uma atividade Delete Items do Cloud Datastore relata sucesso no log de operação, mas o registro de destino ainda existe quando consultado posteriormente.
  • Possível causa: Delete Items identifica registros pela Key (ou Alternative Key) do armazenamento, fornecida 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 de seu valor de chave, nenhum item corresponde e a atividade relata sucesso sem deletar nada.
  • Resolução:
    • Na transformação que prepara a solicitação Delete Items, mapeie a Key (ou Alternative Key) do armazenamento, não o ID do registro interno.
    • Ao encadear a partir de uma atividade Query Items, mapeie o valor key da resposta da consulta para a solicitação de exclusão.

Conector Coupa

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

  • Sintoma: Uma operação do conector Coupa falha com um erro Forbidden (403) ao usar autenticação por chave de API.
  • Possível causa: A partir da versão Coupa R35 (janeiro de 2023), as chaves de API do Coupa foram descontinuadas 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.
  • Resolução:
    1. Na configuração da conexão Coupa, mude da autenticação por chave de API para autenticação OAuth 2.0.
    2. Na sua instância Coupa, crie uma aplicação 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 Database

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

  • Sintoma: Uma função DBLookup ou DBExecute direcionada a um banco de dados PostgreSQL ou SQL Server por 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 no banco de dados.

  • Possível causa: Versões do agente anteriores à 12.9 podem tentar incorretamente decodificar em Base64 um valor de resultado JDBC que corresponda a um padrão semelhante a Base64, independentemente de o valor ser dados realmente 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 conseguir atualizar imediatamente, evite disparar a verificação de Base64 convertendo o valor afetado para hexadecimal na consulta SQL e depois decodificando-o em uma etapa de script usando HexToString. Por exemplo, no PostgreSQL: SELECT encode(<column>, 'hex'). Use o equivalente SQL decode(...,'hex') com StringToHex ao escrever o valor de volta no banco de dados.

Database (ODBC): caracteres multibyte não são tratados corretamente

  • Sintoma: Ao ler ou escrever em um banco de dados por meio do conector Database usando um driver ODBC, caracteres multibyte ou não-ASCII (por exemplo, caracteres acentuados ou não-latinos) não são tratados corretamente.
  • Possível causa: O suporte a caracteres multibyte para o conector Database por um driver ODBC não está habilitado por padrão. A variável Jitterbit jitterbit.scripting.db.multibyte.enable deve ser definida como true. Este suporte está disponível na versão do agente 12.6 e posterior, e não é necessário ao usar um driver JDBC.
  • Resolução:
    1. Confirme que o agente é versão 12.6 ou posterior.

    2. Defina a variável jitterbit.scripting.db.multibyte.enable como true antes da operação do banco de dados ser executada. Por exemplo, em uma etapa 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.

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

  • Sintoma: Um teste de conexão do conector de Banco de dados falha com:

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

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

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

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

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

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

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

Banco de dados: DBLookup ou DBExecute falha com "No suitable driver found" ao testar um script

  • Sintoma: Testar um script (usando Run test) 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, Password ou Connection String 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 de tempo de execução quando a função resolve a conexão. Diferentemente de uma variável referenciada em um campo configurado da própria 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 à mesma variável global ou de projeto seu valor real diretamente no script testado (por exemplo, $login = "value"; para uma variável chamada login), depois remova a atribuição antes de implantar a operação.

Banco de dados: Erros de comprimento de campo em Insert, Update ou Upsert

  • Sintoma: Uma atividade de Insert, Update ou Upsert do Banco de dados falha com um status de operação Error quando um valor de origem mapeado é maior do que o permitido pela coluna de destino. O log de operação contém um dos seguintes:

    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

  • Possível causa: 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.

  • Resolução:
    1. Na configuração da atividade Insert, Update ou Upsert do Banco de Dados, ative Permitir truncamento de campos de caracteres para evitar erros de comprimento de campo. Com essa opção ativada, valores que excedem o comprimento do campo de destino são truncados e a operação relata um status de Sucesso com Informações em vez de um status de Erro.
    2. Se o truncamento não for aceitável, corte 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.

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

  • Sintoma: Arquivos JAR de driver JDBC personalizados instalados para o conector de Banco de Dados são deletados ou sobrescritos quando o agente é atualizado.
  • Possível causa: Apenas o diretório <JITTERBIT_HOME>/tomcat/drivers/lib/ é preservado entre atualizações de agente. Arquivos JAR de driver personalizados colocados em outro lugar 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/. Este diretório é preservado durante atualizações de agente.
    • Se os drivers estão atualmente no local errado, mova-os para o diretório correto e reinicie o agente.

Banco de Dados: caracteres especiais em nomes de coluna causam falhas de consulta

  • Sintoma: Consultas ou transformações do Banco de Dados falham quando uma tabela de origem tem nomes de coluna que contêm caracteres especiais como @.
  • Possível causa: Drivers ODBC não conseguem lidar com certos caracteres especiais em nomes de coluna de banco de dados.
  • Resolução:
    1. Crie uma visualizaçã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 visualização em vez da tabela original.

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

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

IBM DB2 no iSeries: falha de conexão JDBC

  • Sintoma: Uma conexão do Banco de Dados com IBM DB2 no iSeries (AS/400 ou IBM i) usando um driver JDBC falha ao conectar.
  • Possível causa: Algumas conexões com DB2 no iSeries usando um driver JDBC encontram problemas que não ocorrem com um driver ODBC.
  • Resolução: Mude 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 JCC JDBC (JAR e arquivo de licença descontinuados)

  • Sintoma: uma conexão de Banco de Dados usando o driver JCC JDBC do IBM DB2 falha com um erro referenciando uma licença ausente, ou falha ou produz erros de compatibilidade com versões mais recentes do DB2.
  • Possíveis causas:
    • O arquivo de driver db2jcc.jar implementa a especificação JDBC 3 descontinuada. O db2jcc4.jar atual implementa JDBC 4, que as versões mais recentes do DB2 exigem.
    • O driver JCC requer um arquivo JAR de licença separado. O JAR do driver sozinho não é suficiente.
  • Resolução:
    • Use o driver db2jcc4.jar, não o descontinuado db2jcc.jar. Instale-o em <JITTERBIT_HOME>/tomcat/drivers/lib/ no agente privado.
    • Obtenha o arquivo JAR de licença da IBM (nomeado db2jcc_license_cisuz-XX.jar, onde XX é o número da versão) e copie-o para <JITTERBIT_HOME>/tomcat/shared/lib/.
    • Como alternativa, 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.

Kerberos: "Could not initialize class KerbAuthentication"

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

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

  • Possível causa: 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 ticket do Kerberos) como 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 teste de conexão

  • Sintoma: uma conexão de Banco de Dados usando autenticação Kerberos falha com erros referenciando jgss ou gss.
  • Possível causa: a JVM está configurada com -Dsun.security.jgss.native=true, que a direciona para usar a biblioteca GSSAPI nativa do SO. Em alguns sistemas, isso entra em conflito com a configuração do Kerberos.
  • Resolução:
    1. Remova o parâmetro -Dsun.security.jgss.native=true dos argumentos JVM do agente.
    2. Em 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.

Microsoft Excel: "Operation must use an updateable query"

  • Sintoma: uma atividade de Inserção ou Atualização de Banco de Dados direcionada a um arquivo do Microsoft Excel (via ODBC) falha com:

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

  • Possível causa: 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 Connection String da conexão de Banco de Dados (inserido em Optional Settings com Use Connection String selecionado), acrescente ReadOnly=0; ao final da string de conexão para abrir o arquivo do Excel em modo de leitura/gravação.

MySQL: Acesso negado apesar de credenciais corretas

  • Sintoma: A conexão com 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.

  • Possível causa: 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.

  • Resoluçã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 de concessão varia conforme a versão do MySQL (consulte a documentação do MySQL ou entre em contato com o administrador do MySQL), mas geralmente assume 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.

MySQL: Ativar Batch não melhora o desempenho de Insert ou Update

  • Sintoma: Uma atividade de Insert ou Update do banco de dados usando o driver JDBC do MySQL mostra pouca ou nenhuma melhoria de desempenho após ativar Enable Batch, mesmo com um grande número de registros.
  • Possível causa: Por padrão, o driver JDBC do MySQL (Connector/J) envia uma instrução por linha independentemente de Enable Batch, em vez de um verdadeiro batch no lado do servidor.
  • Resolução: No campo Additional Connection String Parameters da conexão, adicione rewriteBatchedStatements=true.

MySQL: Driver ODBC não listado no menu suspenso do Studio

  • Sintoma: Ao configurar uma conexão de banco de dados com MySQL usando um driver ODBC em um agente privado, o driver instalado não aparece no menu suspenso 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.
  • Resolução:
    • No host do agente privado (Windows), abra Data Sources (ODBC) (em Administrative Tools) e confirme se o driver ODBC do MySQL está listado. Para opções de driver MySQL, consulte 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.

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

  • Sintoma: Um teste de conexão do conector de banco de dados com PostgreSQL falha com um erro de "incompatibilidade de codificação do cliente".
  • Possível causa: A codificação que o servidor PostgreSQL usa difere da codificação padrão assumida pelo driver ODBC do PostgreSQL.
  • Resolução:
    • Nas configurações de conexão do banco de dados, adicione ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (substituindo a codificação real do servidor) ao campo Additional Connection String Parameters.
    • 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.

PostgreSQL: Usar 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 no Linux falham ou produzem erros, mesmo quando um driver parece estar instalado.
  • Possível causa: Muitas distribuições Linux incluem um driver ODBC PostgreSQL empacotado com unixODBC que não funciona de forma confiável com o Harmony.
  • Resolução: Não use o driver PostgreSQL empacotado pela distribuição. Use o driver ODBC PostgreSQL incluído na instalação do agente Jitterbit.

SQL Server JDBC: Falha na autenticação integrada do Windows

  • Sintoma: Para agentes privados, uma conexão de Banco de Dados com 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

  • Possíveis causas:

    • A DLL mssql-jdbc_auth necessária para autenticação integrada do Windows está ausente dos diretórios JRE que o agente Jitterbit usa em tempo de execução. Colocar a DLL no mesmo diretório que o arquivo JDBC JAR 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 JDBC JAR incluído no seu agente) para <JITTERBIT_HOME>/jre/bin e <JITTERBIT_HOME>/jre/lib. Faça backup do arquivo, pois ele pode ser removido durante atualizações principais 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.

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

  • Sintoma: Uma conexão de Banco de Dados usando autenticação do Windows do SQL Server falha mesmo quando as credenciais de domínio parecem corretas.
  • Possível causa: O usuário de domínio do Windows que executa o serviço do agente Jitterbit não possui os privilégios de nível do SO necessários para a Segurança Integrada do Windows.
  • Resolução:
    1. Conceda ao usuário de domínio os privilégios do Windows Fazer logon como um serviço e Agir como parte do sistema operacional no host do agente privado.
    2. Confirme que o usuário de domínio tem permissões de leitura e escrita 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: "Cannot insert explicit value for identity column" ao inserir em uma coluna de identidade

  • Sintoma: Uma operação do conector de Banco de Dados que escreve 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.

  • Possível causa: 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 o valor de identidade automaticamente, exclua a coluna do INSERT mapeando o campo de destino de identidade com a função Unmap. Para excluir a coluna apenas quando a origem não fornece um 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 na ramificação verdadeira ainda requer que IDENTITY_INSERT esteja ON; consulte a próxima opção.)

  • Se for necessário inserir valores explícitos na coluna de identidade, defina IDENTITY_INSERT na tabela de destino nos scripts pré e pós-SQL dentro da atividade:

    SET IDENTITY_INSERT <table> ON;

    SET IDENTITY_INSERT <table> OFF;

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

SQL Server: Falha na conexão com erro de caminho de certificado PKIX

  • Sintoma: Uma conexão de Banco de Dados com 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 funcionava anteriormente pode começar a falhar após uma atualização do agente para a versão 12.8 ou posterior.

  • Possível causa: 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 de certificação (CA) que o agente já confia, como um certificado autoassinado, um certificado emitido internamente ou o certificado CA do Amazon RDS que uma instância do Amazon RDS para SQL Server apresenta. Trata-se de uma falha de confiança de certificado e não de criptografia, portanto um banco de dados pode ter criptografia ativada 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 depois.

  • Resolução: Digite encrypt=false; no campo Parâmetros de Cadeia de Conexão Adicionais em Configurações Opcionais da conexão de Banco de Dados, ou inclua-o em uma cadeia de conexão manual. Isso funciona em agentes na nuvem e privados. Para mais informações, consulte Criptografia de conexão e certificados de servidor.

    Aviso

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

Conector EDI for Cloud v2

As entradas de solução de problemas do conector EDI for 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:

Conector de Email

Teste de conexão do Gmail falha com erro de autenticação

  • Sintoma: Um teste de conexão com 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.
  • Possível causa: O Google requer uma senha de app para contas com Verificação em 2 Etapas ativada. A senha da conta do Google não é aceita por SMTP ou IMAP quando a Verificação em 2 Etapas está ativa; apenas senhas de app são aceitas.
  • Resolução:
    1. Na sua conta do Google, gere uma senha de app para a aplicação Jitterbit (consulte a página Fazer login com senhas de app do Google).
    2. Na configuração da conexão de Email no Studio, insira a senha de app no campo Senha SMTP e/ou Senha IMAP em vez da senha da conta do Google.

Assinatura S/MIME falha ou é rejeitada por provedores de email na 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 na nuvem, como Microsoft 365 ou Exchange Online.
  • Possíveis causas:
    • Provedores na nuvem exigem um certificado S/MIME emitido por uma autoridade certificadora (CA) confiável. Certificados autoassinados não são aceitos por provedores na nuvem, como Microsoft 365 (Exchange Online).
    • S/MIME funciona apenas ao usar agentes privados. Se a operação for executada em um agente na nuvem, a assinatura S/MIME não se aplica independentemente do tipo de certificado.
  • Resolução:
    1. Obtenha um certificado S/MIME de uma CA confiável. Let's Encrypt fornece certificados gratuitos aceitos pelos principais provedores na nuvem.
    2. Substitua o certificado autoassinado na atividade Enviar Email do Email pelo certificado emitido pela CA (consulte Pré-requisitos para criptografia S/MIME).
    3. Para agentes privados, confirme que o certificado foi importado corretamente no truststore padrão do agente. Para agentes na nuvem, a assinatura S/MIME não é suportada.

Conexão de Email do Microsoft 365 usando autenticação ROPC falha quando MFA está ativado

  • Sintoma: Uma conexão OAuth 2.0 do Microsoft 365 que usa a concessão Resource Owner Password Credentials (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.
  • Possível causa: A autenticação ROPC requer que a autenticação multifator (MFA) seja desativada para as credenciais do Microsoft 365 usadas com o conector. A concessão ROPC não consegue 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 não for possível remover MFA da conta, use um método de autenticação diferente e suportado para a conexão em vez de ROPC.

Envio de Email falha quando o mesmo endereço aparece em múltiplos campos de destinatário

  • Sintoma: Uma atividade Enviar Email do 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.
  • Possível causa: O conector de Email não permite que o mesmo endereço apareça em múltiplos 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 através 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 da 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 os endereços para a atividade.

Conectores Epicor

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

  • Sintoma: Uma atividade Query do Epicor Prophet 21 falha em tempo de execução quando a Cadeia 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 do 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 Cadeia 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 uma etapa 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 arquivo ou acompanhamento

  • Sintoma: Uma atividade de leitura do FTP, Compartilhamento de Arquivo ou Armazenamento Local falha porque o arquivo que ela 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 anteriormente o arquivo foi bem-sucedida; a falha ocorre em uma etapa posterior (geralmente uma etapa de arquivo ou notificação) que tenta ler o mesmo arquivo com o mesmo filtro.

  • Possíveis causas:

    • A atividade de processamento já moveu ou deletou o arquivo de origem como parte de seu comportamento Após Processamento, então a etapa de arquivo 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 ela termine de escrevê-lo.
    • Uma atividade Escrever do FTP com Usar Renomeação FTP habilitada (o padrão) escreve o arquivo com um nome temporário e o renomeia para o nome final após a conclusão. Uma operação de leitura posterior que é executada antes da renomeação ser concluída não encontrará o arquivo.
  • Resolução:
    • Confirme se a etapa anterior já tratou o arquivamento através de suas opções Após Processamento integradas (mover, renomear, deletar). Se sim, uma etapa de arquivo separada é redundante e deve ser removida.
    • Se uma etapa de arquivo 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 arquivo, em vez de reler o caminho de origem.
    • Se uma etapa posterior 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 Sincronamente, ou, ao chamar a operação a partir 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 Escrever do FTP estiver escrevendo no mesmo local, verifique se Usar Renomeação FTP está habilitada na atividade FTP Write. Se a leitura posterior for executada antes da renomeação ser concluída, desabilite Usar Renomeação FTP na atividade de escrita, ou garanta que a operação de leitura não seja executada até que a operação de escrita seja totalmente concluída.

FTP, File Share e Local Storage: Pasta de erro não gravada em caso de falha de conexão

  • Sintoma: Após uma atividade de FTP, File Share ou Local Storage falhar, nenhum arquivo aparece na pasta de erro configurada.
  • Possível causa: A pasta de erro foi projetada para arquivar uma cópia do arquivo de origem após o 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 da atividade ler qualquer arquivo, então não há arquivo para gravar na pasta de erro.
  • Resolução:
    • Se a pasta de erro estiver vazia após uma falha, verifique os logs de operação para um erro no nível de conexão (como uma falha de autenticação ou mensagem de host inacessível).
    • Use o botão Test na conexão para confirmar se o problema está no nível de rede ou autenticação.

FTP, File Share e Local Storage: Palavras-chave de nome de arquivo não resolvidas em caminhos de pasta 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 pasta de erro em atividades de FTP, File Share e Local Storage não suportam substituição de palavras-chave de nome de arquivo. Variáveis não são expandidas nesses campos.
    • Esses campos se referem 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 uma etapa de script após a atividade para mover ou renomear o arquivo processado para o local pretendido usando funções de arquivo.

FTP, File Share, Local Storage e Temporary Storage: Write Headers não produz um arquivo somente com cabeçalho quando a origem não retorna registros

  • Sintoma: Uma atividade de gravação baseada em arquivo com a opção Write Headers ativada (FTP Write, File Share Write, Local Storage Write ou Temporary Storage Write) não grava cabeçalhos quando a origem não retorna registros. Um arquivo vazio é criado ou nenhum arquivo é criado (se Do not create empty files também estiver selecionado).
  • Causa: Este é o comportamento esperado. Os cabeçalhos são gravados como parte da saída da transformação, e a transformação é executada apenas quando a origem retorna pelo menos um registro. Quando a origem não retorna registros, a transformação é ignorada, portanto nenhuma saída (incluindo cabeçalhos) é gravada, e o Studio registra um aviso de que a origem está vazia. Isso não é específico de um conector de origem particular ou destino de arquivo simples.

FTP: 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 arquivos pequenos dentro de um loop, ou muitas operações executadas contra o mesmo servidor em um agendamento) eventualmente falha com uma negação de login ou erro de conexão. A mesma operação funciona bem sob carga menor.
  • 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 é por design. 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 independentemente.
    • 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 Read dentro de um loop por uma única atividade Read que use um curinga no campo Get Files (por exemplo, *.xml ou data_*.csv), depois divida os dados recuperados em registros individuais dentro de uma transformação.
    • Se a operação precisar processar arquivos um de cada vez, peça ao administrador do servidor FTP para aumentar o limite por usuário de conexões simultâneas ou autenticações por minuto.

SFTP "Login denied. Authentication failure." ao usar chaves SSH

  • Sintoma: Uma operação SFTP usando autenticação de chave privada SSH falha com Login denied. Authentication failure., 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.

  • Possíveis causas:

    • A chave privada está protegida por uma frase-passe, mas a configuração PrivateKeyPassphrase está faltando na seção [SSH] do jitterbit.conf do agente.
    • 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 de PrivateKeyFile e, se a chave estiver protegida por frase-passe, o valor correspondente de PrivateKeyPassphrase (consulte Conectando ao SFTP com chaves SSH).
    • Na configuração do endpoint FTP, limpe o campo Password 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 em formato PuTTY (.ppk) ou outro formato não-OpenSSH.

FTP Write: "Use FTP Rename" falha ao escrever em um servidor SFTP

  • Sintoma: Uma atividade FTP Write configurada com a opção Use FTP Rename falha quando o destino é um servidor SFTP, com um erro similar a:

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

    O <reason> é tipicamente No such file or directory, ou Permission denied para um arquivo cujo nome contém caracteres multibyte.

  • Possíveis causas:

    • Em agentes anteriores à versão 11.56, a opção Use FTP Rename não respeitava de forma confiável a etapa de renomeação ao escrever em um servidor SFTP, particularmente em operações com padrão de arquivo.

  • O nome do arquivo contém caracteres multibyte e o servidor SFTP não suporta renomeação de arquivos cujos nomes os contêm. A partir da versão 12.8 do agent, o conector FTP consegue ler e escrever arquivos com nomes multibyte (exceto em agentes privados do Windows a partir da versão 12.10; consulte Codificação de caracteres e suporte a multibyte); porém, com Use FTP Rename ativado, o agent faz upload do arquivo com um nome temporário (sufixo -jbupload) e depois o renomeia para o nome final. Se o servidor não conseguir renomear o nome multibyte, retorna um erro enganoso Permission denied. Nomes de arquivo usando apenas caracteres ASCII não são afetados. Esta é uma limitação do servidor SFTP, não do Jitterbit.

  • Resolução:

    • Certifique-se de que o agent está na versão 11.56 ou posterior, onde Use FTP Rename com SFTP funciona conforme esperado. Agentes na nuvem são atualizados automaticamente; atualize agentes privados se necessário.

    • Desmarque a caixa de seleção Use FTP Rename na configuração da atividade para que o agent escreva diretamente no caminho de destino em vez de fazer 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 renomeação de arquivos cujos nomes contêm caracteres multibyte.

SFTP: Acrescentar a arquivo não é suportado

  • Sintoma: Uma atividade Write do FTP configurada com a opção Append To File não acrescenta ao arquivo existente quando o destino é um servidor SFTP.
  • Possível causa: O protocolo SFTP não suporta acrescentar a arquivos existentes. Esta é uma limitação no nível do protocolo, não um problema de configuração do Jitterbit.
  • Resolução:
    • Use FTP ou FTPS se o comportamento de acréscimo for necessário.
    • Se SFTP for necessário, implemente a lógica de acréscimo manualmente: leia o conteúdo do arquivo existente, combine-o com os novos dados e escreva o resultado completo de volta como um arquivo completo.

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

  • Sintoma: Uma atividade do conector FTP (sobre o protocolo FTP ou SFTP) falha quando o nome do arquivo de origem ou destino contém um caractere hash (#). A leitura do arquivo retorna um erro como No File with that name ou Error in SSH Layer, e a escrita do 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 resto.
  • Resolução:
    • Renomeie os arquivos para remover ou substituir o caractere # antes que o Jitterbit os leia ou escreva.
    • Para fazer com que o conector codifique em URL nomes que contêm caracteres especiais como #, defina jitterbit.source.ftp.encode_url como true em um script de transformação para nomes de arquivo ou pasta de origem, e jitterbit.target.ftp.encode_url como true para arquivos escritos no destino.

File Share: Caminhos UNC com nomes de servidor falham em agentes na nuvem

  • Sintoma: Conexões do File Share que usam caminhos UNC (por exemplo, \\server\share) falham ao conectar quando a operação é executada em um agente na nuvem.
  • Possível causa: Agentes na nuvem conseguem resolver caminhos UNC usando um endereço IP público, mas não conseguem resolver nomes de host de servidor 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 nome de servidor em caminhos UNC for necessária, use um agente privado.

Compartilhamento de Arquivos: Arquivos maiores que 2 GB podem falhar na recuperação

  • Sintoma: Uma atividade Ler de Compartilhamento de Arquivos pode falhar ao recuperar arquivos individuais maiores que 2 GB. Arquivos menores são recuperados sem problemas.
  • Possível causa: 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 alternativa, divida o arquivo em segmentos menores na origem para que cada arquivo tenha menos de 2 GB antes que a atividade Ler do Compartilhamento de Arquivos 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.
  • Possível causa: O Armazenamento Local acessa o sistema de arquivos da 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 fim.
  • Resolução:
    • Use agentes privados para qualquer operação que exija o conector de Armazenamento Local. O Armazenamento Local é desabilitado em agentes privados por padrão, então também ative-o no arquivo de configuração do agente privado (consulte Ativar local 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 do Armazenamento Temporário gravados por uma operação estão ausentes quando uma operação posterior tenta lê-los.
  • Possíveis causas:
    • 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 tem seu próprio Armazenamento Temporário local. Operações na mesma cadeia de operações têm garantia de execução no mesmo agente, mas uma operação posterior que não esteja na mesma cadeia pode ser despachada para um agente diferente e acessar uma instância diferente do Armazenamento Temporário, portanto não encontra o arquivo, independentemente da janela de 24 horas. Consulte Notas importantes.
  • Resolução:
    • Vincule operações que devem compartilhar arquivos do 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] de jitterbit.conf. Consulte [FileCleanup].
    • Se os arquivos não puderem ser consumidos na 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 do Armazenamento Temporário.

Armazenamento Temporário: Caracteres restritos em caminhos de arquivo

  • Sintoma: Uma atividade de Leitura ou Gravação do Armazenamento Temporário falha quando o caminho do arquivo contém certos caracteres especiais.
  • Possível causa: Os seguintes caracteres não são suportados em caminhos de arquivo 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 na nuvem

  • Sintoma: uma atividade de Gravação de Armazenamento Temporário falha ao gravar arquivos grandes através de um agente na nuvem.
  • Possível causa: agentes na 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 na nuvem estiverem disponíveis, divida grandes conjuntos de dados em múltiplos arquivos menores que 50 GB antes de gravar no Armazenamento Temporário.

Conector HTTP

HTTP v2: cabeçalho de autorização duplicado causa erro 400 Bad Request

  • Sintoma: operações do conector HTTP v2 falham com um erro 400 quando tanto a autenticação no nível de conexão quanto um cabeçalho de solicitação Authorization definido manualmente estão configurados na mesma conexão ou atividade.
  • Possível causa: 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 autorização. Não adicione um cabeçalho Authorization manual junto 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 projeto de cabeçalho de solicitação falha ao fazer parse

  • Sintoma: uma atividade do 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 parse:

    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 incorporadas 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 valor de cabeçalho, escape cada aspas duplas 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 segmentos, por exemplo https://api.example.com/endpoint?param1=A?param2=B.
  • Possível causa: Parâmetros de consulta foram declarados em dois locais: 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 "Encode request URL" está ativado

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

HTTP v2: Operação falha quando Base URL redireciona

  • Sintoma: Uma operação HTTP v2 falha imediatamente quando a URL Base configurada retorna uma resposta de redirecionamento (3xx).
  • Possível causa: Follow redirects está desativado nas configurações de conexão HTTP v2, portanto 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, ative Follow redirects para permitir que o conector siga automaticamente as respostas de redirecionamento até a URL de destino final.

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

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

HTTP v2: Código de status de 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 de resposta HTTP após uma atividade HTTP v2 ser executada não recebem nenhum valor. A mesma abordagem funciona com o conector HTTP, mas não com HTTP v2.
  • Possível causa: O conector HTTP v2 não popula variáveis Jitterbit de origem ou destino. Os dados de resposta, incluindo o código de status HTTP, são retornados através do schema de resposta da atividade.
  • Resolução:
    • Para capturar o código de status usando o schema 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 schema 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 schema de resposta personalizado, ative Incluir Propriedades Adicionais da Resposta HTTP no Schema na configuração da atividade. Isso envolve o schema 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 requisições malsucedidas).
    • Para que o código de status esteja disponível quando a API retorna uma resposta malsucedida, ative Ignorar erro de operação em caso de código de status malsucedido nas configurações opcionais da atividade. Sem essa configuração, a operação falha em respostas malsucedidas antes que os dados de resposta possam ser mapeados.

HTTP v2: Namespaces XML reescritos ao usar um schema de requisiçã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 tenha sucesso quando enviado do Postman ou SoapUI. Ao inspecionar o corpo da requisiçã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 elemento são renumerados como ns, ns1, ns2).
  • Possível causa: Quando um schema de requisiçã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 de 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 uma etapa de script anterior à 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 à versão 12.8, ou se o destino também rejeitar a consolidação de declarações de namespace no elemento raiz, use o schema de requisição padrão em vez de um personalizado e mapeie o payload XML completo como uma string no campo body do schema. O payload é então tratado como uma string em vez de XML analisado, portanto suas declarações de namespace são preservadas. O schema de resposta ainda pode ser um schema 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 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 Encode request URL. O conector então codifica a URL da solicitação, codificando espaços como %20.
    • Forneça a URL da solicitação completamente sem codificação. Não pré-codifique caracteres nem aplique a função URLEncode à URL, porque caracteres já codificados ficam com dupla codificação quando Encode request URL 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 de solicitação é definido na atividade.
  • Possível causa: Quando o esquema de 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 nenhum 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 em HTTP, defina o esquema de solicitação na transformação em vez de na atividade e deixe o esquema de 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

LDAP Delete Entry falha quando a entrada de destino tem entradas filhas

  • Sintoma: Uma atividade LDAP Delete Entry 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 excluir uma entrada que tem 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 cima.
    • Se for necessário excluir uma subárvore inteira, implemente um script que identifique e exclua entradas de baixo para cima na árvore, usando RunOperation com a atividade LDAP Delete Entry para cada entrada.

LDAP Search Entry: A expressão de filtro diferencia maiúsculas de minúsculas em alguns servidores

  • Sintoma: Uma atividade LDAP Search Entry não retorna resultados ou retorna um erro, mesmo que as entradas consultadas existam no diretório.
  • Possível causa: Alguns servidores LDAP exigem que nomes de atributos em expressões de filtro correspondam ao caso exato usado pelo esquema desse servidor. A expressão de filtro pré-preenchida pelo Studio usa maiúsculas e minúsculas de título 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 Search Entry, revise o campo Filter Expression pré-preenchido.
    2. Ajuste o caso dos nomes de atributos para corresponder ao que o servidor LDAP de destino espera. Por exemplo, altere ObjectClass para objectClass se o servidor exigir minúsculas.
    3. Consulte a documentação ou definição de esquema do seu servidor LDAP para as convenções de nomenclatura de atributos necessárias.

Conectores Microsoft

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

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

Microsoft Dynamics 365 Business Central v2: nomes de tipo incompatíveis com metadados

  • Sintoma: Operações usando o conector Microsoft Dynamics 365 Business Central v2 falham com erros indicando que nomes de tipo no payload 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 no payload 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 Update do Microsoft Dynamics 365 Business Central v2.
    2. Em Configurações opcionais, ative Set OData type on payload.
    3. Salve a atividade e teste novamente 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 Query do Microsoft Entra ID, o campo onPremisesExtensionAttributes e seus campos de atributo de extensão filho (por exemplo, extensionAttribute1 até extensionAttribute15) não aparecem no seletor Object Fields na etapa 3 e não podem ser selecionados como condições de filtro de cláusula condicional.
  • Possível causa: onPremisesExtensionAttributes é um objeto de tipo complexo (aninhado). O seletor Object Fields da etapa 3 expõe apenas campos de tipo de dados primitivos; 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 valores de atributo de extensão, mapeie de onPremisesExtensionAttributes e seus campos filho na transformação.

Atividade Microsoft Entra ID Update: campos DateTime rejeitados com incompatibilidade de tipo Edm.String

  • Sintoma: Uma atividade Update do Microsoft Entra ID falha com:
Um valor foi encontrado com um nome de tipo incompatível com os metadados.
O valor especificou seu tipo como 'Edm.String', mas o tipo especificado nos metadados é '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 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 Update do Microsoft Entra ID.
    2. Na etapa 1, expanda Configurações opcionais e ative Definir tipo OData no payload.
    3. Salve a atividade, reimplante e execute novamente a operação.

Consulta do Microsoft Entra ID: "Unsupported or invalid query filter clause" em propriedades filtradas

  • Sintoma: Uma atividade Query 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.

  • Possível causa: A filtragem em certas propriedades do Microsoft Entra ID (como companyName e createdDateTime) usa a capacidade de consulta avançada da API Microsoft Graph, que requer $count=true na string de consulta. Sem ela, 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 usada na etapa 3:
    • Aba Básica: Marque a caixa de seleção Incluir Contagem. Isso adiciona $count=true à consulta automaticamente.

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

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

Para a lista de propriedades que exigem 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 "Logon failed"

  • Sintoma: Operações usando o conector Microsoft Dynamics AX contra AX 2012 falham em tempo de execução, mesmo que o teste de conexão seja bem-sucedido 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 AX 2012 não está definido com o valor correto. A autenticação AX 2012 requer que o Nome do Domínio seja a extensão de nome de domínio DNS (por exemplo, yourcompany.com), 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 logon, mesmo quando o teste de conexão é bem-sucedido.

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

Conector NetSuite

Nota

NetSuite possui um guia de solução de problemas dedicado que aborda problemas adicionais de conexão, configuração de esquema, atividade e desempenho. Consulte Solução de problemas do NetSuite.

Criar, atualizar ou fazer upsert no NetSuite falha com "is not a legal value for Country"

  • Sintoma: Uma atividade NetSuite Criar, Atualizar ou Fazer upsert falha quando o valor de origem de um campo de país não corresponde a um valor enum 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

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

  • Resolução:
    • Na transformação que mapeia para o destino do NetSuite, traduza o valor de país de origem para o valor enum correspondente do NetSuite antes de escrever. Um dicionário de referência cruzada, uma instrução Case ou uma tabela de consulta funcionam para isso.
    • Crie a referência cruzada a partir do enum Country definido no WSDL SuiteTalk do NetSuite que seu conector está usando. Os valores válidos mudam entre versões do WSDL, portanto, sempre verifique em relação à versão do WSDL configurada atualmente na conexão.
    • Aplique a mesma abordagem a qualquer outro campo apoiado por um enum do NetSuite (por exemplo, State, Currency) onde os valores de origem ainda não correspondem ao enum do WSDL.

Conector OData

Conjuntos de entidades OData v2 falham ao carregar com "No entity sets found"

  • Sintoma: Configurar uma atividade 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 do agente 11.59, através da configuração de conexão Versão OData. Em agentes anteriores à versão 11.59, o conector suporta apenas OData V4, portanto, uma conexão apontada para um serviço OData V2 não consegue preencher a lista de objetos. A mesma falha ocorre na versão 11.59 ou posterior se Versão OData for deixada em V4 para um serviço OData V2.

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

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

  • Sintoma: Uma conexão OData com um ponto de extremidade Microsoft Dynamics 365 Finance and Operations retorna dados apenas da empresa padrão do usuário, portanto, registros de outras empresas estão faltando nos resultados.
  • Possível causa: Por padrão, um ponto de extremidade 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 entre empresas (expandido), uma cláusula de filtro entre empresas 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 salve e teste novamente:
?$filter=dataAreaId eq 'usrt'&cross-company=true

Para saber mais 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)

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

  • Resolução:
    1. Baixe ojdbc8.jar do site da Oracle (é necessária uma conta Oracle).
    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

Nota

O conector Salesforce possui um guia de solução de problemas dedicado que aborda autenticação, esquema, configuração de atividade, limite de registros e problemas de atividade em massa. Consulte Solução de problemas do conector Salesforce.

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

  • Sintoma: Após um agente privado ser reiniciado ou reinstalado, os eventos do conector Salesforce Events falham ao serem ativados, mesmo quando as credenciais de conexão estão corretas.
  • Possível causa: 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.
  • Resolução:
    1. Abra a configuração de conexão do Salesforce Events no Studio.
    2. Clique em Test 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 do Salesforce Events (Subscribe Event e as atividades Subscribe Insert, Update e Delete CDC Event) são esperados e não indicam um defeito do conector:

  • Eventos não podem ser ativados porque o número máximo de assinantes foi atingido. A instância do Salesforce limita o número de clientes simultâneos (assinantes). Quando esse limite é atingido, nenhum outro evento pode ser ativado. Reduza o número de assinantes ativos conectados à instância.
  • Símbolos de medição como $ e % estão faltando na resposta. Esses símbolos não são retornados, por design da API do Salesforce.
  • Campos não modificados são retornados como nulos em respostas de Change Data Capture (CDC). Para atividades de CDC, apenas 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 erros de validação, mas falha quando executada.
  • Possível causa: Operações que misturam esses tipos de atividade 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 de operação não sinalizam esse padrão como um erro em 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

  • Possíveis causas:

    • 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 anterior à atividade não define o campo de controle de confirmação.

  • 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 seu administrador SAP BASIS para revisar as atribuições de objeto de autorização do usuário.

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.

  • Possível causa: 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 capitalização incorreta (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 de usuário SAP e use esse.
    3. Teste a conexão no Studio para confirmar que a inicialização é bem-sucedida antes de reimplantar a operação.

Conector ServiceNow

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

  • Sintoma: Operações que usam o conector ServiceNow executam lentamente em dois cenários:

    • Em agentes privados, a primeira operação após a reinicialização do agente pode levar vários minutos; as 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 jusante.

  • Possível causa: 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.

  • Resolução:
    • Em um agente privado, atenue a lentidão pós-reinicialização adicionando getcolumnsmetadata=onUse às Opções Avançadas do endpoint do ServiceNow. Esta 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 ServiceNow. O conector HTTP v2 não armazena metadados em cache e evita o atraso de reconstrução.

Conector Shopify

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

  • Sintoma: Após alterar a versão da API em uma conexão Shopify, uma ou mais atividades do Shopify retornam erros ou se comportam de forma inesperada, e um objeto ou subobjeto configurado parece ter mudado.
  • Possível causa: O Shopify lança novas versões de API trimestralmente e descontinua versões mais antigas após 12 meses. Quando você muda para uma versão de API diferente, objetos ou subobjetos que não estão disponíveis na nova versão podem não ser mais selecionáveis, causando a alteração da seleção configurada da atividade quando a configuração é atualizada.
  • Resolução:
    1. Após alterar a versão da API do Shopify na conexão, abra cada configuração de 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 objeto e subobjeto para confirmar que refletem sua intenção sob a nova versão.
    4. Atualize as seleções que mudaram para os objetos de substituição corretos.
    5. Reimplante e reteste as operações afetadas.
    6. Para informações sobre cronogramas de descontinuação de versão da API do Shopify, consulte o changelog do Shopify.

Conector Snowflake

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

  • Sintoma: Operações que se conectam ao Snowflake usando o tipo de autenticação Senha (Descontinuada) começaram a falhar após funcionar 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 Chave-Par, e configure a conta de usuário do Snowflake para corresponder.

Snowflake: Instância de desenvolvedor está dormindo, tabelas de metadados não estão sendo preenchidas

  • Sintoma: Ao configurar uma atividade do Snowflake, a lista de objetos disponíveis não é preenchida ou aparece vazia, mesmo que o teste de conexão seja bem-sucedido.
  • Possível causa: Instâncias do Snowflake Developer entram em estado de dormência quando não são acessadas há algum tempo. Embora o teste de conexão possa ser bem-sucedido em uma instância dormindo, ela pode não retornar metadados de tabelas e objetos.
  • Resolução:
    1. Faça login na interface web do Snowflake para acordar a instância.
    2. Reabra a conexão do Snowflake no Studio e clique em Test para testar novamente as credenciais.
    3. Reabra a configuração da atividade para atualizar a lista de objetos disponíveis.

Snowflake Query: Incompatibilidade de maiúsculas e minúsculas do nó raiz de esquema simples causa erro ProcessFlatStream

  • Sintoma: Uma atividade Query do Snowflake que usa um esquema simples 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 do Snowflake retorna o nome da tabela em minúsculas na resposta XML. Quando o Studio gera um esquema simples a partir da consulta, o nome do nó raiz é criado em maiúsculas. A incompatibilidade de maiúsculas e minúsculas entre o nó raiz do esquema (maiúsculas) e o nó raiz da resposta XML (minúsculas) causa falha no processamento do fluxo simples.

  • Resolução: Escolha uma das seguintes opções:
    • No esquema simples, altere o nome do nó raiz para 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 simples construído manualmente. O esquema espelho deriva sua estrutura diretamente da resposta do conector e não apresenta essa incompatibilidade de maiúsculas e minúsculas.

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

  • Sintoma: Uma atividade Merge do Snowflake configurada em um estágio externo mostra um esquema de solicitação sem os campos stageName e fileContent. A mesma atividade configurada em 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 no 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 orientam esse upload.
  • Resolução:
    • Quando a atividade tem como alvo um estágio externo, certifique-se de que os arquivos de dados já estão presentes no local de armazenamento em nuvem que o estágio referencia. A atividade Merge lê esses arquivos diretamente; nenhum campo fileContent é necessário.
    • Quando você realmente precisa enviar conteúdo de arquivo da operação, configure a atividade Merge para usar um estágio interno. O esquema então expõe stageName e fileContent.

Snowflake Insert ou Merge: Erros de sintaxe SQL de caracteres especiais

  • Sintoma: Uma atividade Insert ou Merge 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 no payload SQL. A aspa não escapada encerra 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 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 Escape special characters. Isso escapa automaticamente as aspas simples nos payloads das atividades Insert e Invoke Stored Procedure. Para atividades Merge, ou como alternativa para Insert, use SQLEscape no mapeamento de transformação para escapar as aspas simples nos valores de campo afetados antes de chegarem à atividade.
    • Para nomes de coluna contendo caracteres especiais: Confirme que Use quote for Snowflake identifiers está ativado na conexão (ativado por padrão).

Snowflake: Erro de espaço de heap Java ao consultar grandes conjuntos de dados

  • Sintoma: Uma atividade Query 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 desta forma porque envolve o erro Java subjacente, que aparece mais abaixo no rastreamento de pilha:

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

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

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

  • Resolução: Para grandes volumes de consultas, use o conector Database com um driver JDBC do Snowflake em vez do conector Snowflake. O conector Database não armazena o conjunto de resultados completo na memória, portanto pode lidar com volumes de consultas muito maiores. Instale o driver JDBC do Snowflake no agente privado e configure uma conexão Database que o utilize. No agente 12.x e posterior, essa conexão Database também precisa de enableArrowResultFormat=false&jdbc_query_result_format=json em sua string de conexão; consulte Snowflake: Operations fail on agent 12.x.

    Se precisar permanecer no conector Snowflake, qualquer um dos seguintes pode reduzir a pressão de memória, embora nenhum seja garantido 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 JVM do Tomcat no agente privado (consulte Tomcat heap memory).

Snowflake: Operações falham no agente 12.x

  • Sintoma: Em um agente privado executando a versão 12.x, operações que consultam o Snowflake através de um driver JDBC do Snowflake (uma conexão Database 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, por exemplo:
JDBC driver internal error: exception creating result java.lang.ExceptionInInitializerError at net.snowflake.client.jdbc.internal.apache.arrow.memory.unsafe.UnsafeAllocationManager

ou:

JDBC driver internal error: exception creating result java.lang.NoClassDefFoundError: Could not initialize class net.snowflake.client.jdbc.internal.apache.arrow.memory.RootAllocator
  • Possível causa: Por padrão, o driver JDBC do Snowflake retorna resultados de consultas no formato Apache Arrow, que não é compatível com a versão 12.x do agente e posteriores. Consulte o artigo de solução de problemas do Snowflake sobre esse erro de módulo Java para mais detalhes. O teste de conexão não retorna um conjunto de resultados, então ainda passa enquanto as consultas falham. Atualizar a versão do driver JDBC não resolve o problema.

  • Resolução: Defina enableArrowResultFormat como false e jdbc_query_result_format (ou JDBC_QUERY_RESULT_FORMAT) como json para que o driver retorne resultados em JSON em vez de Arrow:

    • Conector de banco de dados: Adicione enableArrowResultFormat=false&jdbc_query_result_format=json à string de conexão do Snowflake, no campo Parâmetros adicionais da string de conexão (ou no campo String de conexão, se Usar string de conexão estiver selecionado).
    • Conector Snowflake: Em Configurações opcionais > Propriedades personalizadas de conexão, adicione enableArrowResultFormat com um valor de false. Uma linha JDBC_QUERY_RESULT_FORMAT com um valor de JSON já está presente lá por padrão.

    Em seguida, salve, teste novamente a conexão e execute a operação novamente.

    Em um agente privado, você pode aplicar a correção no nível da JVM para que não seja necessário repetir por conexão, adicionando --add-opens=java.base/java.nio=ALL-UNNAMED a CATALINA_OPTS:

    Adicione a seguinte linha a /opt/jitterbit/tomcat/bin/setenv.sh:

    export CATALINA_OPTS="$CATALINA_OPTS --add-opens=java.base/java.nio=ALL-UNNAMED"

    Em seguida, reinicie o agente.

    1. Abra o Editor do Registro e localize a seguinte chave:

      HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java

    2. Abra a subchave Options.

    3. No campo Dados do valor, adicione --add-opens=java.base/java.nio=ALL-UNNAMED às opções Java existentes.
    4. Clique em Ok.
    5. Reinicie o agente.

    Use uma das seguintes estratégias para aplicar a configuração:

    1. Atualize o Dockerfile e recrie a imagem do Docker:

      docker build -t my-agent .

    2. Inclua no comando Docker run:

      docker run -e CATALINA_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED" my-agent

    3. Inclua em docker-compose.yml e reinicie o contêiner:

      environment:
  - CATALINA_OPTS=--add-opens=java.base/java.nio=ALL-UNNAMED

Conector SOAP

Erro de implantação do SOAP: "No WSDL with locator"

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

    Failed to deploy - Internal Error: No WSDL with locator

  • Possíveis causas:

    • O WSDL foi removido, reimportado ou sua referência interna foi quebrada, portanto 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 a implantação de um projeto podia deletar arquivos WSDL ainda em uso. O lançamento 12.9 previne a exclusão, mas um WSDL deletado antes disso ainda precisa ser re-enviado.

  • Resolução:

    1. Re-envie 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), re-envie o WSDL, revise as configurações de Port e Select methods e clique em Save Changes.
      • Para uma atividade SOAP Request ou SOAP Response de API, abra a atividade e re-envie o WSDL na etapa 1 de sua configuração.

    2. Revise todas as transformações que herdam esquemas do WSDL re-enviado e regenere-as se necessário.

    3. Reimplante o projeto.

    4. Se o projeto tiver múltiplos WSDLs e não estiver claro qual 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.
  • Possível causa: 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 do WSDL e re-importe o WSDL na conexão SOAP.

Conector SOAP reescreve prefixos e estrutura de namespace XML

  • 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 prefixos de namespace diferentes do 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 envie um esquema de solicitação personalizado) e mapeie a string do envelope SOAP construída para o campo body desse esquema. O conector envia o valor 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 no campo responseContent do esquema de resposta padrão da atividade.

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

Conector VTEX

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

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

    You don't have permission to access this resource

  • Possível causa: O usuário VTEX ou a chave de aplicação associada à conexão não possui 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 aos dados.

  • Resolução:
    1. No portal administrativo do VTEX, abra o perfil de acesso atribuído ao usuário ou à chave de aplicação que o Jitterbit está usando.
    2. Confirme que o perfil de acesso inclui o recurso License Manager com acesso ao recurso Get account by identifier.
    3. Salve o perfil e teste novamente 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 versão WSDL 42.0 ou 42.1 falham ao acessar os serviços web Human_Resources ou Resource_Management.
  • Possível causa: A WSDL v42.0 é conhecida por retornar erros para os serviços Human_Resources (v42.0) e Resource_Management (v42.0). A WSDL v42.1 é conhecida por retornar erros para o serviço Human_Resources (v42.1). Esses são problemas conhecidos específicos dessas versões de WSDL.
  • Resolução:
    1. Na configuração de conexão do Workday, altere a versão WSDL para 41.x ou 43.0 ou posterior para operações que usam 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: Teste de conexão falha com "A tarefa enviada 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.

    Esse erro pode ocorrer com os tipos de autenticação Basic Auth e 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 a ISU pode não ter, enquanto as operações de integração reais chamam serviços diferentes.

  • Possíveis causas:

    • O Integration System User (ISU) não foi atribuído ao grupo de segurança Setup Administrator no Workday. A chamada de teste de conexão do conector é rejeitada se a ISU não tiver essa associação de grupo de segurança.
    • O campo Workday Host contém um valor incorreto. Um host incorreto causa falha na conexão antes da tentativa de autenticação.

  • Resolução:

    1. Verifique se o valor de Workday Host na configuração de conexão está correto. O host deve ser a URL base do seu tenant Workday (por exemplo, https://wd5-impl-services1.workday.com/). Você pode confirmar o valor correto na página View API Client do Workday.
    2. Na instância do Workday, abra a tarefa Assign Users to User-based Security Group, selecione Setup Administrator e confirme que a ISU está listada em System Users. Se não estiver, adicione a ISU. Para obter as etapas completas, consulte Pré-requisitos.
    3. Confirme que a tarefa Configure Web Service Security também foi concluída para a ISU, conforme descrito na página Pré-requisitos.
    4. Teste novamente a conexão.