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

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

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

• Erros HTTP e API

  • 504 Gateway Timeout
  • 507 Insufficient Storage
  • 502 Bad Gateway

• Erros de tempo de design

  • Erros comuns de validação de operação
  • Erros de regra de validação HTTP
  • Nomes de componentes devem ser exclusivos após importação de projeto
  • Blocos de conector somente para agente privado importam para um ambiente de agente em nuvem
  • Fazer upload de um arquivo de esquema o substitui em todo o projeto
  • Falha na implantação do modelo de processo do Marketplace devido a incompatibilidade de esquema
  • O Studio fica lento ou sem resposta com projetos muito grandes

• Erros de sistema e recursos

  • Chunking requer um conector nativo como fonte
  • Atualizações de variáveis perdidas em operações multi-thread em chunks
  • Falha ao criar diretório temporário
  • Mensagens de log de operação truncadas em aproximadamente 100 KB
  • Logging de debug de operação expõe PII e credenciais em texto simples

Etapas de diagnóstico

Estas etapas 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 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 Desabilitar Atualização Automática de Conector esteja habilitada).

Verificar 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 de log adicionais estão disponíveis:

• Ativar logging de debug de operação (para agentes em nuvem ou para agentes privados).
• Ativar logging detalhado de conector (somente agentes privados).
• Verificar os logs do agente (somente agentes privados).

Isolar falhas específicas do agente

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

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

Execução e agendamento de operação

Operações travadas em estado Enviado ou Em execução

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

  Long running operation canceled by System
  

  O cancelamento pode ocorrer depois que a operação é executada por um tempo ou logo após ser iniciada, e não reflete necessariamente por quanto tempo a operação realmente foi executada.

• Possíveis causas:

  • Um agente privado perdeu sua conexão com a plataforma Harmony e não conseguiu relatar o status da operação. A plataforma continua mostrando a operação como Em execução 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 o Harmony, portanto continua aparecendo como Em execução até atingir o tempo limite.
  • O grupo de agentes está sob carga pesada e é lento para aceitar ou atualizar operações enfileiradas.
  • A operação está travada especificamente em Enviado: a mensagem de execução foi enfileirada, mas nenhum agente do grupo a aceitou, porque os agentes estão offline, não saudáveis ou sem capacidade livre para aceitar novas operações (por exemplo, cada thread de trabalho está ocupada).

• Resolução:

  • Para agentes privados, confirme que o agente possui status Running na página Agents no Console de Gerenciamento, analise os logs do agente privado para identificar problemas de conexão e verifique se a conexão de rede entre o agente e a plataforma Harmony está estável.
  • Analise 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 por pouco tempo, portanto não indica necessariamente uma operação genuinamente de longa duração. Os logs também podem revelar um erro específico a ser resolvido, como 401 Unauthorized (verifique as credenciais) ou 429 Too Many Requests. Um 429 de um endpoint de destino pode ser mitigado reduzindo a taxa de requisições ou adicionando lógica de repetição; um 429 do gateway de API em nuvem gerenciado pelo 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 posteriores de agentes melhoram a resiliência do agente e reduzem o cancelamento prematuro de operações.
  • Tente cancelar as operações afetadas. O cancelamento está disponível para operações nos status Submitted, Received, Pending ou Running a partir da página Runtime do Console de Gerenciamento, da tabela de logs de operação ou do status de execução de uma operação na tela de design.
  • Se a operação afetada é executada em um agendamento e nunca é iniciada, consulte Operações agendadas não estão sendo executadas.
  • Se as operações não puderem ser canceladas, se o problema recorrer ou se muitas operações forem afetadas simultaneamente, entre em contato com o suporte do Jitterbit, pois esses casos podem exigir resolução do lado do servidor.

Operações agendadas não estão sendo executadas

• Sintoma: Uma operação configurada com um agendamento de operação não é executada no horário programado ou é despachada mas permanece em um estado Pending ou Received.
• Possíveis causas:
  • O agendamento foi atribuído à operação no Studio, mas o projeto não foi implantado. Agendamentos atribuídos no Studio não têm efeito até que o projeto seja implantado.
  • O agendamento está desabilitado.
  • Existe uma configuração incorreta de fuso horário nas configurações de agendamento.
  • Para agentes privados, o serviço de agendamento não está em execução.
  • O agente associado ao ambiente está offline ou não está saudável.
  • As alterações implantadas em um projeto não foram totalmente sincronizadas com o agente.
  • O grupo de agentes está com recursos saturados. 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 selecione operações agendadas a tempo.
• Resolução:
  • Confirme que o projeto foi implantado desde que o agendamento foi atribuído à operação.
  • Confirme que o agendamento está habilitado. Agendamentos podem ser habilitados ou desabilitados apenas a partir da página Projects do Console de Gerenciamento, tanto na aba Operations quanto na aba Schedules.
  • Analise a configuração de agendamento, prestando atenção particular à configuração de fuso horário. Para obter detalhes, consulte Fusos horários de operação.
  • Para agentes privados, verifique se o agente está online e saudável na página Agents no Console de Gerenciamento e confirme se o serviço de agendamento está em execução na máquina do agente. No Windows, verifique se Jitterbit Scheduler e Jitterbit Scheduler Service estão em execução no Gerenciador de Tarefas. No Linux e Docker, use o comando jitterbit status.
  • Implante novamente o projeto para forçar a ressincronização do agendamento com o agente.
  • Se operações estão presas em um estado Pending, cancele-as através da página Runtime do Console de Gerenciamento e reinicie o serviço do agente.
  • Se as ausências de agendamento se correlacionam com a carga, reduza o número de operações de longa duração simultâneas. Em agentes privados, também analise o uso de CPU e memória e equilibre operações agendadas em relação à capacidade do agente (um agente privado pode executar até o dobro de suas contagens de núcleos de CPU em operações simultâneas).
  • Se uma operação agendada é despachada mas depois fica travada em vez de nunca iniciar, consulte Operações presas em estado Submitted ou Running.

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

• Sintoma: Um dicionário ou variável global preenchido dentro de uma operação filha fica vazio ou mantém seu valor anterior quando a operação pai lê após invocar a filha de forma assíncrona.
• Possível causa: Quando uma operação é invocada de forma assíncrona (a ferramenta Invoke Operation com Run type definido como Asynchronously, ou RunOperation chamado com runSynchronously definido como false), a operação filha é executada em uma thread separada e a operação pai continua sem aguardar. Variáveis globais e dicionários são passados à filha por valor em vez de por referência e não são thread-safe, portanto as alterações feitas na filha não se refletem na pai. A pai também pode ler o valor antes da filha terminar. Para comportamento equivalente em operações multi-thread em chunks, consulte Atualizações de variáveis perdidas em operações multi-thread em chunks.
• Resolução:
  • Se a operação pai depende dos valores que a filha produz, invoque a filha de forma síncrona (a ferramenta Invoke Operation com Run type definido como Synchronously, ou RunOperation executada de forma síncrona, que é o padrão) para que a filha seja concluída e suas alterações de variáveis globais sejam herdadas pela pai.
  • Para compartilhar dados entre operações que devem ser executadas independentemente, 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 foi concluída; execute a operação de forma síncrona em vez disso.

Falhas de conexão e autenticação

Certificado Salesforce: incompatibilidade de Subject Alternative Name (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 PostgreSQL interno do agente privado (TranDb), por exemplo Failed to connect to back-end database 'TranDb' ou FATAL: query_wait_timeout.
• Causa e resolução: Trata-se de um problema no nível do agente com as conexões do banco de dados interno do agente privado. Consulte Falhas de conexão TranDb no guia de troubleshooting do agente para as causas e resolução.

Falha ao carregar certificado do cliente em agentes privados Linux

• Sintoma: Uma operação que faz uma chamada de serviço web mutual-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 é enviado para o Studio com sucesso, mas a operação falha quando é executada. A mesma configuração pode ter funcionado anteriormente em um agente privado Windows.

• Possíveis causas:

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

• Resolução:

  • Garanta que a conta que executa o agente Jitterbit tenha acesso de leitura ao arquivo de chave privada e a todos os diretórios pais.
  • Verifique se SELinux ou AppArmor está restringindo o acesso ao arquivo de chave e ajuste a política ou 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 caracteres (CDATA) não são suportadas em XML incorporado em JSON passado por uma transformação. Quando presentes, o seguinte erro aparece no log da operação:

  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 ...
  

• Resolução: Use um script Jitterbit para Replace os caracteres &, <, >, ' e " dentro da seção CDATA, incluindo os delimitadores CDATA (<![CDATA[ ... ]]>), com seus equivalentes escapados (&, <, >, ', "). Se não for viável atingir apenas a seção CDATA, é possível substituir toda a string XML que a contém.

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

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

Falha na transformação 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 de HTTP v2 com Get response content in base64 string ativado: a codificação Base64 aumenta o conteúdo binário (como um arquivo de áudio ou mídia), então a string codificada pode exceder o limite mesmo quando o arquivo original é menor.

• Causa: O analisador 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 de qualquer atividade posterior (como um upload) ser 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 reinicie o agente. Esta chave está disponível na versão 12.5 do agente e posterior, então atualize o agente primeiro se 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, qualquer caractere especial em um nome de campo ou nó de esquema é substituído por um underscore (_). Ao usar processamento JSON legado (o padrão para projetos criados antes da versão Harmony 11.48), isso pode fazer com que o endpoint retorne erros porque os nomes de campo reais não correspondem mais ao que ele espera.

  Por exemplo, se a atividade fornecer um campo denominado location_ids[], será convertido para location_ids__. Se o endpoint ainda esperar o nome original, poderá retornar um erro como:

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

• Resolução:

  1. Confirme se 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 Preserve JSON names (requer versão do agente 11.48 ou posterior).

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

  Importante

  Quando Preserve JSON names é ativado em um projeto onde estava desativado anteriormente, o novo método de processamento se aplica apenas a operações e esquemas configurados após a ativação da configuração. As 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 ativar essa configuração.

  Para verificar o nome do campo sendo enviado ao endpoint, verifique o valor jsonPropertyName nos dados de entrada ou saída da atividade com debug logging ativado:

  

Caracteres multibyte corrompidos em uma resposta grande do conector

• Sintoma: Um caractere multibyte em uma resposta JSON do conector fica corrompido. O texto corrompido apresenta o padrão clássico de bytes UTF-8 decodificados como Latin-1 (por exemplo, São Luís retornado como São LuÃs). Normalmente, apenas um caractere multibyte que aparece após aproximadamente os primeiros 8 KB da resposta é afetado; o mesmo caractere aparecendo mais cedo na resposta não é afetado.
• Causa possível: Nas versões 12.8 e 12.9 do agente, a detecção automática de codificação de caracteres amostra apenas o início da resposta para determinar sua codificação. Se essa amostra contiver apenas caracteres ASCII, a resposta é detectada como Latin-1 (ISO-8859-1) em vez de UTF-8, corrompendo qualquer caractere multibyte que apareça além da porção amostrada.
• Resolução: Atualize para a versão 12.10 do agente ou posterior, que corrige a detecção de codificação.

Esquemas espelhados com grupos de substituição

• Sintoma: Esquemas espelhados que usam grupos de substituição XML não são suportados. Usá-los 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 outras razões, como importar um mapeamento de transformação com nós duplicados, e não necessariamente indica um problema de grupo de substituição.

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

A importação de um mapeamento de transformação com nós duplicados falha com "node cannot be created"

• 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, mas a operação falha quando executada.

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

• Solução: Na transformação afetada, use Remover todos os mapeamentos abaixo deste nó no nó raiz para remover todos os mapeamentos e depois importe o arquivo de mapeamento novamente. A reimportação sincroniza novamente 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 e 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 Harmony 10.25 e 10.27, projetos criados antes de 10.25 que usam esquemas XML espelhados podem se comportar de forma diferente do esperado. Mapeamentos que usaram funções XML envolvendo namespaces (como SelectNodes) podem agora ser inválidos.

  A diferença está no tratamento de prefixos 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.

• Solução: A partir da versão 10.27, a importação de um projeto cujos esquemas XML espelhados foram criados antes de 10.25 retém o prefixo de namespace original, portanto o esquema é idêntico ao quando foi criado. Para forçar uma atualização para o prefixo de namespace atual, regenere o esquema atualizando-o ou reconfigurando a atividade que o fornece. Após regenerar, revise todas as chamadas de função de namespace XML afetadas e atualize as referências de prefixo de acordo.

  Consulte a comparação de esquema XML anotado para uma ilustração da diferença entre os dois formatos.

Aviso de subelemento extra nos logs de operação

• Sintoma: Uma mensagem de extra subelement nos logs de operação é um aviso, não um erro, e geralmente pode ser ignorada. Isso 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 de resposta.
• Solução: Se você precisar capturar os dados adicionais, atualize o esquema para incluir os campos extras.

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

• Sintoma: Um campo de destino com tipo de dados 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 coage o resultado para o tipo de dados do campo de destino. Se o valor da string começar com um caractere não numérico (por exemplo, "string1"), nenhuma porção numérica pode ser extraída e o campo recebe o valor numérico padrão de 0. Por outro lado, um valor como "1string" produziria 1, já que o dígito inicial é mantido.
• Solução:
  1. Verifique a definição do esquema para o campo de destino afetado e confirme se seu tipo de dados é double ou outro tipo de dados 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 dados do campo no esquema.

Campos mapeados em branco com esquemas de fonte simples

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

• Resolução:

  1. Adicione uma etapa de script no início da operação que desabilite transformações com streaming ao configurar jitterbit.transformation.auto_streaming como false:

     $jitterbit.transformation.auto_streaming = false;
     

  2. Implante e execute novamente a operação. Para mais contexto sobre streaming e processamento de transformação, consulte 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 na implantação 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 fazem referência a 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 adicionais de origem em uma etapa 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, consulte Validade de mapeamento de transformação.

Transformação remove registros duplicados quando a saída é hierárquica

• Sintoma: Uma transformação que lê uma origem CSV e mapeia para um formato de saída hierárquico (como JSON) remove silenciosamente registros duplicados. Registros com valores de campo idênticos aparecem apenas uma vez na saída, independentemente de quantas vezes ocorrem na origem. 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 origem simples 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.
  • Este comportamento é específico para saída hierárquica. Quando o esquema de saída é simples, 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 no início ou no final se tornam idênticos após o corte e estão sujeitos à mesma deduplicação.
• Resolução:
  • Habilite o chunking nas opções de operação. O chunking processa registros em lotes, o que ignora a normalização e preserva todos os registros, incluindo duplicados.
  • Use um esquema de saída simples na transformação em vez de um hierárquico. A normalização não se aplica à saída simples, portanto, todos os registros são preservados.
  • Desabilite a normalização ao configurar uma variável Jitterbit em uma etapa de script anterior à transformação. Para transformações simples-para-simples, configure jitterbit.transformation.disable_normalization como true. Para transformações simples-para-XML, configure 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 com cuidado.
  • Se os duplicados forem causados especificamente por diferenças de espaçamento, configure jitterbit.source.preserve_char_whitespace como true em uma etapa de script anterior à transformação. Isto preserva o espaçamento durante a análise para que registros afetados permaneçam distintos.

IDs numéricos longos sã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 um valor incorreto. O número é muito grande para caber no tipo numérico implícito usado durante o mapeamento, causando um estouro que produz um valor incorreto no destino.
• Possível causa: O campo de origem ou destino é implicitamente digitado como um tipo de dado numérico cujo intervalo não consegue conter o valor completo, causando um estouro 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 digitado 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 remove campos cujo valor é null ou uma string vazia ("") da carga útil de saída, mesmo que esses campos sejam mapeados explicitamente. O sistema de destino recebe uma carga útil que não inclui os campos omitidos, o que pode causar erros de validação quando o destino exige que os campos estejam presentes.
• Possível causa: O processador de saída JSON omite campos com valores null ou string vazia por padrão.
• Resolução:
  • Em uma etapa de script anterior à transformação, defina jitterbit.target.xml.include_nil_attribute como true. Na versão do agent 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, crie o corpo JSON em uma etapa de script usando concatenação de strings e envie-o através de um conector HTTP v2 com um corpo de requisição sem esquema.

Campos mapeados vazios se tornam xsi:nil="true" e invalidam uma requisiçã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 requisição. Por exemplo, um mapeamento vazio de número de telefone 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 null 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 uma etapa de script anterior à transformação, defina $jitterbit.target.xml.include_null_xml = false para remover nós com valor null ou vazio da saída completamente. Se o nó deve estar presente como um elemento vazio, use as variáveis Jitterbit de destino relacionadas jitterbit.target.xml.include_empty_xml e jitterbit.target.xml.include_nil_attribute, que controlam se valores vazios e null são incluídos na saída.

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

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

Erros de script e função

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

• Sintoma: uma operação é concluída com status de êxito, 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.
• Possível causa: ArchiveFile e ReadFile têm comportamento de falha suave: se uma dessas funções falhar, o script atual é interrompido e um aviso é adicionado ao log da operação, mas a operação em si não falha e as etapas subsequentes continuam. A partir da versão do agente 12.5, 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 deletado, em vez de falhar silenciosamente.
• Resolução:
  • verifique os logs da operação para mensagens de aviso quando uma operação é bem-sucedida, mas a saída de arquivo esperada está ausente.
  • se o script deve parar em caso de falha de uma 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 que usa ReadFile para ler um arquivo binário (como um ZIP ou PDF) retorna dados incompletos ou corrompidos.
• Possível causa: ReadFile não é confiável com conteúdo de arquivo binário e normalmente lê apenas uma parte desses arquivos.
• Resolução: use Base64EncodeFile em vez de ReadFile para ler o conteúdo completo de um arquivo binário como uma string codificada em Base64.

Conteúdo de ReadFile com bytes não UTF-8 falha quando mapeado em uma carga útil XML ou JSON UTF-8

• Sintoma: Uma transformação que mapeia o conteúdo bruto de um arquivo lido com ReadFile (por exemplo, um arquivo EDI bruto) para um campo de destino XML ou JSON com codificação 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 ofensivo 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 ativado lança:

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

• Causa: O conteúdo do arquivo contém um byte que não é UTF-8 válido (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 multibyte de um caractere Unicode de aparência similar (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: Procure e substitua o byte bruto com suporte Unicode hex desativado, para que HexToString funcione 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 informado por StringToHex($readFile) e a string de substituição (~) conforme necessário, depois 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) lançam um erro se um arquivo com o nome de destino já existe no local de destino.
• Resolução:
  • Adicione uma chamada 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 timestamp ou identificador exclusivo 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 lança um erro em vez de retornar silenciosamente. Isso pode causar falhas inesperadas de operação quando o arquivo a ser deletado não existe.
• Resolução: Envolva a chamada DeleteFiles em uma função Eval para capturar o erro e tratá-lo sem prejudicar 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 uma matriz está vazia). 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 Proxy Error [502] enganoso retornado ao chamador da API.
• Possível causa: 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 o script inteiro seja abortado.
• Resolução:
  • Valide o caminho JSON antes de passá-lo para GetJSONString, ou (em versões do agent 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 o payload JSON imediatamente antes da chamada GetJSONString para verificar a estrutura real e confirmar o caminho.

Limite de iteração de loop do script excedido

• Sintoma: Um script falha com um erro indicando que o número máximo de iterações de loop foi atingido. O limite padrão é 50.000 iterações.
• Possíveis causas:
  • 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ção 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 agents 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 agent privado.
  • Para Jitterbit Script em agents privados, aumente o limite definindo jitterbit.scripting.while.max_iterations para um valor maior que 50000.

RunOperation interrompe a execução após 50 chamadas síncronas em um loop While

• Sintoma: Após atualizar um agent privado para a versão 12.11 ou posterior, um script que chama RunOperation, RunOperationFromProject ou ReRunOperation de forma síncrona dentro de um loop While processa menos registros do que o esperado. Nenhum erro no nível da operação ocorre, a menos que o script verifique o valor retornado da função ou chame GetLastError. O log da operação mostra uma entrada identificando a operação invocada pelo nome (voltando para o GUID se o nome não puder ser resolvido) quando o limite foi atingido, e GetLastError retorna essa mesma informação de identificação.

• Possível causa: A partir da versão 12.11 do agent, um limite no nível do agent (MaxSynchronousRunOperationCallsInLoop na seção [OperationEngine] do arquivo jitterbit.conf, padrão de 50) limita o número de chamadas síncronas de RunOperation, RunOperationFromProject e ReRunOperation feitas dentro de um único loop While; todos os três compartilham uma contagem cumulativa por loop. Após o limite ser atingido, cada chamada subsequente retorna false sem gerar um erro, portanto um loop que não verifica o valor retornado continua iterando sem perceber que as chamadas posteriores não fizeram nada.

• Resolução:

  • Se o loop não verificar o valor retornado, encapsule a chamada para que um limite excedido apareça como um erro de script, por exemplo: If(!RunOperation("<TAG>operation:MyOp</TAG>"), RaiseError(GetLastError()));.
  • Para aumentar o limite de uma operação específica, defina a variável Jitterbit jitterbit.operation.max_sync_runop_calls_in_loop antes de o loop ser executado, desde que as substituições por operação sejam permitidas (MaxSynchronousRunOperationCallsInLoopOverrideAllowed).
  • Para aumentar o padrão em todo o agente, incremente MaxSynchronousRunOperationCallsInLoop na seção [OperationEngine] do arquivo jitterbit.conf.

Comparar 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 branch errado é executado:

  $value = "test";
  If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
  // logs "equal", even though "test" is not 0
  

• Causa: Quando os dois operandos têm tipos diferentes, o Jitterbit Script converte ambos para 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 é o 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 de 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 é desmapaido. Para um destino JSON ou XML, o campo aparece na saída com um valor null em vez de ser omitido.

• Possíveis causas:

  • RunScript precede Unmap na mesma expressão de mapeamento (por exemplo, RunScript("<TAG>script:MyScript</TAG>"); Unmap();). Em versões de agente anteriores à 12.9, essa combinação não desmapaiva 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 desmapeamento para o mapeamento, então chamar Unmap de dentro do script chamado não tem efeito, em qualquer versão de agente, independentemente de qualquer lógica condicional em torno da chamada. Este é o comportamento esperado.

• Resolução:

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

  • Se Unmap é chamado de dentro do script invocado por RunScript, mova a chamada de Unmap para fora do script chamado e para dentro da 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 são ambos true

• Sintoma: Uma operação usando DBExecute falha com um erro relacionado a configurações de transação conflitantes.
• Possível causa: Tanto jitterbit.scripting.db.auto_commit quanto jitterbit.scripting.db.transaction estão definidas como true no script antes da chamada de DBExecute. Essas duas configurações são mutuamente exclusivas e combiná-las causa um erro.
• Resolução: Decida se você precisa de comportamento de auto-commit ou controle explícito de transação, depois 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 definida ou false.
  • Para controle de transação (confirmação ao 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 o procedimento armazenado retorne dados.
• Possível causa: O parâmetro resultSet é compatível apenas com drivers de banco de dados JDBC. Quando o endpoint de banco de dados usa um driver ODBC, resultSet é sempre null independentemente do que o procedimento armazenado retorna.
• Resolução:
  • Se o conjunto de resultados do procedimento armazenado for necessário, alterne o endpoint de banco de dados para usar um driver JDBC em vez de ODBC.
  • Se não for possível alternar drivers, recupere dados de saída por meio de parâmetros de saída em vez do argumento resultSet.

CallStoredProcedure: "Stored proc or function could not be found" com PostgreSQL JDBC

• Sintoma: Um script usando CallStoredProcedure em 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>
  

• Possível causa: O driver JDBC do PostgreSQL diferencia 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 "not found".

• Resolução:
  1. Determine se o objeto do banco de dados 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 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 de 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 é compatível com drivers ODBC.
• Resolução: Confirme que o endpoint de banco de dados associado à atividade de destino usa um driver JDBC. Se usar um driver ODBC, alterne para JDBC.

AESDecryption falha com dados criptografados no 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 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 uma etapa de script a montante da chamada AESDecryption para habilitar compatibilidade com OpenSSL 3.
  • Como alternativa, substitua AESDecryption por AESDecryptionEx, que oferece suporte a OpenSSL 3 por padrão em versões de agente 11.42 ou posterior.

Variáveis do projeto retornam valores vazios durante testes de script e transformação

• Sintoma: Ao testar uma etapa de script ou transformação no Studio, uma variável do 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).
• Possível causa: Os valores das variáveis do projeto são injetados em tempo de execução pela plataforma Harmony. Durante um teste em tempo de design, não existe contexto de tempo de execução para injetar esse valor, portanto, uma referência de variável de projeto retorna um valor vazio, a menos que a variável tenha um Valor padrão configurado para usar como fallback. A resolução de conexão própria de uma função é um caso separado que não usa o Valor padrão de forma alguma; consulte Uma função falha quando seu campo de conexão de endpoint é definido como uma variável.
• Resolução:
  • Defina um valor padrão na variável do projeto: Na configuração da variável do projeto, insira o valor a ser usado durante o teste no campo Valor padrão. Esta é a correçã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), portanto, em tempo de execução também atua como um fallback quando a variável está indefinida. Consulte Variáveis do projeto para detalhes de configuração.
  • Use uma variável global: Substitua a referência da variável do 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 de injeção em tempo de execução, atribuir um valor 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 não quiser um valor de fallback em tempo de execução. Consulte Variáveis globais para detalhes. Se a variável global for referenciada em um campo de configuração do conector em vez de diretamente em um script, você também deve definir um valor padrão por campo para esse campo (consulte Definir um valor padrão, que aborda tanto o método de variável em píldula quanto o método de sintaxe inline para campos que não mostram uma píldula).

Uma função falha quando seu campo de conexão de endpoint é definido como uma variável

• Sintoma: Testar um script (usando Executar teste) que chama uma função como DBLookup, DBExecute ou SfLookup falha, por exemplo com:

  No suitable driver found for [...]
  

  ou um erro indicando um espaço reservado de variável não resolvido no endereço do endpoint. O mesmo script é executado com sucesso quando implantado e executado em uma operação.

• Possível causa: A conexão usada pela função tem um campo (como Login, Senha, String de Conexão ou um endereço de servidor) definido como uma variável global ou do projeto. Testar um script executa apenas o script testado, portanto, a variável não recebeu seu valor em tempo de execução quando a função resolve a conexão. Diferentemente de uma variável referenciada em um campo configurado próprio de uma atividade, isso não é coberto pelo Valor padrão de uma variável; uma função como essas não lê o valor padrão ao resolver uma conexão. Para uma variável referenciada diretamente em um script ou mapeamento, onde um Valor padrão resolve o problema, consulte Variáveis do projeto retornam valores vazios durante testes de script e transformação.

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

IsNull retorna false para strings vazias de dados de origem JSON

• Sintoma: IsNull retorna false para um campo mapeado de uma origem JSON, mesmo quando o campo parece não ter valor. A lógica downstream que depende da verificação de nulidade se comporta inesperadamente ou produz resultados incorretos.
• Causa possível: 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, então IsNull corretamente retorna false para ele. A partir do agent 11.37, o agent preserva essa distinção com precisão. Scripts ou transformações que anteriormente dependiam de IsNull retornar true para strings vazias dependiam do comportamento anterior que não é mais correto.

• Resolução:

  • Use IfEmpty para tratar null 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 é nulo ou uma string vazia
    result = IfEmpty($myField, "default");
    

  • Use Length para testar strings vazias explicitamente: Se for necessário apenas verificar se uma string está vazia (não nula), use Length($myField) == 0.

  • Corrija os dados de origem: Se a origem JSON deveria indicar nenhum valor, atualize-a para enviar "field": null ou omita o campo inteiramente em vez de "field": "".

Comparar uma variável string ao número 0 retorna true inesperadamente

• Sintoma: Uma comparação como $myVar == 0 retorna true mesmo quando $myVar contém uma string não numérica (por exemplo, "test"). Condições If e outras lógicas que verificam zero produzem resultados inesperados.
• Causa possível: Quando o Jitterbit Script compara valores de tipos de dados diferentes, tenta converter ambos os operandos em doubles como etapa 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, o que é true.

• Resolução:

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

    // Compares string to integer: non-numeric strings coerce to 0 and match unexpectedly
    If($myVar == 0, ...)
    
    // Compares string to string: behaves as expected
    If($myVar == "0", ...)
    

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

Aritmética decimal produz resultados de ponto flutuante inesperados

• Sintoma: Uma expressão aritmética envolvendo literais decimais produz um resultado 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.
• Causa possível: 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 nelas pode acumular pequenos erros de arredondamento. A subtração que cancela a maioria de um valor expõe esse resíduo. Converter explicitamente valores como Double não impede isso: especifica o tipo de dados 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ário para o cálculo:

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

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

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

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

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

Valor em cache expira mais cedo do que o esperado

• Sintoma: Um valor escrito no cache com uma expiração longa (por exemplo, 24 horas) desaparece bem antes desse tempo decorrer, ou expira após 30 minutos independentemente do que foi definido em WriteCache.
• Causa possível: Cada chamada a 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 escrita; leituras subsequentes sem uma expiração explícita encurtam silenciosamente 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:

    // Resets expiration to 24 hours on each read
    testVal = ReadCache("CacheTest", 86400, "env");
    

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

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

RunXSLT falha com "XML version must be 1.0 or 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 <?xml version="1.0"?> válida.

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

• Resolução:

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

  • Use o plugin XSL Transform (somente agentes privados): Para grupos de agentes privados, o plugin XSL Transform descontinuado usa o processador Saxon XSLT e oferece suporte a formatos de saída não XML, incluindo HTML. Consulte Plugins disponíveis para detalhes de instalação.

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

• Sintoma: SelectSingleNode retorna dados do elemento incorreto (por exemplo, sempre a primeira correspondência no documento) quando chamado em um elemento recuperado de um array SelectNodes.
• Causa possível: O uso de uma expressão XPath absoluta (que começa com //) como argumento de caminho faz com que SelectSingleNode pesquise a partir da raiz do documento XML original em vez de 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: Omita o // inicial e especifique apenas o nome do elemento ou um caminho relativo ao nó atual. Isso limita a pesquisa ao nó passado como primeiro argumento:

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

  • Alternativa: envolver o nó em String: Converter o elemento do array para 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");
    

A saída de HexToBinary parece inalterada quando registrada

• Sintoma: HexToBinary parece não ter efeito: o valor escrito no log de operações se parece idêntico à entrada hexadecimal, sugerindo que a conversão não ocorreu.
• Causa possível: WriteToOperationLog não consegue fazer a saída de dados binários brutos. Quando recebe um valor binário, 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 com 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 arquivo lexicograficamente, não cronologicamente

• Sintoma: SortArray retorna nomes de arquivo em ordem alfabética em vez da ordem cronológica esperada quando os nomes de arquivo 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ê controlar a convenção de nomenclatura de arquivo, mude para um formato que seja ordenado corretamente quando classificado alfabeticamente, como YYYY-MM-DD_HHMMSS_filename.txt. Essa é a correção mais simples e confiável.
  • Se o formato do nome de arquivo não puder ser alterado, analise a porção de data de cada nome de arquivo em uma chave ordenável (por exemplo, YYYYMMDDHHMMSS) e ordene contra a chave analisada em vez do nome de arquivo bruto.

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

• Sintoma: Um valor transmitido por meio de URLEncode é enviado para o destino com alguns caracteres não codificados, causando a rejeição da solicitação pelo sistema receptor ou interpretação incorreta do valor. Isso afeta comumente credenciais ou valores de consulta que contêm caracteres como $, + ou !.
• Possíveis causas:
  • URLEncode segue a RFC 1738 e trata esses caracteres como "seguros", portanto nunca os codifica: $ - _ . + ! * ' ( ) ,. Um destino que espera que esses caracteres sejam codificados em percentual recebe o caractere bruto em vez disso.
  • O suporte a caracteres multibyte em URLEncode exige 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 em um valor que contém +), use a função JavaScript encodeURIComponent em uma etapa 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 "Call to Jitterbit Tomcat failed"

• Sintoma: Uma etapa de JavaScript complexa ou de longa execuçã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 ser bem-sucedido quando sua complexidade é reduzida (por exemplo, reduzindo contadores 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
  

• Possível causa: JavaScript profundamente recursivo pode exceder o limite de profundidade de recursão do mecanismo JavaScript do agente, produzindo um estouro de pilha que aparece como esse erro genérico do Tomcat. Esse limite de recursão é intencional. O script normalmente é concluído após a redução da profundidade de recursão.

• Resolução:
  • Reduza a profundidade de recursão ou reescreva a lógica recursiva como um loop iterativo.
  • Se o algoritmo não conseguir evitar recursão profunda, use uma abordagem que não dependa disso.
  • Observe que o limite de iteração de loop por script separado (JavaScriptMaxIterations, consulte 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 configurável.

JavaScript: Alterações de variáveis globais perdidas em caso de falha do 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.
• Possíveis causas:
  • Em JavaScript, as alterações em variáveis globais são confirmadas apenas quando o script é concluído com sucesso. Se o script falhar em qualquer ponto, todas as alterações de variável global feitas durante essa execução serã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 impredizível.
• Resolução:
  • Estruture 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 em todo o script.
  • Para confirmar quais variáveis estão sendo definidas, adicione chamadas WriteToOperationLog para registrar valores de variáveis em pontos-chave durante a execução.

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

• Sintoma: Chamar Jitterbit.GetVar em uma variável de projeto definida pelo usuário em uma etapa de script JavaScript retorna null em vez do valor da variável, sem mensagem de erro.
• Possível causa: Jitterbit.GetVar e Jitterbit.SetVar se destinam a variáveis de sistema Jitterbit (por exemplo, jitterbit.operation.name) e a nomes de variáveis que contêm um ponto, que a notação de ponto do JavaScript não consegue referenciar diretamente. Elas não leem variáveis de projeto ordinárias definidas pelo usuário cujos nomes não contêm ponto; passar tal nome para GetVar retorna null. Referencie essas variáveis diretamente com $name. Essas funções também convertem todos os valores em strings, então não são adequadas para arrays ou objetos, e um valor definido com SetVar pode ser lido novamente com GetVar dentro do mesmo script, mas não persiste para scripts posteriores.

• 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 ponto. Reserve GetVar e SetVar para variáveis de sistema Jitterbit e para variáveis cujos nomes contêm ponto (por exemplo, $hello.world), que a notação de ponto do JavaScript não consegue acessar diretamente. Para uma determinada variável, use ou $-prefixação ou GetVar/SetVar, não ambos. Consulte também JavaScript: alterações de variável global perdidas em caso de falha de script.

  // 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
  

Erros HTTP e API

504 Gateway Timeout

• Sintoma: Chamadas de API através do gateway de API na nuvem ou privado retornam 504 Gateway Timeout, normalmente após a janela 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 consegue ser atribuída a um agente disponível. Consulte HTTP 504 Gateway Timeout no guia de resolução de problemas do API Manager para ver as causas e resoluções completas.

507 Insufficient Storage

• Sintoma: Uma chamada de API retorna:

  507 Insufficient Storage
  

• Possíveis causas:

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

• Resolução:

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

502 Bad Gateway

• Sintoma: Uma operação que usa 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. Esse erro é geralmente 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 o suporte Jitterbit.

Erros em tempo de design

Esses problemas aparecem ao construir, validar ou implantar 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 na tela de design e no painel do projeto. Clique no ícone para visualizar a mensagem de erro específica.

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

Erros de regra de validação HTTP

Uma das regras de validação HTTP se aplica a operações que usam o padrão de arquivo de dois destinos em que uma atividade HTTP na posição Destino 1 escreve uma resposta em uma segunda atividade de destino (Destino 2). Nesse cenário, a regra de validação exige que uma atividade HTTP Destino 1 não seja usada em nenhuma outra operação do padrão de arquivo de dois destinos em que a atividade HTTP Destino 1 escreva em uma segunda atividade de destino diferente.

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

Resolver erros de validação HTTP

Siga as instruções na mensagem de erro para corrigir as operações a fim de torná-las válidas. Para resolver esses erros, conclua as seguintes etapas:

1. Duplique a atividade de destino HTTP na posição Destino 1 de uma das operações que usa o padrão de arquivo HTTP de dois destinos.

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

3. Repita para qualquer operação inválida adicional. Após resolver os erros de validação, reimplante as operações.

Desabilitar a regra de validação HTTP

Em certas situações, convém desabilitar essa regra de validação HTTP. Para desabilitar a regra, conclua as seguintes etapas:

1. Abra as configurações do projeto:

   

2. Na aba Deploy, desabilite HTTP Validation Rule:

   

3. Clique em Save.

Após desabilitar e salvar a configuração, os erros de validação de operação dessa regra devem ser resolvidos. No entanto, qualquer atividade HTTP Destino 1 usada em uma operação do padrão de arquivo de dois destinos escreve na atividade Destino 2 da última operação implantada. Esse comportamento pode fazer com que dados inválidos sejam escritos.

Reabilitar a regra de validação HTTP

Se você tiver desabilitado anteriormente a regra de validação HTTP e quiser reabilitá-la, conclua as seguintes etapas:

1. Abra as configurações do projeto.

2. Na aba Deploy, habilite HTTP Validation Rule.

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

4. Resolver erros de validação HTTP (consulte Resolver erros de validação HTTP).

5. Reimplantar o projeto (consulte Implantação de projeto).

   Nota

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

Os nomes dos componentes devem ser exclusivos após a importação do projeto

• Sintoma: Após importar um projeto de um arquivo de exportação JSON, um ou mais componentes são exibidos 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.
  

• Possível causa: O projeto importado contém vários componentes do mesmo tipo com nomes idênticos. O Studio impede a criação de nomes duplicados ao configurar componentes diretamente na interface, 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, exibidos em itálico vermelho com um ícone de erro .
  2. Clique no ícone de erro para visualizar o nome duplicado específico causando o conflito.
  3. Renomeie um dos componentes duplicados para que cada nome seja exclusivo dentro de seu tipo.
  4. Reimplante o projeto após resolver todos os erros de nome duplicado.
  5. Para trazer apenas componentes selecionados para um projeto existente, use importação seletiva, que identifica conflitos com componentes de mesmo nome já no projeto de destino e permite substituí-los ou manter ambos.

Conector exclusivo de agente privado bloqueia importação 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 usa um conector exclusivo de agente privado. A mensagem lista os conectores exclusivos de 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 Component import not allowed:

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

• Possível causa: O projeto usa um ou mais conectores disponíveis apenas em agentes privados. A coluna Agent availability na lista de Conectores mostra quais conectores são exclusivos de agente privado. Agentes em nuvem não suportam esses conectores, então 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 conector exclusivas de agente privado por conectores compatíveis com nuvem (como HTTP v2 para APIs REST ou o conector de Banco de Dados com um endpoint acessível pela nuvem) antes de importar.

Fazer upload de um arquivo de schema o substitui em todo o projeto

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

A implantação do template de processo do Marketplace falha devido à incompatibilidade de schema

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

O Studio fica lento ou sem resposta 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.
• Possível causa: A tela 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 coloca altas demandas de memória no navegador.
• Resolução:
  • Divida fluxos de trabalho grandes em sub-fluxos menores e vinculados. O Studio renderiza apenas a tela do fluxo de trabalho ativo, portanto menos operações por fluxo de trabalho melhora 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 requer um conector nativo como fonte

• Sintoma: Uma operação com chunking ativado envia todos os registros para o destino em um único lote, em vez de respeitar o tamanho de chunk configurado. Erros do destino indicam que o limite de lote foi excedido (por exemplo, Salesforce retorna EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call).
• Possível causa: O chunking é respeitado apenas quando a fonte é um conector nativo. Operações que usam fontes nativas como HTTP, Database, Variable e Local Storage respeitam o chunking normalmente.
• Resolução:
  • Se o chunking não for necessário, desative-o nas opções de operação.
  • Se o chunking for necessário, divida a operação em duas:
    • Na primeira operação, leia da fonte original e escreva em uma atividade Variable Write.
    • Na segunda operação, leia de uma atividade Variable Read e escreva no destino original com chunking ativado. Como o conector Variable é nativo, o chunking funciona corretamente nesta operação. Para as etapas de configuração do chunking, consulte Configure operation chunking.

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

• Sintoma: Quando uma operação é executada com chunking ativado e Max Number of Threads definido como 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 sua conclusão. Um caso possível é popular uma variável de dicionário ou array a partir de cada registro de origem e descobrir que ela contém apenas parte dos dados depois (por exemplo, aproximadamente metade dos registros quando dois threads são executados). Isso pode ocorrer com conectores cuja configuração padrão usa mais de um thread, como atividades Salesforce, que usam como padrão 2 threads.
• Possível causa: Cada thread recebe sua própria cópia das variáveis globais e de projeto no início do processamento. As alterações locais do thread não são mescladas de volta ao estado compartilhado. Apenas as alterações feitas pelo primeiro thread são preservadas quando a operação é concluída; as alterações de todos os outros threads são descartadas.
• Resolução:
  • Se a correção for mais importante que o throughput por operação, defina Max Number of Threads como 1. Cada chunk é então processado sequencialmente, então as atualizações de variáveis não são divididas entre threads.
  • Se for necessário throughput multi-thread, não acumule estado por registro em uma variável global ou de projeto. Em vez disso, armazene a saída de cada thread em um arquivo Temporary Storage exclusivo ou em uma tabela de banco de dados de staging, e depois consolide os resultados em uma operação subsequente com um único thread. Para um exemplo prático do padrão de staging, consulte Variable scoping with chunking.
  • De modo geral, não confie em atualizações de variáveis globais ou de projeto de operações com chunking e multi-thread em scripts ou operações posteriores. Se o estado da variável deve ser preservado, defina essas variáveis em uma etapa de operação sem chunking que é executada antes ou depois da transformação com chunking. Para detalhes sobre o comportamento do chunking com variáveis, consulte Use variables with 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 ser informado No space left on device.

• Possíveis causas:

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

• Resolução:

  • Para agentes privados, confirme que 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 possui espaço em disco adequado.
  • Para grupos de agentes na nuvem, isto indica um problema no lado do agente que a Jitterbit resolve. Entre em contato com o suporte Jitterbit e inclua a mensagem de erro e a hora em que as falhas ocorreram.

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

• Sintoma: Uma mensagem de log de operação aparece cortada, terminando com message truncated. Isto pode aparecer nos logs de operação ou ao visualizar uma entrada de log de Operação na página API Logs do API Manager.
• Possível causa: Mensagens de log de operação que excedem aproximadamente 100 KB (aproximadamente 99.000 caracteres) são truncadas. O ponto de truncamento é marcado com message truncated no final da mensagem.
• Resolução: Se 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 log de depuração de operação expõe PII e credenciais em texto simples

• Sintoma: Dados sensíveis, credenciais ou informações de identificação pessoal (PII) aparecem nos logs na nuvem Harmony.
• Possível causa: Quando o log de depuração de operação é ativado para uma operação, todos os dados de solicitação e resposta são armazenados na nuvem Harmony em texto simples por 30 dias.
• Resolução:
  • Use o log de depuração de operação apenas em ambientes controlados fora de produção ou por um período de diagnóstico limitado.
  • Para desabilitar a geração de dados de entrada e saída de componentes para um grupo de agentes privado, defina verbose.logging.enable=false na seção [VerboseLogging] do arquivo de configuração do agente.