Solução de problemas de operações no Jitterbit Studio

Este guia abrange erros e comportamentos inesperados ao construir, implantar e executar operações no Jitterbit Studio, incluindo operações, transformações, scripts e funções, além da validação em tempo de design. Se você está solucionando problemas de um conector específico, consulte Solução de problemas de conectores.

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

Passos de diagnóstico

Esses passos se aplicam a quase qualquer falha de operação e são o ponto de partida recomendado antes de investigar um erro específico.

Testar a conexão

Para qualquer operação usando conectores, na conexão, clique no botão Testar para garantir que a conexão seja bem-sucedida.

Para conectores baseados em Connector SDK implantados em operações executadas em agentes privados, clicar em Testar também garante que a versão mais recente do conector seja baixada para o agente (a menos que a política de organização Desativar Atualização Automática do Conector esteja habilitada).

Verifique os logs de operação

Verifique os logs de operação para qualquer informação registrada durante a execução.

Dependendo do tipo de agente, dados adicionais de log estão disponíveis:

• Ative o log de depuração de operação (para agentes em nuvem ou para agentes privados).
• Ative o log detalhado do conector (apenas agentes privados).
• Verifique os logs do agente (apenas agentes privados).

Isolar falhas específicas do agente

Se uma operação falhar em alguns agentes, mas for bem-sucedida em outros dentro do mesmo grupo de agentes privados, use a opção Executar em agente dedicado para direcionar a operação a um agente específico. Isso permite reproduzir e investigar a falha no agente problemático sem tirar o restante do grupo do ar.

Para configurar essa opção, abra as configurações da operação, selecione a aba Opções e configure Executar em agente dedicado.

Execução e agendamento de operações

Operações presas no estado Enviado ou Executando

• Sintoma: Uma operação não é concluída como esperado. Ela permanece em um estado Enviado ou Executando e nunca avança, ou é cancelada com a mensagem:

  Long running operation canceled by System
  

  O cancelamento pode ocorrer após a operação ter sido executada por um tempo ou logo após seu início, e não reflete necessariamente quanto tempo a operação realmente durou.

• Causas possíveis:

  • Um agente privado perdeu a conexão com a plataforma Harmony e não conseguiu relatar o status da operação. A plataforma continua a mostrar a operação como Executando e pode cancelá-la como aparentemente travada, mesmo quando a operação foi concluída no agente. Isso pode afetar operações que normalmente terminam em segundos.
  • A operação foi concluída, mas seu status final não foi reportado de volta para a Harmony, então continua a aparecer como Executando até que atinja o tempo limite.
  • O grupo de agentes está sob alta carga e está lento para iniciar ou atualizar operações em fila.
  • A operação está presa especificamente em Enviado: a mensagem de execução foi enfileirada, mas nenhum agente no grupo a aceitou, porque os agentes estão offline, não saudáveis ou não têm capacidade livre para aceitar novas operações (por exemplo, todas as threads de trabalho estão ocupadas).

• Resolução:

  • Para agentes privados, confirme se o agente tem um status Em Execução na página Agentes no Console de Gerenciamento, revise os logs do agente privado para problemas de conexão e verifique se a conexão de rede entre o agente e a plataforma Harmony está estável.
  • Revise os logs de operação para confirmar o que aconteceu durante a execução. A mensagem de cancelamento pode aparecer mesmo para operações que foram executadas apenas brevemente, portanto, não indica necessariamente uma operação que realmente demorou. Os logs também podem revelar um erro específico a ser resolvido, como um 401 Unauthorized (verifique as credenciais) ou um 429 Too Many Requests. Um 429 de um endpoint de destino pode ser amenizado reduzindo a taxa de requisições ou adicionando lógica de repetição; um 429 do gateway de API gerenciado pela Jitterbit é seu limite de plataforma de 200 requisições por minuto, portanto, distribua as chamadas ao longo do tempo ou execute as APIs afetadas em agentes privados.
  • Mantenha os agentes privados em uma versão atual. Versões mais recentes dos agentes melhoram a resiliência do agente e reduzem o cancelamento prematuro das operações.
  • Tente cancelar as operações afetadas. O cancelamento está disponível para operações com status Enviado, Recebido, Pendente ou Em Execução na página Runtime do Console de Gerenciamento, na tabela de logs de operação, ou no status de execução de uma operação na tela de design.
  • Se a operação afetada estiver programada e nunca iniciar, veja Operações programadas não executando.
  • Se as operações não puderem ser canceladas, se o problema ocorrer novamente ou se muitas operações forem afetadas ao mesmo tempo, entre em contato com o suporte da Jitterbit, pois esses casos podem exigir resolução do lado do servidor.

Operações agendadas não executando

• Sintoma: Uma operação configurada com um cronograma de operação não é executada no horário agendado, ou é despachada, mas permanece em um estado Pending ou Received.
• Causas possíveis:
  • O cronograma foi atribuído à operação no Studio, mas o projeto não foi implantado. Cronogramas atribuídos no Studio não entram em vigor até que o projeto seja implantado.
  • O cronograma está desativado.
  • Existe uma configuração de fuso horário incorreta nas configurações do cronograma.
  • Para agentes privados, o serviço de agendamento não está em execução.
  • O agente associado ao ambiente está offline ou não saudável.
  • As alterações implantadas em um projeto não foram totalmente sincronizadas com o agente.
  • O grupo de agentes está saturado em recursos. Um acúmulo de operações de longa duração ou uso sustentado alto de CPU ou memória pode impedir que um grupo de agentes processe operações agendadas a tempo.
• Resolução:
  • Confirme que o projeto foi implantado desde que o cronograma foi atribuído à operação.
  • Confirme que o cronograma está ativado. Cronogramas podem ser ativados ou desativados apenas na página Projetos do Console de Gerenciamento, nas abas Operações e Cronogramas.
  • Revise a configuração do cronograma, prestando atenção especial à configuração do fuso horário. Para detalhes, veja Fusos horários de operações.
  • Para agentes privados, verifique se o agente está online e saudável na página Agentes do Console de Gerenciamento e confirme se o serviço de agendamento está em execução na máquina do agente. No Windows, verifique se o Jitterbit Scheduler e o Jitterbit Scheduler Service estão em execução no Gerenciador de Tarefas. No Linux e Docker, use o comando jitterbit status.
  • Reimplante o projeto para forçar a re-sincronização do cronograma com o agente.
  • Se as operações estiverem presas em um estado Pending, cancele-as pela página Runtime do Console de Gerenciamento e reinicie o serviço do agente.
  • Se as falhas de cronograma estiverem correlacionadas com a carga, reduza o número de operações de longa duração em execução simultaneamente. Em agentes privados, também revise o uso de CPU e memória e equilibre as operações agendadas com a capacidade do agente (um agente privado pode executar até duas vezes sua contagem de núcleos de CPU em operações simultâneas).
  • Se uma operação agendada for despachada, mas depois travar em vez de nunca iniciar, veja Operações presas em estado Submitted ou Running.

O dicionário ou variável global está vazio após uma operação ser executada de forma assíncrona

• Sintoma: Um dicionário ou variável global populado dentro de uma operação filha está vazio ou mantém seu valor anterior quando a operação pai o lê após invocar a filha de forma assíncrona.
• Causa possível: Quando uma operação é invocada de forma assíncrona (o tipo de execução da ferramenta Invocar Operação definido como Assíncrono, ou RunOperation chamado com runSynchronously definido como false), a filha é executada em uma thread separada e a pai continua sem esperar por ela. Variáveis globais e dicionários são passados para a filha por valor em vez de por referência e não são seguros para threads, portanto, as alterações feitas na filha não são refletidas de volta na pai. A pai também pode ler o valor antes que a filha termine.
• Resolução:
  • Se a pai depende dos valores que a filha produz, invoque a filha de forma síncrona (o tipo de execução da ferramenta Invocar Operação definido como Síncrono, ou RunOperation executado de forma síncrona, que é o padrão) para que a filha complete e suas alterações na variável global sejam herdadas pela pai.
  • Para compartilhar dados entre operações que devem ser executadas de forma independente, persista-os com funções de cache (WriteCache e ReadCache) em vez de depender de um dicionário ou variável global entre threads. Por padrão, as funções de cache são limitadas a 100 chamadas combinadas por minuto por organização.
  • Inserir um atraso fixo (por exemplo, com a função Sleep) adiciona latência e não garante que a filha tenha terminado; execute a operação de forma síncrona em vez disso.
• Relacionado: Para o comportamento equivalente em operações multi-threaded em blocos, veja Atualizações de variáveis perdidas em operações multi-threaded em blocos.

Falhas de conexão e autenticação

Certificado do Salesforce: incompatibilidade de Nome Alternativo do Sujeito (SAN)

• Symptom: A Salesforce connection to a sandbox or an org with Enhanced Domains enabled fails with:

  Certificate for <url> doesn't match any of the subject alternative names
  

• Possible causes:

  • The certificate does not include the Salesforce MyDomain or sandbox URL in its Subject Alternative Names.
  • The Sandbox checkbox in the Salesforce connection settings is not correctly toggled.

• Resolution:

  • Inspect the certificate's SAN entries using OpenSSL: openssl x509 -in cert.crt -text -noout. Confirm the Subject Alternative Name section includes your Salesforce MyDomain URL.
  • In the Salesforce connection settings in Studio, verify the Sandbox checkbox is correctly set for your target org.
  • If the Salesforce URL is absent from the SANs, regenerate the certificate to include the specific domain.
  • If the same connection succeeds on a cloud agent group but fails on a private agent, the cause may instead be a missing SNI extension in the agent's TLS handshake. See Salesforce sandbox connection fails with certificate mismatch.

Falha na conexão do banco de dados do agente privado (TranDb)

• Sintoma: As operações falham com erros que fazem referência ao banco de dados interno PostgreSQL do agente privado (TranDb), por exemplo Falha ao conectar ao banco de dados de back-end 'TranDb' ou FATAL: query_wait_timeout.
• Causa e resolução: Este é um problema em nível de agente com as conexões do banco de dados interno do agente privado. Consulte as falhas de conexão do TranDb no guia de solução de problemas do agente para as causas e resolução.

O certificado do cliente não carrega em agentes privados Linux

• Sintoma: Uma operação que faz uma chamada de serviço web mútua-TLS (certificado do cliente) falha em tempo de execução em um agente privado Linux, com um erro como:

  Problem with the local SSL certificate. Unable to set private key file: '<path>.key' type PEM.
  

  O certificado é carregado com sucesso no Studio, mas a operação falha quando é executada. A mesma configuração pode ter funcionado anteriormente em um agente privado Windows.

• Causas possíveis:

  • O usuário do sistema operacional que executa o agente Jitterbit não tem permissão de leitura para o arquivo da chave privada ou seus diretórios pai.
  • Um módulo de segurança do Linux, como SELinux ou AppArmor, está bloqueando o acesso do agente ao arquivo da chave privada.

• Resolução:

  • Certifique-se de que a conta que executa o agente Jitterbit tenha acesso de leitura ao arquivo da chave privada e a todos os diretórios pai.
  • Verifique se o SELinux ou AppArmor está restringindo o acesso ao arquivo da chave, e ajuste a política ou o contexto do arquivo conforme necessário.

Erros de transformação e dados

Elementos XML não suportados (CDATA) incorporados em JSON

• Sintoma: Seções de dados de caractere (CDATA) não são suportadas em XML incorporado dentro de JSON passado por uma transformação. Quando presentes, o seguinte erro aparece no log de operações:

  Transformation failed. Error: The operation "Operation" failed.
  Error: Failed to convert XML file to JSON.
  org.jitterbit.integration.server.engine.EngineSessionException: org.xml.sax.SAXParseException ...
  

• Solução: Use um script Jitterbit para Substituir os caracteres &, <, >, ' e " dentro da seção CDATA, incluindo os delimitadores CDATA (<![CDATA[ ... ]]>), por seus equivalentes escapados (&, <, >, ', "). Se não for viável direcionar apenas a seção CDATA, a string XML inteira que a contém pode ser substituída.

  O seguinte exemplo é considerado inválido sem essas substituições:

  {
    "name": "Jitterbit",
    "data": "<xml><content><![CDATA[<greeting>Hello, world!</greeting>]]></content></xml>"
  }
  

A transformação falha quando um valor de string JSON excede o comprimento máximo

• Sintoma: Uma transformação que processa um grande valor de string JSON falha com um erro informando que a string excede o comprimento máximo permitido, por exemplo:

  Transformation failed. Error: Error Code: String value length (20054016) exceeds the maximum allowed (20000000, from StreamReadConstraints.getMaxStringLength())
  

  O rastreamento de pilha faz referência a StreamConstraintsException e ao analisador JSON do agente. Um gatilho comum é uma resposta HTTP v2 com Obter conteúdo da resposta em string base64 habilitado: A codificação Base64 aumenta o conteúdo binário (como um arquivo de áudio ou mídia), de modo que a string codificada pode exceder o limite mesmo quando o arquivo original é menor.

• Causa: O parser JSON do agente limita um único valor de string JSON a 20 MB (20000000 caracteres) por padrão. Uma resposta ou valor mapeado maior que isso falha enquanto o agente o analisa, antes que qualquer atividade subsequente (como um upload) seja executada.

• Resolução: Em um agente privado executando a versão 12.5 ou posterior, aumente o limite com a chave MaxStringLength na seção [JsonParser] do arquivo de configuração jitterbit.conf (por exemplo, defina como 50000000 para um limite de 50 MB), e então reinicie o agente. Esta chave está disponível na versão 12.5 do agente e posteriores, portanto, atualize o agente primeiro se ele estiver em uma versão anterior.

Caracteres especiais em esquemas JSON fornecidos pelo conector

• Sintoma: Quando uma transformação usa um esquema JSON herdado de uma atividade de conector adjacente, quaisquer caracteres especiais em um campo ou nome de nó do esquema são substituídos por sublinhados (_). Ao usar processamento JSON legado (o padrão para projetos criados antes do lançamento Harmony 11.48), isso pode fazer com que o endpoint retorne erros porque os nomes dos campos reais não correspondem mais ao que ele espera.

  Por exemplo, se a atividade fornecer um campo chamado location_ids[], ele é convertido para location_ids__. Se o endpoint ainda espera o nome original, pode retornar um erro como:

  "error_message": "{location_ids:expected String to be a Array}"
  

• Resolução:

  1. Confirme que um esquema JSON está sendo usado na atividade afetada. Esses esquemas têm um nó raiz chamado json:

     

  2. Ative a configuração de projeto Preservar nomes JSON configuração de projeto (requer versão do agente 11.48 ou posterior).

  3. Reconfigure, implemente e execute a operação.

  Importante

  Quando Preservar nomes JSON está habilitado em um projeto onde anteriormente estava desabilitado, o novo método de processamento se aplica apenas a operações e esquemas configurados após a habilitação da configuração. Operações e esquemas existentes continuam usando o processamento JSON legado. Para evitar inconsistências dentro de um projeto, reconfigure todas as operações e esquemas existentes após habilitar esta configuração.

  Para verificar o nome do campo sendo enviado para o endpoint, verifique o valor de jsonPropertyName nos dados de entrada ou saída da atividade com registro de depuração habilitado:

  

Esquemas espelhados com grupos de substituição

• Sintoma: Esquemas espelhados que usam grupos de substituição XML não são suportados. Usar um resulta em um erro em tempo de execução:

  Failed to initialize transformation "<transformation name>". Failed to expand the (source|target) tree for the path: <path to substitution head node>.
  

  Este erro também pode ocorrer por outros motivos, como importar um mapeamento de transformação com nós duplicados, e não indica necessariamente um problema com o grupo de substituição.

• Resolução: Se grupos de substituição forem a causa confirmada, limpe o esquema espelhado e recrie-o usando um método diferente (fazendo upload, criando um esquema personalizado, etc.).

Importar um mapeamento de transformação com nós duplicados falha com "nó não pode ser criado"

• Sintoma: Uma transformação cujo mapeamento foi importado de um arquivo que referencia nós duplicados falha em tempo de execução com um erro como:

  Failed to initialize transformation "<transformation name>". Failed to expand the target tree for the path: <path to node>. The node: <node name> cannot be created.
  

  O mapeamento pode parecer correto no designer de transformação, mesmo que a operação falhe ao ser executada.

• Causa possível: A importação de um arquivo de mapeamento que adicionou nós duplicados ao esquema de destino não aplicou a alteração correspondente à definição do esquema usada quando a operação é executada, deixando os dois fora de sincronia. Isso foi corrigido, mas uma transformação cujo mapeamento foi importado antes da correção ainda pode ser afetada.

• Resolução: Na transformação afetada, use Remover todos os mapeamentos abaixo deste nó no nó raiz para remover todos os mapeamentos, depois importe o arquivo de mapeamento novamente. Reimportar resincroniza a definição do esquema usada em tempo de execução com o mapeamento. Se o erro persistir, reconfigure a atividade que fornece o esquema, depois atualize o esquema na transformação.

Reprocessamento de esquema XML espelhado em projetos criados antes da versão 10.25

• Sintoma: Devido a mudanças nas versões do Harmony 10.25 e 10.27, projetos criados antes de 10.25 que usam esquemas XML espelhados podem se comportar de maneira diferente do esperado. Mapeamentos que usaram funções XML envolvendo namespaces (como SelectNodes) podem agora ser inválidos.

A diferença está no manuseio do prefixo de namespace:

• Antes de 10.25: Esquemas XML espelhados usavam o prefixo de namespace padrão xsi.

• 10.25 e posterior: Esquemas XML espelhados usam o prefixo de namespace qualificado ns. Campos não mapeados não são exibidos no esquema.

• Resolução: A partir da versão 10.27, importar um projeto cujos esquemas XML espelhados foram criados antes de 10.25 mantém o prefixo de namespace original, de modo que o esquema é idêntico ao quando foi criado. Para forçar uma atualização para o prefixo de namespace atual, regere o esquema atualizando-o ou reconfigurando a atividade que o fornece. Após a regeneração, revise todas as chamadas de função de namespace XML afetadas e atualize as referências de prefixo conforme necessário.

  Veja a comparação de esquemas XML anotados para uma ilustração da diferença entre os dois formatos.

Aviso de subelemento extra nos logs de operação

• Sintoma: Uma mensagem de subelemento extra nos logs de operação é um aviso, não um erro, e geralmente pode ser ignorada. Indica que a carga útil da API de um conector retornou mais nós ou campos do que estão definidos no esquema de dados da resposta.
• Resolução: Se você precisar capturar os dados adicionais, atualize o esquema para incluir os campos extras.

Saída de transformação convertida para 0 para campos de destino com um tipo de dado double

• Sintoma: Um campo de destino com um tipo de dado double no esquema recebe um valor de 0, mesmo que o script de mapeamento retorne um valor de string não vazio.
• Possível causa: Quando a transformação processa uma saída de script, ela força o resultado para o tipo de dado do campo de destino. Se o valor da string começa com um caractere não numérico (por exemplo, "string1"), nenhuma parte numérica pode ser extraída e o campo recebe o valor numérico padrão de 0. Em contraste, um valor como "1string" produziria 1, já que o dígito inicial é mantido.
• Resolução:
  1. Verifique a definição do esquema para o campo de destino afetado e confirme se seu tipo de dado é double ou outro tipo de dado numérico.
  2. Se o script de mapeamento puder retornar uma string não numérica, adicione validação explícita para garantir que apenas valores numéricos sejam mapeados para campos de destino numéricos, ou altere o tipo de dado do campo no esquema.

Campos mapeados em branco com esquemas de origem planos

• Sintoma: Campos de destino aparecem em branco na saída da operação, mesmo que os dados de origem contenham valores. Esse problema ocorre especificamente ao usar um esquema de origem plano. Não ocorre com esquemas espelhados ou esquemas JSON.
• Possível causa: O modo de transformação de streaming padrão processa registros de forma incremental, o que pode fazer com que campos mapeados não recebam valores quando usados com esquemas de origem planos.

• Resolução:

  1. Adicione um passo de script no início da operação que desabilite as transformações de streaming definindo jitterbit.transformation.auto_streaming como false:

     $jitterbit.transformation.auto_streaming = false;
     

  2. Implemente e execute novamente a operação. Para mais contexto sobre processamento de streaming e transformação, veja Processamento de transformação.

Nó de loop de destino mapeado para múltiplos nós de loop de origem

• Sintoma: Uma transformação é inválida ou falha ao implantar com:

  Mappings of a target loop node depend on more than one source loop node.
  

• Possível causa: Um nó de loop de destino possui mapeamentos de campo que referenciam dois ou mais nós de loop de origem diferentes. Cada nó de loop de destino pode iterar apenas sobre um único nó de loop de origem.

• Resolução:
  1. Abra a transformação e identifique o nó de loop de destino sinalizado no erro.
  2. Revise os mapeamentos sob esse nó para confirmar que todos os campos mapeados derivam do mesmo nó de loop de origem.
  3. Se dados de múltiplos nós de origem forem necessários, pré-processe ou mescle os dados de origem adicionais em um passo de script antes da transformação, para que um único nó de origem unificado alimente o loop de destino.
  4. Para mais detalhes sobre padrões de mapeamento válidos, veja Validade de mapeamento de transformação.

A transformação descarta registros duplicados quando a saída é hierárquica

• Sintoma: Uma transformação que lê uma fonte CSV e mapeia para um formato de saída hierárquico (como JSON) descarta silenciosamente registros duplicados. Registros com valores de campo idênticos aparecem apenas uma vez na saída, independentemente de quantas vezes ocorrem na fonte. A operação é concluída com sucesso, mas relata menos registros de destino do que registros de origem.
• Possíveis causas:
  • Ao converter dados de fonte plana para um formato de saída hierárquico, o mecanismo de transformação remove registros duplicados durante a normalização. Registros com valores idênticos após a análise são tratados como duplicados e apenas uma cópia é mantida.
  • Esse comportamento é específico para saída hierárquica. Quando o esquema de saída é plano, a normalização não é executada e todos os registros são gravados.
  • O mecanismo de transformação também remove espaços em branco no início e no final dos valores de campo CSV por padrão. Registros que diferem apenas por espaços em branco no início ou no final tornam-se idênticos após a remoção e estão sujeitos à mesma deduplicação.
• Resolução:
  • Ative o particionamento nas opções de operação. O particionamento processa registros em lotes, o que contorna a normalização e preserva todos os registros, incluindo duplicados.
  • Use um esquema de saída plano na transformação em vez de um hierárquico. A normalização não se aplica à saída plana, portanto, todos os registros são preservados.
  • Desative a normalização definindo uma variável Jitterbit em um passo de script antes da transformação. Para transformações plano-para-plano, defina jitterbit.transformation.disable_normalization como true. Para transformações plano-para-XML, defina jitterbit.transformation.flat_to_xml.disable_normalization como true (requer agente 11.58 ou posterior). Ambas as variáveis podem afetar outras transformações na mesma operação, portanto, teste a alteração cuidadosamente.
  • Se os duplicados forem causados especificamente por diferenças de espaços em branco, defina jitterbit.source.preserve_char_whitespace como true em um passo de script antes da transformação. Isso preserva os espaços em branco durante a análise, de modo que os registros afetados permaneçam distintos.

IDs numéricos longos estão corrompidos na saída da transformação

• Sintoma: Um valor numérico longo (por exemplo, um número de rastreamento, número de conta ou ID externo) é enviado para o destino com o valor errado. O número é grande demais para caber no tipo numérico implícito usado durante o mapeamento, então ele transborda e produz um valor incorreto no destino.
• Possível causa: O campo de origem ou destino é tipado implicitamente como um tipo de dado numérico cujo intervalo não pode conter o valor completo, causando um transbordamento durante a conversão.
• Resolução:
  • Na transformação, defina o tipo de dado do campo de destino afetado como String em vez de um tipo numérico. IDs longos que não são usados em operações aritméticas devem ser tratados como strings.

  • Se o campo de origem também for tipado numericamente, converta o valor explicitamente com String antes de mapeá-lo:

    String($source.numericId)
    

A saída da transformação JSON omite campos null e de string vazia

• Sintoma: Uma transformação JSON descarta campos cujo valor é null ou uma string vazia ("") da carga útil de saída, mesmo que esses campos estejam explicitamente mapeados. O sistema de destino recebe uma carga útil que não inclui os campos omitidos, o que pode causar erros de validação a montante quando o destino requer que os campos estejam presentes.
• Possível causa: O processador de saída JSON omite campos com valores null ou strings vazias por padrão.
• Resolução:
  • Em um passo de script a montante da transformação, defina jitterbit.target.xml.include_nil_attribute como true. Na versão do agente 11.37 ou posterior, isso inclui valores null e strings vazias na saída JSON, correspondendo à entrada. (Apesar do xml em seu nome, essa variável se aplica a destinos JSON.)
  • Se você precisar de controle total sobre quais campos aparecem na carga útil, construa o corpo JSON em um passo de script usando concatenação de strings e envie-o através de um conector HTTP v2 com um corpo de solicitação sem esquema.

Campos mapeados vazios se tornam xsi:nil="true" e invalidam uma solicitação XML ou SOAP

• Sintoma: Em uma transformação XML ou SOAP, um campo mapeado com um valor vazio é emitido como um elemento nil, e o endpoint de destino rejeita a solicitação. Por exemplo, um mapeamento de número de telefone vazio produz:

  <ns1:Phone_Number xsi:nil="true"/>
  

  Alguns endpoints (por exemplo, serviços SOAP do Workday) tratam isso como inválido e retornam um erro.

• Causa: Por padrão, quando um mapeamento para um nó de destino resulta em um valor nulo ou vazio, a transformação inclui o nó, mas o marca como nil (xsi:nil="true"). Isso é controlado por jitterbit.target.xml.include_null_xml, cujo padrão é true.

• Resolução: Em um passo de script antes da transformação, defina $jitterbit.target.xml.include_null_xml = false para remover completamente os nós com um valor nulo ou vazio da saída. Se, em vez disso, o nó deve estar presente como um elemento vazio, use as variáveis relacionadas target Jitterbit jitterbit.target.xml.include_empty_xml e jitterbit.target.xml.include_nil_attribute, que controlam se valores vazios e nulos são incluídos na saída.

Erros de script e função

Funções de arquivo: A operação continua após falha de ArchiveFile ou ReadFile

• Sintoma: Uma operação é concluída com um status de sucesso, mas os arquivos não foram arquivados ou os dados não foram lidos conforme esperado. Nenhum erro aparece no resultado da operação, apenas um aviso no log da operação.
• Causa possível: ArchiveFile e ReadFile têm comportamento de falha suave: se qualquer uma das funções falhar, o script atual é abortado e um aviso é adicionado ao log da operação, mas a operação em si não falha e os passos subsequentes continuam. A partir da versão 12.5 do agente, um caso é uma exceção: ArchiveFile chamado com deleteSource definido como true lança um erro capturável quando o arquivo de origem não pode ser excluído, em vez de falhar silenciosamente.
• Resolução:
  • Verifique os logs da operação em busca de mensagens de aviso quando uma operação é bem-sucedida, mas a saída de arquivo esperada está faltando.
  • Se o script deve parar em caso de falha de função de arquivo, envolva a chamada em uma função Eval e chame RaiseError explicitamente para promover o aviso a uma falha de operação.

ReadFile: leituras parciais com conteúdo de arquivo binário

• Sintoma: Um script usando ReadFile para ler um arquivo binário (como um ZIP ou PDF) retorna dados incompletos ou corrompidos.
• Causa possível: ReadFile não é confiável com conteúdo de arquivo binário e normalmente lê apenas uma parte desses arquivos.
• Solução: Use Base64EncodeFile em vez de ReadFile para ler o conteúdo completo de um arquivo binário como uma string codificada em Base64.

Falha ao ler conteúdo de ReadFile com bytes não-UTF-8 quando mapeado em um payload XML ou JSON UTF-8

• Sintoma: Uma transformação que mapeia o conteúdo bruto de arquivo lido com ReadFile (por exemplo, um arquivo EDI bruto) em um campo de destino XML ou JSON UTF-8 falha durante a conversão XML ou JSON. Substituir o valor mapeado por uma string codificada permite que a operação seja concluída, o que confirma que o conteúdo bruto é o gatilho. Tentativas de remover o caractere problemático usando seu ponto de código Unicode (por exemplo, Replace($readFile, HexToString("2026"), "~") para a reticência U+2026) não correspondem, e chamar StringToHex no conteúdo com suporte Unicode habilitado gera:

  not a UTF-8 string, byte not in range: 13
  

• Causa: O conteúdo do arquivo contém um byte que não é válido UTF-8 (por exemplo, o byte único 0x85, que alguns arquivos EDI usam como terminador de segmento). Este byte bruto não é o mesmo que a codificação UTF-8 de múltiplos bytes de um caractere Unicode semelhante (a reticência U+2026 é codificada como três bytes), portanto, uma substituição direcionada ao ponto de código Unicode nunca corresponde. Com jitterbit.scripting.hex.enable_unicode_support definido como true, as funções hex interpretam o conteúdo como UTF-8 e falham no byte inválido.

• Resolução: Combine e substitua o byte bruto com suporte a hex Unicode desativado, para que HexToString opere em bytes brutos em vez de caracteres UTF-8:

  $jitterbit.scripting.hex.enable_unicode_support = false;
  $badByte = HexToString("85");
  $readFile = Replace($readFile, $badByte, "~");
  

  Ajuste o valor hex (85) para o byte reportado por StringToHex($readFile), e a string de substituição (~) conforme necessário, e então mapeie o valor sanitizado.

FlushFile / FlushAllFiles: Erro quando o arquivo de destino já existe

• Sintoma: Um script falha ao tentar gravar um arquivo em um destino que já contém um arquivo com o mesmo nome.
• Possível causa: FlushFile e FlushAllFiles (e por extensão ArchiveFile) geram um erro se um arquivo com o nome de destino já existir no local.
• Resolução:
  • Adicione uma chamada de DeleteFile ou DeleteFiles antes da operação de gravação para remover o arquivo existente.
  • Alternativamente, use um nome de arquivo dinâmico que inclua um carimbo de data/hora ou identificador único para evitar colisões.

DeleteFiles: Erro quando o caminho de origem não pode ser encontrado

• Sintoma: Um script usando DeleteFiles falha com um erro quando o caminho ou diretório de origem especificado não pode ser encontrado. (Um filtro que não corresponde a nenhum arquivo retorna 0 em vez de um erro.)
• Possível causa: Se o caminho de origem não puder ser encontrado, DeleteFiles gera um erro em vez de retornar silenciosamente. Isso pode causar falhas inesperadas na operação quando o arquivo a ser excluído não existe.
• Resolução: Envolva a chamada de DeleteFiles em uma função Eval para capturar o erro e tratá-lo sem falhar a operação.

GetJSONString: Execução interrompida em caminho inválido

• Sintoma: Um script que chama GetJSONString falha quando o caminho fornecido não é resolvido no JSON (por exemplo, o nó está ausente ou um array está vazio). O erro é genérico e não identifica o caminho como a causa; quando a operação é invocada através de uma API, pode aparecer como um enganoso Proxy Error [502] retornado ao chamador da API.
• Causa possível: Se o argumento path passado para GetJSONString for inválido ou não corresponder a nenhum dado, a função interrompe o fluxo de execução imediatamente e retorna um erro, o que pode fazer com que todo o script seja abortado.
• Resolução:
  • Valide o caminho JSON antes de passá-lo para GetJSONString, ou (na versão do agente 11.59 / 12.3 ou posterior) use GetJSONStringEx, que retorna um valor personalizável em vez de interromper a execução quando o caminho é inválido ou não encontrado.
  • Registre a carga JSON imediatamente antes da chamada GetJSONString para verificar a estrutura real e confirmar o caminho.

Limite de iterações de loop de script excedido

• Sintoma: Um script falha com um erro indicando que o número máximo de iterações de loop foi alcançado. O limite padrão é 50.000 iterações.
• Causas possíveis:
  • Um loop em um script Jitterbit excede o limite de iterações da plataforma.
  • Um script JavaScript contém múltiplos loops cujas contagens de iterações combinadas excedem 50.000. Em JavaScript, o limite se aplica por script (em todos os loops), não por loop individual.
• Resolução:
  • Revise a lógica do script para determinar se o loop pode ser otimizado para reduzir o número de iterações.
  • Para scripts JavaScript em agentes privados, o limite por script pode ser aumentado adicionando JavaScriptMaxIterations=X (onde X é maior que 50000) à seção [Settings] do arquivo de configuração do agente privado.
  • Para Jitterbit Script em agentes privados, aumente o limite definindo jitterbit.scripting.while.max_iterations para um valor maior que 50000.

Comparando uma string com um número gera resultados inesperados

• Sintoma: Uma comparação entre uma string e um número retorna um resultado inesperado. Por exemplo, comparar uma string não numérica com 0 é avaliado como igual, então o ramo errado é executado:

  $value = "test";
  If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
  // registra "equal", mesmo que "test" não seja 0
  

• Causa: Quando os dois operandos são de tipos diferentes, o Jitterbit Script converte ambos em números para compará-los. Uma string que não representa um número é convertida para 0, então "test" == 0 se torna 0 == 0, que é true. Este é um comportamento esperado.

• Resolução: Compare valores do mesmo tipo. Para testar uma string contra um valor específico, compare-a com um literal de string (por exemplo, $value == "0" ou $value == "") em vez de um número. Se um valor pode chegar como qualquer tipo, converta ambos os operandos para o mesmo tipo (por exemplo, com String) antes de comparar.

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

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

• Possíveis causas:

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

• Resolução:

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

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

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

DBExecute: Erro quando auto_commit e transaction estão ambos true

• Sintoma: Uma operação usando DBExecute falha com um erro relacionado a configurações de transação conflitantes.
• Causa possível: Tanto jitterbit.scripting.db.auto_commit quanto jitterbit.scripting.db.transaction estão definidos como true no script antes da chamada DBExecute. Essas duas configurações são mutuamente exclusivas e combiná-las causa um erro.
• Resolução: Decida se você precisa do comportamento de auto-commit ou controle de transação explícito, e então defina apenas a variável apropriada:
  • Para auto-commit (cada instrução é confirmada imediatamente): defina $jitterbit.scripting.db.auto_commit = true e deixe jitterbit.scripting.db.transaction não definido ou false.
  • Para controle de transação (confirmação no final da transformação): defina $jitterbit.scripting.db.transaction = true e jitterbit.scripting.db.auto_commit = false.

CallStoredProcedure: resultSet sempre nulo com drivers ODBC

• Sintoma: Um script usando CallStoredProcedure retorna null para o parâmetro resultSet, mesmo que a stored procedure retorne dados.
• Causa possível: O parâmetro resultSet é suportado apenas por drivers de banco de dados JDBC. Quando o endpoint do Banco de Dados usa um driver ODBC, resultSet é sempre null, independentemente do que a stored procedure retorna.
• Resolução:
  • Se o conjunto de resultados da stored procedure for necessário, mude o endpoint do Banco de Dados para usar um driver JDBC em vez de ODBC.
  • Se a troca de drivers não for possível, recupere os dados de saída por meio de parâmetros de saída em vez do argumento resultSet.

CallStoredProcedure: "Stored proc ou função não pôde ser encontrada" com PostgreSQL JDBC

• Sintoma: Um script usando CallStoredProcedure contra um banco de dados PostgreSQL falha com:

  CallStoredProcedure failed to execute call "<function-name>".
  java.sql.SQLException: Stored proc or function could not be found: <function-name>
  

• Causa possível: O driver JDBC do PostgreSQL distingue entre funções e procedimentos. CallStoredProcedure sempre constrói sua chamada usando um padrão que o driver interpreta como uma busca por um procedimento. Se o objeto do banco de dados for uma função PostgreSQL em vez de um procedimento, o driver não consegue localizá-lo e retorna o erro "não encontrado".

• Resolução:

  1. Determine se o objeto do banco de dados que está sendo chamado é uma função PostgreSQL (retorna um valor) ou um procedimento (sem valor de retorno).
  2. Substitua CallStoredProcedure por DBExecute e use a sintaxe SQL correta para o tipo de objeto:

• Função: use SELECT.

      ```
      $result = DBExecute("<TAG>Sources/My DB Connection</TAG>", "SELECT my_function(arg1, arg2)");
      ```
  
      `DBExecute` retorna um conjunto de resultados. Use um loop `While` com `Get` para ler os valores retornados.
  

• Procedimento: use CALL.

      ```
      DBExecute("<TAG>Sources/My DB Connection</TAG>", "CALL my_procedure(arg1, arg2)");
      ```
  
      Procedimentos do PostgreSQL não retornam um valor; o valor de retorno de `DBExecute` pode ser descartado.
  

DBLoad: Requer um driver de banco de dados JDBC

• Sintoma: Uma operação usando DBLoad falha ou não produz saída quando o endpoint do Banco de Dados usa um driver ODBC.
• Possível causa: DBLoad funciona apenas com endpoints de Banco de Dados configurados para usar um driver JDBC. Não é suportado com drivers ODBC.
• Resolução: Confirme se o endpoint do Banco de Dados associado à atividade de destino usa um driver JDBC. Se usar um driver ODBC, mude para JDBC.

AESDecryption falha com dados criptografados sob OpenSSL 3

• Sintoma: Uma operação usando AESDecryption falha ou retorna saída corrompida ao descriptografar dados que foram criptografados usando OpenSSL 3.
• Possível causa: AESDecryption usa um algoritmo AES legado por padrão que não é compatível com a criptografia OpenSSL 3. Quando os dados criptografados foram produzidos com OpenSSL 3, a descriptografia falha sem configuração adicional.
• Resolução:
  • Para agentes privados versão 11.42 ou posterior, defina jitterbit.scripting.aes.default como true em um passo de script antes da chamada AESDecryption para habilitar a compatibilidade com OpenSSL 3.
  • Alternativamente, substitua AESDecryption por AESDecryptionEx, que suporta OpenSSL 3 por padrão em versões de agente 11.42 ou posteriores.

As variáveis de projeto retornam valores vazios durante testes de script e transformação

• Sintoma: Ao testar um passo de script ou transformação no Studio, uma variável de projeto referenciada no script ou mapeamento retorna um valor vazio em vez do valor configurado. O teste pode falhar com um erro não relacionado à variável em si (por exemplo, um tempo limite de conexão causado por um endereço de servidor em branco).
• Causa possível: Os valores das variáveis de projeto são injetados em tempo de execução pela plataforma Harmony. Durante um teste em tempo de design, o contexto de tempo de execução não está disponível, então as referências de variáveis de projeto retornam strings vazias, independentemente de quaisquer valores configurados.
• Resolução:
  • Defina um valor padrão na variável de projeto: Na configuração da variável de projeto, insira o valor a ser usado durante os testes no campo Valor padrão. Esta é a solução mais simples para um valor configurado estático. Observe que o padrão é usado sempre que a variável não foi definida em tempo de execução (não apenas durante testes em tempo de design), então em tempo de execução também atua como um fallback quando a variável está de outra forma não definida. Veja Variáveis de projeto para detalhes de configuração.
  • Use uma variável global: Substitua a referência da variável de projeto por uma variável global e atribua seu valor dentro do próprio script, antes da linha que a utiliza. Como uma variável global obtém seu valor da execução do script em vez da injeção em tempo de execução, atribuí-la antes do uso a torna disponível durante um teste em tempo de design. Prefira isso quando o valor for derivado em um script ou quando você não quiser um valor de fallback em tempo de execução. Veja Variáveis globais para detalhes. Se a variável global for referenciada em um campo de configuração de conector em vez de diretamente em um script, você também deve definir um valor padrão por campo na pílula da variável (veja Definir um valor padrão).

IsNull retorna falso para strings vazias de dados de origem JSON

• Sintoma: IsNull retorna falso para um campo mapeado de uma fonte JSON, mesmo quando o campo parece não ter valor. A lógica subsequente que depende da verificação nula se comporta de maneira inesperada ou produz resultados incorretos.
• Possível causa: JSON distingue entre um valor null ausente ou explícito e uma string vazia (""). Um campo definido como "" em JSON é uma string vazia, não nula, portanto IsNull retorna corretamente falso para ele. A partir do agente 11.37, o agente preserva essa distinção com precisão. Scripts ou transformações que anteriormente dependiam de IsNull retornar verdadeiro para strings vazias dependiam de um comportamento anterior que não é mais correto.

• Resolução:

  • Use IfEmpty para lidar com nulos e strings vazias: A função IfEmpty retorna um valor padrão quando o argumento é nulo ou uma string vazia, e é a substituição recomendada para este cenário:

    // Retorna "default" se o campo for nulo ou uma string vazia
    result = IfEmpty($myField, "default");
    

  • Use Length para testar strings vazias explicitamente: Se você só precisa verificar se uma string está vazia (não nula), use Length($myField) == 0.

  • Corrija os dados de origem: Se a fonte JSON deve indicar que não há valor, atualize-a para enviar "field": null ou omita o campo completamente em vez de "field": "".

Comparar uma variável de string com o número 0 retorna inesperadamente true

• Sintoma: Uma comparação como $myVar == 0 retorna verdadeiro mesmo quando $myVar contém uma string não numérica (por exemplo, "teste"). Condições If e outras lógicas que verificam se é zero produzem resultados inesperados.
• Possível causa: Quando o Jitterbit Script compara valores de diferentes tipos de dados, ele tenta converter ambos os operandos para doubles como um passo final. Quando aplicado a uma string não numérica, a conversão falha e retorna 0 como valor padrão. A comparação então é avaliada como 0 == 0, que é verdadeiro.

• Resolução:

  • Certifique-se de que ambos os lados da comparação usem o mesmo tipo de dado. Se a intenção é verificar se uma variável de string contém o valor "0", compare com o literal de string "0" em vez do inteiro 0:

    // Compara string com inteiro: strings não numéricas são convertidas para 0 e coincidem inesperadamente
    If($myVar == 0, ...)
    
    // Compara string com string: comporta-se como esperado
    If($myVar == "0", ...)
    

  • Se a variável deve conter um valor numérico, assegure-se de que ela seja atribuída como um número em vez de uma string antes da comparação.

A aritmética decimal produz resultados inesperados em ponto flutuante

• Sintoma: Uma expressão aritmética envolvendo literais decimais produz um resultado que está ligeiramente diferente do valor esperado. Por exemplo, Double(12.01) - Double(12.00) retorna 0.00999999999999979 em vez de 0.01, e (4.9 * 100) - 490 avalia para 5.6843418860808e-14 em vez de 0.
• Possível causa: O Jitterbit Script armazena números como valores de ponto flutuante. A maioria das frações decimais não pode ser representada exatamente em ponto flutuante binário, então a aritmética sobre elas pode acumular pequenos erros de arredondamento. A subtração que cancela a maior parte de um valor expõe esse residual. Fazer a conversão explícita dos valores como Double não previne isso: especifica o tipo de dado, mas não muda como o valor é armazenado ou calculado.

• Resolução:

  • Aplique Round ao resultado: Use Round com o número de casas decimais necessárias para o cálculo:

    $a = Round(Double(12.01) - Double(12.00), 2); // retorna 0.01
    

  • Converta literais decimais usando Float: Envolva o literal decimal em Float antes do cálculo:

    $a = (Float(4.9) * 100) - 490;
    WriteToOperationLog($a);
    

O valor em cache expira mais cedo do que o esperado

• Sintoma: Um valor escrito no cache com uma longa expiração (por exemplo, 24 horas) desaparece muito antes que esse tempo se esgote, ou expira após 30 minutos, independentemente do que foi definido em WriteCache.
• Possível causa: Cada chamada para ReadCache redefine a expiração do item em cache para 30 minutos (1800 segundos), a menos que o parâmetro expirationSeconds seja fornecido explicitamente. A expiração do WriteCache se aplica apenas no momento da gravação; leituras subsequentes sem uma expiração explícita silenciosamente encurtam a vida útil restante.

• Resolução:

  • Especifique a expiração em ReadCache: Passe o número desejado de segundos como o parâmetro expirationSeconds para preservar ou estender a vida útil do valor em cache em cada leitura:

    // Redefine a expiração para 24 horas em cada leitura
    testVal = ReadCache("CacheTest", 86400, "env");
    

  • Passe -1 para preservar a expiração de gravação: Passar um valor não positivo faz com que ReadCache mantenha a expiração definida pela chamada mais recente de WriteCache, em vez de aplicar uma nova:

    testVal = ReadCache("CacheTest", -1, "env");
    

RunXSLT falha com "A versão XML deve ser 1.0 ou 1.1"

• Sintoma: RunXSLT falha com o erro:

  Failed to execute xslt. XML version must be 1.0 or 1.1
  

  mesmo que o arquivo XML de entrada contenha uma declaração válida <?xml version="1.0"?>.

• Causa possível: A folha de estilo XSLT está configurada para produzir saída HTML (por exemplo, <xsl:output method="html"/>). RunXSLT suporta apenas XML como saída. Quando a folha de estilo produz HTML, a função gera um resultado vazio, o que aciona esse erro. A mensagem de erro refere-se à declaração XML ausente na saída (vazia), e não no XML de entrada.

• Resolução:

  • Atualize o XSLT para produzir saída XML: Altere a declaração de saída da folha de estilo para <xsl:output method="xml"/>, ou remova completamente a declaração xsl:output (XML é o padrão). Esta é a abordagem recomendada e funciona em agentes na nuvem e privados.

  • Use o plugin XSL Transform (apenas agentes privados): Para grupos de agentes privados, o plugin XSL Transform obsoleto usa o processador XSLT Saxon e suporta formatos de saída não-XML, incluindo HTML. Veja Plugins disponíveis para detalhes de instalação.

SelectSingleNode retorna o nó errado quando usado com um elemento de array SelectNodes

• Sintoma: SelectSingleNode retorna dados do elemento errado (por exemplo, sempre a primeira correspondência no documento) quando chamado em um elemento recuperado de um array de SelectNodes.
• Possível causa: Usar uma expressão XPath absoluta (uma que começa com //) como argumento de caminho faz com que SelectSingleNode busque a partir da raiz do documento XML original, em vez de ser relativo ao nó atual. Uma expressão como "//Item/ItemName" corresponde ao primeiro ItemName em qualquer lugar do documento, independentemente de qual elemento Item foi recuperado do array.

• Resolução:

  • Use um caminho relativo: Omitir o // inicial e especificar apenas o nome do elemento ou um caminho relativo ao nó atual. Isso limita a busca ao nó passado como primeiro argumento:

    $itemName = SelectSingleNode($item, "ItemName");
    

  • Alternativa: envolva o nó em String: Converter o elemento do array em uma string antes de passá-lo para SelectSingleNode também produz o resultado correto, embora usar um caminho relativo seja a abordagem preferida:

    $item = String($items[2]);
    $itemName = SelectSingleNode($item, "//Item/ItemName");
    

HexToBinary a saída parece inalterada quando registrada

• Sintoma: HexToBinary parece não ter efeito: o valor escrito no log da operação parece idêntico à entrada em hexadecimal, sugerindo que a conversão não ocorreu.
• Possível causa: WriteToOperationLog não pode output dados binários brutos. Quando passado um valor binário, ele o converte de volta para hexadecimal para exibição. O mesmo comportamento se aplica na janela de teste de script. A conversão está funcionando corretamente; apenas a exibição é afetada.

• Resolução: Para trabalhar ou verificar a saída binária, escreva-a em um arquivo usando WriteFile. Por exemplo:

  WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/Write</TAG>", HexToBinary("1A3F"));
  

SortArray ordena nomes de arquivos lexicograficamente, não cronologicamente

• Sintoma: SortArray retorna nomes de arquivos em ordem alfabética em vez da ordem cronológica esperada quando os nomes de arquivos contêm strings de data ou hora incorporadas.
• Causa possível: SortArray realiza uma ordenação de string (lexicográfica). Para um nome de arquivo como ordall_DDMMYYHHMMSS.txt, a parte do dia precede a parte do ano na string, portanto, uma ordenação alfabética não corresponde a uma ordenação baseada em data.
• Resolução:
  • Se você controla a convenção de nomenclatura dos arquivos, mude para um formato que ordene corretamente quando ordenado alfabeticamente, como YYYY-MM-DD_HHMMSS_filename.txt. Esta é a correção mais simples e confiável.
  • Se o formato do nome do arquivo não puder ser alterado, analise a parte da data de cada nome de arquivo em uma chave ordenável (por exemplo, YYYYMMDDHHMMSS) e ordene com base na chave analisada em vez do nome do arquivo bruto.

URLEncode não codifica certos caracteres "seguros" ou multibyte

• Sintoma: Um valor passado através de URLEncode é enviado ao destino com alguns caracteres não codificados, fazendo com que o sistema receptor rejeite a solicitação ou interprete mal o valor. Isso afeta comumente credenciais ou valores de consulta que contêm caracteres como $, + ou !.
• Causas possíveis:
  • URLEncode segue RFC 1738 e trata esses caracteres como "seguros", portanto, nunca os codifica: $ - _ . + ! * ' ( ) ,. Um destino que espera que esses caracteres sejam codificados em porcentagem recebe o caractere bruto em vez disso.
  • O suporte a caracteres multibyte em URLEncode requer a versão do agente 12.4 ou posterior. Em agentes anteriores, caracteres multibyte podem não ser codificados como esperado.

• Resolução:

  • Quando caracteres "seguros" devem ser codificados (por exemplo, em uma senha OAuth ou um valor que contém +), use a função JavaScript encodeURIComponent em um passo de script JavaScript em vez de URLEncode:

    <javascript>
    $my_username = "$Example+User";
    $loginValue = encodeURIComponent($my_username);
    </javascript>
    

    Isso retorna %24Example%2BUser.

  • Para codificar caracteres multibyte com URLEncode, confirme que o agente está na versão 12.4 ou posterior.

JavaScript: erro "Chamada para Jitterbit Tomcat falhou"

• Sintoma: Um passo JavaScript complexo ou de longa duração falha com um erro genérico referenciando Tomcat, mesmo que os serviços Jitterbit Apache e Jitterbit Tomcat no agente estejam em execução. O script pode ter sucesso quando sua complexidade é reduzida (por exemplo, diminuindo contagens de iteração ou profundidade de recursão).

  Call to Jitterbit Tomcat failed (null response). Make sure the Jitterbit Apache and Jitterbit Tomcat services are both running.
  Failed to execute script
  

• Causa possível: JavaScript recursivo profundamente pode exceder o limite de profundidade de recursão do mecanismo JavaScript do agente, produzindo um estouro de pilha que se manifesta como este erro genérico do Tomcat. Este limite de recursão é intencional. O script normalmente é concluído uma vez que a profundidade de recursão é reduzida.

• Resolução:
  • Reduza a profundidade de recursão ou reescreva a lógica recursiva como um loop iterativo.
  • Se o algoritmo não puder evitar a recursão profunda, use uma abordagem que não dependa dela.
  • Observe que o limite de iteração de loop por script separado (JavaScriptMaxIterations, veja Limite de iteração de loop de script excedido) não aumenta o teto de recursão, que não é exposto como uma configuração ajustável.

JavaScript: alterações em variáveis globais perdidas em falha de script

• Sintoma: Um script JavaScript que modifica variáveis globais é executado sem erro aparente em alguns casos, mas as alterações nessas variáveis globais estão ausentes em scripts ou operações subsequentes.
• Causas possíveis:
  • Em JavaScript, as alterações em variáveis globais são apenas confirmadas quando o script é concluído com sucesso. Se o script falhar em algum ponto, todas as alterações nas variáveis globais feitas durante essa execução são descartadas.
  • Misturar a sintaxe $variable com Jitterbit.SetVar/Jitterbit.GetVar para a mesma variável dentro de um script JavaScript pode causar comportamento de tempo de execução imprevisível.
• Resolução:
  • Estruture os scripts JavaScript para que todas as atribuições de variáveis globais ocorram após a lógica que pode falhar, ou use tratamento de erros para evitar falhas no meio do script.
  • Para qualquer variável em um script JavaScript, use a sintaxe $variable ou Jitterbit.SetVar/Jitterbit.GetVar, nunca ambas. Escolha uma e use-a de forma consistente ao longo do script.
  • Para confirmar quais variáveis estão sendo definidas, adicione chamadas WriteToOperationLog para registrar os valores das variáveis em pontos-chave durante a execução.

JavaScript: GetVar retorna nulo para variáveis de projeto definidas pelo usuário

• Sintoma: Chamar Jitterbit.GetVar em uma variável de projeto definida pelo usuário em um passo de script JavaScript retorna null em vez do valor da variável, sem mensagem de erro.
• Causa possível: Jitterbit.GetVar e Jitterbit.SetVar são destinados a variáveis de sistema Jitterbit (por exemplo, jitterbit.operation.name) e para nomes de variáveis que contêm um ponto, que a notação de ponto do JavaScript não pode referenciar diretamente. Eles não leem variáveis de projeto definidas pelo usuário cujos nomes não contêm um ponto; passar um nome assim para GetVar retorna null. Referencie essas variáveis diretamente com $name em vez disso.

• Resolução: Use a sintaxe $variableName diretamente em JavaScript para acessar variáveis de projeto e globais definidas pelo usuário cujos nomes não contêm um ponto. Reserve GetVar e SetVar para variáveis de sistema Jitterbit e para variáveis cujos nomes contêm um ponto (por exemplo, $hello.world), que a notação de ponto do JavaScript não pode acessar diretamente.

  // Correct: access a user-defined project variable directly
  var value = $myProjectVar;
  
  // Incorrect for user-defined variables without periods:
  var value = Jitterbit.GetVar("$myProjectVar"); // returns null
  

• Notas adicionais:

  • GetVar e SetVar convertem valores em strings, tornando-os inadequados para arrays ou objetos.
  • SetVar seguido por GetVar dentro do mesmo script pode recuperar o valor definido anteriormente nesse script, mesmo para variáveis sem pontos, mas o valor não persiste em outros scripts.
  • Para uma variável dada, use ou o prefixo $ ou GetVar/SetVar, não ambos. Veja também JavaScript: Mudanças em variáveis globais perdidas em falhas de script.

Erros de HTTP e API

504 Gateway Timeout

• Sintoma: Chamadas de API através da nuvem ou do gateway de API privado retornam 504 Gateway Timeout, tipicamente após o período de timeout do gateway (30 a 180 segundos).
• Causa e resolução: A operação de suporte está excedendo o timeout do gateway de API, ou a solicitação não pode ser atribuída a um agente disponível. Veja HTTP 504 Gateway Timeout no guia de solução de problemas do API Manager para as causas e resolução completas.

507 Insufficient Storage

• Sintoma: Uma chamada de API retorna:

  507 Insufficient Storage
  

• Possíveis causas:

  • O agente ou host do gateway está sem espaço em disco.
  • Em um gateway de API privado, o gateway não consegue abrir seu arquivo de carga útil ou resposta hospedado e retorna um 507 mesmo quando há espaço em disco suficiente disponível. Isso geralmente indica um problema de registro de domínio privado ou configuração do gateway.

• Resolução:

  • Confirme que o agente ou host do gateway tem espaço livre em disco suficiente.
  • Se o espaço em disco for suficiente e a API for servida através de um gateway de API privado, veja Gateway privado retorna HTTP 507 ou "No such file or directory" para a causa e resolução.

502 Bad Gateway

• Sintoma: Uma operação que utiliza Jitterbit Message Queue (JBMQ) falha com:

  502 Bad Gateway
  

  O servidor retornou uma resposta inválida ou incompleta.

• Possível causa: O serviço JBMQ não retornou uma resposta completa à solicitação, produzindo um 502. Este erro é tipicamente transitório e pode não ser reproduzível.

• Resolução:
  1. Tente a operação novamente.
  2. Se o erro persistir, entre em contato com suporte Jitterbit.

Erros em tempo de design

Esses problemas aparecem enquanto se constrói, valida ou implanta um projeto no Studio, em vez de quando uma operação é executada.

Erros comuns de validação de operação

Operações com erros de validação exibem um ícone inválido no canvas de design e no painel do projeto. Clique no ícone para ver a mensagem de erro específica.

A tabela a seguir lista erros comuns de validação e suas resoluções:

Erros de regra de validação HTTP

Uma das regras de validação HTTP se aplica a operações que utilizam o padrão de arquivo de dois alvos, onde uma atividade HTTP na posição Alvo 1 escreve uma resposta para uma segunda atividade alvo (Alvo 2). Nesse cenário, a regra de validação exige que uma atividade HTTP Alvo 1 não deve ser utilizada em nenhuma outra operação do padrão de arquivo de dois alvos onde a atividade HTTP Alvo 1 escreve para uma atividade alvo secundária diferente.

Operações que violam essa regra de validação aparecem como inválidas com uma mensagem de erro semelhante ao seguinte exemplo:

Resolver erros de validação HTTP

Siga as instruções na mensagem de erro para corrigir as operações para que sejam válidas. Para resolver esses erros, complete os seguintes passos:

1. Duplicar a atividade alvo HTTP na posição Alvo 1 de uma das operações que utiliza o padrão de arquivo HTTP de dois alvos.

2. Substitua a atividade de destino HTTP na posição Target 1 das operações identificadas pela cópia duplicada.

3. Repita para quaisquer operações inválidas adicionais. Após resolver os erros de validação, reimplante as operações.

Desativar a regra de validação HTTP

Em certas situações, pode ser necessário desativar esta regra de validação HTTP. Para desativar a regra, complete os seguintes passos:

1. Abra as configurações do projeto:

   

2. Na aba Implantar, desative Regra de Validação HTTP:

   

3. Clique em Salvar.

Após desativar e salvar a configuração, os erros de validação da operação dessa regra devem ser resolvidos. No entanto, quaisquer atividades de Target 1 HTTP usadas em uma operação de padrão de arquivo de dois alvos gravam na atividade Target 2 da última operação implantada. Esse comportamento pode causar a gravação de dados inválidos.

Reativar a regra de validação HTTP

Se você desativou anteriormente a regra de validação HTTP e deseja reativá-la, complete os seguintes passos:

1. Abra as configurações do projeto.

2. Na aba Implantar, ative Regra de Validação HTTP.

3. Clique em Salvar. Essa alteração é uma mudança em tempo de design e não implanta nenhuma alteração na nuvem Harmony.

4. Resolva quaisquer erros de validação HTTP (veja Resolver erros de validação HTTP).

5. Reimplante o projeto (veja Implantação de projeto).

   Nota

   Antes da reimplantação, o Harmony permite a execução de quaisquer operações agora inválidas porque o Harmony executa as operações atualmente implantadas. A reimplantação das operações afetadas é necessária para que as alterações se propaguem para o Harmony.

Nomes de componentes devem ser únicos após a importação do projeto

• Sintoma: Após importar um projeto de um arquivo de exportação JSON, um ou mais componentes aparecem como inválidos e a implantação falha com uma mensagem semelhante a:

  [Operation / Connection / Activity / Transformation / Script / Tool / Email / Variable] names must be unique.
  

• Causa possível: O projeto importado contém múltiplos componentes do mesmo tipo com nomes idênticos. O Studio impede a criação de nomes duplicados ao configurar componentes diretamente na interface do usuário, mas uma importação de projeto completa não aplica essa verificação.

• Resolução:
  1. No painel do projeto, identifique os componentes inválidos, mostrados em itálico vermelho com um ícone de erro.
  2. Clique no ícone de erro para visualizar o nome duplicado específico que está causando o conflito.
  3. Renomeie um dos componentes duplicados para que cada nome seja único dentro de seu tipo.
  4. Reimplante o projeto após resolver todos os erros de nomes duplicados.
  5. Para trazer apenas componentes selecionados para um projeto existente, use importação seletiva, que sinaliza conflitos com componentes de mesmo nome já no projeto de destino e permite que você os substitua ou mantenha ambos.

Blocos de conector apenas para agente privado importados para um ambiente de agente em nuvem

• Sintoma: A importação ou migração de um projeto para um ambiente associado a um grupo de agentes em nuvem é bloqueada porque o projeto utiliza um conector apenas para agente privado. A mensagem lista os conectores apenas para agente privado responsáveis. Uma importação de projeto completa exibe:

  The project you are importing uses private agent only connectors and cannot be imported into a cloud environment.
  

  Uma importação seletiva exibe um diálogo de Importação de componente não permitida:

  The components you are importing uses private agent only connectors and cannot be imported into a cloud environment.
  

• Causa possível: O projeto utiliza um ou mais conectores que estão disponíveis apenas em agentes privados. A coluna Disponibilidade do agente na lista de conectores mostra quais conectores são apenas para agente privado. Agentes em nuvem não suportam esses conectores, portanto, o Studio impede que o projeto seja importado ou migrado para um ambiente de agente em nuvem.

• Resolução:
  • Importe ou migre o projeto para um ambiente associado a um grupo de agentes privados que tenha o conector necessário instalado.
  • Se o projeto precisar ser executado em agentes em nuvem, substitua as atividades de conectores apenas para agente privado por conectores compatíveis com a nuvem (como HTTP v2 para APIs REST, ou o conector de Banco de Dados com um endpoint acessível na nuvem) antes de importar.

O upload de um arquivo de esquema substitui-o em todo o projeto

• Sintoma: Após fazer o upload de um novo arquivo de esquema durante a configuração da transformação, outras transformações no projeto que usavam o mesmo esquema agora se comportam de maneira inesperada ou produzem erros.
• Possível causa: Quando você faz o upload de um arquivo com o mesmo nome de um arquivo de esquema existente já definido no projeto, o Studio exibe um diálogo Substituir arquivo?. Se você clicar em Continuar, o arquivo existente é substituído em todos os locais onde é utilizado. Essa substituição é em todo o projeto, não restrita à transformação atual.
• Resolução:
  1. Antes de fazer o upload de um arquivo de esquema substituto, confirme se o esquema existente é compartilhado: abra o esquema para edição e, se ele for referenciado por mais de um componente, o Studio exibirá um diálogo Esquema usado por múltiplos componentes listando-os (veja Atualizar esquemas definidos pela transformação). Avalie o impacto em todos os componentes listados antes de prosseguir.
  2. Se apenas uma transformação deve usar o esquema atualizado, clique em Cancelar no diálogo Substituir arquivo? (ou renomeie o novo arquivo antes de fazer o upload) para que ele não sobrescreva o arquivo compartilhado.

Falha na implantação do template de processo do Marketplace devido a incompatibilidade de esquema

• Sintoma: Um projeto importado de um template de processo do Marketplace falha ao implantar ou produz erros em tempo de execução porque campos estão faltando de uma transformação ou a validação da atividade de origem e destino falha.
• Possível causa: Templates de processo são desenvolvidos contra uma instância de endpoint específica. Se sua instância for diferente (por exemplo, se sua organização Salesforce ou NetSuite tiver campos personalizados ou padrão diferentes), os esquemas incorporados nas transformações do template podem não corresponder ao seu endpoint.
• Resolução:
  1. Na transformação afetada, abra as configurações do esquema e clique no ícone de atualizar (ou na palavra Atualizar) para regenerar o esquema a partir do seu endpoint conectado.
  2. Se o esquema ainda não corresponder após a atualização, limpe o esquema existente e reespelhe-o a partir de um arquivo de amostra atual ou diretamente do endpoint.
  3. Remapeie quaisquer campos que foram adicionados ou removidos durante a regeneração do esquema.
  4. Reimplante o projeto e execute a operação novamente para confirmar que o problema foi resolvido.

O Studio fica lento ou não responde com projetos muito grandes

• Sintoma: O Studio responde lentamente quando um único fluxo de trabalho contém um número muito grande de operações ou ao salvar um script muito grande.
• Causa possível: O canvas de design renderiza todas as operações no fluxo de trabalho ativo de uma vez, portanto, um fluxo de trabalho com um número muito grande de operações exige muita memória do navegador.
• Resolução:
  • Divida fluxos de trabalho grandes em sub-fluxos de trabalho menores e interligados. O Studio renderiza apenas o canvas do fluxo de trabalho ativo, então menos operações por fluxo de trabalho melhoram a responsividade. Use ações de operação para encadear sub-fluxos de trabalho.
  • Se a lentidão ocorrer especificamente ao salvar um script grande, divida o script em scripts menores e chame-os usando RunScript.

Erros de sistema e recursos

Chunking não respeitado quando a fonte é um conector baseado em SDK

• Sintoma: Uma operação com chunking habilitado envia todos os registros para o destino em um único lote, em vez de respeitar o tamanho de lote configurado. Erros do destino indicam que o limite de lote foi excedido (por exemplo, o Salesforce retorna EXCEEDED_ID_LIMIT: limite de registro atingido. não é possível enviar mais de 200 registros nesta chamada).
• Causa possível: O chunking não é suportado quando a fonte é um conector baseado em SDK (conforme listado na coluna Tipo de Conector da lista de Conectores). Operações que usam fontes não-SDK, como HTTP, Banco de Dados, Variável e Armazenamento Local respeitam o chunking normalmente.
• Resolução:
  • Se o chunking não for necessário, desative-o nas opções da operação.
  • Se o chunking for necessário, divida a operação em duas:
    • Na primeira operação, leia da fonte baseada em SDK e escreva em uma atividade de Escrita de Variável.
    • Na segunda operação, leia de uma atividade de Leitura de Variável e escreva no destino original com o chunking habilitado. Como o conector de Variável não é baseado em SDK, o chunking funciona corretamente nesta operação. Para os passos de configuração do chunking, veja Configurar chunking da operação.

Atualizações de variáveis perdidas em operações multi-threaded com chunking

• Sintoma: Quando uma operação é executada com chunking habilitado e Número Máximo de Threads definido para mais de 1, as atualizações de variáveis globais ou de projeto feitas durante a operação não são totalmente preservadas após a conclusão. Um caso possível é a população de um dicionário ou variável de array a partir de cada registro de origem e descobrir que ele contém apenas parte dos dados depois (por exemplo, aproximadamente metade dos registros quando duas threads são executadas). Isso pode ocorrer com conectores cuja configuração padrão utiliza mais de uma thread, como as atividades do Salesforce, que têm como padrão 2 threads.
• Causa possível: Cada thread recebe sua própria cópia das variáveis globais e de projeto no início do processamento. As alterações locais da thread não são mescladas de volta ao estado compartilhado. Apenas as alterações feitas pela primeira thread são preservadas quando a operação é concluída; as alterações de todas as outras threads são descartadas.
• Resolução:
  • Se a correção for mais importante do que a taxa de transferência por operação, defina Número Máximo de Threads como 1. Cada chunk será processado sequencialmente, portanto, as atualizações de variáveis não serão divididas entre as threads.
  • Se a taxa de transferência multi-threaded for necessária, não acumule o estado por registro em uma variável global ou de projeto. Em vez disso, armazene a saída de cada thread em um arquivo de Armazenamento Temporário exclusivo ou em uma tabela de banco de dados de staging, e depois consolide os resultados em uma operação subsequente de thread única. Para um exemplo prático do padrão de staging, veja Escopo de variáveis com chunking.
  • De maneira mais geral, não confie em atualizações de variáveis globais ou de projeto de operações chunked e multi-threaded em scripts ou operações posteriores. Se o estado da variável precisar ser preservado, defina essas variáveis em um passo de operação não chunked que seja executado antes ou depois da transformação chunked. Para detalhes sobre o comportamento do chunking com variáveis, veja Use variáveis com chunking.

Falha ao criar diretório temporário

• Sintoma: Uma operação falha ao criar um diretório temporário, com um erro como:

  Failed to create the directory '/tmp/jitterbit/...'. Reason: boost::filesystem::create_directories: Permission denied
  

  Em um grupo de agentes na nuvem, pode relatar Sem espaço restante no dispositivo.

• Causas possíveis:

  • Em um agente privado, a conta de serviço do Jitterbit Agent não possui permissões em nível de SO no caminho dos arquivos temporários, ou o disco está cheio.
  • Em um grupo de agentes na nuvem, a causa está do lado do agente gerenciado pelo Jitterbit, e não no seu projeto ou configuração.

• Resolução:

  • Para agentes privados, confirme se a conta de serviço do agente possui permissões suficientes no caminho dos arquivos temporários (/tmp ou TemporaryFiles), e verifique se o host do agente tem espaço livre em disco adequado.
  • Para grupos de agentes na nuvem, isso indica um problema do lado do agente que o Jitterbit resolve. Entre em contato com suporte do Jitterbit e inclua a mensagem de erro e o horário em que as falhas ocorreram.

Mensagens de log da operação truncadas em aproximadamente 100 KB

• Sintoma: Uma mensagem de log da operação aparece cortada, terminando com mensagem truncada. Isso pode aparecer nos logs da operação ou ao visualizar uma entrada de log de Operação na página de Logs da API do API Manager.
• Causa possível: Mensagens de log da operação que excedem aproximadamente 100 KB (aproximadamente 99.000 caracteres) são truncadas. O ponto de truncamento é marcado com mensagem truncada no final da mensagem.
• Resolução: Se você precisar do conteúdo completo do log, reduza a verbosidade do log da operação ou divida a operação em unidades menores que produzam mensagens de log mais curtas.

O registro de depuração de operações expõe PII e credenciais em texto claro

• Sintoma: Dados sensíveis, credenciais ou informações pessoalmente identificáveis (PII) aparecem nos logs da nuvem Harmony.
• Causa possível: Quando o registro de depuração de operações está ativado para uma operação, todos os dados de solicitação e resposta são armazenados na nuvem Harmony em texto claro por 30 dias.
• Resolução:
  • Use o registro de depuração de operações apenas em ambientes controlados, não produtivos ou por um período diagnóstico limitado.
  • Para desativar a geração de dados de entrada e saída de componentes para um grupo de agentes privados, defina verbose.logging.enable=false na seção [VerboseLogging] do arquivo de configuração do agente.